juanblanco/Nethereum.Gethv5.8.0
✓ Verified.NET FW4.5.1.NET FW4.6.1.NET 6.0.NET 8.0
Netherum.Geth is the extended Web3 library for Geth. including the non-generic RPC API client methods to interact with the Go Ethereum Client (Geth) Admin, Debug, Miner.
Get Started
$ dotnet add package Nethereum.GethReadme
Nethereum.Geth
Extended Web3 library for Go Ethereum (Geth) client. Provides RPC client methods for Admin, Debug, Miner, TxnPool, and Geth-specific Eth APIs.
Overview
Nethereum.Geth extends Nethereum.Web3 with Geth-specific JSON-RPC methods. Use Web3Geth instead of Web3 to access additional APIs for node administration, transaction tracing, mining control, and mempool inspection.
API Services:
- Admin - Peer management, RPC/HTTP/WS server control, chain import/export
- Debug - Transaction and block tracing, profiling, memory/garbage collection stats
- Miner - Mining control (start, stop, set gas price)
- TxnPool - Transaction pool inspection (status, content)
- GethEth - Geth-specific eth methods (pending transactions, eth_call with state overrides)
Installation
dotnet add package Nethereum.Geth
Or via Package Manager Console:
Install-Package Nethereum.Geth
Dependencies
Package References:
- Nethereum.RPC
- Nethereum.Web3
Usage
Web3Geth Initialization
Replace Web3 with Web3Geth:
using Nethereum.Geth;
var web3 = new Web3Geth("http://localhost:8545");
With account:
using Nethereum.Geth;
using Nethereum.Web3.Accounts;
var account = new Account("PRIVATE_KEY");
var web3 = new Web3Geth(account, "http://localhost:8545");
From: src/Nethereum.Geth/Web3Geth.cs:10
Admin API
Manage node peers, RPC/HTTP/WS servers, and chain data.
Check Connected Peers
var peers = await web3.Admin.Peers.SendRequestAsync();
Console.WriteLine($"Connected peers: {peers.Count}");
From: tests/Nethereum.Geth.IntegrationTests/Testers/AdminPeersTester.cs:18
Add Peer
var enode = "enode://pubkey@ip:port";
var result = await web3.Admin.AddPeer.SendRequestAsync(enode);
From: src/Nethereum.Geth/RPC/Admin/AdminAddPeer.cs
Get Node Info
var nodeInfo = await web3.Admin.NodeInfo.SendRequestAsync();
From: src/Nethereum.Geth/IAdminApiService.cs:16
Start/Stop RPC Server
// Start RPC server
var started = await web3.Admin.StartRPC.SendRequestAsync("localhost", 8545, "*", "web3,eth,net");
// Stop RPC server
var stopped = await web3.Admin.StopRPC.SendRequestAsync();
From: src/Nethereum.Geth/IAdminApiService.cs:17-19
Export/Import Chain
// Export chain to file
var exported = await web3.Admin.ExportChain.SendRequestAsync("/path/to/export.rlp");
// Import chain from file
var imported = await web3.Admin.ImportChain.SendRequestAsync("/path/to/chain.rlp");
From: src/Nethereum.Geth/IAdminApiService.cs:13-14
Debug API
Transaction and block tracing, profiling, memory statistics.
Trace Transaction
using Nethereum.Geth.RPC.Debug.DTOs;
using Newtonsoft.Json.Linq;
var txHash = "0x...";
var tracingOptions = new TracingOptions();
var trace = await web3.GethDebug.TraceTransaction.SendRequestAsync<JToken>(txHash, tracingOptions);
From: tests/Nethereum.Geth.IntegrationTests/Testers/DebugTraceTransactionTester.cs:36
Trace Transaction with Tracers
Geth supports built-in tracers for structured transaction analysis.
Call Tracer:
using Nethereum.Geth.RPC.Debug.Tracers;
var trace = await web3.GethDebug.TraceTransaction.SendRequestAsync<CallTracerResponse>(
txHash,
new TracingOptions
{
Timeout = "1m",
Reexec = 128,
TracerInfo = new CallTracerInfo(onlyTopCalls: false, withLogs: true)
});
From: tests/Nethereum.Geth.IntegrationTests/Testers/DebugTraceTransactionTester.cs:75
4Byte Tracer (function selector frequency):
var trace = await web3.GethDebug.TraceTransaction.SendRequestAsync<FourByteTracerResponse>(
txHash,
new TracingOptions
{
Timeout = "1m",
Reexec = 128,
TracerInfo = new FourByteTracerInfo()
});
From: tests/Nethereum.Geth.IntegrationTests/Testers/DebugTraceTransactionTester.cs:89
Opcode Tracer (EVM opcode execution):
var trace = await web3.GethDebug.TraceTransaction.SendRequestAsync<OpcodeTracerResponse>(
txHash,
new TracingOptions
{
Timeout = "1m",
Reexec = 128,
TracerInfo = new OpcodeTracerInfo(
enableMemory: true,
disableStack: false,
disableStorage: false,
enableReturnData: true,
debug: false,
limit: 10)
});
From: tests/Nethereum.Geth.IntegrationTests/Testers/DebugTraceTransactionTester.cs:166
Prestate Tracer (account state before execution):
// Prestate mode
var prestateTrace = await web3.GethDebug.TraceTransaction.SendRequestAsync<PrestateTracerResponsePrestateMode>(
txHash,
new TracingOptions
{
Timeout = "1m",
Reexec = 128,
TracerInfo = new PrestateTracerInfo(diffMode: false)
});
// Diff mode
var diffTrace = await web3.GethDebug.TraceTransaction.SendRequestAsync<PrestateTracerResponseDiffMode>(
txHash,
new TracingOptions
{
Timeout = "1m",
Reexec = 128,
TracerInfo = new PrestateTracerInfo(diffMode: true)
});
From: tests/Nethereum.Geth.IntegrationTests/Testers/DebugTraceTransactionTester.cs:180
Additional Tracers:
UnigramTracerInfo- Opcode frequency (single opcodes)BigramTracerInfo- Opcode pairs frequencyTrigramTracerInfo- Opcode triples frequencyOpcountTracerInfo- Total opcode count
From: tests/Nethereum.Geth.IntegrationTests/Testers/DebugTraceTransactionTester.cs:115-140
Trace Block
var blockNumber = new Nethereum.Hex.HexTypes.HexBigInteger(12345);
var blockTrace = await web3.GethDebug.TraceBlockByNumber.SendRequestAsync(blockNumber, tracingOptions);
From: src/Nethereum.Geth/IDebugApiService.cs:25
Custom JavaScript Tracer
var customTracerCode = @"{
data: [],
fault: function(log) {},
step: function(log) { this.data.push(log.op.toString()); },
result: function() { return this.data; }
}";
var trace = await web3.GethDebug.TraceTransaction.SendRequestAsync<JToken>(
txHash,
new TracingOptions
{
Timeout = "1m",
Reexec = 128,
TracerInfo = new CustomTracerInfo(customTracerCode)
});
From: tests/Nethereum.Geth.IntegrationTests/Testers/DebugTraceTransactionTester.cs:205
Get Memory Stats
var memStats = await web3.GethDebug.MemStats.SendRequestAsync();
From: src/Nethereum.Geth/IDebugApiService.cs:14
Get Block RLP
var blockNumber = new Nethereum.Hex.HexTypes.HexBigInteger(100);
var rlp = await web3.GethDebug.GetBlockRlp.SendRequestAsync(blockNumber);
From: src/Nethereum.Geth/IDebugApiService.cs:12
CPU Profiling
// Start CPU profiling
await web3.GethDebug.StartCPUProfile.SendRequestAsync("/path/to/profile.prof");
// Stop profiling
await web3.GethDebug.StopCPUProfile.SendRequestAsync();
From: src/Nethereum.Geth/IDebugApiService.cs:19-21
Miner API
Control mining operations.
Start Mining
// Start with 1 thread (argument is optional, default is 1)
var result = await web3.Miner.Start.SendRequestAsync();
From: tests/Nethereum.Geth.IntegrationTests/Testers/MinerStartTester.cs:16
Stop Mining
var result = await web3.Miner.Stop.SendRequestAsync();
From: src/Nethereum.Geth/RPC/Miner/MinerStop.cs
Set Gas Price
using Nethereum.Hex.HexTypes;
var gasPrice = new HexBigInteger(1000000000); // 1 gwei
var result = await web3.Miner.SetGasPrice.SendRequestAsync(gasPrice);
From: src/Nethereum.Geth/RPC/Miner/MinerSetGasPrice.cs
TxnPool API
Inspect transaction pool (mempool).
Get Pool Status
var status = await web3.TxnPool.PoolStatus.SendRequestAsync();
From: src/Nethereum.Geth/ITxnPoolApiService.cs:9
Get Pool Content
var content = await web3.TxnPool.PoolContent.SendRequestAsync();
From: src/Nethereum.Geth/ITxnPoolApiService.cs:7
Inspect Pool
var inspect = await web3.TxnPool.PoolInspect.SendRequestAsync();
From: src/Nethereum.Geth/ITxnPoolApiService.cs:8
GethEth API
Geth-specific eth methods.
Get Pending Transactions
var pendingTxs = await web3.GethEth.PendingTransactions.SendRequestAsync();
From: src/Nethereum.Geth/IGethEthApiService.cs:7
eth_call with State Overrides
Execute contract call with temporary state modifications (e.g., replace contract code, override balances).
using Nethereum.RPC.Eth.DTOs;
using System.Collections.Generic;
var stateChanges = new Dictionary<string, StateChange>
{
["0xContractAddress"] = new StateChange
{
Code = "0x6080604052..." // Override contract code
}
};
var result = await web3.GethEth.Call.SendRequestAsync(
new CallInput
{
To = "0xContractAddress",
Data = "0x893d20e8" // Function selector
},
BlockParameter.CreateLatest(),
stateChanges);
From: tests/Nethereum.Contracts.IntegrationTests/SmartContracts/GethCallTest.cs:39
VM Stack Error Checking
Analyze VM execution traces for errors.
var stackErrorChecker = web3.GethDebug.StackErrorChecker;
// Use with trace results to detect stack errors
From: src/Nethereum.Geth/IDebugApiService.cs:17
Admin API Service
Interface: IAdminApiService (src/Nethereum.Geth/IAdminApiService.cs:5)
| Method | RPC Method | Description |
|---|---|---|
| AddPeer | admin_addPeer | Add peer by enode URL |
| RemovePeer | admin_removePeer | Remove peer |
| AddTrustedPeer | admin_addTrustedPeer | Add trusted peer |
| RemoveTrustedPeer | admin_removeTrustedPeer | Remove trusted peer |
| Peers | admin_peers | List connected peers |
| NodeInfo | admin_nodeInfo | Get node information |
| Datadir | admin_datadir | Get data directory path |
| StartRPC | admin_startRPC | Start RPC server |
| StopRPC | admin_stopRPC | Stop RPC server |
| StartHTTP | admin_startHTTP | Start HTTP server |
| StopHTTP | admin_stopHTTP | Stop HTTP server |
| StartWS | admin_startWS | Start WebSocket server |
| StopWS | admin_stopWS | Stop WebSocket server |
| ExportChain | admin_exportChain | Export blockchain to file |
| ImportChain | admin_importChain | Import blockchain from file |
Debug API Service
Interface: IDebugApiService (src/Nethereum.Geth/IDebugApiService.cs:5)
| Method | RPC Method | Description |
|---|---|---|
| TraceTransaction | debug_traceTransaction | Trace transaction execution |
| TraceBlock | debug_traceBlock | Trace all transactions in block |
| TraceBlockByNumber | debug_traceBlockByNumber | Trace block by number |
| TraceBlockByHash | debug_traceBlockByHash | Trace block by hash |
| TraceBlockFromFile | debug_traceBlockFromFile | Trace block from RLP file |
| TraceCall | debug_traceCall | Trace eth_call execution |
| GetBlockRlp | debug_getBlockRlp | Get RLP-encoded block |
| DumpBlock | debug_dumpBlock | Dump block state |
| SeedHash | debug_seedHash | Get PoW seed hash |
| BacktraceAt | debug_backtraceAt | Set logging backtrace location |
| Verbosity | debug_verbosity | Set logging verbosity |
| Vmodule | debug_vmodule | Set per-module verbosity |
| Stacks | debug_stacks | Get goroutine stack traces |
| MemStats | debug_memStats | Get memory allocation statistics |
| GcStats | debug_gcStats | Get garbage collection statistics |
| CpuProfile | debug_cpuProfile | Write CPU profile |
| StartCPUProfile | debug_startCPUProfile | Start CPU profiling |
| StopCPUProfile | debug_stopCPUProfile | Stop CPU profiling |
| StartGoTrace | debug_startGoTrace | Start Go execution trace |
| StopGoTrace | debug_stopGoTrace | Stop Go execution trace |
| BlockProfile | debug_blockProfile | Write goroutine blocking profile |
| SetBlockProfileRate | debug_setBlockProfileRate | Set blocking profile rate |
| GoTrace | debug_goTrace | Write Go execution trace |
Miner API Service
Interface: IMinerApiService (src/Nethereum.Geth/IMinerApiService.cs:5)
| Method | RPC Method | Description |
|---|---|---|
| Start | miner_start | Start mining |
| Stop | miner_stop | Stop mining |
| SetGasPrice | miner_setGasPrice | Set minimum gas price |
TxnPool API Service
Interface: ITxnPoolApiService (src/Nethereum.Geth/ITxnPoolApiService.cs:5)
| Method | RPC Method | Description |
|---|---|---|
| PoolStatus | txpool_status | Get transaction pool status (pending/queued counts) |
| PoolContent | txpool_content | Get full transaction pool content |
| PoolInspect | txpool_inspect | Get transaction pool summary |
GethEth API Service
Interface: IGethEthApiService (src/Nethereum.Geth/IGethEthApiService.cs:5)
| Method | RPC Method | Description |
|---|---|---|
| PendingTransactions | eth_pendingTransactions | Get pending transactions |
| Call | eth_call | Execute call with state overrides |
Related Packages
- Nethereum.Web3 - Base Web3 implementation
- Nethereum.RPC - JSON-RPC client infrastructure
- Nethereum.Besu - Hyperledger Besu-specific APIs
- Nethereum.Parity - OpenEthereum/Parity-specific APIs