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
- The CL and EL exchange all Engine API communication using text-based JSON-RPC
- Binary data is converted into hexadecimal strings before being sent, doubling the transport size
- The CL repeatedly converts SSZ to JSON and then back to the internal format
After EIP-8178
- A transport method that sends and receives SSZ bytes directly over HTTP REST is added on the same port
- Removing hexadecimal encoding and JSON parsing reduces transport size by about 50%
- The existing JSON-RPC is fully retained, so clients that don't implement the new transport are unaffected
Who is affected
- Client teams: EL and CL clients are the parties that implement the new transport. Since there is no consensus change, it is a purely client-side change and can be shipped as a regular release without a hard fork.
- Validators and node operators: It reuses the same JWT secret as the existing Engine API port (8551), so no additional port or firewall configuration is needed. The serialization burden on the block validation path is reduced.
- Ordinary users: The protocol rules themselves do not change, so there is no change directly felt by users. This is a change that improves communication efficiency inside the node.
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.