Skip to content

Blockchain Engine Tests

The Blockchain Engine Test fixture format tests are included in the fixtures subdirectory blockchain_tests_engine, and use Engine API directives instead of the usual BlockchainTest format.

These are produced by the StateTest and BlockchainTest test specs.

Description

The Blockchain Engine Test fixture format is used to test block validation and the consensus rules of the Ethereum blockchain, when a block is delivered through the Engine API as a engine_newPayloadVX directive.

It does so by defining a pre-execution state, a series of blocks as engine_newPayloadVX directives, and a post-execution state, verifying that, after all the blocks have been processed, appended if valid or rejected if invalid, the result is the expected post-execution state.

A single JSON fixture file is composed of a JSON object where each key-value pair is a different HiveFixture test object, with the key string representing the test name.

The JSON file path plus the test name are used as the unique test identifier.

Consumption

For each HiveFixture test object in the JSON fixture file, perform the following steps:

  1. Start a full node using:

    • network to configure the execution fork schedule according to the Fork type definition.
    • pre as the starting state allocation of the execution environment for the test and calculate the genesis state root.
    • genesisBlockHeader as the genesis block header.

  2. Verify the head of the chain is the genesis block, and the state root matches the one calculated on step 1, otherwise fail the test.

  3. For each FixtureEngineNewPayload in engineNewPayloads:

    1. Deliver the payload using the engine_newPayloadVX directive, using:
    2. If errorCode is present:
      • Verify the directive returns an error, and the error code matches the one in errorCode, otherwise fail the test.
      • Proceed to the next payload.
    3. If valid is false, verify that the directive returns status field of PayloadStatusV1 as INVALID, otherwise fail the test.
    4. If valid is true, verify that the directive returns status field of PayloadStatusV1 as VALID, otherwise fail the test.

Structures

HiveFixture

- network: Fork

Fork configuration for the test.

- genesisBlockHeader: FixtureHeader

Genesis block header.

- engineNewPayloads: List[FixtureEngineNewPayload]

List of engine_newPayloadVX directives to be processed after the genesis block.

- engineFcuVersion: Number

Version of the engine_forkchoiceUpdatedVX directive to use to set the head of the chain.

- pre: Alloc

Starting account allocation for the test. State root calculated from this allocation must match the one in the genesis block.

- post: Alloc

Account allocation for verification after all the blocks have been processed.

FixtureEngineNewPayload

- executionPayload: FixtureExecutionPayload

Execution payload.

- blob_versioned_hashes: Optional[List[Hash]] (fork: Cancun)

List of hashes of the versioned blobs that are part of the execution payload. They can mismatch the hashes of the versioned blobs in the execution payload, for negative-testing reasons.

- parentBeaconBlockRoot: Optional[Hash] (fork: Cancun)

Hash of the parent beacon block root.

- validationError: TransactionException|BlockException

Validation error expected when executing the payload.

When the payload is valid, this field is not present, and a VALID status is expected in the status field of PayloadStatusV1.

If this field is present, the status field of PayloadStatusV1 is expected to be INVALID.

- version: Number

Version of the engine_newPayloadVX directive to use to deliver the payload.

- errorCode: Optional[Number]

Error code to be returned by the engine_newPayloadVX directive.

FixtureExecutionPayload

- parentHash: Hash

Hash of the parent block.

- feeRecipient: Address

Address of the account that will receive the rewards for building the block.

- stateRoot: Hash

Root hash of the state trie.

- receiptsRoot: Hash

Root hash of the receipts trie.

- logsBloom: Bloom

Bloom filter composed of the logs of all the transactions in the block.

- blockNumber: HexNumber

Number of the block.

- gasLimit: HexNumber

Total gas limit of the block.

- gasUsed: HexNumber

Total gas used by all the transactions in the block.

- timestamp: HexNumber

Timestamp of the block.

- extraData: Bytes

Extra data of the block.

- prevRandao: Hash

PrevRandao of the block.

- blockHash: Hash

Hash of the block.

- transactions: List[Bytes]

List of transactions in the block, in serialized format.

- withdrawals: List[FixtureWithdrawal]

List of withdrawals in the block.

- baseFeePerGas: HexNumber (fork: London)

Base fee per gas of the block.

- blobGasUsed: HexNumber (fork: Cancun)

Total blob gas used by all the transactions in the block.

- excessBlobGas: HexNumber (fork: Cancun)

Excess blob gas of the block used to calculate the blob fee per gas for this block.

FixtureWithdrawal

- index: HexNumber

Index of the withdrawal

- validatorIndex: HexNumber

Withdrawing validator index

- address: Address

Address to withdraw to

- amount: HexNumber

Amount of the withdrawal