diff --git a/src/engine/amsterdam.md b/src/engine/amsterdam.md index cc4613fc7..48febf1dd 100644 --- a/src/engine/amsterdam.md +++ b/src/engine/amsterdam.md @@ -9,8 +9,6 @@ This specification is based on and extends [Engine API - Osaka](./osaka.md) spec -- [Structures](#structures) - - [ExecutionPayloadV4](#executionpayloadv4) - [Methods](#methods) - [engine_newPayloadV5](#engine_newpayloadv5) - [Request](#request) @@ -25,45 +23,21 @@ This specification is based on and extends [Engine API - Osaka](./osaka.md) spec -## Structures - -### ExecutionPayloadV4 - -This structure has the syntax of [`ExecutionPayloadV3`](./cancun.md#executionpayloadv3) and appends the new field: `blockAccessList`. - -- `parentHash`: `DATA`, 32 Bytes -- `feeRecipient`: `DATA`, 20 Bytes -- `stateRoot`: `DATA`, 32 Bytes -- `receiptsRoot`: `DATA`, 32 Bytes -- `logsBloom`: `DATA`, 256 Bytes -- `prevRandao`: `DATA`, 32 Bytes -- `blockNumber`: `QUANTITY`, 64 Bits -- `gasLimit`: `QUANTITY`, 64 Bits -- `gasUsed`: `QUANTITY`, 64 Bits -- `timestamp`: `QUANTITY`, 64 Bits -- `extraData`: `DATA`, 0 to 32 Bytes -- `baseFeePerGas`: `QUANTITY`, 256 Bits -- `blockHash`: `DATA`, 32 Bytes -- `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. -- `blobGasUsed`: `QUANTITY`, 64 Bits -- `excessBlobGas`: `QUANTITY`, 64 Bits -- `blockAccessList`: `DATA` - RLP-encoded block access list as defined in [EIP-7928](https://eips.ethereum.org/EIPS/eip-7928) - ## Methods ### engine_newPayloadV5 -This method is updated to support the new `ExecutionPayloadV4` structure. +This method supports the `ExecutionPayloadV3` structure and block access list validation. #### Request * method: `engine_newPayloadV5` * params: - 1. `executionPayload`: [`ExecutionPayloadV4`](#executionpayloadv4). + 1. `executionPayload`: [`ExecutionPayloadV3`](./cancun.md#executionpayloadv3). 2. `expectedBlobVersionedHashes`: `Array of DATA`, 32 Bytes - Array of expected blob versioned hashes to validate. 3. `parentBeaconBlockRoot`: `DATA`, 32 Bytes - Root of the parent beacon block. 4. `executionRequests`: `Array of DATA` - List of execution layer triggered requests. + 5. `blockAccessList`: `DATA` - RLP-encoded block access list as defined in [EIP-7928](https://eips.ethereum.org/EIPS/eip-7928) #### Response @@ -75,14 +49,14 @@ This method follows the same specification as [`engine_newPayloadV4`](./prague.m 1. Client software **MUST** return `-38005: Unsupported fork` error if the `timestamp` of the payload does not fall within the time frame of the Amsterdam activation. -2. Client software **MUST** return `-32602: Invalid params` error if the `blockAccessList` field is missing. +2. Client software **MUST** return `-32602: Invalid params` error if the `blockAccessList` parameter is missing or not provided as the 5th parameter. -3. Client software **MUST** validate the `blockAccessList` field by executing the payload's transactions and verifying that the computed access list matches the provided one. +3. Client software **MUST** validate the `blockAccessList` parameter by executing the payload's transactions and verifying that the computed access list matches the provided one. If this validation fails, the call **MUST** return `{status: INVALID, latestValidHash: null, validationError: errorMessage | null}`. ### engine_getPayloadV6 -This method is updated to return the new `ExecutionPayloadV4` structure. +This method returns the `ExecutionPayloadV3` structure and block access list. #### Request @@ -94,11 +68,12 @@ This method is updated to return the new `ExecutionPayloadV4` structure. #### Response * result: `object` - - `executionPayload`: [`ExecutionPayloadV4`](#executionpayloadv4) + - `executionPayload`: [`ExecutionPayloadV3`](./cancun.md#executionpayloadv3) - `blockValue` : `QUANTITY`, 256 Bits - The expected value to be received by the `feeRecipient` in wei - `blobsBundle`: [`BlobsBundleV2`](./osaka.md#blobsbundlev2) - Bundle with data corresponding to blob transactions included into `executionPayload` - `shouldOverrideBuilder` : `BOOLEAN` - Suggestion from the execution layer to use this `executionPayload` instead of an externally provided one - `executionRequests`: `Array of DATA` - Execution layer triggered requests obtained from the `executionPayload` transaction execution. + - `blockAccessList`: `DATA` - RLP-encoded block access list as defined in [EIP-7928](https://eips.ethereum.org/EIPS/eip-7928) * error: code and message set in case an exception happens while getting the payload. #### Specification @@ -107,7 +82,7 @@ This method follows the same specification as [`engine_getPayloadV5`](./osaka.md 1. Client software **MUST** return `-38005: Unsupported fork` error if the `timestamp` of the built payload does not fall within the time frame of the Amsterdam activation. -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. +2. When building the block, client software **MUST** collect all account accesses and state changes during transaction execution and return the RLP-encoded access list in the `blockAccessList` field of the response. ### Update the methods of previous forks diff --git a/src/engine/eip7928.md b/src/engine/eip7928.md index dd228c288..340c33154 100644 --- a/src/engine/eip7928.md +++ b/src/engine/eip7928.md @@ -9,8 +9,6 @@ This specification is based on and extends [Engine API - Osaka](./osaka.md) spec -- [Structures](#structures) - - [ExecutionPayloadV4](#executionpayloadv4) - [Methods](#methods) - [engine_newPayloadV5](#engine_newpayloadv5) - [Request](#request) @@ -25,45 +23,21 @@ This specification is based on and extends [Engine API - Osaka](./osaka.md) spec -## Structures - -### ExecutionPayloadV4 - -This structure has the syntax of [`ExecutionPayloadV3`](./cancun.md#executionpayloadv3) and appends the new field: `blockAccessList`. - -- `parentHash`: `DATA`, 32 Bytes -- `feeRecipient`: `DATA`, 20 Bytes -- `stateRoot`: `DATA`, 32 Bytes -- `receiptsRoot`: `DATA`, 32 Bytes -- `logsBloom`: `DATA`, 256 Bytes -- `prevRandao`: `DATA`, 32 Bytes -- `blockNumber`: `QUANTITY`, 64 Bits -- `gasLimit`: `QUANTITY`, 64 Bits -- `gasUsed`: `QUANTITY`, 64 Bits -- `timestamp`: `QUANTITY`, 64 Bits -- `extraData`: `DATA`, 0 to 32 Bytes -- `baseFeePerGas`: `QUANTITY`, 256 Bits -- `blockHash`: `DATA`, 32 Bytes -- `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. -- `blobGasUsed`: `QUANTITY`, 64 Bits -- `excessBlobGas`: `QUANTITY`, 64 Bits -- `blockAccessList`: `DATA` - RLP-encoded block access list as defined in [EIP-7928](https://eips.ethereum.org/EIPS/eip-7928) - ## Methods ### engine_newPayloadV5 -This method is updated to support the new `ExecutionPayloadV4` structure. +This method supports the `ExecutionPayloadV3` structure and block access list validation. #### Request * method: `engine_newPayloadV5` * params: - 1. `executionPayload`: [`ExecutionPayloadV4`](#executionpayloadv4). + 1. `executionPayload`: [`ExecutionPayloadV3`](./cancun.md#executionpayloadv3). 2. `expectedBlobVersionedHashes`: `Array of DATA`, 32 Bytes - Array of expected blob versioned hashes to validate. 3. `parentBeaconBlockRoot`: `DATA`, 32 Bytes - Root of the parent beacon block. 4. `executionRequests`: `Array of DATA` - List of execution layer triggered requests. + 5. `blockAccessList`: `DATA` - RLP-encoded block access list as defined in [EIP-7928](https://eips.ethereum.org/EIPS/eip-7928) #### Response @@ -75,13 +49,15 @@ This method follows the same specification as [`engine_newPayloadV4`](./prague.m 1. Client software **MUST** return `-38005: Unsupported fork` error if the `timestamp` of the payload does not fall within the time frame of the EIP-7928 activation. -2. Client software **MUST** validate the `blockAccessList` field by executing the payload's transactions and verifying that the computed access list matches the provided one. +2. Client software **MUST** return `-32602: Invalid params` error if the `blockAccessList` parameter is missing or not provided as the 5th parameter. + +3. Client software **MUST** validate the `blockAccessList` parameter by executing the payload's transactions and verifying that the computed access list matches the provided one. -3. If the `blockAccessList` field is missing, malformed, or doesn't match the computed access list, the call **MUST** return `{status: INVALID, latestValidHash: null, validationError: errorMessage | null}`. +4. If the `blockAccessList` parameter is malformed or doesn't match the computed access list, the call **MUST** return `{status: INVALID, latestValidHash: null, validationError: errorMessage | null}`. ### engine_getPayloadV6 -This method is updated to return the new `ExecutionPayloadV4` structure. +This method returns the `ExecutionPayloadV3` structure and block access list. #### Request @@ -93,11 +69,12 @@ This method is updated to return the new `ExecutionPayloadV4` structure. #### Response * result: `object` - - `executionPayload`: [`ExecutionPayloadV4`](#executionpayloadv4) + - `executionPayload`: [`ExecutionPayloadV3`](./cancun.md#executionpayloadv3) - `blockValue` : `QUANTITY`, 256 Bits - The expected value to be received by the `feeRecipient` in wei - `blobsBundle`: [`BlobsBundleV2`](./osaka.md#blobsbundlev2) - Bundle with data corresponding to blob transactions included into `executionPayload` - `shouldOverrideBuilder` : `BOOLEAN` - Suggestion from the execution layer to use this `executionPayload` instead of an externally provided one - `executionRequests`: `Array of DATA` - Execution layer triggered requests obtained from the `executionPayload` transaction execution. + - `blockAccessList`: `DATA` - RLP-encoded block access list as defined in [EIP-7928](https://eips.ethereum.org/EIPS/eip-7928) * error: code and message set in case an exception happens while getting the payload. #### Specification @@ -106,7 +83,7 @@ This method follows the same specification as [`engine_getPayloadV5`](./osaka.md 1. Client software **MUST** return `-38005: Unsupported fork` error if the `timestamp` of the built payload does not fall within the time frame of the EIP-7928 activation. -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. +2. When building the block, client software **MUST** collect all account accesses and state changes during transaction execution and return the RLP-encoded access list in the `blockAccessList` field of the response. ### Update the methods of previous forks diff --git a/src/engine/openrpc/methods/payload.yaml b/src/engine/openrpc/methods/payload.yaml index 01e267c74..ea0ec60c0 100644 --- a/src/engine/openrpc/methods/payload.yaml +++ b/src/engine/openrpc/methods/payload.yaml @@ -895,7 +895,7 @@ - name: Execution payload required: true schema: - $ref: '#/components/schemas/ExecutionPayloadV4' + $ref: '#/components/schemas/ExecutionPayloadV3' - name: Expected blob versioned hashes required: true schema: @@ -912,6 +912,10 @@ type: array items: $ref: '#/components/schemas/bytes' + - name: Block access list + required: true + schema: + $ref: '#/components/schemas/bytes' result: name: Payload status schema: @@ -954,7 +958,6 @@ amount: '0x1' blobGasUsed: '0x20000' excessBlobGas: '0x0' - blockAccessList: '0xf90244f90241f8f79400000000000000000000000000000000000001f8e8f843a00000000000000000000000000000000000000000000000000000000000000000f838c22080a00000000000000000000000000000000000000000000000000000000000000000c22180a00000000000000000000000000000000000000000000000000000000000000001f843a00000000000000000000000000000000000000000000000000000000000000001f838c22080a00000000000000000000000000000000000000000000000000000000000000100c22180a00000000000000000000000000000000000000000000000000000000000000200c780c22180c680c221890056bc75e2d63100000c080c22180f90145f90142f8f794a94f5374fce5edbc8e2a8697c15331677e6ebf0bf8e8f843a00000000000000000000000000000000000000000000000000000000000000000f838c22080a00000000000000000000000000000000000000000000000000000000000000000c22180a00000000000000000000000000000000000000000000000000000000000000100f843a00000000000000000000000000000000000000000000000000000000000000001f838c22080a00000000000000000000000000000000000000000000000000000000000000200c22180a00000000000000000000000000000000000000000000000000000000000000300c780c22180c680c2218901152d02c7e14af680c080c22180' - name: Expected blob versioned hashes value: - '0x000657f37554c781402a22917dee2f75def7ab966d7b770905398eba3c444014' @@ -964,6 +967,8 @@ value: - '0x96a96086cff07df17668f35f7418ef8798079167e3f4f9b72ecde17b28226137cf454ab1dd20ef5d924786ab3483c2f9003f5102dabe0a27b1746098d1dc17a5d3fbd478759fea9287e4e419b3c3cef20100000000000000b1acdb2c4d3df3f1b8d3bfd33421660df358d84d78d16c4603551935f4b67643373e7eb63dcb16ec359be0ec41fee33b03a16e80745f2374ff1d3c352508ac5d857c6476d3c3bcf7e6ca37427c9209f17be3af5264c0e2132b3dd1156c28b4e9f000000000000000a5c85a60ba2905c215f6a12872e62b1ee037051364244043a5f639aa81b04a204c55e7cc851f29c7c183be253ea1510b001db70c485b6264692f26b8aeaab5b0c384180df8e2184a21a808a3ec8e86ca01000000000000009561731785b48cf1886412234531e4940064584463e96ac63a1a154320227e333fb51addc4a89b7e0d3f862d7c1fd4ea03bd8eb3d8806f1e7daf591cbbbb92b0beb74d13c01617f22c5026b4f9f9f294a8a7c32db895de3b01bee0132c9209e1f100000000000000' - '0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b85103a5617937691dfeeb89b86a80d5dc9e3c9d3a1a0e7ce311e26e0bb732eabaa47ffa288f0d54de28209a62a7d29d0000000000000000000000000000000000000000000000000000010f698daeed734da114470da559bd4b4c7259e1f7952555241dcbc90cf194a2ef676fc6005f3672fada2a3645edb297a75530100000000000000' + - name: Block access list + value: '0xf90244f90241f8f79400000000000000000000000000000000000001f8e8f843a00000000000000000000000000000000000000000000000000000000000000000f838c22080a00000000000000000000000000000000000000000000000000000000000000000c22180a00000000000000000000000000000000000000000000000000000000000000001f843a00000000000000000000000000000000000000000000000000000000000000001f838c22080a00000000000000000000000000000000000000000000000000000000000000100c22180a00000000000000000000000000000000000000000000000000000000000000200c780c22180c680c221890056bc75e2d63100000c080c22180f90145f90142f8f794a94f5374fce5edbc8e2a8697c15331677e6ebf0bf8e8f843a00000000000000000000000000000000000000000000000000000000000000000f838c22080a00000000000000000000000000000000000000000000000000000000000000000c22180a00000000000000000000000000000000000000000000000000000000000000100f843a00000000000000000000000000000000000000000000000000000000000000001f838c22080a00000000000000000000000000000000000000000000000000000000000000200c22180a00000000000000000000000000000000000000000000000000000000000000300c780c22180c680c2218901152d02c7e14af680c080c22180' result: name: Payload status value: @@ -990,9 +995,10 @@ - blobsBundle - shouldOverrideBuilder - executionRequests + - blockAccessList properties: executionPayload: - $ref: '#/components/schemas/ExecutionPayloadV4' + $ref: '#/components/schemas/ExecutionPayloadV3' blockValue: $ref: '#/components/schemas/uint256' blobsBundle: @@ -1003,6 +1009,8 @@ type: array items: $ref: '#/components/schemas/bytes' + blockAccessList: + $ref: '#/components/schemas/bytes' errors: - code: -38001 message: Unknown payload @@ -1053,7 +1061,6 @@ amount: '0x1' blobGasUsed: '0x60000' excessBlobGas: '0x0' - blockAccessList: '0xc0' blockValue: '0x10a741a46278014d' blobsBundle: commitments: @@ -1066,3 +1073,4 @@ executionRequests: - '0x96a96086cff07df17668f35f7418ef8798079167e3f4f9b72ecde17b28226137cf454ab1dd20ef5d924786ab3483c2f9003f5102dabe0a27b1746098d1dc17a5d3fbd478759fea9287e4e419b3c3cef20100000000000000b1acdb2c4d3df3f1b8d3bfd33421660df358d84d78d16c4603551935f4b67643373e7eb63dcb16ec359be0ec41fee33b03a16e80745f2374ff1d3c352508ac5d857c6476d3c3bcf7e6ca37427c9209f17be3af5264c0e2132b3dd1156c28b4e9f000000000000000a5c85a60ba2905c215f6a12872e62b1ee037051364244043a5f639aa81b04a204c55e7cc851f29c7c183be253ea1510b001db70c485b6264692f26b8aeaab5b0c384180df8e2184a21a808a3ec8e86ca01000000000000009561731785b48cf1886412234531e4940064584463e96ac63a1a154320227e333fb51addc4a89b7e0d3f862d7c1fd4ea03bd8eb3d8806f1e7daf591cbbbb92b0beb74d13c01617f22c5026b4f9f9f294a8a7c32db895de3b01bee0132c9209e1f100000000000000' - '0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b85103a5617937691dfeeb89b86a80d5dc9e3c9d3a1a0e7ce311e26e0bb732eabaa47ffa288f0d54de28209a62a7d29d0000000000000000000000000000000000000000000000000000010f698daeed734da114470da559bd4b4c7259e1f7952555241dcbc90cf194a2ef676fc6005f3672fada2a3645edb297a75530100000000000000' + blockAccessList: '0xc0' diff --git a/src/engine/openrpc/schemas/payload.yaml b/src/engine/openrpc/schemas/payload.yaml index 7252f8f8b..036e2d037 100644 --- a/src/engine/openrpc/schemas/payload.yaml +++ b/src/engine/openrpc/schemas/payload.yaml @@ -243,66 +243,6 @@ ExecutionPayloadV3: excessBlobGas: title: Excess blob gas $ref: '#/components/schemas/uint64' -ExecutionPayloadV4: - title: Execution payload object V4 - type: object - required: - - parentHash - - feeRecipient - - stateRoot - - receiptsRoot - - logsBloom - - prevRandao - - blockNumber - - gasLimit - - gasUsed - - timestamp - - extraData - - baseFeePerGas - - blockHash - - transactions - - withdrawals - - blobGasUsed - - excessBlobGas - - blockAccessList - properties: - parentHash: - $ref: '#/components/schemas/ExecutionPayloadV3/properties/parentHash' - feeRecipient: - $ref: '#/components/schemas/ExecutionPayloadV3/properties/feeRecipient' - stateRoot: - $ref: '#/components/schemas/ExecutionPayloadV3/properties/stateRoot' - receiptsRoot: - $ref: '#/components/schemas/ExecutionPayloadV3/properties/receiptsRoot' - logsBloom: - $ref: '#/components/schemas/ExecutionPayloadV3/properties/logsBloom' - prevRandao: - $ref: '#/components/schemas/ExecutionPayloadV3/properties/prevRandao' - blockNumber: - $ref: '#/components/schemas/ExecutionPayloadV3/properties/blockNumber' - gasLimit: - $ref: '#/components/schemas/ExecutionPayloadV3/properties/gasLimit' - gasUsed: - $ref: '#/components/schemas/ExecutionPayloadV3/properties/gasUsed' - timestamp: - $ref: '#/components/schemas/ExecutionPayloadV3/properties/timestamp' - extraData: - $ref: '#/components/schemas/ExecutionPayloadV3/properties/extraData' - baseFeePerGas: - $ref: '#/components/schemas/ExecutionPayloadV3/properties/baseFeePerGas' - blockHash: - $ref: '#/components/schemas/ExecutionPayloadV3/properties/blockHash' - transactions: - $ref: '#/components/schemas/ExecutionPayloadV3/properties/transactions' - withdrawals: - $ref: '#/components/schemas/ExecutionPayloadV3/properties/withdrawals' - blobGasUsed: - $ref: '#/components/schemas/ExecutionPayloadV3/properties/blobGasUsed' - excessBlobGas: - $ref: '#/components/schemas/ExecutionPayloadV3/properties/excessBlobGas' - blockAccessList: - title: Block access list - $ref: '#/components/schemas/bytes' ExecutionPayloadBodyV1: title: Execution payload body object V1 type: object