Skip to main content

Nethereum.AppChain.Server

NuGet: Nethereum.AppChain.Server | Source: src/Nethereum.AppChain.Server/

Nethereum.AppChain.Server

PREVIEW — This package is in preview. APIs may change between releases.

Production-ready server for running a Nethereum AppChain — a lightweight, domain-specific execution layer that extends Ethereum L1/L2 with publicly readable, cryptographically verifiable state.

Overview​

Nethereum.AppChain.Server is the primary executable for running an AppChain node. It combines all subsystems into a single configurable server: block production, transaction processing, HTTP and WebSocket JSON-RPC endpoints, multi-peer synchronisation, L1 state anchoring, Prometheus metrics, batch serving, and optional MUD World deployment.

The server supports three operational modes: sequencer (produces blocks — your business, your rules), follower (syncs and verifies — anyone can run one), or Clique validator (multi-signer PoA consensus). Configuration is entirely via command-line arguments, making it suitable for containerised deployments.

Key Features​

  • Full JSON-RPC 2.0: All standard eth_*, web3_*, net_* methods plus admin RPC
  • WebSocket Subscriptions: eth_subscribe/eth_unsubscribe via /ws endpoint
  • Consensus Modes: Single-sequencer (default) or Clique PoA with multiple validators
  • HTTP Sync: Multi-peer sync with automatic failover and state re-execution
  • Batch & Snapshot Serving: REST endpoints for batch download and sync status
  • MUD World Deployment: Optional MUD framework contract deployment during genesis
  • L1 Anchoring: Periodic state commitment to Ethereum mainnet
  • Prometheus Metrics: Comprehensive instrumentation at /metrics
  • Storage Options: In-memory or RocksDB persistent storage
  • CLI Configuration: 30+ command-line options via System.CommandLine

Installation​

# As a .NET tool
dotnet tool install Nethereum.AppChain.Server

# Run
nethereum-appchain --help

Or run directly from source:

dotnet run --project src/Nethereum.AppChain.Server -- [options]

Dependencies​

  • Nethereum.AppChain - Core chain abstraction and genesis
  • Nethereum.AppChain.Sequencer - Block production and transaction ordering
  • Nethereum.AppChain.Sync - Multi-peer synchronization and batch import
  • Nethereum.AppChain.Metrics - Prometheus metrics instrumentation
  • Nethereum.AppChain.P2P / P2P.DotNetty - P2P networking for Clique mode
  • Nethereum.Consensus.Clique - Clique PoA consensus engine
  • Nethereum.CoreChain - RPC handler registry, storage interfaces
  • Nethereum.CoreChain.RocksDB - Persistent storage backend

Quick Start​

Sequencer Mode​

nethereum-appchain \
  --port 8546 \
  --chain-id 420420 \
  --name "MyAppChain" \
  --genesis-owner-key 0xYOUR_PRIVATE_KEY \
  --sequencer-key 0xYOUR_PRIVATE_KEY \
  --block-time 1000

Follower Mode​

nethereum-appchain \
  --port 8547 \
  --chain-id 420420 \
  --name "MyAppChain" \
  --genesis-owner-address 0xOWNER_ADDRESS \
  --sequencer-address 0xSEQUENCER_ADDRESS \
  --sync-peers http://sequencer:8546 \
  --sync-poll-interval 100

HTTP Endpoints​

MethodPathDescription
POST/JSON-RPC 2.0 (all eth_*, web3_*, net_*, admin_* methods)
WS/wsWebSocket JSON-RPC (eth_subscribe, eth_unsubscribe)
GET/healthHealth check
GET/statusComprehensive node status
GET/metricsPrometheus metrics
GET/batchesList available batches
GET/batches/{fileName}Download batch file
GET/batches/latestLatest batch info
GET/blocks/latestLatest block header
GET/blocks/{number}Block by number
GET/blocks/rangeBlock range query
GET/finalityFinality tracker status
GET/finality/{blockNumber}Block finality status
GET/sync/statusSync status

CLI Options​

Core​

OptionDefaultDescription
--host0.0.0.0HTTP listen address
--port8546HTTP listen port
--chain-id420420Chain ID
--nameAppChainChain name
--block-time1000Block production interval (ms)
--in-memoryfalseUse in-memory storage (no persistence)
--db-path./appchain-dataRocksDB data directory

Genesis & Keys​

OptionDescription
--genesis-owner-keyPrivate key for genesis owner (sequencer mode)
--genesis-owner-addressAddress of genesis owner (follower mode)
--sequencer-keyPrivate key for block signing
--sequencer-addressAddress of sequencer (follower mode)

Sync​

OptionDefaultDescription
--sync-peersComma-separated peer URLs for HTTP sync
--sync-poll-interval1000Sync poll interval (ms)

Clique Consensus​

OptionDefaultDescription
--cliquefalseEnable Clique PoA consensus
--clique-signersInitial signer addresses
--clique-block-period1Block period in seconds
--p2p-port30303DotNetty P2P port
--p2p-peersBootstrap peer endpoints

MUD & Anchoring​

OptionDefaultDescription
--deploy-mud-worldtrueDeploy MUD World contracts on genesis
--anchor-l1-rpcL1 RPC URL for anchoring
--anchor-contractL1 anchor contract address
--anchor-cadence100Blocks between L1 anchors

Usage Examples​

Example 1: Sequencer with RocksDB​

nethereum-appchain \
  --port 8546 \
  --chain-id 420420 \
  --name "ProdChain" \
  --genesis-owner-key $OWNER_KEY \
  --sequencer-key $SEQ_KEY \
  --db-path /data/appchain \
  --block-time 500 \
  --deploy-mud-world true

Example 2: Clique Multi-Validator​

# Validator 1
nethereum-appchain \
  --port 8546 --clique \
  --clique-signers $ADDR1,$ADDR2,$ADDR3 \
  --genesis-owner-key $KEY1 \
  --sequencer-key $KEY1 \
  --p2p-port 30303

# Validator 2
nethereum-appchain \
  --port 8547 --clique \
  --clique-signers $ADDR1,$ADDR2,$ADDR3 \
  --genesis-owner-key $KEY2 \
  --sequencer-key $KEY2 \
  --p2p-port 30304 \
  --p2p-peers 127.0.0.1:30303

Example 3: Follower with L1 Anchoring Verification​

nethereum-appchain \
  --port 8547 \
  --chain-id 420420 \
  --genesis-owner-address $OWNER_ADDR \
  --sequencer-address $SEQ_ADDR \
  --sync-peers http://sequencer:8546 \
  --anchor-l1-rpc https://mainnet.infura.io/v3/KEY \
  --anchor-contract $ANCHOR_ADDR

Dependencies​

See Also​

Additional Resources​