Engine API changes introduced in Cancun.
This specification 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 the following changes to the processing flow:
-
Client software MUST verify that
forkchoiceState
matches theForkchoiceStateV1
structure and return-32602: Invalid params
on failure. -
Extend point (7) of the
engine_forkchoiceUpdatedV1
specification by defining the following sequence of checks that MUST be run overpayloadAttributes
:-
payloadAttributes
matches thePayloadAttributesV3
structure, return-38003: Invalid payload attributes
on failure. -
payloadAttributes.timestamp
falls within the time frame of the Cancun fork, return-38005: Unsupported fork
on failure. -
payloadAttributes.timestamp
is greater thantimestamp
of a block referenced byforkchoiceState.headBlockHash
, return-38003: Invalid payload attributes
on failure. -
If any of the above checks fails, the
forkchoiceState
update MUST NOT be rolled back.
-
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.