Scope
The eth capability serves execution headers, bodies, and receipts. Consensus
clients propagate post-Merge blocks through the consensus network, but
execution peers still provide chain data for synchronization and backfill.
Message inventory
| Request | Response | Result |
|---|---|---|
GetBlockHeaders |
BlockHeaders |
Ordered headers from a number or hash. |
GetBlockBodies |
BlockBodies |
Bodies for requested block hashes. |
GetReceipts |
Receipts |
Receipt lists for requested block hashes. |
Each request and response starts with the same 64-bit request ID.
Header ranges
GetBlockHeaders specifies a start, limit, skip count, and direction. The start
is a block number or hash. The response follows the canonical chain from that
start and returns at most the requested limit.
An empty response means that no requested header was found. The recommended soft response limit is 2 MiB.
Bodies
GetBlockBodies lists block hashes. BlockBodies returns available bodies in
request order and can be empty. The recommended soft response limit is 2 MiB.
A requester checks each body against the transactions root, withdrawals root, and other commitments in its header.
Receipts
The current eth wire versions request an offset into the first block's receipt list:
[request-id, first-block-receipt-index, block-hashes]
The response contains a last-block-incomplete flag and ordered receipt lists.
Only the first list can omit a requested prefix. Only the last list can omit a
suffix, and only when the flag is one.
The requester continues an incomplete last list with another offset request. It checks complete receipt lists against the header receipt root. Partial lists need continuation checks before final root validation: the delivered count must match the block's transaction count, each receipt must stay within its transaction gas-limit bound, and the accumulated receipt size must stay within the block gas-limit bound.
Legacy block announcements
NewBlockHashes and NewBlock remain assigned message IDs. Mainnet no longer
uses them for block propagation after the Merge.
Failure handling
- Match every response to a pending request ID.
- Accept an empty response when the peer lacks the requested data.
- Check response order and block commitments.
- Apply local size limits without changing request semantics.
- Continue a partial receipt list from its exact next index.
- A client may lower local peer reputation when a peer repeatedly announces data and then refuses valid requests.
Design rationale
Headers identify and authenticate the larger body and receipt objects. Separate requests let a syncing node schedule work across peers and avoid duplicate bulk data.
History
eth/66 added request IDs. eth/69 added history-range advertisements and simpler receipt encoding. eth/70 added receipt-list pagination.