Nethereum.EVM.Contracts

NuGet: Nethereum.EVM.Contracts | Source: src/Nethereum.EVM.Contracts/

Nethereum.EVM.Contracts

Nethereum.EVM.Contracts provides high-level contract simulators built on top of Nethereum.EVM for testing and analyzing smart contract behavior without broadcasting transactions.

Overview

This package offers specialized contract simulators that leverage the EVM execution engine to:

Simulate contract function calls with real blockchain state
Track state changes across transactions
Reverse-engineer contract storage layouts
Validate expected behavior before deployment
Test contract interactions locally

Status: Production - suitable for testing, debugging, simulation, and analysis.

Installation

dotnet add package Nethereum.EVM.Contracts

Features

ERC20 Contract Simulation

Complete ERC20 token operation simulation with:

Transfer simulation with before/after balance tracking
Balance queries using EVM simulation
Storage slot discovery for mapping-based balances
Event log capture from simulated transfers
State verification comparing EVM storage with function calls

Core Components

ERC20ContractSimulator

High-level simulator for ERC20 token contracts. Located in ERC20/ERC20ContractSimulator.cs:19-197.

Constructor:

public ERC20ContractSimulator(
    IWeb3 web3,
    BigInteger chainId,
    string contractAddress,
    byte[] code = null
)

Properties:

Web3 - Web3 instance for RPC access
ChainId - Network chain ID
ContractAddress - ERC20 token contract address

TransferSimulationResult

Result from SimulateTransferAndBalanceStateAsync. Located in ERC20ContractSimulator.cs:35-47.

Properties:

BalanceSenderBefore - Sender balance before transfer
BalanceSenderStorageAfter - Sender balance in storage after transfer
BalanceSenderAfter - Sender balance from balanceOf after transfer
BalanceReceiverBefore - Receiver balance before transfer
BalanceReceiverStorageAfter - Receiver balance in storage after transfer
BalanceReceiverAfter - Receiver balance from balanceOf after transfer
TransferLogs - Event logs emitted during transfer

Usage Examples

Example 1: Simulate ERC20 Transfer

using Nethereum.EVM.Contracts.ERC20;
using Nethereum.Web3;

var web3 = new Web3("https://mainnet.infura.io/v3/YOUR_KEY");

// USDC contract on mainnet
var usdcAddress = "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48";
var simulator = new ERC20ContractSimulator(web3, chainId: 1, usdcAddress);

// Simulate transfer from address1 to address2
var senderAddress = "0x0000000000000000000000000000000000000001";
var receiverAddress = "0x0000000000000000000000000000000000000025";
var amount = 100; // 100 USDC (6 decimals)

var result = await simulator.SimulateTransferAndBalanceStateAsync(
    senderAddress,
    receiverAddress,
    amount
);

Console.WriteLine($"Sender balance before: {result.BalanceSenderBefore}");
Console.WriteLine($"Sender balance after: {result.BalanceSenderAfter}");
Console.WriteLine($"Receiver balance before: {result.BalanceReceiverBefore}");
Console.WriteLine($"Receiver balance after: {result.BalanceReceiverAfter}");

// Verify balance changes
Assert.Equal(result.BalanceSenderAfter, result.BalanceSenderBefore - amount);
Assert.Equal(result.BalanceReceiverAfter, result.BalanceReceiverBefore + amount);

// Check storage consistency
Assert.Equal(result.BalanceSenderStorageAfter, result.BalanceSenderAfter);
Assert.Equal(result.BalanceReceiverStorageAfter, result.BalanceReceiverAfter);

// Inspect transfer logs
foreach (var log in result.TransferLogs)
{
    Console.WriteLine($"Transfer event: {log.Topics[0]}");
}

From test: Erc20EVMContractSimulatorAndStorage.cs:54-67

Example 2: Simulate Balance Query

using Nethereum.EVM.Contracts.ERC20;
using Nethereum.EVM.BlockchainState;
using Nethereum.RPC.Eth.DTOs;
using Nethereum.Web3;

var web3 = new Web3("https://mainnet.infura.io/v3/YOUR_KEY");
var tokenAddress = "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"; // USDC

