feat(engine): REST+SSZ engine API (execution-apis #793)#7
Open
barnabasbusa wants to merge 1 commit into
Open
Conversation
Replaces the #764 SSZ-over-JSON-RPC transport with the #793 resource-
oriented REST engine API: fork-scoped endpoints under /engine/v2/{fork}/...
with SSZ bodies over HTTP/2 (h2c via httpx), structured JSON for
capabilities/identity, RFC-7807 errors, and the restricted PayloadStatus
enum (no INVALID_BLOCK_HASH). Legacy JSON-RPC stays as the transition-
window fallback: if the EL doesn't expose /engine/v2 (or doesn't advertise
the URL fork), every call falls back to JSON-RPC for the connection.
- ssz_types: per-fork ExecutionPayloadEnvelope (params folded in,
expected_blob_versioned_hashes removed), ForkchoiceUpdate (with
Amsterdam custody_columns), BuiltPayload (new field order), blob-pool
v1-v4 and historical-bodies containers, plus per-fork dispatch tables.
- client: httpx transport (h2c for v2, HTTP/1.1 for JSON-RPC fallback),
GET /engine/v2/capabilities probe, GET /engine/v2/identity +
X-Engine-Client-Version header, CL->EL fork mapping. newPayload/
forkchoiceUpdated/getPayload/getBlobs/bodies route via v2 when the fork
is advertised, else JSON-RPC.
- node: best-effort blob backfill from the EL pool (engine getBlobs) on
gossiped blocks with commitments; reconstructs Deneb/Electra sidecars,
fetches PeerDAS cell proofs (column reconstruction left to the existing
data-column path).
- keep target_gas_limit in the Amsterdam PayloadAttributes: #793 omits it
but geth's post-Amsterdam build path requires it.
getPayloadBodies is implemented on the client but intentionally not wired
into the node: consensoor syncs state over HTTP and the EL self-syncs, so
there is no consumer yet.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Switches the engine API from the #764 SSZ-over-JSON-RPC transport to the #793 resource-oriented REST API: fork-scoped endpoints under
/engine/v2/{fork}/...with SSZ bodies over HTTP/2 (h2c viahttpx), structured JSON for capabilities/identity, RFC-7807 problem responses, and the restrictedPayloadStatusenum (noINVALID_BLOCK_HASH).Legacy JSON-RPC stays as the transition-window fallback: if the EL doesn't expose
/engine/v2/...(or doesn't advertise the URL fork viaGET /engine/v2/capabilities), every call falls back to JSON-RPC for the connection's lifetime.What changed
engine/ssz_types.py— rewritten for #793: per-forkExecutionPayloadEnvelope(params folded in,expectedBlobVersionedHashesremoved),ForkchoiceUpdate(with Amsterdamcustody_columns),BuiltPayload(new field order), blob-poolv1–v4and historical-bodies containers, plus per-fork dispatch tables. NewPayloadStatus(uint8enum,Optional[String]validation_error) — serializes to exactly the 41 bytes in the spec's worked example.engine/client.py—httpxtransport (h2c prior-knowledge for v2, HTTP/1.1 for the JSON-RPC fallback).GET /engine/v2/capabilitiesprobe,GET /engine/v2/identity+X-Engine-Client-Versionheader, CL→EL fork mapping (gloas→amsterdam, …).newPayload/forkchoiceUpdated/getPayload/getBlobs/bodies route via v2 when the fork is advertised, else JSON-RPC.node.py— best-effort blob backfill from the EL pool (enginegetBlobs) for gossiped blocks carrying commitments; reconstructs Deneb/Electra sidecars, fetches PeerDAS cell proofs (column reconstruction left to the existing data-column path). Runs in the background, never blocks import.pyproject.toml— addhttpx[http2];cli.py— update--engine-force-jsonhelp.Notes / deliberate scoping
target_gas_limitkept in the AmsterdamPayloadAttributes. #793's container sketch omits it, but geth's post-Amsterdam build path requires it (the sketch self-describes its types as placeholders).getPayloadBodiesimplemented but not wired into the node — consensoor syncs state over HTTP and the EL self-syncs, so there's no consumer yet. Client methods remain available + tested.Test plan
PayloadStatus== 41-byte spec example--engine-force-jsonskip; identity v2get_blobsfork→revision selection (amsterdam→v4/v3, osaka→v3, cancun→v1, none→None)/engine/v2-capable EL (none available yet)