Nethereum.Explorer 6.0.4

Nethereum.Explorer

Blazor Server blockchain explorer Razor Class Library for Ethereum-compatible chains with indexed storage, ABI decoding, EVM debugging, and wallet interaction.

Overview

Nethereum.Explorer is a Razor Class Library (RCL) that provides a complete blockchain explorer UI as embeddable Blazor Server components. It reads from an indexed PostgreSQL database populated by a separate blockchain processor, and optionally connects to a live RPC endpoint for balance queries and contract interaction.

The Explorer is designed for progressive integration: at minimum it requires a blockchain storage database, and optionally adds token indexing, MUD World browsing, EVM debugging, and live RPC features as additional dependencies are registered.

Key Features

• Indexed block, transaction, account, contract, and log browsing with pagination and CSV export
• ABI decoding of function inputs, event logs, and revert errors via configurable source chain (Sourcify, Etherscan, 4Byte, local filesystem)
• Contract interaction via EIP-6963 browser wallet (read functions without wallet, write functions with wallet connection)
• EVM debugger with opcode-level step-through, Solidity source mapping, memory/stack/storage inspection
• Internal transactions from indexed database with decoded call data and errors
• Token views for ERC-20/721/1155 balances, NFT inventory, and transfer history (requires token indexing repositories)
• MUD World browser with raw, decoded, and normalised SQL record views (requires MUD Postgres repositories)
• Dark/light theme with persistent toggle (localStorage)
• Localisation with English and Spanish translations, switchable from the navbar
• Search with address, transaction hash, block number, and ENS name resolution
• Add chain to wallet via EIP-6963 wallet provider from the home page

Installation

dotnet add package Nethereum.Explorer

Requires net10.0. Uses EF Core 10 and MapStaticAssets().

Dependencies

• Nethereum.BlockchainStore.EFCore - IBlockchainDbContextFactory for indexed block/transaction/log/contract queries
• Nethereum.BlockchainProcessing - Block storage entity models and repository interfaces
• Nethereum.Blazor - EIP-6963 wallet interop and EthereumAuthenticationStateProvider
• Nethereum.Blazor.Solidity - EVM debugger components, Solidity code viewer, and debug service registration
• Nethereum.DataServices - ABI info storage implementations (Sourcify, Etherscan, 4Byte)
• Nethereum.Web3 - JSON-RPC client for live RPC queries
• Nethereum.Mud.Repositories.EntityFramework - MUD store record DB sets interface

Integration

Minimum Setup (Indexed Storage)

Requires Nethereum.BlockchainStore.Postgres to provide IBlockchainDbContextFactory. This enables block, transaction, account, contract, and log browsing from indexed data.

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorComponents()
    .AddInteractiveServerComponents();

builder.Services.AddPostgresBlockchainStorage(connectionString);
builder.Services.AddExplorerServices(builder.Configuration);

var app = builder.Build();

app.UseRateLimiter();
app.UseAntiforgery();
app.MapStaticAssets();
app.MapRazorComponents<Nethereum.Explorer.Components.App>()
    .AddInteractiveServerRenderMode()
    .AddAdditionalAssemblies(
        typeof(Nethereum.Blazor.EIP6963WalletInterop.EIP6963WalletBlazorInterop).Assembly);

app.MapTokenApiEndpoints();
app.MapContractApiEndpoints();

app.Run();

The database must be populated by a separate blockchain processor/indexer. Without indexed data, pages will be empty.

Adding Token Indexing

Register Nethereum.BlockchainStorage.Token.Postgres to enable token balances, NFT inventory, and transfer history pages. The Explorer checks at runtime for ITokenBalanceRepository, INFTInventoryRepository, ITokenTransferLogRepository, and ITokenMetadataRepository. If all four are present, TokenExplorerService is used. If any are missing, NullTokenExplorerService is registered instead (returns empty results, IsAvailable = false).

builder.Services.AddPostgresBlockchainStorage(connectionString);
builder.Services.AddTokenPostgresRepositories(connectionString);
builder.Services.AddExplorerServices(builder.Configuration);

Adding MUD World Browser

Register Nethereum.Mud.Repositories.Postgres to enable MUD World record browsing. The MudExplorerService checks for IMudStoreRecordsDbSets at runtime; if null, IsAvailable returns false and MUD pages show empty state.

builder.Services.AddDbContext<MudPostgresStoreRecordsDbContext>(options =>
    options.UseNpgsql(connectionString).UseLowerCaseNamingConvention());

builder.Services.AddScoped<IMudStoreRecordsDbSets>(sp =>
    sp.GetRequiredService<MudPostgresStoreRecordsDbContext>());

builder.Services.AddTransient<INormalisedTableQueryService>(sp =>
{
    var conn = new NpgsqlConnection(connectionString);
    var logger = sp.GetService<ILogger<NormalisedTableQueryService>>();
    return new NormalisedTableQueryService(conn, logger);
});

