<commit_before>.. _t8ntool_ref:

###########################################
Transition Tool
###########################################



Command Line Parameters
=======================
The command line parameters are used to specify the parameters, input files, and
output files.

Test Parameters
---------------
- **-\\-state.fork** *fork name*
- **-\\-state.reward** *block mining reward* (appears only in Block tests)
- **-\\-trace** produce a trace

Input Files
-----------
- **-\\-input.alloc** *full path to pretest allocation file*
- **-\\-input.txs** *full path to transaction file*
- **-\\-input.env** *full path to environment file*

.. note::

   If you want to specify any of this information in `stdin`, either 
   omit the parameter or use the value **stdin**.

Output Files
------------
- **-\\-output.basedir** *directory to write the output files*
- **-\\-output.result** *file name for test output*
- **-\\-output.alloc**  *file name for post test allocation file*
- **-\\-output.body** *file name for a list of rlp transactions* (a binary file)

.. note::

   If you want to receive this information into `stdout`, either omit
   the parameter or use the value **stdout**.


File Structures
===============
All of the transition tool files are in JSON format. Any values that are not
provided are assumed to be zero or empty, as applicable.


Transaction File
----------------
The transaction file is a list that contains maps, one for each transaction. 
This is an input to the tool, which `retesteth` calls `txs.json`. 

Every transaction can include these fields:

* `gas`
* `gasPrice`
* `input`, the transaction data
* `nonce`
* `value`, the value in WEI sent by the transaction
* `to`, the destination. If it is not specified the transaction creates a contract

In addition, there are a few special fields that may or may not appear, as explained
below.

Transaction Signatures
^^^^^^^^^^^^^^^^^^^^^^
Transactions can be previously signed by the caller that runs the tool. In that case
the transaction includes the `v`, `r`, and `s` values of the signature.

Alternatively, the transaction can include `secretKey`, in which the tool is responsible
for the signature.


EIP 2930
^^^^^^^^
`This EIP <https://eips.ethereum.org/EIPS/eip-2930>`_ defines a new transaction type
which includes a list of addresses and storage locations. If a transaction uses
EIP 2930 it would have two additional fields:

* `type` equal to one. If the transaction is normal it either has a value of zero 
  or does not appear at all. 
* `accessList`, an EIP 2930 access list.


Example 
^^^^^^^ 
The first transaction in this list is a normal transaction, already signed. 
The second is an EIP 2930 transaction which needs to be signed.

::

   [
      {
         "gas": "0x5208",
         "gasPrice": "0x2",
         "hash": "0x0557bacce3375c98d806609b8d5043072f0b6a8bae45ae5a67a00d3a1a18d673",
         "input": "0x",
         "nonce": "0x0",
         "r": "0x9500e8ba27d3c33ca7764e107410f44cbd8c19794bde214d694683a7aa998cdb",
         "s": "0x7235ae07e4bd6e0206d102b1f8979d6adab280466b6a82d2208ee08951f1f600",
         "to": "0x8a8eafb1cf62bfbeb1741769dae1a9dd47996192",
         "v": "0x1b",
         "value": "0x1"
      },
      {
         "gas": "0x4ef00",
         "gasPrice": "0x1",
         "chainId": "0x1",
         "input": "0x",
         "nonce": "0x0",
         "to": "0x000000000000000000000000000000000000aaaa",
         "value": "0x1",
         "type" : "0x1",
         "accessList": [
            {
               "address": "0x0000000000000000000000000000000000000aaaa",
               "storageKeys": [
                  "0x0000000000000000000000000000000000000000000000000000000000000000",
                  "0x0000000000000000000000000000000000000000000000000000000000000012"
               ]
            },
            {
               "address": "0x0000000000000000000000000000000000000aaab",
               "storageKeys": [
                  "0x00000000000000000000000000000000000000000000000000000000000060A7",
                  "0x0000000000000000000000000000000000000000000000000000000000000012"
               ]
            }
         ]
         "v": "0x0",
         "r": "0x0",
         "s": "0x0",
         "secretKey": "0x45a915e4d060149eb4365960e6a7a45f334393093061116b197e3240065ff2d8"
      }
   ]


Environment File
----------------
This file is a map with the execution environment. 
This is an input to the tool, which `retesteth` calls `env.json`.
It has these fields:


* `currentCoinbase`
* `currentDifficulty`
* `currentGasLimit`
* `currentNumber`
* `currentTimestamp`
* `previousHash`, the hash of the previous (`currentNumber`-1) block
* `blockHashes`, a map of historical block numbers and their hashes

.. note::<commit_msg>feat(docs): Updated t8ntool to say txs.rlp<commit_after>.. _t8ntool_ref:

###########################################
Transition Tool
###########################################



Command Line Parameters
=======================
The command line parameters are used to specify the parameters, input files, and
output files.

In the **t8ntool** client provided with the system, which uses **geth**, the commands being called are:

- **evm t8n** For state transition and blockchain tests.
- **evm t9n** For transaction tests.

However, you can change that by editing the **tests/config/t8ntool/start.sh** file.


Test Parameters
---------------
- **-\\-state.fork** *fork name*
- **-\\-state.reward** *block mining reward* (appears only in Block tests)
- **-\\-trace** produce a trace

Input Files
-----------
- **-\\-input.alloc** *full path to pretest allocation file with the state*
  Note that in the case of transaction tests this file does not appear
- **-\\-input.txs** *full path to transaction file*
- **-\\-input.env** *full path to environment file*

.. note::

   If you want to specify any of this information in `stdin`, either 
   omit the parameter or use the value **stdin**.

Output Files
------------
- **-\\-output.basedir** *directory to write the output files*
- **-\\-output.result** *file name for test output*
- **-\\-output.alloc**  *file name for post test allocation file*
- **-\\-output.body** *file name for a list of rlp transactions* (a binary file)

.. note::

   If you want to receive this information into `stdout`, either omit
   the parameter or use the value **stdout**.


File Structures
===============
Most of the transition tool files are in JSON format. Any values that are not
provided are assumed to be zero or empty, as applicable.


Transaction File
----------------
This file is a single line `"0x<rlp encoded transaction><rlp encoded transaction>..."`.
If there are no transactions, the line is `"0xc0"`.
This is an input to the tool, which `retesteth` calls `txs.rlp`. 


Environment File
----------------
This file is a map with the execution environment. 
This is an input to the tool, which `retesteth` calls `env.json`.
It has these fields:


* `currentCoinbase`
* `currentDifficulty`
* `currentGasLimit`
* `currentNumber`
* `currentTimestamp`
* `previousHash`, the hash of the previous (`currentNumber`-1) block
* `blockHashes`, a map of historical block numbers and their hashes

.. note::
{'fraction_non_alphanumeric': 0.15807702964810197, 'fraction_numerical': 0.08880576336935439, 'mean_word_length': 3.1204337899543377, 'pattern_counts': {'":': 26, '<': 6, '<?xml version=': 0, '>': 6, 'https://': 1, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 7, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3907485', 'n_tokens_mistral': 2565, 'n_tokens_neox': 2032, 'n_words': 779}