For AI agents: a documentation index is available at /llms.txt. Markdown versions of pages are available by appending .md to any documentation URL.
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​

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|sepolia|dev|hoodi|linea_mainnet|linea_sepolia>

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. Run evmtool state-test --help for the full list of supported options. Notable options are --json, --nomemory, --workers, --test-name, --test-name-regex, --json-array, and --summary-only.

Set --json for EVM Lab Fuzzing. Each executed test prints a summary JSON object to standard output, whether or not --json is set. --summary-only omits that object for tests that pass. --json-array prints one JSON array instead. The command exits with code 1 when any test fails or when no test runs.

workers​

evmtool state-test --workers=<integer>

Number of parallel workers used to process fixture files. The default is the number of available processor cores. A single path, including the stdin path, stays on one thread. Parallelism applies only when the run collects more than one fixture file.

test-name​

evmtool state-test --test-name=<string>

Limits execution to tests where the argument matches a case-insensitive substring of the test name. The special characters * and ? can be used as wildcards to match multiple or single characters. An argument with a wildcard must match the whole test name, so add a leading or trailing * to match part of it. Quote an argument that contains * or ? so the shell does not expand it. For example, --test-name='*ccess?ist'. An invalid pattern, or a pattern that selects no test, exits with code 1.

test-name-regex​

evmtool state-test --test-name-regex=<regex>

Limits execution to tests whose name matches this regular expression, taken exactly as written. The match is case-sensitive and starts at the beginning of the test name, as a hive --sim.limit filter does, so you can pass a published hive filter unchanged. This option can't be used with --test-name. An invalid pattern, or a pattern that selects no test, exits with code 1.

json-array​

evmtool state-test --json-array

Prints results as one JSON array and prints nothing else. Each element has name, pass, fork, stateRoot, and error. error is an empty string when the test passes. The process exits with code 1 when a test fails or when no test runs.

[
  {
    "name": "<test-name>",
    "pass": true,
    "fork": "<fork>",
    "stateRoot": "<state-root>",
    "error": ""
  }
]

summary-only​

evmtool state-test --summary-only

Skips the per-test summary JSON object for tests that pass. Failed tests still print a summary JSON object. When at least one test runs, the command then prints State test summary: <passed> passed, <failed> failed. With --json, that summary line is printed only when --summary-only is also set. --json-array ignores this option and prints only the JSON array.

Use command arguments​

Pass one or more state test files or directories. A directory is expanded recursively to its .json files, in sorted order. Files under a .meta directory are skipped. The collected files run in parallel when --workers is greater than 1 and more than one file is collected. A single file runs on one thread.

docker run --rm -v ${PWD}:/opt/referencetests hyperledger/besu-evmtool:develop --json state-test /opt/referencetests/GeneralStateTests/stExample/add11.json

Use standard input​

Pass the path stdin to read one state test JSON object from standard input.

docker run --rm -i hyperledger/besu-evmtool:develop --json state-test stdin < stExample/add11.json

With no path argument, each line of standard input is the path of one state test file. This path runs one file at a time and does not use --workers:

evmtool --json state-test < filenames.txt

transition, t8n, t8n-server​

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.