From 6dcd49a8c3a52da0d4a1735bbd598edaf48346a9 Mon Sep 17 00:00:00 2001 From: Mikhail Kalinin Date: Wed, 16 Nov 2022 12:12:10 +0600 Subject: [PATCH 1/3] Decouple shanghai spec --- src/engine/shanghai.md | 130 ++++++++++++++++++++++++++++++++++++ src/engine/specification.md | 121 +-------------------------------- 2 files changed, 133 insertions(+), 118 deletions(-) create mode 100644 src/engine/shanghai.md diff --git a/src/engine/shanghai.md b/src/engine/shanghai.md new file mode 100644 index 00000000..e8c6c4ed --- /dev/null +++ b/src/engine/shanghai.md @@ -0,0 +1,130 @@ +# Shanghai -- Engine API + +## Table of contents + + + + +- [Structures](#structures) + - [WithdrawalV1](#withdrawalv1) + - [ExecutionPayloadV2](#executionpayloadv2) + - [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) + + + +## Structures + +### 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. + +### 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. + +## Methods + +### engine_newPayloadV2 + +#### Request + +* method: `engine_newPayloadV2` +* params: + 1. [`ExecutionPayloadV2`](#ExecutionPayloadV2) + +#### Response + +Refer to the response for [`engine_newPayloadV1`](./specification.md#engine_newpayloadv1). + +#### Specification + +This method follows the same specification as [`engine_newPayloadV1`](./specification.md#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`](./specification.md#engine_newpayloadv1) to specification of the appropriate `latestValidHash` value. + +### engine_forkchoiceUpdatedV2 + +#### Request + +* method: "engine_forkchoiceUpdatedV2" +* params: + 1. `forkchoiceState`: `Object` - instance of [`ForkchoiceStateV1`](./specification.md#ForkchoiceStateV1) + 2. `payloadAttributes`: `Object|null` - instance of [`PayloadAttributesV2`](#PayloadAttributesV2) or `null` + +#### Response + +Refer to the response for [`engine_forkchoiceUpdatedV1`](./specification.md#engine_forkchoiceupdatedv1). + +#### Specification + +This method follows the same specification as [`engine_forkchoiceUpdatedV1`](./specification.md#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_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`](./specification.md#engine_getpayloadv1). diff --git a/src/engine/specification.md b/src/engine/specification.md index 7d502d18..9c9d81f7 100644 --- a/src/engine/specification.md +++ b/src/engine/specification.md @@ -16,11 +16,8 @@ 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) @@ -32,30 +29,18 @@ This document specifies the Engine API methods that the Consensus Layer uses to - [Request](#request) - [Response](#response) - [Specification](#specification) - - [engine_newPayloadV2](#engine_newpayloadv2) + - [engine_forkchoiceUpdatedV1](#engine_forkchoiceupdatedv1) - [Request](#request-1) - [Response](#response-1) - [Specification](#specification-1) - - [engine_forkchoiceUpdatedV1](#engine_forkchoiceupdatedv1) + - [engine_getPayloadV1](#engine_getpayloadv1) - [Request](#request-2) - [Response](#response-2) - [Specification](#specification-2) - - [engine_forkchoiceUpdatedV2](#engine_forkchoiceupdatedv2) + - [engine_exchangeTransitionConfigurationV1](#engine_exchangetransitionconfigurationv1) - [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) @@ -189,38 +174,6 @@ 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: @@ -239,15 +192,6 @@ 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: @@ -348,27 +292,6 @@ 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 @@ -420,27 +343,6 @@ This method follows the same specification as [`engine_newPayloadV1`](#engine_ne 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 @@ -463,23 +365,6 @@ This method follows the same specification as [`engine_forkchoiceUpdatedV1`](#en 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 From 3da8b4437ff7454beb3744031bb178ed7d360fd0 Mon Sep 17 00:00:00 2001 From: Mikhail Kalinin Date: Fri, 9 Dec 2022 16:22:14 +0600 Subject: [PATCH 2/3] Rip Paris out of the main spec --- src/engine/common.md | 132 ++++++++++++++++++++++ src/engine/{specification.md => paris.md} | 127 +-------------------- src/engine/shanghai.md | 18 +-- 3 files changed, 146 insertions(+), 131 deletions(-) create mode 100644 src/engine/common.md rename src/engine/{specification.md => paris.md} (77%) diff --git a/src/engine/common.md b/src/engine/common.md new file mode 100644 index 00000000..8c654463 --- /dev/null +++ b/src/engine/common.md @@ -0,0 +1,132 @@ +# Engine API -- Common Definitions + +This document specifies common definitions and requirements affecting Engine API specification in general. + +## Table of contents + + + + +- [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) + + + +## Underlying protocol + +Message format and encoding notation used by this specification are inherited +from [Ethereum JSON-RPC Specification][json-rpc-spec]. + +Client software **MUST** expose Engine API at a port independent from JSON-RPC API. +The default port for the Engine API is 8551. +The Engine API is exposed under the `engine` namespace. + +To facilitate an Engine API consumer to access state and logs (e.g. proof-of-stake deposits) through the same connection, +the client **MUST** also expose the following subset of `eth` methods: +* `eth_blockNumber` +* `eth_call` +* `eth_chainId` +* `eth_getCode` +* `eth_getBlockByHash` +* `eth_getBlockByNumber` +* `eth_getLogs` +* `eth_sendRawTransaction` +* `eth_syncing` + +These methods are described in [Ethereum JSON-RPC Specification][json-rpc-spec]. + +### Authentication + +Engine API uses JWT authentication enabled by default. +JWT authentication is specified in [Authentication](./authentication.md) document. + +## 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: + * a set of method parameters + * a method response value + * a method behavior + * 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. + +## Message ordering + +Consensus Layer client software **MUST** respect the order of the corresponding fork choice update events +when making calls to the `engine_forkchoiceUpdated` method. + +Execution Layer client software **MUST** process `engine_forkchoiceUpdated` method calls +in the same order as they have been received. + +## Load-balancing and advanced configurations + +The Engine API supports a one-to-many Consensus Layer to Execution Layer configuration. +Intuitively this is because the Consensus Layer drives the Execution Layer and thus can drive many of them independently. + +On the other hand, generic many-to-one Consensus Layer to Execution Layer configurations are not supported out-of-the-box. +The Execution Layer, by default, only supports one chain head at a time and thus has undefined behavior when multiple Consensus Layers simultaneously control the head. +The Engine API does work properly, if in such a many-to-one configuration, only one Consensus Layer instantiation is able to *write* to the Execution Layer's chain head and initiate the payload build process (i.e. call `engine_forkchoiceUpdated` ), +while other Consensus Layers can only safely insert payloads (i.e. `engine_newPayload`) and read from the Execution Layer. + +## Errors + +The list of error codes introduced by this specification can be found below. + +| Code | Message | Meaning | +| - | - | - | +| -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). | +| -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. | +| -38002 | Invalid forkchoice state | Forkchoice state is invalid / inconsistent. | +| -38003 | Invalid payload attributes | Payload attributes are invalid / inconsistent. | + +Each error returns a `null` `data` value, except `-32000` which returns the `data` object with a `err` member that explains the error encountered. + +For example: + +```console +$ curl https://localhost:8551 \ + -X POST \ + -H "Content-Type: application/json" \ + -d '{"jsonrpc":"2.0","method":"engine_getPayloadV1","params": ["0x1"],"id":1}' +{ + "jsonrpc": "2.0", + "id": 1, + "error": { + "code": -32000, + "message": "Server error", + "data": { + "err": "Database corrupted" + } + } +} +``` + +## Timeouts + +Consensus Layer client software **MUST** wait for a specified `timeout` before aborting the call. In such an event, the Consensus Layer client software **SHOULD** retry the call when it is needed to keep progressing. + +Consensus Layer client software **MAY** wait for response longer than it is specified by the `timeout` parameter. + +## Encoding + +Values of a field of `DATA` type **MUST** be encoded as a hexadecimal string with a `0x` prefix matching the regular expression `^0x(?:[a-fA-F0-9]{2})*$`. + +Values of a field of `QUANTITY` type **MUST** be encoded as a hexadecimal string with a `0x` prefix and the leading 0s stripped (except for the case of encoding the value `0`) matching the regular expression `^0x(?:0|(?:[a-fA-F1-9][a-fA-F0-9]*))$`. + +*Note:* Byte order of encoded value having `QUANTITY` type is big-endian. + +[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/src/engine/specification.md b/src/engine/paris.md similarity index 77% rename from src/engine/specification.md rename to src/engine/paris.md index 9c9d81f7..70f73983 100644 --- a/src/engine/specification.md +++ b/src/engine/paris.md @@ -1,19 +1,12 @@ -# Engine API +# Engine API -- Paris -This document specifies the Engine API methods that the Consensus Layer uses to interact with the Execution Layer. +Engine API structures and methods specified for Paris. ## Table of contents -- [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) - [Structures](#structures) - [ExecutionPayloadV1](#executionpayloadv1) - [ForkchoiceStateV1](#forkchoicestatev1) @@ -24,7 +17,7 @@ This document specifies the Engine API methods that the Consensus Layer uses to - [Payload validation](#payload-validation) - [Sync](#sync) - [Payload building](#payload-building) -- [Core](#core) +- [Methods](#methods) - [engine_newPayloadV1](#engine_newpayloadv1) - [Request](#request) - [Response](#response) @@ -43,118 +36,8 @@ This document specifies the Engine API methods that the Consensus Layer uses to - [Specification](#specification-3) - -## Underlying protocol - -Message format and encoding notation used by this specification are inherited -from [Ethereum JSON-RPC Specification][json-rpc-spec]. - -Client software **MUST** expose Engine API at a port independent from JSON-RPC API. -The default port for the Engine API is 8551. -The Engine API is exposed under the `engine` namespace. - -To facilitate an Engine API consumer to access state and logs (e.g. proof-of-stake deposits) through the same connection, -the client **MUST** also expose the following subset of `eth` methods: -* `eth_blockNumber` -* `eth_call` -* `eth_chainId` -* `eth_getCode` -* `eth_getBlockByHash` -* `eth_getBlockByNumber` -* `eth_getLogs` -* `eth_sendRawTransaction` -* `eth_syncing` - -These methods are described in [Ethereum JSON-RPC Specification][json-rpc-spec]. - -### Authentication - -Engine API uses JWT authentication enabled by default. -JWT authentication is specified in [Authentication](./authentication.md) document. - -## 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: - * a set of method parameters - * a method response value - * a method behavior - * 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. - -## Message ordering - -Consensus Layer client software **MUST** respect the order of the corresponding fork choice update events -when making calls to the `engine_forkchoiceUpdated` method. - -Execution Layer client software **MUST** process `engine_forkchoiceUpdated` method calls -in the same order as they have been received. - -## Load-balancing and advanced configurations - -The Engine API supports a one-to-many Consensus Layer to Execution Layer configuration. -Intuitively this is because the Consensus Layer drives the Execution Layer and thus can drive many of them independently. - -On the other hand, generic many-to-one Consensus Layer to Execution Layer configurations are not supported out-of-the-box. -The Execution Layer, by default, only supports one chain head at a time and thus has undefined behavior when multiple Consensus Layers simultaneously control the head. -The Engine API does work properly, if in such a many-to-one configuration, only one Consensus Layer instantiation is able to *write* to the Execution Layer's chain head and initiate the payload build process (i.e. call `engine_forkchoiceUpdated` ), -while other Consensus Layers can only safely insert payloads (i.e. `engine_newPayload`) and read from the Execution Layer. - -## Errors - -The list of error codes introduced by this specification can be found below. - -| Code | Message | Meaning | -| - | - | - | -| -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). | -| -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. | -| -38002 | Invalid forkchoice state | Forkchoice state is invalid / inconsistent. | -| -38003 | Invalid payload attributes | Payload attributes are invalid / inconsistent. | - -Each error returns a `null` `data` value, except `-32000` which returns the `data` object with a `err` member that explains the error encountered. - -For example: - -```console -$ curl https://localhost:8551 \ - -X POST \ - -H "Content-Type: application/json" \ - -d '{"jsonrpc":"2.0","method":"engine_getPayloadV1","params": ["0x1"],"id":1}' -{ - "jsonrpc": "2.0", - "id": 1, - "error": { - "code": -32000, - "message": "Server error", - "data": { - "err": "Database corrupted" - } - } -} -``` - -## Timeouts - -Consensus Layer client software **MUST** wait for a specified `timeout` before aborting the call. In such an event, the Consensus Layer client software **SHOULD** retry the call when it is needed to keep progressing. - -Consensus Layer client software **MAY** wait for response longer than it is specified by the `timeout` parameter. - ## Structures -Values of a field of `DATA` type **MUST** be encoded as a hexadecimal string with a `0x` prefix matching the regular expression `^0x(?:[a-fA-F0-9]{2})*$`. - -Values of a field of `QUANTITY` type **MUST** be encoded as a hexadecimal string with a `0x` prefix and the leading 0s stripped (except for the case of encoding the value `0`) matching the regular expression `^0x(?:0|(?:[a-fA-F1-9][a-fA-F0-9]*))$`. - -*Note:* Byte order of encoded value having `QUANTITY` type is big-endian. - ### ExecutionPayloadV1 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: @@ -253,7 +136,7 @@ The payload build process is specified as follows: 4. Client software **SHOULD** stop the updating process when either a call to `engine_getPayload` with the build process's `payloadId` is made or [`SECONDS_PER_SLOT`](https://github.com/ethereum/consensus-specs/blob/dev/specs/phase0/beacon-chain.md#time-parameters-1) (12s in the Mainnet configuration) have passed since the point in time identified by the `timestamp` parameter. -## Core +## Methods ### engine_newPayloadV1 @@ -394,5 +277,3 @@ 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. - -[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/src/engine/shanghai.md b/src/engine/shanghai.md index e8c6c4ed..0c7b12eb 100644 --- a/src/engine/shanghai.md +++ b/src/engine/shanghai.md @@ -1,4 +1,6 @@ -# Shanghai -- Engine API +# Engine API -- Shanghai + +Engine API changes introduced in Shanghai. ## Table of contents @@ -80,16 +82,16 @@ This structure has the syntax of `PayloadAttributesV1` and appends a single fiel #### Response -Refer to the response for [`engine_newPayloadV1`](./specification.md#engine_newpayloadv1). +Refer to the response for [`engine_newPayloadV1`](./paris.md#engine_newpayloadv1). #### Specification -This method follows the same specification as [`engine_newPayloadV1`](./specification.md#engine_newpayloadv1) with the exception of the following: +This method follows the same specification as [`engine_newPayloadV1`](./paris.md#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`](./specification.md#engine_newpayloadv1) to specification of the appropriate `latestValidHash` value. + Refer to the validity conditions for [`engine_newPayloadV1`](./paris.md#engine_newpayloadv1) to specification of the appropriate `latestValidHash` value. ### engine_forkchoiceUpdatedV2 @@ -97,16 +99,16 @@ This method follows the same specification as [`engine_newPayloadV1`](./specific * method: "engine_forkchoiceUpdatedV2" * params: - 1. `forkchoiceState`: `Object` - instance of [`ForkchoiceStateV1`](./specification.md#ForkchoiceStateV1) + 1. `forkchoiceState`: `Object` - instance of [`ForkchoiceStateV1`](./paris.md#ForkchoiceStateV1) 2. `payloadAttributes`: `Object|null` - instance of [`PayloadAttributesV2`](#PayloadAttributesV2) or `null` #### Response -Refer to the response for [`engine_forkchoiceUpdatedV1`](./specification.md#engine_forkchoiceupdatedv1). +Refer to the response for [`engine_forkchoiceUpdatedV1`](./paris.md#engine_forkchoiceupdatedv1). #### Specification -This method follows the same specification as [`engine_forkchoiceUpdatedV1`](./specification.md#engine_forkchoiceupdatedv1) with the exception of the following: +This method follows the same specification as [`engine_forkchoiceUpdatedV1`](./paris.md#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`. @@ -127,4 +129,4 @@ This method follows the same specification as [`engine_forkchoiceUpdatedV1`](./s #### Specification -Refer to the specification for [`engine_getPayloadV1`](./specification.md#engine_getpayloadv1). +Refer to the specification for [`engine_getPayloadV1`](./paris.md#engine_getpayloadv1). From 1489a3d028e63dbe8b16785a220bd5443fd7475a Mon Sep 17 00:00:00 2001 From: Mikhail Kalinin Date: Mon, 19 Dec 2022 15:17:06 +0600 Subject: [PATCH 3/3] Add experimental/ --- src/engine/{ => experimental}/blob-extension.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename src/engine/{ => experimental}/blob-extension.md (100%) diff --git a/src/engine/blob-extension.md b/src/engine/experimental/blob-extension.md similarity index 100% rename from src/engine/blob-extension.md rename to src/engine/experimental/blob-extension.md