AppChain Quickstart
PREVIEW — AppChain packages are in preview. APIs may change between releases.
An AppChain is a lightweight, domain-specific chain that extends Ethereum. This guide covers the two ways to launch one: the CLI server (production) and the programmatic AppChainBuilder (embedded/testing). Both give you a full EVM with standard JSON-RPC — deploy contracts with Hardhat, Foundry, or Nethereum, interact with any Ethereum library.
# Launch a sequencer, serving eth/snap over DevP2P so followers can sync from it
nethereum-appchain --chain-id 420420 --genesis-owner-key $KEY --sequencer-key $KEY \
--enable-devp2p-serve --devp2p-serve-port 30403
# Launch a follower — dial the sequencer's enode, not its JSON-RPC port
nethereum-appchain --chain-id 420420 --genesis-owner-address $ADDR --sequencer-address $SEQ_ADDR \
--follow-peer enode://<sequencer-id>@<host>:30403
That's it. Full EVM, JSON-RPC, WebSocket subscriptions — standard Ethereum interface.
Prerequisites
# Install the CLI tool
dotnet tool install --global Nethereum.AppChain.Server
# For programmatic usage
dotnet add package Nethereum.AppChain.Sequencer
You need a private key for the sequencer (block signer) and genesis owner (pre-funded account). For local development, generate one or use a test key.
Launch a Sequencer
The sequencer is the block producer — it accepts transactions, validates them, and produces blocks. Launch one with the CLI:
nethereum-appchain \
--port 8546 \
--chain-id 420420 \
--name "MyAppChain" \
--genesis-owner-key 0xYOUR_PRIVATE_KEY \
--sequencer-key 0xYOUR_PRIVATE_KEY \
--block-time 1000 \
--enable-devp2p-serve
This starts an HTTP/WebSocket JSON-RPC server on port 8546. The genesis owner address is pre-funded, and the sequencer produces a block every 1000ms, but only when transactions are pending unless --allow-empty-blocks is set. By default, persistent storage uses RocksDB at ./appchain-data — see the Storage guide for configuration options. --enable-devp2p-serve makes the sequencer advertise eth/snap over DevP2P so followers have a peer to dial — see Launch a Follower below.
Key CLI options for the sequencer:
| Option | Default | Description |
|---|---|---|
--port | 8546 | HTTP listen port |
--chain-id | 420420 | Chain ID |
--name | AppChain | Chain display name |
--genesis-owner-key | Private key for genesis owner (pre-funded) | |
--sequencer-key | Private key for block signing | |
--block-time | 1000 | Block production interval in milliseconds |
--db-path | ./appchain-data | RocksDB data directory |
--in-memory | false | Use in-memory storage (no persistence) |
--deploy-mud-world | true | Deploy MUD World contracts at genesis |
--enable-devp2p-serve | false | Serve eth/snap over DevP2P so followers can sync from this node |
--devp2p-serve-port | 30403 | DevP2P listen port for served followers |
Launch a Follower
A follower syncs from the sequencer and maintains a verified copy of the chain. Anyone can run one — that's the public verifiability promise:
nethereum-appchain \
--port 8547 \
--chain-id 420420 \
--name "MyAppChain" \
--genesis-owner-address 0xOWNER_ADDRESS \
--sequencer-address 0xSEQUENCER_ADDRESS \
--follow-peer enode://<sequencer-node-id>@<host>:30403
The sequencer must be launched with --enable-devp2p-serve so it advertises eth/snap over DevP2P for followers to dial. The follower connects over RLPx to the sequencer's --follow-peer enode (not its JSON-RPC port), snap-syncs the state at the pivot, re-executes blocks to validate state roots, and then follows the chain head live. It serves the same JSON-RPC interface as the sequencer but doesn't produce blocks. See the Syncing guide for how the DevP2P sync stack drives this.
Note the follower uses --genesis-owner-address (not --genesis-owner-key) because it doesn't need the private key — it just needs to know the address to reconstruct the same genesis state.
Interact via Nethereum
Once your AppChain is running, connect with Nethereum exactly as you would any Ethereum network:
using Nethereum.Web3;
using Nethereum.Web3.Accounts;
var account = new Account(privateKey, chainId: 420420);
var web3 = new Web3(account, "http://localhost:8546");
// Check balance (genesis owner is pre-funded)
var balance = await web3.Eth.GetBalance.SendRequestAsync(account.Address);
// Deploy a contract
var receipt = await web3.Eth.GetContractDeploymentHandler<MyContractDeployment>()
.SendRequestAndWaitForReceiptAsync(new MyContractDeployment { ... });
// Call a contract
var service = new MyContractService(web3, receipt.ContractAddress);
await service.MyFunctionRequestAndWaitForReceiptAsync(new MyFunction { ... });
All standard web3.Eth operations work — balance queries, contract deployment, transaction sending, event filtering, gas estimation. The AppChain handles EIP-1559 fees, nonce management, and transaction signing automatically.
HTTP Endpoints
The server exposes more than just JSON-RPC:
| Method | Path | Description |
|---|---|---|
| POST | / | JSON-RPC 2.0 (eth_*, web3_*, net_*) |
| WS | /ws | WebSocket subscriptions (eth_subscribe) |
| GET | /health | Health check |
| GET | /status | Comprehensive node status |
| GET | /metrics | Prometheus metrics (when a metrics port is configured) |
| GET | /blocks/latest | Latest block header |
Programmatic AppChain with AppChainBuilder
For embedded usage, testing, or when you need programmatic control over the chain lifecycle, use AppChainBuilder. This creates an in-process AppChain without an HTTP server:
using Nethereum.AppChain.Sequencer.Builder;
var chain = await new AppChainBuilder("TestChain", 420420)
.WithOperator(privateKey)
.BuildAsync();
The builder configures genesis, storage, sequencer, and transaction pool in a single fluent call. WithOperator sets both the genesis owner (pre-funded) and the sequencer signer.
Builder Configuration
The builder supports all the same options as the CLI:
var chain = await new AppChainBuilder("MyChain", 420420)
.WithOperator(privateKey)
.WithBaseFee(0)
.WithBlockGasLimit(30_000_000)
.WithOnDemandBlocks()
.WithPrefundedAddresses(new[] { addr1, addr2 })
.BuildAsync();
WithOnDemandBlocks() produces a block immediately when a transaction is submitted — useful for tests where you don't want to wait for interval-based production.
AppChainBuilder runs fully in-memory (its default storage). For persistent RocksDB storage, run the AppChain via the CLI (RocksDB is the default; use --db-path to set the location) or inject stores manually — WithStorage(StorageType.RocksDb, …) on the builder is not supported and throws NotSupportedException.
Presets
AppChainPresets provides pre-configured builders for common scenarios:
// Gaming chain — optimized for high-frequency state updates
var chain = await AppChainPresets
.ForGaming("GameChain", 420420, operatorKey)
.WithPrefundedAddresses(playerAddresses)
.BuildAsync();
// Testing — in-memory, on-demand blocks
var chain = await AppChainPresets
.ForTesting("TestChain", 31337, testKey)
.BuildAsync();
Interacting with a Programmatic AppChain
The built chain exposes an AppChainNode that you can use with an RPC client:
// Get the node for RPC interaction
var node = new AppChainNode(chain.AppChain, chain.Sequencer);
// Create an RPC client that talks directly to the node (no HTTP)
var rpcClient = new AppChainRpcClient(node, chainId: 420420);
var web3 = new Web3(new Account(userKey, 420420), rpcClient);
// Now use web3 normally
var balance = await web3.Eth.GetBalance.SendRequestAsync(userAddress);
await web3.Eth.GetEtherTransferService()
.TransferEtherAndWaitForReceiptAsync(recipientAddress, 1.0m);
The AppChainRpcClient routes JSON-RPC calls directly to the in-process node without HTTP overhead — ideal for testing and embedded scenarios.
MUD World at Genesis
By default, the AppChain deploys MUD World contracts during genesis (controlled by --deploy-mud-world). This means you can use the MUD Framework immediately:
var chain = await new AppChainBuilder("MyChain", 420420)
.WithOperator(privateKey)
.BuildAsync();
// The deployed World address (null if MUD was not deployed at genesis)
var worldAddress = chain.MudResult?.WorldAddress;
From there, register namespaces and tables using your MUD-generated namespace and table services — see the MUD Framework guide. The generated namespace class derives from NamespaceBase and exposes RegisterNamespaceRequestAndWaitForReceiptAsync() and Tables.BatchRegisterAllTablesRequestAndWaitForReceiptAsync().
Common Gotchas
- Same genesis = same chain — sequencer and followers must use the same genesis owner address and chain ID, otherwise they produce different genesis blocks and can't sync. A follower accepts only blocks signed by the key behind its
--sequencer-address, so a chain created by 7.0 (unsigned blocks) must be re-created. --block-timemust be positive —--block-time 0is rejected in interval block production (the CLI default). The default is 1000 ms, and blocks are produced only when transactions are pending unless--allow-empty-blocksis set; for instant on-demand blocks, useAppChainBuilder.WithOnDemandBlocks()programmatically.- RocksDB is the default — the CLI uses RocksDB at
./appchain-dataunless you pass--in-memory. For development without persistence, add--in-memory. - Port conflicts — the sequencer defaults to 8546. Use
--portto change it. - RPC modules and hosts — the RPC port serves
eth,netandweb3only; addtxpool,debugoradminwith--rpc-modules eth,net,web3,admin. A request whoseHostheader is notlocalhost, an IP address or the bind host is answered 403: list the name with--rpc-vhosts(for example behind a proxy or in a container). A browser WebSocket origin needs--ws-origins; a request body over 10 MiB is refused.
Next Steps
- Storage — configure RocksDB for production, understand storage interfaces, tune performance
- Syncing Follower Nodes — sync a follower over the shared DevP2P stack (
--follow-peer), snap bootstrap, forward execution, and independent state-root verification