Skip to content

Add Beacon API endpoints for EIP-8025 execution proofs - #43

Merged
frisitano merged 1 commit into
optional-proofs-gloasfrom
optional-proofs-gloas-pr-4
Sep 10, 2026
Merged

Add Beacon API endpoints for EIP-8025 execution proofs#43
frisitano merged 1 commit into
optional-proofs-gloasfrom
optional-proofs-gloas-pr-4

Conversation

@frisitano

@frisitano frisitano commented Sep 10, 2026

Copy link
Copy Markdown
Collaborator

Add Beacon API endpoints for EIP-8025 execution proofs

Adds Lighthouse Beacon API server and client support for submitting and retrieving execution proofs, on top of optional-proofs-gloas (base 535046063).

Endpoints

  • POST /eth/v1/beacon/execution_proofs — accepts a JSON array or SSZ List[SignedExecutionProofEnvelope, MAX_EXECUTION_PROOFS_PER_PAYLOAD=4]. Each proof runs the same verification as the execution_proof gossip topic, is published to the network, and is cached in the pending payload cache, importing the payload envelope when the proof gate is satisfied.
  • GET /eth/v1/beacon/execution_proofs/{block_id} — returns the proof envelopes cached for a block's payload, keyed by beacon block root and ordered by proof type, as JSON ({ execution_optimistic, finalized, data }) or SSZ.

Client

BeaconNodeHttpClient gains post_beacon_execution_proofs[_ssz] and get_beacon_execution_proofs[_ssz] over the shared SignedExecutionProofEnvelopes wire type (no duplicated structs).

Response codes

200 when every proof is on the network (published now or already known); an indexed 400 naming the proofs gossip would drop; 404 for unknown blocks; 500 for proof engine or beacon chain faults; 501 on nodes without --proof-engine.

Contract decisions (for the beacon-APIs PR)

  • Request body is a bare list, matching the other batch publish endpoints, not { "proofs": [...] }.
  • Wire type is the gossip envelope SignedExecutionProofEnvelope, never re-signed, adapted from the older SignedExecutionProof + PublicInput shape.
  • proof_type serializes as a quoted string in JSON to match the beacon-APIs Uint8 schema; SSZ and gossip encoding are unchanged.
  • MAX_EXECUTION_PROOFS_PER_PAYLOAD = 4 taken from the EIP text.

Validation

  • cargo fmt --all -- --check: clean.
  • cargo test -p types execution_proof (7), -p warp_utils (3), -p beacon_chain --lib pending_payload_cache (12), -p eth2 (13): pass.
  • cargo test --release -p http_api --test bn_http_api_tests execution_proof_tests (3): pass — JSON and SSZ submit/get, publication, lookup by root/head/slot, 404, 501, indexed 400 failures.
  • cargo clippy on the five changed crates with the make lint flags: no issues.
  • Not run: full bn_http_api_tests suite, the FORK_NAME matrix, workspace clippy, network/Kurtosis.

Note

Retrieval currently reads the in-memory pending payload cache (last 32 payloads); a follow-up persistent-storage task will extend this beyond recent blocks.

Serve `POST /eth/v1/beacon/execution_proofs` and
`GET /eth/v1/beacon/execution_proofs/{block_id}`, and expose matching
`BeaconNodeHttpClient` methods in JSON and SSZ.

Submitted `SignedExecutionProofEnvelope`s go through the same
verification as the `execution_proof` gossip topic, are published to the
network and cached in the pending payload cache, importing the payload
envelope when the proof gate is satisfied. Retrieval returns the
envelopes cached for a block's payload, keyed by beacon block root and
ordered by proof type.

Responses follow existing conventions: 200 when every proof is on the
network (published now or already known), an indexed 400 naming the
proofs gossip would drop, 404 for unknown blocks, 500 for proof engine
or beacon chain faults, and 501 on nodes without a proof engine.

Both encodings use the new `SignedExecutionProofEnvelopes` list bounded
by EIP-8025 `MAX_EXECUTION_PROOFS_PER_PAYLOAD`, and `proof_type` is now
quoted in JSON to match the beacon-APIs `Uint8` schema.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QMcYSjxdgRfab7TaYXFV3E
@frisitano frisitano changed the title optional-proofs-gloas-pr-4 Add Beacon API endpoints for EIP-8025 execution proofs Sep 10, 2026
@frisitano
frisitano merged commit 2ab0268 into optional-proofs-gloas Sep 10, 2026
35 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant