feat: eip8025

[frisitano]

Issue Addressed

Which issue # does this PR address?

Proposed Changes

Please list or describe the changes introduced by this PR.

Additional Info

Please provide any additional information. For example, future considerations
or information useful for reviewers.

[kevaundray]

Isn't this logic that the CL should be doing? It seems like we are redoing logic related to forks that we probably can just get from the CLs fork choice impl for free

[frisitano]

As far as I can see, there are no execution block hash ancestry checks in the CL specs or code. These checks are delegated to the engineAPI. I think we could make some changes to the specs to mitigate this requirement, but that would be more invasive (spec changes) than using the existing decoupling and separation of concerns. I would propose deferring those changes to the mandatory proofs hardfork.

[kevaundray]

My assumption here is that the CL has forking logic that is used to select the "correct" beacon block and every beacon block corresponds to an execution block hash -- can this not be re-used or are you solving a different problem?

[kevaundray]

May be good to add a comment on this and or make it conditional for optional proofs, since normal CLs will have an EL attached

[frisitano]

From what I can see, DEFAULT_ENGINE_CAPABILITIES is primarily used in MockServer, which does not support get_blobs_* methods.

[kevaundray]

ack on comment; since we are now cloning on every block import

[frisitano]

I will try to refactor this code to remove this requirement.

[kevaundray]

Even if execution engine doesn't error, wouldn't this ? cause an early return if proof_engine errors, so we never get to:

        let result = engine_result
            .or(proof_engine_result)
            .expect("at least one of engine or proof engine must be present");

?

[frisitano]

Good catch. I was using ? for ergonomic proof conversion, but you are correct that this results in early return. I will update.

[dapplion]

yoo human lion here: I had a long chat with claude on how we can get the min possible thing that Lighthouse devs will pay attention to, to get the ball rolling. This is my suggestion @kevaundray

Review & Suggestion for Minimum Viable First PR

This PR is very comprehensive but at 102 files / ~8400 lines it will be extremely difficult to review and merge as a single PR. Below is a suggestion for scoping a minimal first PR that delivers a working end-to-end proof verification path while minimizing changes to existing production code.

Proposed scope: HTTP API only

Proofs are submitted via the beacon node HTTP API → BLS verified → proof engine verified → fork choice updated. No P2P gossip, no sync, no validator client proof service.

Key design simplifications

1. Keep the execution engine required (don't make engine an Option).

The current PR refactors ~30 methods in execution_layer/src/lib.rs to wrap every self.engine() call in if let Some(engine). This is the single largest source of production-path contamination. Instead, keep the engine required and make the proof engine purely additive — users run a normal EL alongside it. This reduces the EL changes to ~3 lines added to notify_new_payload and ~3 lines to notify_forkchoice_updated:

if let Some(proof_engine) = self.proof_engine() {
    proof_engine.new_payload(&new_payload_request).await;
}

Proof-engine-only mode (no traditional EL) can come in a follow-up PR.

2. Move the request_root ↔ block_root mapping into the proof engine state.

The current PR adds two Mutex<LruCache> fields to HotColdDB and computes + stores the mapping during every block import in execution_payload.rs. This is unnecessary — the proof engine's new_payload already receives the NewPayloadRequest, so it can compute the tree hash root and store the mapping in its own in-memory State struct (which is already ephemeral and prunes on finalization). This eliminates all changes to HotColdDB and execution_payload.rs.

3. Don't modify NewPayloadRequest.

The current PR adds #[derive(TreeHash)] to NewPayloadRequest and changes versioned_hashes from Vec<VersionedHash> to VariableList<VersionedHash, ...>, which ripples through every TryFrom<BeaconBlockRef> arm. Instead, compute the tree hash externally with a standalone function. Zero changes to the existing type.

4. Drop BlockFull SSE event.

This is a separate feature unrelated to proof verification. Including it changes the import_block_update_metrics_and_events signature and adds an unconditional Arc::unwrap_or_clone(signed_block.clone()) on every block import. Can be its own small PR.

5. Don't gossip proofs.

The HTTP API handler just verifies and stores locally. This eliminates all lighthouse_network dependencies from this PR.

What remains in the minimal PR

Layer	Scope
Consensus types	New eip8025 module (types, domain constant). All new code.
Proof engine	New eip8025 module in execution_layer (HttpProofEngine, State, errors, JSON-RPC). All new code.
Execution layer	~3 lines in notify_new_payload + ~3 lines in notify_forkchoice_updated. New proof_engine field.
Beacon chain	New eip8025 module with verify_execution_proof (BLS → engine verify → fork choice). All new code.
HTTP API	New GET/POST /eth/v1/beacon/execution_proofs. All new code.
CLI	New --proof-engine-endpoint flag.

Production path changes: exactly two methods (notify_new_payload, notify_forkchoice_updated), each with a small additive change.

Estimated size: ~2500-3000 lines across ~20 files (down from ~8400 / 102).

What moves to follow-up PRs

1. P2P gossip + proof sync (the entire networking layer)
2. Validator client proof service
3. Proof-engine-only mode (making engine optional)
4. BlockFull SSE event

Additional review notes on the current code

A few issues worth addressing regardless of how the PR is split:

• verify_signed_execution_proof_signature never checks whether the fork supports EIP-8025. The UnsupportedFork error variant exists but is never returned, and test_verify_unsupported_fork will fail.
• buffered_proofs in HttpProofEngine has no size bound — needs a capacity limit to prevent memory DoS.
• Duplicate proof insertion is not checked in State::insert_proof — the same proof pushed N times can falsely meet min_required_proofs.
• is_descendant in state.rs has no cycle guard — a corrupted parent pointer causes an infinite loop.
• RPC error handler in sync/manager.rs for execution proof requests only logs the error without cleaning up tracking maps or notifying ProofSync, leaving it stuck in RangeRequestInFlight permanently.
• ExecutionProofsByRange handler has no upper-bound validation on count (unlike BlocksByRange and LCUpdatesByRange).
• Multiple TODOs throughout lack GitHub issue links (repo convention per CLAUDE.md).