Skip to content

State Tests

The State Test fixture format tests are included in the fixtures subdirectory state_tests.

These are produced by the StateTest and StateTestOnly test specs.

Description

The state test fixture format is used to test the state transition function of the Ethereum Virtual Machine (EVM).

It does so by defining a transaction, a pre-execution state, and a post-execution state, and verifying that the transaction execution results in 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.

As opposed to other fixture formats, the state test fixture format could contain multiple test vectors per test object, each represented by an element in the mapping of lists of the post field.

However tests generated by the execution-spec-tests repository do not use this feature, as every single test object contains only a single test vector.

Consumption

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

  1. Use pre as the starting state allocation of the execution environment for the test.
  2. Use env to configure the current execution environment.

  3. For each Fork key of post in the test, and for each of the elements of the list of FixtureForkPost values:

    1. Configure the execution fork schedule according to the current Fork key.
    2. Using the indexes values, and the transaction object, decode the transaction to be executed.
    3. If the serialized version of the decoded transaction does not match txbytes, fail the test.

    4. Attempt to apply the transaction using the current execution environment:

      1. If the transaction could not be applied to the current execution context:
      2. If the transaction could be applied to the current execution context:

    5. Compare the resulting post-state root with the expected post-state root contained in the hash field of the current FixtureForkPost, and fail the test if they do not match.

    6. Compare the resulting logs hash with the expected logs contained in the logs field of the current FixtureForkPost, and fail the test if they do not match.

Structures

Fixture

- env: FixtureEnvironment

Execution environment description for the test.

- pre: Alloc

Starting account allocation for the test.

- transaction: FixtureTransaction

Transaction to be executed.

- post: Mapping(Fork,List[ FixtureForkPost ])

Mapping of lists of post for verification per fork, where each element represents a single possible outcome of the transaction execution after being applied to the pre.

FixtureEnvironment

- currentCoinbase: Address

The address of the account that will receive the rewards for building the block.

- currentGasLimit: ZeroPaddedHexNumber

Total gas limit of the block where the transaction is executed.

- currentNumber: ZeroPaddedHexNumber

Number of the block where the transaction is executed.

- currentDifficulty: ZeroPaddedHexNumber

Difficulty of the block where the transaction is executed.

- currentTimestamp: ZeroPaddedHexNumber

Timestamp of the block where the transaction is executed.

- currentBaseFee: ZeroPaddedHexNumber (fork: London)

Base fee of the block where the transaction is executed.

- currentRandom: Hash (fork: Paris)

Randao value of the block where the transaction is executed.

- currentExcessBlobGas: ZeroPaddedHexNumber (fork: Cancun)

Excess blob gas of the block where the transaction is executed.

FixtureTransaction

- nonce: ZeroPaddedHexNumber

Nonce of the account that sends the transaction

- gasPrice: ZeroPaddedHexNumber

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

- maxPriorityFeePerGas: HexNumber

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

- maxFeePerGas: HexNumber

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

- gasLimit: List[ZeroPaddedHexNumber]

List of gas limits used on each indexed test combination

- to: Address|EmptyAddress

Destination address of the transaction, or an empty string to create a contract

- value: List[ZeroPaddedHexNumber]

List of values used on each indexed test combination

- data: List[Bytes]

List of data bytes used on each indexed test combination

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

List of account access lists used on each indexed test combination (Transaction types 1, 2 & 3)

- maxFeePerBlobGas: HexNumber (fork: Cancun)

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

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

List of blob versioned hashes the transaction includes (Transaction type 3)

- sender: Address

Sender address of the transaction

- secretKey: Hash

Private key that must be used to sign the transaction

FixtureForkPost

- indexes: FixtureForkPostIndexes

Transaction field indexes that must be used to obtain the transaction to be executed

- txbytes: Bytes

Serialized bytes version of the FixtureTransaction that was executed to produce this post-state

- hash: Hash

Expected state root value that results of applying the transaction to the pre-state

- logs: Hash

Hash of the RLP representation of the state logs result of applying the transaction to the pre-state (TODO: double-check this.)

- expectException: TransactionException

Exception that is expected to be thrown by the transaction execution (Field is missing if the transaction is expected to succeed)

FixtureForkPostIndexes

- data: int

Index of the data field in the transaction

- gas: int

Index of the gas limit field in the transaction

- value: int

Index of the value field in the transaction