Skip to content

feat: add support for ethrex execution client - #549

Open
ilitteri wants to merge 1 commit into
NethermindEth:developfrom
lambdaclass:feat/ethrex-client
Open

feat: add support for ethrex execution client#549
ilitteri wants to merge 1 commit into
NethermindEth:developfrom
lambdaclass:feat/ethrex-client

Conversation

@ilitteri

@ilitteri ilitteri commented Jul 20, 2026

Copy link
Copy Markdown

Motivation

ethrex is an Ethereum execution client written in Rust, focused on simplicity and auditability. It runs on Ethereum mainnet in production, passed an external security audit by Least Authority, and runs the EF execution-spec-tests and cross-client Hive suites in CI. Adding it to Sedge gives node operators one more execution-layer option and improves client diversity, following the same integration pattern as the existing clients.

This PR was discussed with the Nethermind team beforehand, who suggested opening it.

Description

Adds ethrex as a selectable execution client on mainnet, sepolia, and hoodi (the networks ethrex currently supports — no gnosis/chiado, so no templates are added there and Sedge won't offer it on those networks).

Follows the checklist in docs/docs/guidelines/new-clients.mdx:

  • Client registry: ethrex added to AllClients["execution"], ClientImages struct, setExecutionImage, and configs/client_images.yaml pinned to ghcr.io/lambdaclass/ethrex:21.0.0 (multi-arch amd64+arm64). Note: ethrex docker tags carry no leading v (release CI strips it), while its GitHub release tags do — scripts/check-image-updates.sh therefore uses ltrimstr("v").
  • Templates: templates/services/merge/execution/ethrex.tmpl (compose service) + env fragments for mainnet/sepolia/hoodi. Flags verified against the ethrex CLI: --http.addr/--authrpc.addr bound to 0.0.0.0 for docker, JWT via --authrpc.jwtsecret, single P2P port for both --p2p.port and --discovery.port, Prometheus metrics on the standard Sedge metrics port, --bootnodes passthrough, ElExtraFlags supported. No CORS flag is passed (ethrex has none; its CORS is permissive by default).
  • Help text: execution-client enumerations in cli/sub_gen.go updated (and mirrored in docs/docs/commands/generate.mdx).
  • Docs: README client tables, clients.mdx sample output, networks/{mainnet,sepolia,hoodi}.mdx.
  • Tests: clients_test.go execution lists, an ethrex case in TestSetImageOrDefault_Execution, and an ethrex branch in checkECBootnodesOnExecution so the generate-matrix asserts its bootnodes flag. The compose-generation test matrix picks ethrex up automatically for the three networks.
  • CHANGELOG: entry under Unreleased.

How to test

make test-no-e2e
./sedge clients                          # ethrex listed for mainnet/hoodi/sepolia only
./sedge generate full-node --network sepolia -c lighthouse -e ethrex --no-validator -p $PWD
docker compose config                    # valid compose; image ghcr.io/lambdaclass/ethrex:21.0.0

Validation already run on this branch:

  • make test-no-e2e — passing (the only failures are the pre-existing live-RPC Lido tests, which fail identically on clean develop)
  • sedge clients — ethrex on mainnet/hoodi/sepolia; absent on gnosis/chiado/custom
  • sedge generate full-node --network sepolia -c lighthouse -e ethrex — compose + .env render correctly, docker compose config clean
  • Docker smoke test (hoodi): generated stack brought up; ethrex 21.0.0 (arm64) started with zero flag errors and ran with 0 restarts; HTTP-RPC on 8545, auth-RPC on the Sedge-assigned port, discv4+discv5 up; engine_exchangeCapabilities answered through the generated JWT (full capability list) and eth_chainId returned 0x88bb0 (hoodi), proving the JWT mount and --network env plumbing end to end
  • cd docs && npm run build — Docusaurus build passing

Note from the smoke test, unrelated to this PR: Lighthouse v8 checkpoint sync failed against three public hoodi checkpointz instances ("Error fetching finalized blobs: 500 not found") before ever dialing the EL — the same failure occurs with any execution client.

Possible follow-ups (out of scope)

  • custom network support via ethrex's --network <genesis.json> (custom currently offers only nethermind).
  • WebSocket port wiring (--ws.enabled); omitted to match the other non-geth EL templates.

Add ethrex (https://github.com/lambdaclass/ethrex), a Rust Ethereum
execution client, as a selectable execution client on mainnet, sepolia
and hoodi (the networks ethrex currently supports; no gnosis/chiado
templates, so it is not offered there).

Follows the new-clients guideline: client registry entries, docker
compose service template, per-network env templates, image pinned to
ghcr.io/lambdaclass/ethrex:21.0.0, check-image-updates.sh block
(ethrex GitHub tags carry a leading v but its docker tags do not,
hence ltrimstr), docs (README, clients/generate command pages, network
pages), CLI help strings, tests (client lists, default-image case,
bootnodes assertion), and CHANGELOG entry.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant