diff --git a/src/engine/specification.md b/src/engine/specification.md index 2ef315bc..7d502d18 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) @@ -112,7 +127,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. | @@ -174,6 +189,38 @@ 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 +- `validatorIndex`: `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`. + +- `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 This structure encapsulates the fork choice state. The fields are encoded as follows: @@ -192,6 +239,15 @@ 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`. + +- `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 This structure contains the result of processing a payload. The fields are encoded as follows: @@ -260,7 +316,7 @@ The payload build process is specified as follows: #### Request * method: `engine_newPayloadV1` -* params: +* params: 1. [`ExecutionPayloadV1`](#ExecutionPayloadV1) * timeout: 8s @@ -292,12 +348,33 @@ 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 + +Refer to the response for [`engine_newPayloadV1`](#engine_newpayloadv1). + +#### Specification + +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 #### 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 @@ -343,6 +420,27 @@ 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 + +Refer to the response for [`engine_forkchoiceUpdatedV1`](#engine_forkchoiceupdatedv1). + +#### 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`. + Blocks without withdrawals **MUST** be expressed with an explicit empty list `[]` value. + ### engine_getPayloadV1 #### Request @@ -365,6 +463,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_getpayloadv1). + ### engine_exchangeTransitionConfigurationV1 #### Request @@ -393,6 +508,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 diff --git a/wordlist.txt b/wordlist.txt index 927f1549..a38207e4 100644 --- a/wordlist.txt +++ b/wordlist.txt @@ -46,3 +46,5 @@ ssz kzg besu graphql +gwei +withdrawalv