-
Notifications
You must be signed in to change notification settings - Fork 304
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Added doc rst files from the Homestead docs
- Loading branch information
Showing
9 changed files
with
598 additions
and
8 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,139 @@ | ||
.. _blockchain_tests: | ||
|
||
################################################################################ | ||
Blockchain Tests | ||
################################################################################ | ||
|
||
Found in ``/BlockTests``, the blockchain tests aim is to test the basic verification of a blockchain. | ||
|
||
``/BlockTests`` - general blockchain tests. All blocks are built on network: **Frontier** | ||
``/BlockTests/Homestead`` - homestead blockchain tests. All blocks are built on network: **Homestead** | ||
``/BlockTests/TestNetwork`` - transition blockchain tests. All blocks before 5th are built on network: **Frontier**, then each block should correspond to Homestead rules. | ||
|
||
It is based around the notion of executing a list of single blocks, described by the ``blocks`` portion of the test. The first block is the modified genesis block as described by the ``genesisBlockHeader`` portion of the test. A set of pre-existing accounts are detailed in the ``pre`` portion and form the world state of the genesis block. | ||
|
||
It is generally expected that the test implementer will read ``genesisBlockHeader`` and ``pre`` and build the corresponding blockchain in the client. Then the new blocks, described by its RLP found in the ``rlp`` object of the ``blocks`` (RLP of a complete block, not the block header only), is read. If the client concludes that the block is valid, it should execute the block and verify the parameters given in ``blockHeader`` (block header of the new block), ``transactions`` (transaction list) and ``uncleHeaders`` (list of uncle headers). If the client concludes that the block is invalid, it should verify that no ``blockHeader``, ``transactions`` or ``uncleHeaders`` object is present in the test. The client is expected to iterate through the list of blocks and ignore invalid blocks. | ||
|
||
Basic structure | ||
-------------------------------------------------------------------------------- | ||
|
||
:: | ||
|
||
{ | ||
"ValidBlocks": { | ||
"genesisBlockHeader": { ... }, | ||
"pre": { ... }, | ||
"blocks" : [ | ||
{ | ||
"chainname" : "A", | ||
"blocknumber" : "1", | ||
"rlp": { ... }, | ||
"blockHeader": { ... }, | ||
"transactions": { ... }, | ||
"uncleHeaders": { ... } | ||
}, | ||
{ | ||
"chainname" : "A", | ||
"blocknumber" : "2", | ||
"rlp": { ... }, | ||
"blockHeader": { ... }, | ||
"transactions": { ... }, | ||
"uncleHeaders": { ... } | ||
} | ||
] | ||
}, | ||
"SomeInvalidBlocks": { | ||
"genesisBlockHeader": { ... }, | ||
"pre": { ... }, | ||
"blocks" : [ | ||
{ | ||
"chainname" : "B", | ||
"blocknumber" : "3", | ||
"chainnetwork" : "Frontier", | ||
"rlp": { ... }, | ||
}, | ||
{ | ||
"blocknumber" : "1", | ||
"rlp": { ... }, | ||
"blockHeader": { ... }, | ||
"transactions": { ... }, | ||
"uncleHeaders": { ... } | ||
}, | ||
{ | ||
"blocknumber" : "1", | ||
"chainnetwork" : "Homestead", | ||
"rlp": { ... }, | ||
}, | ||
{ | ||
"blocknumber" : "2", | ||
"rlp": { ... }, | ||
"blockHeader": { ... }, | ||
"transactions": { ... }, | ||
"uncleHeaders": { ... } | ||
} | ||
] | ||
}, | ||
... | ||
} | ||
|
||
|
||
Sections | ||
-------------------------------------------------------------------------------- | ||
|
||
* The ``genesisBlockHeader`` section | ||
|
||
``coinbase``: | ||
The 160-bit address to which all fees collected from the successful mining of this block be | ||
transferred, as returned by the **COINBASE** instruction. | ||
``difficulty``: | ||
A scalar value corresponding to the difficulty level of this block. This can be alculated | ||
from the previous block’s difficulty level and the timestamp, as returned by the **DIFFICULTY** instruction. | ||
``gasLimit``: | ||
A scalar value equal to the current limit of gas expenditure per block, as returned by the **GASLIMIT** instruction. | ||
``number``: | ||
A scalar value equal to the number of ancestor blocks. The genesis block has a number of zero. | ||
``timestamp``: | ||
A scalar value equal to the reasonable output of Unix’s time() at this block’s inception, as returned by the **TIMESTAMP** instruction. | ||
``parentHash``: | ||
The Keccak 256-bit hash of the parent block’s header, in its entirety | ||
``bloom``: | ||
The Bloom filter composed from indexable information (logger address and log topics) | ||
contained in each log entry from the receipt of each transaction in the transactions list. | ||
``extraData``: | ||
An arbitrary byte array containing data relevant to this block. This must be 1024 bytes or fewer. | ||
``gasUsed``: | ||
A scalar value equal to the total gas used in transactions in this block. | ||
``nonce``: | ||
A 256-bit hash which proves that a sufficient amount of computation has been carried out on this block. | ||
``receiptTrie``: | ||
The Keccak 256-bit hash of the root node of the trie structure populated with the receipts of each transaction in the transactions list portion of the block. | ||
``stateRoot``: | ||
The Keccak 256-bit hash of the root node of the state trie, after all transactions are executed and finalisations applied. | ||
``transactionsTrie``: | ||
The Keccak 256-bit hash of the root node of the trie structure populated with each transaction in the transactions list portion of the block. | ||
``uncleHash``: | ||
The Keccak 256-bit hash of the uncles list portion of this block | ||
|
||
* ``pre`` section: as described in State Tests. | ||
|
||
* ``postState`` section: as described in State Tests (section - post). | ||
|
||
* ``blocks`` section is a list of block objects, which have the following format: | ||
|
||
* ``rlp`` section contains the complete rlp of the new block as described in the yellow paper in section 4.3.3. | ||
|
||
* ``blockHeader`` section describes the block header of the new block in the same format as described in `genesisBlockHeader`. | ||
|
||
* ``transactions`` section is a list of transactions which have the same format as in Transaction Tests. | ||
|
||
* ``uncleHeaders`` section is a list of block headers which have the same format as descibed in `genesisBlockHeader`. | ||
|
||
Optional BlockHeader Sections (Information fields) | ||
-------------------------------------------------------------------------------- | ||
|
||
``"blocknumber" = "int"`` is section which defines what is the order of this block. | ||
It is used to define a situation when you have 3 blocks already imported but then it comes new version of the block 2 and 3 and thus you might have new best blockchain with blocks 1 2' 3' instead previous. If `blocknumber` is undefined then it is assumed that blocks are imported one by one. When running test, this field could be used for information purpose only. | ||
|
||
``"chainname" = "string"`` This is used for defining forks in the same test. You could mine blocks to chain "A": 1, 2, 3 then to chain "B": 1, 2, 3, 4 (chainB becomes primary). Then again to chain "A": 4, 5, 6 (chainA becomes primary) and so on. chainname could also be defined in uncle header section. If defined in uncle header it tells on which chain's block uncle header would be populated from. When running test, this field could be used for information purpose only. | ||
|
||
``"chainnetwork" = "string"`` Defines on which network rules this block was mined. (see the difference https://github.com/ethereum/EIPs/blob/master/EIPS/eip-2.mediawiki). When running test, this field could be used for information purpose only. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,50 @@ | ||
.. _difficulty_tests: | ||
|
||
################################################################################ | ||
Difficulty Tests | ||
################################################################################ | ||
|
||
Found in ``\Basic Tests\difficulty*.json`` files. This tests are designed to just check the difficulty formula of a block. | ||
|
||
difficulty = DIFFICULTY(currentBlockNumber, currentTimestamp, parentTimestamp, parentDifficulty) | ||
|
||
described at [EIP2](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-2.mediawiki) point 4 with homestead changes. | ||
|
||
So basically this .json tests are just to check how this function is calculated on different function parameters (parentDifficulty, currentNumber) in its extremum points. | ||
|
||
There are several test files: | ||
|
||
``difficulty.json`` | ||
Normal Frontier/Homestead chain difficulty tests defined manually | ||
``difficultyFrontier.json`` | ||
Same as above, but auto-generated tests | ||
``difficultyMorden.json`` | ||
Tests for testnetwork difficulty. (it has different homestead transition block) | ||
``difficultyOlimpic.json`` | ||
Olympic network. (no homestead) | ||
``difficultyHomestead.json`` | ||
Tests for homestead difficulty (regardless of the block number) | ||
``difficultyCustomHomestead.json`` | ||
Tests for homestead difficulty (regardless of the block number) | ||
|
||
Basic structure | ||
-------------------------------------------------------------------------------- | ||
:: | ||
|
||
{ | ||
"difficultyTest" : { | ||
"parentTimestamp" : "42", | ||
"parentDifficulty" : "1000000", | ||
"currentTimestamp" : "43", | ||
"currentBlockNumber" : "42", | ||
"currentDifficulty" : "1000488" | ||
} | ||
} | ||
|
||
Sections | ||
-------------------------------------------------------------------------------- | ||
* ``parentTimestamp`` - indicates the timestamp of a previous block | ||
* ``parentDifficulty`` - indicates the difficulty of a previous block | ||
* ``currentTimestamp`` - indicates the timestamp of a current block | ||
* ``currentBlockNumber`` - indicates the number of a current block (previous block number = currentBlockNumber - 1) | ||
* ``currentDifficulty`` - indicates the difficulty of a current block |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,50 @@ | ||
.. _rlp_tests: | ||
|
||
################################################################################ | ||
RLP Tests | ||
################################################################################ | ||
|
||
Describes an **RLP** (https://github.com/ethereum/wiki/wiki/RLP) encoding using the .json file. | ||
The client should read the rlp byte stream, **decode** and check whether the contents match its json representation. Then it should try do it reverse - **encode** json rlp representation into rlp byte stream and check whether it matches the given rlp byte stream. | ||
|
||
If it is an invalid RLP byte stream in the test, then 'in' field would contain string 'INVALID' | ||
|
||
Some RLP byte streams are expected to be generated by fuzz test suite. For those examples 'in' field would contain string 'VALID' as it means that rlp should be easily decoded. | ||
|
||
RLP tests are located in in ``/RLPTests`` | ||
|
||
**Note** that RLP tests are testing a single RLP object encoding. Not a stream of RLP objects in one array. | ||
|
||
Basic structure | ||
-------------------------------------------------------------------------------- | ||
|
||
:: | ||
|
||
{ | ||
"rlpTest": { | ||
"in": "dog", | ||
"out": "83646f67" | ||
}, | ||
|
||
"multilist": { | ||
"in": [ "zw", [ 4 ], 1 ], | ||
"out": "c6827a77c10401" | ||
}, | ||
|
||
"validRLP": { | ||
"in": "VALID", | ||
"out": "c7c0c1c0c3c0c1c0" | ||
}, | ||
|
||
"invalidRLP": { | ||
"in": "INVALID", | ||
"out": "bf0f000000000000021111" | ||
}, | ||
... | ||
} | ||
|
||
Sections | ||
-------------------------------------------------------------------------------- | ||
|
||
* ``in`` - json object (array, int, string) representation of the rlp byte stream (\*except values 'VALID' and 'INVALID') | ||
* ``out`` - string of rlp bytes stream |
Oops, something went wrong.