👁 Image
Nethereum.CoreChain 6.1.0

Nethereum.CoreChain

Core blockchain infrastructure for state management, block production, transaction processing, and JSON-RPC handling. Provides the foundational components for building local Ethereum nodes and development chains. Supports EVM execution up to the Prague hardfork.

Overview

Nethereum.CoreChain provides:

• Block Production - Create and validate blocks from pending transactions
• State Management - Account state, storage, and trie-based state roots
• Storage Interfaces - Pluggable block, transaction, receipt, log, state, and filter stores
• RPC Framework - Extensible JSON-RPC handler system with dispatcher and registry
• Standard RPC Handlers - Full implementation of Ethereum JSON-RPC methods
• Proof Generation - Merkle proofs for account and storage verification (eth_getProof)
• Forking Support - Fork state from remote RPC endpoints

Installation

dotnet add package Nethereum.CoreChain

Dependencies

• Nethereum.Model
• Nethereum.Merkle.Patricia
• Nethereum.EVM
• Nethereum.Hex
• Nethereum.RPC
• Nethereum.Signer
• Nethereum.Util
• Nethereum.JsonRpc.Client
• Microsoft.Extensions.Logging.Abstractions

Storage Interfaces

CoreChain defines pluggable interfaces for all blockchain data. Implementations include in-memory (built-in), SQLite (Nethereum.DevChain), and RocksDB (Nethereum.CoreChain.RocksDB).

IBlockStore

public interface IBlockStore
{
 Task<BlockHeader> GetByHashAsync(byte[] hash);
 Task<BlockHeader> GetByNumberAsync(BigInteger number);
 Task<BlockHeader> GetLatestAsync();
 Task<BigInteger> GetHeightAsync();
 Task SaveAsync(BlockHeader header, byte[] blockHash);
 Task<bool> ExistsAsync(byte[] hash);
 Task<byte[]> GetHashByNumberAsync(BigInteger number);
 Task UpdateBlockHashAsync(BigInteger blockNumber, byte[] newHash);
 Task DeleteByNumberAsync(BigInteger blockNumber);
}

ITransactionStore

public interface ITransactionStore
{
 Task<ISignedTransaction> GetByHashAsync(byte[] txHash);
 Task<List<ISignedTransaction>> GetByBlockHashAsync(byte[] blockHash);
 Task<List<byte[]>> GetHashesByBlockHashAsync(byte[] blockHash);
 Task<List<ISignedTransaction>> GetByBlockNumberAsync(BigInteger blockNumber);
 Task SaveAsync(ISignedTransaction tx, byte[] blockHash, int txIndex, BigInteger blockNumber);
 Task<TransactionLocation> GetLocationAsync(byte[] txHash);
 Task DeleteByBlockNumberAsync(BigInteger blockNumber);
}

public class TransactionLocation
{
 public byte[] BlockHash { get; set; }
 public BigInteger BlockNumber { get; set; }
 public int TransactionIndex { get; set; }
}

IReceiptStore

public interface IReceiptStore
{
 Task SaveAsync(Receipt receipt, byte[] txHash, byte[] blockHash,
 BigInteger blockNumber, int txIndex, BigInteger gasUsed,
 string contractAddress, BigInteger effectiveGasPrice);
 Task<ReceiptInfo> GetByTxHashAsync(byte[] txHash);
 Task<List<ReceiptInfo>> GetByBlockHashAsync(byte[] blockHash);
 Task<List<ReceiptInfo>> GetByBlockNumberAsync(BigInteger blockNumber);
 Task DeleteByBlockNumberAsync(BigInteger blockNumber);
}

IStateStore

public interface IStateStore
{
 // Account state
 Task<AccountState> GetAccountAsync(string address);
 Task SaveAccountAsync(string address, AccountState state);
 Task<List<string>> GetAllAccountsAsync();

 // Storage slots
 Task<byte[]> GetStorageAsync(string address, byte[] key);
 Task SaveStorageAsync(string address, byte[] key, byte[] value);

 // Code
 Task<byte[]> GetCodeByHashAsync(byte[] codeHash);
 Task SaveCodeAsync(byte[] codeHash, byte[] code);

 // Snapshots
 Task<int> TakeSnapshotAsync();
 Task RevertToSnapshotAsync(int snapshotId);
}

ILogStore

