Engine API changes introduced in Cancun.
This specificaiton is based on and extends Engine API - Shanghai specification.
This structure has the syntax of ExecutionPayloadV2
and appends the new fields: blobGasUsed
and excessBlobGas
.
parentHash
:DATA
, 32 BytesfeeRecipient
:DATA
, 20 BytesstateRoot
:DATA
, 32 BytesreceiptsRoot
:DATA
, 32 ByteslogsBloom
:DATA
, 256 BytesprevRandao
:DATA
, 32 BytesblockNumber
:QUANTITY
, 64 BitsgasLimit
:QUANTITY
, 64 BitsgasUsed
:QUANTITY
, 64 Bitstimestamp
:QUANTITY
, 64 BitsextraData
:DATA
, 0 to 32 BytesbaseFeePerGas
:QUANTITY
, 256 BitsblockHash
:DATA
, 32 Bytestransactions
:Array of DATA
- Array of transaction objects, each object is a byte list (DATA
) representingTransactionType || TransactionPayload
orLegacyTransaction
as defined in EIP-2718withdrawals
:Array of WithdrawalV1
- Array of withdrawals, each object is anOBJECT
containing the fields of aWithdrawalV1
structure.blobGasUsed
:QUANTITY
, 64 BitsexcessBlobGas
:QUANTITY
, 64 Bits
The fields are encoded as follows:
commitments
:Array of DATA
- Array ofKZGCommitment
as defined in EIP-4844, 48 bytes each (DATA
).proofs
:Array of DATA
- Array ofKZGProof
as defined in EIP-4844, 48 bytes each (DATA
).blobs
:Array of DATA
- Array of blobs, each blob isFIELD_ELEMENTS_PER_BLOB * BYTES_PER_FIELD_ELEMENT = 4096 * 32 = 131072
bytes (DATA
) representing a SSZ-encodedBlob
as defined in EIP-4844
All of the above three arrays MUST be of same length.
This structure has the syntax of PayloadAttributesV2
and appends a single field: parentBeaconBlockRoot
.
timestamp
:QUANTITY
, 64 Bits - value for thetimestamp
field of the new payloadprevRandao
:DATA
, 32 Bytes - value for theprevRandao
field of the new payloadsuggestedFeeRecipient
:DATA
, 20 Bytes - suggested value for thefeeRecipient
field of the new payloadwithdrawals
:Array of WithdrawalV1
- Array of withdrawals, each object is anOBJECT
containing the fields of aWithdrawalV1
structure.parentBeaconBlockRoot
:DATA
, 32 Bytes - Root of the parent beacon block.
- method:
engine_newPayloadV3
- params:
executionPayload
:ExecutionPayloadV3
.expectedBlobVersionedHashes
:Array of DATA
, 32 Bytes - Array of expected blob versioned hashes to validate.parentBeaconBlockRoot
:DATA
, 32 Bytes - Root of the parent beacon block.
Refer to the response for engine_newPayloadV2
.
This method follows the same specification as engine_newPayloadV2
with the addition of the following:
-
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 havingnull
value MUST be considered as not provided. -
Client software MUST return
-38005: Unsupported fork
error if thetimestamp
of the payload does not fall within the time frame of the Cancun fork. -
Given the expected array of blob versioned hashes client software MUST run its validation by taking the following steps:
- 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[]
. - 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.
- Obtain the actual array by concatenating blob versioned hashes lists (
- method:
engine_forkchoiceUpdatedV3
- params:
forkchoiceState
:ForkchoiceStateV1
.payloadAttributes
:Object|null
- Instance ofPayloadAttributesV3
ornull
.
- timeout: 8s
Refer to the response for engine_forkchoiceUpdatedV2
.
This method follows the same specification as engine_forkchoiceUpdatedV2
with addition of the following:
-
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 havingnull
value MUST be considered as not provided. -
Client software MUST return
-38005: Unsupported fork
error if thepayloadAttributes
is set and thepayloadAttributes.timestamp
does not fall within the time frame of the Cancun fork.
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.
- method:
engine_getPayloadV3
- params:
payloadId
:DATA
, 8 Bytes - Identifier of the payload build process
- timeout: 1s
- result:
object
executionPayload
:ExecutionPayloadV3
blockValue
:QUANTITY
, 256 Bits - The expected value to be received by thefeeRecipient
in weiblobsBundle
:BlobsBundleV1
- Bundle with data corresponding to blob transactions included intoexecutionPayload
shouldOverrideBuilder
:BOOLEAN
- Suggestion from the execution layer to use thisexecutionPayload
instead of an externally provided one
- error: code and message set in case an exception happens while getting the payload.
Refer to the specification for engine_getPayloadV2
with addition of the following:
-
Client software MUST return
-38005: Unsupported fork
error if thetimestamp
of the built payload does not fall within the time frame of the Cancun fork. -
The call MUST return
blobsBundle
with emptyblobs
,commitments
andproofs
if the payload doesn't contain any blob transactions. -
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). -
The call MUST return
blobs
andproofs
that match thecommitments
list, i.e.assert len(blobsBundle.commitments) == len(blobsBundle.blobs) == len(blobsBundle.proofs)
andassert verify_blob_kzg_proof_batch(blobsBundle.blobs, blobsBundle.commitments, blobsBundle.proofs)
. -
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 tofalse
.
This document introduces deprecation of engine_exchangeTransitionConfigurationV1
. The deprecation is specified as follows:
-
Consensus layer clients MUST NOT call this method.
-
Execution layer clients MUST NOT surface an error message to the user if this method is not called.
-
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.
This document defines how Cancun payload should be handled by the Shanghai API
.
For the following methods:
a validation MUST be added:
- Client software MUST return
-38005: Unsupported fork
error if thetimestamp
of payload or payloadAttributes greater or equal to the Cancun activation timestamp.