From 9fa03b3779a6591d744ad67a2a6cdef9f3287e5d Mon Sep 17 00:00:00 2001 From: Alexandra Tran Carrillo <12214231+alexandratran@users.noreply.github.com> Date: Thu, 26 Oct 2023 20:07:57 -0700 Subject: [PATCH] update evm tool docs (#1428) * update evm tool docs Signed-off-by: Alexandra Tran * address reviewer feedback Signed-off-by: Alexandra Tran * address reviewer comments Signed-off-by: Alexandra Tran --------- Signed-off-by: Alexandra Tran Signed-off-by: Alexandra Tran Carrillo <12214231+alexandratran@users.noreply.github.com> --- .../how-to/troubleshoot/evm-tool.md | 51 ++++---- docs/public-networks/reference/evm-tool.md | 114 ++++++++---------- 2 files changed, 72 insertions(+), 93 deletions(-) diff --git a/docs/public-networks/how-to/troubleshoot/evm-tool.md b/docs/public-networks/how-to/troubleshoot/evm-tool.md index 7e5a044180a..3ccf4e08dad 100644 --- a/docs/public-networks/how-to/troubleshoot/evm-tool.md +++ b/docs/public-networks/how-to/troubleshoot/evm-tool.md @@ -9,11 +9,13 @@ tags: # 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. +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 does not have a standard zip file distribution. To use, you need to either build from the source repository or use a pre-published docker image. +The EVM tool is part of the standard [Besu binary distribution](../../get-started/install/binary-distribution.md). ### Build from source @@ -23,12 +25,13 @@ 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`. +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: ```bash -ethereum/evmtool/build/install/evmtool/bin/evm +ethereum/evmtool/build/install/evmtool/bin/evmtool ``` ### Execute with Docker @@ -39,36 +42,28 @@ To run the Besu EVM tool in a container: docker run -rm hyperledger/besu-evmtool:develop ``` -- 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. +- 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. - +The `latest` tag is the latest released version of Besu. +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](../../reference/evm-tool.md) specify the code and other contextual information. - -The EVM tool also has a [`state-test` subcommand](../../reference/evm-tool.md#state-test-options) that allows [Ethereum state tests](https://github.com/ethereum/tests/tree/develop/GeneralStateTests) to be evaluated, and a [`code-validate` subcommand](../../reference/evm-tool.md#eof-code-validation) that allows [Ethereum object formatted (EOF)](https://eips.ethereum.org/EIPS/eip-3540) code to be validated. Most of the options from EVM execution don't apply. - - +## EVM tool options -# `state-test` +The first mode of the EVM tool runs arbitrary EVM bytecode. +Use [command line options](../../reference/evm-tool.md#options) to specify the code and other +contextual information. +For example: ```bash -evm state-test --nomemory +evmtool --code=5B600080808060045AFA50600056 ``` -# `code-validate` - -```bash -evm code-validate --file -``` - - - -The [EVM tool reference](../../reference/evm-tool.md) provides more information on these modes. +The EVM tool also has [subcommands](../../reference/evm-tool.md#subcommands) used for testing code bases. +These subcommands are not meant for typical user interactions. diff --git a/docs/public-networks/reference/evm-tool.md b/docs/public-networks/reference/evm-tool.md index 37c8b88ea02..03742232170 100644 --- a/docs/public-networks/reference/evm-tool.md +++ b/docs/public-networks/reference/evm-tool.md @@ -9,11 +9,8 @@ tags: # EVM tool reference -This reference describes options for running the following [using the EVM tool](../how-to/troubleshoot/evm-tool.md): - -- [Arbitrary EVM programs](#run-options) -- [Ethereum state tests](#state-test-options) -- [Ethereum object formatted code](#eof-code-validation) +This reference describes [options](#options) and [subcommands](#subcommands) for the +[EVM tool](../how-to/troubleshoot/evm-tool.md). :::note @@ -21,9 +18,7 @@ Option names that include `trace`, such as [`--trace`](#json-trace) and [`--trac ::: -## 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. +## Options ### `code` @@ -433,130 +428,119 @@ Displays the version information. `-v` is an alias for `--version`. -## State test options +## Subcommands -The `state-test` subcommand allows the [Ethereum state tests](https://github.com/ethereum/tests/tree/develop/GeneralStateTests) to be evaluated. The only applicable options are `--json` and `--nomemory`. +:::caution +The following subcommands are used for testing code bases and not meant for typical user interactions. +::: -### `json`, `trace` +### `code-validate` # Syntax ```bash ---json +evmtool code-validate --file= ``` - - -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 +# Example ```bash ---[no]memory +evmtool code-validate --file=eof.txt ``` -Setting `--nomemory` disables tracing the memory output for each operation. Setting `--memory` enables it. Memory traces are disabled by default. +Allows [Ethereum object formatted (EOF)](https://eips.ethereum.org/EIPS/eip-3540) code to be validated. -For memory heavy scripts, disabling memory traces may reduce the volume of JSON output. +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. -`--trace.[no]memory` is an alias for `--[no]memory`. +#### Use command arguments -### 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. +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 ```bash -docker run --rm -v ${PWD}:/opt/referencetests hyperledger/besu-evmtool:develop --json state-test /opt/referencetests/GeneralStateTests/stExample/add11.json +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 ``` # CLI example ```bash -evm --json state-test stExample/add11.json +evmtool 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 one complete JSON object from standard input and executes that state test. - - - -# Docker example +#### Use standard input -```bash -docker run --rm -i hyperledger/besu-evmtool:develop --json state-test < stExample/add11.json -``` - -# CLI example +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. -```bash -evm --json state-test < stExample/add11.json -``` +### `state-test` - +Allows the [Ethereum state tests](https://github.com/ethereum/tests/tree/develop/GeneralStateTests) +to be evaluated. +Run `evmtool state-test --help` for the full list of supported options. +Notable options are [`--json`](#json-trace) and [`--nomemory`](#nomemory-tracenomemory). -## EOF code validation +Set `--json` for EVM Lab Fuzzing. +Whether or not `--json` is set, a summary JSON object is printed to standard output for each state +test executed. -The `code-validate` subcommand allows [Ethereum object formatted (EOF)](https://eips.ethereum.org/EIPS/eip-3540) code to be validated. It accepts candidate EOF containers or EVM bytecode using the `--file` option, command arguments, or standard input. +#### Use command arguments -### `file` +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. -# Syntax +# Docker example ```bash ---file= +docker run --rm -v ${PWD}:/opt/referencetests hyperledger/besu-evmtool:develop --json state-test /opt/referencetests/GeneralStateTests/stExample/add11.json ``` -# Example +# CLI example ```bash ---file=eof.txt +evmtool --json state-test stExample/add11.json ``` -File containing one or more EOF containers or EVM bytecode. Each line in the file is considered a separate program. - -### Use command arguments +#### Use standard input -If you use command arguments, each argument is considered a separate program. If a code segment includes spaces, it must be contained in quotes. +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 ```bash -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 +docker run --rm -i hyperledger/besu-evmtool:develop --json state-test < stExample/add11.json ``` # CLI example ```bash -evm code-validate "0xef0001 010008 020002-0007-0002 030000 00 00000002-02010002 59-59-b00001-50-b1 03-b1" 0xef0002 0xef00010100040200010001030000000000000000 +evmtool --json state-test < stExample/add11.json ``` -### Use standard input +### `transition`, `t8n`, `t8n-server` -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. +Allows the Ethereum state transition and blockchain tests to be evaluated. +See the [transition tool reference](https://ethereum-tests.readthedocs.io/en/develop/t8ntool-ref.html) +and [Execution Spec Tests](https://ethereum.github.io/execution-spec-tests/v1.0.6/) for more +information about this subcommand.