Skip to main content

​
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

FlagTypeDefaultDescription
--codestring-Hex-encoded EVM bytecode
--codefilestring-Bytecode file (- for stdin)
--inputstring-Call data (hex)
--inputfilestring-Call data file
--gasuint6410000000000Gas limit
--pricebig.Int0Gas price
--valuebig.Int0Transferred value
--senderaddressdefaultSender address
--receiveraddressdefaultReceiver address
--createboolfalseUse CREATE instead of CALL
--prestatestring-Genesis JSON for state initialization
--debugboolfalseFull trace output
--jsonboolfalseJSON output
--dumpboolfalseDump state after execution
--benchboolfalseRun 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

FlagDefaultDescription
--input.allocstdinPre-state allocation
--input.envstdinBlock environment
--input.txsstdinTransactions
--output.basedir-Output directory
--output.allocalloc.jsonPost-state
--output.resultresult.jsonExecution result
--output.bodybody.rlpBlock body
--state.fork-Fork name
--state.chainid1Chain ID
--state.reward-1Mining reward
--tracefalseJSON 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

FlagDefaultDescription
--input.txsstdinTransaction input
--state.fork-Fork rules
--state.chainid1Chain ID

​
evm block-builder (b11r) Command

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

​
Key Flags

FlagDefaultDescription
--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

FunctionPurpose
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.