var simulator = new ERC20ContractSimulator(web3, chainId: 1, tokenAddress);

// Get current block
var blockNumber = await web3.Eth.Blocks.GetBlockNumber.SendRequestAsync();

// Create state service
var nodeDataService = new RpcNodeDataService(
    web3.Eth,
    new BlockParameter(blockNumber)
);
var stateService = new ExecutionStateService(nodeDataService);

// Simulate balance query
var ownerAddress = "0x0000000000000000000000000000000000000001";
var balance = await simulator.SimulateGetBalanceAsync(ownerAddress, stateService);

Console.WriteLine($"Balance of {ownerAddress}: {balance}");

From method: ERC20ContractSimulator.cs:117-133

Example 3: Discover Storage Slot for Balances

This powerful feature reverse-engineers where ERC20 balances are stored by simulating balanceOf and comparing storage values.

using Nethereum.EVM.Contracts.ERC20;
using Nethereum.Web3;

var web3 = new Web3("https://mainnet.infura.io/v3/YOUR_KEY");

// USDC contract
var usdcAddress = "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48";
var simulator = new ERC20ContractSimulator(web3, chainId: 1, usdcAddress);

// Find an address with a non-zero balance
var addressWithBalance = "0x0000000000000000000000000000000000000001";

// Calculate the storage slot where balances are stored
// Tests up to 100 slots by default
var balanceSlot = await simulator.CalculateMappingBalanceSlotAsync(
    addressWithBalance,
    numberOfSlotsToTry: 100
);

Console.WriteLine($"Balance mapping is at storage slot: {balanceSlot}");
// Output: Balance mapping is at storage slot: 9 (for USDC)

From test: Erc20EVMContractSimulatorAndStorage.cs:34-50

Example 4: Direct Transfer Simulation with Custom State

using Nethereum.EVM.Contracts.ERC20;
using Nethereum.EVM.BlockchainState;
using Nethereum.RPC.Eth.DTOs;
using Nethereum.Web3;
using System.Numerics;

var web3 = new Web3("https://mainnet.infura.io/v3/YOUR_KEY");
var tokenAddress = "0xYourTokenAddress";

var simulator = new ERC20ContractSimulator(web3, chainId: 1, tokenAddress);

// Setup state service
var blockNumber = await web3.Eth.Blocks.GetBlockNumber.SendRequestAsync();
var nodeDataService = new RpcNodeDataService(web3.Eth, new BlockParameter(blockNumber));
var stateService = new ExecutionStateService(nodeDataService);

// Simulate transfer
var senderAddress = "0xSenderAddress";
var receiverAddress = "0xReceiverAddress";
var amount = BigInteger.Parse("1000000"); // 1 token (6 decimals)

var programResult = await simulator.SimulateTransferAsync(
    senderAddress,
    receiverAddress,
    amount,
    stateService
);

if (programResult.IsRevert)
{
    Console.WriteLine($"Transfer would revert: {programResult.GetRevertMessage()}");
}
else
{
    Console.WriteLine("Transfer simulation successful");
    Console.WriteLine($"Logs generated: {programResult.Logs.Count}");

    // Inspect Transfer event
    foreach (var log in programResult.Logs)
    {
        if (log.Topics.Length > 0)
        {
            Console.WriteLine($"Event signature: {log.Topics[0]}");
        }
    }
}

From method: ERC20ContractSimulator.cs:96-115

Example 5: Validate Storage Layout

Compare direct storage reads with contract function calls to validate storage layout:

using Nethereum.Contracts.ContractStorage;
using Nethereum.Web3;

var web3 = new Web3("https://mainnet.infura.io/v3/YOUR_KEY");
var tokenAddress = "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"; // USDC

// Get balance via smart contract call
var erc20Service = web3.Eth.ERC20.GetContractService(tokenAddress);
var address = "0x0000000000000000000000000000000000000001";
var balanceFromContract = await erc20Service.BalanceOfQueryAsync(address);

// Get balance from direct storage read (slot 9 for USDC)
var balanceFromStorage = await erc20Service.GetBalanceFromStorageAsync(address, slot: 9);

