feat: integrate with ethrex over the Engine API

Cargo.toml

@@ -11,6 +11,7 @@ members = [
     "crates/common/test-fixtures",
     "crates/common/types",
     "crates/net/api",
+    "crates/net/ethrex-client",
     "crates/net/p2p",
     "crates/net/rpc",
     "crates/storage",
@@ -35,6 +36,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" }

bin/ethlambda/Cargo.toml

@@ -7,6 +7,7 @@ license.workspace = true
 
 [dependencies]
 ethlambda-blockchain.workspace = true
+ethlambda-ethrex-client.workspace = true
 ethlambda-network-api.workspace = true
 ethlambda-p2p.workspace = true
 ethlambda-types.workspace = true

bin/ethlambda/src/checkpoint_sync.rs

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

bin/ethlambda/src/main.rs

@@ -25,6 +25,8 @@ use ethlambda_p2p::{Bootnode, P2P, PeerId, SwarmConfig, build_swarm, parse_enrs}
 use ethlambda_types::primitives::{H256, HashTreeRoot as _};
 use ethlambda_types::{
     aggregator::AggregatorController,
+    block::{Block, BlockBody},
+    execution_payload::ExecutionPayloadV3,
     genesis::GenesisConfig,
     signature::ValidatorSecretKey,
     state::{State, ValidatorPubkeyBytes},
@@ -34,6 +36,7 @@ use tracing::{error, info, warn};
 use tracing_subscriber::{EnvFilter, Layer, Registry, layer::SubscriberExt};
 
 use ethlambda_blockchain::BlockChain;
+use ethlambda_ethrex_client::{ETHLAMBDA_ENGINE_CAPABILITIES, EngineClient, JwtSecret};
 use ethlambda_rpc::RpcConfig;
 use ethlambda_storage::{StorageBackend, Store, backend::RocksDBBackend};
 
@@ -109,6 +112,30 @@ struct CliOptions {
     /// Directory for RocksDB storage
     #[arg(long, default_value = "./data")]
     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")]
+    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")]
+    execution_jwt_secret: Option<PathBuf>,
+    /// 32-byte hex hash of the EL's genesis block.
+    ///
+    /// When set, seeds `state.latest_execution_payload_header.block_hash`
+    /// so the very first `engine_forkchoiceUpdatedV3` carries a head the
+    /// EL recognizes. Without this seed the EL replies `SYNCING` forever
+    /// and never starts building payloads, leaving the chain stuck with
+    /// synthetic zero-hash payloads.
+    ///
+    /// Find ethrex's value in its boot log line `Genesis Block Hash: ...`.
+    /// Required when running paired with an EL; only meaningful alongside
+    /// `--execution-endpoint`.
+    #[arg(long, requires = "execution_endpoint")]
+    execution_genesis_block_hash: Option<String>,
 }
 
 #[tokio::main]
@@ -206,10 +233,21 @@ async fn main() -> eyre::Result<()> {
     std::fs::create_dir_all(&data_dir).expect("Failed to create data directory");
     let backend = Arc::new(RocksDBBackend::open(&data_dir).expect("Failed to open RocksDB"));
 
+    let execution_genesis_block_hash = options
+        .execution_genesis_block_hash
+        .as_deref()
+        .map(parse_h256_hex)
+        .transpose()
+        .map_err(|err| {
+            error!(%err, "Invalid --execution-genesis-block-hash");
+            eyre::eyre!(err)
+        })?;
+
     let store = fetch_initial_state(
         options.checkpoint_sync_url.as_deref(),
         &genesis_config,
         backend.clone(),
+        execution_genesis_block_hash,
     )
     .await
     .inspect_err(|err| error!(%err, "Failed to initialize state"))?;
@@ -221,7 +259,18 @@ async fn main() -> eyre::Result<()> {
     // and the API server (which exposes GET/POST admin endpoints).
     let aggregator = AggregatorController::new(options.is_aggregator);
 
-    let blockchain = BlockChain::spawn(store.clone(), validator_keys, aggregator.clone());
+    let execution_client = build_execution_client(
+        options.execution_endpoint.as_deref(),
+        options.execution_jwt_secret.as_deref(),
+    )
+    .await;
+
+    let blockchain = BlockChain::spawn(
+        store.clone(),
+        validator_keys,
+        aggregator.clone(),
+        execution_client,
+    );
 
     // Note: SwarmConfig.is_aggregator is intentionally a plain bool, not the
     // AggregatorController — subnet subscriptions are decided once here and
@@ -542,6 +591,70 @@ fn read_validator_keys(
     Ok(validator_keys)
 }
 
+/// Build the optional Engine API client and run the capability handshake.
+///
+/// Returns `None` when integration is disabled (neither flag provided).
+/// Returns `None` and logs an error when construction or the handshake
+/// fails — consensus must keep running regardless of EL state.
+async fn build_execution_client(
+    endpoint: Option<&str>,
+    jwt_path: Option<&Path>,
+) -> Option<EngineClient> {
+    // CLI requires both-or-neither; defensive recheck for clarity.
+    let (endpoint, jwt_path) = match (endpoint, jwt_path) {
+        (Some(e), Some(p)) => (e, p),
+        (None, None) => return None,
+        _ => {
+            error!("Both --execution-endpoint and --execution-jwt-secret are required together");
+            return None;
+        }
+    };
+
+    let secret = match JwtSecret::from_file(jwt_path) {
+        Ok(s) => s,
+        Err(err) => {
+            error!(path = %jwt_path.display(), %err, "Failed to load JWT secret");
+            return None;
+        }
+    };
+
+    let client = match EngineClient::new(endpoint, secret) {
+        Ok(c) => c,
+        Err(err) => {
+            error!(%err, "Failed to construct EngineClient");
+            return None;
+        }
+    };
+
+    info!(endpoint, "Engine API integration enabled");
+
+    match client
+        .exchange_capabilities(ETHLAMBDA_ENGINE_CAPABILITIES)
+        .await
+    {
+        Ok(caps) => info!(count = caps.len(), "EL capability handshake succeeded"),
+        Err(err) => warn!(
+            %err,
+            "EL capability handshake failed; per-slot FCU calls will still be attempted"
+        ),
+    }
+
+    Some(client)
+}
+
+/// Parse a 32-byte hex H256 from a `0x`-prefixed or bare hex string.
+fn parse_h256_hex(s: &str) -> Result<H256, String> {
+    let stripped = s.strip_prefix("0x").unwrap_or(s);
+    let bytes = hex::decode(stripped).map_err(|e| format!("{s:?} is not valid hex: {e}"))?;
+    if bytes.len() != 32 {
+        return Err(format!(
+            "{s:?} decoded to {} bytes, expected 32",
+            bytes.len()
+        ));
+    }
+    Ok(H256::from_slice(&bytes))
+}
+
 fn read_hex_file_bytes(path: impl AsRef<Path>) -> Vec<u8> {
     let path = path.as_ref();
     let Ok(file_content) = std::fs::read_to_string(path)
@@ -584,13 +697,64 @@ async fn fetch_initial_state(
     checkpoint_url: Option<&str>,
     genesis: &GenesisConfig,
     backend: Arc<dyn StorageBackend>,
+    execution_genesis_block_hash: Option<H256>,
 ) -> Result<Store, checkpoint_sync::CheckpointSyncError> {
     let validators = genesis.validators();
 
     let Some(checkpoint_url) = checkpoint_url else {
         info!("No checkpoint sync URL provided, initializing from genesis state");
-        let genesis_state = State::from_genesis(genesis.genesis_time, validators);
-        return Ok(Store::from_anchor_state(backend, genesis_state));
+        let mut genesis_state = State::from_genesis(genesis.genesis_time, validators);
+
+        // M6: when paired with an EL, seed both the cached header in state AND
+        // the genesis block's actual `execution_payload.block_hash` with the
+        // EL's genesis hash. The cached header drives STF's
+        // `process_execution_payload` parent_hash check; the body's block_hash
+        // is what `el_hash_at` reads back into `engine_forkchoiceUpdatedV3`'s
+        // `head_block_hash`. Without seeding *both*, either the first non-
+        // genesis block fails STF or every FCU stays at ZERO and the EL never
+        // accepts the build attempt.
+        return Ok(match execution_genesis_block_hash {
+            Some(el_hash) => {
+                info!(%el_hash, "Seeding genesis with EL block hash");
+                genesis_state.latest_execution_payload_header.block_hash = el_hash;
+
+                // Build the body, then update the state's latest header so
+                // its body_root reflects the seeded body (rather than the
+                // empty default it had after State::from_genesis).
+                let body = BlockBody {
+                    attestations: Default::default(),
+                    execution_payload: ExecutionPayloadV3 {
+                        block_hash: el_hash,
+                        ..Default::default()
+                    },
+                };
+                genesis_state.latest_block_header.body_root = body.hash_tree_root();
+
+                // Compute state_root with the header's state_root zeroed,
+                // then write it back. `anchor_pair_is_consistent` requires
+                // `block.state_root == state.hash_tree_root(state_root=0)`
+                // exactly — not just "block.state_root is zero".
+                genesis_state.latest_block_header.state_root = H256::ZERO;
+                let anchor_state_root = genesis_state.hash_tree_root();
+                genesis_state.latest_block_header.state_root = anchor_state_root;
+
+                let genesis_block = Block {
+                    slot: genesis_state.latest_block_header.slot,
+                    proposer_index: genesis_state.latest_block_header.proposer_index,
+                    parent_root: genesis_state.latest_block_header.parent_root,
+                    state_root: anchor_state_root,
+                    body,
+                };
+
+                Store::get_forkchoice_store(backend, genesis_state, genesis_block).map_err(
+                    |err| {
+                        error!(%err, "Failed to initialize store with seeded genesis body");
+                        checkpoint_sync::CheckpointSyncError::AnchorPairingMismatch
+                    },
+                )?
+            }
+            None => Store::from_anchor_state(backend, genesis_state),
+        });
     };
 
     // Checkpoint sync path

crates/blockchain/Cargo.toml

@@ -11,6 +11,7 @@ version.workspace = true
 autotests = false
 
 [dependencies]
+ethlambda-ethrex-client.workspace = true
 ethlambda-network-api.workspace = true
 ethlambda-storage.workspace = true
 ethlambda-state-transition.workspace = true