From 98aaaa93c170160a5d650d7068ae43ade58cf45f Mon Sep 17 00:00:00 2001 From: Alex Stokes Date: Thu, 10 Mar 2022 09:32:55 -0700 Subject: [PATCH 01/11] whitespace edits --- src/engine/specification.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/engine/specification.md b/src/engine/specification.md index 2ef315bc..9c9d81f7 100644 --- a/src/engine/specification.md +++ b/src/engine/specification.md @@ -112,7 +112,7 @@ The list of error codes introduced by this specification can be found below. | -32700 | Parse error | Invalid JSON was received by the server. | | -32600 | Invalid Request | The JSON sent is not a valid Request object. | | -32601 | Method not found | The method does not exist / is not available. | -| -32602 | Invalid params | Invalid method parameter(s). | +| -32602 | Invalid params | Invalid method parameter(s). | | -32603 | Internal error | Internal JSON-RPC error. | | -32000 | Server error | Generic client error while processing request. | | -38001 | Unknown payload | Payload does not exist / is not available. | @@ -260,7 +260,7 @@ The payload build process is specified as follows: #### Request * method: `engine_newPayloadV1` -* params: +* params: 1. [`ExecutionPayloadV1`](#ExecutionPayloadV1) * timeout: 8s @@ -297,7 +297,7 @@ The payload build process is specified as follows: #### Request * method: "engine_forkchoiceUpdatedV1" -* params: +* params: 1. `forkchoiceState`: `Object` - instance of [`ForkchoiceStateV1`](#ForkchoiceStateV1) 2. `payloadAttributes`: `Object|null` - instance of [`PayloadAttributesV1`](#PayloadAttributesV1) or `null` * timeout: 8s @@ -393,6 +393,6 @@ The payload build process is specified as follows: 6. Considering the absence of the `TERMINAL_BLOCK_NUMBER` setting, Consensus Layer client software **MAY** use `0` value for the `terminalBlockNumber` field in the input parameters of this call. -7. Considering the absence of the `TERMINAL_TOTAL_DIFFICULTY` value (i.e. when a value has not been decided), Consensus Layer and Execution Layer client software **MUST** use `115792089237316195423570985008687907853269984665640564039457584007913129638912` value (equal to`2**256-2**10`) for the `terminalTotalDifficulty` input parameter of this call. +7. Considering the absence of the `TERMINAL_TOTAL_DIFFICULTY` value (i.e. when a value has not been decided), Consensus Layer and Execution Layer client software **MUST** use `115792089237316195423570985008687907853269984665640564039457584007913129638912` value (equal to`2**256-2**10`) for the `terminalTotalDifficulty` input parameter of this call. [json-rpc-spec]: https://playground.open-rpc.org/?schemaUrl=https://raw.githubusercontent.com/ethereum/execution-apis/assembled-spec/openrpc.json&uiSchema[appBar][ui:splitView]=false&uiSchema[appBar][ui:input]=false&uiSchema[appBar][ui:examplesDropdown]=false From 698565f0c54c87bb615f96f8ab9a6530934040df Mon Sep 17 00:00:00 2001 From: Alex Stokes Date: Thu, 10 Mar 2022 09:33:09 -0700 Subject: [PATCH 02/11] add support for withdrawals --- src/engine/specification.md | 83 +++++++++++++++++++++++++++++++++++++ 1 file changed, 83 insertions(+) diff --git a/src/engine/specification.md b/src/engine/specification.md index 9c9d81f7..a4693c64 100644 --- a/src/engine/specification.md +++ b/src/engine/specification.md @@ -174,6 +174,24 @@ 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) +### WithdrawalV1 + +This structure maps onto the validator withdrawal object from the beacon chain spec. +The fields are encoded as follows: + +- `index`: `QUANTITY`, 64 Bits +- `address`: `DATA`, 20 Bytes +- `amount`: `QUANTITY`, 256 Bits + +*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 Wei. + +### ExecutionPayloadV2 + +This structure has the syntax of `ExecutionPayloadV1` and appends a single field: `withdrawals`. + +- `ExecutionPayloadV1` fields... +- `withdrawals`: `Array of WithdrawalV1` - Array of withdrawals, each object is an `OBJECT` containing the fields of a `WithdrawalV1` structure. + ### ForkchoiceStateV1 This structure encapsulates the fork choice state. The fields are encoded as follows: @@ -192,6 +210,13 @@ 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 +### PayloadAttributesV2 + +This structure has the syntax of `PayloadAttributesV1` and appends a single field: `withdrawals`. + +- `PayloadAttributesV1` fields... +- `withdrawals`: `Array of WithdrawalV1` - Array of withdrawals, each object is an `OBJECT` containing the fields of a `WithdrawalV1` structure. + ### PayloadStatusV1 This structure contains the result of processing a payload. The fields are encoded as follows: @@ -292,6 +317,23 @@ The payload build process is specified as follows: 6. If any of the above fails due to errors unrelated to the normal processing flow of the method, client software **MUST** respond with an error object. +### engine_newPayloadV2 + +#### Request + +* method: `engine_newPayloadV2` +* params: + 1. [`ExecutionPayloadV2`](#ExecutionPayloadV2) + +#### Response + +* result: [`PayloadStatusV1`](#PayloadStatusV1) +* error: code and message set in case an exception happens while processing the payload. + +#### Specification + +Refer to the specification for `engine_newPayloadV1`. + ### engine_forkchoiceUpdatedV1 #### Request @@ -343,6 +385,30 @@ The payload build process is specified as follows: 10. If any of the above fails due to errors unrelated to the normal processing flow of the method, client software **MUST** respond with an error object. +### engine_forkchoiceUpdatedV2 + +#### Request + +* method: "engine_forkchoiceUpdatedV2" +* params: + 1. `forkchoiceState`: `Object` - instance of [`ForkchoiceStateV1`](#ForkchoiceStateV1) + 2. `payloadAttributes`: `Object|null` - instance of [`PayloadAttributesV2`](#PayloadAttributesV2) or `null` + +#### Response + +* result: `object` + - `payloadStatus`: [`PayloadStatusV1`](#PayloadStatusV1); values of the `status` field in the context of this method are restricted to the following subset: + * `"VALID"` + * `"INVALID"` + * `"SYNCING"` + * `"INVALID_TERMINAL_BLOCK"` + - `payloadId`: `DATA|null`, 8 Bytes - identifier of the payload build process or `null` +* error: code and message set in case an exception happens while the validating payload, updating the forkchoice or initiating the payload build process. + +#### Specification + +Refer to the specification for `engine_forkchoiceUpdatedV1`. + ### engine_getPayloadV1 #### Request @@ -365,6 +431,23 @@ The payload build process is specified as follows: 3. Client software **MAY** stop the corresponding build process after serving this call. +### engine_getPayloadV2 + +#### Request + +* method: `engine_getPayloadV2` +* params: + 1. `payloadId`: `DATA`, 8 Bytes - Identifier of the payload build process + +#### Response + +* result: [`ExecutionPayloadV2`](#ExecutionPayloadV2) +* error: code and message set in case an exception happens while getting the payload. + +#### Specification + +Refer to the specification for `engine_getPayloadV1`. + ### engine_exchangeTransitionConfigurationV1 #### Request From fa90a902cc7da73e3af8bb7b02f45cff9a3d2009 Mon Sep 17 00:00:00 2001 From: Alex Stokes Date: Thu, 10 Mar 2022 09:36:49 -0700 Subject: [PATCH 03/11] update wordlist for spellcheck --- wordlist.txt | 2 ++ 1 file changed, 2 insertions(+) diff --git a/wordlist.txt b/wordlist.txt index b941e83a..7df3d5ae 100644 --- a/wordlist.txt +++ b/wordlist.txt @@ -42,3 +42,5 @@ ipc cli besu graphql +gwei +withdrawalv From 9eba4d91eeae366b88b348a71c76dcf964e568c7 Mon Sep 17 00:00:00 2001 From: Alex Stokes Date: Wed, 21 Sep 2022 14:47:38 +0200 Subject: [PATCH 04/11] run doctoc --- src/engine/specification.md | 21 ++++++++++++++++++--- 1 file changed, 18 insertions(+), 3 deletions(-) diff --git a/src/engine/specification.md b/src/engine/specification.md index a4693c64..44363004 100644 --- a/src/engine/specification.md +++ b/src/engine/specification.md @@ -16,8 +16,11 @@ This document specifies the Engine API methods that the Consensus Layer uses to - [Timeouts](#timeouts) - [Structures](#structures) - [ExecutionPayloadV1](#executionpayloadv1) + - [WithdrawalV1](#withdrawalv1) + - [ExecutionPayloadV2](#executionpayloadv2) - [ForkchoiceStateV1](#forkchoicestatev1) - [PayloadAttributesV1](#payloadattributesv1) + - [PayloadAttributesV2](#payloadattributesv2) - [PayloadStatusV1](#payloadstatusv1) - [TransitionConfigurationV1](#transitionconfigurationv1) - [Routines](#routines) @@ -29,18 +32,30 @@ This document specifies the Engine API methods that the Consensus Layer uses to - [Request](#request) - [Response](#response) - [Specification](#specification) - - [engine_forkchoiceUpdatedV1](#engine_forkchoiceupdatedv1) + - [engine_newPayloadV2](#engine_newpayloadv2) - [Request](#request-1) - [Response](#response-1) - [Specification](#specification-1) - - [engine_getPayloadV1](#engine_getpayloadv1) + - [engine_forkchoiceUpdatedV1](#engine_forkchoiceupdatedv1) - [Request](#request-2) - [Response](#response-2) - [Specification](#specification-2) - - [engine_exchangeTransitionConfigurationV1](#engine_exchangetransitionconfigurationv1) + - [engine_forkchoiceUpdatedV2](#engine_forkchoiceupdatedv2) - [Request](#request-3) - [Response](#response-3) - [Specification](#specification-3) + - [engine_getPayloadV1](#engine_getpayloadv1) + - [Request](#request-4) + - [Response](#response-4) + - [Specification](#specification-4) + - [engine_getPayloadV2](#engine_getpayloadv2) + - [Request](#request-5) + - [Response](#response-5) + - [Specification](#specification-5) + - [engine_exchangeTransitionConfigurationV1](#engine_exchangetransitionconfigurationv1) + - [Request](#request-6) + - [Response](#response-6) + - [Specification](#specification-6) From bd2109f97c0e3359ddfeb5c1477aea2b2cdbfd20 Mon Sep 17 00:00:00 2001 From: Alex Stokes Date: Wed, 21 Sep 2022 14:54:14 +0200 Subject: [PATCH 05/11] Apply PR feedback --- src/engine/specification.md | 32 ++++++++++++++++++++------------ 1 file changed, 20 insertions(+), 12 deletions(-) diff --git a/src/engine/specification.md b/src/engine/specification.md index 44363004..9257e4e8 100644 --- a/src/engine/specification.md +++ b/src/engine/specification.md @@ -204,7 +204,20 @@ The fields are encoded as follows: This structure has the syntax of `ExecutionPayloadV1` and appends a single field: `withdrawals`. -- `ExecutionPayloadV1` fields... +- `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. ### ForkchoiceStateV1 @@ -229,7 +242,9 @@ This structure contains the attributes required to initiate a payload build proc This structure has the syntax of `PayloadAttributesV1` and appends a single field: `withdrawals`. -- `PayloadAttributesV1` fields... +- `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. ### PayloadStatusV1 @@ -347,7 +362,7 @@ The payload build process is specified as follows: #### Specification -Refer to the specification for `engine_newPayloadV1`. +Refer to the specification for [`engine_newPayloadV1`](#enginenewpayloadv1). ### engine_forkchoiceUpdatedV1 @@ -411,14 +426,7 @@ Refer to the specification for `engine_newPayloadV1`. #### Response -* result: `object` - - `payloadStatus`: [`PayloadStatusV1`](#PayloadStatusV1); values of the `status` field in the context of this method are restricted to the following subset: - * `"VALID"` - * `"INVALID"` - * `"SYNCING"` - * `"INVALID_TERMINAL_BLOCK"` - - `payloadId`: `DATA|null`, 8 Bytes - identifier of the payload build process or `null` -* error: code and message set in case an exception happens while the validating payload, updating the forkchoice or initiating the payload build process. +Refer to the response for [`engine_forkchoiceUpdatedV1`](#engineforkchoiceupdatedv1). #### Specification @@ -461,7 +469,7 @@ Refer to the specification for `engine_forkchoiceUpdatedV1`. #### Specification -Refer to the specification for `engine_getPayloadV1`. +Refer to the specification for [`engine_getPayloadV1`](#enginegetpayloadv1). ### engine_exchangeTransitionConfigurationV1 From f60c5e84dff0fcd1c772194981f2f7f13156c848 Mon Sep 17 00:00:00 2001 From: Alex Stokes Date: Wed, 21 Sep 2022 15:03:22 +0200 Subject: [PATCH 06/11] Apply suggestions from code review --- src/engine/specification.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/engine/specification.md b/src/engine/specification.md index 9257e4e8..51ed033b 100644 --- a/src/engine/specification.md +++ b/src/engine/specification.md @@ -362,7 +362,7 @@ The payload build process is specified as follows: #### Specification -Refer to the specification for [`engine_newPayloadV1`](#enginenewpayloadv1). +Refer to the specification for [`engine_newPayloadV1`](#engine_newpayloadv1). ### engine_forkchoiceUpdatedV1 @@ -426,11 +426,11 @@ Refer to the specification for [`engine_newPayloadV1`](#enginenewpayloadv1). #### Response -Refer to the response for [`engine_forkchoiceUpdatedV1`](#engineforkchoiceupdatedv1). +Refer to the response for [`engine_forkchoiceUpdatedV1`](#engine_forkchoiceupdatedv1). #### Specification -Refer to the specification for `engine_forkchoiceUpdatedV1`. +Refer to the specification for [`engine_forkchoiceUpdatedV1`](#engine_forkchoiceupdatedv1). ### engine_getPayloadV1 @@ -469,7 +469,7 @@ Refer to the specification for `engine_forkchoiceUpdatedV1`. #### Specification -Refer to the specification for [`engine_getPayloadV1`](#enginegetpayloadv1). +Refer to the specification for [`engine_getPayloadV1`](#engine_getpayloadv1). ### engine_exchangeTransitionConfigurationV1 From 4cc2d92ad294c91b76e5965a2814a63c7931bb4f Mon Sep 17 00:00:00 2001 From: Alex Stokes Date: Wed, 21 Sep 2022 15:07:38 +0200 Subject: [PATCH 07/11] Condense spec with prior response --- src/engine/specification.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/src/engine/specification.md b/src/engine/specification.md index 51ed033b..64b7c41f 100644 --- a/src/engine/specification.md +++ b/src/engine/specification.md @@ -357,8 +357,7 @@ The payload build process is specified as follows: #### Response -* result: [`PayloadStatusV1`](#PayloadStatusV1) -* error: code and message set in case an exception happens while processing the payload. +Refer to the response for [`engine_newPayloadV1`](#engine_newpayloadv1). #### Specification From 1436f24048d07cc829b7b3689b9313c8695d737e Mon Sep 17 00:00:00 2001 From: Alex Stokes Date: Tue, 25 Oct 2022 15:11:04 -0600 Subject: [PATCH 08/11] Update src/engine/specification.md Co-authored-by: lightclient <14004106+lightclient@users.noreply.github.com> --- src/engine/specification.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/engine/specification.md b/src/engine/specification.md index 64b7c41f..2af6c167 100644 --- a/src/engine/specification.md +++ b/src/engine/specification.md @@ -429,7 +429,8 @@ Refer to the response for [`engine_forkchoiceUpdatedV1`](#engine_forkchoiceupdat #### Specification -Refer to the specification for [`engine_forkchoiceUpdatedV1`](#engine_forkchoiceupdatedv1). +This method follows the same specification as [`engine_forkchoiceUpdatedV1`](#engine_forkchoiceupdatedv1) with the exception of the following: +1. If withdrawal functionality is activated, client software **MUST** return error `-38003: Invalid payload attributes` if `payloadAttributes.withdrawals` is `null`. Similarly, if the functionality is not activated, client software **MUST** return error -38003: Invalid payload attributes` if `payloadAttributes.withdrawals` is not `null`. Zero withdrawal blocks **MUST** be expressed with an explicit empty list `[]` value. ### engine_getPayloadV1 From 60b353f26bbc10db6f077656ce5c47684ab74d92 Mon Sep 17 00:00:00 2001 From: Alex Stokes Date: Tue, 25 Oct 2022 15:21:03 -0600 Subject: [PATCH 09/11] update `WithdrawalV1` definition with the validatorIndex --- src/engine/specification.md | 1 + 1 file changed, 1 insertion(+) diff --git a/src/engine/specification.md b/src/engine/specification.md index 2af6c167..e8a7f742 100644 --- a/src/engine/specification.md +++ b/src/engine/specification.md @@ -195,6 +195,7 @@ This structure maps onto the validator withdrawal object from the beacon chain s The fields are encoded as follows: - `index`: `QUANTITY`, 64 Bits +- `validatorIndex`: `QUANTITY`, 64 Bits - `address`: `DATA`, 20 Bytes - `amount`: `QUANTITY`, 256 Bits From fa29c09217fef9a87055cf09f4a9a67e492b0f61 Mon Sep 17 00:00:00 2001 From: Alex Stokes Date: Tue, 25 Oct 2022 15:21:24 -0600 Subject: [PATCH 10/11] clarify the handling of empty vs `null` withdrawals --- src/engine/specification.md | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/src/engine/specification.md b/src/engine/specification.md index e8a7f742..7bda7fe4 100644 --- a/src/engine/specification.md +++ b/src/engine/specification.md @@ -362,7 +362,12 @@ Refer to the response for [`engine_newPayloadV1`](#engine_newpayloadv1). #### Specification -Refer to the specification for [`engine_newPayloadV1`](#engine_newpayloadv1). +This method follows the same specification as [`engine_newPayloadV1`](#engine_newpayloadv1) with the exception of the following: + +1. If withdrawal functionality is activated, client software **MUST** return an `INVALID` status with the appropriate `latestValidHash` if `payload.withdrawals` is `null`. + Similarly, if the functionality is not activated, client software **MUST** return an `INVALID` status with the appropriate `latestValidHash` if `payloadAttributes.withdrawals` is not `null`. + Blocks without withdrawals **MUST** be expressed with an explicit empty list `[]` value. + Refer to the validity conditions for [`engine_newPayloadV1`](#engine_newpayloadv1) to specification of the appropriate `latestValidHash` value. ### engine_forkchoiceUpdatedV1 @@ -431,7 +436,10 @@ Refer to the response for [`engine_forkchoiceUpdatedV1`](#engine_forkchoiceupdat #### Specification This method follows the same specification as [`engine_forkchoiceUpdatedV1`](#engine_forkchoiceupdatedv1) with the exception of the following: -1. If withdrawal functionality is activated, client software **MUST** return error `-38003: Invalid payload attributes` if `payloadAttributes.withdrawals` is `null`. Similarly, if the functionality is not activated, client software **MUST** return error -38003: Invalid payload attributes` if `payloadAttributes.withdrawals` is not `null`. Zero withdrawal blocks **MUST** be expressed with an explicit empty list `[]` value. + +1. If withdrawal functionality is activated, client software **MUST** return error `-38003: Invalid payload attributes` if `payloadAttributes.withdrawals` is `null`. + Similarly, if the functionality is not activated, client software **MUST** return error -38003: Invalid payload attributes` if `payloadAttributes.withdrawals` is not `null`. + Blocks without withdrawals **MUST** be expressed with an explicit empty list `[]` value. ### engine_getPayloadV1 From fac2082c7b0012befb7e41cd123e64be0dbf42cc Mon Sep 17 00:00:00 2001 From: Alex Stokes Date: Wed, 2 Nov 2022 16:06:57 -0600 Subject: [PATCH 11/11] Update src/engine/specification.md Co-authored-by: terencechain --- src/engine/specification.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/engine/specification.md b/src/engine/specification.md index 7bda7fe4..7d502d18 100644 --- a/src/engine/specification.md +++ b/src/engine/specification.md @@ -438,7 +438,7 @@ Refer to the response for [`engine_forkchoiceUpdatedV1`](#engine_forkchoiceupdat This method follows the same specification as [`engine_forkchoiceUpdatedV1`](#engine_forkchoiceupdatedv1) with the exception of the following: 1. If withdrawal functionality is activated, client software **MUST** return error `-38003: Invalid payload attributes` if `payloadAttributes.withdrawals` is `null`. - Similarly, if the functionality is not activated, client software **MUST** return error -38003: Invalid payload attributes` if `payloadAttributes.withdrawals` is not `null`. + Similarly, if the functionality is not activated, client software **MUST** return error `-38003: Invalid payload attributes` if `payloadAttributes.withdrawals` is not `null`. Blocks without withdrawals **MUST** be expressed with an explicit empty list `[]` value. ### engine_getPayloadV1