EIP-8178 - Binary SSZ Transport for the Engine API

Abstract

This EIP specifies a binary SSZ transport for Engine API communication between consensus layer (CL) and execution layer (EL) clients. The binary transport replaces JSON-RPC with resource-oriented REST endpoints and raw SSZ encoding for fast, efficient CL-EL communication. SSZ container definitions are provided for all Engine API structures and methods across all forks for backwards compatibility.

Motivation

Fast communication between the consensus layer and execution layer is critical for block propagation and validation timing. The JSON-RPC transport introduces unnecessary overhead in this critical path:

• Binary data (hashes, addresses, transactions, blobs) is hex-encoded, doubling wire size.
• JSON parsing and generation adds CPU overhead on both sides.
• The CL uses SSZ natively, forcing a round-trip conversion (SSZ → JSON, then JSON → internal types) at the Engine API boundary.

Binary SSZ eliminates all of this. The CL sends raw SSZ bytes over HTTP; the EL deserializes directly. No hex encoding, no JSON parsing, no intermediate representations. Payload sizes are reduced by ~50% compared to JSON-RPC, and serialization is no longer a bottleneck in the critical path between CL and EL.

Specification

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 and RFC 8174.

Transport

The binary SSZ transport uses resource-oriented REST over HTTP. Endpoints are organized by resource type (payloads, forkchoice, blobs) with per-endpoint versioning, following the same conventions as the Beacon API.

Base URL

All endpoints are served under the /engine prefix on the existing Engine API port (default 8551):

http://localhost:8551/engine

Content Types

Request bodies are the SSZ serialization of the endpoint's request container. Response bodies are the SSZ serialization of the endpoint's response type. GET requests with no body SHOULD include the Accept header to indicate SSZ preference.

Authentication

The binary transport uses the same JWT authentication as the JSON-RPC endpoint. All requests MUST include a valid JWT bearer token in the Authorization header:

Authorization: Bearer <JWT token>

All existing authentication requirements from the Engine API specification apply.

Versioning

Endpoints use path-based versioning following Beacon API conventions. Each endpoint includes a version number in its path (e.g., /engine/v5/payloads). The version number corresponds to the JSON-RPC method version it replaces:

When a new fork introduces a new method version, a new versioned endpoint is added. Older versioned endpoints MAY be deprecated but SHOULD remain available for backwards compatibility.

HTTP Status Codes

Success

Client Errors

Server Errors

Error responses use Content-Type: text/plain with a human-readable error message body.

Constants

SSZ Type Mappings

Each JSON-encoded base type used in the Engine API maps to a specific SSZ type:

Nullable types are represented as List[T, 1] in SSZ encoding. An empty list (0 elements) denotes absence (null). A list with one element denotes presence.

Container Definitions

WithdrawalV1

class WithdrawalV1(Container):
    index: uint64
    validator_index: uint64
    address: Bytes20
    amount: uint64

ExecutionPayloadV1

class ExecutionPayloadV1(Container):
    parent_hash: Bytes32
    fee_recipient: Bytes20
    state_root: Bytes32
    receipts_root: Bytes32
    logs_bloom: ByteVector[BYTES_PER_LOGS_BLOOM]
    prev_randao: Bytes32
    block_number: uint64
    gas_limit: uint64
    gas_used: uint64
    timestamp: uint64
    extra_data: ByteList[MAX_EXTRA_DATA_BYTES]
    base_fee_per_gas: uint256
    block_hash: Bytes32
    transactions: List[ByteList[MAX_BYTES_PER_TRANSACTION], MAX_TRANSACTIONS_PER_PAYLOAD]

ExecutionPayloadV2

Extends ExecutionPayloadV1 with withdrawals.

class ExecutionPayloadV2(Container):
    parent_hash: Bytes32
    fee_recipient: Bytes20
    state_root: Bytes32
    receipts_root: Bytes32
    logs_bloom: ByteVector[BYTES_PER_LOGS_BLOOM]
    prev_randao: Bytes32
    block_number: uint64
    gas_limit: uint64
    gas_used: uint64
    timestamp: uint64
    extra_data: ByteList[MAX_EXTRA_DATA_BYTES]
    base_fee_per_gas: uint256
    block_hash: Bytes32
    transactions: List[ByteList[MAX_BYTES_PER_TRANSACTION], MAX_TRANSACTIONS_PER_PAYLOAD]
    withdrawals: List[WithdrawalV1, MAX_WITHDRAWALS_PER_PAYLOAD]

