norn
Documentation

Contributing

Contributions to the Norn Protocol are welcome. This guide covers everything you need to get started.

Repository Structure

Crate / PackageDescription
norn-typesShared type definitions (Thread, Knot, Weave, Loom, consensus, fraud proof, genesis, network message types)
norn-cryptoCryptographic operations (Ed25519, BLAKE3, Merkle trees, BIP-39, SLIP-0010, XChaCha20)
norn-threadThread management (chain, Knot creation/validation, state management)
norn-storageStorage abstraction (KvStore trait with memory, SQLite, and RocksDB backends)
norn-relayP2P networking (libp2p, peer discovery, relay service, state sync)
norn-weaveAnchor chain (block production, HotStuff consensus, dynamic fees, fraud proof verification)
norn-loomSmart contract runtime (Wasm, host functions, gas metering, dispute resolution)
norn-spindleWatchtower service (monitoring, fraud proof construction)
norn-sdkContract SDK (#![no_std], targets wasm32-unknown-unknown)
norn-nodeFull node binary (CLI, JSON-RPC server, wallet, NornNames, NT-1 tokens, Looms, metrics)
sdk/typescriptTypeScript SDK (@norn-protocol/sdk)
explorer/Block explorer (Next.js 15)
wallet-extension/Chrome wallet extension

Prerequisites

  • Rust (stable toolchain)

The repository includes a rust-toolchain.toml that pins the stable channel with clippy and rustfmt components.

Build

cargo build --workspace

Test

cargo test --workspace

Lint

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

All three commands must pass before submitting a pull request.

Getting Started

  1. Fork the repository on GitHub
  2. Clone your fork locally: 
    git clone https://github.com/<your-username>/norn-protocol.git
cd norn-protocol
  3. Create a branch for your work: 
    git checkout -b feat/your-feature-name
  4. Make your changes, commit, and push to your fork
  5. Open a Pull Request against the main branch

Branch Naming

Use descriptive branch names with a type prefix:

  • feat/description -- New feature
  • fix/description -- Bug fix
  • refactor/description -- Code refactoring
  • docs/description -- Documentation changes
  • test/description -- Test additions or fixes

Commit Style

This project follows Conventional Commits:

<type>[optional scope]: <description>

Common types: feat, fix, docs, style, refactor, perf, test, chore.

Code Style

  • Run cargo fmt before committing
  • Run cargo clippy --workspace -- -D warnings and resolve all warnings
  • Use thiserror for error enums
  • Use borsh for serialization of protocol types
  • All new code must include tests

License

This project is licensed under the MIT License.