Skip to content

Clarify Cancun payloads handling by earlier APIs; reorder checks #426

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
mkalinin merged 7 commits into from
Aug 4, 2023
Merged

Clarify Cancun payloads handling by earlier APIs; reorder checks #426

Show file tree
Hide file tree
Changes from 5 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
a338ce4
Clarify Cancun payloads handling by Shanghai APIs; reorder checks
flcl42 Jun 29, 2023
c9ba39b
Place updates for old methods in the Cancun spec
flcl42 Jun 29, 2023
55c1b63
Stricter rules of handling payloads depending on method version and fork
flcl42 Jul 10, 2023
8a0ef17
Do not change *V1 APIs; clarify params validation
flcl42 Jul 10, 2023
292f5be
Move timestamp validation down to ease more basic params validation
flcl42 Aug 3, 2023
ad2ccb0
Decline payloads with headBlockHash of pre-Cancun blocks
flcl42 Aug 4, 2023
da5cf65
Check only when `payloadAttributes` is set
flcl42 Aug 4, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 28 additions & 16 deletions src/engine/cancun.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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).
Expand All @@ -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.

@g11tech g11tech Aug 3, 2023

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

+1 for first checking correct fields before timestamp


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
Expand All @@ -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).
Expand All @@ -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.timestamp` does not fall within the time frame of the Cancun fork.
Comment thread
flcl42 marked this conversation as resolved.
Outdated

### engine_getPayloadV3

Expand All @@ -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`

Expand All @@ -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.
120 changes: 0 additions & 120 deletions src/engine/experimental/blob-extension.md
View file
Open in desktop

This file was deleted.