diff --git a/src/engine/shanghai.md b/src/engine/shanghai.md index 19e6b0f1e..8c228f1db 100644 --- a/src/engine/shanghai.md +++ b/src/engine/shanghai.md @@ -10,6 +10,7 @@ Engine API changes introduced in Shanghai. - [Structures](#structures) - [WithdrawalV1](#withdrawalv1) - [ExecutionPayloadV2](#executionpayloadv2) + - [ExecutionPayloadBodyV1](#executionpayloadbodyv1) - [PayloadAttributesV2](#payloadattributesv2) - [Methods](#methods) - [engine_newPayloadV2](#engine_newpayloadv2) @@ -24,6 +25,14 @@ Engine API changes introduced in Shanghai. - [Request](#request-2) - [Response](#response-2) - [Specification](#specification-2) + - [engine_getPayloadBodiesByHashV1](#engine_getpayloadbodiesbyhashv1) + - [Request](#request-3) + - [Response](#response-3) + - [Specification](#specification-3) + - [engine_getPayloadBodiesByRangeV1](#engine_getpayloadbodiesbyrangev1) + - [Request](#request-4) + - [Response](#response-4) + - [Specification](#specification-4) @@ -62,6 +71,11 @@ This structure has the syntax of `ExecutionPayloadV1` and appends a single field - `transactions`: `Array of DATA` - Array of transaction objects, each object is a byte list (`DATA`) representing `TransactionType || TransactionPayload` or `LegacyTransaction` as defined in [EIP-2718](https://eips.ethereum.org/EIPS/eip-2718) - `withdrawals`: `Array of WithdrawalV1` - Array of withdrawals, each object is an `OBJECT` containing the fields of a `WithdrawalV1` structure. +### ExecutionPayloadBodyV1 +This structure contains a body of an execution payload. The fields are encoded as follows: +- `transactions`: `Array of DATA` - Array of transaction objects, each object is a byte list (`DATA`) representing `TransactionType || TransactionPayload` or `LegacyTransaction` as defined in [EIP-2718](https://eips.ethereum.org/EIPS/eip-2718) +- `withdrawals`: `Array of WithdrawalV1` - Array of withdrawals, each object is an `OBJECT` containing the fields of a `WithdrawalV1` structure. + ### PayloadAttributesV2 This structure has the syntax of `PayloadAttributesV1` and appends a single field: `withdrawals`. @@ -146,3 +160,66 @@ This method follows the same specification as [`engine_forkchoiceUpdatedV1`](./p This method follows the same specification as [`engine_getPayloadV1`](./paris.md#engine_getpayloadv1) with the addition of the following: 1. Client software **SHOULD** use the sum of the block's priority fees or any other algorithm to determine `blockValue`. + +### engine_getPayloadBodiesByHashV1 + +#### Request + +* method: `engine_getPayloadBodiesByHashV1` +* params: + 1. `Array of DATA`, 32 Bytes - Array of `block_hash` field values of the `ExecutionPayload` structure +* timeout: 10s + +#### Response + +* result: `Array of ExecutionPayloadBodyV1` - Array of [`ExecutionPayloadBodyV1`](#ExecutionPayloadBodyV1) objects. +* error: code and message set in case an exception happens while processing the method call. + +#### Specification + +1. Given array of block hashes client software **MUST** respond with array of `ExecutionPayloadBodyV1` objects with the corresponding hashes respecting the order of block hashes in the input array. + +1. Client software **MUST** place responses in the order given in the request, using `null` for any missing blocks. For instance, if the request is `[A.block_hash, B.block_hash, C.block_hash]` and client software has data of payloads `A` and `C`, but doesn't have data of `B`, the response **MUST** be `[A.body, null, C.body]`. + +1. Client software **MAY NOT** respond to requests for finalized blocks by hash. + +1. Client software **MUST** set `withdrawals` field to `null` for bodies of pre-Shanghai blocks. + +1. This request maps to [`BeaconBlocksByRoot`](https://github.com/ethereum/consensus-specs/blob/dev/specs/phase0/p2p-interface.md#beaconblocksbyroot) in the consensus layer `p2p` specification. Callers must be careful to use the execution block hash, instead of the beacon block root. + +### engine_getPayloadBodiesByRangeV1 + +#### Request + +* method: `engine_getPayloadBodiesByRangeV1` +* params: + 1. `start`: `QUANTITY`, 64 bits - Starting block number + 1. `count`: `QUANITTY`, 64 bits - Number of blocks to return +* timeout: 10s + +#### Response + +* result: `Array of ExecutionPayloadBodyV1` - Array of [`ExecutionPayloadBodyV1`](#ExecutionPayloadBodyV1) objects. +* error: code and message set in case an exception happens while processing the method call. + +#### Specification + +1. Given a `start` and a `count`, the client software **MUST** respond with array of `ExecutionPayloadBodyV1` objects with the corresponding execution block number respecting the order of blocks in the canonical chain, as selected by the latest `engine_forkchoiceUpdated` call. + +1. Client software **MUST** support `count` values of at least 32 blocks. + +1. Client software **MUST** place `null` in the response array for unavailable blocks which numbers are lower than a number of the latest known block. Client software **MUST NOT** return trailing `null` values if the request extends past the current latest known block. Execution Layer client software is expected to download and carry the full block history until EIP-4444 or a similar proposal takes into effect. Consider the following response examples: + * `[B1.body, B2.body, ..., Bn.body]` -- entire requested range is filled with block bodies, + * `[null, null, B3.body, ..., Bn.body]` -- first two blocks are unavailable (either pruned or not yet downloaded), + * `[null, null, ..., null]` -- requested range is behind the latest known block and all blocks are unavailable, + * `[B1.body, B2.body, B3.body, B4.body]` -- `B4` is the latest known block and trailing `null` values are trimmed, + * `[]` -- entire requested range is beyond the latest known block, + * `[null, null, B3.body, B4.body]` -- first two blocks are unavailable, `B4` is the latest known block. + +1. Client software **MUST** set `withdrawals` field to `null` for bodies of pre-Shanghai blocks. + +1. This request maps to [`BeaconBlocksByRange`](https://github.com/ethereum/consensus-specs/blob/dev/specs/phase0/p2p-interface.md#beaconblocksbyrange) in the consensus layer `p2p` specification. + +1. Callers must be careful to not confuse `start` with a slot number, instead mapping the slot to a block number. Callers must also be careful to request non-finalized blocks by hash in order to avoid race conditions around the current view of the canonical chain. + +1. Callers must be careful to verify the hash of the received blocks when requesting non-finalized parts of the chain since the response is prone to being re-orged. diff --git a/wordlist.txt b/wordlist.txt index 5ff2b089b..bc03ceac9 100644 --- a/wordlist.txt +++ b/wordlist.txt @@ -1,5 +1,8 @@ apis attributesv +bodyv +bodiesbyrangev +bodiesbyhashv bytecode configurationv crypto