Skip to content

engine: add Rest-SSZ spec#793

Draft
MariusVanDerWijden wants to merge 6 commits into
ethereum:mainfrom
MariusVanDerWijden:rest-ssz
Draft

engine: add Rest-SSZ spec#793
MariusVanDerWijden wants to merge 6 commits into
ethereum:mainfrom
MariusVanDerWijden:rest-ssz

Conversation

@MariusVanDerWijden
Copy link
Copy Markdown
Member

@MariusVanDerWijden MariusVanDerWijden commented May 8, 2026

There have been multiple attempts at this already.
Moving away from JSON-RPC to REST-SSZ.
However most kept the engine api as is.
I think we have a good shot at refactoring the engine api with this change.

This Draft does that; the move and the refactoring.

Happy for any feedback I can get!

The core of the change is:

Old method New endpoint Notes
engine_newPayloadV{1..5} POST /{fork}/payloads parentBeaconBlockRoot and executionRequests folded into the SSZ envelope; expectedBlobVersionedHashes removed; INVALID_BLOCK_HASH removed from the status enum
engine_forkchoiceUpdatedV{1..4} POST /{fork}/forkchoice one atomic call; carries forkchoice state, optional payload_attributes, and (Amsterdam+) optional custody_columns
engine_getPayloadV{1..6} GET /{fork}/payloads/{id} poll-style, same semantics as today
engine_getPayloadBodiesByHashV{1,2} POST /{fork}/bodies/hash {fork} selects the response schema (not the era of requested blocks); POST because hash lists are too large for URLs
engine_getPayloadBodiesByRangeV{1,2} GET /{fork}/bodies?from=...&count=... {fork} selects the response schema
engine_getBlobsV1 POST /blobs/v1 independently versioned; legacy version numbers carry forward
engine_getBlobsV2 POST /blobs/v2 all-or-nothing cell proofs
engine_getBlobsV3 POST /blobs/v3 partial-response cell proofs
engine_getBlobsV4 POST /blobs/v4 cell-range selection
engine_getClientVersionV1 GET /identity + X-Engine-Client-Version request header unscoped
engine_exchangeCapabilities GET /capabilities unscoped
engine_exchangeTransitionConfigurationV1 removed already deprecated since Cancun

@arnetheduck
Copy link
Copy Markdown
Contributor

arnetheduck commented May 14, 2026

One thing that I think would make sense would be to reuse the base structure of the beacon api (https://github.com/ethereum/beacon-APIs/) - this includes several things:

  • primitives and their json/ssz encoding - ie in general, where possible, reuse the types from https://github.com/ethereum/beacon-APIs/blob/master/types/primitive.yaml so that we don't end up with pointless minor differences in how for example a number is string-encoded (0x0 vs 0x and the like)
  • execution payloads and other (consensus) spec types - the "shape" of objects in the beacon api generally follows the shape of things as they travel on the gossip network and their SSZ encoding - by reusing these types, we would reduce the maintenance overhead of having to pointlessly reorder and rename the exact same fields from the beacon api/consensus spec just to send the same info to the execution api in a slightly different shape
  • use of the canonical ssz/json encodings specified here: https://github.com/ethereum/consensus-specs/blob/master/ssz/simple-serialize.md#json-mapping - this aids debugging and removes the need to double-specify things
  • explicit encoding of fork in the http headers -> we can then upgrade to an new hard fork "automatically" without having to come up with V2, V3 etc

@arnetheduck
Copy link
Copy Markdown
Contributor

The core of the change is:

For top-up sync we also need "current block number", similar to eth_blockNumber but limited to latest and with a well-defined behavior for when the EL does not have a state.

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.

3 participants