From b520e100762fc8156569537e8829c560ae432113 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Toni=20Wahrst=C3=A4tter?= Date: Mon, 22 Dec 2025 14:02:00 +0100 Subject: [PATCH 1/5] Update EIP-7928 define engine api methods --- docs/reference/quickstart.md | 7 +- src/engine/amsterdam.md | 73 ++++++++++++++++++++ src/engine/openrpc/methods/capabilities.yaml | 4 ++ src/engine/openrpc/methods/payload.yaml | 68 ++++++++++++++++++ src/engine/openrpc/schemas/payload.yaml | 8 +++ 5 files changed, 156 insertions(+), 4 deletions(-) diff --git a/docs/reference/quickstart.md b/docs/reference/quickstart.md index 945ba004f..01b4fb381 100644 --- a/docs/reference/quickstart.md +++ b/docs/reference/quickstart.md @@ -131,7 +131,7 @@ $ npm run graphql:validate ## License -This repository is licensed under [CC0][license]. +This repository is licensed under [CC0](LICENSE). [playground]: https://ethereum.github.io/execution-apis/api-documentation/ @@ -139,9 +139,8 @@ This repository is licensed under [CC0][license]. [validator]: https://open-rpc.github.io/schema-utils-js/functions/validateOpenRPCDocument.html [graphql-schema]: http://graphql-schema.ethdevops.io/?url=https://raw.githubusercontent.com/ethereum/execution-apis/main/graphql.json [eip-1767]: https://eips.ethereum.org/EIPS/eip-1767 -[contributors-guide]: ../contributors-guide +[contributors-guide]: docs/reference/contributors-guide.md [json-schema]: https://json-schema.org [hive]: https://github.com/ethereum/hive [rpc-compat]: https://github.com/ethereum/hive/tree/master/simulators/ethereum/rpc-compat -[test-gen]: ../tests -[license]: https://github.com/ethereum/execution-apis/blob/main/LICENSE +[test-gen]: docs/reference/tests.md diff --git a/src/engine/amsterdam.md b/src/engine/amsterdam.md index cc4613fc7..ef020eda7 100644 --- a/src/engine/amsterdam.md +++ b/src/engine/amsterdam.md @@ -20,6 +20,14 @@ This specification is based on and extends [Engine API - Osaka](./osaka.md) spec - [Request](#request-1) - [Response](#response-1) - [Specification](#specification-1) + - [engine_getBlockAccessListsByHashV1](#engine_getbalsbyhashv1) + - [Request](#request-2) + - [Response](#response-2) + - [Specification](#specification-2) + - [engine_getBlockAccessListsByRangeV1](#engine_getbalsbyrangev1) + - [Request](#request-3) + - [Response](#response-3) + - [Specification](#specification-3) - [Update the methods of previous forks](#update-the-methods-of-previous-forks) - [Osaka API](#osaka-api) @@ -109,6 +117,71 @@ This method follows the same specification as [`engine_getPayloadV5`](./osaka.md 2. When building the block, client software **MUST** collect all account accesses and state changes during transaction execution and populate the `blockAccessList` field in the returned `ExecutionPayloadV4` with the RLP-encoded access list. +### engine_getBlockAccessListsByHashV1 + +This method retrieves RLP-encoded block access lists for specified blocks. + +#### Request + +* method: `engine_getBlockAccessListsByHashV1` +* params: + 1. `blockHashes`: `Array of DATA`, 32 Bytes - Array of block hashes to retrieve block access lists for +* timeout: 10s + +#### Response + +* result: `Array` - Array of block access list body objects or `null` for blocks without block access lists + - `blockAccessList`: `DATA` - RLP-encoded block access list as defined in EIP-7928, or `null` if unavailable +* error: code and message set in case an exception happens while getting the block access lists. + +#### Specification + +1. Client software **MUST** return an array of the same length as the input array. + +2. Client software **MUST** place responses in the same order as the corresponding block hashes in the input array. + +3. Client software **MUST** return `null` for any block hash that: + - Is unknown or unavailable + - Predates the Amsterdam fork activation + - Has been pruned from storage + +4. Client software **MUST** return `-38004: Too large request` error if the requested range is too large. + +5. Client software **MUST** retain block access lists for at least 3533 epochs (the weak subjectivity period) to support synchronization with re-execution. + +### engine_getBlockAccessListsByRangeV1 + +This method retrieves RLP-encoded block access lists for a range of blocks. + +#### Request + +* method: `engine_getBlockAccessListsByRangeV1` +* params: + 1. `start`: `QUANTITY`, 64 Bits - Starting block number + 2. `count`: `QUANTITY`, 64 Bits - Number of blocks to retrieve block access lists for +* timeout: 10s + +#### Response + +* result: `Array` - Array of block access list body objects or `null` for blocks without block access lists + - `blockAccessList`: `DATA` - RLP-encoded block access list as defined in EIP-7928, or `null` if unavailable +* error: code and message set in case an exception happens while getting the block access lists. + +#### Specification + +1. Client software **MUST** return block access lists for the range `[start, start + count)`. + +2. Client software **MUST** return an array of length equal to `count` or less if the range extends beyond the current head. + +3. Client software **MUST** return `null` for any block in the range that: + - Has not been processed yet + - Predates the Amsterdam fork activation + - Has been pruned from storage + +4. Client software **MUST** return `-38004: Too large request` error if the requested range is too large. + +5. Client software **MUST** retain block access lists for at least 3533 epochs (the weak subjectivity period) to support synchronization with re-execution. + ### Update the methods of previous forks #### Osaka API diff --git a/src/engine/openrpc/methods/capabilities.yaml b/src/engine/openrpc/methods/capabilities.yaml index 17dae9346..9a48bbd74 100644 --- a/src/engine/openrpc/methods/capabilities.yaml +++ b/src/engine/openrpc/methods/capabilities.yaml @@ -25,6 +25,8 @@ - 'engine_forkchoiceUpdatedV1' - 'engine_getPayloadBodiesByHashV1' - 'engine_getPayloadBodiesByRangeV1' + - 'engine_getBlockAccessListsByHashV1' + - 'engine_getBlockAccessListsByRangeV1' - 'engine_getPayloadV1' - 'engine_newPayloadV1' result: @@ -40,3 +42,5 @@ - 'engine_exchangeTransitionConfigurationV1' - 'engine_getPayloadBodiesByHashV1' - 'engine_getPayloadBodiesByRangeV1' + - 'engine_getBlockAccessListsByHashV1' + - 'engine_getBlockAccessListsByRangeV1' diff --git a/src/engine/openrpc/methods/payload.yaml b/src/engine/openrpc/methods/payload.yaml index 01e267c74..1bb9f817b 100644 --- a/src/engine/openrpc/methods/payload.yaml +++ b/src/engine/openrpc/methods/payload.yaml @@ -886,6 +886,74 @@ validatorIndex: '0xf3' address: '0x00000000000000000000000000000000000010f3' amount: '0x1' +- name: engine_getBlockAccessListsByHashV1 + summary: Given block hashes returns RLP-encoded block access lists of the corresponding execution payloads + externalDocs: + description: Method specification + url: https://github.com/ethereum/execution-apis/blob/main/src/engine/amsterdam.md#engine_getblockaccesslistsbyhashv1 + params: + - name: Array of block hashes + required: true + schema: + type: array + items: + $ref: '#/components/schemas/hash32' + result: + name: Block access list bodies + schema: + type: array + items: + $ref: '#/components/schemas/BlockAccessListBodyV1' + errors: + - code: -38004 + message: Too large request + examples: + - name: engine_getBlockAccessListsByHashV1 example + params: + - name: Array of block hashes + value: + - '0xd5f1812548be429cbdc6376b29611fc49e06f1359758c4ceaaa3b393e2239f9c' + - '0xfe88c94d860f01a17f961bf4bdfb6e0c6cd10d3fda5cc861e805ca1240c58553' + result: + name: Block access list bodies + value: + - blockAccessList: '0xf8daf8d8f8d6a000000000000000000000000000000000000000000000000000000000000000a0f8a7a02222222222222222222222222222222222222222222222222222222222222222a03333333333333333333333333333333333333333333333333333333333333333a04444444444444444444444444444444444444444444444444444444444444444' + - null +- name: engine_getBlockAccessListsByRangeV1 + summary: Given a range of block numbers returns RLP-encoded block access lists of the corresponding execution payloads + externalDocs: + description: Method specification + url: https://github.com/ethereum/execution-apis/blob/main/src/engine/amsterdam.md#engine_getblockaccesslistsbyrangev1 + params: + - name: Starting block number + required: true + schema: + $ref: '#/components/schemas/uint64' + - name: Number of blocks to return + required: true + schema: + $ref: '#/components/schemas/uint64' + result: + name: Block access list bodies + schema: + type: array + items: + $ref: '#/components/schemas/BlockAccessListBodyV1' + errors: + - code: -38004 + message: Too large request + examples: + - name: engine_getBlockAccessListsByRangeV1 example + params: + - name: Starting block number + value: '0x20' + - name: Number of blocks to return + value: '0x2' + result: + name: Block access list bodies + value: + - null + - blockAccessList: '0xf8daf8d8f8d6a000000000000000000000000000000000000000000000000000000000000000a0f8a7a05555555555555555555555555555555555555555555555555555555555555555a06666666666666666666666666666666666666666666666666666666666666666a07777777777777777777777777777777777777777777777777777777777777777' - name: engine_newPayloadV5 summary: Runs execution payload validation externalDocs: diff --git a/src/engine/openrpc/schemas/payload.yaml b/src/engine/openrpc/schemas/payload.yaml index 7252f8f8b..631f6679c 100644 --- a/src/engine/openrpc/schemas/payload.yaml +++ b/src/engine/openrpc/schemas/payload.yaml @@ -318,6 +318,14 @@ ExecutionPayloadBodyV1: - 'null' items: $ref: '#/components/schemas/WithdrawalV1' +BlockAccessListBodyV1: + title: Block access list body object V1 + type: object + properties: + blockAccessList: + title: Block access list + description: RLP-encoded block access list as defined in EIP-7928 + $ref: '#/components/schemas/bytes' BlobsBundleV1: title: Blobs bundle object V1 type: object From 3b81935c2c3562c2d230515f077cb20b5d8ca3e3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Toni=20Wahrst=C3=A4tter?= Date: Mon, 22 Dec 2025 14:14:01 +0100 Subject: [PATCH 2/5] Update wordlist --- wordlist.txt | 90 ++++++++++++++++++++++++++++------------------------ 1 file changed, 49 insertions(+), 41 deletions(-) diff --git a/wordlist.txt b/wordlist.txt index cf5f76c62..6f216f3e9 100644 --- a/wordlist.txt +++ b/wordlist.txt @@ -1,82 +1,90 @@ apis attributesv -bodyv -bodiesbyrangev +besu +blobandproofv +blobsbundlev +blockaccesslist +blockAccessList +BlockAccessList +blockaccesslistbodyv +BlockAccessListBodyV bodiesbyhashv +bodiesbyrangev +bodyv bytecode +CL +cli clientversionv +CLs configurationv crypto +DocToc eg eip +eips +EIPS +EL endian enum +EOA +EOA's +ERC +erigon eth ethereum ethereumjs -erigon -getclientversionv +EVM +exitv +feeRecipient +forkchoiceupdatedresponsev +getblobsbundlev getblobsv +getblockaccesslistsbyhashv +getBlockAccessListsByHashV +getblockaccesslistsbyrangev +getBlockAccessListsByRangeV +getclientversionv +graphql +gwei +https interop +ipc js json +JWT +kzg mempool merkle +multicallV npm ommers openrpc params pos pre +prevrandao pyspelling +randao rlp rpc schemas secp +sha +simulateV +src +ssz statev statusv -sha teku +txs uint updatedv url +UX validator +VM wei +withdrawalv +WS yaml yParity -eips -EIPS -EL -CL -CLs -JWT -WS -ipc -cli -blobsbundlev -getblobsbundlev -blobandproofv -ssz -kzg -besu -graphql -gwei -withdrawalv -DocToc -prevrandao -randao -src -https -forkchoiceupdatedresponsev -feeRecipient -multicallV -EOA -EOA's -EVM -ERC -VM -exitv -txs -UX -simulateV -EOA's From b04c6ede70f769f7fb42da5216458b624f6b384a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Toni=20Wahrst=C3=A4tter?= Date: Wed, 21 Jan 2026 19:44:31 +0100 Subject: [PATCH 3/5] move bal into engine_getPayloadBodiesBy response --- src/engine/amsterdam.md | 65 ++++++++++---------- src/engine/openrpc/methods/capabilities.yaml | 8 +-- src/engine/openrpc/methods/payload.yaml | 64 +++++++++++++------ src/engine/openrpc/schemas/payload.yaml | 21 +++++-- wordlist.txt | 6 -- 5 files changed, 98 insertions(+), 66 deletions(-) diff --git a/src/engine/amsterdam.md b/src/engine/amsterdam.md index ef020eda7..23442a5cc 100644 --- a/src/engine/amsterdam.md +++ b/src/engine/amsterdam.md @@ -11,6 +11,7 @@ This specification is based on and extends [Engine API - Osaka](./osaka.md) spec - [Structures](#structures) - [ExecutionPayloadV4](#executionpayloadv4) + - [ExecutionPayloadBodyV2](#executionpayloadbodyv2) - [Methods](#methods) - [engine_newPayloadV5](#engine_newpayloadv5) - [Request](#request) @@ -20,11 +21,11 @@ This specification is based on and extends [Engine API - Osaka](./osaka.md) spec - [Request](#request-1) - [Response](#response-1) - [Specification](#specification-1) - - [engine_getBlockAccessListsByHashV1](#engine_getbalsbyhashv1) + - [engine_getPayloadBodiesByHashV2](#engine_getpayloadbodiesbyhashv2) - [Request](#request-2) - [Response](#response-2) - [Specification](#specification-2) - - [engine_getBlockAccessListsByRangeV1](#engine_getbalsbyrangev1) + - [engine_getPayloadBodiesByRangeV2](#engine_getpayloadbodiesbyrangev2) - [Request](#request-3) - [Response](#response-3) - [Specification](#specification-3) @@ -58,6 +59,14 @@ This structure has the syntax of [`ExecutionPayloadV3`](./cancun.md#executionpay - `excessBlobGas`: `QUANTITY`, 64 Bits - `blockAccessList`: `DATA` - RLP-encoded block access list as defined in [EIP-7928](https://eips.ethereum.org/EIPS/eip-7928) +### ExecutionPayloadBodyV2 + +This structure has the syntax of [`ExecutionPayloadBodyV1`](./shanghai.md#executionpayloadbodyv1) and appends the new field: `blockAccessList`. + +- `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. Value is `null` for blocks produced before Shanghai. +- `blockAccessList`: `DATA|null` - RLP-encoded block access list as defined in [EIP-7928](https://eips.ethereum.org/EIPS/eip-7928). Value is `null` for blocks produced before Amsterdam or if the data has been pruned. + ## Methods ### engine_newPayloadV5 @@ -117,70 +126,58 @@ This method follows the same specification as [`engine_getPayloadV5`](./osaka.md 2. When building the block, client software **MUST** collect all account accesses and state changes during transaction execution and populate the `blockAccessList` field in the returned `ExecutionPayloadV4` with the RLP-encoded access list. -### engine_getBlockAccessListsByHashV1 +### engine_getPayloadBodiesByHashV2 -This method retrieves RLP-encoded block access lists for specified blocks. +This method retrieves execution payload bodies including block access lists for specified blocks. #### Request -* method: `engine_getBlockAccessListsByHashV1` +* method: `engine_getPayloadBodiesByHashV2` * params: - 1. `blockHashes`: `Array of DATA`, 32 Bytes - Array of block hashes to retrieve block access lists for + 1. `blockHashes`: `Array of DATA`, 32 Bytes - Array of block hashes to retrieve payload bodies for * timeout: 10s #### Response -* result: `Array` - Array of block access list body objects or `null` for blocks without block access lists - - `blockAccessList`: `DATA` - RLP-encoded block access list as defined in EIP-7928, or `null` if unavailable -* error: code and message set in case an exception happens while getting the block access lists. +* result: `Array of ExecutionPayloadBodyV2` - Array of [`ExecutionPayloadBodyV2`](#executionpayloadbodyv2) objects or `null` for blocks that are unavailable +* error: code and message set in case an exception happens while getting the payload bodies. #### Specification -1. Client software **MUST** return an array of the same length as the input array. - -2. Client software **MUST** place responses in the same order as the corresponding block hashes in the input array. +This method follows the same specification as [`engine_getPayloadBodiesByHashV1`](./shanghai.md#engine_getpayloadbodiesbyhashv1) with the following additions: -3. Client software **MUST** return `null` for any block hash that: - - Is unknown or unavailable - - Predates the Amsterdam fork activation - - Has been pruned from storage +1. Client software **MUST** set the `blockAccessList` field to `null` for blocks that predate the Amsterdam fork activation. -4. Client software **MUST** return `-38004: Too large request` error if the requested range is too large. +2. Client software **MUST** set the `blockAccessList` field to `null` if the block access list has been pruned from storage. -5. Client software **MUST** retain block access lists for at least 3533 epochs (the weak subjectivity period) to support synchronization with re-execution. +3. Client software **MUST** retain block access lists for at least 3533 epochs (the weak subjectivity period) to support synchronization with re-execution. -### engine_getBlockAccessListsByRangeV1 +### engine_getPayloadBodiesByRangeV2 -This method retrieves RLP-encoded block access lists for a range of blocks. +This method retrieves execution payload bodies including block access lists for a range of blocks. #### Request -* method: `engine_getBlockAccessListsByRangeV1` +* method: `engine_getPayloadBodiesByRangeV2` * params: 1. `start`: `QUANTITY`, 64 Bits - Starting block number - 2. `count`: `QUANTITY`, 64 Bits - Number of blocks to retrieve block access lists for + 2. `count`: `QUANTITY`, 64 Bits - Number of blocks to retrieve payload bodies for * timeout: 10s #### Response -* result: `Array` - Array of block access list body objects or `null` for blocks without block access lists - - `blockAccessList`: `DATA` - RLP-encoded block access list as defined in EIP-7928, or `null` if unavailable -* error: code and message set in case an exception happens while getting the block access lists. +* result: `Array of ExecutionPayloadBodyV2` - Array of [`ExecutionPayloadBodyV2`](#executionpayloadbodyv2) objects or `null` for blocks that are unavailable +* error: code and message set in case an exception happens while getting the payload bodies. #### Specification -1. Client software **MUST** return block access lists for the range `[start, start + count)`. - -2. Client software **MUST** return an array of length equal to `count` or less if the range extends beyond the current head. +This method follows the same specification as [`engine_getPayloadBodiesByRangeV1`](./shanghai.md#engine_getpayloadbodiesbyrangev1) with the following additions: -3. Client software **MUST** return `null` for any block in the range that: - - Has not been processed yet - - Predates the Amsterdam fork activation - - Has been pruned from storage +1. Client software **MUST** set the `blockAccessList` field to `null` for blocks that predate the Amsterdam fork activation. -4. Client software **MUST** return `-38004: Too large request` error if the requested range is too large. +2. Client software **MUST** set the `blockAccessList` field to `null` if the block access list has been pruned from storage. -5. Client software **MUST** retain block access lists for at least 3533 epochs (the weak subjectivity period) to support synchronization with re-execution. +3. Client software **MUST** retain block access lists for at least 3533 epochs (the weak subjectivity period) to support synchronization with re-execution. ### Update the methods of previous forks diff --git a/src/engine/openrpc/methods/capabilities.yaml b/src/engine/openrpc/methods/capabilities.yaml index 9a48bbd74..81e4bf3e0 100644 --- a/src/engine/openrpc/methods/capabilities.yaml +++ b/src/engine/openrpc/methods/capabilities.yaml @@ -25,8 +25,8 @@ - 'engine_forkchoiceUpdatedV1' - 'engine_getPayloadBodiesByHashV1' - 'engine_getPayloadBodiesByRangeV1' - - 'engine_getBlockAccessListsByHashV1' - - 'engine_getBlockAccessListsByRangeV1' + - 'engine_getPayloadBodiesByHashV2' + - 'engine_getPayloadBodiesByRangeV2' - 'engine_getPayloadV1' - 'engine_newPayloadV1' result: @@ -42,5 +42,5 @@ - 'engine_exchangeTransitionConfigurationV1' - 'engine_getPayloadBodiesByHashV1' - 'engine_getPayloadBodiesByRangeV1' - - 'engine_getBlockAccessListsByHashV1' - - 'engine_getBlockAccessListsByRangeV1' + - 'engine_getPayloadBodiesByHashV2' + - 'engine_getPayloadBodiesByRangeV2' diff --git a/src/engine/openrpc/methods/payload.yaml b/src/engine/openrpc/methods/payload.yaml index 1bb9f817b..aa0b09d6c 100644 --- a/src/engine/openrpc/methods/payload.yaml +++ b/src/engine/openrpc/methods/payload.yaml @@ -886,11 +886,11 @@ validatorIndex: '0xf3' address: '0x00000000000000000000000000000000000010f3' amount: '0x1' -- name: engine_getBlockAccessListsByHashV1 - summary: Given block hashes returns RLP-encoded block access lists of the corresponding execution payloads +- name: engine_getPayloadBodiesByHashV2 + summary: Given block hashes returns bodies of the corresponding execution payloads including block access lists externalDocs: description: Method specification - url: https://github.com/ethereum/execution-apis/blob/main/src/engine/amsterdam.md#engine_getblockaccesslistsbyhashv1 + url: https://github.com/ethereum/execution-apis/blob/main/src/engine/amsterdam.md#engine_getpayloadbodiesbyhashv2 params: - name: Array of block hashes required: true @@ -899,31 +899,45 @@ items: $ref: '#/components/schemas/hash32' result: - name: Block access list bodies + name: Execution payload bodies schema: type: array items: - $ref: '#/components/schemas/BlockAccessListBodyV1' + $ref: '#/components/schemas/ExecutionPayloadBodyV2' errors: - code: -38004 message: Too large request examples: - - name: engine_getBlockAccessListsByHashV1 example + - name: engine_getPayloadBodiesByHashV2 example params: - name: Array of block hashes value: - '0xd5f1812548be429cbdc6376b29611fc49e06f1359758c4ceaaa3b393e2239f9c' - '0xfe88c94d860f01a17f961bf4bdfb6e0c6cd10d3fda5cc861e805ca1240c58553' result: - name: Block access list bodies + name: Execution payload bodies value: - - blockAccessList: '0xf8daf8d8f8d6a000000000000000000000000000000000000000000000000000000000000000a0f8a7a02222222222222222222222222222222222222222222222222222222222222222a03333333333333333333333333333333333333333333333333333333333333333a04444444444444444444444444444444444444444444444444444444444444444' - - null -- name: engine_getBlockAccessListsByRangeV1 - summary: Given a range of block numbers returns RLP-encoded block access lists of the corresponding execution payloads + - transactions: + - '0xf865808506fc23ac00830124f8940101010101010101010101010101010101010101018031a02c4d88bfdc2f6dbf82c33d235c4e785e9fc23b2d0fc7b9d20fc5e9674f1f9d15a016d6d69b925cf26128683ab4a096e196fbb1142d6c6d4e8d3481b9bef1bd0f65' + withdrawals: + - index: '0xf0' + validatorIndex: '0xf0' + address: '0x00000000000000000000000000000000000010f0' + amount: '0x1' + blockAccessList: '0xf8daf8d8f8d6a000000000000000000000000000000000000000000000000000000000000000a0f8a7a02222222222222222222222222222222222222222222222222222222222222222a03333333333333333333333333333333333333333333333333333333333333333a04444444444444444444444444444444444444444444444444444444444444444' + - transactions: + - '0xf865108506fc23ac00830124f8940101010101010101010101010101010101010101018031a0d9712a3c40ae85aea4ad1bd95a0b7cc7bd805189a9e2517403b11a00a1530f81a053b53b0267a6dcfe9f9a1652307b396b3e8a65e65707a450e60c92baefdbcfbe' + withdrawals: + - index: '0xf1' + validatorIndex: '0xf1' + address: '0x00000000000000000000000000000000000010f1' + amount: '0x1' + blockAccessList: null +- name: engine_getPayloadBodiesByRangeV2 + summary: Given a range of block numbers returns bodies of the corresponding execution payloads including block access lists externalDocs: description: Method specification - url: https://github.com/ethereum/execution-apis/blob/main/src/engine/amsterdam.md#engine_getblockaccesslistsbyrangev1 + url: https://github.com/ethereum/execution-apis/blob/main/src/engine/amsterdam.md#engine_getpayloadbodiesbyrangev2 params: - name: Starting block number required: true @@ -934,26 +948,40 @@ schema: $ref: '#/components/schemas/uint64' result: - name: Block access list bodies + name: Execution payload bodies schema: type: array items: - $ref: '#/components/schemas/BlockAccessListBodyV1' + $ref: '#/components/schemas/ExecutionPayloadBodyV2' errors: - code: -38004 message: Too large request examples: - - name: engine_getBlockAccessListsByRangeV1 example + - name: engine_getPayloadBodiesByRangeV2 example params: - name: Starting block number value: '0x20' - name: Number of blocks to return value: '0x2' result: - name: Block access list bodies + name: Execution payload bodies value: - - null - - blockAccessList: '0xf8daf8d8f8d6a000000000000000000000000000000000000000000000000000000000000000a0f8a7a05555555555555555555555555555555555555555555555555555555555555555a06666666666666666666666666666666666666666666666666666666666666666a07777777777777777777777777777777777777777777777777777777777777777' + - transactions: + - '0xf865808506fc23ac00830124f8940101010101010101010101010101010101010101018031a02c4d88bfdc2f6dbf82c33d235c4e785e9fc23b2d0fc7b9d20fc5e9674f1f9d15a016d6d69b925cf26128683ab4a096e196fbb1142d6c6d4e8d3481b9bef1bd0f65' + withdrawals: + - index: '0xf0' + validatorIndex: '0xf0' + address: '0x00000000000000000000000000000000000010f0' + amount: '0x1' + blockAccessList: null + - transactions: + - '0xf865108506fc23ac00830124f8940101010101010101010101010101010101010101018031a0d9712a3c40ae85aea4ad1bd95a0b7cc7bd805189a9e2517403b11a00a1530f81a053b53b0267a6dcfe9f9a1652307b396b3e8a65e65707a450e60c92baefdbcfbe' + withdrawals: + - index: '0xf1' + validatorIndex: '0xf1' + address: '0x00000000000000000000000000000000000010f1' + amount: '0x1' + blockAccessList: '0xf8daf8d8f8d6a000000000000000000000000000000000000000000000000000000000000000a0f8a7a05555555555555555555555555555555555555555555555555555555555555555a06666666666666666666666666666666666666666666666666666666666666666a07777777777777777777777777777777777777777777777777777777777777777' - name: engine_newPayloadV5 summary: Runs execution payload validation externalDocs: diff --git a/src/engine/openrpc/schemas/payload.yaml b/src/engine/openrpc/schemas/payload.yaml index 631f6679c..2658a3e17 100644 --- a/src/engine/openrpc/schemas/payload.yaml +++ b/src/engine/openrpc/schemas/payload.yaml @@ -318,14 +318,27 @@ ExecutionPayloadBodyV1: - 'null' items: $ref: '#/components/schemas/WithdrawalV1' -BlockAccessListBodyV1: - title: Block access list body object V1 +ExecutionPayloadBodyV2: + title: Execution payload body object V2 type: object + required: + - transactions properties: + transactions: + $ref: '#/components/schemas/ExecutionPayloadV1/properties/transactions' + withdrawals: + title: Withdrawals + type: + - array + - 'null' + items: + $ref: '#/components/schemas/WithdrawalV1' blockAccessList: title: Block access list - description: RLP-encoded block access list as defined in EIP-7928 - $ref: '#/components/schemas/bytes' + description: RLP-encoded block access list as defined in EIP-7928, or null if unavailable + oneOf: + - $ref: '#/components/schemas/bytes' + - type: 'null' BlobsBundleV1: title: Blobs bundle object V1 type: object diff --git a/wordlist.txt b/wordlist.txt index 6f216f3e9..7b2ca3bd7 100644 --- a/wordlist.txt +++ b/wordlist.txt @@ -6,8 +6,6 @@ blobsbundlev blockaccesslist blockAccessList BlockAccessList -blockaccesslistbodyv -BlockAccessListBodyV bodiesbyhashv bodiesbyrangev bodyv @@ -39,10 +37,6 @@ feeRecipient forkchoiceupdatedresponsev getblobsbundlev getblobsv -getblockaccesslistsbyhashv -getBlockAccessListsByHashV -getblockaccesslistsbyrangev -getBlockAccessListsByRangeV getclientversionv graphql gwei From 4f20b3e03e9d098a85bdd64d0be62dd911dcc527 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Toni=20Wahrst=C3=A4tter?= Date: Fri, 30 Jan 2026 11:29:11 +0100 Subject: [PATCH 4/5] fix: correct relative links in quickstart.md --- docs/reference/quickstart.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/reference/quickstart.md b/docs/reference/quickstart.md index 01b4fb381..5801775bc 100644 --- a/docs/reference/quickstart.md +++ b/docs/reference/quickstart.md @@ -131,7 +131,7 @@ $ npm run graphql:validate ## License -This repository is licensed under [CC0](LICENSE). +This repository is licensed under [CC0][license]. [playground]: https://ethereum.github.io/execution-apis/api-documentation/ @@ -139,8 +139,9 @@ This repository is licensed under [CC0](LICENSE). [validator]: https://open-rpc.github.io/schema-utils-js/functions/validateOpenRPCDocument.html [graphql-schema]: http://graphql-schema.ethdevops.io/?url=https://raw.githubusercontent.com/ethereum/execution-apis/main/graphql.json [eip-1767]: https://eips.ethereum.org/EIPS/eip-1767 -[contributors-guide]: docs/reference/contributors-guide.md +[contributors-guide]: ./contributors-guide.md [json-schema]: https://json-schema.org [hive]: https://github.com/ethereum/hive [rpc-compat]: https://github.com/ethereum/hive/tree/master/simulators/ethereum/rpc-compat -[test-gen]: docs/reference/tests.md +[test-gen]: ./tests.md +[license]: https://github.com/ethereum/execution-apis/blob/main/LICENSE From e4db22e66691c5a2feb249e26697ef22f6115eaf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Toni=20Wahrst=C3=A4tter?= Date: Tue, 3 Feb 2026 08:38:14 +0100 Subject: [PATCH 5/5] remove retention policy mention --- src/engine/amsterdam.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/src/engine/amsterdam.md b/src/engine/amsterdam.md index 23442a5cc..04ccba879 100644 --- a/src/engine/amsterdam.md +++ b/src/engine/amsterdam.md @@ -150,8 +150,6 @@ This method follows the same specification as [`engine_getPayloadBodiesByHashV1` 2. Client software **MUST** set the `blockAccessList` field to `null` if the block access list has been pruned from storage. -3. Client software **MUST** retain block access lists for at least 3533 epochs (the weak subjectivity period) to support synchronization with re-execution. - ### engine_getPayloadBodiesByRangeV2 This method retrieves execution payload bodies including block access lists for a range of blocks. @@ -177,8 +175,6 @@ This method follows the same specification as [`engine_getPayloadBodiesByRangeV1 2. Client software **MUST** set the `blockAccessList` field to `null` if the block access list has been pruned from storage. -3. Client software **MUST** retain block access lists for at least 3533 epochs (the weak subjectivity period) to support synchronization with re-execution. - ### Update the methods of previous forks #### Osaka API