update evm tool docs (#1428)

* update evm tool docs Signed-off-by: Alexandra Tran <alexandra.tran@consensys.net> * address reviewer feedback Signed-off-by: Alexandra Tran <alexandra.tran@consensys.net> * address reviewer comments Signed-off-by: Alexandra Tran <alexandra.tran@consensys.net> --------- Signed-off-by: Alexandra Tran <alexandra.tran@consensys.net> Signed-off-by: Alexandra Tran Carrillo <12214231+alexandratran@users.noreply.github.com>
hyperledger · Oct 27, 2023 · 9fa03b3 · 9fa03b3
1 parent 5b3b5c1
commit 9fa03b3
Show file tree

Hide file tree

Showing 2 changed files with 72 additions and 93 deletions.
diff --git 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 <evmtool options>
+ethereum/evmtool/build/install/evmtool/bin/evmtool <evmtool options>
 ```
 
 ### Execute with Docker
@@ -39,36 +42,28 @@ 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.
+- 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.
-
-<!--tabs-->
+## 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 <state-test> --nomemory
+evmtool --code=5B600080808060045AFA50600056
 ```
 
-# `code-validate`
-
-```bash
-evm code-validate --file <file>
-```
-
-<!--/tabs-->
-
-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
@@ -9,21 +9,16 @@ 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
 
 Option names that include `trace`, such as [`--trace`](#json-trace) and [`--trace.[no]memory`](#nomemory-tracenomemory) exist to support [`t8ntool`](https://ethereum-tests.readthedocs.io/en/latest/t8ntool.html) 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.
+## 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`
 
 <!--tabs-->
 
 # Syntax
 
 ```bash
---json
+evmtool code-validate --file=<file>
 ```
 
-<!--/tabs-->
-
-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`
-
-<!--tabs-->
-
-# Syntax
+# Example
 
 ```bash
---[no]memory
+evmtool code-validate --file=eof.txt
 ```
 
 <!--/tabs-->
 
-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.
 
 <!--tabs-->
 
 # 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
 ```
 
 <!--/tabs-->
 
-### 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.
-
-<!--tabs-->
-
-# 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`
 
-<!--/tabs-->
+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.
 
 <!--tabs-->
 
-# Syntax
+# Docker example
 
 ```bash
---file=<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
 ```
 
 <!--/tabs-->
 
-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.
 
 <!--tabs-->
 
 # 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
 ```
 
 <!--/tabs-->
 
-### 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.