Generated State Transition Tests

Location /GeneralStateTests

Test Structure

Contains transactions that are to be executed on a state pre given the environment env and must end up with post results post

Although its a simple transaction execution on stateA to stateB, due to the generation of this tests into blockchain format, the transaction execution is performed as if it was a single block with single transaction. This means that mining reward and touch rules after EIP-161 are applied. (mining reward is 0)

  • A test file must contain only one test testname
  • Test file name must be identical for the test name testname
{
  "testname" : {
    "_info" : { ... },
    "env" : { ... },
    "post" : { ... },
    "pre" : { ... },
    "transaction" : { ... }
  }
}

Info Section

"_info" : {
         "comment" : "A test for (add 1 1) opcode result",
         "filling-rpc-server" : "Geth-1.9.14-unstable-8cf83419-20200512",
         "filling-tool-version" : "retesteth-0.0.3+commit.672a84dd.Linux.g++",
         "lllcversion" : "Version: 0.5.14-develop.2019.11.27+commit.8f259595.Linux.g++",
         "source" : "src/GeneralStateTestsFiller/stExample/add11Filler.json",
         "sourceHash" : "e474fc13b1ea4c60efe2ba925dd48d6f9c1b12317dcd631f5eeeb3722a790a37",
         "labels" : {
             "0" : ":label normal",
             "1" : ":label normal",
             "2" : ":label normal"
         },
 },

Info section is generated with the test and contains information about test and it’s generators.

Fields

comment comment from the test source. (can be edited at source)
filling-rpc-server tool that has been used to generate the test (version)
filling-tool-version the test generator (retesteth) version
lllcversion lllc version that was used to compile LLL code in test fillers
source path to the source filler in the test repository
sourceHash hash of the json of source file (used to track that tests are updated)
labels labels for the different transaction data options

Env Section

"env" : {
    "currentCoinbase" : "0x2adc25665018aa1fe0e6bc666dac8fc2697ff9ba",
    "currentDifficulty" : "0x020000",
    "currentGasLimit" : "0xff112233445566",
    "currentNumber" : "0x01",
    "currentTimestamp" : "0x03e8",
    "previousHash" : "0x5e20a0453cecd065ea59c37ac63e079ee08998b6045136a8ce6635c7912ec0b6"
},

Env section describe information required to construct a genesis block, or VM env for transaction execution.

  • The fields are always 0x prefixed HEX.

Fields

currentCoinbase author/miner/coinbase address
currentDifficulty transaction executed in a block with this difficulty
currentGasLimit transaction executed in a block with this gas limit
currentNumber transaction executed in a block with this number
currentTimestamp transaction executed in a block with this timestamp
previousHash hash of the previous block (deprecated)

Post Section

"post" : {
    "London" : [
        {
            "indexes" : {
                "data" : 0,
                "gas" : 0,
                "value" : 0
            },
            "hash" : "0xe4c855f0d0e96d48d73778772ee570c45acb7c57f87092e08fed6b2205d390f4",
            "logs" : "0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347",
            "txbytes" : "0x02f88d0101808207d0871000000000000094cccccccccccccccccccccccccccccccccccccccc80a4693c61390000000000000000000000000000000000000000000000000000000000000000c001a05fecc3972a35c9e341b41b0c269d9a7325e13269fb01c2f64cbce1046b3441c8a07d4d0eda0e4ebd53c5d0b6fc35c600b317f8fa873b3963ab623ec9cec7d969bd"
            "expectException" : "TR_IntrinsicGas"
        }
    ]
},

Post section is a map <FORK> => [TransactionResults]

The test can have many fork results and each fork result can have many transaction results.

In generated test indexes are a single digit and could not be array. Thus define a single transaction from the test. See transaction section which define transactions by data, gasLimit, value arrays.

Fields

London fork name as defined by client config (test standard names)
indexes define an index of the transaction in txs vector that has been used for this result
data index in transaction data vector
gas index in transaction gas vector
value index in transaction value vector
hash hash of the post state after transaction execution
logs log hash of the transaction logs
txbytes the transaction bytes of the generated transaction
expectException for a transaction that is supposed to fail, the exception

Pre/preState Section

"pre" : {
    "0x095e7baea6a6c7c4c2dfeb977efac326af552d87" : {
        "balance" : "0x0de0b6b3a7640000",
        "code" : "0x600160010160005500",
        "nonce" : "0x00",
        "storage" : {
            "0x00" : "0x01"
        }
    },
    "0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b" : {
        "balance" : "0x0de0b6b3a7640000",
        "code" : "0x",
        "nonce" : "0x00",
        "storage" : {
        }
    }
},

Pre section describes a full state of accounts used in test.

Its a map of <Account> => <AccountFields>

AccountFields are always complete (balance, code, nonce, storage must present) in this section and can not have a missing field.

  • All values are 0x prefixed hex.
  • Empty code defined as 0x.
  • Zero storage record defined as 0x00.

Fields

address hash HASH20 is 20 bytes ethereum address 0x prefixed
balance VALUE account balance in evm state
code BYTES account code in evm state
nonce VALUE account nonce in evm state
storage map map of storage records VALUE => VALUE
TYPE Empty Length Format description
VALUE 0x00 Any* 0x prefixed hex up to 32 bytes long with no leading zeros.
BYTES 0x Any* 0x prefixed bytes of any length
HASH8 0x00…00 Fixed 8 0x prefixed bytes of length 8
HASH20 0x00…00 Fixed 20 0x prefixed bytes of length 20
HASH32 0x00…00 Fixed 32 0x prefixed bytes of length 32
HASH256 0x00…00 Fixed 256 0x prefixed bytes of length 256
  • Size can be limited by the meaning of field in tests. (like gasLimit ceil, tx signature v - value)

Transaction Section

"transaction" : {
    "data" : [
        "0x"
    ],
    "gasLimit" : [
        "0x061a80"
    ],
    "gasPrice" : "0x01",
    "nonce" : "0x00",
    "secretKey" : "0x45a915e4d060149eb4365960e6a7a45f334393093061116b197e3240065ff2d8",
    "to" : "0x095e7baea6a6c7c4c2dfeb977efac326af552d87",
    "value" : [
        "0x0186a0"
    ]
}

Transaction section defines a vector of transaction to be executed in GeneralStateTest From this section it is possible to construct many transaction using values from data,gasLimit,value array. Indexes in this array used in the post section to point out which transaction has been used to calculate the post state hash.

  • All fields are 0x prefixed HEX of even length (can be like 0x0122)
  • empty data is defined as 0x
  • transaction creation to defined as “”

Fields

data array(BYTES) Array of data/input of transaction. In Post section indexes::data index indicates index in this array.
gasLimit array(VALUE) Array of gasLimit of transaction. In Post section indexes::gas index indicates index in this array
gasPrice VALUE Transaction’s gas price
nonce VALUE Transaction’s nonce
secretKey FH32 SecretKey criptic value used to sign tx data by v,r,s
to FH20 Transaction’s to destination address. set to “” if creation.
value VALUE Array of value of transaction. In Post section indexes::value index indicates index in this array