Skip to main content

Use the EVM tool

The Besu EVM tool is a CLI program that executes arbitrary EVM programs and Ethereum State Tests outside the context of an operating node. Use the EVM tool for benchmarking and fuzz testing.

Get the EVM tool​

The Besu EVM tool is a part of the standard zip file distribution. To use the EVM tool, you can download the standard Besu distributuon on the releases page. You may also build from the source repository or use a pre-published docker image.

Build from source​

To build from source, run the following from the root of the Besu repository:

./gradlew :ethereum:evmTool:installDist

An extractable archive files is created in ethereum/evmtool/build/distributions and an executable installation in ethereum/evmtool/build/install/evmtool.

Execute the EVM tool:

ethereum/evmtool/build/install/evmtool/bin/evm <evmtool options>

Execute with Docker​

To run the Besu EVM tool in a container:

docker run -rm <docker options> hyperledger/besu-evmtool:develop <evmtool options>
  • Because no data is stored in local directories we recommended using the -rm docker option. The -rm option deletes the container at the end of execution.
  • If you use an option that requires input from standard in, use the -i docker option. The -i option pipes standard input to the EVM tool.
  • If you need to reference files we recommend using a docker file binding, such as -v ${PWD}:/opt/data, which maps the current directory to the /opt/data directory in the container.
note

The latest tag is the latest released version of Besu, starting with 1.5.3. The develop tag is the current main branch code that will go into a future release version of Besu.

EVM tool 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.

The EVM tool also has a state-test subcommand that allows Ethereum state tests to be evaluated, and a code-validate subcommand that allows Ethereum object formatted (EOF) code to be validated. Most of the options from EVM execution don't apply.

evm state-test <state-test> --nomemory

The EVM tool reference provides more information on these modes.