diff --git a/docs-api/docs/quickstart.md b/docs-api/docs/quickstart.md index b8e37cf8b..3325ecc87 100644 --- a/docs-api/docs/quickstart.md +++ b/docs-api/docs/quickstart.md @@ -154,9 +154,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-api/docs/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-api/docs/tests.md +[test-gen]: ./tests.md [license]: https://github.com/ethereum/execution-apis/blob/main/LICENSE diff --git a/src/engine/amsterdam.md b/src/engine/amsterdam.md index 45cfb6198..04fbfd1b5 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,6 +21,19 @@ This specification is based on and extends [Engine API - Osaka](./osaka.md) spec - [Request](#request-1) - [Response](#response-1) - [Specification](#specification-1) + - [engine_getPayloadBodiesByHashV2](#engine_getpayloadbodiesbyhashv2) + - [Request](#request-2) + - [Response](#response-2) + - [Specification](#specification-2) + - [engine_getPayloadBodiesByRangeV2](#engine_getpayloadbodiesbyrangev2) + - [Request](#request-3) + - [Response](#response-3) + - [Specification](#specification-3) + - [engine_forkchoiceUpdatedV4](#engine_forkchoiceupdatedv4) + - [Request](#request-4) + - [Response](#response-4) + - [Specification](#specification-4) + - [PayloadAttributesV4](#payloadattributesv4) - [Update the methods of previous forks](#update-the-methods-of-previous-forks) - [Osaka API](#osaka-api) @@ -51,6 +65,14 @@ This structure has the syntax of [`ExecutionPayloadV3`](./cancun.md#executionpay - `blockAccessList`: `DATA` - RLP-encoded block access list as defined in [EIP-7928](https://eips.ethereum.org/EIPS/eip-7928) - `slotNumber`: `QUANTITY`, 64 Bits +### 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 @@ -110,6 +132,55 @@ 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_getPayloadBodiesByHashV2 + +This method retrieves execution payload bodies including block access lists for specified blocks. + +#### Request + +* method: `engine_getPayloadBodiesByHashV2` +* params: + 1. `blockHashes`: `Array of DATA`, 32 Bytes - Array of block hashes to retrieve payload bodies for +* timeout: 10s + +#### Response + +* 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 + +This method follows the same specification as [`engine_getPayloadBodiesByHashV1`](./shanghai.md#engine_getpayloadbodiesbyhashv1) with the following additions: + +1. Client software **MUST** set the `blockAccessList` field to `null` for blocks that predate the Amsterdam fork activation. + +2. Client software **MUST** set the `blockAccessList` field to `null` if the block access list has been pruned from storage. + +### engine_getPayloadBodiesByRangeV2 + +This method retrieves execution payload bodies including block access lists for a range of blocks. + +#### Request + +* method: `engine_getPayloadBodiesByRangeV2` +* params: + 1. `start`: `QUANTITY`, 64 Bits - Starting block number + 2. `count`: `QUANTITY`, 64 Bits - Number of blocks to retrieve payload bodies for +* timeout: 10s + +#### Response + +* 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 + +This method follows the same specification as [`engine_getPayloadBodiesByRangeV1`](./shanghai.md#engine_getpayloadbodiesbyrangev1) with the following additions: + +1. Client software **MUST** set the `blockAccessList` field to `null` for blocks that predate the Amsterdam fork activation. + +2. Client software **MUST** set the `blockAccessList` field to `null` if the block access list has been pruned from storage. + ### engine_forkchoiceUpdatedV4 #### Request diff --git a/src/engine/openrpc/methods/capabilities.yaml b/src/engine/openrpc/methods/capabilities.yaml index 17dae9346..81e4bf3e0 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_getPayloadBodiesByHashV2' + - 'engine_getPayloadBodiesByRangeV2' - 'engine_getPayloadV1' - 'engine_newPayloadV1' result: @@ -40,3 +42,5 @@ - 'engine_exchangeTransitionConfigurationV1' - 'engine_getPayloadBodiesByHashV1' - 'engine_getPayloadBodiesByRangeV1' + - 'engine_getPayloadBodiesByHashV2' + - 'engine_getPayloadBodiesByRangeV2' diff --git a/src/engine/openrpc/methods/payload.yaml b/src/engine/openrpc/methods/payload.yaml index 01e267c74..aa0b09d6c 100644 --- a/src/engine/openrpc/methods/payload.yaml +++ b/src/engine/openrpc/methods/payload.yaml @@ -886,6 +886,102 @@ validatorIndex: '0xf3' address: '0x00000000000000000000000000000000000010f3' amount: '0x1' +- 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_getpayloadbodiesbyhashv2 + params: + - name: Array of block hashes + required: true + schema: + type: array + items: + $ref: '#/components/schemas/hash32' + result: + name: Execution payload bodies + schema: + type: array + items: + $ref: '#/components/schemas/ExecutionPayloadBodyV2' + errors: + - code: -38004 + message: Too large request + examples: + - name: engine_getPayloadBodiesByHashV2 example + params: + - name: Array of block hashes + value: + - '0xd5f1812548be429cbdc6376b29611fc49e06f1359758c4ceaaa3b393e2239f9c' + - '0xfe88c94d860f01a17f961bf4bdfb6e0c6cd10d3fda5cc861e805ca1240c58553' + result: + name: Execution payload bodies + value: + - 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_getpayloadbodiesbyrangev2 + 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: Execution payload bodies + schema: + type: array + items: + $ref: '#/components/schemas/ExecutionPayloadBodyV2' + errors: + - code: -38004 + message: Too large request + examples: + - name: engine_getPayloadBodiesByRangeV2 example + params: + - name: Starting block number + value: '0x20' + - name: Number of blocks to return + value: '0x2' + result: + name: Execution payload bodies + value: + - 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 2abeaf613..182e2ce40 100644 --- a/src/engine/openrpc/schemas/payload.yaml +++ b/src/engine/openrpc/schemas/payload.yaml @@ -322,6 +322,27 @@ ExecutionPayloadBodyV1: - 'null' items: $ref: '#/components/schemas/WithdrawalV1' +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, 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 cf5f76c62..7b2ca3bd7 100644 --- a/wordlist.txt +++ b/wordlist.txt @@ -1,82 +1,84 @@ apis attributesv -bodyv -bodiesbyrangev +besu +blobandproofv +blobsbundlev +blockaccesslist +blockAccessList +BlockAccessList 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 +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