EIP-8178 Engine API Binary SSZ Transport (Binary SSZ Transport for the Engine API)

No call decision · Networking & nodes · EIP status Draft · created 2026-03-01

Adds a binary SSZ transport that can be used instead of JSON-RPC for Engine API communication between the consensus layer and the execution layer. Transport size is reduced by about 50%.

Why it is needed

An Ethereum node is split into two programs, the Consensus Layer (CL) and the Execution Layer (EL), and they talk to each other through a channel called the Engine API throughout the whole process of propagating and validating blocks. Right now this channel uses a text-based method called JSON-RPC. Binary data such as hashes, addresses, transactions, and blobs is converted into hexadecimal characters before being sent, which doubles the transport size and burns CPU on both sides building and parsing JSON. On top of that, because the consensus layer internally uses a binary format called SSZ, it repeatedly converts SSZ to JSON at the Engine API boundary and then back to the internal format. This EIP adds a transport method that sends and receives SSZ bytes directly over HTTP, eliminating this waste. According to the source, transport size is reduced by about 50% compared to JSON-RPC, and serialization no longer becomes a bottleneck on the critical path between the CL and EL.

What changes

Today

After EIP-8178

Who is affected

In depth

Transport layer: REST and octet-stream on the same port

The new transport is resource-oriented REST over HTTP. All endpoints are served under the /engine prefix on the existing Engine API port (default 8551), with paths split by resource type (payloads, forkchoice, blobs). Request and response bodies carry SSZ-serialized bytes as is with Content-Type: application/octet-stream, and only error responses return human-readable messages as text/plain. GET requests with no body should (SHOULD) include an Accept: application/octet-stream header. Authentication uses the same JWT scheme as JSON-RPC, and every request must (MUST) include a valid JWT bearer token in the Authorization header.

Versioning: one-to-one correspondence with JSON-RPC method versions

Following Beacon API convention, endpoints embed a version number in the path, and this number matches the version of the JSON-RPC method it replaces. Per the endpoint summary, POST /engine/v4/payloads corresponds to engine_newPayloadV4, GET /engine/v5/payloads/{payload_id} to engine_getPayloadV5, POST /engine/v3/forkchoice to engine_forkchoiceUpdatedV3, and POST /engine/v3/blobs to engine_getBlobsV3. Payload submission is defined from v1 (Paris) through v4 (Prague), payload retrieval from v1 through v5 (Osaka), fork choice from v1 through v3 (Cancun), blob retrieval from v1 (Cancun) through v3 (Osaka), and client version exchange defines v1. When a new fork introduces a new method version, a new version path is added, and old paths may (MAY) be deprecated but should (SHOULD) be kept for backward compatibility.

HTTP status code scheme

There are two success cases. 200 OK carries the SSZ-encoded result in the body, and 204 No Content responds with an empty body when the result is null, such as during syncing. Client errors are split into 400 (malformed SSZ encoding), 401 (missing or invalid JWT), 404 (unknown payload ID), 409 (invalid fork choice state), 413 (maximum element count exceeded), and 422 (invalid payload attributes), and server errors are 500 (unexpected server error). Error response bodies are human-readable messages with Content-Type: text/plain.

SSZ type mapping and null representation

JSON-RPC's basic types map fixedly to SSZ types. address is Bytes20, hash32 and bytes32 are Bytes32, bytes48 is Bytes48, bytes256 is ByteVector[256], uint64 and uint256 stay the same, variable-length bytes become ByteList[MAX_LENGTH] with a context-specific cap, and arrays become List[T, MAX_LENGTH]. 'T or null' is expressed as List[T, 1]: zero elements means null (absent), and one element means a value is present. This rule is used for payload_attributes in fork choice requests, the inner list of PayloadBodiesV1Response (zero for an unknown block, one for a known block), and the inner list of GetBlobsV3Response (zero for a missing blob, one for a present blob).

Container definitions: SSZ structures for every fork

Fork-specific SSZ containers are defined for every structure in the Engine API. ExecutionPayloadV1 (Paris) holds fields from parent_hash through transactions, V2 (Shanghai) adds withdrawals, and V3 (Cancun) adds blob_gas_used and excess_blob_gas. PayloadStatusV1's status is a uint8 enum where 0=VALID, 1=INVALID, 2=SYNCING, 3=ACCEPTED, 4=INVALID_BLOCK_HASH, and latest_valid_hash is filled with all zeros when there is no value. ForkchoiceUpdatedResponseV1's payload_id is also all zeros if payload building has not started. Blob bundles are split into BlobsBundleV1 (one proof per blob) and BlobsBundleV2 (CELLS_PER_EXT_BLOB=128 cell proofs per blob), and GetPayloadResponse is defined from V2 (adds block_value) through V5 (includes BlobsBundleV2 and execution_requests).

Constants, size limits, and security requirements

List caps are fixed as constants. A single transaction is at most MAX_BYTES_PER_TRANSACTION (2**30 bytes), transactions per payload are capped at MAX_TRANSACTIONS_PER_PAYLOAD (2**20), blob commitments per block are capped at MAX_BLOB_COMMITMENTS_PER_BLOCK (4,096), and a single blob is BLOB_SIZE (131,072 bytes). On the security side, SSZ deserialization must (MUST) observe the same size limits as JSON deserialization, and payloads exceeding the defined maximum size must (MUST) be rejected before attempting full deserialization. Implementations should (SHOULD) use a validated SSZ library and extensively fuzz-test SSZ parsing, and the {payload_id} in the URL path must (MUST) be validated as a proper hexadecimal Bytes8 before processing.

Design rationale: REST, same port, no hard fork needed

The source explains the reasoning behind the design choices. REST is used instead of raw TCP because it is easier to debug, can reuse existing infrastructure such as load balancers, proxies, and monitoring, and the Beacon API already works well with the combination of REST and SSZ. The connection between the CL and EL is usually localhost communication, so there is no real benefit to dropping to a lower level. The same port is used instead of a separate port so that operators don't have to manage an additional port, firewall rules, and JWT secret. JSON-RPC uses application/json on POST /, while the SSZ REST uses application/octet-stream on resource paths, so the two coexist without conflict. This EIP is a purely client-side change with no consensus change, no state transition change, and no new opcodes, so it requires no hard fork and each client can ship it as a regular release whenever it wants.

Status: Draft

The status of this EIP is Draft. Specification details such as endpoint configuration, container definitions, and constants may still change. The existing JSON-RPC Engine API is fully retained and always available, so clients that have not implemented binary SSZ are unaffected. The call records provided contain no fork inclusion decision for this EIP.

Original EIP · ← EIPs