ExecutionPayloadV3

Extends ExecutionPayloadV2 with blob_gas_used and excess_blob_gas.

class ExecutionPayloadV3(Container):
    parent_hash: Bytes32
    fee_recipient: Bytes20
    state_root: Bytes32
    receipts_root: Bytes32
    logs_bloom: ByteVector[BYTES_PER_LOGS_BLOOM]
    prev_randao: Bytes32
    block_number: uint64
    gas_limit: uint64
    gas_used: uint64
    timestamp: uint64
    extra_data: ByteList[MAX_EXTRA_DATA_BYTES]
    base_fee_per_gas: uint256
    block_hash: Bytes32
    transactions: List[ByteList[MAX_BYTES_PER_TRANSACTION], MAX_TRANSACTIONS_PER_PAYLOAD]
    withdrawals: List[WithdrawalV1, MAX_WITHDRAWALS_PER_PAYLOAD]
    blob_gas_used: uint64
    excess_blob_gas: uint64

PayloadStatusV1

The status field is encoded as a uint8 enum.

class PayloadStatusV1(Container):
    status: uint8
    latest_valid_hash: Bytes32
    validation_error: ByteList[MAX_ERROR_MESSAGE_LENGTH]

Note: latest_valid_hash is all zeros when absent (e.g. when status is SYNCING or ACCEPTED). validation_error is empty when absent.

ForkchoiceStateV1

class ForkchoiceStateV1(Container):
    head_block_hash: Bytes32
    safe_block_hash: Bytes32
    finalized_block_hash: Bytes32

PayloadAttributesV1

class PayloadAttributesV1(Container):
    timestamp: uint64
    prev_randao: Bytes32
    suggested_fee_recipient: Bytes20

PayloadAttributesV2

Extends PayloadAttributesV1 with withdrawals.

class PayloadAttributesV2(Container):
    timestamp: uint64
    prev_randao: Bytes32
    suggested_fee_recipient: Bytes20
    withdrawals: List[WithdrawalV1, MAX_WITHDRAWALS_PER_PAYLOAD]

PayloadAttributesV3

Extends PayloadAttributesV2 with parent_beacon_block_root.

class PayloadAttributesV3(Container):
    timestamp: uint64
    prev_randao: Bytes32
    suggested_fee_recipient: Bytes20
    withdrawals: List[WithdrawalV1, MAX_WITHDRAWALS_PER_PAYLOAD]
    parent_beacon_block_root: Bytes32

ForkchoiceUpdatedResponseV1

Used by all versions of engine_forkchoiceUpdated.

class ForkchoiceUpdatedResponseV1(Container):
    payload_status: PayloadStatusV1
    payload_id: Bytes8

Note: payload_id is all zeros when no payload building was initiated.

ExecutionPayloadBodyV1

class ExecutionPayloadBodyV1(Container):
    transactions: List[ByteList[MAX_BYTES_PER_TRANSACTION], MAX_TRANSACTIONS_PER_PAYLOAD]
    withdrawals: List[WithdrawalV1, MAX_WITHDRAWALS_PER_PAYLOAD]

Note: withdrawals is empty for pre-Shanghai blocks.

BlobsBundleV1

class BlobsBundleV1(Container):
    commitments: List[Bytes48, MAX_BLOB_COMMITMENTS_PER_BLOCK]
    proofs: List[Bytes48, MAX_BLOB_COMMITMENTS_PER_BLOCK]
    blobs: List[ByteVector[BLOB_SIZE], MAX_BLOB_COMMITMENTS_PER_BLOCK]

BlobsBundleV2

Proofs are cell proofs with CELLS_PER_EXT_BLOB proofs per blob.

class BlobsBundleV2(Container):
    commitments: List[Bytes48, MAX_BLOB_COMMITMENTS_PER_BLOCK]
    proofs: List[Bytes48, MAX_BLOB_COMMITMENTS_PER_BLOCK * CELLS_PER_EXT_BLOB]
    blobs: List[ByteVector[BLOB_SIZE], MAX_BLOB_COMMITMENTS_PER_BLOCK]

BlobAndProofV1

class BlobAndProofV1(Container):
    blob: ByteVector[BLOB_SIZE]
    proof: Bytes48

BlobAndProofV2

class BlobAndProofV2(Container):
    blob: ByteVector[BLOB_SIZE]
    proofs: List[Bytes48, CELLS_PER_EXT_BLOB]

TransitionConfigurationV1

Deprecated in Cancun.

