From 8c57822dfc87113759af346267affdf6941d531a Mon Sep 17 00:00:00 2001 From: holgerd77 Date: Wed, 30 Aug 2017 18:09:50 +0200 Subject: Fix headings, line breaks --- docs/blockchain_tests/index.rst | 7 +++--- docs/contribute.rst | 1 - docs/index.rst | 4 ++-- docs/rlp_tests/index.rst | 20 ++++++++++------- docs/state_tests/index.rst | 5 ++--- docs/transaction_tests/index.rst | 7 +++--- docs/using-testeth.rst | 6 ++--- docs/vm_tests/index.rst | 48 +++++++++++++++++++++++++++------------- 8 files changed, 58 insertions(+), 40 deletions(-) diff --git a/docs/blockchain_tests/index.rst b/docs/blockchain_tests/index.rst index 27b8cd76d..6b4ed420f 100644 --- a/docs/blockchain_tests/index.rst +++ b/docs/blockchain_tests/index.rst @@ -1,8 +1,7 @@ .. _blockchain_tests: -################################################################################ Blockchain Tests -################################################################################ +================ Found in `/BlockChainTests `_, the blockchain tests aim is to test the basic verification of a blockchain. @@ -80,7 +79,7 @@ Basic structure Sections --------------------------------------------------------------------------------- +-------- * The ``genesisBlockHeader`` section @@ -138,7 +137,7 @@ Sections * ``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. diff --git a/docs/contribute.rst b/docs/contribute.rst index 02055b463..eab88d00f 100644 --- a/docs/contribute.rst +++ b/docs/contribute.rst @@ -1,6 +1,5 @@ .. _contribute: -================== Contribute to Docs ================== diff --git a/docs/index.rst b/docs/index.rst index cfd45916f..5dd1f5518 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,8 +1,8 @@ .. _ethereum_tests: -################################################################################ +############## Ethereum Tests -################################################################################ +############## | Common tests for all clients to test against. The `git repo `_ updated regulary with new tests. | This section describes basic test concepts and templates which are created by cpp-client. | diff --git a/docs/rlp_tests/index.rst b/docs/rlp_tests/index.rst index 00ba3dc7b..154bd5890 100644 --- a/docs/rlp_tests/index.rst +++ b/docs/rlp_tests/index.rst @@ -1,22 +1,26 @@ .. _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. +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. +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. +**Note** that RLP tests are testing a single RLP object encoding. Not a stream of +RLP objects in one array. Basic structure --------------------------------------------------------------------------------- +--------------- :: @@ -44,7 +48,7 @@ Basic structure } Sections --------------------------------------------------------------------------------- +-------- * ``in`` - json object (array, int, string) representation of the rlp byte stream (\*except values 'VALID' and 'INVALID') * ``out`` - string of rlp bytes stream diff --git a/docs/state_tests/index.rst b/docs/state_tests/index.rst index 978d2542a..a57f3b4c2 100644 --- a/docs/state_tests/index.rst +++ b/docs/state_tests/index.rst @@ -1,8 +1,7 @@ .. _state_tests: -################################################################################ General State Tests -################################################################################ +=================== Found in `/GeneralStateTests `_, the state tests aim is to test the basic workings of the state in isolation. @@ -28,7 +27,7 @@ and ``pre`` then check their results against ``logs``, ``out``, and ``post``. integrated in these docs in the future. Basic structure --------------------------------------------------------------------------------- +--------------- :: diff --git a/docs/transaction_tests/index.rst b/docs/transaction_tests/index.rst index ffe65247d..eb06504f6 100644 --- a/docs/transaction_tests/index.rst +++ b/docs/transaction_tests/index.rst @@ -1,15 +1,14 @@ .. _transaction_tests: -################################################################################ Transaction Tests -################################################################################ +================= Describes a complete transaction and its `RLP `_ representation using the .json file. The client should read the rlp and check whether the transaction is valid, has the correct sender and corresponds to the transaction parameters. If it is an invalid transaction, the transaction and the sender object will be missing. Basic structure --------------------------------------------------------------------------------- +--------------- :: { @@ -37,7 +36,7 @@ Basic structure } Sections --------------------------------------------------------------------------------- +-------- * ``rlp`` - RLP encoded data of this transaction * ``transaction`` - transaction described by fields diff --git a/docs/using-testeth.rst b/docs/using-testeth.rst index 49ef3945a..390225d7f 100644 --- a/docs/using-testeth.rst +++ b/docs/using-testeth.rst @@ -1,7 +1,7 @@ -***************************************************** Using Testeth -***************************************************** +============= + Ethereum cpp-client testeth tool for creation and execution of ethereum tests. To run tests you should open folder (see also `Installing and building `_ @@ -51,7 +51,7 @@ That's it for test execution. To read more about command line options you may ru Now let's see what test cases are available. Test Cases --------------------------------------------------------------------------------- +---------- Almost each test case has its filler file available at ``/webthree-umbrella/libethereum/test`` diff --git a/docs/vm_tests/index.rst b/docs/vm_tests/index.rst index 732c4d08b..16716d53b 100644 --- a/docs/vm_tests/index.rst +++ b/docs/vm_tests/index.rst @@ -1,23 +1,41 @@ .. _vm_tests: -################################################################################ VM Tests -################################################################################ - -Found in ``/VMTest``, the VM tests aim is to test the basic workings of the VM in isolation. This is specifically not meant to cover transaction, creation or call processing, or management of the state trie. Indeed at least one implementation tests the VM without calling into any Trie code at all. - -It is based around the notion of executing a single piece of code as part of a transaction, described by the ``exec`` portion of the test. The overarching environment in which it is executed is described by the ``env`` portion of the test and includes attributes of the current and previous blocks. A set of pre-existing accounts are detailed in the ``pre`` portion and form the world state prior to execution. Similarly, a set of accounts are detailed in the ``post`` portion to specify the end world state. - -The gas remaining (``gas``), the log entries (``logs``) as well as any output returned from the code (``output``) is also detailed. - -Because the data of the blockchain is not given, the opcode BLOCKHASH could not return the hashes of the corresponding blocks. Therefore we define the hash of block number n to be SHA3-256("n"). - -Since these tests are meant only as a basic test of VM operation, the ``CALL`` and ``CREATE`` instructions are not actually executed. To provide the possibility of testing to guarantee they were actually run at all, a separate portion ``callcreates`` details each ``CALL`` or ``CREATE`` operation in the order they would have been executed. Furthermore, gas required is simply that of the VM execution: the gas cost for transaction processing is excluded. - -It is generally expected that the test implementer will read ``env``, ``exec`` and ``pre`` then check their results against ``gas``, ``logs``, ``out``, ``post`` and ``callcreates``. If an exception is expected, then latter sections are absent in the test. Since the reverting of the state is not part of the VM tests. +======== + +Found in ``/VMTest``, the VM tests aim is to test the basic workings of the VM in +isolation. This is specifically not meant to cover transaction, creation or call +processing, or management of the state trie. Indeed at least one implementation +tests the VM without calling into any Trie code at all. + +It is based around the notion of executing a single piece of code as part of a transaction, +described by the ``exec`` portion of the test. The overarching environment in which it is +executed is described by the ``env`` portion of the test and includes attributes +of the current and previous blocks. A set of pre-existing accounts are detailed +in the ``pre`` portion and form the world state prior to execution. Similarly, a set +of accounts are detailed in the ``post`` portion to specify the end world state. + +The gas remaining (``gas``), the log entries (``logs``) as well as any output returned +from the code (``output``) is also detailed. + +Because the data of the blockchain is not given, the opcode BLOCKHASH could not +return the hashes of the corresponding blocks. Therefore we define the hash of +block number n to be SHA3-256("n"). + +Since these tests are meant only as a basic test of VM operation, the ``CALL`` and +``CREATE`` instructions are not actually executed. To provide the possibility of +testing to guarantee they were actually run at all, a separate portion ``callcreates`` +details each ``CALL`` or ``CREATE`` operation in the order they would have been executed. +Furthermore, gas required is simply that of the VM execution: the gas cost for +transaction processing is excluded. + +It is generally expected that the test implementer will read ``env``, ``exec`` and ``pre`` +then check their results against ``gas``, ``logs``, ``out``, ``post`` and ``callcreates``. +If an exception is expected, then latter sections are absent in the test. Since the +reverting of the state is not part of the VM tests. Basic structure --------------------------------------------------------------------------------- +--------------- :: -- cgit v1.2.3 From d373f55f25bb3fb5a7c8e786b05e9d7fdb72bd1c Mon Sep 17 00:00:00 2001 From: holgerd77 Date: Wed, 30 Aug 2017 19:03:28 +0200 Subject: Structural improvements to the blockchain tests section, new info box with location and HF support info, notice on GeneralStateTests subfolder --- docs/blockchain_tests/index.rst | 62 ++++++++++++++++++++++++++++------------- 1 file changed, 43 insertions(+), 19 deletions(-) diff --git a/docs/blockchain_tests/index.rst b/docs/blockchain_tests/index.rst index 6b4ed420f..1cda66fc6 100644 --- a/docs/blockchain_tests/index.rst +++ b/docs/blockchain_tests/index.rst @@ -3,14 +3,27 @@ Blockchain Tests ================ -Found in `/BlockChainTests `_, -the blockchain tests aim is to test the basic verification of a blockchain. +The blockchain tests aim is to test the basic verification of a blockchain. + +=================== ============================================================== +Location `/BlockchainTests `_ +Supported Hardforks ``Byzantium`` | ``Constantinople`` | ``EIP150`` | ``EIP158`` | ``Frontier`` | ``Homestead`` +=================== ============================================================== A blockchain test 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. +world state of the genesis block. + +Of special notice is the +`/BlockchainTests/GeneralStateTests `_ +folder within the blockchain tests folder structure, which contains a copy of the +:ref:`state_tests` but executes them within the logic of the blockchain tests. + + +Test Implementation +------------------- 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, @@ -22,8 +35,8 @@ it should execute the block and verify the parameters given in ``blockHeader`` 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 --------------------------------------------------------------------------------- +Test Structure +-------------- :: @@ -78,10 +91,26 @@ Basic structure } -Sections --------- +The Blocks Section +^^^^^^^^^^^^^^^^^^ + +The ``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. -* The ``genesisBlockHeader`` section +* ``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 :ref:`transaction_tests`. + +* ``uncleHeaders`` section is a list of block headers which have the same format as + descibed in `genesisBlockHeader`. + + +The genesisBlockHeader Section +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ``coinbase``: The 160-bit address to which all fees collected from the successful mining of this block be @@ -122,22 +151,17 @@ Sections ``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. +Pre and postState Sections +^^^^^^^^^^^^^^^^^^^^^^^^^^ -* ``blockHeader`` section describes the block header of the new block in the same format as described in `genesisBlockHeader`. +* ``pre`` section: as described in :ref:`state_tests`. -* ``transactions`` section is a list of transactions which have the same format as in Transaction Tests. +* ``postState`` section: as described in :ref:`state_tests` (section - post). -* ``uncleHeaders`` section is a list of block headers which have the same format as descibed in `genesisBlockHeader`. -Optional BlockHeader Sections (Information fields) --------------------------------------------------- +Optional BlockHeader Information +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ``"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. -- cgit v1.2.3 From ce9d58f24f5d688c1d62ec79b903b3ba1a80e9f6 Mon Sep 17 00:00:00 2001 From: holgerd77 Date: Wed, 30 Aug 2017 19:33:01 +0200 Subject: Added updated version of the state test docs from EIP 176 (rough version as a basis to be fine-tuned) --- docs/blockchain_tests/index.rst | 1 + docs/state_tests/index.rst | 146 ++++++++++++++++++++++++---------------- 2 files changed, 88 insertions(+), 59 deletions(-) diff --git a/docs/blockchain_tests/index.rst b/docs/blockchain_tests/index.rst index 1cda66fc6..c9b6dd359 100644 --- a/docs/blockchain_tests/index.rst +++ b/docs/blockchain_tests/index.rst @@ -8,6 +8,7 @@ The blockchain tests aim is to test the basic verification of a blockchain. =================== ============================================================== Location `/BlockchainTests `_ Supported Hardforks ``Byzantium`` | ``Constantinople`` | ``EIP150`` | ``EIP158`` | ``Frontier`` | ``Homestead`` +Status Actively supported =================== ============================================================== A blockchain test is based around the notion of executing a list of single blocks, diff --git a/docs/state_tests/index.rst b/docs/state_tests/index.rst index a57f3b4c2..facb66187 100644 --- a/docs/state_tests/index.rst +++ b/docs/state_tests/index.rst @@ -3,8 +3,13 @@ General State Tests =================== -Found in `/GeneralStateTests `_, -the state tests aim is to test the basic workings of the state in isolation. +The state tests aim is to test the basic workings of the state in isolation. + +=================== ============================================================== +Location `/GeneralStateTests `_ +Supported Hardforks ``Byzantium`` | ``Constantinople`` | ``EIP150`` | ``EIP158`` | ``Frontier`` | ``Homestead`` +Status Actively supported +=================== ============================================================== A state test is based around the notion of executing a single transaction, described by the ``transaction`` portion of the test. The overarching environment @@ -18,44 +23,79 @@ block number ``n`` to be ``SHA256("n")``. The log entries (``logs``) as well as any output returned from the code (``output``) is also detailed. +Test Implementation +------------------- + It is generally expected that the test implementer will read ``env``, ``transaction`` and ``pre`` then check their results against ``logs``, ``out``, and ``post``. .. note:: - The structure description of state tests is outdated. A more up-to-date description - can be found `here `_ and should be - integrated in these docs in the future. + The structure of state tests was reworked lately, see the associated discussion + `here `_. -Basic structure ---------------- +Test Structure +-------------- :: - { - "test name 1": { - "env": { ... }, - "logs": { ... }, - "out": { ... }, - "post": { ... }, - "pre": { ... }, - "transaction": { ... }, - }, - "test name 2": { - "env": { ... }, - "logs": { ... }, - "out": { ... }, - "post": { ... }, - "pre": { ... }, - "transaction": { ... }, - }, - ... - } - - -Sections --------------------------------------------------------------------------------- - -* **The** ``env`` **section:** + { + "testname" : { + "env" : { + "currentCoinbase" : "address", + "currentDifficulty" : "0x020000", //minimum difficulty for mining on blockchain + "currentGasLimit" : "u64", //not larger then maxGasLimit = 0x7fffffffffffffff + "currentNumber" : "0x01", //Irrelevant to hardfork parameters! + "currentTimestamp" : "1000", //for blockchain version + "previousHash" : "h256" + }, + "post" : { + "EIP150" : [ + { + "hash" : "3e6dacc1575c6a8c76422255eca03529bbf4c0dda75dfc110b22d6dc4152396f", + "indexes" : { "data" : 0, "gas" : 0, "value" : 0 } + }, + { + "hash" : "99a450d8ce5b987a71346d8a0a1203711f770745c7ef326912e46761f14cd764", + "indexes" : { "data" : 0, "gas" : 0, "value" : 1 } + }, + ... + ], + "EIP158" : [ + { + "hash" : "3e6dacc1575c6a8c76422255eca03529bbf4c0dda75dfc110b22d6dc4152396f", + "indexes" : { "data" : 0, "gas" : 0, "value" : 0 } + }, + { + "hash" : "99a450d8ce5b987a71346d8a0a1203711f770745c7ef326912e46761f14cd764", + "indexes" : { "data" : 0, "gas" : 0, "value" : 1 } + }, + ... + ], + "Frontier" : [ + ... + ], + "Homestead" : [ + ... + ] + }, + "pre" : { + //same as for StateTests + }, + "transaction" : { + "data" : [ "" ], + "gasLimit" : [ "285000", "100000", "6000" ], + "gasPrice" : "0x01", + "nonce" : "0x00", + "secretKey" : "45a915e4d060149eb4365960e6a7a45f334393093061116b197e3240065ff2d8", + "to" : "095e7baea6a6c7c4c2dfeb977efac326af552d87", + "value" : [ "10", "0" ] + } + } + } + + +The env Section +^^^^^^^^^^^^^^^ | ``currentCoinbase`` | The current block's coinbase address, to be returned by the `COINBASE` instruction. @@ -71,7 +111,8 @@ Sections | The previous block's hash. | -* **The** ``transaction`` **section:** +The transaction Section +^^^^^^^^^^^^^^^^^^^^^^^ | ``data`` | The input data passed to the execution, as used by the `CALLDATA`... instructions. Given as an array of byte values. See $DATA_ARRAY. @@ -91,7 +132,19 @@ Sections | The value of the transaction (or the endowment of the create), to be returned by the `CALLVALUE`` instruction (if executed first, before any `CALL`). | -* **The** ``pre`` **and** ``post`` **sections each have the same format of a mapping between addresses and accounts. Each account has the format:** +The post Section +^^^^^^^^^^^^^^^^ + +``Indexes`` section describes which values from given array to set for transaction +before it's execution on a pre state. Transaction now has data, value, and gasLimit as arrays. +post section now has array of implemented forks. For each fork it has another array +of execution results on that fork rules with post state root hash and transaction parameters. + +The pre Section +^^^^^^^^^^^^^^^ + +The ``pre`` section have the format of a mapping between addresses and accounts. +Each account has the format: | ``balance`` | The balance of the account. @@ -103,29 +156,4 @@ Sections | The account's storage, given as a mapping of keys to values. For key used notion of string as digital or hex number e.g: ``"1200"`` or ``"0x04B0"`` For values used $DATA_ARRAY. | -| The ``logs`` sections is a mapping between the blooms and their corresponding logentries. -| Each logentry has the format: -| ``address`` The address of the logentry. -| ``data`` The data of the logentry. -| ``topics`` The topics of the logentry, given as an array of values. -| - -Finally, there is one simple key ``output`` - -| ``output`` -| The data, given as an array of bytes, returned from the execution (using the ``RETURN`` instruction). See $DATA_ARRAY. In order to avoid big data files, there is one exception. If the output data is prefixed with ``#``, the following number represents the size of the output, and not the output directly. -| - - **$DATA_ARRAY** - type that intended to contain raw byte data - and for convenient of the users is populated with three - types of numbers, all of them should be converted and - concatenated to a byte array for VM execution. - - The types are: - - 1. number - (unsigned 64bit) - 2. "longnumber" - (any long number) - 3. "0xhex_num" - (hex format number) - - e.g: ``````[1, 2, 10000, "0xabc345dFF", "199999999999999999999999999999999999999"]`````` \ No newline at end of file -- cgit v1.2.3 From b0425dc87ab3556d020b2e76980bfe516e7b4b84 Mon Sep 17 00:00:00 2001 From: holgerd77 Date: Wed, 30 Aug 2017 20:00:48 +0200 Subject: Updated rlp tests structure --- docs/rlp_tests/index.rst | 30 ++++++++++++++++++++---------- 1 file changed, 20 insertions(+), 10 deletions(-) diff --git a/docs/rlp_tests/index.rst b/docs/rlp_tests/index.rst index 154bd5890..2d812aae6 100644 --- a/docs/rlp_tests/index.rst +++ b/docs/rlp_tests/index.rst @@ -4,23 +4,33 @@ 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 +the .json file. + +=================== ============================================================== +Location `/RLPTests `_ +Supported Hardforks Hardfork-independent +Status Actively supported +=================== ============================================================== + + +Test Implementation +------------------- + +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' +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`` +examples 'in' field would contain string ``VALID`` as it means that rlp should be easily decoded. -**Note** that RLP tests are testing a single RLP object encoding. Not a stream of +**Note** that RLP tests are testing a single RLP object encoding and not a stream of RLP objects in one array. -Basic structure ---------------- +Test Structure +-------------- :: @@ -48,7 +58,7 @@ Basic structure } Sections --------- +^^^^^^^^ -* ``in`` - json object (array, int, string) representation of the rlp byte stream (\*except values 'VALID' and 'INVALID') +* ``in`` - json object (array, int, string) representation of the rlp byte stream (\*except values ``VALID`` and ``INVALID``) * ``out`` - string of rlp bytes stream -- cgit v1.2.3 From 6702d4400f0e68da92881d6600eefd2685a22470 Mon Sep 17 00:00:00 2001 From: holgerd77 Date: Wed, 30 Aug 2017 20:07:50 +0200 Subject: Updated difficulty test structure, network/fork information --- docs/difficulty_tests/index.rst | 20 +++++++++++++------- 1 file changed, 13 insertions(+), 7 deletions(-) diff --git a/docs/difficulty_tests/index.rst b/docs/difficulty_tests/index.rst index 2125169f5..a72e5cb9a 100644 --- a/docs/difficulty_tests/index.rst +++ b/docs/difficulty_tests/index.rst @@ -1,14 +1,19 @@ .. _difficulty_tests: -################################################################################ Difficulty Tests -################################################################################ +================ -Found in ``\Basic Tests\difficulty*.json`` files. This tests are designed to just check the difficulty formula of a block. +These tests are designed to just check the difficulty formula of a block. + +=================== ============================================================== +Location `\BasicTests `_ (difficulty*.json) +Supported Hardforks ``Test Networks`` | ``Frontier`` | ``Homestead`` +Status Outdated +=================== ============================================================== 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. +described at `EIP2 `_ 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. @@ -27,8 +32,8 @@ There are several test files: ``difficultyCustomHomestead.json`` Tests for homestead difficulty (regardless of the block number) -Basic structure --------------------------------------------------------------------------------- +Test Structure +-------------- :: { @@ -42,7 +47,8 @@ Basic structure } 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 -- cgit v1.2.3 From c098cf4761fffaf781cac3d0dc3823cdc020958e Mon Sep 17 00:00:00 2001 From: holgerd77 Date: Wed, 30 Aug 2017 20:21:04 +0200 Subject: Updated VM tests --- docs/transaction_tests/index.rst | 16 +++++++++--- docs/vm_tests/index.rst | 56 ++++++++++++++++++++++++++++------------ 2 files changed, 53 insertions(+), 19 deletions(-) diff --git a/docs/transaction_tests/index.rst b/docs/transaction_tests/index.rst index eb06504f6..f4bac251d 100644 --- a/docs/transaction_tests/index.rst +++ b/docs/transaction_tests/index.rst @@ -4,11 +4,21 @@ Transaction Tests ================= Describes a complete transaction and its `RLP `_ representation using the .json file. + +=================== ============================================================== +Location `/TransactionTests `_ +Supported Hardforks ``Constantinople`` | ``EIP158`` | ``Frontier`` | ``Homestead`` +Status Actively supported +=================== ============================================================== + +Test Implementation +------------------- + The client should read the rlp and check whether the transaction is valid, has the correct sender and corresponds to the transaction parameters. If it is an invalid transaction, the transaction and the sender object will be missing. -Basic structure ---------------- +Test Structure +-------------- :: { @@ -36,7 +46,7 @@ Basic structure } Sections --------- +^^^^^^^^ * ``rlp`` - RLP encoded data of this transaction * ``transaction`` - transaction described by fields diff --git a/docs/vm_tests/index.rst b/docs/vm_tests/index.rst index 16716d53b..4ab33c921 100644 --- a/docs/vm_tests/index.rst +++ b/docs/vm_tests/index.rst @@ -3,12 +3,20 @@ VM Tests ======== -Found in ``/VMTest``, the VM tests aim is to test the basic workings of the VM in -isolation. This is specifically not meant to cover transaction, creation or call +The VM tests aim is to test the basic workings of the VM in +isolation. + +=================== ============================================================== +Location `/VMTests `_ +Supported Hardforks Currently only one fork support depending on latest test fill +Status Actively supported +=================== ============================================================== + +This is specifically not meant to cover transaction, creation or call processing, or management of the state trie. Indeed at least one implementation tests the VM without calling into any Trie code at all. -It is based around the notion of executing a single piece of code as part of a transaction, +A VM test is based around the notion of executing a single piece of code as part of a transaction, described by the ``exec`` portion of the test. The overarching environment in which it is executed is described by the ``env`` portion of the test and includes attributes of the current and previous blocks. A set of pre-existing accounts are detailed @@ -18,6 +26,15 @@ of accounts are detailed in the ``post`` portion to specify the end world state. The gas remaining (``gas``), the log entries (``logs``) as well as any output returned from the code (``output``) is also detailed. + +Test Implementation +------------------- + +It is generally expected that the test implementer will read ``env``, ``exec`` and ``pre`` +then check their results against ``gas``, ``logs``, ``out``, ``post`` and ``callcreates``. +If an exception is expected, then latter sections are absent in the test. Since the +reverting of the state is not part of the VM tests. + Because the data of the blockchain is not given, the opcode BLOCKHASH could not return the hashes of the corresponding blocks. Therefore we define the hash of block number n to be SHA3-256("n"). @@ -29,13 +46,8 @@ details each ``CALL`` or ``CREATE`` operation in the order they would have been Furthermore, gas required is simply that of the VM execution: the gas cost for transaction processing is excluded. -It is generally expected that the test implementer will read ``env``, ``exec`` and ``pre`` -then check their results against ``gas``, ``logs``, ``out``, ``post`` and ``callcreates``. -If an exception is expected, then latter sections are absent in the test. Since the -reverting of the state is not part of the VM tests. - -Basic structure ---------------- +Test Structure +-------------- :: @@ -63,10 +75,8 @@ Basic structure ... } -Sections --------------------------------------------------------------------------------- - -The ``env`` section: +The env Section +^^^^^^^^^^^^^^^ * ``currentCoinbase``: The current block's coinbase address, to be returned by the ``COINBASE`` instruction. * ``currentDifficulty``: The current block's difficulty, to be returned by the ``DIFFICULTY`` instruction. @@ -75,7 +85,8 @@ The ``env`` section: * ``currentTimestamp``: The current block's timestamp. * ``previousHash``: The previous block's hash. -The ``exec`` section: +The exec Section +^^^^^^^^^^^^^^^^ * ``address``: The address of the account under which the code is executing, to be returned by the ``ADDRESS`` instruction. * ``origin``: The address of the execution's origin, to be returned by the ``ORIGIN`` instruction. @@ -86,6 +97,9 @@ The ``exec`` section: * ``gasPrice``: The price of gas for the transaction, as used by the ``GASPRICE`` instruction. * ``gas``: The total amount of gas available for the execution, as would be returned by the ``GAS`` instruction were it be executed first. +The pre and post Section +^^^^^^^^^^^^^^^^^^^^^^^^ + The ``pre`` and ``post`` sections each have the same format of a mapping between addresses and accounts. Each account has the format: * ``balance``: The balance of the account. @@ -93,6 +107,9 @@ The ``pre`` and ``post`` sections each have the same format of a mapping between * ``code``: The body code of the account, given as an array of byte values. See $DATA_ARRAY. * ``storage``: The account's storage, given as a mapping of keys to values. For key used notion of string as digital or hex number e.g: ``"1200"`` or ``"0x04B0"`` For values used $DATA_ARRAY. +The callcreates Section +^^^^^^^^^^^^^^^^^^^^^^^ + The ``callcreates`` section details each ``CALL`` or ``CREATE`` instruction that has been executed. It is an array of maps with keys: * ``data``: An array of bytes specifying the data with which the ``CALL`` or ``CREATE`` operation was made. In the case of ``CREATE``, this would be the (initialisation) code. See $DATA_ARRAY. @@ -100,12 +117,19 @@ The ``callcreates`` section details each ``CALL`` or ``CREATE`` instruction that * ``gasLimit``: The amount of gas with which the operation was made. * ``value``: The value or endowment with which the operation was made. -The ``logs`` sections is a mapping between the blooms and their corresponding logentries. Each logentry has the format: +The logs Section +^^^^^^^^^^^^^^^^ + +The ``logs`` sections is a mapping between the blooms and their corresponding logentries. +Each logentry has the format: * ``address``: The address of the logentry. * ``data``: The data of the logentry. * ``topics``: The topics of the logentry, given as an array of values. +The gas and output Keys +^^^^^^^^^^^^^^^^^^^^^^^ + Finally, there are two simple keys, ``gas`` and ``output``: * ``gas``: The amount of gas remaining after execution. -- cgit v1.2.3 From f7c1b767bba59ae4836f794bff7eeeb51b2bdecf Mon Sep 17 00:00:00 2001 From: holgerd77 Date: Wed, 30 Aug 2017 20:28:20 +0200 Subject: Moved to a simpler file structure for test types --- docs/blockchain_tests/index.rst | 172 ---------------------------------- docs/difficulty_tests/index.rst | 56 ----------- docs/index.rst | 12 +-- docs/rlp_tests/index.rst | 64 ------------- docs/state_tests/index.rst | 159 ------------------------------- docs/test_types/blockchain_tests.rst | 172 ++++++++++++++++++++++++++++++++++ docs/test_types/difficulty_tests.rst | 56 +++++++++++ docs/test_types/rlp_tests.rst | 64 +++++++++++++ docs/test_types/state_tests.rst | 159 +++++++++++++++++++++++++++++++ docs/test_types/transaction_tests.rst | 60 ++++++++++++ docs/test_types/vm_tests.rst | 149 +++++++++++++++++++++++++++++ docs/transaction_tests/index.rst | 60 ------------ docs/vm_tests/index.rst | 149 ----------------------------- 13 files changed, 666 insertions(+), 666 deletions(-) delete mode 100644 docs/blockchain_tests/index.rst delete mode 100644 docs/difficulty_tests/index.rst delete mode 100644 docs/rlp_tests/index.rst delete mode 100644 docs/state_tests/index.rst create mode 100644 docs/test_types/blockchain_tests.rst create mode 100644 docs/test_types/difficulty_tests.rst create mode 100644 docs/test_types/rlp_tests.rst create mode 100644 docs/test_types/state_tests.rst create mode 100644 docs/test_types/transaction_tests.rst create mode 100644 docs/test_types/vm_tests.rst delete mode 100644 docs/transaction_tests/index.rst delete mode 100644 docs/vm_tests/index.rst diff --git a/docs/blockchain_tests/index.rst b/docs/blockchain_tests/index.rst deleted file mode 100644 index c9b6dd359..000000000 --- a/docs/blockchain_tests/index.rst +++ /dev/null @@ -1,172 +0,0 @@ -.. _blockchain_tests: - -Blockchain Tests -================ - -The blockchain tests aim is to test the basic verification of a blockchain. - -=================== ============================================================== -Location `/BlockchainTests `_ -Supported Hardforks ``Byzantium`` | ``Constantinople`` | ``EIP150`` | ``EIP158`` | ``Frontier`` | ``Homestead`` -Status Actively supported -=================== ============================================================== - -A blockchain test 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. - -Of special notice is the -`/BlockchainTests/GeneralStateTests `_ -folder within the blockchain tests folder structure, which contains a copy of the -:ref:`state_tests` but executes them within the logic of the blockchain tests. - - -Test Implementation -------------------- - -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. - -Test Structure --------------- - -:: - - { - "TESTNAME_Byzantium": { - "blocks" : [ - { - "blockHeader": { ... }, - "rlp": { ... }, - "transactions": { ... }, - "uncleHeaders": { ... } - }, - { - "blockHeader": { ... }, - "rlp": { ... }, - "transactions": { ... }, - "uncleHeaders": { ... } - }, - { ... } - ], - "genesisBlockHeader": { ... }, - "genesisRLP": " ... ", - "lastblockhash": " ... ", - "network": "Byzantium", - "postState": { ... }, - "pre": { ... } - }, - "TESTNAME_EIP150": { - "blocks" : [ - { - "blockHeader": { ... }, - "rlp": { ... }, - "transactions": { ... }, - "uncleHeaders": { ... } - }, - { - "blockHeader": { ... }, - "rlp": { ... }, - "transactions": { ... }, - "uncleHeaders": { ... } - }, - { ... } - ], - "genesisBlockHeader": { ... }, - "genesisRLP": " ... ", - "lastblockhash": " ... ", - "network": "Byzantium", - "postState": { ... }, - "pre": { ... } - }, - ... - } - - -The Blocks Section -^^^^^^^^^^^^^^^^^^ - -The ``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 :ref:`transaction_tests`. - -* ``uncleHeaders`` section is a list of block headers which have the same format as - descibed in `genesisBlockHeader`. - - -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 - calculated 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 and postState Sections -^^^^^^^^^^^^^^^^^^^^^^^^^^ - -* ``pre`` section: as described in :ref:`state_tests`. - -* ``postState`` section: as described in :ref:`state_tests` (section - post). - - -Optional BlockHeader Information -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -``"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. \ No newline at end of file diff --git a/docs/difficulty_tests/index.rst b/docs/difficulty_tests/index.rst deleted file mode 100644 index a72e5cb9a..000000000 --- a/docs/difficulty_tests/index.rst +++ /dev/null @@ -1,56 +0,0 @@ -.. _difficulty_tests: - -Difficulty Tests -================ - -These tests are designed to just check the difficulty formula of a block. - -=================== ============================================================== -Location `\BasicTests `_ (difficulty*.json) -Supported Hardforks ``Test Networks`` | ``Frontier`` | ``Homestead`` -Status Outdated -=================== ============================================================== - -difficulty = DIFFICULTY(currentBlockNumber, currentTimestamp, parentTimestamp, parentDifficulty) - -described at `EIP2 `_ 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) - -Test 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 diff --git a/docs/index.rst b/docs/index.rst index 5dd1f5518..8840e12eb 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -16,12 +16,12 @@ Ethereum Tests :caption: Contents: using-testeth.rst - blockchain_tests/index.rst - state_tests/index.rst - rlp_tests/index.rst - difficulty_tests/index.rst - transaction_tests/index.rst - vm_tests/index.rst + test_types/blockchain_tests.rst + test_types/state_tests.rst + test_types/rlp_tests.rst + test_types/difficulty_tests.rst + test_types/transaction_tests.rst + test_types/vm_tests.rst contribute.rst diff --git a/docs/rlp_tests/index.rst b/docs/rlp_tests/index.rst deleted file mode 100644 index 2d812aae6..000000000 --- a/docs/rlp_tests/index.rst +++ /dev/null @@ -1,64 +0,0 @@ -.. _rlp_tests: - -RLP Tests -========= - -Describes an **RLP** (https://github.com/ethereum/wiki/wiki/RLP) encoding using -the .json file. - -=================== ============================================================== -Location `/RLPTests `_ -Supported Hardforks Hardfork-independent -Status Actively supported -=================== ============================================================== - - -Test Implementation -------------------- - -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. - -**Note** that RLP tests are testing a single RLP object encoding and not a stream of -RLP objects in one array. - -Test 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 diff --git a/docs/state_tests/index.rst b/docs/state_tests/index.rst deleted file mode 100644 index facb66187..000000000 --- a/docs/state_tests/index.rst +++ /dev/null @@ -1,159 +0,0 @@ -.. _state_tests: - -General State Tests -=================== - -The state tests aim is to test the basic workings of the state in isolation. - -=================== ============================================================== -Location `/GeneralStateTests `_ -Supported Hardforks ``Byzantium`` | ``Constantinople`` | ``EIP150`` | ``EIP158`` | ``Frontier`` | ``Homestead`` -Status Actively supported -=================== ============================================================== - -A state test is based around the notion of executing a single transaction, described -by the ``transaction`` portion of the test. The overarching environment -in which it is executed is described by the ``env`` portion of the test and -includes attributes of the current and previous blocks. A set of pre-existing accounts -are detailed in the ``pre`` portion and form the world state prior to execution. -Similarly, a set of accounts are detailed in the ``post`` portion to specify the -end world state. Since the data of the blockchain is not given, the opcode ``BLOCKHASH`` -could not return the hashes of the corresponding blocks. Therefore we define the hash of -block number ``n`` to be ``SHA256("n")``. - -The log entries (``logs``) as well as any output returned from the code (``output``) is also detailed. - -Test Implementation -------------------- - -It is generally expected that the test implementer will read ``env``, ``transaction`` -and ``pre`` then check their results against ``logs``, ``out``, and ``post``. - -.. note:: - The structure of state tests was reworked lately, see the associated discussion - `here `_. - -Test Structure --------------- - -:: - - { - "testname" : { - "env" : { - "currentCoinbase" : "address", - "currentDifficulty" : "0x020000", //minimum difficulty for mining on blockchain - "currentGasLimit" : "u64", //not larger then maxGasLimit = 0x7fffffffffffffff - "currentNumber" : "0x01", //Irrelevant to hardfork parameters! - "currentTimestamp" : "1000", //for blockchain version - "previousHash" : "h256" - }, - "post" : { - "EIP150" : [ - { - "hash" : "3e6dacc1575c6a8c76422255eca03529bbf4c0dda75dfc110b22d6dc4152396f", - "indexes" : { "data" : 0, "gas" : 0, "value" : 0 } - }, - { - "hash" : "99a450d8ce5b987a71346d8a0a1203711f770745c7ef326912e46761f14cd764", - "indexes" : { "data" : 0, "gas" : 0, "value" : 1 } - }, - ... - ], - "EIP158" : [ - { - "hash" : "3e6dacc1575c6a8c76422255eca03529bbf4c0dda75dfc110b22d6dc4152396f", - "indexes" : { "data" : 0, "gas" : 0, "value" : 0 } - }, - { - "hash" : "99a450d8ce5b987a71346d8a0a1203711f770745c7ef326912e46761f14cd764", - "indexes" : { "data" : 0, "gas" : 0, "value" : 1 } - }, - ... - ], - "Frontier" : [ - ... - ], - "Homestead" : [ - ... - ] - }, - "pre" : { - //same as for StateTests - }, - "transaction" : { - "data" : [ "" ], - "gasLimit" : [ "285000", "100000", "6000" ], - "gasPrice" : "0x01", - "nonce" : "0x00", - "secretKey" : "45a915e4d060149eb4365960e6a7a45f334393093061116b197e3240065ff2d8", - "to" : "095e7baea6a6c7c4c2dfeb977efac326af552d87", - "value" : [ "10", "0" ] - } - } - } - - -The env Section -^^^^^^^^^^^^^^^ - -| ``currentCoinbase`` -| The current block's coinbase address, to be returned by the `COINBASE` instruction. -| ``currentDifficulty`` -| The current block's difficulty, to be returned by the `DIFFICULTY` instruction. -| ``currentGasLimit`` -| The current block's gas limit. -| ``currentNumber`` -| The current block's number. Also indicates network rules for the transaction. Since blocknumber = **1000000** Homestead rules are applied to transaction. (see https://github.com/ethereum/EIPs/blob/master/EIPS/eip-2.mediawiki) -| ``currentTimestamp`` -| The current block's timestamp. -| ``previousHash`` -| The previous block's hash. -| - -The transaction Section -^^^^^^^^^^^^^^^^^^^^^^^ - -| ``data`` -| The input data passed to the execution, as used by the `CALLDATA`... instructions. Given as an array of byte values. See $DATA_ARRAY. -| ``gasLimit`` -| The total amount of gas available for the execution, as would be returned by the `GAS` instruction were it be executed first. -| ``gasPrice`` -| The price of gas for the transaction, as used by the `GASPRICE` instruction. -| ``nonce`` -| Scalar value equal to the number of transactions sent by the sender. -| ``address`` -| The address of the account under which the code is executing, to be returned by the `ADDRESS` instruction. -| ``secretKey`` -| The secret key as can be derived by the v,r,s values if the transaction. -| ``to`` -| The address of the transaction's recipient, to be returned by the `ORIGIN` instruction. -| ``value`` -| The value of the transaction (or the endowment of the create), to be returned by the `CALLVALUE`` instruction (if executed first, before any `CALL`). -| - -The post Section -^^^^^^^^^^^^^^^^ - -``Indexes`` section describes which values from given array to set for transaction -before it's execution on a pre state. Transaction now has data, value, and gasLimit as arrays. -post section now has array of implemented forks. For each fork it has another array -of execution results on that fork rules with post state root hash and transaction parameters. - -The pre Section -^^^^^^^^^^^^^^^ - -The ``pre`` section have the format of a mapping between addresses and accounts. -Each account has the format: - -| ``balance`` -| The balance of the account. -| ``nonce`` -| The nonce of the account. -| ``code`` -| The body code of the account, given as an array of byte values. See $DATA_ARRAY. -| ``storage`` -| The account's storage, given as a mapping of keys to values. For key used notion of string as digital or hex number e.g: ``"1200"`` or ``"0x04B0"`` For values used $DATA_ARRAY. -| - - diff --git a/docs/test_types/blockchain_tests.rst b/docs/test_types/blockchain_tests.rst new file mode 100644 index 000000000..c9b6dd359 --- /dev/null +++ b/docs/test_types/blockchain_tests.rst @@ -0,0 +1,172 @@ +.. _blockchain_tests: + +Blockchain Tests +================ + +The blockchain tests aim is to test the basic verification of a blockchain. + +=================== ============================================================== +Location `/BlockchainTests `_ +Supported Hardforks ``Byzantium`` | ``Constantinople`` | ``EIP150`` | ``EIP158`` | ``Frontier`` | ``Homestead`` +Status Actively supported +=================== ============================================================== + +A blockchain test 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. + +Of special notice is the +`/BlockchainTests/GeneralStateTests `_ +folder within the blockchain tests folder structure, which contains a copy of the +:ref:`state_tests` but executes them within the logic of the blockchain tests. + + +Test Implementation +------------------- + +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. + +Test Structure +-------------- + +:: + + { + "TESTNAME_Byzantium": { + "blocks" : [ + { + "blockHeader": { ... }, + "rlp": { ... }, + "transactions": { ... }, + "uncleHeaders": { ... } + }, + { + "blockHeader": { ... }, + "rlp": { ... }, + "transactions": { ... }, + "uncleHeaders": { ... } + }, + { ... } + ], + "genesisBlockHeader": { ... }, + "genesisRLP": " ... ", + "lastblockhash": " ... ", + "network": "Byzantium", + "postState": { ... }, + "pre": { ... } + }, + "TESTNAME_EIP150": { + "blocks" : [ + { + "blockHeader": { ... }, + "rlp": { ... }, + "transactions": { ... }, + "uncleHeaders": { ... } + }, + { + "blockHeader": { ... }, + "rlp": { ... }, + "transactions": { ... }, + "uncleHeaders": { ... } + }, + { ... } + ], + "genesisBlockHeader": { ... }, + "genesisRLP": " ... ", + "lastblockhash": " ... ", + "network": "Byzantium", + "postState": { ... }, + "pre": { ... } + }, + ... + } + + +The Blocks Section +^^^^^^^^^^^^^^^^^^ + +The ``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 :ref:`transaction_tests`. + +* ``uncleHeaders`` section is a list of block headers which have the same format as + descibed in `genesisBlockHeader`. + + +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 + calculated 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 and postState Sections +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +* ``pre`` section: as described in :ref:`state_tests`. + +* ``postState`` section: as described in :ref:`state_tests` (section - post). + + +Optional BlockHeader Information +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +``"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. \ No newline at end of file diff --git a/docs/test_types/difficulty_tests.rst b/docs/test_types/difficulty_tests.rst new file mode 100644 index 000000000..a72e5cb9a --- /dev/null +++ b/docs/test_types/difficulty_tests.rst @@ -0,0 +1,56 @@ +.. _difficulty_tests: + +Difficulty Tests +================ + +These tests are designed to just check the difficulty formula of a block. + +=================== ============================================================== +Location `\BasicTests `_ (difficulty*.json) +Supported Hardforks ``Test Networks`` | ``Frontier`` | ``Homestead`` +Status Outdated +=================== ============================================================== + +difficulty = DIFFICULTY(currentBlockNumber, currentTimestamp, parentTimestamp, parentDifficulty) + +described at `EIP2 `_ 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) + +Test 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 diff --git a/docs/test_types/rlp_tests.rst b/docs/test_types/rlp_tests.rst new file mode 100644 index 000000000..2d812aae6 --- /dev/null +++ b/docs/test_types/rlp_tests.rst @@ -0,0 +1,64 @@ +.. _rlp_tests: + +RLP Tests +========= + +Describes an **RLP** (https://github.com/ethereum/wiki/wiki/RLP) encoding using +the .json file. + +=================== ============================================================== +Location `/RLPTests `_ +Supported Hardforks Hardfork-independent +Status Actively supported +=================== ============================================================== + + +Test Implementation +------------------- + +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. + +**Note** that RLP tests are testing a single RLP object encoding and not a stream of +RLP objects in one array. + +Test 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 diff --git a/docs/test_types/state_tests.rst b/docs/test_types/state_tests.rst new file mode 100644 index 000000000..facb66187 --- /dev/null +++ b/docs/test_types/state_tests.rst @@ -0,0 +1,159 @@ +.. _state_tests: + +General State Tests +=================== + +The state tests aim is to test the basic workings of the state in isolation. + +=================== ============================================================== +Location `/GeneralStateTests `_ +Supported Hardforks ``Byzantium`` | ``Constantinople`` | ``EIP150`` | ``EIP158`` | ``Frontier`` | ``Homestead`` +Status Actively supported +=================== ============================================================== + +A state test is based around the notion of executing a single transaction, described +by the ``transaction`` portion of the test. The overarching environment +in which it is executed is described by the ``env`` portion of the test and +includes attributes of the current and previous blocks. A set of pre-existing accounts +are detailed in the ``pre`` portion and form the world state prior to execution. +Similarly, a set of accounts are detailed in the ``post`` portion to specify the +end world state. Since the data of the blockchain is not given, the opcode ``BLOCKHASH`` +could not return the hashes of the corresponding blocks. Therefore we define the hash of +block number ``n`` to be ``SHA256("n")``. + +The log entries (``logs``) as well as any output returned from the code (``output``) is also detailed. + +Test Implementation +------------------- + +It is generally expected that the test implementer will read ``env``, ``transaction`` +and ``pre`` then check their results against ``logs``, ``out``, and ``post``. + +.. note:: + The structure of state tests was reworked lately, see the associated discussion + `here `_. + +Test Structure +-------------- + +:: + + { + "testname" : { + "env" : { + "currentCoinbase" : "address", + "currentDifficulty" : "0x020000", //minimum difficulty for mining on blockchain + "currentGasLimit" : "u64", //not larger then maxGasLimit = 0x7fffffffffffffff + "currentNumber" : "0x01", //Irrelevant to hardfork parameters! + "currentTimestamp" : "1000", //for blockchain version + "previousHash" : "h256" + }, + "post" : { + "EIP150" : [ + { + "hash" : "3e6dacc1575c6a8c76422255eca03529bbf4c0dda75dfc110b22d6dc4152396f", + "indexes" : { "data" : 0, "gas" : 0, "value" : 0 } + }, + { + "hash" : "99a450d8ce5b987a71346d8a0a1203711f770745c7ef326912e46761f14cd764", + "indexes" : { "data" : 0, "gas" : 0, "value" : 1 } + }, + ... + ], + "EIP158" : [ + { + "hash" : "3e6dacc1575c6a8c76422255eca03529bbf4c0dda75dfc110b22d6dc4152396f", + "indexes" : { "data" : 0, "gas" : 0, "value" : 0 } + }, + { + "hash" : "99a450d8ce5b987a71346d8a0a1203711f770745c7ef326912e46761f14cd764", + "indexes" : { "data" : 0, "gas" : 0, "value" : 1 } + }, + ... + ], + "Frontier" : [ + ... + ], + "Homestead" : [ + ... + ] + }, + "pre" : { + //same as for StateTests + }, + "transaction" : { + "data" : [ "" ], + "gasLimit" : [ "285000", "100000", "6000" ], + "gasPrice" : "0x01", + "nonce" : "0x00", + "secretKey" : "45a915e4d060149eb4365960e6a7a45f334393093061116b197e3240065ff2d8", + "to" : "095e7baea6a6c7c4c2dfeb977efac326af552d87", + "value" : [ "10", "0" ] + } + } + } + + +The env Section +^^^^^^^^^^^^^^^ + +| ``currentCoinbase`` +| The current block's coinbase address, to be returned by the `COINBASE` instruction. +| ``currentDifficulty`` +| The current block's difficulty, to be returned by the `DIFFICULTY` instruction. +| ``currentGasLimit`` +| The current block's gas limit. +| ``currentNumber`` +| The current block's number. Also indicates network rules for the transaction. Since blocknumber = **1000000** Homestead rules are applied to transaction. (see https://github.com/ethereum/EIPs/blob/master/EIPS/eip-2.mediawiki) +| ``currentTimestamp`` +| The current block's timestamp. +| ``previousHash`` +| The previous block's hash. +| + +The transaction Section +^^^^^^^^^^^^^^^^^^^^^^^ + +| ``data`` +| The input data passed to the execution, as used by the `CALLDATA`... instructions. Given as an array of byte values. See $DATA_ARRAY. +| ``gasLimit`` +| The total amount of gas available for the execution, as would be returned by the `GAS` instruction were it be executed first. +| ``gasPrice`` +| The price of gas for the transaction, as used by the `GASPRICE` instruction. +| ``nonce`` +| Scalar value equal to the number of transactions sent by the sender. +| ``address`` +| The address of the account under which the code is executing, to be returned by the `ADDRESS` instruction. +| ``secretKey`` +| The secret key as can be derived by the v,r,s values if the transaction. +| ``to`` +| The address of the transaction's recipient, to be returned by the `ORIGIN` instruction. +| ``value`` +| The value of the transaction (or the endowment of the create), to be returned by the `CALLVALUE`` instruction (if executed first, before any `CALL`). +| + +The post Section +^^^^^^^^^^^^^^^^ + +``Indexes`` section describes which values from given array to set for transaction +before it's execution on a pre state. Transaction now has data, value, and gasLimit as arrays. +post section now has array of implemented forks. For each fork it has another array +of execution results on that fork rules with post state root hash and transaction parameters. + +The pre Section +^^^^^^^^^^^^^^^ + +The ``pre`` section have the format of a mapping between addresses and accounts. +Each account has the format: + +| ``balance`` +| The balance of the account. +| ``nonce`` +| The nonce of the account. +| ``code`` +| The body code of the account, given as an array of byte values. See $DATA_ARRAY. +| ``storage`` +| The account's storage, given as a mapping of keys to values. For key used notion of string as digital or hex number e.g: ``"1200"`` or ``"0x04B0"`` For values used $DATA_ARRAY. +| + + diff --git a/docs/test_types/transaction_tests.rst b/docs/test_types/transaction_tests.rst new file mode 100644 index 000000000..f4bac251d --- /dev/null +++ b/docs/test_types/transaction_tests.rst @@ -0,0 +1,60 @@ +.. _transaction_tests: + +Transaction Tests +================= + +Describes a complete transaction and its `RLP `_ representation using the .json file. + +=================== ============================================================== +Location `/TransactionTests `_ +Supported Hardforks ``Constantinople`` | ``EIP158`` | ``Frontier`` | ``Homestead`` +Status Actively supported +=================== ============================================================== + +Test Implementation +------------------- + +The client should read the rlp and check whether the transaction is valid, has the correct sender and corresponds to the transaction parameters. +If it is an invalid transaction, the transaction and the sender object will be missing. + +Test Structure +-------------- +:: + + { + "transactionTest1": { + "rlp" : "bytearray", + "sender" : "address", + "blocknumber" : "1000000" + "transaction" : { + "nonce" : "int", + "gasPrice" : "int", + "gasLimit" : "int", + "to" : "address", + "value" : "int", + "v" : "byte", + "r" : "256 bit unsigned int", + "s" : "256 bit unsigned int", + "data" : "byte array" + } + }, + + "invalidTransactionTest": { + "rlp" : "bytearray", + }, + ... + } + +Sections +^^^^^^^^ + +* ``rlp`` - RLP encoded data of this transaction +* ``transaction`` - transaction described by fields +* ``nonce`` - A scalar value equal to the number of transactions sent by the sender. +* ``gasPrice`` - A scalar value equal to the number of wei to be paid per unit of gas. +* ``gasLimit`` - A scalar value equal to the maximum amount of gas that should be used in executing this transaction. +* ``to`` - The 160-bit address of the message call's recipient or empty for a contract creation transaction. +* ``value`` - A scalar value equal to the number of wei to be transferred to the message call's recipient or, in the case of contract creation, as an endowment to the newly created account. +* ``v, r, s`` - Values corresponding to the signature of the transaction and used to determine the sender of the transaction. +* ``sender`` - the address of the sender, derived from the v,r,s values. +* ``blocknumber`` - indicates network rules for the transaction. Since blocknumber = **1000000** Homestead rules are applied to transaction. (see https://github.com/ethereum/EIPs/blob/master/EIPS/eip-2.mediawiki) diff --git a/docs/test_types/vm_tests.rst b/docs/test_types/vm_tests.rst new file mode 100644 index 000000000..4ab33c921 --- /dev/null +++ b/docs/test_types/vm_tests.rst @@ -0,0 +1,149 @@ +.. _vm_tests: + +VM Tests +======== + +The VM tests aim is to test the basic workings of the VM in +isolation. + +=================== ============================================================== +Location `/VMTests `_ +Supported Hardforks Currently only one fork support depending on latest test fill +Status Actively supported +=================== ============================================================== + +This is specifically not meant to cover transaction, creation or call +processing, or management of the state trie. Indeed at least one implementation +tests the VM without calling into any Trie code at all. + +A VM test is based around the notion of executing a single piece of code as part of a transaction, +described by the ``exec`` portion of the test. The overarching environment in which it is +executed is described by the ``env`` portion of the test and includes attributes +of the current and previous blocks. A set of pre-existing accounts are detailed +in the ``pre`` portion and form the world state prior to execution. Similarly, a set +of accounts are detailed in the ``post`` portion to specify the end world state. + +The gas remaining (``gas``), the log entries (``logs``) as well as any output returned +from the code (``output``) is also detailed. + + +Test Implementation +------------------- + +It is generally expected that the test implementer will read ``env``, ``exec`` and ``pre`` +then check their results against ``gas``, ``logs``, ``out``, ``post`` and ``callcreates``. +If an exception is expected, then latter sections are absent in the test. Since the +reverting of the state is not part of the VM tests. + +Because the data of the blockchain is not given, the opcode BLOCKHASH could not +return the hashes of the corresponding blocks. Therefore we define the hash of +block number n to be SHA3-256("n"). + +Since these tests are meant only as a basic test of VM operation, the ``CALL`` and +``CREATE`` instructions are not actually executed. To provide the possibility of +testing to guarantee they were actually run at all, a separate portion ``callcreates`` +details each ``CALL`` or ``CREATE`` operation in the order they would have been executed. +Furthermore, gas required is simply that of the VM execution: the gas cost for +transaction processing is excluded. + +Test Structure +-------------- + +:: + + { + "test name 1": { + "env": { ... }, + "pre": { ... }, + "exec": { ... }, + "gas": { ... }, + "logs": { ... }, + "out": { ... }, + "post": { ... }, + "callcreates": { ... } + }, + "test name 2": { + "env": { ... }, + "pre": { ... }, + "exec": { ... }, + "gas": { ... }, + "logs": { ... }, + "out": { ... }, + "post": { ... }, + "callcreates": { ... } + }, + ... + } + +The env Section +^^^^^^^^^^^^^^^ + +* ``currentCoinbase``: The current block's coinbase address, to be returned by the ``COINBASE`` instruction. +* ``currentDifficulty``: The current block's difficulty, to be returned by the ``DIFFICULTY`` instruction. +* ``currentGasLimit``: The current block's gas limit. +* ``currentNumber``: The current block's number. +* ``currentTimestamp``: The current block's timestamp. +* ``previousHash``: The previous block's hash. + +The exec Section +^^^^^^^^^^^^^^^^ + +* ``address``: The address of the account under which the code is executing, to be returned by the ``ADDRESS`` instruction. +* ``origin``: The address of the execution's origin, to be returned by the ``ORIGIN`` instruction. +* ``caller``: The address of the execution's caller, to be returned by the ``CALLER`` instruction. +* ``value``: The value of the call (or the endowment of the create), to be returned by the ``CALLVALUE`` instruction. +* ``data``: The input data passed to the execution, as used by the ``CALLDATA``... instructions. Given as an array of byte values. See $DATA_ARRAY. +* ``code``: The actual code that should be executed on the VM (not the one stored in the state(address)) . See $DATA_ARRAY. +* ``gasPrice``: The price of gas for the transaction, as used by the ``GASPRICE`` instruction. +* ``gas``: The total amount of gas available for the execution, as would be returned by the ``GAS`` instruction were it be executed first. + +The pre and post Section +^^^^^^^^^^^^^^^^^^^^^^^^ + +The ``pre`` and ``post`` sections each have the same format of a mapping between addresses and accounts. Each account has the format: + +* ``balance``: The balance of the account. +* ``nonce``: The nonce of the account. +* ``code``: The body code of the account, given as an array of byte values. See $DATA_ARRAY. +* ``storage``: The account's storage, given as a mapping of keys to values. For key used notion of string as digital or hex number e.g: ``"1200"`` or ``"0x04B0"`` For values used $DATA_ARRAY. + +The callcreates Section +^^^^^^^^^^^^^^^^^^^^^^^ + +The ``callcreates`` section details each ``CALL`` or ``CREATE`` instruction that has been executed. It is an array of maps with keys: + +* ``data``: An array of bytes specifying the data with which the ``CALL`` or ``CREATE`` operation was made. In the case of ``CREATE``, this would be the (initialisation) code. See $DATA_ARRAY. +* ``destination``: The receipt address to which the ``CALL`` was made, or the null address (``"0000..."``) if the corresponding operation was ``CREATE``. +* ``gasLimit``: The amount of gas with which the operation was made. +* ``value``: The value or endowment with which the operation was made. + +The logs Section +^^^^^^^^^^^^^^^^ + +The ``logs`` sections is a mapping between the blooms and their corresponding logentries. +Each logentry has the format: + +* ``address``: The address of the logentry. +* ``data``: The data of the logentry. +* ``topics``: The topics of the logentry, given as an array of values. + +The gas and output Keys +^^^^^^^^^^^^^^^^^^^^^^^ + +Finally, there are two simple keys, ``gas`` and ``output``: + +* ``gas``: The amount of gas remaining after execution. +* ``output``: The data, given as an array of bytes, returned from the execution (using the ``RETURN`` instruction). See $DATA_ARRAY. + + **$DATA_ARRAY** - type that intended to contain raw byte data + and for convenient of the users is populated with three + types of numbers, all of them should be converted and + concatenated to a byte array for VM execution. + +* The types are: + 1. number - (unsigned 64bit) + 2. "longnumber" - (any long number) + 3. "0xhex_num" - (hex format number) + + + e.g: ``````[1, 2, 10000, "0xabc345dFF", "199999999999999999999999999999999999999"]`````` \ No newline at end of file diff --git a/docs/transaction_tests/index.rst b/docs/transaction_tests/index.rst deleted file mode 100644 index f4bac251d..000000000 --- a/docs/transaction_tests/index.rst +++ /dev/null @@ -1,60 +0,0 @@ -.. _transaction_tests: - -Transaction Tests -================= - -Describes a complete transaction and its `RLP `_ representation using the .json file. - -=================== ============================================================== -Location `/TransactionTests `_ -Supported Hardforks ``Constantinople`` | ``EIP158`` | ``Frontier`` | ``Homestead`` -Status Actively supported -=================== ============================================================== - -Test Implementation -------------------- - -The client should read the rlp and check whether the transaction is valid, has the correct sender and corresponds to the transaction parameters. -If it is an invalid transaction, the transaction and the sender object will be missing. - -Test Structure --------------- -:: - - { - "transactionTest1": { - "rlp" : "bytearray", - "sender" : "address", - "blocknumber" : "1000000" - "transaction" : { - "nonce" : "int", - "gasPrice" : "int", - "gasLimit" : "int", - "to" : "address", - "value" : "int", - "v" : "byte", - "r" : "256 bit unsigned int", - "s" : "256 bit unsigned int", - "data" : "byte array" - } - }, - - "invalidTransactionTest": { - "rlp" : "bytearray", - }, - ... - } - -Sections -^^^^^^^^ - -* ``rlp`` - RLP encoded data of this transaction -* ``transaction`` - transaction described by fields -* ``nonce`` - A scalar value equal to the number of transactions sent by the sender. -* ``gasPrice`` - A scalar value equal to the number of wei to be paid per unit of gas. -* ``gasLimit`` - A scalar value equal to the maximum amount of gas that should be used in executing this transaction. -* ``to`` - The 160-bit address of the message call's recipient or empty for a contract creation transaction. -* ``value`` - A scalar value equal to the number of wei to be transferred to the message call's recipient or, in the case of contract creation, as an endowment to the newly created account. -* ``v, r, s`` - Values corresponding to the signature of the transaction and used to determine the sender of the transaction. -* ``sender`` - the address of the sender, derived from the v,r,s values. -* ``blocknumber`` - indicates network rules for the transaction. Since blocknumber = **1000000** Homestead rules are applied to transaction. (see https://github.com/ethereum/EIPs/blob/master/EIPS/eip-2.mediawiki) diff --git a/docs/vm_tests/index.rst b/docs/vm_tests/index.rst deleted file mode 100644 index 4ab33c921..000000000 --- a/docs/vm_tests/index.rst +++ /dev/null @@ -1,149 +0,0 @@ -.. _vm_tests: - -VM Tests -======== - -The VM tests aim is to test the basic workings of the VM in -isolation. - -=================== ============================================================== -Location `/VMTests `_ -Supported Hardforks Currently only one fork support depending on latest test fill -Status Actively supported -=================== ============================================================== - -This is specifically not meant to cover transaction, creation or call -processing, or management of the state trie. Indeed at least one implementation -tests the VM without calling into any Trie code at all. - -A VM test is based around the notion of executing a single piece of code as part of a transaction, -described by the ``exec`` portion of the test. The overarching environment in which it is -executed is described by the ``env`` portion of the test and includes attributes -of the current and previous blocks. A set of pre-existing accounts are detailed -in the ``pre`` portion and form the world state prior to execution. Similarly, a set -of accounts are detailed in the ``post`` portion to specify the end world state. - -The gas remaining (``gas``), the log entries (``logs``) as well as any output returned -from the code (``output``) is also detailed. - - -Test Implementation -------------------- - -It is generally expected that the test implementer will read ``env``, ``exec`` and ``pre`` -then check their results against ``gas``, ``logs``, ``out``, ``post`` and ``callcreates``. -If an exception is expected, then latter sections are absent in the test. Since the -reverting of the state is not part of the VM tests. - -Because the data of the blockchain is not given, the opcode BLOCKHASH could not -return the hashes of the corresponding blocks. Therefore we define the hash of -block number n to be SHA3-256("n"). - -Since these tests are meant only as a basic test of VM operation, the ``CALL`` and -``CREATE`` instructions are not actually executed. To provide the possibility of -testing to guarantee they were actually run at all, a separate portion ``callcreates`` -details each ``CALL`` or ``CREATE`` operation in the order they would have been executed. -Furthermore, gas required is simply that of the VM execution: the gas cost for -transaction processing is excluded. - -Test Structure --------------- - -:: - - { - "test name 1": { - "env": { ... }, - "pre": { ... }, - "exec": { ... }, - "gas": { ... }, - "logs": { ... }, - "out": { ... }, - "post": { ... }, - "callcreates": { ... } - }, - "test name 2": { - "env": { ... }, - "pre": { ... }, - "exec": { ... }, - "gas": { ... }, - "logs": { ... }, - "out": { ... }, - "post": { ... }, - "callcreates": { ... } - }, - ... - } - -The env Section -^^^^^^^^^^^^^^^ - -* ``currentCoinbase``: The current block's coinbase address, to be returned by the ``COINBASE`` instruction. -* ``currentDifficulty``: The current block's difficulty, to be returned by the ``DIFFICULTY`` instruction. -* ``currentGasLimit``: The current block's gas limit. -* ``currentNumber``: The current block's number. -* ``currentTimestamp``: The current block's timestamp. -* ``previousHash``: The previous block's hash. - -The exec Section -^^^^^^^^^^^^^^^^ - -* ``address``: The address of the account under which the code is executing, to be returned by the ``ADDRESS`` instruction. -* ``origin``: The address of the execution's origin, to be returned by the ``ORIGIN`` instruction. -* ``caller``: The address of the execution's caller, to be returned by the ``CALLER`` instruction. -* ``value``: The value of the call (or the endowment of the create), to be returned by the ``CALLVALUE`` instruction. -* ``data``: The input data passed to the execution, as used by the ``CALLDATA``... instructions. Given as an array of byte values. See $DATA_ARRAY. -* ``code``: The actual code that should be executed on the VM (not the one stored in the state(address)) . See $DATA_ARRAY. -* ``gasPrice``: The price of gas for the transaction, as used by the ``GASPRICE`` instruction. -* ``gas``: The total amount of gas available for the execution, as would be returned by the ``GAS`` instruction were it be executed first. - -The pre and post Section -^^^^^^^^^^^^^^^^^^^^^^^^ - -The ``pre`` and ``post`` sections each have the same format of a mapping between addresses and accounts. Each account has the format: - -* ``balance``: The balance of the account. -* ``nonce``: The nonce of the account. -* ``code``: The body code of the account, given as an array of byte values. See $DATA_ARRAY. -* ``storage``: The account's storage, given as a mapping of keys to values. For key used notion of string as digital or hex number e.g: ``"1200"`` or ``"0x04B0"`` For values used $DATA_ARRAY. - -The callcreates Section -^^^^^^^^^^^^^^^^^^^^^^^ - -The ``callcreates`` section details each ``CALL`` or ``CREATE`` instruction that has been executed. It is an array of maps with keys: - -* ``data``: An array of bytes specifying the data with which the ``CALL`` or ``CREATE`` operation was made. In the case of ``CREATE``, this would be the (initialisation) code. See $DATA_ARRAY. -* ``destination``: The receipt address to which the ``CALL`` was made, or the null address (``"0000..."``) if the corresponding operation was ``CREATE``. -* ``gasLimit``: The amount of gas with which the operation was made. -* ``value``: The value or endowment with which the operation was made. - -The logs Section -^^^^^^^^^^^^^^^^ - -The ``logs`` sections is a mapping between the blooms and their corresponding logentries. -Each logentry has the format: - -* ``address``: The address of the logentry. -* ``data``: The data of the logentry. -* ``topics``: The topics of the logentry, given as an array of values. - -The gas and output Keys -^^^^^^^^^^^^^^^^^^^^^^^ - -Finally, there are two simple keys, ``gas`` and ``output``: - -* ``gas``: The amount of gas remaining after execution. -* ``output``: The data, given as an array of bytes, returned from the execution (using the ``RETURN`` instruction). See $DATA_ARRAY. - - **$DATA_ARRAY** - type that intended to contain raw byte data - and for convenient of the users is populated with three - types of numbers, all of them should be converted and - concatenated to a byte array for VM execution. - -* The types are: - 1. number - (unsigned 64bit) - 2. "longnumber" - (any long number) - 3. "0xhex_num" - (hex format number) - - - e.g: ``````[1, 2, 10000, "0xabc345dFF", "199999999999999999999999999999999999999"]`````` \ No newline at end of file -- cgit v1.2.3 From 047ea6801d058a6bd58f0f7a3d4aaa6d659684a7 Mon Sep 17 00:00:00 2001 From: holgerd77 Date: Wed, 30 Aug 2017 20:38:35 +0200 Subject: Updated contribute notice on table of contents in docs --- docs/index.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index 8840e12eb..323902751 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -8,8 +8,7 @@ Ethereum Tests | .. note:: - Larger parts of the test docs are currently outdated (see :ref:`contribute` on how to - help). + See :ref:`contribute` if you want to help improve this documentation. .. toctree:: :maxdepth: 2 -- cgit v1.2.3