Skip to main content

Engine API objects

The following objects are parameters for or returned by the Engine API methods.

Blob and proof object

Returned by engine_getBlobsV1.

KeyTypeValue
blobData, 131072 BytesAn SSZ-encoded Blob as defined in EIP-4844.
proofData, 48 BytesA KZGProof as defined in EIP-4844.

Execution payload object

Parameter for engine_newPayloadV1. Returned by engine_getPayloadV1.

KeyTypeValue
parentHashData, 32 BytesHash of the parent block.
feeRecipientData, 20 BytesBeneficiary of the fee.
stateRootData, 32 BytesRoot of the final state trie for the block.
receiptsRootData, 32 BytesRoot of the receipts trie for the block.
logsBloomData, 256 BytesBloom filter for light clients to quickly retrieve related logs.
prevRandaoData, 32 BytesDifficulty for this block.
blockNumberQuantity, 64 BitsBlock number of block containing this transaction.
gasLimitQuantity, 64 BitsMaximum gas allowed in this block.
gasUsedQuantity, 64 BitsTotal gas used by all transactions in this block.
timestampQuantity, 64 BitsUnix timestamp (milliseconds) for block assembly.
extraDataData, 0 to 32 BytesExtra data field for this block.
baseFeePerGasQuantity, 256 BitsThe block's base fee per gas. This field is empty for blocks created before EIP-1559.
blockHashData, 32 BytesHash of the execution block.
transactionsArrayArray of transaction objects, each object is a list representing TransactionType, TransactionPayload, or LegacyTransaction as defined in EIP-2718.

Fork choice state object

Parameter for engine_forkchoiceUpdatedV1.

KeyTypeValue
headBlockHashData, 32 BytesBlock hash of the head of the canonical chain.
safeBlockHashData, 32 Bytes"Safe" block hash of the canonical chain under certain synchrony and honesty assumptions. This value MUST be either equal to or an ancestor of headBlockHash.
finalizedBlockHashData, 32 BytesBlock hash of the most recent finalized block.

Payload attributes object

Parameter for engine_forkchoiceUpdatedV1.

KeyTypeValue
timestampQuantity, 64 BitsValue for the timestamp field of the new payload.
prevRandaoData, 32 BytesValue for the prevRandao field of the new payload.
suggestedFeeRecipientData, 20 BytesSuggested value for the feeRecipient field of the new payload.

Payload status object

Returned by engine_newPayloadV1 and engine_forkchoiceUpdatedV1.

KeyTypeValue
statusEnumerationEither "VALID", "INVALID", "SYNCING", "ACCEPTED", "INVALID_BLOCK_HASH", or "INVALID_TERMINAL_BLOCK".
latestValidHashData, 32 BytesHash of the most recent valid block in the branch defined by payload and its ancestors.
validationErrorStringMessage providing additional details on the validation error if the payload is classified as INVALID, INVALID_BLOCK_HASH or INVALID_TERMINAL_BLOCK.

Transition configuration object

Parameter for and returned by engine_exchangeTransitionConfigurationV1.

KeyTypeValue
terminalTotalDifficultyQuantity, 256 BitsMaps on the TERMINAL_TOTAL_DIFFICULTY parameter of EIP-3675.
terminalBlockHashData, 32 BytesMaps on the TERMINAL_BLOCK_HASH parameter of EIP-3675.
terminalBlockNumberQuantity, 64 BitsMaps on the TERMINAL_BLOCK_NUMBER parameter of EIP-3675.