Merge engine-api-integration (#367) into the in-process ethrex PoC

Absorbs the out-of-process Engine-API integration (#367) so the full EL
pipeline — ExecutionEngine trait, ExecutionPayloadV3 embedded in BlockBody,
process_execution_payload STF, per-slot forkchoiceUpdated, newPayload on import
and on own-built blocks — lands on this branch alongside the in-process
ethrex-engine crate.

Reconciled against 55 commits of main evolution since #367 branched:

- Block-production timing (Option A): main builds+publishes the next slot's
  block one interval early (interval 4). The EL payload is now built inline and
  synchronously at interval 4 via build_execution_payload (build-mode
  forkchoiceUpdated + getPayload), replacing #367's request-at-4 / fetch-at-0
  stash. Dropped pending_payload_id, request_payload_id_for_next_slot,
  take_prepared_payload.
- BlockChainConfig gained execution_client + suggested_fee_recipient (main had
  folded actor params into the config struct); CliOptions moved to cli.rs and
  gained the --execution-* flags there.
- Signature type rename TypeOneMultiSignature -> SingleMessageAggregate applied
  to the merged block-builder / store paths; build_block and
  produce_block_with_signatures now thread both proposer_config and the optional
  execution_payload.
- StateDiff carries latest_execution_payload_header so reconstructed states keep
  the EL block-hash chain (added the field + Eq/PartialEq on
  ExecutionPayloadHeader). Test-only State literals updated for the new field.

Workspace builds, clippy -D warnings is clean, fmt clean; blockchain (58),
state-transition (108), storage (67) unit tests and the ethrex-engine roundtrip
pass. The in-process ExecutionEngine impl + --execution-mode selector are the
next step.

Author: pablodeymo

Cargo.lock

@@ -11,6 +11,7 @@ members = [
     "crates/common/test-fixtures",
     "crates/common/types",
     "crates/net/api",
+    "crates/net/ethrex-client",
     "crates/net/ethrex-engine",
     "crates/net/p2p",
     "crates/net/rpc",
@@ -36,6 +37,7 @@ ethlambda-metrics = { path = "crates/common/metrics" }
 ethlambda-test-fixtures = { path = "crates/common/test-fixtures" }
 ethlambda-types = { path = "crates/common/types" }
 ethlambda-network-api = { path = "crates/net/api" }
+ethlambda-ethrex-client = { path = "crates/net/ethrex-client" }
 ethlambda-p2p = { path = "crates/net/p2p" }
 ethlambda-rpc = { path = "crates/net/rpc" }
 ethlambda-storage = { path = "crates/storage" }
@@ -56,6 +58,7 @@ spawned-concurrency = "0.5.0"
 spawned-rt = "0.5.0"
 tokio = "1.0"
 tokio-util = "0.7"
+async-trait = "0.1.83"
 
 prometheus = "0.14"
 

Cargo.toml

@@ -1,4 +1,4 @@
-.PHONY: help fmt lint docker-build shadow-build shadow-docker-build run-devnet test docs docs-deps docs-serve
+.PHONY: help fmt lint docker-build shadow-build shadow-docker-build run-devnet run-el-demo test docs docs-deps docs-serve
 
 help: ## 📚 Show help for each of the Makefile recipes
 	@grep -E '^[a-zA-Z0-9_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}'
@@ -74,6 +74,9 @@ run-devnet: docker-build lean-quickstart ## 🚀 Run a local devnet using lean-q
 	@cd lean-quickstart \
 		&& NETWORK_DIR=local-devnet ./spin-node.sh --node all --generateGenesis --metrics > ../devnet.log 2>&1
 
+run-el-demo: ## 🔗 Run the ethlambda <-> ethrex Engine API demo (see scripts/engine-api-demo/README.md)
+	@./scripts/engine-api-demo/run.sh
+
 docs-deps: ## 📦 Install dependencies for generating the documentation
 	cargo install --version 0.5.2 --locked mdbook
 	cargo install --version 0.12.0 --locked mdbook-linkcheck2

Makefile

@@ -21,6 +21,7 @@ shadow-integration = ["ethlambda-crypto/shadow-integration"]
 [dependencies]
 ethlambda-blockchain.workspace = true
 ethlambda-crypto.workspace = true
+ethlambda-ethrex-client.workspace = true
 ethlambda-network-api.workspace = true
 ethlambda-p2p.workspace = true
 ethlambda-types.workspace = true

bin/ethlambda/Cargo.toml

@@ -380,6 +380,7 @@ mod tests {
             justified_slots: JustifiedSlots::new(),
             justifications_roots: Default::default(),
             justifications_validators: JustificationValidators::new(),
+            latest_execution_payload_header: Default::default(),
         }
     }
 

bin/ethlambda/src/checkpoint_sync.rs

@@ -75,6 +75,23 @@ pub(crate) struct CliOptions {
     /// Directory for RocksDB storage
     #[arg(long, default_value = "./data")]
     pub(crate) data_dir: PathBuf,
+    /// URL of the ethrex (or other EL) Engine API auth endpoint, e.g.
+    /// `http://127.0.0.1:8551`. When unset, Engine API integration is disabled
+    /// and ethlambda runs as a consensus-only node. When set,
+    /// `--execution-jwt-secret` is required.
+    #[arg(long, requires = "execution_jwt_secret")]
+    pub(crate) execution_endpoint: Option<String>,
+    /// Path to a file containing the 32-byte JWT secret shared with the EL, as
+    /// a single line of hex (optionally `0x`-prefixed). Same format used by
+    /// Lighthouse/Teku/Prysm/ethrex.
+    #[arg(long, requires = "execution_endpoint")]
+    pub(crate) execution_jwt_secret: Option<PathBuf>,
+    /// 32-byte hex hash of the EL's genesis block. Seeds
+    /// `state.latest_execution_payload_header.block_hash` so the first
+    /// `forkchoiceUpdated` carries a head the EL recognizes. Only meaningful
+    /// alongside `--execution-endpoint`.
+    #[arg(long, requires = "execution_endpoint")]
+    pub(crate) execution_genesis_block_hash: Option<String>,
     /// Disable the sync-gate's suppression of validator duties.
     ///
     /// By default a node that judges itself to be syncing (local head lagging