> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/ethereum/go-ethereum/llms.txt
> Use this file to discover all available pages before exploring further.

# EVM tool

> Run EVM bytecode, execute state transitions, and validate transactions without a running node.

The `evm` command is a developer utility for exercising the Ethereum Virtual Machine in isolation. It is useful for:

* Running bytecode snippets and inspecting output or gas usage
* Executing full state transitions for consensus testing (`t8n`)
* Validating raw transactions against a fork spec (`t9n`)
* Assembling sealed block RLPs (`b11r`)
* Running the Ethereum state test suite

## Installation

`evm` is built alongside the rest of go-ethereum:

```bash theme={null}
git clone https://github.com/ethereum/go-ethereum.git
cd go-ethereum
make all
# binary at ./build/bin/evm
```

Or install it directly:

```bash theme={null}
go install github.com/ethereum/go-ethereum/cmd/evm@latest
```

## Subcommands

| Subcommand      | Alias  | Description                        |
| --------------- | ------ | ---------------------------------- |
| `run`           | —      | Execute arbitrary EVM bytecode     |
| `statetest`     | —      | Run Ethereum state test JSON files |
| `transition`    | `t8n`  | Stateless state transition utility |
| `transaction`   | `t9n`  | Validate a set of raw transactions |
| `block-builder` | `b11r` | Assemble and seal a full block RLP |
| `verkle`        | `vkt`  | Binary trie helper commands        |

## Running bytecode (`evm run`)

The `run` subcommand executes raw EVM bytecode against an in-memory state.

### Basic usage

```bash theme={null}
# Pass bytecode as the first positional argument (hex, no 0x prefix required).
evm run 6001600201
```

```bash theme={null}
# Read bytecode from a file.
evm run --codefile contract.bin
```

```bash theme={null}
# Read bytecode from stdin.
echo '6001600201' | evm run --codefile -
```

### Tracing execution

Use `--trace` to emit a structured execution trace to stderr.

```bash theme={null}
# JSON trace (default format).
evm run --trace 6001600201
```

```bash theme={null}
# Structured (human-readable) format.
evm run --trace --trace.format struct 6001600201
```

```bash theme={null}
# Markdown format.
evm run --trace --trace.format md 6001600201
```

### Example: PUSH and ADD

The bytecode `6001 6002 01` pushes `1` and `2` onto the stack, then adds them.

```bash theme={null}
evm run --trace --trace.format struct 6001600201
```

Expected output on stdout:

```text theme={null}
0x03
```

With `--trace --trace.format struct`, stderr shows each opcode step, the stack state, gas consumed, and the final result.

### Inspecting state after execution

```bash theme={null}
# Dump the full post-execution state trie.
evm run --dump 6001600201
```

```bash theme={null}
# Print memory and heap allocation stats.
evm run --statdump 6001600201
```

### Benchmarking

```bash theme={null}
evm run --bench 6001600201
```

`--bench` runs the bytecode repeatedly using Go's testing benchmarker and prints average gas used, execution time, and allocations.

### `run` flags reference

<AccordionGroup>
  <Accordion title="Execution flags">
    | Flag          | Default       | Description                                                   |
    | ------------- | ------------- | ------------------------------------------------------------- |
    | `--gas`       | `10000000000` | Gas limit for the execution                                   |
    | `--price`     | `0`           | Gas price (wei)                                               |
    | `--value`     | `0`           | ETH value sent with the call (wei)                            |
    | `--sender`    | `"sender"`    | Originating address of the transaction                        |
    | `--receiver`  | `"receiver"`  | Address of the contract being called                          |
    | `--input`     | —             | ABI-encoded calldata (hex)                                    |
    | `--inputfile` | —             | File containing calldata (hex)                                |
    | `--codefile`  | —             | File containing bytecode. Use `-` for stdin.                  |
    | `--prestate`  | —             | JSON genesis file used as the initial state                   |
    | `--create`    | `false`       | Treat the execution as a contract creation rather than a call |
    | `--bench`     | `false`       | Benchmark the execution                                       |
    | `--dump`      | `false`       | Dump the state trie after execution                           |
    | `--statdump`  | `false`       | Print stack and heap memory info                              |
  </Accordion>

  <Accordion title="Tracing flags">
    | Flag                   | Default | Description                                    |
    | ---------------------- | ------- | ---------------------------------------------- |
    | `--trace`              | `false` | Enable opcode-level tracing                    |
    | `--trace.format`       | `json`  | Trace output format: `json`, `struct`, or `md` |
    | `--trace.nomemory`     | `true`  | Disable memory output in traces                |
    | `--trace.nostack`      | `false` | Disable stack output in traces                 |
    | `--trace.nostorage`    | `false` | Disable storage output in traces               |
    | `--trace.noreturndata` | `true`  | Disable return data in traces                  |
  </Accordion>
</AccordionGroup>

## Running state tests (`evm statetest`)

The `statetest` subcommand runs Ethereum state test JSON files from the official test suite.

```bash theme={null}
# Run a single file.
evm statetest tests/GeneralStateTests/stExample/add11.json
```

```bash theme={null}
# Run all JSON files in a directory.
evm statetest tests/GeneralStateTests/stExample/
```

```bash theme={null}
# Restrict to a specific fork and emit a structured trace.
evm statetest --statetest.fork Berlin --trace tests/GeneralStateTests/stExample/add11.json
```

```bash theme={null}
# Filter by test name (regex).
evm statetest --run 'add.*' tests/GeneralStateTests/stExample/
```

## State transition tool (`evm t8n`)

The `transition` subcommand (alias `t8n`) applies a set of transactions to a pre-state and produces a post-state. It is the core primitive used in consensus testing across multiple client implementations.

```bash theme={null}
evm t8n \
  --input.alloc=alloc.json \
  --input.txs=txs.json \
  --input.env=env.json \
  --state.fork=Cancun \
  --output.result=result.json \
  --output.alloc=post-alloc.json
```

Pipe output to a second transition to chain blocks:

```bash theme={null}
evm t8n \
  --input.alloc=alloc.json \
  --input.txs=txs.json \
  --input.env=env.json \
  --state.fork=Berlin \
  --output.alloc=stdout \
| evm t8n \
  --input.alloc=stdin \
  --input.txs=txs2.json \
  --input.env=env2.json \
  --state.fork=Berlin
```

<Tip>
  Pass `stdout` or `stderr` as the value for any `--output.*` flag to write that artifact to the corresponding stream instead of a file.
</Tip>

## Transaction validation tool (`evm t9n`)

The `transaction` subcommand (alias `t9n`) validates raw transactions without applying them to state.

```bash theme={null}
evm t9n --state.fork London --input.txs testdata/signed_txs.rlp
```

## Block builder tool (`evm b11r`)

The `block-builder` subcommand (alias `b11r`) assembles a complete block RLP from a header, transactions, and optional ommer/withdrawal data.

```bash theme={null}
evm b11r \
  --input.header=header.json \
  --input.txs=txs.rlp \
  --output.block=block.json
```