class TransitionConfigurationV1(Container):
    terminal_total_difficulty: uint256
    terminal_block_hash: Bytes32
    terminal_block_number: uint64

GetPayloadResponseV2

class GetPayloadResponseV2(Container):
    execution_payload: ExecutionPayloadV2
    block_value: uint256

Note: Pre-Shanghai payloads have an empty withdrawals list.

GetPayloadResponseV3

class GetPayloadResponseV3(Container):
    execution_payload: ExecutionPayloadV3
    block_value: uint256
    blobs_bundle: BlobsBundleV1
    should_override_builder: boolean

GetPayloadResponseV4

class GetPayloadResponseV4(Container):
    execution_payload: ExecutionPayloadV3
    block_value: uint256
    blobs_bundle: BlobsBundleV1
    should_override_builder: boolean
    execution_requests: List[ByteList[MAX_BYTES_PER_TRANSACTION], MAX_EXECUTION_REQUESTS]

GetPayloadResponseV5

class GetPayloadResponseV5(Container):
    execution_payload: ExecutionPayloadV3
    block_value: uint256
    blobs_bundle: BlobsBundleV2
    should_override_builder: boolean
    execution_requests: List[ByteList[MAX_BYTES_PER_TRANSACTION], MAX_EXECUTION_REQUESTS]

PayloadBodiesV1Response

class PayloadBodiesV1Response(Container):
    payload_bodies: List[List[ExecutionPayloadBodyV1, 1], MAX_PAYLOAD_BODIES_REQUEST]

Note: Each inner list has 0 elements for unknown blocks and 1 element for known blocks.

GetBlobsV1Response

class GetBlobsV1Response(Container):
    blobs_and_proofs: List[BlobAndProofV1, MAX_BLOB_HASHES_REQUEST]

GetBlobsV2Response

class GetBlobsV2Response(Container):
    blobs_and_proofs: List[BlobAndProofV2, MAX_BLOB_HASHES_REQUEST]

GetBlobsV3Response

class GetBlobsV3Response(Container):
    blobs_and_proofs: List[List[BlobAndProofV2, 1], MAX_BLOB_HASHES_REQUEST]

Note: Each inner list has 0 elements for a missing blob and 1 element for a present blob.

ClientVersionV1

class ClientVersionV1(Container):
    code: ByteList[MAX_CLIENT_CODE_LENGTH]
    name: ByteList[MAX_CLIENT_NAME_LENGTH]
    version: ByteList[MAX_CLIENT_VERSION_LENGTH]
    commit: Bytes4

GetClientVersionV1Response

class GetClientVersionV1Response(Container):
    versions: List[ClientVersionV1, MAX_CLIENT_VERSIONS]

Endpoints

All endpoints use Content-Type: application/octet-stream for request and response bodies containing SSZ-encoded data. Error responses use Content-Type: text/plain.

Payloads

POST /engine/v{N}/payloads — Submit execution payload

Submit an execution payload for validation. The EL validates the payload and returns its status.

Request containers:

class NewPayloadV1Request(Container):
    execution_payload: ExecutionPayloadV1

class NewPayloadV2Request(Container):
    execution_payload: ExecutionPayloadV2

class NewPayloadV3Request(Container):
    execution_payload: ExecutionPayloadV3
    expected_blob_versioned_hashes: List[Bytes32, MAX_BLOB_COMMITMENTS_PER_BLOCK]
    parent_beacon_block_root: Bytes32

class NewPayloadV4Request(Container):
    execution_payload: ExecutionPayloadV3
    expected_blob_versioned_hashes: List[Bytes32, MAX_BLOB_COMMITMENTS_PER_BLOCK]
    parent_beacon_block_root: Bytes32
    execution_requests: List[ByteList[MAX_BYTES_PER_TRANSACTION], MAX_EXECUTION_REQUESTS]

Response: 200 OK — PayloadStatusV1

GET /engine/v{N}/payloads/{payload_id} — Retrieve built payload

Retrieve an execution payload previously requested via forkchoice update with payload attributes. The {payload_id} path parameter is the hex-encoded Bytes8 payload identifier (e.g., 0x1234567890abcdef).

Request: No body. The payload ID is in the URL path.

Response: 200 OK — SSZ-encoded response type from the table above.

POST /engine/v{N}/payloads/bodies/by-hash — Get payload bodies by hash

Retrieve execution payload bodies for a list of block hashes.

Request container:

