Nethereum.AppChain.Server 7.1.0-preview

Nethereum.AppChain.Server

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

The executable for running a Nethereum AppChain — a lightweight, domain-specific execution layer that extends Ethereum L1/L2 with publicly readable, cryptographically verifiable state. One process gives you block production, JSON-RPC (HTTP + WebSocket), DevP2P peering and sync, Clique PoA consensus, cross-chain messaging, L1 anchoring, and optional MUD World deployment.

A node runs in one of three roles, chosen by which keys/addresses you hand it: sequencer (holds a private key, produces blocks), follower (holds only addresses, imports and verifies blocks from a peer), or Clique validator (one of several signers in a multi-node PoA set).

Install

dotnet tool install -g Nethereum.AppChain.Server

Getting started

Run it with no arguments:

nethereum-appchain

With no genesis owner, sequencer, or Clique signer identity supplied, the server generates ephemeral keys in memory, logs AppChain dev mode: generated ephemeral keys (NOT for production), and starts producing blocks straight away — single-sequencer consensus, RocksDB storage under ./appchain-data, JSON-RPC on http://127.0.0.1:8546. This is the fastest way to get an AppChain running locally; the generated keys are lost on restart, so it is not for anything you need to come back to (AppChainComposition.ApplyEphemeralDevKeys, gated by AppChainServerConfig.IsFullyUnconfigured).

For anything persistent, supply your own keys:

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

A follower supplies addresses instead of private keys, and points --follow-peer at a sequencer's enode. It imports and verifies blocks over DevP2P instead of producing any:

nethereum-appchain \
  --port 8547 \
  --chain-id 420420 \
  --name "MyAppChain" \
  --genesis-owner-address 0xOWNER_ADDRESS \
  --sequencer-address 0xSEQUENCER_ADDRESS \
  --follow-peer enode://PRODUCER_PUBKEY@sequencer:30403

Follower mode requires both --genesis-owner-address and --sequencer-address — the server needs to know who it's trusting before it will import a single block (AppChainServerConfigValidator.ValidateOperatorKeys).

Clique multi-validator

# Validator 1
nethereum-appchain \
  --port 8546 --consensus clique \
  --initial-signers $ADDR1,$ADDR2,$ADDR3 \
  --signer-key $KEY1 \
  --genesis-owner-key $KEY1 \
  --sequencer-key $KEY1 \
  --enable-devp2p-serve --devp2p-serve-port 30403

# Validator 2
nethereum-appchain \
  --port 8547 --consensus clique \
  --initial-signers $ADDR1,$ADDR2,$ADDR3 \
  --signer-key $KEY2 \
  --genesis-owner-key $KEY2 \
  --sequencer-key $KEY2 \
  --enable-devp2p-serve --devp2p-serve-port 30404 \
  --devp2p-peers enode://VALIDATOR1_PUBKEY@127.0.0.1:30403

Clique consensus additionally requires --signer-key (unless following), at least one --initial-signers entry, and at least one DevP2P peer to reach — each is enforced at startup with a specific error, not a silent no-op (AppChainServerConfigValidator.ValidateClique).

HTTP endpoints

(AppChainServerRunner.MapEndpoints; LiveBlockEndpoints.MapLiveBlockEndpoints.)

CLI options

Every option below is defined in AppChainCliOptions — Program.cs just wires it up. This is the full set the tool understands today.

Server / RPC

Genesis & keys

Leave all four unset and the server generates ephemeral keys itself — see Getting started.

Block production

Storage

Consensus & DevP2P

MUD

Anchoring

Cross-chain messaging

Advanced configuration

The everyday flags above are layered on top of a full configuration system, so you have three ways to set any value and they compose in a fixed order (later wins): appsettings.json → environment variables → command-line flags. BuildLayeredConfiguration wires all three (src/Nethereum.AppChain.Server/AppChainCli.cs:102-107); the AppChain section of appsettings.json and AppChain__-prefixed env vars bind straight onto AppChainServerConfig.

Beyond the everyday flags, every setting on AppChainServerConfig can be set in its raw --AppChain:<Path> <value> form. Run nethereum-appchain --help-advanced to list the full expert surface (TryHandleAdvancedHelp/PrintAdvancedHelp, src/Nethereum.AppChain.Server/AppChainCli.cs:178-199, invoked from Program.cs).

Node identity is a first-class concern: --node-key-hex pins the DevP2P identity from a hex key, and --node-key-file persists it to a file (defaulting to <db-path>/nodekey), so a node keeps a stable enode across restarts.

Embed it

AppChainServerRunner.RunAsync is the whole server — composition, HTTP host, and endpoint mapping — packaged as a single call, so embedding it in your own process is one line:

using Nethereum.AppChain.Server;
using Nethereum.AppChain.Server.Configuration;

var config = new AppChainServerConfig
{
    ChainId = 420420,
    ChainName = "MyAppChain",
};
config.Consensus.Sequencer.PrivateKey = sequencerKey;
config.Genesis.Owner.PrivateKey = genesisOwnerKey;

await AppChainServerRunner.RunAsync(config);

If you're composing your own ASP.NET Core host instead and only want the AppChain building blocks wired into your DI container, AddAppChainServer registers the config, MudWorldDeployer, and the in-memory finality tracker as singletons; pair it with AddAppChainMetrics, AddAppChainOpenTelemetry, and AddAppChainHealthChecks for the same instrumentation AppChainServerRunner sets up internally (src/Nethereum.AppChain.Server.Core/Hosting/ServiceCollectionExtensions.cs). Endpoint mapping (/, /ws, /status, /blocks/*, /finality/*) is not yet exposed as a reusable Map*Endpoints extension the way Nethereum.DevChain.Server and Nethereum.MainnetChain.Server offer it — AppChainServerRunner.RunAsync is the supported way to get the full HTTP surface today.

Related packages

Dependencies

• Nethereum.AppChain - Core chain abstraction
• Nethereum.AppChain.Sequencer - Block production
• Nethereum.DevP2P.Sync - DevP2P peering and sync
• Nethereum.Consensus.Clique - PoA consensus

See also

• Nethereum.DevChain.Server - Development chain server
• Nethereum.MainnetChain.Server - Mainnet follower server

Additional resources

• MUD Framework
• Nethereum Documentation