// Verify they match
Assert.Equal(balanceFromContract, balanceFromStorage);

Console.WriteLine($"Balance from contract call: {balanceFromContract}");
Console.WriteLine($"Balance from storage: {balanceFromStorage}");
Console.WriteLine("Storage layout validated!");

From test: Erc20EVMContractSimulatorAndStorage.cs:72-80

How It Works

Storage Slot Discovery Algorithm

The CalculateMappingBalanceSlotAsync method discovers where balances are stored by: (Located in ERC20ContractSimulator.cs:136-193)

Execute balanceOf via EVM - Simulates the balanceOf(address) call to get expected balance
Capture storage accesses - Tracks all storage slots read during execution
Compare values - Finds storage values matching the returned balance
Calculate slot - For each match, tries slot positions 0-N to calculate mapping key
Validate - Confirms the slot by recalculating keccak256(address || slot)

Example calculation:

// For mapping(address => uint256) balances at slot 9:
// Storage key = keccak256(leftPad32(address) + leftPad32(9))

var storageKey = StorageUtil.CalculateMappingAddressStorageKeyAsBigInteger(
    address,
    slot: 9
);

Transfer Simulation Flow

The SimulateTransferAndBalanceStateAsync method: (Located in ERC20ContractSimulator.cs:59-94)

Query initial balances - Gets sender and receiver balances via RPC
Calculate storage slot - Discovers balance mapping slot (if not known)
Setup EVM state - Creates ExecutionStateService with RPC data source
Simulate transfer - Executes transfer function via EVM simulator
Capture logs - Records Transfer events from execution
Query final balances - Gets updated balances via simulated balanceOf calls
Read storage - Reads balance storage slots directly
Compare results - Validates function results match storage values

Advanced Usage

Custom Contract Code

Provide pre-fetched contract bytecode to avoid RPC calls:

var web3 = new Web3("https://mainnet.infura.io/v3/YOUR_KEY");
var contractAddress = "0xYourContract";

// Fetch bytecode once
var bytecode = await web3.Eth.GetCode.SendRequestAsync(contractAddress);

// Reuse bytecode for multiple simulations
var simulator = new ERC20ContractSimulator(
    web3,
    chainId: 1,
    contractAddress,
    code: bytecode.HexToByteArray()
);

// Multiple simulations without refetching code
var result1 = await simulator.SimulateTransferAndBalanceStateAsync(addr1, addr2, 100);
var result2 = await simulator.SimulateTransferAndBalanceStateAsync(addr3, addr4, 200);

Historical Block Simulation

Simulate at a specific block height:

using Nethereum.Hex.HexTypes;

var web3 = new Web3("https://mainnet.infura.io/v3/YOUR_KEY");
var simulator = new ERC20ContractSimulator(web3, 1, tokenAddress);

// Simulate at specific block
var historicalBlock = new HexBigInteger(18_000_000);
var slot = await simulator.CalculateMappingBalanceSlotAsync(
    address,
    numberOfSlotsToTry: 1000,
    blockNumber: historicalBlock
);

From method: ERC20ContractSimulator.cs:136-143

Gas Estimation Comparison

Compare actual gas with simulated gas:

using Nethereum.Contracts.Standards.ERC20.ContractDefinition;

var web3 = new Web3("https://mainnet.infura.io/v3/YOUR_KEY");
var contractAddress = "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48";

// Estimate gas via RPC
var contractHandler = web3.Eth.GetContractHandler(contractAddress);
var balanceOfFunction = new BalanceOfFunction { Owner = address };
var gasEstimate = await contractHandler.EstimateGasAsync(balanceOfFunction);

Console.WriteLine($"Gas estimate from RPC: {gasEstimate.Value}");

// Simulate with gas tracking
var simulator = new ERC20ContractSimulator(web3, 1, contractAddress);
var blockNumber = await web3.Eth.Blocks.GetBlockNumber.SendRequestAsync();
var nodeDataService = new RpcNodeDataService(web3.Eth, new BlockParameter(blockNumber));
var stateService = new ExecutionStateService(nodeDataService);

var balance = await simulator.SimulateGetBalanceAsync(address, stateService);

