EVM tool reference
This reference describes options for running the following using the EVM tool:
Option names that include trace
, such as --trace
and --trace.[no]memory
exist to support t8ntool
reference testing, and are interchangeable with their standard option names.
Run options
The first mode of the EVM tool runs an arbitrary EVM and is invoked without an extra command. Command line options specify the code and other contextual information.
code
- Syntax
- Example
--code=<code>
--code=5B600080808060045AFA50600056
The code to be executed, in compiled hex code form. Execution fails if this is not set.
gas
- Syntax
- Example
--gas=<integer>
--gas=100000000
Amount of gas to make available to the EVM. The default is 10 billion, a number unlikely to be seen in any production blockchain.
price
- Syntax
- Example
--price=<integer>
--price=10
Price of gas in Gwei. The default is 0
. If set to a non-zero value, the sender account must have enough value to cover the gas fees.
sender
- Syntax
- Example
--sender=<address>
--sender=0xfe3b557e8fb62b89f4916b721be55ceb828dbd73
The account the invocation is sent from. The specified account must exist in the world state, which, unless specified by --genesis
, is the set of accounts used for testing.
receiver
- Syntax
- Example
--receiver=<address>
--receiver=0x588108d3eab34e94484d7cda5a1d31804ca96fe7
The account the invocation is sent to. The specified account does not need to exist.
input
- Syntax
- Example
--input=<code>
--input=9064129300000000000000000000000000000000000000000000000000000000
The data passed into the call. Corresponds to the data
field of the transaction and is returned by the CALLDATA
and related opcodes.
value
- Syntax
- Example
--value=<integer>
--value=1000000000000000000
The value, in wei, attached to this transaction. For operations that query the value or transfer it to other accounts this is the amount that is available. The amount is not reduced to cover intrinsic cost and gas fees.
json
, trace
- Syntax
--json
Provides an operation-by-operation trace of the command in JSON.
--trace
is an alias for --json
.
json-alloc
- Syntax
--json-alloc
Outputs a JSON summary of the post-execution world state and allocations.
[no]memory
, trace.[no]memory
- Syntax
--nomemory, --memory
Setting --nomemory
disables tracing the memory output for each operation. Setting --memory
enables it. Memory traces are disabled by default.
For memory heavy scripts, disabling memory traces may reduce the volume of JSON output.
--trace.[no]memory
is an alias for --[no]memory
.
trace.[no]stack
- Syntax
--trace.nostack, --trace.stack
Setting --trace.nostack
disables tracing the operand stack for each operation. Setting --trace.stack
enables it. Stack traces are enabled by default.
trace.[no]returndata
- Syntax
--trace.noreturndata, --trace.returndata
Setting --trace.noreturndata
disables tracing the return data for each operation. Setting --trace.returndata
enables it. Return data traces are enabled by default.
[no]time
- Syntax
--notime, --time
Setting --notime
disables including time data in the summary output. Setting --time
enables it.
This is useful for testing and differential evaluations.
genesis
- Syntax
- Example
--genesis=<path>
--genesis=/opt/besu/genesis.json
The Besu genesis file to use when evaluating the EVM. Most useful are the alloc
items that set up accounts and their stored memory states.
--prestate
is a deprecated alias for --genesis
.
chain
- Syntax
- Example
--chain=<mainnet|goerli|sepolia|dev|classic|mordor|kotti|astor>
--chain=goerli
The well-known network genesis file to use when evaluating the EVM. These values are an alternative to the --genesis
option for well-known networks.
repeat
- Syntax
- Example
--repeat=<integer>
--repeat=1000
Number of times to repeat the contract before gathering timing information. This is useful when benchmarking EVM operations. The default is 0
.
revert-reason-enabled
- Syntax
--revert-reason-enabled
Enables tracing the reason included in REVERT
operations. The revert reason is enabled by default.
fork
- Syntax
- Example
--fork=<string>
--fork=FutureEips
Specific fork to evaluate, overriding network settings.
key-value-storage
- Syntax
- Example
--key-value-storage=<memory|rocksdb>
--key-value-storage=rocksdb
Kind of key value storage to use.
It might be useful to execute isolated EVM calls in the context of an actual world state. The default is memory
, which executes the call only in the context of the world provided by --genesis
or --chain
at block zero.
When set to rocksdb
and combined with --data-path
, --block-number
, and --genesis
, a Besu node that isn't currently running can be used to provide the appropriate world state for a transaction. This is useful when evaluating consensus failures.
data-path
- Syntax
- Example
--data-path=<path>
--data-path=/opt/besu/data
When --key-value-storage
is set to rocksdb
, specifies the location of the database on disk.
block-number
- Syntax
- Example
--block-number=<integer>
--block-number=10000000
The block number to evaluate the code against. Used to ensure that the EVM is evaluating the code against the correct fork, or to specify the world state when --key-value-storage
is set to rocksdb
.
version
- Syntax
--version
Displays the version information.
-v
is an alias for --version
.
State test options
The state-test
subcommand allows the Ethereum state tests to be evaluated. The only applicable options are --json
and --nomemory
.
json
, trace
- Syntax
--json
Provides an operation-by-operation trace of the command in JSON.
Set this option for EVM Lab Fuzzing. Whether or not --json
is set, a summary JSON object is printed to standard output for each state test executed.
--trace
is an alias for --json
.
[no]memory
, trace.[no]memory
- Syntax
--[no]memory
Setting --nomemory
disables tracing the memory output for each operation. Setting --memory
enables it. Memory traces are disabled by default.
For memory heavy scripts, disabling memory traces may reduce the volume of JSON output.
--trace.[no]memory
is an alias for --[no]memory
.
Use command arguments
If you use command arguments, you can list one or more state tests. All the state tests are evaluated in the order they are specified.
- Docker example
- CLI example
docker run --rm -v ${PWD}:/opt/referencetests hyperledger/besu-evmtool:develop --json state-test /opt/referencetests/GeneralStateTests/stExample/add11.json
evm --json state-test stExample/add11.json
Use standard input
If no reference tests are passed in using the command line, the EVM tool loads one complete JSON object from standard input and executes that state test.
- Docker example
- CLI example
docker run --rm -i hyperledger/besu-evmtool:develop --json state-test < stExample/add11.json
evm --json state-test < stExample/add11.json
EOF code validation
The code-validate
subcommand allows Ethereum object formatted (EOF) code to be validated. It accepts candidate EOF containers or EVM bytecode using the --file
option, command arguments, or standard input.
file
- Syntax
- Example
--file=<file>
--file=eof.txt
File containing one or more EOF containers or EVM bytecode. Each line in the file is considered a separate program.
Use command arguments
If you use command arguments, each argument is considered a separate program. If a code segment includes spaces, it must be contained in quotes.
- Docker example
- CLI example
docker run --rm hyperledger/besu-evmtool:develop code-validate "0xef0001 010008 020002-0007-0002 030000 00 00000002-02010002 59-59-b00001-50-b1 03-b1" 0xef0002 0xef00010100040200010001030000000000000000
evm code-validate "0xef0001 010008 020002-0007-0002 030000 00 00000002-02010002 59-59-b00001-50-b1 03-b1" 0xef0002 0xef00010100040200010001030000000000000000
Use standard input
If no reference tests are passed in using the command line, the EVM tool loads and validates code from standard input. Each line is considered a separate program. Comment lines and blanks are ignored.