From 7e576768a03e00cc686a2f0dc3efbb8a5fc7e61d Mon Sep 17 00:00:00 2001 From: Alex Stokes Date: Wed, 21 Aug 2024 15:57:12 -0600 Subject: [PATCH 1/7] changes required for EIP-7742 --- src/engine/prague.md | 39 +++++++++++++++++++++++++++++++++++++-- 1 file changed, 37 insertions(+), 2 deletions(-) diff --git a/src/engine/prague.md b/src/engine/prague.md index 688c6abb0..c77d32218 100644 --- a/src/engine/prague.md +++ b/src/engine/prague.md @@ -15,6 +15,7 @@ This specification is based on and extends [Engine API - Cancun](./cancun.md) sp - [ConsolidationRequestV1](#consolidationrequestv1) - [ExecutionPayloadV4](#executionpayloadv4) - [ExecutionPayloadBodyV2](#executionpayloadbodyv2) + - [PayloadAttributesV4](#payloadattributesv4) - [Methods](#methods) - [engine_newPayloadV4](#engine_newpayloadv4) - [Request](#request) @@ -24,14 +25,18 @@ This specification is based on and extends [Engine API - Cancun](./cancun.md) sp - [Request](#request-1) - [Response](#response-1) - [Specification](#specification-1) - - [engine_getPayloadBodiesByHashV2](#engine_getpayloadbodiesbyhashv2) + - [engine_forkchoiceUpdatedV4](#engine_forkchoiceupdatedv4) - [Request](#request-2) - [Response](#response-2) - [Specification](#specification-2) - - [engine_getPayloadBodiesByRangeV2](#engine_getpayloadbodiesbyrangev2) + - [engine_getPayloadBodiesByHashV2](#engine_getpayloadbodiesbyhashv2) - [Request](#request-3) - [Response](#response-3) - [Specification](#specification-3) + - [engine_getPayloadBodiesByRangeV2](#engine_getpayloadbodiesbyrangev2) + - [Request](#request-4) + - [Response](#response-4) + - [Specification](#specification-4) - [Update the methods of previous forks](#update-the-methods-of-previous-forks) @@ -103,6 +108,17 @@ This structure has the syntax of [`ExecutionPayloadBodyV1`](./shanghai.md#execut - `withdrawalRequests`: `Array of WithdrawalRequestV1` - Array of withdrawal requests, each object is an `OBJECT` containing the fields of a `WithdrawalRequestV1` structure. - `consolidationRequests`: `Array of ConsolidationRequestV1` - Array of consolidation requests, each object is an `OBJECT` containing the fields of a `ConsolidationRequestV1` structure. +### PayloadAttributesV4 + +This structure has the syntax of `PayloadAttributesV3` and appends a single field: `targetBlobCount`. + +- `timestamp`: `QUANTITY`, 64 Bits - value for the `timestamp` field of the new payload +- `prevRandao`: `DATA`, 32 Bytes - value for the `prevRandao` field of the new payload +- `suggestedFeeRecipient`: `DATA`, 20 Bytes - suggested value for the `feeRecipient` field of the new payload +- `withdrawals`: `Array of WithdrawalV1` - Array of withdrawals, each object is an `OBJECT` containing the fields of a `WithdrawalV1` structure. +- `parentBeaconBlockRoot`: `DATA`, 32 Bytes - Root of the parent beacon block. +- `targetBlobCount`: `QUANTITY`, 64 Bits - Average number of blobs to include per payload. + ## Methods ### engine_newPayloadV4 @@ -116,6 +132,7 @@ The request of this method is updated with [`ExecutionPayloadV4`](#ExecutionPayl 1. `executionPayload`: [`ExecutionPayloadV4`](#ExecutionPayloadV4). 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. `targetBlobCount`: `QUANTITY`, 64 Bits - Average number of blobs to include per payload. #### Response @@ -153,6 +170,24 @@ This method follows the same specification as [`engine_getPayloadV3`](./cancun.m 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 Prague fork. +### engine_forkchoiceUpdatedV4 + +#### Request + +* method: `engine_forkchoiceUpdatedV4` +* params: + 1. `forkchoiceState`: [`ForkchoiceStateV1`](./paris.md#ForkchoiceStateV1). + 2. `payloadAttributes`: `Object|null` - Instance of [`PayloadAttributesV4`](#payloadattributesv4) or `null`. +* timeout: 8s + +#### Response + +Refer to the response for [`engine_forkchoiceUpdatedV3`](./shanghai.md#engine_forkchoiceupdatedv3). + +#### Specification + +This method follows the same specification as [`engine_forkchoiceUpdatedV3`](./shanghai.md#engine_forkchoiceupdatedv3). + ### engine_getPayloadBodiesByHashV2 The response of this method is updated with [`ExecutionPayloadBodyV2`](#executionpayloadbodyv2). From ec49a5f419be6b16878322c5e37313856c6247a3 Mon Sep 17 00:00:00 2001 From: Alex Stokes Date: Thu, 22 Aug 2024 14:01:37 -0600 Subject: [PATCH 2/7] provide `maximumBlobCount` for payload construction --- src/engine/prague.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/engine/prague.md b/src/engine/prague.md index c77d32218..66a811836 100644 --- a/src/engine/prague.md +++ b/src/engine/prague.md @@ -110,7 +110,7 @@ This structure has the syntax of [`ExecutionPayloadBodyV1`](./shanghai.md#execut ### PayloadAttributesV4 -This structure has the syntax of `PayloadAttributesV3` and appends a single field: `targetBlobCount`. +This structure has the syntax of `PayloadAttributesV3` and appends the fields: `targetBlobCount`, `maximumBlobCount`. - `timestamp`: `QUANTITY`, 64 Bits - value for the `timestamp` field of the new payload - `prevRandao`: `DATA`, 32 Bytes - value for the `prevRandao` field of the new payload @@ -118,6 +118,7 @@ This structure has the syntax of `PayloadAttributesV3` and appends a single fiel - `withdrawals`: `Array of WithdrawalV1` - Array of withdrawals, each object is an `OBJECT` containing the fields of a `WithdrawalV1` structure. - `parentBeaconBlockRoot`: `DATA`, 32 Bytes - Root of the parent beacon block. - `targetBlobCount`: `QUANTITY`, 64 Bits - Average number of blobs to include per payload. +- `maximumBlobCount`: `QUANTITY`, 64 Bits - Maximum number of blobs allowed per payload. ## Methods From 3e8f327f853a14088e9f562b3e37103c82272aad Mon Sep 17 00:00:00 2001 From: Mikhail Kalinin Date: Tue, 3 Dec 2024 12:21:39 +0600 Subject: [PATCH 3/7] Apply suggestions from @ppopth Co-authored-by: Pop Chunhapanya --- src/engine/prague.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/src/engine/prague.md b/src/engine/prague.md index 66a811836..2be34c57e 100644 --- a/src/engine/prague.md +++ b/src/engine/prague.md @@ -110,15 +110,15 @@ This structure has the syntax of [`ExecutionPayloadBodyV1`](./shanghai.md#execut ### PayloadAttributesV4 -This structure has the syntax of `PayloadAttributesV3` and appends the fields: `targetBlobCount`, `maximumBlobCount`. +This structure has the syntax of `PayloadAttributesV3` and appends the fields: `targetBlobsPerBlock`, `maxBlobsPerBlock`. - `timestamp`: `QUANTITY`, 64 Bits - value for the `timestamp` field of the new payload - `prevRandao`: `DATA`, 32 Bytes - value for the `prevRandao` field of the new payload - `suggestedFeeRecipient`: `DATA`, 20 Bytes - suggested value for the `feeRecipient` field of the new payload - `withdrawals`: `Array of WithdrawalV1` - Array of withdrawals, each object is an `OBJECT` containing the fields of a `WithdrawalV1` structure. - `parentBeaconBlockRoot`: `DATA`, 32 Bytes - Root of the parent beacon block. -- `targetBlobCount`: `QUANTITY`, 64 Bits - Average number of blobs to include per payload. -- `maximumBlobCount`: `QUANTITY`, 64 Bits - Maximum number of blobs allowed per payload. +- `targetBlobsPerBlock`: `QUANTITY`, 64 Bits - Average number of blobs to include per payload. +- `maxBlobsPerBlock`: `QUANTITY`, 64 Bits - Maximum number of blobs allowed per payload. ## Methods @@ -133,7 +133,7 @@ The request of this method is updated with [`ExecutionPayloadV4`](#ExecutionPayl 1. `executionPayload`: [`ExecutionPayloadV4`](#ExecutionPayloadV4). 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. `targetBlobCount`: `QUANTITY`, 64 Bits - Average number of blobs to include per payload. + 4. `targetBlobsPerBlock`: `QUANTITY`, 64 Bits - Average number of blobs to include per payload. #### Response @@ -183,11 +183,11 @@ This method follows the same specification as [`engine_getPayloadV3`](./cancun.m #### Response -Refer to the response for [`engine_forkchoiceUpdatedV3`](./shanghai.md#engine_forkchoiceupdatedv3). +Refer to the response for [`engine_forkchoiceUpdatedV3`](./cancun.md#engine_forkchoiceupdatedv3). #### Specification -This method follows the same specification as [`engine_forkchoiceUpdatedV3`](./shanghai.md#engine_forkchoiceupdatedv3). +This method follows the same specification as [`engine_forkchoiceUpdatedV3`](./cancun.md#engine_forkchoiceupdatedv3). ### engine_getPayloadBodiesByHashV2 From f9bb55b78398a7bbd99e782d7f3ef97831d05031 Mon Sep 17 00:00:00 2001 From: Mikhail Kalinin Date: Tue, 3 Dec 2024 12:37:19 +0600 Subject: [PATCH 4/7] Add fork time constraint to fcUV4 --- src/engine/prague.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/src/engine/prague.md b/src/engine/prague.md index 586f4b3ee..dd1fa49cc 100644 --- a/src/engine/prague.md +++ b/src/engine/prague.md @@ -118,7 +118,9 @@ Refer to the response for [`engine_forkchoiceUpdatedV3`](./cancun.md#engine_fork #### Specification -This method follows the same specification as [`engine_forkchoiceUpdatedV3`](./cancun.md#engine_forkchoiceupdatedv3). +This method follows the same specification as [`engine_forkchoiceUpdatedV3`](./cancun.md#engine_forkchoiceupdatedv3) with the following modifications: +1. `payloadAttributes` **MUST** match the [`PayloadAttributesV4`](#payloadattributesv4) structure. +2. `payloadAttributes.timestamp` **MUST** fall within the time frame of the Prague fork. ### Update the methods of previous forks From 3d695a3935c7441f8eebbaa30e65ef0693068791 Mon Sep 17 00:00:00 2001 From: Mikhail Kalinin Date: Tue, 3 Dec 2024 12:39:55 +0600 Subject: [PATCH 5/7] Change definition order --- src/engine/prague.md | 44 ++++++++++++++++++++++---------------------- 1 file changed, 22 insertions(+), 22 deletions(-) diff --git a/src/engine/prague.md b/src/engine/prague.md index dd1fa49cc..f3079b730 100644 --- a/src/engine/prague.md +++ b/src/engine/prague.md @@ -16,11 +16,11 @@ This specification is based on and extends [Engine API - Cancun](./cancun.md) sp - [Request](#request) - [Response](#response) - [Specification](#specification) - - [engine_getPayloadV4](#engine_getpayloadv4) + - [engine_forkchoiceUpdatedV4](#engine_forkchoiceupdatedv4) - [Request](#request-1) - [Response](#response-1) - [Specification](#specification-1) - - [engine_forkchoiceUpdatedV4](#engine_forkchoiceupdatedv4) + - [engine_getPayloadV4](#engine_getpayloadv4) - [Request](#request-2) - [Response](#response-2) - [Specification](#specification-2) @@ -73,6 +73,26 @@ and incorporate it into the `blockHash` validation process. That is, if the computed commitment does not match the corresponding commitment in the execution layer block header, the call **MUST** return `{status: INVALID, latestValidHash: null, validationError: errorMessage | null}`. +### engine_forkchoiceUpdatedV4 + +#### Request + +* method: `engine_forkchoiceUpdatedV4` +* params: + 1. `forkchoiceState`: [`ForkchoiceStateV1`](./paris.md#ForkchoiceStateV1). + 2. `payloadAttributes`: `Object|null` - Instance of [`PayloadAttributesV4`](#payloadattributesv4) or `null`. +* timeout: 8s + +#### Response + +Refer to the response for [`engine_forkchoiceUpdatedV3`](./cancun.md#engine_forkchoiceupdatedv3). + +#### Specification + +This method follows the same specification as [`engine_forkchoiceUpdatedV3`](./cancun.md#engine_forkchoiceupdatedv3) with the following modifications: +1. `payloadAttributes` **MUST** match the [`PayloadAttributesV4`](#payloadattributesv4) structure. +2. `payloadAttributes.timestamp` **MUST** fall within the time frame of the Prague fork. + ### engine_getPayloadV4 The response of this method is extended with the `executionRequests` field. @@ -102,26 +122,6 @@ This method follows the same specification as [`engine_getPayloadV3`](./cancun.m 2. The call **MUST** return `executionRequests` list representing execution layer triggered requests. Each list element is a `requests` byte array as defined by [EIP-7685](https://eips.ethereum.org/EIPS/eip-7685). The first byte of each element is the `request_type` and the remaining bytes are the `request_data`. Elements of the list **MUST** be ordered by `request_type` in ascending order. Elements with empty `request_data` **MUST** be excluded from the list. -### engine_forkchoiceUpdatedV4 - -#### Request - -* method: `engine_forkchoiceUpdatedV4` -* params: - 1. `forkchoiceState`: [`ForkchoiceStateV1`](./paris.md#ForkchoiceStateV1). - 2. `payloadAttributes`: `Object|null` - Instance of [`PayloadAttributesV4`](#payloadattributesv4) or `null`. -* timeout: 8s - -#### Response - -Refer to the response for [`engine_forkchoiceUpdatedV3`](./cancun.md#engine_forkchoiceupdatedv3). - -#### Specification - -This method follows the same specification as [`engine_forkchoiceUpdatedV3`](./cancun.md#engine_forkchoiceupdatedv3) with the following modifications: -1. `payloadAttributes` **MUST** match the [`PayloadAttributesV4`](#payloadattributesv4) structure. -2. `payloadAttributes.timestamp` **MUST** fall within the time frame of the Prague fork. - ### Update the methods of previous forks This document defines how Prague payload should be handled by the [`Cancun API`](./cancun.md). From 68405963d2ab511aed6207a35da03251b558b035 Mon Sep 17 00:00:00 2001 From: Mikhail Kalinin Date: Tue, 3 Dec 2024 12:49:21 +0600 Subject: [PATCH 6/7] Add schema for fcUV4 --- src/engine/openrpc/methods/forkchoice.yaml | 60 ++++++++++++++++++++++ src/engine/openrpc/schemas/forkchoice.yaml | 26 ++++++++++ 2 files changed, 86 insertions(+) diff --git a/src/engine/openrpc/methods/forkchoice.yaml b/src/engine/openrpc/methods/forkchoice.yaml index 66479d12a..2ee9498bf 100644 --- a/src/engine/openrpc/methods/forkchoice.yaml +++ b/src/engine/openrpc/methods/forkchoice.yaml @@ -153,3 +153,63 @@ latestValidHash: '0x3559e851470f6e7bbed1db474980683e8c315bfce99b2a6ef47c057c04de7858' validationError: null payloadId: '0x0000000021f32cc1' +- name: engine_forkchoiceUpdatedV4 + summary: Updates the forkchoice state + externalDocs: + description: Method specification + url: https://github.com/ethereum/execution-apis/blob/main/src/engine/prague.md#engine_forkchoiceupdatedv4 + params: + - name: Forkchoice state + required: true + schema: + $ref: '#/components/schemas/ForkchoiceStateV1' + - name: Payload attributes + required: false + schema: + $ref: '#/components/schemas/PayloadAttributesV4' + result: + name: Response object + schema: + $ref: '#/components/schemas/ForkchoiceUpdatedResponseV1' + errors: + - code: -38002 + message: Invalid forkchoice state + - code: -38003 + message: Invalid payload attributes + - code: -32602 + message: Invalid params + - code: -38005 + message: Unsupported fork + examples: + - name: engine_forkchoiceUpdatedV4 example + params: + - name: Forkchoice state + value: + headBlockHash: '0x3559e851470f6e7bbed1db474980683e8c315bfce99b2a6ef47c057c04de7858' + safeBlockHash: '0x3559e851470f6e7bbed1db474980683e8c315bfce99b2a6ef47c057c04de7858' + finalizedBlockHash: '0x3b8fb240d288781d4aac94d3fd16809ee413bc99294a085798a589dae51ddd4a' + - name: Payload attributes + value: + timestamp: '0x64e7785b' + prevRandao: '0xc130d5e63c61c935f6089e61140ca9136172677cf6aa5800dcc1cf0a02152a14' + suggestedFeeRecipient: '0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b' + withdrawals: + - index: '0xf0' + validatorIndex: '0xf0' + address: '0x00000000000000000000000000000000000010f0' + amount: '0x1' + - index: '0xf1' + validatorIndex: '0xf1' + address: '0x00000000000000000000000000000000000010f1' + amount: '0x1' + parentBeaconBlockRoot: '0x11f780a954bcba8889998e4e61deaae6388dd2391e9c810bd9c94962cc1eadc1' + targetBlobsPerBlock: '0x3' + maxBlobsPerBlock: '0x6' + result: + name: Response object + value: + payloadStatus: + status: VALID + latestValidHash: '0x3559e851470f6e7bbed1db474980683e8c315bfce99b2a6ef47c057c04de7858' + validationError: null + payloadId: '0x0000000021f32cc1' diff --git a/src/engine/openrpc/schemas/forkchoice.yaml b/src/engine/openrpc/schemas/forkchoice.yaml index c398de23f..9aae8cefd 100644 --- a/src/engine/openrpc/schemas/forkchoice.yaml +++ b/src/engine/openrpc/schemas/forkchoice.yaml @@ -85,3 +85,29 @@ PayloadAttributesV3: parentBeaconBlockRoot: title: Parent beacon block root $ref: '#/components/schemas/hash32' +PayloadAttributesV4: + title: Payload attributes object V4 + type: object + required: + - timestamp + - prevRandao + - suggestedFeeRecipient + - withdrawals + - parentBeaconBlockRoot + - targetBlobsPerBlock + - maxBlobsPerBlock + properties: + timestamp: + $ref: '#/components/schemas/PayloadAttributesV3/properties/timestamp' + prevRandao: + $ref: '#/components/schemas/PayloadAttributesV3/properties/prevRandao' + suggestedFeeRecipient: + $ref: '#/components/schemas/PayloadAttributesV3/properties/suggestedFeeRecipient' + withdrawals: + $ref: '#/components/schemas/PayloadAttributesV3/properties/withdrawals' + parentBeaconBlockRoot: + $ref: '#/components/schemas/PayloadAttributesV3/properties/parentBeaconBlockRoot' + targetBlobsPerBlock: + $ref: '#/components/schemas/uint64' + maxBlobsPerBlock: + $ref: '#/components/schemas/uint64' From d0d88cd3f7a54b612a99d02a0f0e75857cea1bac Mon Sep 17 00:00:00 2001 From: Alex Stokes Date: Mon, 9 Dec 2024 15:38:51 -0700 Subject: [PATCH 7/7] add updates to execution payload for extended header under EIP-7742 --- src/engine/prague.md | 28 ++++++++++++++++++++++++++-- 1 file changed, 26 insertions(+), 2 deletions(-) diff --git a/src/engine/prague.md b/src/engine/prague.md index f3079b730..8434ba703 100644 --- a/src/engine/prague.md +++ b/src/engine/prague.md @@ -10,6 +10,7 @@ This specification is based on and extends [Engine API - Cancun](./cancun.md) sp - [Structures](#structures) + - [ExecutionPayloadV4](#executionpayloadv4) - [PayloadAttributesV4](#payloadattributesv4) - [Methods](#methods) - [engine_newPayloadV4](#engine_newpayloadv4) @@ -30,6 +31,29 @@ This specification is based on and extends [Engine API - Cancun](./cancun.md) sp ## Structures +### ExecutionPayloadV4 + +This structure has the syntax of [`ExecutionPayloadV3`](./cancun.md#executionpayloadv3) and appends the new field(s): `targetBlobsPerBlock`. + +- `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 +- `targetBlobsPerBlock`: `QUANTITY`, 64 Bits + ### PayloadAttributesV4 This structure has the syntax of [`PayloadAttributesV3`](./cancun.md#payloadattributesv3) and appends the fields: `targetBlobsPerBlock`, `maxBlobsPerBlock`. @@ -52,7 +76,7 @@ Method parameter list is extended with `executionRequests`. * method: `engine_newPayloadV4` * params: - 1. `executionPayload`: [`ExecutionPayloadV3`](./cancun.md#executionpayloadv3). + 1. `executionPayload`: [`ExecutionPayloadV4`](#ExecutionPayloadV4). 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. Each list element is a `requests` byte array as defined by [EIP-7685](https://eips.ethereum.org/EIPS/eip-7685). The first byte of each element is the `request_type` and the remaining bytes are the `request_data`. Elements of the list **MUST** be ordered by `request_type` in ascending order. Elements with empty `request_data` **MUST** be excluded from the list. @@ -107,7 +131,7 @@ The response of this method is extended with the `executionRequests` field. #### Response * result: `object` - - `executionPayload`: [`ExecutionPayloadV3`](./cancun.md#executionpayloadv3) + - `executionPayload`: [`ExecutionPayloadV4`](#ExecutionPayloadv4) - `blockValue` : `QUANTITY`, 256 Bits - The expected value to be received by the `feeRecipient` in wei - `blobsBundle`: [`BlobsBundleV1`](#BlobsBundleV1) - 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