diff --git a/src/engine/cancun.md b/src/engine/cancun.md index 8abd2612e..84479273e 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** 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 `[]`. 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 @@ -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). @@ -126,7 +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` is less than the Cancun activation timestamp. +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` is set and the `payloadAttributes.timestamp` does not fall within the time frame of the Cancun fork. ### engine_getPayloadV3 @@ -152,14 +150,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 does not fall within the time frame of the Cancun fork. -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 +168,17 @@ 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 the methods of previous forks + +This document defines how Cancun payload should be handled by the [`Shanghai API`](./shanghai.md). + +For the following methods: + +- [`engine_forkchoiceUpdatedV2`](./shanghai.md#engine_forkchoiceupdatedv2) +- [`engine_newPayloadV2`](./shanghai.md#engine_newpayloadV2) +- [`engine_getPayloadV2`](./shanghai.md#engine_getpayloadv2) + +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 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.