Skip to main content

EVM tool reference

This reference describes options and subcommands for the EVM tool.

note

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.

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​

--code=<code>

The code to be executed, in compiled hex code form. Execution fails if this is not set.

gas​

--gas=<integer>

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​

--price=<integer>

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​

--sender=<address>

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​

--receiver=<address>

The account the invocation is sent to. The specified account does not need to exist.

input​

--input=<code>

The data passed into the call. Corresponds to the data field of the transaction and is returned by the CALLDATA and related opcodes.

value​

--value=<integer>

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​

--json

Provides an operation-by-operation trace of the command in JSON.

--trace is an alias for --json.

json-alloc​

--json-alloc

Outputs a JSON summary of the post-execution world state and allocations.

[no]memory, trace.[no]memory​

--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​

--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​

--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​

--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​

--genesis=<path>

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​

--chain=<mainnet|goerli|sepolia|dev|classic|mordor|kotti|astor>

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​

--repeat=<integer>

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​

--revert-reason-enabled

Enables tracing the reason included in REVERT operations. The revert reason is enabled by default.

fork​

--fork=<string>

Specific fork to evaluate, overriding network settings.

key-value-storage​

--key-value-storage=<memory|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​

--data-path=<path>

When --key-value-storage is set to rocksdb, specifies the location of the database on disk.

block-number​

--block-number=<integer>

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​

--version

Displays the version information.

-v is an alias for --version.

Subcommands​

caution

The following subcommands are used for testing code bases and not meant for typical user interactions.

code-validate​

evmtool code-validate --file=<file>

Allows Ethereum object formatted (EOF) code to be validated.

You can specify a file containing one or more EOF containers or EVM bytecode using the --file option. 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 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

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.

state-test​

Allows the Ethereum state tests to be evaluated. The only applicable options are --json and --nomemory.

Set --json 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.

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 run --rm -v ${PWD}:/opt/referencetests hyperledger/besu-evmtool:develop --json state-test /opt/referencetests/GeneralStateTests/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 run --rm -i hyperledger/besu-evmtool:develop --json state-test < stExample/add11.json

transition, t8n​

Allows the Ethereum state transition and blockchain tests to be evaluated. See the transition tool reference and Execution Spec Tests for more information about this subcommand.