public interface ILogStore
{
 Task SaveLogsAsync(List<Log> logs, byte[] txHash, byte[] blockHash,
 BigInteger blockNumber, int txIndex);
 Task SaveBlockBloomAsync(BigInteger blockNumber, byte[] bloom);
 Task<List<FilteredLog>> GetLogsAsync(LogFilter filter);
 Task<List<FilteredLog>> GetLogsByTxHashAsync(byte[] txHash);
 Task<List<FilteredLog>> GetLogsByBlockHashAsync(byte[] blockHash);
 Task<List<FilteredLog>> GetLogsByBlockNumberAsync(BigInteger blockNumber);
 Task DeleteByBlockNumberAsync(BigInteger blockNumber);
}

In-Memory Implementations

CoreChain provides in-memory implementations for all storage interfaces:

using Nethereum.CoreChain.Storage.InMemory;

var blockStore = new InMemoryBlockStore();
var txStore = new InMemoryTransactionStore(blockStore);
var receiptStore = new InMemoryReceiptStore();
var logStore = new InMemoryLogStore();
var stateStore = new InMemoryStateStore();
var filterStore = new InMemoryFilterStore();
var trieNodeStore = new InMemoryTrieNodeStore();

Block Production

The BlockProducer creates blocks from pending transactions with full EVM execution:

using Nethereum.CoreChain;

var producer = new BlockProducer(
 blockStore, transactionStore, receiptStore,
 logStore, stateStore, trieNodeStore, chainConfig);

var result = await producer.ProduceBlockAsync(pendingTransactions);

// Result contains:
// - Block header with state root, receipts root, transactions root
// - Processed transactions and receipts
// - Gas used and logs bloom

RPC Framework

RpcHandlerRegistry

Central registry for RPC method handlers:

using Nethereum.CoreChain.Rpc;

var registry = new RpcHandlerRegistry();

// Register all standard Ethereum handlers
registry.AddStandardHandlers();

// Register custom handler
registry.Register(new MyCustomHandler());

// Override an existing handler
registry.Override(new MyCustomEthCallHandler());

RpcDispatcher

Routes JSON-RPC requests to registered handlers:

var context = new RpcContext(chainNode, chainId, serviceProvider);
var dispatcher = new RpcDispatcher(registry, context, logger);

// Single request
var response = await dispatcher.DispatchAsync(request);

// Batch request
var responses = await dispatcher.DispatchBatchAsync(requests);

Custom RPC Handler

using Nethereum.CoreChain.Rpc;
using Nethereum.JsonRpc.Client.RpcMessages;

public class MyHandler : RpcHandlerBase
{
 public override string MethodName => "my_method";

 public override async Task<RpcResponseMessage> HandleAsync(
 RpcRequestMessage request, RpcContext context)
 {
 var param = GetParam<string>(request, 0);
 var result = await DoWorkAsync(param, context.Node);
 return Success(request.Id, result);
 }
}

Standard RPC Handlers

CoreChain implements the full Ethereum JSON-RPC specification:

Network

Blocks

Transactions

State

Execution

Gas and Fees

Logs and Filters

Proofs

Chain Node Interface

CoreChain defines the IChainNode interface for chain implementations:

public interface IChainNode
{
 IBlockStore BlockStore { get; }
 ITransactionStore TransactionStore { get; }
 IReceiptStore ReceiptStore { get; }
 IStateStore StateStore { get; }
 ILogStore LogStore { get; }
 IFilterStore FilterStore { get; }
 ITrieNodeStore TrieNodeStore { get; }
 DevChainConfig Config { get; }

 Task<CallResult> CallAsync(CallInput callInput, string blockParameter = "latest");
 Task<BigInteger> EstimateGasAsync(CallInput callInput);
 Task<byte[]> SendRawTransactionAsync(byte[] signedTransaction);
 // ... block, transaction, and state accessors
}

Proof Service

Generate Merkle proofs for state verification:

using Nethereum.CoreChain.Services;

var proofService = new ProofService(stateStore, trieNodeStore);

var proof = await proofService.GetProofAsync(
 address: "0x1234...",
 storageKeys: new[] { "0x0", "0x1" },
 blockNumber: 12345
);

Forking Support

Fork state from a remote chain for local testing:

using Nethereum.CoreChain.State;

var forkingService = new ForkingNodeDataService(
 rpcClient: web3.Client,
 blockNumber: 18000000
);

// Reads fetch from fork source, writes go to local state

Related Packages

• Nethereum.DevChain - Development chain with mining, tracing, and SQLite storage
• Nethereum.DevChain.Server - HTTP JSON-RPC server (dotnet tool)
• Nethereum.CoreChain.RocksDB - RocksDB storage adapter for production use
• Nethereum.EVM - EVM simulator
• Nethereum.Merkle.Patricia - Patricia trie implementation

Additional Resources

• Ethereum JSON-RPC Specification
• Nethereum Documentation