From 34912d869fc6be387f97b306f91e1fbac8d69afe Mon Sep 17 00:00:00 2001 From: Holger Drewes Date: Wed, 25 Jan 2023 21:44:43 +0100 Subject: [PATCH 01/14] Engine API: separated version and type sections in the common definitions --- src/engine/common.md | 39 ++++++++++++++++++++++++++------------- 1 file changed, 26 insertions(+), 13 deletions(-) diff --git a/src/engine/common.md b/src/engine/common.md index a995745cd..51121b316 100644 --- a/src/engine/common.md +++ b/src/engine/common.md @@ -7,14 +7,17 @@ This document specifies common definitions and requirements affecting Engine API -- [Underlying protocol](#underlying-protocol) - - [Authentication](#authentication) -- [Versioning](#versioning) -- [Message ordering](#message-ordering) -- [Load-balancing and advanced configurations](#load-balancing-and-advanced-configurations) -- [Errors](#errors) -- [Timeouts](#timeouts) -- [Encoding](#encoding) +- [Engine API -- Common Definitions](#engine-api----common-definitions) + - [Table of contents](#table-of-contents) + - [Underlying protocol](#underlying-protocol) + - [Authentication](#authentication) + - [Method Versioning](#method-versioning) + - [Structure Types](#structure-types) + - [Message ordering](#message-ordering) + - [Load-balancing and advanced configurations](#load-balancing-and-advanced-configurations) + - [Errors](#errors) + - [Timeouts](#timeouts) + - [Encoding](#encoding) @@ -46,18 +49,28 @@ These methods are described in [Ethereum JSON-RPC Specification][json-rpc-spec]. Engine API uses JWT authentication enabled by default. JWT authentication is specified in [Authentication](./authentication.md) document. -## Versioning +## Method Versioning The versioning of the Engine API is defined as follows: -* The version of each method and structure is independent from versions of other methods and structures. -* The `VX`, where the `X` is the number of the version, is suffixed to the name of each method and structure. -* The version of a method or a structure **MUST** be incremented by one if any of the following is changed: +* The version of each method is independent from versions of other methods or numbers of structural types. +* The `VX`, where the `X` is the number of the version, is suffixed to the name of each method. +* The version of a method **MUST** be incremented by one if any of the following is changed: * a set of method parameters * a method response value * a method behavior +* The specification **MAY** reference a method without the version suffix e.g. `engine_newPayload`. These statements should be read as related to all versions of the referenced method. + +## Structure Types + +Structural types of the Engine API are defined as follows: + +* Types for a structure are numbered for differentiation +* The type number of each structure is independent from numbers of other structural types or versions of methods. +* The `TypeX`, where the `X` is the number of the type, is suffixed to the name of each structure. +* The type of a a structure **MUST** be incremented by one if any of the following is changed: * a set of structure fields -* The specification **MAY** reference a method or a structure without the version suffix e.g. `engine_newPayload`. These statements should be read as related to all versions of the referenced method or structure. +* The specification **MAY** reference a structure without the type suffix e.g. `ExecutionPayload`. These statements should be read as related to all available types of the referenced structure. ## Message ordering From 6f320ffdf9ed3ba72b1882066993580d1f2c2be7 Mon Sep 17 00:00:00 2001 From: Holger Drewes Date: Wed, 25 Jan 2023 21:53:42 +0100 Subject: [PATCH 02/14] Engine API: ExecutionPayloadV1 -> ExecutionPayloadType1 --- src/engine/experimental/blob-extension.md | 8 +-- src/engine/experimental/eip6110.md | 2 +- src/engine/paris.md | 62 ++++++++++++----------- src/engine/shanghai.md | 10 ++-- 4 files changed, 42 insertions(+), 40 deletions(-) diff --git a/src/engine/experimental/blob-extension.md b/src/engine/experimental/blob-extension.md index a2e042ce1..b88540c32 100644 --- a/src/engine/experimental/blob-extension.md +++ b/src/engine/experimental/blob-extension.md @@ -66,8 +66,8 @@ The fields are encoded as follows: * method: `engine_newPayloadV3` * params: - 1. [`ExecutionPayloadV1`](../paris.md#ExecutionPayloadV1) | [`ExecutionPayloadV2`](../shanghai.md#ExecutionPayloadV2) | [`ExecutionPayloadV3`](#ExecutionPayloadV3), where: - - `ExecutionPayloadV1` **MUST** be used if the `timestamp` value is lower than the Shanghai timestamp, + 1. [`ExecutionPayloadType1`](../paris.md#ExecutionPayloadType1) | [`ExecutionPayloadV2`](../shanghai.md#ExecutionPayloadV2) | [`ExecutionPayloadV3`](#ExecutionPayloadV3), where: + - `ExecutionPayloadType1` **MUST** be used if the `timestamp` value is lower than the Shanghai timestamp, - `ExecutionPayloadV2` **MUST** be used if the `timestamp` value is greater or equal to the Shanghai and lower than the EIP-4844 activation timestamp, - `ExecutionPayloadV3` **MUST** be used if the `timestamp` value is greater or equal to the EIP-4844 activation timestamp, - Client software **MUST** return `-32602: Invalid params` error if the wrong version of the structure is used in the method call. @@ -92,8 +92,8 @@ Refer to the response for `engine_newPayloadV2`. #### Response * result: `object` - - `executionPayload`: [`ExecutionPayloadV1`](../paris.md#ExecutionPayloadV1) | [`ExecutionPayloadV2`](../shanghai.md#ExecutionPayloadV2) | [`ExecutionPayloadV3`](#ExecutionPayloadV3) where: - - `ExecutionPayloadV1` **MUST** be returned if the payload `timestamp` is lower than the Shanghai timestamp + - `executionPayload`: [`ExecutionPayloadType1`](../paris.md#ExecutionPayloadType1) | [`ExecutionPayloadV2`](../shanghai.md#ExecutionPayloadV2) | [`ExecutionPayloadV3`](#ExecutionPayloadV3) where: + - `ExecutionPayloadType1` **MUST** be returned if the payload `timestamp` is lower than the Shanghai timestamp - `ExecutionPayloadV2` **MUST** be returned if the payload `timestamp` is greater or equal to the Shanghai timestamp and lower than the EIP-4844 activation timestamp - `ExecutionPayloadV3` **MUST** be returned if the payload `timestamp` is greater or equal to the EIP-4844 activation timestamp - `blockValue` : `QUANTITY`, 256 Bits - The expected value to be received by the `feeRecipient` in wei diff --git a/src/engine/experimental/eip6110.md b/src/engine/experimental/eip6110.md index 29178db7f..ed99c901f 100644 --- a/src/engine/experimental/eip6110.md +++ b/src/engine/experimental/eip6110.md @@ -66,7 +66,7 @@ This structure has the syntax of [`ExecutionPayloadV2`](../shanghai.md#execution * method: `engine_newPayloadV6110` * params: 1. [`ExecutionPayloadV2`](../shanghai.md#ExecutionPayloadV2) | [`ExecutionPayloadV6110`](#ExecutionPayloadV6110), where: - - `ExecutionPayloadV1` **MUST** be used if the `timestamp` value is lower than the EIP-6110 activation timestamp, + - `ExecutionPayloadType1` **MUST** be used if the `timestamp` value is lower than the EIP-6110 activation timestamp, - `ExecutionPayloadV6110` **MUST** be used if the `timestamp` value is greater or equal to the EIP-6110 activation timestamp, - Client software **MUST** return `-32602: Invalid params` error if the wrong version of the structure is used in the method call. * timeout: 8s diff --git a/src/engine/paris.md b/src/engine/paris.md index 70f73983a..352736967 100644 --- a/src/engine/paris.md +++ b/src/engine/paris.md @@ -7,38 +7,40 @@ Engine API structures and methods specified for Paris. -- [Structures](#structures) - - [ExecutionPayloadV1](#executionpayloadv1) - - [ForkchoiceStateV1](#forkchoicestatev1) - - [PayloadAttributesV1](#payloadattributesv1) - - [PayloadStatusV1](#payloadstatusv1) - - [TransitionConfigurationV1](#transitionconfigurationv1) -- [Routines](#routines) - - [Payload validation](#payload-validation) - - [Sync](#sync) - - [Payload building](#payload-building) -- [Methods](#methods) - - [engine_newPayloadV1](#engine_newpayloadv1) - - [Request](#request) - - [Response](#response) - - [Specification](#specification) - - [engine_forkchoiceUpdatedV1](#engine_forkchoiceupdatedv1) - - [Request](#request-1) - - [Response](#response-1) - - [Specification](#specification-1) - - [engine_getPayloadV1](#engine_getpayloadv1) - - [Request](#request-2) - - [Response](#response-2) - - [Specification](#specification-2) - - [engine_exchangeTransitionConfigurationV1](#engine_exchangetransitionconfigurationv1) - - [Request](#request-3) - - [Response](#response-3) - - [Specification](#specification-3) +- [Engine API -- Paris](#engine-api----paris) + - [Table of contents](#table-of-contents) + - [Structures](#structures) + - [ExecutionPayloadType1](#executionpayloadtype1) + - [ForkchoiceStateV1](#forkchoicestatev1) + - [PayloadAttributesV1](#payloadattributesv1) + - [PayloadStatusV1](#payloadstatusv1) + - [TransitionConfigurationV1](#transitionconfigurationv1) + - [Routines](#routines) + - [Payload validation](#payload-validation) + - [Sync](#sync) + - [Payload building](#payload-building) + - [Methods](#methods) + - [engine\_newPayloadV1](#engine_newpayloadv1) + - [Request](#request) + - [Response](#response) + - [Specification](#specification) + - [engine\_forkchoiceUpdatedV1](#engine_forkchoiceupdatedv1) + - [Request](#request-1) + - [Response](#response-1) + - [Specification](#specification-1) + - [engine\_getPayloadV1](#engine_getpayloadv1) + - [Request](#request-2) + - [Response](#response-2) + - [Specification](#specification-2) + - [engine\_exchangeTransitionConfigurationV1](#engine_exchangetransitionconfigurationv1) + - [Request](#request-3) + - [Response](#response-3) + - [Specification](#specification-3) ## Structures -### ExecutionPayloadV1 +### ExecutionPayloadType1 This structure maps on the [`ExecutionPayload`](https://github.com/ethereum/consensus-specs/blob/dev/specs/bellatrix/beacon-chain.md#ExecutionPayload) structure of the beacon chain spec. The fields are encoded as follows: @@ -144,7 +146,7 @@ The payload build process is specified as follows: * method: `engine_newPayloadV1` * params: - 1. [`ExecutionPayloadV1`](#ExecutionPayloadV1) + 1. [`ExecutionPayloadType1`](#ExecutionPayloadType1) * timeout: 8s #### Response @@ -237,7 +239,7 @@ The payload build process is specified as follows: #### Response -* result: [`ExecutionPayloadV1`](#ExecutionPayloadV1) +* result: [`ExecutionPayloadType1`](#ExecutionPayloadType1) * error: code and message set in case an exception happens while getting the payload. #### Specification diff --git a/src/engine/shanghai.md b/src/engine/shanghai.md index 82fc20f39..ad80d2568 100644 --- a/src/engine/shanghai.md +++ b/src/engine/shanghai.md @@ -53,7 +53,7 @@ The fields are encoded as follows: ### ExecutionPayloadV2 -This structure has the syntax of `ExecutionPayloadV1` and appends a single field: `withdrawals`. +This structure has the syntax of `ExecutionPayloadType1` and appends a single field: `withdrawals`. - `parentHash`: `DATA`, 32 Bytes - `feeRecipient`: `DATA`, 20 Bytes @@ -93,8 +93,8 @@ This structure has the syntax of `PayloadAttributesV1` and appends a single fiel * method: `engine_newPayloadV2` * params: - 1. [`ExecutionPayloadV1`](#./paris.md#ExecutionPayloadV1) | [`ExecutionPayloadV2`](#ExecutionPayloadV2), where: - - `ExecutionPayloadV1` **MUST** be used if the `timestamp` value is lower than the Shanghai timestamp, + 1. [`ExecutionPayloadType1`](#./paris.md#ExecutionPayloadType1) | [`ExecutionPayloadV2`](#ExecutionPayloadV2), where: + - `ExecutionPayloadType1` **MUST** be used if the `timestamp` value is lower than the Shanghai timestamp, - `ExecutionPayloadV2` **MUST** be used if the `timestamp` value is greater or equal to the Shanghai timestamp, - Client software **MUST** return `-32602: Invalid params` error if the wrong version of the structure is used in the method call. * timeout: 8s @@ -149,8 +149,8 @@ This method follows the same specification as [`engine_forkchoiceUpdatedV1`](./p #### Response * result: `object` - - `executionPayload`: [`ExecutionPayloadV1`](./paris.md#ExecutionPayloadV1) | [`ExecutionPayloadV2`](#ExecutionPayloadV2) where: - - `ExecutionPayloadV1` **MUST** be returned if the payload `timestamp` is lower than the Shanghai timestamp + - `executionPayload`: [`ExecutionPayloadType1`](./paris.md#ExecutionPayloadType1) | [`ExecutionPayloadV2`](#ExecutionPayloadV2) where: + - `ExecutionPayloadType1` **MUST** be returned if the payload `timestamp` is lower than the Shanghai timestamp - `ExecutionPayloadV2` **MUST** be returned if the payload `timestamp` is greater or equal to the Shanghai timestamp - `blockValue` : `QUANTITY`, 256 Bits - The expected value to be received by the `feeRecipient` in wei * error: code and message set in case an exception happens while getting the payload. From 23d1bcc42f98b18c480957d5d9768adfe1387989 Mon Sep 17 00:00:00 2001 From: Holger Drewes Date: Wed, 25 Jan 2023 21:54:52 +0100 Subject: [PATCH 03/14] Engine API: ForkchoiceStateV1 -> ForkchoiceStateType1 --- src/engine/paris.md | 6 +++--- src/engine/shanghai.md | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/src/engine/paris.md b/src/engine/paris.md index 352736967..7e8612403 100644 --- a/src/engine/paris.md +++ b/src/engine/paris.md @@ -11,7 +11,7 @@ Engine API structures and methods specified for Paris. - [Table of contents](#table-of-contents) - [Structures](#structures) - [ExecutionPayloadType1](#executionpayloadtype1) - - [ForkchoiceStateV1](#forkchoicestatev1) + - [ForkchoiceStateType1](#forkchoicestatetype1) - [PayloadAttributesV1](#payloadattributesv1) - [PayloadStatusV1](#payloadstatusv1) - [TransitionConfigurationV1](#transitionconfigurationv1) @@ -59,7 +59,7 @@ This structure maps on the [`ExecutionPayload`](https://github.com/ethereum/cons - `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) -### ForkchoiceStateV1 +### ForkchoiceStateType1 This structure encapsulates the fork choice state. The fields are encoded as follows: @@ -183,7 +183,7 @@ The payload build process is specified as follows: * method: "engine_forkchoiceUpdatedV1" * params: - 1. `forkchoiceState`: `Object` - instance of [`ForkchoiceStateV1`](#ForkchoiceStateV1) + 1. `forkchoiceState`: `Object` - instance of [`ForkchoiceStateType1`](#ForkchoiceStateType1) 2. `payloadAttributes`: `Object|null` - instance of [`PayloadAttributesV1`](#PayloadAttributesV1) or `null` * timeout: 8s diff --git a/src/engine/shanghai.md b/src/engine/shanghai.md index ad80d2568..0e1fed8c0 100644 --- a/src/engine/shanghai.md +++ b/src/engine/shanghai.md @@ -118,7 +118,7 @@ This method follows the same specification as [`engine_newPayloadV1`](./paris.md * method: "engine_forkchoiceUpdatedV2" * params: - 1. `forkchoiceState`: `Object` - instance of [`ForkchoiceStateV1`](./paris.md#ForkchoiceStateV1) + 1. `forkchoiceState`: `Object` - instance of [`ForkchoiceStateType1`](./paris.md#ForkchoiceStateType1) 2. `payloadAttributes`: `Object|null` - instance of [`PayloadAttributesV1`](./paris.md#PayloadAttributesV1) | [`PayloadAttributesV2`](#PayloadAttributesV2) or `null`, where: - `PayloadAttributesV1` **MUST** be used to build a payload with the `timestamp` value lower than the Shanghai timestamp, - `PayloadAttributesV2` **MUST** be used to build a payload with the `timestamp` value greater or equal to the Shanghai timestamp, From 8763f81b8a03c82260c41ba0b1c7b979abaff431 Mon Sep 17 00:00:00 2001 From: Holger Drewes Date: Wed, 25 Jan 2023 21:56:54 +0100 Subject: [PATCH 04/14] Engine API: PayloadAttributesV1 -> PayloadAttributesType1 --- src/engine/paris.md | 6 +++--- src/engine/shanghai.md | 6 +++--- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/src/engine/paris.md b/src/engine/paris.md index 7e8612403..083a8c6a8 100644 --- a/src/engine/paris.md +++ b/src/engine/paris.md @@ -12,7 +12,7 @@ Engine API structures and methods specified for Paris. - [Structures](#structures) - [ExecutionPayloadType1](#executionpayloadtype1) - [ForkchoiceStateType1](#forkchoicestatetype1) - - [PayloadAttributesV1](#payloadattributesv1) + - [PayloadAttributesType1](#payloadattributestype1) - [PayloadStatusV1](#payloadstatusv1) - [TransitionConfigurationV1](#transitionconfigurationv1) - [Routines](#routines) @@ -69,7 +69,7 @@ This structure encapsulates the fork choice state. The fields are encoded as fol *Note:* `safeBlockHash` and `finalizedBlockHash` fields are allowed to have `0x0000000000000000000000000000000000000000000000000000000000000000` value unless transition block is finalized. -### PayloadAttributesV1 +### PayloadAttributesType1 This structure contains the attributes required to initiate a payload build process in the context of an `engine_forkchoiceUpdated` call. The fields are encoded as follows: @@ -184,7 +184,7 @@ The payload build process is specified as follows: * method: "engine_forkchoiceUpdatedV1" * params: 1. `forkchoiceState`: `Object` - instance of [`ForkchoiceStateType1`](#ForkchoiceStateType1) - 2. `payloadAttributes`: `Object|null` - instance of [`PayloadAttributesV1`](#PayloadAttributesV1) or `null` + 2. `payloadAttributes`: `Object|null` - instance of [`PayloadAttributesType1`](#PayloadAttributesType1) or `null` * timeout: 8s #### Response diff --git a/src/engine/shanghai.md b/src/engine/shanghai.md index 0e1fed8c0..28e396609 100644 --- a/src/engine/shanghai.md +++ b/src/engine/shanghai.md @@ -78,7 +78,7 @@ This structure contains a body of an execution payload. The fields are encoded a ### PayloadAttributesV2 -This structure has the syntax of `PayloadAttributesV1` and appends a single field: `withdrawals`. +This structure has the syntax of `PayloadAttributesType1` and appends a single field: `withdrawals`. - `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 @@ -119,8 +119,8 @@ This method follows the same specification as [`engine_newPayloadV1`](./paris.md * method: "engine_forkchoiceUpdatedV2" * params: 1. `forkchoiceState`: `Object` - instance of [`ForkchoiceStateType1`](./paris.md#ForkchoiceStateType1) - 2. `payloadAttributes`: `Object|null` - instance of [`PayloadAttributesV1`](./paris.md#PayloadAttributesV1) | [`PayloadAttributesV2`](#PayloadAttributesV2) or `null`, where: - - `PayloadAttributesV1` **MUST** be used to build a payload with the `timestamp` value lower than the Shanghai timestamp, + 2. `payloadAttributes`: `Object|null` - instance of [`PayloadAttributesType1`](./paris.md#PayloadAttributesType1) | [`PayloadAttributesV2`](#PayloadAttributesV2) or `null`, where: + - `PayloadAttributesType1` **MUST** be used to build a payload with the `timestamp` value lower than the Shanghai timestamp, - `PayloadAttributesV2` **MUST** be used to build a payload with the `timestamp` value greater or equal to the Shanghai timestamp, - Client software **MUST** return `-32602: Invalid params` error if the wrong version of the structure is used in the method call. * timeout: 8s From db1aa1cffdc12249ba47d731ce12e0be8bd94878 Mon Sep 17 00:00:00 2001 From: Holger Drewes Date: Wed, 25 Jan 2023 21:57:51 +0100 Subject: [PATCH 05/14] Engine API: PayloadStatusV1 -> PayloadStatusType1 --- src/engine/paris.md | 8 ++++---- src/engine/shanghai.md | 2 +- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/src/engine/paris.md b/src/engine/paris.md index 083a8c6a8..72d706345 100644 --- a/src/engine/paris.md +++ b/src/engine/paris.md @@ -13,7 +13,7 @@ Engine API structures and methods specified for Paris. - [ExecutionPayloadType1](#executionpayloadtype1) - [ForkchoiceStateType1](#forkchoicestatetype1) - [PayloadAttributesType1](#payloadattributestype1) - - [PayloadStatusV1](#payloadstatusv1) + - [PayloadStatusType1](#payloadstatustype1) - [TransitionConfigurationV1](#transitionconfigurationv1) - [Routines](#routines) - [Payload validation](#payload-validation) @@ -77,7 +77,7 @@ This structure contains the attributes required to initiate a payload build proc - `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 -### PayloadStatusV1 +### PayloadStatusType1 This structure contains the result of processing a payload. The fields are encoded as follows: @@ -151,7 +151,7 @@ The payload build process is specified as follows: #### Response -* result: [`PayloadStatusV1`](#PayloadStatusV1) +* result: [`PayloadStatusType1`](#PayloadStatusType1) * error: code and message set in case an exception happens while processing the payload. #### Specification @@ -190,7 +190,7 @@ The payload build process is specified as follows: #### Response * result: `object` - - `payloadStatus`: [`PayloadStatusV1`](#PayloadStatusV1); values of the `status` field in the context of this method are restricted to the following subset: + - `payloadStatus`: [`PayloadStatusType1`](#PayloadStatusType1); values of the `status` field in the context of this method are restricted to the following subset: * `"VALID"` * `"INVALID"` * `"SYNCING"` diff --git a/src/engine/shanghai.md b/src/engine/shanghai.md index 28e396609..74ed66423 100644 --- a/src/engine/shanghai.md +++ b/src/engine/shanghai.md @@ -101,7 +101,7 @@ This structure has the syntax of `PayloadAttributesType1` and appends a single f #### Response -* result: [`PayloadStatusV1`](./paris.md#payloadstatusv1), values of the `status` field are restricted in the following way: +* result: [`PayloadStatusType1`](./paris.md#payloadstatusv1), values of the `status` field are restricted in the following way: - `INVALID_BLOCK_HASH` status value is supplanted by `INVALID`. * error: code and message set in case an exception happens while processing the payload. From d5f12a16ebd61a566124b8eb7a87af9c1b377417 Mon Sep 17 00:00:00 2001 From: Holger Drewes Date: Wed, 25 Jan 2023 21:58:39 +0100 Subject: [PATCH 06/14] Engine API: TransitionConfigurationV1 -> TransitionConfigurationType1 --- src/engine/paris.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/src/engine/paris.md b/src/engine/paris.md index 72d706345..efba17c87 100644 --- a/src/engine/paris.md +++ b/src/engine/paris.md @@ -14,7 +14,7 @@ Engine API structures and methods specified for Paris. - [ForkchoiceStateType1](#forkchoicestatetype1) - [PayloadAttributesType1](#payloadattributestype1) - [PayloadStatusType1](#payloadstatustype1) - - [TransitionConfigurationV1](#transitionconfigurationv1) + - [TransitionConfigurationType1](#transitionconfigurationtype1) - [Routines](#routines) - [Payload validation](#payload-validation) - [Sync](#sync) @@ -32,7 +32,7 @@ Engine API structures and methods specified for Paris. - [Request](#request-2) - [Response](#response-2) - [Specification](#specification-2) - - [engine\_exchangeTransitionConfigurationV1](#engine_exchangetransitionconfigurationv1) + - [engine\_exchangeTransitionConfigurationType1](#engine_exchangetransitionconfigurationtype1) - [Request](#request-3) - [Response](#response-3) - [Specification](#specification-3) @@ -85,7 +85,7 @@ This structure contains the result of processing a payload. The fields are encod - `latestValidHash`: `DATA|null`, 32 Bytes - the hash of the most recent *valid* block in the branch defined by payload and its ancestors - `validationError`: `String|null` - a message providing additional details on the validation error if the payload is classified as `INVALID` or `INVALID_BLOCK_HASH`. -### TransitionConfigurationV1 +### TransitionConfigurationType1 This structure contains configurable settings of the transition process. The fields are encoded as follows: - `terminalTotalDifficulty`: `QUANTITY`, 256 Bits - maps on the `TERMINAL_TOTAL_DIFFICULTY` parameter of [EIP-3675](https://eips.ethereum.org/EIPS/eip-3675#client-software-configuration) @@ -250,18 +250,18 @@ The payload build process is specified as follows: 3. Client software **MAY** stop the corresponding build process after serving this call. -### engine_exchangeTransitionConfigurationV1 +### engine_exchangeTransitionConfigurationType1 #### Request -* method: `engine_exchangeTransitionConfigurationV1` +* method: `engine_exchangeTransitionConfigurationType1` * params: - 1. `transitionConfiguration`: `Object` - instance of [`TransitionConfigurationV1`](#TransitionConfigurationV1) + 1. `transitionConfiguration`: `Object` - instance of [`TransitionConfigurationType1`](#TransitionConfigurationType1) * timeout: 1s #### Response -* result: [`TransitionConfigurationV1`](#TransitionConfigurationV1) +* result: [`TransitionConfigurationType1`](#TransitionConfigurationType1) * error: code and message set in case an exception happens while getting a transition configuration. #### Specification From f2dbc3f1cc647936aef3b0a050745fbb1de02926 Mon Sep 17 00:00:00 2001 From: Holger Drewes Date: Wed, 25 Jan 2023 22:07:08 +0100 Subject: [PATCH 07/14] Engine API: WithdrawalV1 -> WithdrawalType1 --- src/engine/experimental/blob-extension.md | 2 +- src/engine/experimental/eip6110.md | 2 +- src/engine/shanghai.md | 62 ++++++++++++----------- 3 files changed, 34 insertions(+), 32 deletions(-) diff --git a/src/engine/experimental/blob-extension.md b/src/engine/experimental/blob-extension.md index b88540c32..d4039512f 100644 --- a/src/engine/experimental/blob-extension.md +++ b/src/engine/experimental/blob-extension.md @@ -48,7 +48,7 @@ This structure has the syntax of `ExecutionPayloadV2` and appends a single field - `excessDataGas`: `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. +- `withdrawals`: `Array of WithdrawalType1` - Array of withdrawals, each object is an `OBJECT` containing the fields of a `WithdrawalType1` structure. ### BlobsBundleV1 diff --git a/src/engine/experimental/eip6110.md b/src/engine/experimental/eip6110.md index ed99c901f..351051e05 100644 --- a/src/engine/experimental/eip6110.md +++ b/src/engine/experimental/eip6110.md @@ -54,7 +54,7 @@ This structure has the syntax of [`ExecutionPayloadV2`](../shanghai.md#execution - `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. +- `withdrawals`: `Array of WithdrawalType1` - Array of withdrawals, each object is an `OBJECT` containing the fields of a `WithdrawalType1` structure. - `deposits`: `Array of DepositV1` - Array of deposits, each object is an `OBJECT` containing the fields of a `DepositV1` structure. ## Methods diff --git a/src/engine/shanghai.md b/src/engine/shanghai.md index 74ed66423..2b08ee693 100644 --- a/src/engine/shanghai.md +++ b/src/engine/shanghai.md @@ -7,38 +7,40 @@ Engine API changes introduced in Shanghai. -- [Structures](#structures) - - [WithdrawalV1](#withdrawalv1) - - [ExecutionPayloadV2](#executionpayloadv2) - - [ExecutionPayloadBodyV1](#executionpayloadbodyv1) - - [PayloadAttributesV2](#payloadattributesv2) -- [Methods](#methods) - - [engine_newPayloadV2](#engine_newpayloadv2) - - [Request](#request) - - [Response](#response) - - [Specification](#specification) - - [engine_forkchoiceUpdatedV2](#engine_forkchoiceupdatedv2) - - [Request](#request-1) - - [Response](#response-1) - - [Specification](#specification-1) - - [engine_getPayloadV2](#engine_getpayloadv2) - - [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) +- [Engine API -- Shanghai](#engine-api----shanghai) + - [Table of contents](#table-of-contents) + - [Structures](#structures) + - [WithdrawalType1](#withdrawaltype1) + - [ExecutionPayloadV2](#executionpayloadv2) + - [ExecutionPayloadBodyV1](#executionpayloadbodyv1) + - [PayloadAttributesV2](#payloadattributesv2) + - [Methods](#methods) + - [engine\_newPayloadV2](#engine_newpayloadv2) + - [Request](#request) + - [Response](#response) + - [Specification](#specification) + - [engine\_forkchoiceUpdatedV2](#engine_forkchoiceupdatedv2) + - [Request](#request-1) + - [Response](#response-1) + - [Specification](#specification-1) + - [engine\_getPayloadV2](#engine_getpayloadv2) + - [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) ## Structures -### WithdrawalV1 +### WithdrawalType1 This structure maps onto the validator withdrawal object from the beacon chain spec. The fields are encoded as follows: @@ -69,12 +71,12 @@ This structure has the syntax of `ExecutionPayloadType1` and appends a single fi - `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. +- `withdrawals`: `Array of WithdrawalType1` - Array of withdrawals, each object is an `OBJECT` containing the fields of a `WithdrawalType1` 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. +- `withdrawals`: `Array of WithdrawalType1` - Array of withdrawals, each object is an `OBJECT` containing the fields of a `WithdrawalType1` structure. ### PayloadAttributesV2 @@ -83,7 +85,7 @@ This structure has the syntax of `PayloadAttributesType1` and appends a single f - `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. +- `withdrawals`: `Array of WithdrawalType1` - Array of withdrawals, each object is an `OBJECT` containing the fields of a `WithdrawalType1` structure. ## Methods From 9225181f95b65bc979d9e994cbdfd2eef8c4765d Mon Sep 17 00:00:00 2001 From: Holger Drewes Date: Wed, 25 Jan 2023 22:08:56 +0100 Subject: [PATCH 08/14] Engine API: ExecutionPayloadV2 -> ExecutionPayloadType2 --- src/engine/experimental/blob-extension.md | 10 +++++----- src/engine/experimental/eip6110.md | 4 ++-- src/engine/shanghai.md | 12 ++++++------ 3 files changed, 13 insertions(+), 13 deletions(-) diff --git a/src/engine/experimental/blob-extension.md b/src/engine/experimental/blob-extension.md index d4039512f..bc22be341 100644 --- a/src/engine/experimental/blob-extension.md +++ b/src/engine/experimental/blob-extension.md @@ -31,7 +31,7 @@ This extension is backwards-compatible, but not part of the initial Engine API. ### ExecutionPayloadV3 -This structure has the syntax of `ExecutionPayloadV2` and appends a single field: `excessDataGas`. +This structure has the syntax of `ExecutionPayloadType2` and appends a single field: `excessDataGas`. - `parentHash`: `DATA`, 32 Bytes - `feeRecipient`: `DATA`, 20 Bytes @@ -66,9 +66,9 @@ The fields are encoded as follows: * method: `engine_newPayloadV3` * params: - 1. [`ExecutionPayloadType1`](../paris.md#ExecutionPayloadType1) | [`ExecutionPayloadV2`](../shanghai.md#ExecutionPayloadV2) | [`ExecutionPayloadV3`](#ExecutionPayloadV3), where: + 1. [`ExecutionPayloadType1`](../paris.md#ExecutionPayloadType1) | [`ExecutionPayloadType2`](../shanghai.md#ExecutionPayloadType2) | [`ExecutionPayloadV3`](#ExecutionPayloadV3), where: - `ExecutionPayloadType1` **MUST** be used if the `timestamp` value is lower than the Shanghai timestamp, - - `ExecutionPayloadV2` **MUST** be used if the `timestamp` value is greater or equal to the Shanghai and lower than the EIP-4844 activation timestamp, + - `ExecutionPayloadType2` **MUST** be used if the `timestamp` value is greater or equal to the Shanghai and lower than the EIP-4844 activation timestamp, - `ExecutionPayloadV3` **MUST** be used if the `timestamp` value is greater or equal to the EIP-4844 activation timestamp, - Client software **MUST** return `-32602: Invalid params` error if the wrong version of the structure is used in the method call. @@ -92,9 +92,9 @@ Refer to the response for `engine_newPayloadV2`. #### Response * result: `object` - - `executionPayload`: [`ExecutionPayloadType1`](../paris.md#ExecutionPayloadType1) | [`ExecutionPayloadV2`](../shanghai.md#ExecutionPayloadV2) | [`ExecutionPayloadV3`](#ExecutionPayloadV3) where: + - `executionPayload`: [`ExecutionPayloadType1`](../paris.md#ExecutionPayloadType1) | [`ExecutionPayloadType2`](../shanghai.md#ExecutionPayloadType2) | [`ExecutionPayloadV3`](#ExecutionPayloadV3) where: - `ExecutionPayloadType1` **MUST** be returned if the payload `timestamp` is lower than the Shanghai timestamp - - `ExecutionPayloadV2` **MUST** be returned if the payload `timestamp` is greater or equal to the Shanghai timestamp and lower than the EIP-4844 activation timestamp + - `ExecutionPayloadType2` **MUST** be returned if the payload `timestamp` is greater or equal to the Shanghai timestamp and lower than the EIP-4844 activation timestamp - `ExecutionPayloadV3` **MUST** be returned if the payload `timestamp` is greater or equal to the EIP-4844 activation timestamp - `blockValue` : `QUANTITY`, 256 Bits - The expected value to be received by the `feeRecipient` in wei * error: code and message set in case an exception happens while getting the payload. diff --git a/src/engine/experimental/eip6110.md b/src/engine/experimental/eip6110.md index 351051e05..5067ad52d 100644 --- a/src/engine/experimental/eip6110.md +++ b/src/engine/experimental/eip6110.md @@ -38,7 +38,7 @@ The fields are encoded as follows: ### ExecutionPayloadV6110 -This structure has the syntax of [`ExecutionPayloadV2`](../shanghai.md#executionpayloadv2) and appends a single field: `deposits`. +This structure has the syntax of [`ExecutionPayloadType2`](../shanghai.md#executionpayloadv2) and appends a single field: `deposits`. - `parentHash`: `DATA`, 32 Bytes - `feeRecipient`: `DATA`, 20 Bytes @@ -65,7 +65,7 @@ This structure has the syntax of [`ExecutionPayloadV2`](../shanghai.md#execution * method: `engine_newPayloadV6110` * params: - 1. [`ExecutionPayloadV2`](../shanghai.md#ExecutionPayloadV2) | [`ExecutionPayloadV6110`](#ExecutionPayloadV6110), where: + 1. [`ExecutionPayloadType2`](../shanghai.md#ExecutionPayloadType2) | [`ExecutionPayloadV6110`](#ExecutionPayloadV6110), where: - `ExecutionPayloadType1` **MUST** be used if the `timestamp` value is lower than the EIP-6110 activation timestamp, - `ExecutionPayloadV6110` **MUST** be used if the `timestamp` value is greater or equal to the EIP-6110 activation timestamp, - Client software **MUST** return `-32602: Invalid params` error if the wrong version of the structure is used in the method call. diff --git a/src/engine/shanghai.md b/src/engine/shanghai.md index 2b08ee693..94640630c 100644 --- a/src/engine/shanghai.md +++ b/src/engine/shanghai.md @@ -11,7 +11,7 @@ Engine API changes introduced in Shanghai. - [Table of contents](#table-of-contents) - [Structures](#structures) - [WithdrawalType1](#withdrawaltype1) - - [ExecutionPayloadV2](#executionpayloadv2) + - [ExecutionPayloadType2](#executionpayloadtype2) - [ExecutionPayloadBodyV1](#executionpayloadbodyv1) - [PayloadAttributesV2](#payloadattributesv2) - [Methods](#methods) @@ -53,7 +53,7 @@ The fields are encoded as follows: *Note*: the `amount` value is represented on the beacon chain as a little-endian value in units of Gwei, whereas the `amount` in this structure *MUST* be converted to a big-endian value in units of Gwei. -### ExecutionPayloadV2 +### ExecutionPayloadType2 This structure has the syntax of `ExecutionPayloadType1` and appends a single field: `withdrawals`. @@ -95,9 +95,9 @@ This structure has the syntax of `PayloadAttributesType1` and appends a single f * method: `engine_newPayloadV2` * params: - 1. [`ExecutionPayloadType1`](#./paris.md#ExecutionPayloadType1) | [`ExecutionPayloadV2`](#ExecutionPayloadV2), where: + 1. [`ExecutionPayloadType1`](#./paris.md#ExecutionPayloadType1) | [`ExecutionPayloadType2`](#ExecutionPayloadType2), where: - `ExecutionPayloadType1` **MUST** be used if the `timestamp` value is lower than the Shanghai timestamp, - - `ExecutionPayloadV2` **MUST** be used if the `timestamp` value is greater or equal to the Shanghai timestamp, + - `ExecutionPayloadType2` **MUST** be used if the `timestamp` value is greater or equal to the Shanghai timestamp, - Client software **MUST** return `-32602: Invalid params` error if the wrong version of the structure is used in the method call. * timeout: 8s @@ -151,9 +151,9 @@ This method follows the same specification as [`engine_forkchoiceUpdatedV1`](./p #### Response * result: `object` - - `executionPayload`: [`ExecutionPayloadType1`](./paris.md#ExecutionPayloadType1) | [`ExecutionPayloadV2`](#ExecutionPayloadV2) where: + - `executionPayload`: [`ExecutionPayloadType1`](./paris.md#ExecutionPayloadType1) | [`ExecutionPayloadType2`](#ExecutionPayloadType2) where: - `ExecutionPayloadType1` **MUST** be returned if the payload `timestamp` is lower than the Shanghai timestamp - - `ExecutionPayloadV2` **MUST** be returned if the payload `timestamp` is greater or equal to the Shanghai timestamp + - `ExecutionPayloadType2` **MUST** be returned if the payload `timestamp` is greater or equal to the Shanghai timestamp - `blockValue` : `QUANTITY`, 256 Bits - The expected value to be received by the `feeRecipient` in wei * error: code and message set in case an exception happens while getting the payload. From 478a170a2472ebcd9297e433354f19974abd9a0e Mon Sep 17 00:00:00 2001 From: Holger Drewes Date: Wed, 25 Jan 2023 22:10:48 +0100 Subject: [PATCH 09/14] Engine API: ExecutionPayloadBodyV1 -> ExecutionPayloadBodyType1 --- src/engine/shanghai.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/src/engine/shanghai.md b/src/engine/shanghai.md index 94640630c..bf507b88d 100644 --- a/src/engine/shanghai.md +++ b/src/engine/shanghai.md @@ -12,7 +12,7 @@ Engine API changes introduced in Shanghai. - [Structures](#structures) - [WithdrawalType1](#withdrawaltype1) - [ExecutionPayloadType2](#executionpayloadtype2) - - [ExecutionPayloadBodyV1](#executionpayloadbodyv1) + - [ExecutionPayloadBodyType1](#executionpayloadbodytype1) - [PayloadAttributesV2](#payloadattributesv2) - [Methods](#methods) - [engine\_newPayloadV2](#engine_newpayloadv2) @@ -73,7 +73,7 @@ This structure has the syntax of `ExecutionPayloadType1` and appends a single fi - `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 WithdrawalType1` - Array of withdrawals, each object is an `OBJECT` containing the fields of a `WithdrawalType1` structure. -### ExecutionPayloadBodyV1 +### ExecutionPayloadBodyType1 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 WithdrawalType1` - Array of withdrawals, each object is an `OBJECT` containing the fields of a `WithdrawalType1` structure. @@ -174,12 +174,12 @@ This method follows the same specification as [`engine_getPayloadV1`](./paris.md #### Response -* result: `Array of ExecutionPayloadBodyV1` - Array of [`ExecutionPayloadBodyV1`](#ExecutionPayloadBodyV1) objects. +* result: `Array of ExecutionPayloadBodyType1` - Array of [`ExecutionPayloadBodyType1`](#ExecutionPayloadBodyType1) 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. Given array of block hashes client software **MUST** respond with array of `ExecutionPayloadBodyType1` 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]`. @@ -205,12 +205,12 @@ This method follows the same specification as [`engine_getPayloadV1`](./paris.md #### Response -* result: `Array of ExecutionPayloadBodyV1` - Array of [`ExecutionPayloadBodyV1`](#ExecutionPayloadBodyV1) objects. +* result: `Array of ExecutionPayloadBodyType1` - Array of [`ExecutionPayloadBodyType1`](#ExecutionPayloadBodyType1) 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. Given a `start` and a `count`, the client software **MUST** respond with array of `ExecutionPayloadBodyType1` 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. The call **MUST** return `-38004: Too large request` error if the requested range is too large. From e244defe064c51c403ccd4f55cae8bf2c5b58dff Mon Sep 17 00:00:00 2001 From: Holger Drewes Date: Wed, 25 Jan 2023 22:12:11 +0100 Subject: [PATCH 10/14] Engine API: PayloadAttributesV2 -> PayloadAttributesType2 --- src/engine/shanghai.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/engine/shanghai.md b/src/engine/shanghai.md index bf507b88d..72f76d6f3 100644 --- a/src/engine/shanghai.md +++ b/src/engine/shanghai.md @@ -13,7 +13,7 @@ Engine API changes introduced in Shanghai. - [WithdrawalType1](#withdrawaltype1) - [ExecutionPayloadType2](#executionpayloadtype2) - [ExecutionPayloadBodyType1](#executionpayloadbodytype1) - - [PayloadAttributesV2](#payloadattributesv2) + - [PayloadAttributesType2](#payloadattributestype2) - [Methods](#methods) - [engine\_newPayloadV2](#engine_newpayloadv2) - [Request](#request) @@ -78,7 +78,7 @@ This structure contains a body of an execution payload. The fields are encoded a - `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 WithdrawalType1` - Array of withdrawals, each object is an `OBJECT` containing the fields of a `WithdrawalType1` structure. -### PayloadAttributesV2 +### PayloadAttributesType2 This structure has the syntax of `PayloadAttributesType1` and appends a single field: `withdrawals`. @@ -121,9 +121,9 @@ This method follows the same specification as [`engine_newPayloadV1`](./paris.md * method: "engine_forkchoiceUpdatedV2" * params: 1. `forkchoiceState`: `Object` - instance of [`ForkchoiceStateType1`](./paris.md#ForkchoiceStateType1) - 2. `payloadAttributes`: `Object|null` - instance of [`PayloadAttributesType1`](./paris.md#PayloadAttributesType1) | [`PayloadAttributesV2`](#PayloadAttributesV2) or `null`, where: + 2. `payloadAttributes`: `Object|null` - instance of [`PayloadAttributesType1`](./paris.md#PayloadAttributesType1) | [`PayloadAttributesType2`](#PayloadAttributesType2) or `null`, where: - `PayloadAttributesType1` **MUST** be used to build a payload with the `timestamp` value lower than the Shanghai timestamp, - - `PayloadAttributesV2` **MUST** be used to build a payload with the `timestamp` value greater or equal to the Shanghai timestamp, + - `PayloadAttributesType2` **MUST** be used to build a payload with the `timestamp` value greater or equal to the Shanghai timestamp, - Client software **MUST** return `-32602: Invalid params` error if the wrong version of the structure is used in the method call. * timeout: 8s From cf157ba438695324da148a54c518ffdfff111e49 Mon Sep 17 00:00:00 2001 From: Holger Drewes Date: Wed, 25 Jan 2023 22:16:50 +0100 Subject: [PATCH 11/14] Engine API: ExecutionPayloadV3 -> ExecutionPayloadType3 --- src/engine/experimental/blob-extension.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/src/engine/experimental/blob-extension.md b/src/engine/experimental/blob-extension.md index bc22be341..2f9123528 100644 --- a/src/engine/experimental/blob-extension.md +++ b/src/engine/experimental/blob-extension.md @@ -4,18 +4,18 @@ - [Shard Blob Extension](#shard-blob-extension) - [Structures](#structures) - - [ExecutionPayloadV3](#executionpayloadv3) + - [ExecutionPayloadType3](#executionpayloadtype3) - [BlobsBundleV1](#blobsbundlev1) - [Methods](#methods) - - [engine_newPayloadV3](#engine_newpayloadv3) + - [engine\_newPayloadV3](#engine_newpayloadv3) - [Request](#request) - [Specification](#specification) - [Response](#response) - - [engine_getPayloadV3](#engine_getpayloadv3) + - [engine\_getPayloadV3](#engine_getpayloadv3) - [Request](#request-1) - [Response](#response-1) - [Specification](#specification-1) - - [engine_getBlobsBundleV1](#engine_getblobsbundlev1) + - [engine\_getBlobsBundleV1](#engine_getblobsbundlev1) - [Request](#request-2) - [Response](#response-2) - [Specification](#specification-2) @@ -29,7 +29,7 @@ This extension is backwards-compatible, but not part of the initial Engine API. ## Structures -### ExecutionPayloadV3 +### ExecutionPayloadType3 This structure has the syntax of `ExecutionPayloadType2` and appends a single field: `excessDataGas`. @@ -66,10 +66,10 @@ The fields are encoded as follows: * method: `engine_newPayloadV3` * params: - 1. [`ExecutionPayloadType1`](../paris.md#ExecutionPayloadType1) | [`ExecutionPayloadType2`](../shanghai.md#ExecutionPayloadType2) | [`ExecutionPayloadV3`](#ExecutionPayloadV3), where: + 1. [`ExecutionPayloadType1`](../paris.md#ExecutionPayloadType1) | [`ExecutionPayloadType2`](../shanghai.md#ExecutionPayloadType2) | [`ExecutionPayloadType3`](#ExecutionPayloadType3), where: - `ExecutionPayloadType1` **MUST** be used if the `timestamp` value is lower than the Shanghai timestamp, - `ExecutionPayloadType2` **MUST** be used if the `timestamp` value is greater or equal to the Shanghai and lower than the EIP-4844 activation timestamp, - - `ExecutionPayloadV3` **MUST** be used if the `timestamp` value is greater or equal to the EIP-4844 activation timestamp, + - `ExecutionPayloadType3` **MUST** be used if the `timestamp` value is greater or equal to the EIP-4844 activation timestamp, - Client software **MUST** return `-32602: Invalid params` error if the wrong version of the structure is used in the method call. #### Specification @@ -92,10 +92,10 @@ Refer to the response for `engine_newPayloadV2`. #### Response * result: `object` - - `executionPayload`: [`ExecutionPayloadType1`](../paris.md#ExecutionPayloadType1) | [`ExecutionPayloadType2`](../shanghai.md#ExecutionPayloadType2) | [`ExecutionPayloadV3`](#ExecutionPayloadV3) where: + - `executionPayload`: [`ExecutionPayloadType1`](../paris.md#ExecutionPayloadType1) | [`ExecutionPayloadType2`](../shanghai.md#ExecutionPayloadType2) | [`ExecutionPayloadType3`](#ExecutionPayloadType3) where: - `ExecutionPayloadType1` **MUST** be returned if the payload `timestamp` is lower than the Shanghai timestamp - `ExecutionPayloadType2` **MUST** be returned if the payload `timestamp` is greater or equal to the Shanghai timestamp and lower than the EIP-4844 activation timestamp - - `ExecutionPayloadV3` **MUST** be returned if the payload `timestamp` is greater or equal to the EIP-4844 activation timestamp + - `ExecutionPayloadType3` **MUST** be returned if the payload `timestamp` is greater or equal to the EIP-4844 activation timestamp - `blockValue` : `QUANTITY`, 256 Bits - The expected value to be received by the `feeRecipient` in wei * error: code and message set in case an exception happens while getting the payload. From 1d9b5db48e025f24fa50695c18d201d91e14817b Mon Sep 17 00:00:00 2001 From: Holger Drewes Date: Wed, 25 Jan 2023 22:17:31 +0100 Subject: [PATCH 12/14] Engine API: BlobsBundleV1 -> BlobsBundleType1 --- src/engine/experimental/blob-extension.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/src/engine/experimental/blob-extension.md b/src/engine/experimental/blob-extension.md index 2f9123528..7dbd761ad 100644 --- a/src/engine/experimental/blob-extension.md +++ b/src/engine/experimental/blob-extension.md @@ -5,7 +5,7 @@ - [Shard Blob Extension](#shard-blob-extension) - [Structures](#structures) - [ExecutionPayloadType3](#executionpayloadtype3) - - [BlobsBundleV1](#blobsbundlev1) + - [BlobsBundleType1](#blobsbundletype1) - [Methods](#methods) - [engine\_newPayloadV3](#engine_newpayloadv3) - [Request](#request) @@ -15,7 +15,7 @@ - [Request](#request-1) - [Response](#response-1) - [Specification](#specification-1) - - [engine\_getBlobsBundleV1](#engine_getblobsbundlev1) + - [engine\_getBlobsBundleType1](#engine_getblobsbundletype1) - [Request](#request-2) - [Response](#response-2) - [Specification](#specification-2) @@ -50,7 +50,7 @@ This structure has the syntax of `ExecutionPayloadType2` and appends a single fi - `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 WithdrawalType1` - Array of withdrawals, each object is an `OBJECT` containing the fields of a `WithdrawalType1` structure. -### BlobsBundleV1 +### BlobsBundleType1 The fields are encoded as follows: @@ -103,7 +103,7 @@ Refer to the response for `engine_newPayloadV2`. Refer to the specification for `engine_getPayloadV2`. -### engine_getBlobsBundleV1 +### engine_getBlobsBundleType1 This method retrieves the blobs and their respective KZG commitments corresponding to the `versioned_hashes` included in the blob transactions of the referenced execution payload. @@ -113,20 +113,20 @@ The separation of concerns aims to minimize changes during the testing phase of #### Request -* method: `engine_getBlobsBundleV1` +* method: `engine_getBlobsBundleType1` * params: 1. `payloadId`: `DATA`, 8 Bytes - Identifier of the payload build process * timeout: 1s #### Response -* result: [`BlobsBundleV1`](#BlobsBundleV1) +* result: [`BlobsBundleType1`](#BlobsBundleType1) * error: code and message set in case an exception happens while getting the blobs bundle. #### Specification 1. Given the `payloadId` client software **MUST** return the blobs bundle corresponding to the most recent version of the payload that was served with `engine_getPayload`, if any, - and halt any further changes to the payload. The `engine_getBlobsBundleV1` and `engine_getPayloadV2` results **MUST** be consistent as outlined in items 3, 4 and 5 below. + and halt any further changes to the payload. The `engine_getBlobsBundleType1` and `engine_getPayloadV2` results **MUST** be consistent as outlined in items 3, 4 and 5 below. 2. The call **MUST** return `-32001: Unknown payload` error if the build process identified by the `payloadId` does not exist. Note that a payload without any blobs **MUST** return an empty `blobs` and `kzgs` list, not an error. From 9a9d35cf135f1c7a271fe431d7c54206456dbbed Mon Sep 17 00:00:00 2001 From: Holger Drewes Date: Wed, 25 Jan 2023 22:18:35 +0100 Subject: [PATCH 13/14] Engine API: DepositV1 -> DepositType1 --- src/engine/experimental/eip6110.md | 30 ++++++++++++++++-------------- 1 file changed, 16 insertions(+), 14 deletions(-) diff --git a/src/engine/experimental/eip6110.md b/src/engine/experimental/eip6110.md index 5067ad52d..0945991a1 100644 --- a/src/engine/experimental/eip6110.md +++ b/src/engine/experimental/eip6110.md @@ -7,24 +7,26 @@ Engine API changes introduced in EIP-6110. -- [Structures](#structures) - - [DepositV1](#depositv1) - - [ExecutionPayloadV6110](#executionpayloadv6110) -- [Methods](#methods) - - [engine_newPayloadV6110](#engine_newpayloadv6110) - - [Request](#request) - - [Response](#response) - - [Specification](#specification) - - [engine_getPayloadV6110](#engine_getpayloadv6110) - - [Request](#request-1) - - [Response](#response-1) - - [Specification](#specification-1) +- [Engine API -- EIP-6110](#engine-api----eip-6110) + - [Table of contents](#table-of-contents) + - [Structures](#structures) + - [DepositType1](#deposittype1) + - [ExecutionPayloadV6110](#executionpayloadv6110) + - [Methods](#methods) + - [engine\_newPayloadV6110](#engine_newpayloadv6110) + - [Request](#request) + - [Response](#response) + - [Specification](#specification) + - [engine\_getPayloadV6110](#engine_getpayloadv6110) + - [Request](#request-1) + - [Response](#response-1) + - [Specification](#specification-1) ## Structures -### DepositV1 +### DepositType1 This structure maps onto the deposit object from [EIP-6110](https://eips.ethereum.org/EIPS/eip-6110). The fields are encoded as follows: @@ -55,7 +57,7 @@ This structure has the syntax of [`ExecutionPayloadType2`](../shanghai.md#execut - `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 WithdrawalType1` - Array of withdrawals, each object is an `OBJECT` containing the fields of a `WithdrawalType1` structure. -- `deposits`: `Array of DepositV1` - Array of deposits, each object is an `OBJECT` containing the fields of a `DepositV1` structure. +- `deposits`: `Array of DepositType1` - Array of deposits, each object is an `OBJECT` containing the fields of a `DepositType1` structure. ## Methods From 56732ee5209693e9e76e3f9205fc12f4e08904b9 Mon Sep 17 00:00:00 2001 From: Holger Drewes Date: Wed, 25 Jan 2023 22:22:18 +0100 Subject: [PATCH 14/14] Engine API: ExecutionPayloadV6110 -> ExecutionPayloadType6110 --- src/engine/experimental/eip6110.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/engine/experimental/eip6110.md b/src/engine/experimental/eip6110.md index 0945991a1..55e2718ee 100644 --- a/src/engine/experimental/eip6110.md +++ b/src/engine/experimental/eip6110.md @@ -11,7 +11,7 @@ Engine API changes introduced in EIP-6110. - [Table of contents](#table-of-contents) - [Structures](#structures) - [DepositType1](#deposittype1) - - [ExecutionPayloadV6110](#executionpayloadv6110) + - [ExecutionPayloadType6110](#executionpayloadtype6110) - [Methods](#methods) - [engine\_newPayloadV6110](#engine_newpayloadv6110) - [Request](#request) @@ -38,7 +38,7 @@ The fields are encoded as follows: *Note:* The `amount` value is represented in Gwei. -### ExecutionPayloadV6110 +### ExecutionPayloadType6110 This structure has the syntax of [`ExecutionPayloadType2`](../shanghai.md#executionpayloadv2) and appends a single field: `deposits`. @@ -67,9 +67,9 @@ This structure has the syntax of [`ExecutionPayloadType2`](../shanghai.md#execut * method: `engine_newPayloadV6110` * params: - 1. [`ExecutionPayloadType2`](../shanghai.md#ExecutionPayloadType2) | [`ExecutionPayloadV6110`](#ExecutionPayloadV6110), where: + 1. [`ExecutionPayloadType2`](../shanghai.md#ExecutionPayloadType2) | [`ExecutionPayloadType6110`](#ExecutionPayloadType6110), where: - `ExecutionPayloadType1` **MUST** be used if the `timestamp` value is lower than the EIP-6110 activation timestamp, - - `ExecutionPayloadV6110` **MUST** be used if the `timestamp` value is greater or equal to the EIP-6110 activation timestamp, + - `ExecutionPayloadType6110` **MUST** be used if the `timestamp` value is greater or equal to the EIP-6110 activation timestamp, - Client software **MUST** return `-32602: Invalid params` error if the wrong version of the structure is used in the method call. * timeout: 8s @@ -93,7 +93,7 @@ This method follows the same specification as [`engine_newPayloadV2`](../shangha #### Response Refer to the response for [`engine_getPayloadV2`](../shanghai.md#engine_getpayloadv2) with the following change: -* `executionPayload` data structure is changed to [`ExecutionPayloadV6110`](#ExecutionPayloadV6110). +* `executionPayload` data structure is changed to [`ExecutionPayloadType6110`](#ExecutionPayloadType6110). #### Specification