// Access trace for gas analysis
// Note: Requires tracing enabled in ExecuteAsync

Use Cases

1. Pre-Transaction Validation

Validate transfers before broadcasting:

var simulator = new ERC20ContractSimulator(web3, 1, tokenAddress);

// Check if transfer would succeed
var result = await simulator.SimulateTransferAndBalanceStateAsync(
    senderAddress,
    receiverAddress,
    amount
);

// Check if the transfer was successful (sufficient balance, no revert)
if (result.BalanceSenderAfter > result.BalanceSenderBefore)
{
    throw new Exception("Unexpected sender balance increase");
}

// Validate expected balance changes
var expectedSenderBalance = result.BalanceSenderBefore - amount;
var expectedReceiverBalance = result.BalanceReceiverBefore + amount;

if (result.BalanceSenderAfter != expectedSenderBalance ||
    result.BalanceReceiverAfter != expectedReceiverBalance)
{
    throw new Exception("Unexpected balance changes");
}

// Validate events
if (!result.TransferLogs.Any(log =>
    log.Topics.Length > 0 &&
    log.Topics[0].ToString() == "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"))
{
    throw new Exception("Missing Transfer event");
}

2. Storage Layout Analysis

Reverse-engineer contract storage for data extraction:

var simulator = new ERC20ContractSimulator(web3, 1, contractAddress);

// Find balance storage slot
var balanceSlot = await simulator.CalculateMappingBalanceSlotAsync(knownAddress);

Console.WriteLine($"Balances stored at slot: {balanceSlot}");

// Now you can directly read any address's balance from storage
var anyAddress = "0xAnyAddress";
var storageKey = StorageUtil.CalculateMappingAddressStorageKeyAsBigInteger(
    anyAddress,
    (ulong)balanceSlot
);

var balanceBytes = await web3.Eth.GetStorageAt.SendRequestAsync(
    contractAddress,
    storageKey.ToHexBigInteger()
);

var balance = new IntTypeDecoder().DecodeBigInteger(balanceBytes);
Console.WriteLine($"Balance of {anyAddress}: {balance}");

3. Testing Contract Upgrades

Test new implementations before deployment:

// Fetch current implementation bytecode
var currentCode = await web3.Eth.GetCode.SendRequestAsync(tokenAddress);
var currentSimulator = new ERC20ContractSimulator(web3, 1, tokenAddress, currentCode.HexToByteArray());

// Simulate with current implementation
var currentResult = await currentSimulator.SimulateTransferAndBalanceStateAsync(addr1, addr2, 100);

// Load new implementation bytecode
var newCode = File.ReadAllBytes("NewImplementation.bin");
var newSimulator = new ERC20ContractSimulator(web3, 1, tokenAddress, newCode);

// Simulate with new implementation
var newResult = await newSimulator.SimulateTransferAndBalanceStateAsync(addr1, addr2, 100);

// Compare results
Assert.Equal(currentResult.BalanceSenderAfter, newResult.BalanceSenderAfter);
Assert.Equal(currentResult.BalanceReceiverAfter, newResult.BalanceReceiverAfter);

4. Multi-Transfer Simulation

Simulate complex transfer sequences:

var simulator = new ERC20ContractSimulator(web3, 1, tokenAddress);
var blockNumber = await web3.Eth.Blocks.GetBlockNumber.SendRequestAsync();
var nodeDataService = new RpcNodeDataService(web3.Eth, new BlockParameter(blockNumber));

// Reuse state service across simulations (preserves state changes)
var stateService = new ExecutionStateService(nodeDataService);

// Simulation 1: A -> B
await simulator.SimulateTransferAsync("0xA", "0xB", 100, stateService);

// Simulation 2: B -> C (uses updated state from simulation 1)
await simulator.SimulateTransferAsync("0xB", "0xC", 50, stateService);

// Simulation 3: C -> A (uses updated state from simulations 1 & 2)
await simulator.SimulateTransferAsync("0xC", "0xA", 25, stateService);

