Nethereum.DevChain 6.0.0

Nethereum.DevChain

Development blockchain with full EVM execution up to the Prague hardfork, automatic mining, SQLite storage, and extended RPC support. A local Ethereum-compatible chain for testing and development.

Overview

Nethereum.DevChain provides a complete local blockchain environment:

• Instant Mining - Transactions mined immediately or on a configurable interval
• Full EVM Execution - EVM opcode support up to Prague via Nethereum.EVM
• SQLite Storage - Default lightweight storage with auto-cleanup (no native dependencies)
• State Management - Patricia trie-based state with snapshot/revert
• Extended RPC - Development, debug, and Anvil-compatible APIs
• Transaction Tracing - Geth-compatible debug_traceTransaction and debug_traceCall
• Forking - Fork from live Ethereum networks

Installation

dotnet add package Nethereum.DevChain

Dependencies

• Nethereum.CoreChain - Core blockchain infrastructure
• Nethereum.RPC.Extensions - Extended RPC utilities
• Nethereum.JsonRpc.RpcClient - JSON-RPC client
• Nethereum.RPC - Standard debug tracing DTOs
• Microsoft.Data.Sqlite - SQLite storage provider

Quick Start

Default (SQLite with auto-cleanup)

using Nethereum.DevChain;

var node = new DevChainNode();
await node.StartAsync(new[] { "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266" });

// Use the node...

node.Dispose(); // SQLite DB deleted automatically

With Custom Config

var config = new DevChainConfig
{
    ChainId = 1337,
    BlockGasLimit = 30_000_000,
    AutoMine = true,
    InitialBalance = BigInteger.Parse("10000000000000000000000") // 10000 ETH
};

var node = new DevChainNode(config);
await node.StartAsync(fundedAddresses);

Fully In-Memory

var node = DevChainNode.CreateInMemory();
await node.StartAsync(fundedAddresses);

Persistent SQLite

var node = new DevChainNode(DevChainConfig.Default, "./mychain/chain.db", persistDb: true);
await node.StartAsync(fundedAddresses);
// DB survives restart

Custom ChainId

var node = new DevChainNode(new DevChainConfig { ChainId = 31337 });
await node.StartAsync(new[] { "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266" });

Storage Architecture

DevChain uses a hybrid storage strategy by default:

SQLite uses WAL journal mode for concurrent reads during block production. The database is auto-deleted on dispose unless persistence is enabled.

Configuration

DevChainConfig inherits from ChainConfig. Properties like ChainId, BlockGasLimit, BaseFee, and InitialBalance come from the base class.

public class DevChainConfig : ChainConfig
{
    public int ChainId { get; set; } = 1337;
    public long BlockGasLimit { get; set; } = 30_000_000;
    public bool AutoMine { get; set; } = true;
    public long BlockTime { get; set; } = 0;           // 0 = instant
    public int MaxTransactionsPerBlock { get; set; } = 100;
    public BigInteger BaseFee { get; set; } = 1_000_000_000; // 1 gwei
    public BigInteger InitialBalance { get; set; }; // Default: 10000 ETH (BigInteger.Parse("10000000000000000000000"))

    // Forking
    public string ForkUrl { get; set; }
    public long? ForkBlockNumber { get; set; }

    // Auto-mine batching
    public int AutoMineBatchSize { get; set; } = 1;
    public int AutoMineBatchTimeoutMs { get; set; } = 10;
}

// Built-in presets
var config = DevChainConfig.Default;   // ChainId 1337
var config = DevChainConfig.Hardhat;   // ChainId 31337
var config = DevChainConfig.Anvil;     // ChainId 31337

Core Features

Transaction Processing

// Send a signed transaction
var txHash = await node.SendTransactionAsync(signedTransaction);

// Get receipt
var receipt = await node.GetTransactionReceiptAsync(txHash);

// Raw byte sending (eth_sendRawTransaction) is available via the RPC layer

Contract Execution

// Execute without state change (individual parameters)
var result = await node.CallAsync(
    to: contractAddress,
    data: dataBytes,
    from: senderAddress,
    value: null,
    gasLimit: null
);

// eth_call and eth_estimateGas are also available via the RPC layer with CallInput objects

State Access

