Run a Node

Run your own Norn node to sync chain state, interact with the network, and build on the protocol.

Why Run a Node?

Running a Norn node connects you directly to the network:

• Hold your own state -- Your Thread (personal state chain) lives on your machine. You do not depend on anyone else to verify your balances or history.
• Full RPC access -- Query blocks, submit transactions, and build applications against your own local endpoint with no rate limits.
• Sync the chain -- Your node connects to the devnet, downloads all blocks, and stays in sync with the latest state.

Note: The devnet currently runs a fixed validator set of 3 nodes using HotStuff BFT consensus. Running a node syncs and verifies all blocks, but does not make your node a consensus validator. Dynamic validator joining (stake-to-participate) is planned for a future release.

Quick Setup

Get a node running with a single command:

curl -sSf https://raw.githubusercontent.com/augmnt/norn-protocol/main/scripts/setup-node.sh | bash

This installs Rust (if needed), builds norn from source, creates a wallet, and configures for the devnet. After it finishes, start your node:

norn run --dev

Start immediately

To install and start the node in one go:

curl -sSf https://raw.githubusercontent.com/augmnt/norn-protocol/main/scripts/setup-node.sh | bash -s -- --start --faucet

This starts the node in the background and requests devnet faucet funds automatically.

Production setup (Linux)

For servers that should run 24/7, use --systemd to create and enable a systemd service:

curl -sSf https://raw.githubusercontent.com/augmnt/norn-protocol/main/scripts/setup-node.sh | bash -s -- --systemd --faucet

This creates a dedicated norn system user, writes a systemd service file, copies your wallet, and starts the service. The node auto-restarts on failure and starts on boot.

Script Options

Options can be combined: --start --faucet or --systemd --faucet.

Manual Setup

If you prefer full control over each step, follow the manual process below.

1. Install Norn

From Git (latest release):

cargo install --git https://github.com/augmnt/norn-protocol norn-node

Or clone and build from source:

git clone https://github.com/augmnt/norn-protocol
cd norn-protocol
cargo install --path norn-node

Verify the installation:

norn --version

2. Create a Wallet

norn wallet create --name mynode

This creates an encrypted keystore in ~/.norn/wallets/. You will be prompted to set a password. Keep your password safe -- it protects your private key.

3. Start the Node

norn run --dev

Your node will:

• Connect to seed.norn.network as a peer (automatic)
• Sync all existing blocks from the network
• Store thread and chain state locally (SQLite, persistent)
• Verify all blocks and transactions

4. Get Funded (Devnet Only)

norn wallet faucet

The devnet faucet sends you NORN so you can start transacting immediately. There is a 60-second cooldown between requests.

Consensus

Norn uses HotStuff BFT for block consensus -- a 3-phase commit protocol (Prepare, PreCommit, Commit) that provides Byzantine fault tolerance.

The devnet currently operates with a fixed set of 3 validators. Blocks are proposed by a rotating leader and require agreement from the validator set before being finalized. Your node syncs these finalized blocks and verifies their integrity.

Becoming a Validator

Dynamic validator joining is not yet available on devnet. The current validator set is defined in the genesis configuration. Future releases will support staking-based validator registration, where anyone meeting the minimum stake requirement can join the active set.

Validator Rewards

Norn has zero inflation. There are no block rewards minted out of thin air. Instead, validators earn from real network activity:

1. Every transaction pays a commitment fee. Transfers, name registrations, token operations, loom deployments -- all of them contribute fees.
2. Fees accumulate in an epoch pool. Each epoch spans 1,000 blocks (roughly 50 minutes at 3-second block times).
3. At each epoch boundary, the pool is distributed. Validators receive a share proportional to their stake weight.
4. More network usage = higher rewards. As adoption grows, so does the fee pool.

Checking Network Info

# View current block height and sync status
norn wallet node-info
 
# View the current validator set and stake weights
norn wallet validators
 
# View epoch reward info
norn wallet rewards
 
# JSON output for scripting
norn wallet rewards --json

Running as a Service

The setup script's --systemd flag handles this automatically. If you prefer to configure it manually:

Create the service file at /etc/systemd/system/norn-node.service:

[Unit]
Description=Norn Protocol Node
Documentation=https://norn.network/docs/run-a-node
After=network-online.target
Wants=network-online.target
 
[Service]
Type=simple
User=norn
Group=norn
ExecStart=/usr/local/bin/norn run --dev --storage sqlite --data-dir /var/lib/norn/data
Restart=always
RestartSec=5
LimitNOFILE=65535
Environment=HOME=/var/lib/norn
 
[Install]
WantedBy=multi-user.target

Then enable and start it:

# Create a dedicated user
sudo useradd --system --home /var/lib/norn --shell /usr/sbin/nologin norn
sudo mkdir -p /var/lib/norn/data
sudo chown norn:norn /var/lib/norn/data
 
# Copy your wallet to the service user
sudo mkdir -p /var/lib/norn/.norn/wallets
sudo cp ~/.norn/wallets/* /var/lib/norn/.norn/wallets/
sudo chown -R norn:norn /var/lib/norn/.norn
 
# Enable the service
sudo systemctl daemon-reload
sudo systemctl enable norn-node
sudo systemctl start norn-node
 
# Check status
sudo systemctl status norn-node
 
# Follow logs
sudo journalctl -u norn-node -f

Network Modes

Common Flags

Monitoring

Node Status

norn wallet node-info

This returns your node's sync state, connected peers, current block height, and chain ID.

Prometheus Metrics

Norn exposes Prometheus-compatible metrics at the /metrics endpoint on your RPC port:

http://localhost:9741/metrics

You can scrape this endpoint with Prometheus and visualize with Grafana. Key metrics include:

• norn_block_height -- Current block height
• norn_peer_count -- Number of connected peers
• norn_tx_pool_size -- Pending transaction pool size
• norn_epoch_fees -- Accumulated fees in the current epoch

Health Check

For load balancers and uptime monitors, use the RPC health endpoint:

curl http://localhost:9741/health

Next Steps

• Wallet CLI -- Full reference for all wallet commands
• Architecture -- Understand Threads, Knots, and the Weave
• Quick Start -- Installation and devnet quickstart
• NornNames -- Register a human-readable name for your node