class GetPayloadBodiesByHashRequest(Container):
    block_hashes: List[Bytes32, MAX_PAYLOAD_BODIES_REQUEST]

Response: 200 OK — PayloadBodiesV1Response

POST /engine/v{N}/payloads/bodies/by-range — Get payload bodies by range

Retrieve execution payload bodies for a contiguous range of block numbers.

Request container:

class GetPayloadBodiesByRangeRequest(Container):
    start: uint64
    count: uint64

Response: 200 OK — PayloadBodiesV1Response

Forkchoice

POST /engine/v{N}/forkchoice — Update fork choice

Update the EL's fork choice state and optionally start building a new payload.

Request containers:

class ForkchoiceUpdatedV1Request(Container):
    forkchoice_state: ForkchoiceStateV1
    payload_attributes: List[PayloadAttributesV1, 1]

class ForkchoiceUpdatedV2Request(Container):
    forkchoice_state: ForkchoiceStateV1
    payload_attributes: List[PayloadAttributesV2, 1]

class ForkchoiceUpdatedV3Request(Container):
    forkchoice_state: ForkchoiceStateV1
    payload_attributes: List[PayloadAttributesV3, 1]

Response: 200 OK — ForkchoiceUpdatedResponseV1

Blobs

POST /engine/v{N}/blobs — Get blobs by versioned hash

Retrieve blobs from the EL's blob pool by their versioned hashes.

Request container:

class GetBlobsRequest(Container):
    blob_versioned_hashes: List[Bytes32, MAX_BLOB_HASHES_REQUEST]

Response: 200 OK — SSZ-encoded response type from the table above, or 204 No Content when the EL is syncing.

Client

POST /engine/v1/client/version — Exchange client version

Exchange client version information between CL and EL.

Request container:

class GetClientVersionV1Request(Container):
    client_version: ClientVersionV1

Response: 200 OK — GetClientVersionV1Response

Endpoint Summary

Example

Submit payload

curl -X POST http://localhost:8551/engine/v4/payloads \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/octet-stream" \
  -H "Accept: application/octet-stream" \
  --data-binary @new_payload_request.ssz \
  -o payload_status.ssz

Retrieve built payload

curl -X GET http://localhost:8551/engine/v4/payloads/0x1234567890abcdef \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Accept: application/octet-stream" \
  -o get_payload_response.ssz

Update fork choice

curl -X POST http://localhost:8551/engine/v3/forkchoice \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @forkchoice_request.ssz \
  -o forkchoice_response.ssz

Rationale

Why REST instead of raw SSZ over TCP?

REST is well understood, easy to debug, and infrastructure already exists for it (load balancers, proxies, monitoring). The Beacon API already uses REST with SSZ and it works well. Going lower level (raw TCP, custom framing) adds complexity without a clear benefit for the EL-CL link, which is typically localhost communication.

Why same port instead of a separate port?

Serving both JSON-RPC and SSZ REST on the same port simplifies deployment and configuration. There's no need for operators to manage an additional port, firewall rule, or JWT secret. The two transports coexist cleanly — JSON-RPC uses POST / with Content-Type: application/json, while SSZ REST uses resource-oriented paths with Content-Type: application/octet-stream.

Why application/octet-stream?

This is the standard content type for binary data. The Beacon API already uses it for SSZ responses. It signals that the body is raw bytes, not text, which is exactly what SSZ is.

Why text/plain for errors instead of JSON?

Errors are small, infrequent, and need to be human-readable for debugging. A plain text message body is the simplest possible approach — no parsing needed, just log it. JSON error bodies add complexity for minimal gain.

No hard fork required

This is purely a client-side change. It's a new transport option for an existing API — no consensus changes, no state transition changes, no new opcodes. Clients can implement it whenever they want and roll it out with a regular release.

Backwards Compatibility

This EIP introduces a new transport protocol alongside the existing JSON-RPC Engine API. The JSON-RPC API remains fully functional and is always available. Clients that don't implement binary SSZ are unaffected.

Security Considerations

• The SSZ REST transport uses the same JWT authentication as the JSON-RPC endpoint. All existing authentication requirements apply.
• SSZ deserialization MUST enforce the same size limits as JSON deserialization. Implementations MUST reject SSZ payloads exceeding defined maximum sizes before attempting full deserialization.
• Implementations SHOULD use well-tested SSZ libraries and fuzz test SSZ parsing extensively.
• The {payload_id} path parameter MUST be validated as a well-formed hex-encoded Bytes8 before processing.

Copyright

Copyright and related rights waived via CC0.