Skip to content

A thread-centric L1 blockchain where every account is a personal cryptographic chain that only you can sign. Near-zero fee transfers, ~3s finality, WASM smart contracts, and lightweight full nodes — built in Rust with HotStuff BFT consensus.

License

Notifications You must be signed in to change notification settings

augmnt/norn-protocol

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

223 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Norn Protocol

CI License: MIT Rust Version Discord


What is Norn?

Norn is a thread-centric blockchain protocol that reimagines the relationship between users and the chain. Rather than treating accounts as entries in a global ledger, Norn gives every user a personal cryptographic chain with sovereign control. You hold the thread.

Every account is a Thread -- a personal cryptographic chain that only you can sign. Your state is replicated across the network for availability, but only your signature can authorize changes. Transfers are signed by the sender and validated by the network. Clients can independently verify their balances using Merkle proofs. The chain validates state transitions and guarantees correctness -- it doesn't hold your money.

For complex multi-party logic, WASM smart contracts called Looms provide WebAssembly-powered programmability with fraud proof guarantees. The result is a protocol with near-zero fee transfers, fast finality, and cryptographic state verification -- where the chain exists only to keep everyone honest.

Key Properties

  • Near-zero fee transfers -- Each transfer incurs a flat 0.001 NORN fee that is burned, preventing spam while keeping costs negligible. Operations like name registration and token creation carry additional fees.
  • Fast finality -- Transactions confirm in ~3 second blocks on the Weave.
  • Lightweight full nodes -- Memory-bounded data structures and efficient state management keep resource requirements low. A full node starts under 2 GB of RAM.
  • State verification -- Clients independently verify balances via Merkle proofs against the on-chain state root.
  • Fraud-proof security -- Cheating is detectable and punishable through economic penalties. Honest behavior is the Nash equilibrium.

Installation

From Git (latest)

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

From Source

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

After installation, the norn command is available:

norn --version
norn wallet create --name mywallet
norn run --dev   # Joins the devnet, syncs blocks, persists to SQLite

Architecture

Norn's architecture consists of six core components:

Component Description
Threads Personal state chains -- each user maintains their own cryptographically owned history of state transitions, replicated across the network.
Knots Atomic state transitions -- signed transfers that update Thread state, validated by the network.
Weave The anchor chain -- a HotStuff BFT blockchain that orders transactions and anchors state.
Looms WASM smart contracts -- WebAssembly programs that execute on validators with fraud proof guarantees.
Spindles Watchtower services -- monitor the Weave for invalid operations and submit fraud proofs when misbehavior is detected.
Relays P2P message buffers -- asynchronous message delivery between Threads via the libp2p protocol stack.
flowchart TB
    subgraph Threads
        A["Thread A<br/>(Alice)"]
        B["Thread B<br/>(Bob)"]
    end

    A <-->|"Signed Transfers<br/>(near-zero fees, fast finality)"| B

    A -->|"Transactions<br/>(transfers, operations)"| W
    B -->|"Transactions<br/>(transfers, operations)"| W

    subgraph W["The Weave (Anchor Chain -- HotStuff BFT Consensus)"]
        T[Transfers]
        R[Registrations]
        F[Fraud Proofs]
        L2[Looms]
    end

    SP["Spindles<br/>(Watchtower Services)"] --> W
    LM["Looms<br/>(WASM Contracts)"] --> W
    RL["Relays<br/>(P2P Message Buffers)"] --> W
Loading

Running a Node

Network Architecture

The devnet runs HotStuff BFT consensus across multiple validators. The seed node acts as the bootstrap peer and initial block producer, with validators participating in multi-validator consensus.

flowchart TB
    subgraph Seed["seed.norn.network (validator + bootstrap)"]
        P2P["P2P :9740"]
        RPC["RPC :9741"]
    end

    subgraph Validator["validator (consensus participant)"]
        VP2P["P2P :9740"]
        VRPC["RPC :9741"]
    end

    Explorer["Explorer\nexplorer.norn.network"] -.->|HTTPS| RPC
    WebWallet["Web Wallet\nwallet.norn.network"] -.->|HTTPS| RPC
    WalletExt["Wallet Extension"] -.->|HTTPS| RPC
    Website["Website\nnorn.network"]

    subgraph Local["Local Nodes"]
        A["Your Node\n(norn run --dev)"]
    end

    A <-->|"gossip + sync"| P2P
    Validator <-->|"consensus + gossip"| Seed
