Skip to content

Commit 8530db4

Browse files
marioevzmarioevz
committed
docs: Add blockchain_test specification
1 parent 1d29783 commit 8530db4

File tree

7 files changed

+418
-11
lines changed

7 files changed

+418
-11
lines changed

‎docs/consuming_tests/blockchain_test.md

Lines changed: 161 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,165 @@ The Blockchain Test fixture format tests are included in subdirectory `blockchai
44

55
These are produced by the `StateTest` and `BlockchainTest` test specs.
66

7-
## Structure
7+
## Description
88

9-
A single JSON fixture file is composed of a JSON object where each key is a different test vector, with the key string representing the test name.
9+
The blockchain test fixture format is used to test block validation and the consensus rules of the Ethereum blockchain.
10+
11+
It does so by defining a series of blocks, a pre-execution state, a post-execution state, and verifying that, after all the blocks have been processed, appended if valid or rejected if invalid, the result is the expected post-execution state.
12+
13+
A single JSON fixture file is composed of a JSON object where each key-value pair is a different [`Fixture`](#fixture) test object, with the key string representing the test name.
14+
15+
The JSON file path plus the test name are used as the unique test identifier.
16+
17+
## Behavior
18+
19+
For each [`Fixture`](#fixture) test object in the JSON fixture file, perform the following steps:
20+
21+
1. Use [`network`](#-network) to configure the execution fork schedule according to the [`Fork`](./common_types.md#fork) type definition
22+
2. Use [`pre`](#-pre-alloc) as the starting state of the execution environment for the test and calculate the state root
23+
3. Decode [`genesisRLP`](#-genesisrlp-bytes) to obtain the genesis block header
24+
4. Compare the genesis block header with [`genesisBlockHeader`](#-genesisblockheader-fixtureheader), if any field does not match, fail the test
25+
5. Compare the state root calculated from [`pre`](#-pre-alloc) with the state root in the genesis block header, if they do not match, fail the test
26+
6. Set the genesis block as the current head of the chain
27+
7. If [`blocks`](#-blocks-listfixtureblock--null) is not `null`, and contains at least one block, perform the following steps for each [`FixtureBlock`](#fixtureblock):
28+
1. Attempt to decode block from field [`rlp`](#-rlp-bytes), and if the block cannot be decoded:
29+
1. If [`expectException`](#expectexception-str--null) is `null`, fail the test
30+
2. Proceed to the next block
31+
2. Attempt to apply the decoded block on top of the current head of the chain, and if the block cannot be applied:
32+
1. If [`expectException`](#expectexception-str--null) is `null`, fail the test
33+
2. Proceed to the next block
34+
3. If [`expectException`](#expectexception-str--null) is not `null`, fail the test
35+
4. Set the decoded block as the current head of the chain
36+
8. Compare the hash of the current head of the chain against [`lastblockhash`](#-lastblockhash-hash), if they do not match, fail the test
37+
9. Compare all accounts and the fields described in [`post`](#-post-alloc) against the current state, if any do not match, fail the test
38+
39+
## Structures
40+
41+
### `Fixture`
42+
43+
#### - `network`: [`Fork`](./common_types.md#fork)
44+
Fork configuration for the test.
45+
#### - `pre`: [`Alloc`](./common_types.md#alloc)
46+
Starting account allocation for the test. State root calculated from this allocation must match the one in the genesis block.
47+
#### - `genesisRLP`: [`Bytes`](./common_types.md#bytes)
48+
RLP serialized version of the genesis block.
49+
#### - `genesisBlockHeader`: [`FixtureHeader`](#fixtureheader)
50+
Genesis block header.
51+
#### - `blocks`: `List[`[`FixtureBlock`](#fixtureblock)`] | null`
52+
List of blocks to be processed after the genesis block.
53+
#### - `lastblockhash`: [`Hash`](./common_types.md#hash)
54+
Hash of the last valid block, or the genesis block hash if the list of blocks is `null`, empty, or contains a single invalid block.
55+
#### - `post`: [`Alloc`](./common_types.md#alloc)
56+
Account allocation for verification after all the blocks have been processed.
57+
#### - `sealEngine`: `str`
58+
TODO: Seal engine description.
59+
60+
### `FixtureHeader`
61+
62+
#### - `parentHash`: [`Hash`](./common_types.md#hash)
63+
Hash of the parent block.
64+
#### - `uncleHash`: [`Hash`](./common_types.md#hash)
65+
Hash of the uncle block list.
66+
#### - `coinbase`: [`Address`](./common_types.md#address)
67+
Address of the account that will receive the rewards for building the block.
68+
#### - `stateRoot`: [`Hash`](./common_types.md#hash)
69+
Root hash of the state trie.
70+
#### - `transactionsTrie`: [`Hash`](./common_types.md#hash)
71+
Root hash of the transactions trie.
72+
#### - `receiptTrie`: [`Hash`](./common_types.md#hash)
73+
Root hash of the receipts trie.
74+
#### - `bloom`: [`Bytes`](./common_types.md#bloom)
75+
Bloom filter composed of the logs of all the transactions in the block.
76+
#### - `difficulty`: [`ZeroPaddedHexNumber`](./common_types.md#zeropaddedhexnumber)
77+
Difficulty of the block.
78+
#### - `number`: [`ZeroPaddedHexNumber`](./common_types.md#zeropaddedhexnumber)
79+
Number of the block.
80+
#### - `gasLimit`: [`ZeroPaddedHexNumber`](./common_types.md#zeropaddedhexnumber)
81+
Total gas limit of the block.
82+
#### - `gasUsed`: [`ZeroPaddedHexNumber`](./common_types.md#zeropaddedhexnumber)
83+
Total gas used by all the transactions in the block.
84+
#### - `timestamp`: [`ZeroPaddedHexNumber`](./common_types.md#zeropaddedhexnumber)
85+
Timestamp of the block.
86+
#### - `extraData`: [`Bytes`](./common_types.md#bytes)
87+
Extra data of the block.
88+
#### - `mixHash`: [`Hash`](./common_types.md#hash)
89+
Mix hash or PrevRandao of the block.
90+
#### - `nonce`: [`HeaderNonce`](./common_types.md#headernonce)
91+
Nonce of the block.
92+
#### - `hash`: [`Hash`](./common_types.md#hash)
93+
Hash of the block.
94+
#### - `baseFeePerGas`: [`ZeroPaddedHexNumber`](./common_types.md#zeropaddedhexnumber) `(fork: London)`
95+
Base fee per gas of the block.
96+
#### - `withdrawalsRoot`: [`Hash`](./common_types.md#hash) `(fork: Shanghai)`
97+
Root hash of the withdrawals trie.
98+
#### - `blobGasUsed`: [`ZeroPaddedHexNumber`](./common_types.md#zeropaddedhexnumber) `(fork: Cancun)`
99+
Total blob gas used by all the transactions in the block.
100+
#### - `excessBlobGas`: [`ZeroPaddedHexNumber`](./common_types.md#zeropaddedhexnumber) `(fork: Cancun)`
101+
Excess blob gas of the block used to calculate the blob fee per gas for this block.
102+
#### - `parentBeaconBlockRoot`: [`Hash`](./common_types.md#hash) `(fork: Cancun)`
103+
Root hash of the parent beacon block.
104+
105+
### `FixtureBlock`
106+
107+
#### - `rlp`: [`Bytes`](./common_types.md#bytes)
108+
RLP serialized version of the block.
109+
#### - `blockHeader`: [`FixtureHeader`](#fixtureheader)` | null`
110+
Decoded block header fields included in the block RLP.
111+
#### - `blocknumber`: [`Number`](./common_types.md#number)
112+
Block number.
113+
#### - `transactions`: `List[`[`FixtureTransaction`](#fixturetransaction)`] | null`
114+
List of decoded transactions included in the block RLP.
115+
#### - `uncleHeaders`: `List[`[`FixtureHeader`](#fixturetransaction)`] | null`
116+
List of uncle headers included in the block RLP.
117+
#### - `withdrawals`: `List[`[`FixtureWithdrawal`](#fixturewithdrawal)`] | null`
118+
List of withdrawals included in the block RLP.
119+
#### - `expectException`: `str | null`
120+
Expected exception message if the block is invalid. Field will be missing if the block is valid.
121+
122+
### `FixtureTransaction`
123+
#### - `type`: [`ZeroPaddedHexNumber`](./common_types.md#zeropaddedhexnumber)
124+
Transaction type.
125+
#### - `chainId`: [`ZeroPaddedHexNumber`](./common_types.md#zeropaddedhexnumber)
126+
Chain ID of the transaction.
127+
#### - `nonce`: [`ZeroPaddedHexNumber`](./common_types.md#zeropaddedhexnumber)
128+
Nonce of the account that sends the transaction
129+
#### - `gasPrice`: [`ZeroPaddedHexNumber`](./common_types.md#zeropaddedhexnumber)
130+
Gas price for the transaction (Transaction types 0 & 1)
131+
#### - `maxPriorityFeePerGas`: [`HexNumber`](./common_types.md#hexnumber) `(fork: London)`
132+
Max priority fee per gas to pay (Transaction types 2 & 3)
133+
#### - `maxFeePerGas`: [`HexNumber`](./common_types.md#hexnumber) `(fork: London)`
134+
Max base fee per gas to pay (Transaction types 2 & 3)
135+
#### - `gasLimit`: [`ZeroPaddedHexNumber`](./common_types.md#zeropaddedhexnumber)
136+
Gas limit of the transaction
137+
#### - `to`: [`Address`](./common_types.md#address)` | null`
138+
Destination address of the transaction, or `null` to create a contract
139+
#### - `value`: [`ZeroPaddedHexNumber`](./common_types.md#zeropaddedhexnumber)
140+
Value of the transaction
141+
#### - `data`: [`Bytes`](./common_types.md#bytes)
142+
Data bytes of the transaction
143+
#### - `accessList`: `List[Mapping[`[`Address`](./common_types.md#address)`, List[`[`Hash`](./common_types.md#hash)`]]]` `(fork: Berlin)`
144+
Account access lists (Transaction types 1, 2 & 3)
145+
#### - `maxFeePerBlobGas`: [`ZeroPaddedHexNumber`](./common_types.md#zeropaddedhexnumber) `(fork: Cancun)`
146+
Max fee per blob gas to pay (Transaction type 3)
147+
#### - `blobVersionedHashes`: `List[`[`Hash`](./common_types.md#hash)`]` `(fork: Cancun)`
148+
Max fee per blob gas to pay (Transaction type 3)
149+
#### - `v`: [`ZeroPaddedHexNumber`](./common_types.md#zeropaddedhexnumber)
150+
V value of the transaction signature
151+
#### - `r`: [`ZeroPaddedHexNumber`](./common_types.md#zeropaddedhexnumber)
152+
R value of the transaction signature
153+
#### - `s`: [`ZeroPaddedHexNumber`](./common_types.md#zeropaddedhexnumber)
154+
S value of the transaction signature
155+
#### - `sender`: [`Address`](./common_types.md#address)
156+
Sender address of the transaction
157+
#### - `secretKey`: [`Hash`](./common_types.md#hash)
158+
Private key that must be used to sign the transaction
159+
160+
### `FixtureWithdrawal`
161+
#### - `index`: [`ZeroPaddedHexNumber`](./common_types.md#zeropaddedhexnumber)
162+
Index of the withdrawal
163+
#### - `validatorIndex`: [`ZeroPaddedHexNumber`](./common_types.md#zeropaddedhexnumber)
164+
Withdrawing validator index
165+
#### - `address`: [`Address`](./common_types.md#address)
166+
Address to withdraw to
167+
#### - `amount`: [`ZeroPaddedHexNumber`](./common_types.md#zeropaddedhexnumber)
168+
Amount of the withdrawal

0 commit comments

Comments
 (0)