var balance = await node.GetBalanceAsync(address);
var code = await node.GetCodeAsync(contractAddress);
var storage = await node.GetStorageAtAsync(contractAddress, slot);
var nonce = await node.GetNonceAsync(address);

Account Management

Modify account state for testing:

await node.SetBalanceAsync(address, newBalance);
await node.SetCodeAsync(address, bytecode);
await node.SetStorageAtAsync(address, slot, value);
await node.SetNonceAsync(address, nonce);

Snapshots

// Take snapshot (returns IStateSnapshot)
var snapshot = await node.TakeSnapshotAsync();

// Execute transactions...

// Revert all changes (takes the snapshot object)
await node.RevertToSnapshotAsync(snapshot);

Block Mining

// Manual mining
await node.MineBlockAsync();

// Time manipulation
node.DevConfig.NextBlockTimestamp = DateTimeOffset.UtcNow.AddDays(1).ToUnixTimeSeconds();
await node.MineBlockAsync();

Debug/Trace APIs

debug_traceTransaction

Trace a mined transaction step-by-step:

using Nethereum.CoreChain.Tracing;

var config = new OpcodeTraceConfig
{
    EnableMemory = true,
    DisableStack = false,
    DisableStorage = false,
    EnableReturnData = true,
    Limit = 1000
};

var trace = await node.TraceTransactionAsync(txHash, config);

foreach (var log in trace.StructLogs)
{
    Console.WriteLine($"PC: {log.Pc}, Op: {log.Op}, Gas: {log.Gas}");
}

debug_traceCall

Trace a call without mining, with optional state overrides:

using Nethereum.CoreChain.Tracing;

var stateOverrides = new Dictionary<string, StateOverride>
{
    [address] = new StateOverride
    {
        Balance = "0x1000000000000000000",
        Code = "0x...",
        State = new Dictionary<string, string>
        {
            ["0x0"] = "0x..."
        }
    }
};

var trace = await node.TraceCallAsync(callInput, config, stateOverrides);

RPC Handler Extensions

Register DevChain-specific RPC handlers:

using Nethereum.DevChain.Rpc;
using Nethereum.CoreChain.Rpc;

var registry = new RpcHandlerRegistry();
registry.AddStandardHandlers();  // Core Ethereum methods
registry.AddDevHandlers();       // Dev/debug methods
registry.AddAnvilAliases();      // Anvil compatibility

Development Methods

Account Management Methods

Debug Methods

Anvil Aliases

All hardhat_* methods are also available as anvil_* for compatibility:

Usage with RPC Server

DevChain is typically used with Nethereum.DevChain.Server:

using Nethereum.DevChain;
using Nethereum.DevChain.Rpc;
using Nethereum.CoreChain.Rpc;

var node = new DevChainNode(config);
await node.StartAsync(fundedAddresses);

var registry = new RpcHandlerRegistry();
registry.AddStandardHandlers();
registry.AddDevHandlers();
registry.AddAnvilAliases();

var context = new RpcContext(node, chainId, services);
var dispatcher = new RpcDispatcher(registry, context);

var response = await dispatcher.DispatchAsync(request);

Forking

Fork from live Ethereum networks to test against real state:

var config = new DevChainConfig
{
    ForkUrl = "https://eth.llamarpc.com",
    ForkBlockNumber = 19000000
};

var node = new DevChainNode(config);
await node.StartAsync(fundedAddresses);

// Reads hit fork source on cache miss, writes are local only
var balance = await node.GetBalanceAsync("0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045");

Historical State

DevChain supports querying state at any past block when using HistoricalStateStore:

// State diffs are automatically recorded per block
// Query balance at a specific block
var pastBalance = await node.GetBalanceAsync(address, blockNumber: 5);

Related Packages

• Nethereum.CoreChain - Core blockchain infrastructure and storage interfaces
• Nethereum.DevChain.Server - HTTP JSON-RPC server (dotnet tool)
• Nethereum.Aspire.DevChain - Aspire-orchestrated variant for distributed dev environments
• Nethereum.EVM - EVM simulator
• Nethereum.RPC - Standard debug tracing DTOs

Additional Resources

• Ethereum JSON-RPC Specification
• Geth Debug API
• Nethereum Documentation