Adding RPC

Configure an RPC endpoint to enable live balance/nonce queries, contract interaction, state diffs, and pending transactions.

The ExplorerWeb3Factory resolves the RPC URL in this order:

1. ExplorerOptions.RpcUrl (from Explorer:RpcUrl in configuration)
2. ConnectionStrings:devchain

{
  "Explorer": {
    "RpcUrl": "http://localhost:8545"
  }
}

Without RPC, account pages show only database-stored state and contract write functions are unavailable.

Pages

UI Features

Search

The search bar in the navbar resolves multiple input types:

• Block number - numeric input navigates to block detail
• Transaction hash - 66-character hex string navigates to transaction detail
• Address - 42-character hex string navigates to account detail
• ENS name - .eth domain names are resolved via ENS registry when RPC is available

Recent searches are tracked per session and shown in a dropdown for quick access.

Theme

A dark/light theme toggle is available in the navbar. The selected theme persists to localStorage under the key explorer-theme. All components including the Monaco editor (used by the EVM debugger) adapt to the selected theme.

Localisation

The Explorer supports English (en) and Spanish (es) via the ExplorerLocalizer service. A language selector dropdown in the navbar allows switching at runtime. All page titles, labels, table headers, error messages, and empty states are localised.

EVM Debugger

The transaction detail page includes a "Debug" button (when EnableEvmDebugger is true and RPC is available) that navigates to a full EVM debugger:

• Replays the transaction via debug_traceTransaction with an opcode tracer
• Displays opcodes grouped by function with call depth indentation
• Highlights the corresponding Solidity source line when source maps are available (via Sourcify or AbiSources.SourceBasePath)
• Inspects memory, stack, and storage at each execution step
• Shows gas cost per instruction and call information (target contract, function selector)
• Supports filtering to show only calls, events, and storage operations

Wallet Integration

The Explorer uses EIP-6963 for browser wallet discovery. When a wallet is connected:

• Write functions on the contract detail page send transactions through the wallet
• The home page shows an "Add to Wallet" button that registers the chain via wallet_addEthereumChain
• Authentication state is provided by EthereumAuthenticationStateProvider

Configuration

Bound from IConfiguration section "Explorer" into ExplorerOptions:

Pagination uses a fixed page size of 25 items, clamped to a maximum of 100 for API requests (defined in ExplorerConstants).

ABI Source Options (AbiSources sub-section)

ABI resolution uses a composite chain. Sources are checked in order; results are cached in a singleton in-memory cache shared across all Blazor circuits.

Resolution order: in-memory cache, local filesystem (if enabled, highest priority), Sourcify, Etherscan, 4Byte. Falls back to local-only if no sources are configured.

API Endpoints

All endpoints are rate-limited: 100 requests per minute, fixed window, 429 on rejection.

Token API (/api/tokens)

Returns 503 { error: "Token indexing not configured" } if ITokenExplorerService.IsAvailable is false.

Contract API (/api/contracts)

POST endpoints validate ABI JSON via ABIDeserialiserFactory.DeserialiseContractABI(). If ExplorerOptions.ApiKey is set, POST requests must include a matching X-Api-Key header (simple ordinal string check, intended as a dev-time guard — not a production auth mechanism). If ApiKey is null (the default), POST endpoints are open.

Aspire Integration

The Aspire Explorer host resolves RPC URL via service discovery (services:devchain:http:0 or services:devchain:https:0) and connection strings from Aspire resources:

// AppHost
var postgres = builder.AddPostgres("postgres").AddDatabase("nethereumdb");
var devchain = builder.AddProject<Projects.DevChainServer>("devchain");

builder.AddProject<Projects.ExplorerHost>("explorer")
    .WithReference(postgres)
    .WithReference(devchain)
    .WithExternalHttpEndpoints();

// Explorer host
builder.AddServiceDefaults();

var connectionString = builder.Configuration.GetConnectionString("nethereumdb");
builder.Services.AddPostgresBlockchainStorage(connectionString);
builder.Services.AddTokenPostgresRepositories(connectionString);
builder.Services.AddExplorerServices(builder.Configuration);

Related Packages

Required

• Nethereum.BlockchainStore.Postgres - Provides IBlockchainDbContextFactory via AddPostgresBlockchainStorage()

Optional

• Nethereum.BlockchainStorage.Token.Postgres - Token balance, NFT, and transfer repositories via AddTokenPostgresRepositories()
• Nethereum.Mud.Repositories.Postgres - MUD World store records DB context and normalised table queries

See Also

• Nethereum.Blazor - EIP-6963 wallet interop and Ethereum authentication provider
• Nethereum.Blazor.Solidity - EVM debugger components and Solidity code viewer
• Nethereum.DataServices - ABI info storage implementations (Sourcify, Etherscan, 4Byte)

Additional Resources

• Nethereum Documentation
• MUD Framework
• EIP-6963: Multi Injected Provider Discovery