> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stablenet.network/llms.txt
> Use this file to discover all available pages before exploring further.

# EVM Testing Tools

## Purpose and Scope

This page describes the testing and debugging tools provided by StableNet for EVM bytecode execution, state transitions, and transaction validation.\
These tools are essential for developers performing smart contract development, consensus rule verification, and transaction execution debugging.

The core tool is the `cmd/evm` utility, which provides multiple subcommands supporting a wide range of testing scenarios.\
This document covers both command-line tools and programmatic testing interfaces.

For more comprehensive testing infrastructure and JSON test fixtures, see\
[Test Framework](/en/development-tools/10.4-testing-framework).

## Command-Line Tool Overview

The `evm` command-line tool provides an isolated execution environment for testing EVM bytecode, transactions, and state transitions without running a full node.\
All commands support various tracing and debugging options.

### Available Commands

* `evm run`
* `evm transition` (`t8n`)
* `evm transaction` (`t9n`)
* `evm block-builder` (`b11r`)
* `evm blocktest`

## evm run Command

The `run` command executes arbitrary EVM bytecode in an isolated environment with configurable state and block context.

### Key Flags

| Flag          | Type    | Default     | Description                           |
| ------------- | ------- | ----------- | ------------------------------------- |
| `--code`      | string  | -           | Hex-encoded EVM bytecode              |
| `--codefile`  | string  | -           | Bytecode file (`-` for stdin)         |
| `--input`     | string  | -           | Call data (hex)                       |
| `--inputfile` | string  | -           | Call data file                        |
| `--gas`       | uint64  | 10000000000 | Gas limit                             |
| `--price`     | big.Int | 0           | Gas price                             |
| `--value`     | big.Int | 0           | Transferred value                     |
| `--sender`    | address | default     | Sender address                        |
| `--receiver`  | address | default     | Receiver address                      |
| `--create`    | bool    | false       | Use CREATE instead of CALL            |
| `--prestate`  | string  | -           | Genesis JSON for state initialization |
| `--debug`     | bool    | false       | Full trace output                     |
| `--json`      | bool    | false       | JSON output                           |
| `--dump`      | bool    | false       | Dump state after execution            |
| `--bench`     | bool    | false       | Run benchmark                         |

### Execution Process

`runCmd` orchestrates execution in the following order:

1. Initialize StateDB with genesis or an empty state
2. Load bytecode (`--code`, `--codefile`, or positional argument)
3. Set up sender and receiver accounts
4. Configure `runtime.Config` with gas, price, and block context
5. Execute one of `Execute`, `Call`, or `Create`
6. Output execution result, gas usage, and optional traces

## evm transition (t8n) Command

The `transition` command implements the Ethereum state transition function, applying a set of transactions to a pre-state and producing a post-state.\
It is a core tool for validating consensus-level transaction processing.

### Input Formats

`t8n` requires the following three inputs:

* **alloc.json**: Pre-state account allocation
* **env.json**: Block environment information
* **txs.json** or `txs.rlp`: Transaction list

### Output Formats

* **alloc.json**: Post-state
* **result.json**: Execution results
* **body.rlp**: Block body (optional)

### Key Flags

| Flag               | Default     | Description          |
| ------------------ | ----------- | -------------------- |
| `--input.alloc`    | stdin       | Pre-state allocation |
| `--input.env`      | stdin       | Block environment    |
| `--input.txs`      | stdin       | Transactions         |
| `--output.basedir` | -           | Output directory     |
| `--output.alloc`   | alloc.json  | Post-state           |
| `--output.result`  | result.json | Execution result     |
| `--output.body`    | body.rlp    | Block body           |
| `--state.fork`     | -           | Fork name            |
| `--state.chainid`  | 1           | Chain ID             |
| `--state.reward`   | -1          | Mining reward        |
| `--trace`          | false       | JSON trace           |
| `--trace.tracer`   | -           | Custom tracer        |

### Fork Configuration

`--state.fork` specifies the consensus rules to apply.

* `Frontier`, `Homestead`, `EIP150`, `EIP158`
* `Byzantium`, `Constantinople`, `Istanbul`
* `Berlin`, `London`, `Shanghai`, `Cancun`
* `Anzeon` (StableNet-specific)

Additional EIPs can be specified in the form `London+3855+3860`.

### Environment Validation Rules

Required fields are validated depending on the active fork.

* London: `currentBaseFee` or `parentBaseFee` required
* Shanghai: `withdrawals` required
* Merge: `currentRandom` required, difficulty must be 0
* Cancun: `parentBeaconBlockRoot` required

## evm transaction (t9n) Command

The `t9n` command validates transaction encoding and signature recovery without executing the transaction.

### Validation Items

1. Whether RLP decoding succeeds
2. Sender recovery via ECDSA signature
3. Compliance with fork-specific validation rules

### Key Flags

| Flag              | Default | Description       |
| ----------------- | ------- | ----------------- |
| `--input.txs`     | stdin   | Transaction input |
| `--state.fork`    | -       | Fork rules        |
| `--state.chainid` | 1       | Chain ID          |

## evm block-builder (b11r) Command

The `block-builder` command constructs a complete block from transactions, ommers, and withdrawals.

### Key Flags

| Flag                  | Default | Description        |
| --------------------- | ------- | ------------------ |
| `--input.header`      | -       | Header template    |
| `--input.txs`         | -       | Transaction RLP    |
| `--input.ommers`      | -       | Uncle headers      |
| `--input.withdrawals` | -       | Withdrawal list    |
| `--output.block`      | -       | Output block RLP   |
| `--seal.clique`       | -       | Clique signing key |

## evm blocktest Command

`blocktest` executes blockchain tests in JSON format to validate block validity and state transitions.\
The test structure and execution logic follow the same rules as the test framework.

## Integration with the Test Framework

The `evm` tool internally reuses the execution logic from the `tests` package.

### Key Test Functions

| Function                  | Purpose                      |
| ------------------------- | ---------------------------- |
| `StateTest.Run()`         | Execute State tests          |
| `StateTest.RunNoVerify()` | Execute without verification |
| `BlockTest.Run()`         | Execute Block tests          |
| `TransactionTest.Run()`   | Validate transactions        |
| `MakePreState()`          | Create pre-state             |
| `GetChainConfig()`        | Parse fork configuration     |

## EVM Runtime Package

The `core/vm/runtime` package provides a programmatic interface for executing the EVM without blockchain infrastructure.

### Default Behavior

`runtime.Config` provides reasonable defaults.

* All hard forks enabled
* Difficulty 0 (post-merge)
* Maximum GasLimit
* BaseFee 1 gwei
* BlobBaseFee 1 wei

### State Preparation Steps

Before execution, the following steps are performed:

1. Access list warm-up (post-Berlin)
2. Transient storage initialization (EIP-1153)
3. Precompile address warm-up
4. Transaction-related address warm-up

## Test Workflow Summary

EVM testing tools are typically used in the following workflow:

1. Single bytecode testing (`evm run`)
2. Consensus rule validation (`evm transition`)
3. Transaction format validation (`evm transaction`)
4. Block construction and validation (`evm block-builder`, `evm blocktest`)

This allows precise validation of EVM and consensus logic without running a full node.