Loading
  • Seed node: Bootstrap peer and consensus participant. Produces blocks via HotStuff BFT, serves the explorer, web wallet, and wallet extension.
  • Validator node: Consensus participant. Validates blocks, votes on proposals, and triggers view changes on leader failure.
  • Local nodes: Connect to the seed as peers. Sync blocks from the network, maintain local state, and gossip transactions for inclusion in blocks.

Quick Start (Join the Devnet)

norn run --dev

That's it. This will:

  1. Connect to seed.norn.network as a peer (automatic)
  2. Sync all existing blocks from the network
  3. Store chain state locally (SQLite, persistent)
  4. Gossip any transactions you submit to the seed for inclusion in blocks

Your wallet CLI works against your local node by default (--rpc-url http://localhost:9741), and transactions will propagate to the entire network.

Running the Seed Node

The seed node runs with --no-bootstrap since it IS the bootstrap peer:

norn run --dev --consensus --no-bootstrap --rpc-addr 0.0.0.0:9741 --data-dir /var/lib/norn/norn-data

Network Modes

Norn supports three network modes, selectable via --network flag or network_id in norn.toml:

Mode Chain ID Faucet Use Case
dev norn-dev Enabled (60s cooldown) Local development and devnet
testnet norn-testnet-1 Enabled (1hr cooldown) Public testing, multi-node
mainnet norn-mainnet Disabled Production deployment

Common Flags

Flag Description
--dev Dev mode: faucet, SQLite storage, solo validator, auto-bootstrap to devnet seed
--consensus Enable multi-validator HotStuff BFT consensus (overrides solo mode from --dev)
--no-bootstrap Run as the seed node (no outbound peers)
--storage <TYPE> Override storage: sqlite (default for --dev), memory, rocksdb
--boot-node <MULTIADDR> Add a custom bootstrap peer
--rpc-addr <ADDR:PORT> Bind RPC server (default 127.0.0.1:9741)
--data-dir <PATH> Data directory (default ~/.norn/data)
--reset-state Wipe data directory before starting

Public Endpoints

Service URL
Website norn.network
RPC https://seed.norn.network
WebSocket wss://seed.norn.network
Explorer explorer.norn.network
Web Wallet wallet.norn.network
P2P Bootstrap /ip4/164.90.182.133/tcp/9740

Repository Structure

Crate / Package Description
norn-types Shared type definitions (Thread, Knot, Weave, Loom, consensus, fraud proof, genesis, network message types)
norn-crypto Cryptographic operations (Ed25519 keys, BLAKE3 hashing, Merkle trees, BIP-39 seeds, SLIP-0010 HD derivation, XChaCha20 encryption)
norn-thread Thread management (Thread chain, Knot creation/validation, state management, version tracking)
norn-storage Storage abstraction (KvStore trait with memory, SQLite, and RocksDB backends; Merkle, Thread, and Weave stores)
norn-relay P2P networking (libp2p behaviour, protocol codec, peer discovery, relay service, state sync, Spindle registry)
norn-weave Anchor chain (block production, transaction processing, HotStuff consensus, dynamic fees, fraud proof verification, staking)
norn-loom Smart contract runtime (Wasm runtime, host functions, gas metering, Loom lifecycle, dispute resolution)
norn-spindle Watchtower service (Weave monitoring, fraud proof construction, rate limiting, service orchestration)
norn-sdk Contract SDK for writing Norn loom smart contracts (#![no_std], targets wasm32-unknown-unknown)
norn-node Full node binary (CLI, node configuration, genesis handling, JSON-RPC server with API key auth, wallet CLI, NornNames, NT-1 tokens, Loom smart contracts with execution, Prometheus metrics endpoint, fraud proof submission, spindle watchtower integration)
sdk/typescript TypeScript SDK (@norn-protocol/sdk) — wallet primitives, transaction builders, RPC client, WebSocket subscriptions
explorer/ Block explorer — Next.js 15 web app for browsing blocks, transactions, accounts, tokens, and contracts
wallet/ Web wallet — Next.js 15 passkey-secured browser wallet for managing NORN, tokens, names, and contracts
wallet-extension/ Wallet extension — Chrome extension for sending/receiving NORN, managing accounts, and registering names
website/ Website — norn.network marketing site and documentation hub

Getting Started

Prerequisites

  • Rust (stable toolchain)

Build

cargo build --workspace

Test

cargo test --workspace

Lint

cargo clippy --workspace -- -D warnings
cargo fmt --check

Run the Demo

cargo run --example demo -p norn-node

Wallet CLI

The norn binary includes a full-featured wallet CLI with 45 subcommands for key management, transfers, NornNames (register, transfer, reverse-resolve, records), custom tokens, Loom smart contracts (deploy, upload, execute, query, join, leave), Thread inspection, and encrypted keystore backup.

# Create a new wallet
norn wallet create --name alice

# List wallets
norn wallet list

# Check balance (native NORN or custom token by symbol)
norn wallet balance --address <ADDRESS>
norn wallet balance --token MTK

# Send tokens (by address or NornName)
norn wallet transfer --to <ADDRESS_OR_NAME> --amount <AMOUNT>
norn wallet transfer --to <ADDRESS_OR_NAME> --amount 100 --token MTK
# Or use the `send` alias
norn wallet send --to <ADDRESS_OR_NAME> --amount <AMOUNT>

# Register a NornName (costs 1 NORN, burned)
norn wallet register-name --name alice

# Resolve a NornName to its owner address
norn wallet resolve --name alice

# List names owned by the active wallet
norn wallet names

# Transfer a name to another address
norn wallet transfer-name --name alice --to 0x<ADDRESS>

# Reverse-resolve an address to its primary NNS name
norn wallet reverse-name --address 0x<ADDRESS>

# Attach a record to a name
norn wallet set-name-record --name alice --key avatar --value "https://example.com/avatar.png"

# View records for a name
norn wallet name-records alice

# Configure wallet (network, RPC URL)
norn wallet config --network testnet
norn wallet config --rpc-url http://my-node:9741

# Check node connectivity
norn wallet node-info

# View current fees
norn wallet fees

# View validator set
norn wallet validators

# Active wallet dashboard
norn wallet whoami

Token Management

# Create a custom fungible token (costs 10 NORN, burned)
norn wallet create-token --name "My Token" --symbol MTK --decimals 8 --max-supply 1000000 --initial-supply 1000

# Mint tokens (creator only)
norn wallet mint-token --token MTK --to 0x<ADDRESS> --amount 500

# Burn tokens (any holder)
norn wallet burn-token --token MTK --amount 100

# Query token metadata
norn wallet token-info MTK

# List all registered tokens
norn wallet list-tokens

# View all token balances for the active wallet
norn wallet token-balances

The --token flag on balance and transfer accepts token symbols (e.g., MTK), NORN/native for the native token, or a 64-character hex token ID.

Wallets are stored in ~/.norn/wallets/ with Argon2id key derivation and XChaCha20-Poly1305 authenticated encryption.

NornNames (NNS)

NornNames is Norn's native consensus-level name system -- an ENS-like identity layer mapping human-readable names to owner addresses. Names are included in WeaveBlocks and propagate to all nodes via P2P gossip, making them globally visible across the network.

NNS supports name transfers, reverse resolution, and name records (avatar, url, description, twitter, github, email, discord).

Naming Rules

Rule Constraint
Length 3--32 characters
Character set Lowercase ASCII letters (a-z), digits (0-9), hyphens (-)
Hyphens Must not start or end with a hyphen
Uniqueness Globally unique, first-come first-served

Valid names: alice, bob-42, my-validator, norn-relay-1

Invalid names: ab (too short), -alice (leading hyphen), bob- (trailing hyphen), Alice (uppercase), my name (spaces)

Registration Cost

Registering a NornName costs 1 NORN, which is permanently burned (debited from the registrant, not credited to anyone), reducing the circulating supply. Name transfers are free.

Wallet CLI Usage

# Register a NornName for the active wallet (submitted to mempool, included in next block)
norn wallet register-name --name alice

# Resolve a NornName to its owner address
norn wallet resolve --name alice

# List names owned by the active wallet
norn wallet names

# Transfer a name to another address
norn wallet transfer-name --name alice --to 0x<ADDRESS>

# Reverse-resolve an address to its primary NNS name
norn wallet reverse-name --address 0x<ADDRESS>

# Attach a record to a name (allowed keys: avatar, url, description, twitter, github, email, discord)
norn wallet set-name-record --name alice --key avatar --value "https://example.com/avatar.png"

# View all records for a name
norn wallet name-records alice

Names work seamlessly in transfers -- pass a NornName instead of a hex address:

norn wallet send --to alice --amount 10

The wallet resolves alice to the owner's address via norn_resolveName before constructing the transfer.

Name Records

Name owners can attach predefined text records to their names. Records are consensus-level and propagate to all nodes.

Key Description
avatar Profile image URL
url Website URL
description Short bio or description
twitter Twitter/X handle
github GitHub username
email Contact email
discord Discord handle

Constraints: Max value length 256 bytes. Max 16 records per name.

RPC Methods

Method Parameters Returns Auth
norn_registerName hex (hex-encoded borsh NameRegistration) SubmitResult Yes
norn_resolveName name (string) Option<NameResolution> No
norn_getNamesByOwner address (hex) Vec<NameInfo> No
norn_transferName name, from_hex, transfer_hex SubmitResult Yes
norn_reverseName address_hex Option<String> No
norn_setNameRecord name, key, value, owner_hex, update_hex SubmitResult Yes
norn_getNameRecords name HashMap<String, String> No

For full technical details, see the Protocol Specification, Section 28.

NT-1 Fungible Token Standard

Norn supports protocol-level custom fungible tokens via the NT-1 standard. Tokens are consensus-level: definitions, mints, and burns are included in WeaveBlocks and propagate to all nodes via P2P gossip.

Token Operations

Operation Who Fee Effect
Create Anyone 10 NORN (burned) Registers a new token with metadata; optionally mints initial supply to creator
Mint Token creator only None Creates new tokens, credits to recipient
Burn Any holder None Destroys tokens from burner's balance

Token ID is deterministic: BLAKE3(creator ++ name ++ symbol ++ decimals ++ max_supply ++ timestamp).

Symbol uniqueness is enforced at the consensus level -- no two tokens can share the same ticker.

Token Rules

Rule Constraint
Name length 1--64 printable ASCII characters
Symbol length 1--12 uppercase alphanumeric characters
Decimals 0--18
Max supply 0 = unlimited, otherwise enforced on mint

Wallet CLI Usage

# Create a token
norn wallet create-token --name "Wrapped Bitcoin" --symbol WBTC --decimals 8 --max-supply 21000000 --initial-supply 0

# Mint tokens to a recipient (creator only)
norn wallet mint-token --token WBTC --to 0x<ADDRESS> --amount 1000

# Transfer custom tokens
norn wallet transfer --to 0x<ADDRESS> --amount 100 --token WBTC

# Burn tokens from your own balance
norn wallet burn-token --token WBTC --amount 50

# Query token info (by symbol or hex token ID)
norn wallet token-info WBTC

# List all tokens on the network
norn wallet list-tokens

# View all non-zero token holdings for the active wallet
norn wallet token-balances

RPC Methods

Method Parameters Returns Auth
norn_createToken hex (hex-encoded borsh TokenDefinition) SubmitResult Yes
norn_mintToken hex (hex-encoded borsh TokenMint) SubmitResult Yes
norn_burnToken hex (hex-encoded borsh TokenBurn) SubmitResult Yes
norn_getTokenInfo token_id (hex) Option<TokenInfo> No
norn_getTokenBySymbol symbol Option<TokenInfo> No
norn_listTokens limit, offset Vec<TokenInfo> No

For full technical details, see the Protocol Specification, Section 28b.

Loom Smart Contracts

Norn supports WASM smart contracts called Looms -- WebAssembly programs that execute on every validator with fraud proof guarantees. Loom deployments are consensus-level: registrations are included in WeaveBlocks and propagate to all nodes via P2P gossip.

Loom Operations

Operation Who Fee Effect
Deploy Anyone 50 NORN (burned) Registers a new loom with metadata on the network
Upload Bytecode Loom operator None Uploads .wasm bytecode to the node and calls init()
Execute Any participant None Runs the contract with input data, mutates state
Query Anyone None Read-only contract execution, no state change
Join Anyone None Join a loom as a participant
Leave Participant None Leave a loom

Loom ID is deterministic: BLAKE3(name ++ operator ++ timestamp).

Naming Rules

Rule Constraint
Length 3--64 characters
Character set Lowercase ASCII letters (a-z), digits (0-9), hyphens (-)
Hyphens Must not start or end with a hyphen

Contract SDK

The norn-sdk crate provides the building blocks for writing loom contracts in Rust, targeting wasm32-unknown-unknown. Contracts export init(), execute(ptr, len), and query(ptr, len) functions.

# Build a contract (see examples/counter/ for a working example)
cargo build --target wasm32-unknown-unknown --release --manifest-path examples/counter/Cargo.toml

Wallet CLI Usage

# Deploy a loom (costs 50 NORN, burned)
norn wallet deploy-loom --name my-contract

# Upload bytecode to a deployed loom
norn wallet upload-bytecode --loom-id <LOOM_ID> --bytecode path/to/contract.wasm

# Execute a loom contract
norn wallet execute-loom --loom-id <LOOM_ID> --input 01

# Query a loom contract (read-only)
norn wallet query-loom --loom-id <LOOM_ID>

# Join/leave a loom
norn wallet join-loom --loom-id <LOOM_ID>
norn wallet leave-loom --loom-id <LOOM_ID>

# Query loom metadata
norn wallet loom-info <LOOM_ID>

# List all deployed looms
norn wallet list-looms

RPC Methods

Method Parameters Returns Auth
norn_deployLoom hex (hex-encoded borsh LoomRegistration) SubmitResult Yes
norn_uploadLoomBytecode loom_id (hex), bytecode_hex SubmitResult Yes
norn_executeLoom loom_id (hex), input_hex, sender_hex ExecutionResult Yes
norn_queryLoom loom_id (hex), input_hex QueryResult No
norn_joinLoom loom_id (hex), participant_hex, pubkey_hex SubmitResult Yes
norn_leaveLoom loom_id (hex), participant_hex SubmitResult Yes
norn_getLoomInfo loom_id (hex) Option<LoomInfo> No
norn_listLooms limit, offset Vec<LoomInfo> No

For full technical details, see the Protocol Specification.

Token Economics

NORN has a fixed maximum supply of 1,000,000,000 NORN (1 billion), enforced at the protocol level.

Category % Amount Vesting
Founder & Core Team 15% 150,000,000 4-year linear, 1-year cliff
Ecosystem Development 20% 200,000,000 Controlled release over 5 years
Validator Rewards 30% 300,000,000 Block rewards over 10+ years
Community & Grants 15% 150,000,000 Governance-controlled
Treasury Reserve 10% 100,000,000 DAO-governed after decentralization
Initial Liquidity 5% 50,000,000 Available at launch
Testnet Participants 5% 50,000,000 Airdrop at mainnet launch

Deflationary mechanics: Every transfer burns 0.001 NORN. NornNames registration burns 1 NORN per name. NT-1 token creation burns 10 NORN per token. Loom deployment burns 50 NORN per contract.

For full details, see the Protocol Specification.

Explorer

The Norn Explorer is a block explorer web app for browsing the Norn network — blocks, transactions, accounts, tokens, and smart contracts. Built with Next.js 15, React 19, shadcn/ui, and the @norn-protocol/sdk.

Live instance: explorer.norn.network

To run locally:

cd sdk/typescript && npm install && npm run build  # Build SDK first
cd ../../explorer
npm install
npm run dev

Open http://localhost:3000. By default it connects to seed.norn.network. To point at a local node, create .env.local:

NEXT_PUBLIC_RPC_URL=http://localhost:9741
NEXT_PUBLIC_WS_URL=ws://localhost:9741

Key pages:

Route Description
/ Dashboard with network stats, recent blocks, and transactions
/blocks Paginated block list
/block/[height] Block detail with metadata and activity counts
/transactions Live transaction feed with pending transactions
/address/[address] Account balances, transaction history, NNS name and records
/tokens Token registry with supply information
/contracts Deployed smart contracts

Real-time updates are powered by WebSocket subscriptions — blocks and transactions stream in as they are produced.

See explorer/README.md for full setup instructions, environment variables, and troubleshooting.

Web Wallet

The Norn Web Wallet is a self-custodial browser wallet secured by WebAuthn passkeys. No extensions to install -- just visit the URL and authenticate with Face ID, Touch ID, or Windows Hello.

Live instance: wallet.norn.network

Features:

  • Passkey authentication (Face ID / Touch ID / Windows Hello)
  • Self-custodial -- private keys derived on-the-fly, never stored
  • Cross-device sync via iCloud Keychain or Google Password Manager
  • Send & receive NORN to addresses or NornNames
  • Create, mint, and burn NT-1 tokens
  • NornNames -- register, transfer, reverse-resolve, and manage name records
  • Deploy, execute, and query Loom smart contracts
  • Transaction history with detail views
  • Devnet faucet
  • Optional 24-word recovery phrase backup
  • Auto-lock with configurable timeout

To run locally:

cd sdk/typescript && npm install && npm run build  # Build SDK first
cd ../../wallet
npm install
npm run dev

Open http://localhost:3002. By default it connects to seed.norn.network. To point at a local node, create .env.local:

NEXT_PUBLIC_RPC_URL=http://localhost:9741
NEXT_PUBLIC_WS_URL=ws://localhost:9741

See the Web Wallet documentation for security model details, browser support, and setup instructions.

Wallet Extension

The Norn Wallet is a Chrome browser extension for managing NORN on the Norn Protocol. Send and receive tokens, browse activity, register NornNames, and manage multiple accounts — all from the browser toolbar.

cd wallet-extension
npm install
npm run build

Then load the wallet-extension/dist directory as an unpacked extension in chrome://extensions (Developer mode).

Features:

  • Create new wallets or import from private key hex / CLI export
  • Send NORN to addresses or NornNames (e.g. alice)
  • Receive with QR code
  • Browse NT-1 tokens and transaction history
  • NornNames -- register names, transfer to other addresses, and manage name records
  • Multi-account support with auto-lock
  • Configurable RPC endpoint (defaults to seed.norn.network)

Importing a CLI wallet:

# In terminal — export your CLI wallet's private key
norn wallet export <wallet-name> --show-private-key

# Then paste the 64-char hex into the extension's "Import from CLI" page

See wallet-extension/README.md for full setup instructions, page reference, and security details.

Website

The Norn website at norn.network serves as the project's landing page and documentation hub. Built with Next.js 15 and MDX.

To run locally:

cd website
npm install
npm run dev

TypeScript SDK

The @norn-protocol/sdk package provides wallet primitives, transaction builders, an RPC client, and WebSocket subscription helpers for building TypeScript/JavaScript applications on Norn.

cd sdk/typescript
npm install
npm run build

The Explorer, Web Wallet, and Wallet Extension all depend on this SDK via local file link. Build it first before running any of them.

import { Wallet, NornClient } from "@norn-protocol/sdk";

const wallet = Wallet.generate();
const client = new NornClient("http://localhost:9944");
const balance = await client.getBalance(wallet.address);

Documentation

Contributing

Contributions are welcome. See CONTRIBUTING.md for guidelines.

License

This project is licensed under the MIT License.

About

A thread-centric L1 blockchain where every account is a personal cryptographic chain that only you can sign. Near-zero fee transfers, ~3s finality, WASM smart contracts, and lightweight full nodes — built in Rust with HotStuff BFT consensus.

Topics

Resources

License

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Packages

 
 
 

Contributors