Running a Node¶

Citizen nodes can operate as validators (consensus participants) or observers (read-only replicas).

Prerequisites¶

Rust 1.75+
Linux or macOS (production), any OS (development)
Open firewall ports for QUIC (consensus) and HTTP (API)

Build¶

cd citizen-protocol
cargo build --release

Node Configuration¶

Node configuration is specified via TOML files. See config/localnet/ for example configurations.

Key configuration fields:

[node]
node_id = "validator-alpha"
role = "validator"          # or "observer"
data_dir = "./data"

[network]
listen_addr = "0.0.0.0:7000"
bootstrap_peers = ["validator-beta:7000", "validator-gamma:7000"]

[api]
listen_addr = "0.0.0.0:7001"

[consensus]
quorum_bps = 6667
view_timeout_ms = 5000

[storage]
path = "./data"

Starting a Validator¶

./target/release/citizen-node --config config/validator.toml

On startup, the node will:

Load configuration and admission manifest
Run admission preflight checks
Open RocksDB storage
Boot configured namespaces
Connect to bootstrap peers
Start the HTTP API server
Join consensus (if validator) or begin replicating (if observer)

QUIC-Only Validator Mode¶

Consensus participation and block synchronization happen entirely over QUIC — the HTTP API is only for external consumers (builders, wallets, explorers, health checks). A validator can stay fully synced and vote on blocks using QUIC alone, without exposing the HTTP API. To run a QUIC-only validator, firewall-block the API port (api_port) while leaving the QUIC port open for peer communication. The block sync protocol (SyncRequest/SyncResponse) operates exclusively over QUIC with full BFT commit-proof verification.

Starting an Observer¶

./target/release/citizen-node --config config/observer.toml

Observers do not participate in voting but replicate the full ledger and serve API requests.

Verifying Node Health¶

curl http://localhost:7001/health

{
  "status": "healthy",
  "node_id": "validator-alpha",
  "role": "validator",
  "head_height": 42,
  "peers": 4
}

Node Identity¶

Each node has a cryptographic identity generated during setup:

./target/release/citizen-node --generate-identity

This produces a node identity key pair that is used for peer authentication and must be registered with the network's admission system.

Storage Management¶

The node uses RocksDB. Key data:

data/ - RocksDB database files
data/IDENTITY - Node identity
data/CURRENT - Current storage manifest

Warning

Never delete data/IDENTITY - this is your node's cryptographic identity. Losing it requires generating a new identity and re-admission to the network.

Logs¶

By default, the node logs to stdout. For production, redirect to a log file:

./target/release/citizen-node --config config/validator.toml 2>&1 | tee /var/log/citizen-node.log