Skip to content

cancun.md

Latest commit

 

History

History
238 lines (156 loc) · 12.4 KB

cancun.md

File metadata and controls

238 lines (156 loc) · 12.4 KB

Engine API -- Cancun

Engine API changes introduced in Cancun.

This specification is based on and extends Engine API - Shanghai specification.

Table of contents

Structures

ExecutionPayloadV3

This structure has the syntax of ExecutionPayloadV2 and appends the new fields: blobGasUsed and excessBlobGas.

  • 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
  • withdrawals: Array of WithdrawalV1 - Array of withdrawals, each object is an OBJECT containing the fields of a WithdrawalV1 structure.
  • blobGasUsed: QUANTITY, 64 Bits
  • excessBlobGas: QUANTITY, 64 Bits

BlobsBundleV1

The fields are encoded as follows:

  • commitments: Array of DATA - Array of KZGCommitment as defined in EIP-4844, 48 bytes each (DATA).
  • proofs: Array of DATA - Array of KZGProof as defined in 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

All of the above three arrays MUST be of same length.

BlobAndProofV1

The fields are encoded as follows:

  • blob: DATA - FIELD_ELEMENTS_PER_BLOB * BYTES_PER_FIELD_ELEMENT = 4096 * 32 = 131072 bytes (DATA) representing a SSZ-encoded Blob as defined in EIP-4844.
  • proof: DATA - KZGProof as defined in EIP-4844, 48 bytes (DATA).

PayloadAttributesV3

This structure has the syntax of PayloadAttributesV2 and appends a single field: parentBeaconBlockRoot.

  • 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.
  • parentBeaconBlockRoot: DATA, 32 Bytes - Root of the parent beacon block.

Methods

engine_newPayloadV3

Request

  • method: engine_newPayloadV3
  • params:
    1. executionPayload: ExecutionPayloadV3.
    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.

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. 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 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.

engine_forkchoiceUpdatedV3

Request

Response

Refer to the response for engine_forkchoiceUpdatedV2.

Specification

This method follows the same specification as engine_forkchoiceUpdatedV2 with the following changes to the processing flow:

  1. Client software MUST verify that forkchoiceState matches the ForkchoiceStateV1 structure and return -32602: Invalid params on failure.

  2. Extend point (7) of the engine_forkchoiceUpdatedV1 specification by defining the following sequence of checks that MUST be run over payloadAttributes:

    1. payloadAttributes matches the PayloadAttributesV3 structure, return -38003: Invalid payload attributes on failure.

    2. payloadAttributes.timestamp does not fall within the time frame of the Cancun fork, return -38005: Unsupported fork on failure.

    3. payloadAttributes.timestamp is greater than timestamp of a block referenced by forkchoiceState.headBlockHash, return -38003: Invalid payload attributes on failure.

    4. If any of the above checks fails, the forkchoiceState update MUST NOT be rolled back.

engine_getPayloadV3

The response of this method is extended with 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
    • blockValue : QUANTITY, 256 Bits - The expected value to be received by the feeRecipient in wei
    • blobsBundle: BlobsBundleV1 - Bundle with data corresponding to blob transactions included into executionPayload
    • shouldOverrideBuilder : BOOLEAN - Suggestion from the execution layer to use this executionPayload instead of an externally provided one
  • 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. 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.

  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. 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).

  5. Client software MAY use any heuristics to decide whether to set shouldOverrideBuilder flag or not. If client software does not implement any heuristic this flag SHOULD be set to false.

engine_getBlobsV1

Consensus layer clients MAY use this method to fetch blobs from the execution layer blob pool.

Note: This is a new method introduced after Cancun. It is defined here because it is backwards-compatible with Cancun.

Request

  • method: engine_getBlobsV1
  • params:
    1. Array of DATA, 32 Bytes - Array of blob versioned hashes.
  • timeout: 1s

Response

  • result: Array of BlobAndProofV1 - Array of BlobAndProofV1, items of which may be null.
  • error: code and message set in case an error occurs during processing of the request.

Specification

  1. Given an array of blob versioned hashes client software MUST respond with an array of BlobAndProofV1 objects with matching versioned hashes, respecting the order of versioned hashes in the input array.

  2. Client software MUST place responses in the order given in the request, using null for any missing blobs. For instance, if the request is [A_versioned_hash, B_versioned_hash, C_versioned_hash] and client software has data for blobs A and C, but doesn't have data for B, the response MUST be [A, null, C].

  3. Client software MUST support request sizes of at least 128 blob versioned hashes. The client MUST return -38004: Too large request error if the number of requested blobs is too large.

  4. Client software MAY return an array of all null entries if syncing or otherwise unable to serve blob pool data.

  5. Callers MUST consider that execution layer clients may prune old blobs from their pool, and will respond with null if a blob has been pruned.

Deprecate engine_exchangeTransitionConfigurationV1

This document introduces deprecation of engine_exchangeTransitionConfigurationV1. The deprecation is specified as follows:

  1. Consensus layer clients MUST NOT call this method.

  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 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.

For the following methods:

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.