feat(rpc): Hive lean spec-assets test-driver endpoints (lambdaclass#357)

## Summary

- Adds an opt-in `/lean/v0/test_driver/...` HTTP router gated by
`HIVE_LEAN_TEST_DRIVER`, enabling the new lean spec-asset suites from
[ethereum/hive#1480](ethereum/hive#1480)
(`lean-spec-tests-{fork-choice,state-transition,verify-signatures}`) to
drive ethlambda over HTTP.
- In driver mode the binary skips the BlockChain actor and P2P swarm
entirely and serves only the four new endpoints plus `/lean/v0/health`.
State lives behind `Arc<RwLock<Store>>` so each `fork_choice/init`
request replaces the store and a single container can replay many
fixtures.
- Reuses the production code paths (`store::on_tick` /
`on_block_without_verification` / `on_gossip_*`,
`state_transition::state_transition`, `verify_block_signatures`) so the
driver exercises the same logic as the consensus stack.
- Lifts the fork-choice and verify-signatures fixture deserialization
types out of `crates/blockchain/tests/` into the shared
`ethlambda-test-fixtures` crate so the RPC handler and offline spec-test
runner consume the same JSON schemas.

### Endpoints (camelCase per the hive contract)

```
POST /lean/v0/test_driver/fork_choice/init      -> 204 / 400
POST /lean/v0/test_driver/fork_choice/step      -> { accepted, error?, snapshot }
POST /lean/v0/test_driver/state_transition/run  -> { succeeded, error?, post? }
POST /lean/v0/test_driver/verify_signatures/run -> { succeeded, error? }
```

### Hive run result

End-to-end run against a local hive instance with ethlambda built from
this branch — all three spec-asset suites green:

| Suite | Result |
|---|---|
| `lean-spec-tests-fork-choice`     | **85/85** ✅ |
| `lean-spec-tests-state-transition`| **51/51** ✅ |
| `lean-spec-tests-verify-signatures`| **12/12** ✅ |
| **Total**                          | **148/148** ✅ |

First fork-choice run was 84/85: a single fixture
(`test_store_from_anchor_rejects_mismatched_state_root`) caught a
missing anchor invariant in the init handler. Fix in `1aa9f8f` enforces
`block.state_root == state.tree_hash_root()` (with the header's
`state_root` zeroed), mirroring Ream's check, and a new e2e regression
test (`init_with_garbage_block_state_root_returns_400`) covers the exact
shape. The rerun went 85/85.

### Commits

- `41b86fd` feat(rpc): add Hive lean spec-assets test-driver endpoints
- `b1f2ba5` fix(bin): check `HIVE_LEAN_TEST_DRIVER` before reading
`--node-key`
- `1aa9f8f` fix(rpc): reject anchors whose `block.state_root` disagrees
with the state

## Test plan

- [x] `cargo fmt --all -- --check`
- [x] `cargo clippy --workspace --tests --all-targets -- -D warnings`
- [x] `cargo test -p ethlambda-rpc` — 18 lib + 8 e2e tests (the 8 e2e
tests use `tower::ServiceExt::oneshot` to exercise every endpoint with
real JSON bodies; one of them is a regression test for the anchor
invariant from `1aa9f8f`)
- [x] `cargo test --workspace --lib --bins` — all suites green
- [x] Smoke test the binary in driver mode with a non-existent
`--node-key`; confirm short-circuit + `/lean/v0/health` +
`/state_transition/run` respond correctly
- [x] Hive `lean-spec-tests-fork-choice` — **85/85 pass**
- [x] Hive `lean-spec-tests-state-transition` — **51/51 pass**
- [x] Hive `lean-spec-tests-verify-signatures` — **12/12 pass**

Author: MegaRedHand

Cargo.lock

@@ -109,8 +109,6 @@ async fn main() -> eyre::Result<()> {
     ethlambda_blockchain::metrics::set_node_info("ethlambda", version::CLIENT_VERSION);
     ethlambda_blockchain::metrics::set_node_start_time();
 
-    let node_p2p_key = read_hex_file_bytes(&options.node_key);
-    let p2p_socket = SocketAddr::new(IpAddr::from([0, 0, 0, 0]), options.gossipsub_port);
     let rpc_config = RpcConfig {
         http_address: options.http_address,
         api_port: options.api_port,
@@ -120,6 +118,22 @@ async fn main() -> eyre::Result<()> {
     println!("{ASCII_ART}");
 
     info!(version = version::CLIENT_VERSION, "Starting ethlambda");
+
+    // Hive lean spec-asset suites boot the client with
+    // HIVE_LEAN_TEST_DRIVER=1 so it skips the consensus/p2p stack and
+    // exposes only the `/lean/v0/test_driver/...` endpoints driven by the
+    // simulator. Detected here before any config / key / genesis loading
+    // so the driver run doesn't touch --node-key, --custom-network-config-dir,
+    // or any other consensus prerequisite the hive shim doesn't bother to
+    // provision.
+    if ethlambda_rpc::test_driver::test_driver_enabled() {
+        info!("HIVE_LEAN_TEST_DRIVER detected; booting in test-driver mode");
+        return run_test_driver(rpc_config).await;
+    }
+
+    let node_p2p_key = read_hex_file_bytes(&options.node_key);
+    let p2p_socket = SocketAddr::new(IpAddr::from([0, 0, 0, 0]), options.gossipsub_port);
+
     #[cfg(not(target_env = "msvc"))]
     info!("Using jemalloc allocator with heap profiling enabled");
     #[cfg(target_env = "msvc")]
@@ -275,6 +289,40 @@ async fn main() -> eyre::Result<()> {
     Ok(())
 }
 
+/// Boot the binary in Hive test-driver mode.
+///
+/// Skips every consensus/p2p subsystem and just exposes the
+/// `/lean/v0/test_driver/...` HTTP endpoints over the configured API port.
+/// The driver-mode store is seeded with an empty in-memory state and is
+/// replaced on every `fork_choice/init` request from the simulator.
+async fn run_test_driver(rpc_config: RpcConfig) -> eyre::Result<()> {
+    use tokio::sync::RwLock;
+
+    let driver: ethlambda_rpc::test_driver::DriverState =
+        Arc::new(RwLock::new(ethlambda_rpc::test_driver::empty_driver_store()));
+
+    let shutdown_token = CancellationToken::new();
+    let rpc_shutdown = shutdown_token.clone();
+
+    let rpc_handle = tokio::spawn(async move {
+        if let Err(err) =
+            ethlambda_rpc::start_test_driver_rpc_server(rpc_config, driver, rpc_shutdown).await
+        {
+            error!(%err, "Test-driver RPC server failed");
+        }
+    });
+
+    info!("Test-driver RPC ready");
+
+    tokio::signal::ctrl_c().await.ok();
+    info!("Shutdown signal received, stopping test-driver RPC...");
+    shutdown_token.cancel();
+    let _ = rpc_handle.await;
+    info!("Shutdown complete");
+
+    Ok(())
+}
+
 /// Subset of `validator-config.yaml` consumed by ethlambda.
 ///
 /// The `config` block is a network-wide settings bag shared across clients;

bin/ethlambda/src/main.rs

@@ -477,7 +477,7 @@ fn on_block_core(
     let sig_verification_start = std::time::Instant::now();
     if verify {
         // Validate cryptographic signatures
-        verify_signatures(&parent_state, &signed_block)?;
+        verify_block_signatures(&parent_state, &signed_block)?;
     }
     let sig_verification = sig_verification_start.elapsed();
 
@@ -1157,7 +1157,15 @@ fn build_block(
 /// Verify all signatures in a signed block.
 ///
 /// Each attestation has a corresponding proof in the signature list.
-fn verify_signatures(state: &State, signed_block: &SignedBlock) -> Result<(), StoreError> {
+///
+/// Exposed publicly so RPC handlers (notably the Hive test-driver
+/// `verify_signatures/run` endpoint) can run the exact same verification path
+/// the import pipeline uses; the production import path also calls this from
+/// [`on_block_core`].
+pub fn verify_block_signatures(
+    state: &State,
+    signed_block: &SignedBlock,
+) -> Result<(), StoreError> {
     use ethlambda_crypto::verify_aggregated_signature;
     use ethlambda_types::signature::ValidatorSignature;
 
@@ -1372,7 +1380,7 @@ mod tests {
             },
         };
 
-        let result = verify_signatures(&state, &signed_block);
+        let result = verify_block_signatures(&state, &signed_block);
         assert!(
             matches!(result, Err(StoreError::ParticipantsMismatch)),
             "Expected ParticipantsMismatch, got: {result:?}"

crates/blockchain/src/store.rs

@@ -7,20 +7,16 @@ use std::{
 use ethlambda_blockchain::{MILLISECONDS_PER_INTERVAL, MILLISECONDS_PER_SLOT, store};
 use ethlambda_storage::{Store, backend::InMemoryBackend};
 use ethlambda_types::{
-    attestation::{AttestationData, SignedAggregatedAttestation, SignedAttestation, XmssSignature},
-    block::{AggregatedSignatureProof, Block, BlockSignatures, SignedBlock},
+    attestation::{AttestationData, SignedAggregatedAttestation, SignedAttestation},
+    block::{AggregatedSignatureProof, Block},
     primitives::{ByteList, H256, HashTreeRoot as _},
-    signature::SIGNATURE_SIZE,
     state::State,
 };
 
-use crate::types::{ForkChoiceTestVector, StoreChecks};
+use ethlambda_test_fixtures::fork_choice::{AttestationCheck, ForkChoiceTestVector, StoreChecks};
 
 const SUPPORTED_FIXTURE_FORMAT: &str = "fork_choice_test";
 
-mod common;
-mod types;
-
 /// List of skipped tests.
 const SKIP_TESTS: &[&str] = &[];
 
@@ -66,7 +62,7 @@ fn run(path: &Path) -> datatest_stable::Result<()> {
                         block_registry.insert(label.clone(), root);
                     }
 
-                    let signed_block = build_signed_block(block_data);
+                    let signed_block = block_data.to_blank_signed_block();
 
                     let block_time_ms =
                         genesis_time * 1000 + signed_block.message.slot * MILLISECONDS_PER_SLOT;
@@ -161,29 +157,6 @@ fn assert_step_outcome<T, E: std::fmt::Debug>(
     }
 }
 
-fn build_signed_block(block_data: types::BlockStepData) -> SignedBlock {
-    let block: Block = block_data.to_block();
-
-    // Build one empty proof per attestation, matching the aggregation_bits from
-    // each attestation in the block body. Block processing zips attestations with
-    // signatures, so they must be the same length for attestations to reach
-    // fork choice.
-    let proofs: Vec<_> = block
-        .body
-        .attestations
-        .iter()
-        .map(|att| AggregatedSignatureProof::empty(att.aggregation_bits.clone()))
-        .collect();
-
-    SignedBlock {
-        message: block,
-        signature: BlockSignatures {
-            proposer_signature: XmssSignature::try_from(vec![0u8; SIGNATURE_SIZE]).unwrap(),
-            attestation_signatures: proofs.try_into().expect("attestation proofs within limit"),
-        },
-    }
-}
-
 fn validate_checks(
     st: &Store,
     checks: &StoreChecks,
@@ -374,7 +347,7 @@ fn validate_checks(
 
 fn validate_attestation_check(
     st: &Store,
-    check: &types::AttestationCheck,
+    check: &AttestationCheck,
     step_idx: usize,
 ) -> datatest_stable::Result<()> {
     let validator_id = check.validator;

crates/blockchain/tests/common.rs

@@ -9,9 +9,7 @@ use ethlambda_types::{
     state::State,
 };
 
-mod common;
-mod signature_types;
-use signature_types::VerifySignaturesTestVector;
+use ethlambda_test_fixtures::verify_signatures::VerifySignaturesTestVector;
 
 const SUPPORTED_FIXTURE_FORMAT: &str = "verify_signatures_test";
 

crates/blockchain/tests/forkchoice_spectests.rs

@@ -14,4 +14,5 @@ ethlambda-types.workspace = true
 libssz-types.workspace = true
 
 serde.workspace = true
+serde_json.workspace = true
 hex.workspace = true