feat: embed ethrex as the beacon node's execution client (include-ethrex)

.github/PULL_REQUEST_TEMPLATE.md

@@ -23,4 +23,4 @@
 
 - [ ] Ran `make fmt` — clean
 - [ ] Ran `make lint` (clippy with `-D warnings`) — clean
-- [ ] Ran `make test` (`test-consensus` plus `test-node`, at `release-fast`) — all passing
+- [ ] Ran `make test` (`test-consensus`, `test-node` and `test-ethrex`, at `release-fast`) — all passing

.github/workflows/ci.yml

@@ -65,6 +65,34 @@ jobs:
       - name: Clippy (skipped spectests)
         run: cargo clippy --locked --workspace --test forkchoice_spectests --test signature_spectests --test stf_spectests --test ssz_spectests -- -D warnings
 
+      # The binary's `include-ethrex` code (the `--ethrex.*` flags, the
+      # embedded client's startup and shutdown) is cfg'd out of every pass
+      # above.
+      - name: Clippy (include-ethrex)
+        run: cargo clippy --locked --workspace --all-targets --features ethlambda/include-ethrex -- -D warnings
+
+  # The embedded execution client, in a job of its own: `make test-ethrex`
+  # says why it is kept out of both halves of `test`. No leanSpec fixtures:
+  # its integration tests run ethrex against a checked-in dev genesis.
+  ethrex:
+    name: Test (include-ethrex)
+    runs-on: ${{ vars.ETHLAMBDA_RUNNER || 'ubuntu-latest' }}
+    steps:
+      - uses: actions/checkout@v6.1.0
+
+      - uses: $/.github/actions/free-disk
+
+      - name: Setup Rust
+        uses: dtolnay/rust-toolchain@master
+        with:
+          toolchain: "1.97.1"
+
+      - name: Setup cache
+        uses: Swatinem/rust-cache@v2.9.3
+
+      - name: Run tests
+        run: make test-ethrex
+
   # Two features gate code that no step in `lint` reaches, so both would rot
   # silently between merges.
   #

CLAUDE.md

@@ -10,7 +10,7 @@ Ethereum Beacon Chain (AKA Eth2), and `ethlambda node` runs Lean consensus.
 **Rust version:** 1.97.1 (edition 2024)
 **Test fixtures release:** Download latest production fixtures from leanSpec releases
 
-## Codebase Structure (13 workspace crates)
+## Codebase Structure (14 workspace crates)
 
 ```
 bin/ethlambda/              # Entry point, CLI, orchestration
@@ -44,8 +44,11 @@ crates/
     ├─ ssz-tree/            # Persistent Merkle tree (List/Vector) behind the beacon registry and balances
     ├─ metrics/             # Prometheus re-exports, TimingGuard, gather utilities
     └─ test-fixtures/       # Spec-fixture loading (prod dep of rpc's Hive test driver)
+  execution/
+    └─ ethrex/              # [include-ethrex] ethrex in-process: bootstrap, --ethrex.* flags, eth_ server (docs/ethrex.md)
   net/
     ├─ api/                 # Actor protocol traits wiring BlockChain ↔ P2P
+    ├─ engine/              # Engine API client: JSON-RPC over HTTP, or typed in-process ethrex calls (include-ethrex)
     ├─ p2p/                 # libp2p: gossipsub + req-resp (Status, BlocksByRoot, BlocksByRange, gloas envelopes)
     │   ├─ src/gossipsub/   # Topic encoding, message handling
     │   ├─ src/req_resp/    # Request/response codec and handlers
@@ -922,6 +925,16 @@ incremental, and line-tables-only debuginfo, so rebuilds are much faster than
 
 ## Common Gotchas
 
+### Embedded ethrex (`include-ethrex`)
+- In a feature build, `ethlambda beacon` without `--execution-endpoint` starts ethrex
+  in-process; with the endpoint it uses HTTP as before. A feature build has no
+  "no execution client" mode. See [`docs/ethrex.md`](docs/ethrex.md)
+- One ethrex tag for the whole workspace (`[workspace.dependencies]`), shared with
+  p2p's discovery. Bumping it means re-diffing ethrex's `init_l1`/`init_rpc_api`/
+  `server_shutdown` against `crates/execution/ethrex/src/lib.rs`, which repeats them
+- `make test-node` excludes `ethlambda-ethrex`; `make test-ethrex` (own CI job) runs
+  it plus the engine and binary with the feature on
+
 ### Aggregator Flag Required for Finalization
 - At least one node **must** be started with `--is-aggregator` to finalize blocks
 - Without this flag, attestations pass signature verification and are logged as "Attestation processed", but the signature is never stored for aggregation (the `is_aggregator` gate in `on_gossip_attestation`, `store.rs`), so blocks are always built with `attestation_count=0`