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.

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.