evm-simulation

EVM Simulation — Nethereum.EVM

The Nethereum EVM simulator is a full in-process Ethereum Virtual Machine that executes bytecode locally against real blockchain state. It powers the wallet transaction preview, DevChain, CoreChain, and the Solidity debugger.

When to Use This

• Transaction preview: Simulate a transaction to see all balance changes (ETH, ERC-20, NFT) before signing
• Call tree decoding: Understand which contracts and functions are called during a complex transaction
• Event extraction: Get all events emitted and consolidate token transfers into net balance changes
• Revert debugging: Decode why a transaction failed — custom errors, require messages, panic codes
• ERC-20 testing: Simulate token transfers, approvals, and detect fee-on-transfer tokens
• Bytecode analysis: Execute, debug, or disassemble EVM bytecode
• Source-level debugging: Step through execution with Solidity source maps

Required Packages

dotnet add package Nethereum.EVM          # Core simulator, executor, decoder, extractor
dotnet add package Nethereum.EVM.Contracts # ERC-20 contract simulator
dotnet add package Nethereum.Web3          # RPC connection for blockchain state

The Transaction Simulation Pipeline

This is the primary pattern — simulate a transaction and extract all state changes:

using Nethereum.EVM;
using Nethereum.EVM.BlockchainState;
using Nethereum.EVM.Decoding;
using Nethereum.EVM.Execution;
using Nethereum.EVM.StateChanges;
using Nethereum.Hex.HexConvertors.Extensions;
using Nethereum.RPC.Eth.DTOs;
using Nethereum.Web3;
using System.Numerics;

// 1. Connect to blockchain state
var web3 = new Web3("https://mainnet.infura.io/v3/YOUR_KEY");
var blockNumber = await web3.Eth.Blocks.GetBlockNumber.SendRequestAsync();
var block = await web3.Eth.Blocks.GetBlockWithTransactionsHashesByNumber
    .SendRequestAsync(blockNumber);

var nodeDataService = new RpcNodeDataService(web3.Eth, new BlockParameter(blockNumber));
var executionState = new ExecutionStateService(nodeDataService);

// 2. Build execution context
var ctx = new TransactionExecutionContext
{
    Mode = ExecutionMode.Call,           // Simulate without gas payment
    Sender = "0xYourAddress",
    To = "0xContractAddress",
    Data = calldata.HexToByteArray(),    // ABI-encoded function call
    GasLimit = 10_000_000,
    Value = BigInteger.Zero,
    GasPrice = block.BaseFeePerGas.Value + 1_000_000_000,
    MaxFeePerGas = block.BaseFeePerGas.Value + 1_000_000_000,
    MaxPriorityFeePerGas = 1_000_000_000,
    Nonce = BigInteger.Zero,
    IsEip1559 = true,
    IsContractCreation = false,
    BlockNumber = (long)blockNumber.Value,
    Timestamp = (long)block.Timestamp.Value,
    BaseFee = block.BaseFeePerGas.Value,
    Coinbase = "0x0000000000000000000000000000000000000000",
    BlockGasLimit = 30_000_000,
    ExecutionState = executionState,
    TraceEnabled = true
};

// 3. Execute
var executor = new TransactionExecutor(HardforkConfig.Default);
var execResult = await executor.ExecuteAsync(ctx);

// 4. Decode call tree and events
var decoder = new ProgramResultDecoder(abiStorage); // IABIInfoStorage
var decoded = decoder.Decode(execResult, callInput, chainId);

// 5. Extract balance changes
var extractor = new StateChangesExtractor();
var stateChanges = extractor.ExtractFromDecodedResult(
    decoded, executionState, "0xCurrentUserAddress");

// Check results
if (execResult.Success)
{
    Console.WriteLine(stateChanges.ToSummaryString());
    foreach (var change in stateChanges.BalanceChanges)
    {
        Console.WriteLine(
quot;{change.Address}: {change.Change} ({change.Type})");
    }
}
else
{
    Console.WriteLine(
quot;Would revert: {decoded.RevertReason?.GetDisplayMessage()}");
}

Key Classes

Decoding Call Trees

var decoded = decoder.Decode(execResult, callInput, chainId);

// Walk the call tree
void PrintCallTree(DecodedCall call, int indent = 0)
{
    var prefix = new string(' ', indent * 2);
    Console.WriteLine(
quot;{prefix}{call.CallType}: {call.GetDisplayName()} (gas: {call.GasUsed})");
    if (call.InputParameters != null)
        foreach (var p in call.InputParameters)
            Console.WriteLine(
quot;{prefix}  {p.Parameter.Name}: {p.Result}");
    if (call.InnerCalls != null)
        foreach (var inner in call.InnerCalls)
            PrintCallTree(inner, indent + 1);
}
PrintCallTree(decoded.RootCall);

Decoding Reverts

if (!execResult.Success)
{
    var decoded = decoder.Decode(execResult, callInput, chainId);
    if (decoded.RevertReason != null)
    {
        Console.WriteLine(
quot;Error: {decoded.RevertReason.GetErrorName()}");
        Console.WriteLine(
quot;Message: {decoded.RevertReason.GetDisplayMessage()}");
        if (decoded.RevertReason.Parameters != null)
            foreach (var p in decoded.RevertReason.Parameters)
                Console.WriteLine(
quot;  {p.Parameter.Name}: {p.Result}");
    }
}

Bytecode Execution

using Nethereum.EVM;
using Nethereum.Hex.HexConvertors.Extensions;

var bytecode = "6004600401".HexToByteArray(); // PUSH1 4, PUSH1 4, ADD
var vm = new EVMSimulator();
var program = new Program(bytecode);
await vm.ExecuteAsync(program, traceEnabled: true);

var result = program.StackPeek(); // 0x08
foreach (var trace in program.Trace)
    Console.WriteLine(
quot;{trace.Instruction?.Instruction} Gas:{trace.GasCost}");

Bytecode Disassembly

var disassembly = ProgramInstructionsUtils.DisassembleToString(bytecodeHex);
// "0000   60   PUSH1  0x80\n0002   60   PUSH1  0x40\n..."

var instructions = ProgramInstructionsUtils.GetProgramInstructions(bytecodeHex);
bool hasTransfer = ProgramInstructionsUtils.ContainsFunctionSignature(
    instructions, "0xa9059cbb"); // transfer(address,uint256)

ExecutionMode

• ExecutionMode.Call — simulates without gas payment (like eth_call)
• ExecutionMode.Transaction — full execution with gas payment validation

HardforkConfig

• HardforkConfig.Cancun — EIP-4844 only, 6 blobs, precompiles 1-10
• HardforkConfig.Prague — All EIPs (4844, 7623, 7702), 9 blobs, precompiles 1-17
• HardforkConfig.Default — Same as Prague

Balance Change Types

Validation Statuses

BalanceValidationStatus: NotValidated, Verified, FeeOnTransfer, Rebasing, OwnerMismatch, Mismatch

For full documentation, see: https://docs.nethereum.com/docs/evm-simulator/overview