// Query final balances
var balanceA = await simulator.SimulateGetBalanceAsync("0xA", stateService);
var balanceB = await simulator.SimulateGetBalanceAsync("0xB", stateService);
var balanceC = await simulator.SimulateGetBalanceAsync("0xC", stateService);

Dependencies

Required packages:

Nethereum.EVM - EVM simulator engine
Nethereum.Contracts - ERC20 contract definitions and handlers
Nethereum.Web3 - Web3 client for RPC access
Nethereum.ABI - ABI encoding/decoding
Nethereum.RPC - RPC infrastructure

Limitations

Current Limitations

This simulator has the following limitations:

ERC20 Focus - Currently only provides ERC20 simulator (more contract types planned)
Gas Accuracy - Gas calculations may differ slightly from actual execution
Precompiled Contracts - Limited support for precompiled contract interactions
State Consistency - No automatic state revert between simulations
Performance - Slower than native execution (designed for testing, not production)

Storage Slot Discovery Constraints

The CalculateMappingBalanceSlotAsync method:

Requires a non-zero balance at the test address
Tests slots sequentially (can be slow for high slot numbers)
May fail if contract uses non-standard storage layouts
Limited to numberOfSlotsToTry attempts (default 10,000)

Design Scope

Not designed for:

High-frequency simulation requirements (use direct RPC for production)
Consensus-critical operations
Real-time gas estimation (use RPC eth_estimateGas for production)

Source Files Reference

Contract Simulators:

ERC20/ERC20ContractSimulator.cs - ERC20 token simulator

Test Files:

tests/Nethereum.Contracts.IntegrationTests/EVM/Erc20EVMContractSimulatorAndStorage.cs - Integration tests

Future Enhancements

Planned additions:

ERC721 (NFT) contract simulator
ERC1155 (Multi-token) contract simulator
Generic contract simulator with custom ABI
Batch operation simulation
State snapshot and rollback
Parallel simulation support

License

Nethereum is licensed under the MIT License.

Nethereum.EVM - Core EVM simulator
Nethereum.Contracts - Smart contract interaction
Nethereum.Contracts.ContractStorage - Storage utilities
Nethereum.Web3 - Ethereum client library

Support

GitHub: https://github.com/Nethereum/Nethereum
Documentation: https://docs.nethereum.com
Discord: https://discord.gg/jQPrR58FxX

Nethereum.EVM.Contracts

Overview​

Installation​

Features​

ERC20 Contract Simulation​

Core Components​

ERC20ContractSimulator​

TransferSimulationResult​

Usage Examples​

Example 1: Simulate ERC20 Transfer​

Example 2: Simulate Balance Query​

Example 3: Discover Storage Slot for Balances​

Example 4: Direct Transfer Simulation with Custom State​

Example 5: Validate Storage Layout​

How It Works​

Storage Slot Discovery Algorithm​

Transfer Simulation Flow​

Advanced Usage​

Custom Contract Code​

Historical Block Simulation​

Gas Estimation Comparison​

Use Cases​

1. Pre-Transaction Validation​

2. Storage Layout Analysis​

3. Testing Contract Upgrades​

4. Multi-Transfer Simulation​

Dependencies​

Limitations​

Current Limitations​

Storage Slot Discovery Constraints​

Design Scope​

Source Files Reference​

Future Enhancements​

License​

Related Packages​

Support​

Overview

Installation

Features

ERC20 Contract Simulation

Core Components

ERC20ContractSimulator

TransferSimulationResult

Usage Examples

Example 1: Simulate ERC20 Transfer

Example 2: Simulate Balance Query

Example 3: Discover Storage Slot for Balances

Example 4: Direct Transfer Simulation with Custom State

Example 5: Validate Storage Layout

How It Works

Storage Slot Discovery Algorithm

Transfer Simulation Flow

Advanced Usage

Custom Contract Code

Historical Block Simulation

Gas Estimation Comparison

Use Cases

1. Pre-Transaction Validation

2. Storage Layout Analysis

3. Testing Contract Upgrades

4. Multi-Transfer Simulation

Dependencies

Limitations

Current Limitations

Storage Slot Discovery Constraints

Design Scope

Source Files Reference

Future Enhancements

License

Related Packages

Support