From a338ce477d46c252934f2e11db02596b4e36719e Mon Sep 17 00:00:00 2001 From: Alexey Osipov Date: Thu, 29 Jun 2023 14:31:07 +0300 Subject: [PATCH 1/7] Clarify Cancun payloads handling by Shanghai APIs; reorder checks --- src/engine/cancun.md | 12 +-- src/engine/experimental/blob-extension.md | 120 ---------------------- src/engine/paris.md | 19 ++-- 3 files changed, 18 insertions(+), 133 deletions(-) delete mode 100644 src/engine/experimental/blob-extension.md diff --git a/src/engine/cancun.md b/src/engine/cancun.md index 8abd2612e..3a4d0b62e 100644 --- a/src/engine/cancun.md +++ b/src/engine/cancun.md @@ -51,7 +51,7 @@ This structure has the syntax of [`ExecutionPayloadV2`](./shanghai.md#executionp - `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. -- `dataGasUsed`: `QUANTITY`, 64 bits +- `dataGasUsed`: `QUANTITY`, 64 Bits - `excessDataGas`: `QUANTITY`, 64 Bits ### BlobsBundleV1 @@ -86,8 +86,6 @@ This structure has the syntax of [`PayloadAttributesV2`](./shanghai.md#payloadat 2. `expectedBlobVersionedHashes`: `Array of DATA`, 32 Bytes - Array of expected blob versioned hashes to validate. 3. `parentBeaconBlockRoot`: `DATA`, 32 Bytes - Root of the parent beacon block. -Client software **MUST** return `-32602: Invalid params` error unless all parameters and their fields are provided with non-`null` values. - #### Response Refer to the response for [`engine_newPayloadV2`](./shanghai.md#engine_newpayloadv2). @@ -96,14 +94,16 @@ Refer to the response for [`engine_newPayloadV2`](./shanghai.md#engine_newpayloa This method follows the same specification as [`engine_newPayloadV2`](./shanghai.md#engine_newpayloadv2) with the addition of the following: -1. Given the expected array of blob versioned hashes client software **MUST** run its validation by taking the following steps: +1. Client software **MUST** return `-32602: Invalid params` error unless all parameters and their fields are provided with non-`null` values. + +2. Client software **MUST** return `-38005: Unsupported fork` error if the `timestamp` of the payload is less than the Cancun activation timestamp. This rule replaces similar one defined for `engine_newPayloadV1`. + +3. Given the expected array of blob versioned hashes client software **MUST** run its validation by taking the following steps: 1. Obtain the actual array by concatenating blob versioned hashes lists (`tx.blob_versioned_hashes`) of each [blob transaction](https://eips.ethereum.org/EIPS/eip-4844#new-transaction-type) included in the payload, respecting the order of inclusion. If the payload has no blob transactions the expected array **MUST** be `[]`. 2. Return `{status: INVALID, latestValidHash: null, validationError: errorMessage | null}` if the expected and the actual arrays don't match. This validation **MUST** be instantly run in all cases even during active sync process. -2. Client software **MUST** return `-38005: Unsupported fork` error if the `timestamp` of the payload is less than the Cancun activation timestamp. - ### engine_forkchoiceUpdatedV3 #### Request diff --git a/src/engine/experimental/blob-extension.md b/src/engine/experimental/blob-extension.md deleted file mode 100644 index aa352119e..000000000 --- a/src/engine/experimental/blob-extension.md +++ /dev/null @@ -1,120 +0,0 @@ - - -**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)* - -- [Shard Blob Extension](#shard-blob-extension) - - [Structures](#structures) - - [ExecutionPayloadV3](#executionpayloadv3) - - [BlobsBundleV1](#blobsbundlev1) - - [Methods](#methods) - - [engine_newPayloadV3](#engine_newpayloadv3) - - [Request](#request) - - [Response](#response) - - [Specification](#specification) - - [engine_getPayloadV3](#engine_getpayloadv3) - - [Request](#request-1) - - [Response](#response-1) - - [Specification](#specification-1) - - - -# Shard Blob Extension - -This is an extension specific to [EIP-4844](https://eips.ethereum.org/EIPS/eip-4844) to the structures and methods as defined in the [Engine API - Paris](../paris.md) and [Engine API - Shanghai](../shanghai.md). -This extension is backwards-compatible, but not part of the initial Engine API. - -## Structures - -### ExecutionPayloadV3 - -This structure has the syntax of `ExecutionPayloadV2` and append two new fields: `dataGasUsed` and `excessDataGas`. - -- `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. -- `dataGasUsed`: `QUANTITY`, 64 bits -- `excessDataGas`: `QUANTITY`, 64 Bits - -### BlobsBundleV1 - -The fields are encoded as follows: - -- `commitments`: `Array of DATA` - Array of `KZGCommitment` as defined in [EIP-4844](https://eips.ethereum.org/EIPS/eip-4844), 48 bytes each (`DATA`). -- `proofs`: `Array of DATA` - Array of `KZGProof` as defined in [EIP-4844](https://eips.ethereum.org/EIPS/eip-4844), 48 bytes each (`DATA`). -- `blobs`: `Array of DATA` - Array of blobs, each blob is `FIELD_ELEMENTS_PER_BLOB * BYTES_PER_FIELD_ELEMENT = 4096 * 32 = 131072` bytes (`DATA`) representing a SSZ-encoded `Blob` as defined in [EIP-4844](https://eips.ethereum.org/EIPS/eip-4844) - -All of the above three arrays **MUST** be of same length. - -## Methods - -### engine_newPayloadV3 - -#### Request - -* method: `engine_newPayloadV3` -* params: - 1. [`ExecutionPayloadV3`](#ExecutionPayloadV3). - 2. `Array of DATA`, 32 Bytes - Array of blob versioned hashes to validate. - -Client software **MUST** return `-32602: Invalid params` error unless all parameters and their fields are provided with non-`null` values. - -#### Response - -Refer to the response for `engine_newPayloadV2`. - -#### Specification - -This method follows the same specification as `engine_newPayloadV2` with the addition of the following: - -1. Given the expected array of blob versioned hashes client software **MUST** run its validation by taking the following steps: - 1. Obtain an actual array by concatenating blob versioned hashes lists (`tx.blob_versioned_hashes`) of each [blob transaction](https://eips.ethereum.org/EIPS/eip-4844#new-transaction-type) included in the payload, respecting the order of inclusion. If the payload has no blob transactions the expected array **MUST** be `[]`. - 2. Return `{status: INVALID, latestValidHash: null, validationError: errorMessage | null}` if the expected and the actual arrays don't match. - - This validation **MUST** be instantly run in all cases even during active sync process. - -2. Client software **MUST** return `-38005: Unsupported fork` error if the `timestamp` of the payload is less than the EIP-4844 activation timestamp. - -### engine_getPayloadV3 - -The response of this method is extended with [`BlobsBundleV1`](#blobsbundlev1) containing the blobs, their respective KZG commitments -and proofs corresponding to the `versioned_hashes` included in the blob transactions of the execution payload. - -#### Request - -* method: `engine_getPayloadV3` -* params: - 1. `payloadId`: `DATA`, 8 Bytes - Identifier of the payload build process -* timeout: 1s - -#### Response - -* result: `object` - - `executionPayload`: [`ExecutionPayloadV3`](#ExecutionPayloadV3) - - `blockValue` : `QUANTITY`, 256 Bits - The expected value to be received by the `feeRecipient` in wei - - `blobsBundle`: [`BlobsBundleV1`](#BlobsBundleV1) - Bundle with data corresponding to blob transactions included into `executionPayload` -* error: code and message set in case an exception happens while getting the payload. - -#### Specification - -Refer to the specification for `engine_getPayloadV2` with addition of the following: - -1. The call **MUST** return empty `blobs`, `commitments` and `proofs` if the payload doesn't contain any blob transactions. - -2. The call **MUST** return `commitments` matching the versioned hashes of the transactions list of the execution payload, in the same order, - i.e. `assert verify_kzg_commitments_against_transactions(payload.transactions, bundle.commitments)` (see EIP-4844 consensus-specs). - -3. The call **MUST** return `blobs` and `proofs` that match the `commitments` list, i.e. `assert len(commitments) == len(blobs) == len(proofs)` and `assert verify_blob_kzg_proof_batch(bundle.blobs, bundle.commitments, bundle.proofs)`. - -4. Client software **MUST** return `-38005: Unsupported fork` error if the `timestamp` of the built payload is less than the EIP-4844 activation timestamp. diff --git a/src/engine/paris.md b/src/engine/paris.md index f726c403e..6a96957b6 100644 --- a/src/engine/paris.md +++ b/src/engine/paris.md @@ -159,15 +159,18 @@ The payload build process is specified as follows: #### Specification -1. Client software **MUST** validate `blockHash` value as being equivalent to `Keccak256(RLP(ExecutionBlockHeader))`, where `ExecutionBlockHeader` is the execution layer block header (the former PoW block header structure). Fields of this object are set to the corresponding payload values and constant values according to the Block structure section of [EIP-3675](https://eips.ethereum.org/EIPS/eip-3675#block-structure), extended with the corresponding section of [EIP-4399](https://eips.ethereum.org/EIPS/eip-4399#block-structure). Client software **MUST** run this validation in all cases even if this branch or any other branches of the block tree are in an active sync process. -2. Client software **MAY** initiate a sync process if requisite data for payload validation is missing. Sync process is specified in the [Sync](#sync) section. +1. Client software **MUST** return `-38005: Unsupported fork` error if the `timestamp` of the payload is greater or equal to the Cancun activation timestamp. -3. Client software **MUST** validate the payload if it extends the canonical chain and requisite data for the validation is locally available. The validation process is specified in the [Payload validation](#payload-validation) section. +2. Client software **MUST** validate `blockHash` value as being equivalent to `Keccak256(RLP(ExecutionBlockHeader))`, where `ExecutionBlockHeader` is the execution layer block header (the former PoW block header structure). Fields of this object are set to the corresponding payload values and constant values according to the Block structure section of [EIP-3675](https://eips.ethereum.org/EIPS/eip-3675#block-structure), extended with the corresponding section of [EIP-4399](https://eips.ethereum.org/EIPS/eip-4399#block-structure). Client software **MUST** run this validation in all cases even if this branch or any other branches of the block tree are in an active sync process. -4. Client software **MAY NOT** validate the payload if the payload doesn't belong to the canonical chain. +3. Client software **MAY** initiate a sync process if requisite data for payload validation is missing. Sync process is specified in the [Sync](#sync) section. -5. Client software **MUST** respond to this method call in the following way: +4. Client software **MUST** validate the payload if it extends the canonical chain and requisite data for the validation is locally available. The validation process is specified in the [Payload validation](#payload-validation) section. + +5. Client software **MAY NOT** validate the payload if the payload doesn't belong to the canonical chain. + +6. Client software **MUST** respond to this method call in the following way: * `{status: INVALID_BLOCK_HASH, latestValidHash: null, validationError: errorMessage | null}` if the `blockHash` validation has failed * `{status: INVALID, latestValidHash: 0x0000000000000000000000000000000000000000000000000000000000000000, validationError: errorMessage | null}` if terminal block conditions are not satisfied * `{status: SYNCING, latestValidHash: null, validationError: null}` if requisite data for the payload's acceptance or validation is missing @@ -178,7 +181,7 @@ The payload build process is specified as follows: - the payload hasn't been fully validated - ancestors of a payload are known and comprise a well-formed chain. -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. +7. 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_forkchoiceUpdatedV1 @@ -251,7 +254,9 @@ The payload build process is specified as follows: 2. The call **MUST** return `-38001: Unknown payload` error if the build process identified by the `payloadId` does not exist. -3. Client software **MAY** stop the corresponding build process after serving this call. +3. Client software **MUST** return `-38005: Unsupported fork` error if the `timestamp` of the payload is greater or equal to the Cancun activation timestamp. + +4. Client software **MAY** stop the corresponding build process after serving this call. ### engine_exchangeTransitionConfigurationV1 From c9ba39b99d138941eaca91c5e58ca69acae566ac Mon Sep 17 00:00:00 2001 From: Alexey Osipov Date: Thu, 29 Jun 2023 19:43:25 +0300 Subject: [PATCH 2/7] Place updates for old methods in the Cancun spec --- src/engine/cancun.md | 45 +++++++++++++++++++++++++++++++++----------- src/engine/paris.md | 19 +++++++------------ 2 files changed, 41 insertions(+), 23 deletions(-) diff --git a/src/engine/cancun.md b/src/engine/cancun.md index 3a4d0b62e..654c329d5 100644 --- a/src/engine/cancun.md +++ b/src/engine/cancun.md @@ -94,9 +94,9 @@ Refer to the response for [`engine_newPayloadV2`](./shanghai.md#engine_newpayloa This method follows the same specification as [`engine_newPayloadV2`](./shanghai.md#engine_newpayloadv2) with the addition of the following: -1. Client software **MUST** return `-32602: Invalid params` error unless all parameters and their fields are provided with non-`null` values. +1. Client software **MUST** return `-38005: Unsupported fork` error if the `timestamp` of the payload is less than the Cancun activation timestamp. -2. Client software **MUST** return `-38005: Unsupported fork` error if the `timestamp` of the payload is less than the Cancun activation timestamp. This rule replaces similar one defined for `engine_newPayloadV1`. +2. Client software **MUST** return `-32602: Invalid params` error unless all parameters and their fields are provided with non-`null` values. 3. Given the expected array of blob versioned hashes client software **MUST** run its validation by taking the following steps: 1. Obtain the actual array by concatenating blob versioned hashes lists (`tx.blob_versioned_hashes`) of each [blob transaction](https://eips.ethereum.org/EIPS/eip-4844#new-transaction-type) included in the payload, respecting the order of inclusion. If the payload has no blob transactions the expected array **MUST** be `[]`. @@ -114,10 +114,6 @@ This method follows the same specification as [`engine_newPayloadV2`](./shanghai 2. `payloadAttributes`: `Object|null` - Instance of [`PayloadAttributesV3`](#payloadattributesv3) or `null`. * timeout: 8s -Client software **MUST** return `-32602: Invalid params` error unless: -* every field of `forkchoiceState` is provided with non-`null` value, -* every field of `payloadAttributes` is provided with non-`null` values when `payloadAttributes` is not `null`. - #### Response Refer to the response for [`engine_forkchoiceUpdatedV2`](./shanghai.md#engine_forkchoiceupdatedv2). @@ -128,6 +124,10 @@ This method follows the same specification as [`engine_forkchoiceUpdatedV2`](./s 1. Client software **MUST** return `-38005: Unsupported fork` error if the `payloadAttributes.timestamp` is less than the Cancun activation timestamp. +2. Client software **MUST** return `-32602: Invalid params` error unless: + * every field of `forkchoiceState` is provided with non-`null` value, + * every field of `payloadAttributes` is provided with non-`null` values when `payloadAttributes` is not `null`. + ### engine_getPayloadV3 The response of this method is extended with [`BlobsBundleV1`](#blobsbundlev1) containing the blobs, their respective KZG commitments @@ -152,14 +152,14 @@ and proofs corresponding to the `versioned_hashes` included in the blob transact Refer to the specification for [`engine_getPayloadV2`](./shanghai.md#engine_getpayloadv2) with addition of the following: -1. The call **MUST** return `blobsBundle` with empty `blobs`, `commitments` and `proofs` if the payload doesn't contain any blob transactions. +1. Client software **MUST** return `-38005: Unsupported fork` error if the `timestamp` of the built payload is less than the Cancun activation timestamp. -2. The call **MUST** return `commitments` matching the versioned hashes of the transactions list of the execution payload, in the same order, - i.e. `assert verify_kzg_commitments_against_transactions(payload.transactions, blobsBundle.commitments)` (see EIP-4844 consensus-specs). +2. The call **MUST** return `blobsBundle` with empty `blobs`, `commitments` and `proofs` if the payload doesn't contain any blob transactions. -3. The call **MUST** return `blobs` and `proofs` that match the `commitments` list, i.e. `assert len(blobsBundle.commitments) == len(blobsBundle.blobs) == len(blobsBundle.proofs)` and `assert verify_blob_kzg_proof_batch(blobsBundle.blobs, blobsBundle.commitments, blobsBundle.proofs)`. +3. The call **MUST** return `commitments` matching the versioned hashes of the transactions list of the execution payload, in the same order, + i.e. `assert verify_kzg_commitments_against_transactions(payload.transactions, blobsBundle.commitments)` (see EIP-4844 consensus-specs). -4. Client software **MUST** return `-38005: Unsupported fork` error if the `timestamp` of the built payload is less than the Cancun activation timestamp. +4. The call **MUST** return `blobs` and `proofs` that match the `commitments` list, i.e. `assert len(blobsBundle.commitments) == len(blobsBundle.blobs) == len(blobsBundle.proofs)` and `assert verify_blob_kzg_proof_batch(blobsBundle.blobs, blobsBundle.commitments, blobsBundle.proofs)`. ### Deprecate `engine_exchangeTransitionConfigurationV1` @@ -170,3 +170,26 @@ This document introduces deprecation of [`engine_exchangeTransitionConfiguration 2. Execution layer clients **MUST NOT** surface an error message to the user if this method is not called. 3. Consensus and execution layer clients **MAY** remove support of this method after Cancun. If no longer supported, this method **MUST** be removed from the [`engine_exchangeCapabilities`](./common.md#engine_exchangecapabilities) request or response list depending on whether it is consensus or execution layer client. + + +### Update methods of previous forks + +For the following methods: + +- `engine_newPayloadV1` +- `engine_newPayloadV2` +- `engine_getPayloadV1` +- `engine_getPayloadV2` + +an early validation **MUST** be added: + +1. Client software **MUST** return `-38005: Unsupported fork` error if the `timestamp` of the payload is greater or equal to the Cancun activation timestamp. + +For the following methods: + +- `engine_forkchoiceUpdatedV1` +- `engine_forkchoiceUpdatedV2` + +similar early validation **MUST** be added: + +1. Client software **MUST** return `-38005: Unsupported fork` error if the `payloadAttributes.timestamp` of the payload is greater or equal to the Cancun activation timestamp. \ No newline at end of file diff --git a/src/engine/paris.md b/src/engine/paris.md index 6a96957b6..f726c403e 100644 --- a/src/engine/paris.md +++ b/src/engine/paris.md @@ -159,18 +159,15 @@ The payload build process is specified as follows: #### Specification +1. Client software **MUST** validate `blockHash` value as being equivalent to `Keccak256(RLP(ExecutionBlockHeader))`, where `ExecutionBlockHeader` is the execution layer block header (the former PoW block header structure). Fields of this object are set to the corresponding payload values and constant values according to the Block structure section of [EIP-3675](https://eips.ethereum.org/EIPS/eip-3675#block-structure), extended with the corresponding section of [EIP-4399](https://eips.ethereum.org/EIPS/eip-4399#block-structure). Client software **MUST** run this validation in all cases even if this branch or any other branches of the block tree are in an active sync process. -1. Client software **MUST** return `-38005: Unsupported fork` error if the `timestamp` of the payload is greater or equal to the Cancun activation timestamp. +2. Client software **MAY** initiate a sync process if requisite data for payload validation is missing. Sync process is specified in the [Sync](#sync) section. -2. Client software **MUST** validate `blockHash` value as being equivalent to `Keccak256(RLP(ExecutionBlockHeader))`, where `ExecutionBlockHeader` is the execution layer block header (the former PoW block header structure). Fields of this object are set to the corresponding payload values and constant values according to the Block structure section of [EIP-3675](https://eips.ethereum.org/EIPS/eip-3675#block-structure), extended with the corresponding section of [EIP-4399](https://eips.ethereum.org/EIPS/eip-4399#block-structure). Client software **MUST** run this validation in all cases even if this branch or any other branches of the block tree are in an active sync process. +3. Client software **MUST** validate the payload if it extends the canonical chain and requisite data for the validation is locally available. The validation process is specified in the [Payload validation](#payload-validation) section. -3. Client software **MAY** initiate a sync process if requisite data for payload validation is missing. Sync process is specified in the [Sync](#sync) section. +4. Client software **MAY NOT** validate the payload if the payload doesn't belong to the canonical chain. -4. Client software **MUST** validate the payload if it extends the canonical chain and requisite data for the validation is locally available. The validation process is specified in the [Payload validation](#payload-validation) section. - -5. Client software **MAY NOT** validate the payload if the payload doesn't belong to the canonical chain. - -6. Client software **MUST** respond to this method call in the following way: +5. Client software **MUST** respond to this method call in the following way: * `{status: INVALID_BLOCK_HASH, latestValidHash: null, validationError: errorMessage | null}` if the `blockHash` validation has failed * `{status: INVALID, latestValidHash: 0x0000000000000000000000000000000000000000000000000000000000000000, validationError: errorMessage | null}` if terminal block conditions are not satisfied * `{status: SYNCING, latestValidHash: null, validationError: null}` if requisite data for the payload's acceptance or validation is missing @@ -181,7 +178,7 @@ The payload build process is specified as follows: - the payload hasn't been fully validated - ancestors of a payload are known and comprise a well-formed chain. -7. 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. +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_forkchoiceUpdatedV1 @@ -254,9 +251,7 @@ The payload build process is specified as follows: 2. The call **MUST** return `-38001: Unknown payload` error if the build process identified by the `payloadId` does not exist. -3. Client software **MUST** return `-38005: Unsupported fork` error if the `timestamp` of the payload is greater or equal to the Cancun activation timestamp. - -4. Client software **MAY** stop the corresponding build process after serving this call. +3. Client software **MAY** stop the corresponding build process after serving this call. ### engine_exchangeTransitionConfigurationV1 From 55c1b6331fe5370a9af374cd4d72413943160ebd Mon Sep 17 00:00:00 2001 From: Alexey Osipov Date: Mon, 10 Jul 2023 15:51:38 +0300 Subject: [PATCH 3/7] Stricter rules of handling payloads depending on method version and fork --- src/engine/cancun.md | 25 ++++++++++++------------- 1 file changed, 12 insertions(+), 13 deletions(-) diff --git a/src/engine/cancun.md b/src/engine/cancun.md index 654c329d5..cd9d45382 100644 --- a/src/engine/cancun.md +++ b/src/engine/cancun.md @@ -94,7 +94,7 @@ Refer to the response for [`engine_newPayloadV2`](./shanghai.md#engine_newpayloa This method follows the same specification as [`engine_newPayloadV2`](./shanghai.md#engine_newpayloadv2) with the addition of the following: -1. Client software **MUST** return `-38005: Unsupported fork` error if the `timestamp` of the payload is less than the Cancun activation timestamp. +1. Client software **MUST** return `-38005: Unsupported fork` error if the `timestamp` of the payload does not fall within the time frame of the Cancun fork. 2. Client software **MUST** return `-32602: Invalid params` error unless all parameters and their fields are provided with non-`null` values. @@ -122,7 +122,7 @@ Refer to the response for [`engine_forkchoiceUpdatedV2`](./shanghai.md#engine_fo This method follows the same specification as [`engine_forkchoiceUpdatedV2`](./shanghai.md#engine_forkchoiceupdatedv2) with addition of the following: -1. Client software **MUST** return `-38005: Unsupported fork` error if the `payloadAttributes.timestamp` is less than the Cancun activation timestamp. +1. Client software **MUST** return `-38005: Unsupported fork` error if the `payloadAttributes.timestamp` does not fall within the time frame of the Cancun fork. 2. Client software **MUST** return `-32602: Invalid params` error unless: * every field of `forkchoiceState` is provided with non-`null` value, @@ -152,7 +152,7 @@ and proofs corresponding to the `versioned_hashes` included in the blob transact Refer to the specification for [`engine_getPayloadV2`](./shanghai.md#engine_getpayloadv2) with addition of the following: -1. Client software **MUST** return `-38005: Unsupported fork` error if the `timestamp` of the built payload is less than the Cancun activation timestamp. +1. Client software **MUST** return `-38005: Unsupported fork` error if the `timestamp` of the built payload does not fall within the time frame of the Cancun fork. 2. The call **MUST** return `blobsBundle` with empty `blobs`, `commitments` and `proofs` if the payload doesn't contain any blob transactions. @@ -171,25 +171,24 @@ This document introduces deprecation of [`engine_exchangeTransitionConfiguration 3. Consensus and execution layer clients **MAY** remove support of this method after Cancun. If no longer supported, this method **MUST** be removed from the [`engine_exchangeCapabilities`](./common.md#engine_exchangecapabilities) request or response list depending on whether it is consensus or execution layer client. - -### Update methods of previous forks +### Update the methods of previous forks For the following methods: -- `engine_newPayloadV1` -- `engine_newPayloadV2` - `engine_getPayloadV1` -- `engine_getPayloadV2` +- `engine_newPayloadV1` +- `engine_forkchoiceUpdatedV1` -an early validation **MUST** be added: +an early **MUST** be added: -1. Client software **MUST** return `-38005: Unsupported fork` error if the `timestamp` of the payload is greater or equal to the Cancun activation timestamp. +1. Client software **MUST** return `-38005: Unsupported fork` error if the `timestamp` of payload or payloadAttributes does not fall within the time frame of the Paris fork. For the following methods: -- `engine_forkchoiceUpdatedV1` +- `engine_getPayloadV2` +- `engine_newPayloadV2` - `engine_forkchoiceUpdatedV2` -similar early validation **MUST** be added: +an early **MUST** be added: -1. Client software **MUST** return `-38005: Unsupported fork` error if the `payloadAttributes.timestamp` of the payload is greater or equal to the Cancun activation timestamp. \ No newline at end of file +1. Client software **MUST** return `-38005: Unsupported fork` error if the `timestamp` of payload or payloadAttributes does not fall within the time frame of the Shanghai fork. \ No newline at end of file From 8a0ef17abe1d5d7990fed03451be51ce69089e22 Mon Sep 17 00:00:00 2001 From: Alexey Osipov Date: Mon, 10 Jul 2023 16:53:04 +0300 Subject: [PATCH 4/7] Do not change *V1 APIs; clarify params validation --- src/engine/cancun.md | 26 ++++++++------------------ 1 file changed, 8 insertions(+), 18 deletions(-) diff --git a/src/engine/cancun.md b/src/engine/cancun.md index cd9d45382..9a4123802 100644 --- a/src/engine/cancun.md +++ b/src/engine/cancun.md @@ -96,7 +96,7 @@ This method follows the same specification as [`engine_newPayloadV2`](./shanghai 1. Client software **MUST** return `-38005: Unsupported fork` error if the `timestamp` of the payload does not fall within the time frame of the Cancun fork. -2. Client software **MUST** return `-32602: Invalid params` error unless all parameters and their fields are provided with non-`null` values. +2. Client software **MUST** check that provided set of parameters and their fields strictly matches the expected one and return `-32602: Invalid params` error if this check fails. Any field having `null` value **MUST** be considered as not provided. 3. Given the expected array of blob versioned hashes client software **MUST** run its validation by taking the following steps: 1. Obtain the actual array by concatenating blob versioned hashes lists (`tx.blob_versioned_hashes`) of each [blob transaction](https://eips.ethereum.org/EIPS/eip-4844#new-transaction-type) included in the payload, respecting the order of inclusion. If the payload has no blob transactions the expected array **MUST** be `[]`. @@ -124,9 +124,7 @@ This method follows the same specification as [`engine_forkchoiceUpdatedV2`](./s 1. Client software **MUST** return `-38005: Unsupported fork` error if the `payloadAttributes.timestamp` does not fall within the time frame of the Cancun fork. -2. Client software **MUST** return `-32602: Invalid params` error unless: - * every field of `forkchoiceState` is provided with non-`null` value, - * every field of `payloadAttributes` is provided with non-`null` values when `payloadAttributes` is not `null`. +2. Client software **MUST** check that provided set of parameters and their fields strictly matches the expected one and return `-32602: Invalid params` error if this check fails. Any field having `null` value **MUST** be considered as not provided. ### engine_getPayloadV3 @@ -173,22 +171,14 @@ This document introduces deprecation of [`engine_exchangeTransitionConfiguration ### Update the methods of previous forks -For the following methods: - -- `engine_getPayloadV1` -- `engine_newPayloadV1` -- `engine_forkchoiceUpdatedV1` - -an early **MUST** be added: - -1. Client software **MUST** return `-38005: Unsupported fork` error if the `timestamp` of payload or payloadAttributes does not fall within the time frame of the Paris fork. +This document defines how Cancun payload should be handled by the [`Shanghai API`](./shanghai.md). For the following methods: -- `engine_getPayloadV2` -- `engine_newPayloadV2` -- `engine_forkchoiceUpdatedV2` +- [`engine_forkchoiceUpdatedV2`](./shanghai.md#engine_forkchoiceupdatedv2) +- [`engine_newPayloadV2`](./shanghai.md#engine_newpayloadV2) +- [`engine_getPayloadV2`](./shanghai.md#engine_getpayloadv2) -an early **MUST** be added: +an early validation **MUST** be added: -1. Client software **MUST** return `-38005: Unsupported fork` error if the `timestamp` of payload or payloadAttributes does not fall within the time frame of the Shanghai fork. \ No newline at end of file +1. Client software **MUST** return `-38005: Unsupported fork` error if the `timestamp` of payload or payloadAttributes greater or equal to the Cancun activation timestamp. \ No newline at end of file From 292f5bec2ecc2520375d8bc1eacc89157076853f Mon Sep 17 00:00:00 2001 From: Alexey Osipov Date: Thu, 3 Aug 2023 18:45:03 +0300 Subject: [PATCH 5/7] Move timestamp validation down to ease more basic params validation --- src/engine/cancun.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/engine/cancun.md b/src/engine/cancun.md index 9a4123802..4bbec1178 100644 --- a/src/engine/cancun.md +++ b/src/engine/cancun.md @@ -94,9 +94,9 @@ Refer to the response for [`engine_newPayloadV2`](./shanghai.md#engine_newpayloa This method follows the same specification as [`engine_newPayloadV2`](./shanghai.md#engine_newpayloadv2) with the addition of the following: -1. Client software **MUST** return `-38005: Unsupported fork` error if the `timestamp` of the payload does not fall within the time frame of the Cancun fork. +1. Client software **MUST** check that provided set of parameters and their fields strictly matches the expected one and return `-32602: Invalid params` error if this check fails. Any field having `null` value **MUST** be considered as not provided. -2. Client software **MUST** check that provided set of parameters and their fields strictly matches the expected one and return `-32602: Invalid params` error if this check fails. Any field having `null` value **MUST** be considered as not provided. +2. Client software **MUST** return `-38005: Unsupported fork` error if the `timestamp` of the payload does not fall within the time frame of the Cancun fork. 3. Given the expected array of blob versioned hashes client software **MUST** run its validation by taking the following steps: 1. Obtain the actual array by concatenating blob versioned hashes lists (`tx.blob_versioned_hashes`) of each [blob transaction](https://eips.ethereum.org/EIPS/eip-4844#new-transaction-type) included in the payload, respecting the order of inclusion. If the payload has no blob transactions the expected array **MUST** be `[]`. @@ -122,9 +122,9 @@ Refer to the response for [`engine_forkchoiceUpdatedV2`](./shanghai.md#engine_fo This method follows the same specification as [`engine_forkchoiceUpdatedV2`](./shanghai.md#engine_forkchoiceupdatedv2) with addition of the following: -1. Client software **MUST** return `-38005: Unsupported fork` error if the `payloadAttributes.timestamp` does not fall within the time frame of the Cancun fork. +1. Client software **MUST** check that provided set of parameters and their fields strictly matches the expected one and return `-32602: Invalid params` error if this check fails. Any field having `null` value **MUST** be considered as not provided. -2. Client software **MUST** check that provided set of parameters and their fields strictly matches the expected one and return `-32602: Invalid params` error if this check fails. Any field having `null` value **MUST** be considered as not provided. +2. Client software **MUST** return `-38005: Unsupported fork` error if the `payloadAttributes.timestamp` does not fall within the time frame of the Cancun fork. ### engine_getPayloadV3 @@ -179,6 +179,6 @@ For the following methods: - [`engine_newPayloadV2`](./shanghai.md#engine_newpayloadV2) - [`engine_getPayloadV2`](./shanghai.md#engine_getpayloadv2) -an early validation **MUST** be added: +a validation **MUST** be added: 1. Client software **MUST** return `-38005: Unsupported fork` error if the `timestamp` of payload or payloadAttributes greater or equal to the Cancun activation timestamp. \ No newline at end of file From ad2ccb0cff295f82dae7a49ef38b319121cffe74 Mon Sep 17 00:00:00 2001 From: Alexey Date: Fri, 4 Aug 2023 08:15:59 +0300 Subject: [PATCH 6/7] Decline payloads with headBlockHash of pre-Cancun blocks Co-authored-by: g11tech --- src/engine/cancun.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/src/engine/cancun.md b/src/engine/cancun.md index 4bbec1178..99994db03 100644 --- a/src/engine/cancun.md +++ b/src/engine/cancun.md @@ -124,7 +124,9 @@ This method follows the same specification as [`engine_forkchoiceUpdatedV2`](./s 1. Client software **MUST** check that provided set of parameters and their fields strictly matches the expected one and return `-32602: Invalid params` error if this check fails. Any field having `null` value **MUST** be considered as not provided. -2. Client software **MUST** return `-38005: Unsupported fork` error if the `payloadAttributes.timestamp` does not fall within the time frame of the Cancun fork. +2. Client software **MUST** return `-38005: Unsupported fork` error + * if the `payloadAttributes.timestamp` does not fall within the time frame of the Cancun fork or + * if the `forkchoiceState.headBlockHash` refers to a pre-Cancun block (if resolvable by EL) when forkchoice update issued without `payloadAttributes` ### engine_getPayloadV3 From da5cf65c89c55995fed99effaef9ba27d2e00f85 Mon Sep 17 00:00:00 2001 From: Alexey Osipov Date: Fri, 4 Aug 2023 12:32:36 +0300 Subject: [PATCH 7/7] Check only when `payloadAttributes` is set --- src/engine/cancun.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/src/engine/cancun.md b/src/engine/cancun.md index 99994db03..84479273e 100644 --- a/src/engine/cancun.md +++ b/src/engine/cancun.md @@ -124,9 +124,7 @@ This method follows the same specification as [`engine_forkchoiceUpdatedV2`](./s 1. Client software **MUST** check that provided set of parameters and their fields strictly matches the expected one and return `-32602: Invalid params` error if this check fails. Any field having `null` value **MUST** be considered as not provided. -2. Client software **MUST** return `-38005: Unsupported fork` error - * if the `payloadAttributes.timestamp` does not fall within the time frame of the Cancun fork or - * if the `forkchoiceState.headBlockHash` refers to a pre-Cancun block (if resolvable by EL) when forkchoice update issued without `payloadAttributes` +2. Client software **MUST** return `-38005: Unsupported fork` error if the `payloadAttributes` is set and the `payloadAttributes.timestamp` does not fall within the time frame of the Cancun fork. ### engine_getPayloadV3