Skip to content

Blockchain Tests

The Blockchain Test fixture format tests are included in the fixtures subdirectory blockchain_tests.

These are produced by the StateTest and BlockchainTest test specs.

Description

The blockchain test fixture format is used to test block validation and the consensus rules of the Ethereum blockchain.

It does so by defining a pre-execution state, a series of blocks, 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 Fixture 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 Fixture test object in the JSON fixture file, perform the following steps:

  1. Use network to configure the execution fork schedule according to the Fork type definition.
  2. Use pre as the starting state allocation of the execution environment for the test and calculate the genesis state root.
  3. Decode genesisRLP to obtain the genesis block header, if the block cannot be decoded, fail the test.
  4. Compare the genesis block header with genesisBlockHeader, if any field does not match, fail the test.
  5. Compare the state root calculated on step 2 with the state root in the genesis block header, if they do not match, fail the test.
  6. Set the genesis block as the current head of the chain.

  7. If blocks contains at least one block, perform the following steps for each FixtureBlock or InvalidFixtureBlock:

    1. Determine whether the current block is valid or invalid:

      1. If the expectException field is not present, it is valid, and object must be decoded as a FixtureBlock.
      2. If the expectException field is present, it is invalid, and object must be decoded as a InvalidFixtureBlock.

    2. Attempt to decode field rlp as the current block

      1. If the block cannot be decoded:
        • If an rlp decoding exception is not expected for the current block, fail the test.
        • If an rlp decoding error is expected, pass the test (Note: A block with an expected exception will be the last block in the fixture).
      2. If the block can be decoded, proceed to the next step.

    3. Attempt to apply the current decoded block on top of the current head of the chain

      1. If the block cannot be applied:
        • If an exception is expected on the current block and it matches the exception obtained upon execution, pass the test. (Note: A block with an expected exception will be the last block in the fixture)
        • If an exception is not expected on the current block, fail the test
      2. If the block can be applied:
        • If an exception is expected on the current block, fail the test
        • If an exception is not expected on the current block, set the decoded block as the current head of the chain and proceed to the next block until you reach the last block in the fixture.

  8. Compare the hash of the current head of the chain against lastblockhash, if they do not match, fail the test.

  9. Compare all accounts and the fields described in post against the current state, if any do not match, fail the test.

Structures

Fixture

- network: Fork

Fork configuration for the test.

- pre: Alloc

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

- genesisRLP: Bytes

RLP serialized version of the genesis block.

- genesisBlockHeader: FixtureHeader

Genesis block header.

- blocks: List[FixtureBlock|InvalidFixtureBlock]

List of blocks to be processed after the genesis block.

- lastblockhash: Hash

Hash of the last valid block, or the genesis block hash if the list of blocks is empty, or contains a single invalid block.

- post: Alloc

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

- sealEngine: str

Deprecated: Seal engine used to mine the blocks.

FixtureHeader

- parentHash: Hash

Hash of the parent block.

- uncleHash: Hash

Hash of the uncle block list.

- coinbase: Address

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

- stateRoot: Hash

Root hash of the state trie.

- transactionsTrie: Hash

Root hash of the transactions trie.

- receiptTrie: Hash

Root hash of the receipts trie.

- bloom: Bloom

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

- difficulty: ZeroPaddedHexNumber

Difficulty of the block.

- number: ZeroPaddedHexNumber

Number of the block.

- gasLimit: ZeroPaddedHexNumber

Total gas limit of the block.

- gasUsed: ZeroPaddedHexNumber

Total gas used by all the transactions in the block.

- timestamp: ZeroPaddedHexNumber

Timestamp of the block.

- extraData: Bytes

Extra data of the block.

- mixHash: Hash

Mix hash or PrevRandao of the block.

- nonce: HeaderNonce

Nonce of the block.

- hash: Hash

Hash of the block.

- baseFeePerGas: ZeroPaddedHexNumber (fork: London)

Base fee per gas of the block.

- withdrawalsRoot: Hash (fork: Shanghai)

Root hash of the withdrawals trie.

- blobGasUsed: ZeroPaddedHexNumber (fork: Cancun)

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

- excessBlobGas: ZeroPaddedHexNumber (fork: Cancun)

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

- parentBeaconBlockRoot: Hash (fork: Cancun)

Root hash of the parent beacon block.

FixtureBlock

- rlp: Bytes

RLP serialized version of the block. Field is only optional when embedded in a InvalidFixtureBlock as the rlp_decoded field.

- blockHeader: FixtureHeader

Decoded block header fields included in the block RLP.

- blocknumber: Number

Block number.

- transactions: List[FixtureTransaction]

List of decoded transactions included in the block RLP.

- uncleHeaders: List[FixtureHeader]

List of uncle headers included in the block RLP. An empty list post merge.

- withdrawals: Optional[List[FixtureWithdrawal]] (fork: Shanghai)

Optional list of withdrawals included in the block RLP.

InvalidFixtureBlock

- expectException: TransactionException|BlockException

Expected exception that invalidates the block.

- rlp: Bytes

RLP serialized version of the block.

- rlp_decoded: Optional[FixtureBlock]

Decoded block attributes included in the block RLP.

FixtureTransaction

- type: ZeroPaddedHexNumber

Transaction type.

- chainId: ZeroPaddedHexNumber

Chain ID of the transaction.

- nonce: ZeroPaddedHexNumber

Nonce of the account that sends the transaction

- gasPrice: ZeroPaddedHexNumber

Gas price for the transaction (Transaction types 0 & 1)

- maxPriorityFeePerGas: HexNumber (fork: London)

Max priority fee per gas to pay (Transaction types 2 & 3)

- maxFeePerGas: HexNumber (fork: London)

Max base fee per gas to pay (Transaction types 2 & 3)

- gasLimit: ZeroPaddedHexNumber

Gas limit of the transaction

- to: Address| null

Destination address of the transaction, or null to create a contract

- value: ZeroPaddedHexNumber

Value of the transaction

- data: Bytes

Data bytes of the transaction

- accessList: List[Mapping[Address,List[Hash]]] (fork: Berlin)

Account access lists (Transaction types 1, 2 & 3)

- maxFeePerBlobGas: ZeroPaddedHexNumber (fork: Cancun)

Max fee per blob gas to pay (Transaction type 3)

- blobVersionedHashes: List[Hash] (fork: Cancun)

Max fee per blob gas to pay (Transaction type 3)

- v: ZeroPaddedHexNumber

V value of the transaction signature

- r: ZeroPaddedHexNumber

R value of the transaction signature

- s: ZeroPaddedHexNumber

S value of the transaction signature

- sender: Address

Sender address of the transaction

- secretKey: Hash

Private key that must be used to sign the transaction

FixtureWithdrawal

- index: ZeroPaddedHexNumber

Index of the withdrawal

- validatorIndex: ZeroPaddedHexNumber

Withdrawing validator index

- address: Address

Address to withdraw to

- amount: ZeroPaddedHexNumber

Amount of the withdrawal