NOXY Wiki

NOXY is a post-quantum L0 blockchain implemented in Rust. The protocol uses ML-DSA-44 (FIPS 204) for account signatures and a hybrid ML-DSA-44 + Ed25519 scheme for validator consensus votes. State is committed to a Jellyfish Merkle Tree; block production runs in either single-validator or BFT mode.

This wiki describes the protocol as it exists in the repository.

Quickstart

A node is driven from a TOML config file. The repository ships a multi-stage Dockerfile and a disposable local harness at ops/devnet/docker-compose.yml that boots a 4-validator devnet on a single host; the same noxy-node binary can also be installed locally with cargo install. For development, running directly out of the workspace works without an install step:

cargo run -p noxy-node -- --config path/to/node.toml

For long-running deployments, build once and install the binary into ~/.cargo/bin:

cargo install --path crates/noxy-node --locked
noxy-node --config path/to/node.toml

A minimal config requires only [network] and [storage]:

[network]
network_alias             = "localnet-0"
chain_id                  = "noxy-localnet-0"
expected_genesis_hash_hex = "<64-char lowercase hex>"
genesis_path              = "configs/localnet-0/genesis.json"

[storage]
db_path = "var/localnet-0/node-0"

The RPC listener binds to 127.0.0.1:7300 by default. Two endpoints are enough to confirm the node booted correctly:

curl http://127.0.0.1:7300/v0/health
curl http://127.0.0.1:7300/v0/node/identity

See Getting started for the full config reference and startup sequence.

# install the NOXY CLI
$ npm i -g @noxy/cli

# run a local protocol devnet
$ noxy dev --profile local

# inspect the static wiki
$ open http://127.0.0.1:3000/wiki

$ pnpm add -g @noxy/cli
$ noxy dev --profile local
$ open http://127.0.0.1:3000/wiki

$ bun add -g @noxy/cli
$ noxy dev --profile local
$ open http://127.0.0.1:3000/wiki

$ cargo install noxy-cli
$ noxy dev --profile local
$ open http://127.0.0.1:3000/wiki

CLI

The noxy-cli binary covers wallet creation, key derivation, transaction signing, and read-only RPC queries. It uses the same canonical encoding rules as the node.

Install it once from the workspace:

cargo install --path crates/noxy-cli --locked

After install, noxy-cli is available on PATH:

# Create an encrypted keystore from a fresh BIP-39 mnemonic
noxy-cli wallet create \
    --keystore-out wallet.json \
    --mnemonic-out wallet.seed

# Resolve an account-name handle against the active profile
noxy-cli account-name resolve pavel@noxy-localnet-0

# Inspect a committed block
noxy-cli block get --height 42

For one-off use during development, cargo run -p noxy-cli -- <subcommand> works without installing.

Keystores are AES-256-GCM encrypted with an Argon2id-derived key. The passphrase is read from an environment variable, not from the command line.

Cryptography

Every consensus-critical digest is BLAKE3 with a domain prefix:

BLAKE3("NOXY-L0/v0.1/<domain>\0" || data)

Signature usage is split across two domains:

| Where | Algorithm | Purpose | |---|---|---| | Transaction envelope | ML-DSA-44 | Account authorization | | Consensus vote | ML-DSA-44 + Ed25519 (both required) | Validator vote in BFT mode |

ML-DSA-44 public keys are 1 312 bytes and signatures are 2 420 bytes. Ed25519 keys are 32 bytes and signatures are 64 bytes. A consensus vote with only one valid signature is rejected — neither algorithm is a fallback for the other.

Block ledger

Genesis is version 0 / height 0. The first ledger block is at height 1. Each BlockHeader commits to:

• prev_block_hash — chain linkage
• tx_root, state_root, event_root, evidence_root — Merkle roots over block content
• validator_set_hash — hash of the active validator set
• consensus_certificate_meta — height, view, certificate kind, signer bitmap

Blocks finalized by the BFT runtime are committed atomically: state writes, JMT nodes, block header and body, indexes, sidecars, and mempool removals land in a single RocksDB write batch.

Consensus modes

The node selects a consensus mode at startup via [consensus] mode:

• single_validator — a single block producer owns block production. No P2P. Suitable for local development.
• bft — HotStuff/Jolteon BFT runtime with up to 4 validators connected over QUIC. Hybrid PQ + classical signatures, view-based pacemaker, dedicated evidence channel for double-sign detection.

See Protocol architecture for the full block lifecycle.

RPC

The node exposes JSON over HTTP on 127.0.0.1:7300 by default.

Read

| Endpoint | Description | |---|---| | GET /v0/health | Liveness, uptime, latest DB version | | GET /v0/node/identity | Chain ID, genesis hash, latest state root, release version, commit SHA, protocol version | | GET /v0/state/root | Latest state root and version | | GET /v0/account/{id} | Account record | | GET /v0/account/{id}/nonce | Sequence nonce | | GET /v0/account/{id}/balance/{asset} | Asset balance | | GET /v0/account/{id}/names | Account names targeting this account | | GET /v0/account-name/{handle@chain} | Resolve a handle to an account | | GET /v0/block/{height} | Block by height | | GET /v0/block/by-hash/{hash} | Block by header hash | | GET /v0/block/{height}/txs | Transactions in a block | | GET /v0/events/{event_id} | Event record | | GET /v0/events/{event_id}/proof | Merkle proof for an event |

Submit and verify

| Endpoint | Description | |---|---| | POST /v0/tx/submit | Submit a base64-encoded TransactionEnvelope | | GET /v0/tx/{hash} | Transaction status: pending, committed, or unknown | | POST /v0/proofs/event/verify | Verify an event proof against the committed event root | | POST /v0/proofs/state/verify | Verify a state proof against the committed state root |

Economics

| Endpoint | Description | |---|---| | GET /v0/economics/summary | Inflation, total supply, treasury balance | | GET /v0/economics/treasury | Treasury state and multisig signers | | GET /v0/economics/treasury/spend/{spend_id} | Pending treasury spend | | GET /v0/economics/validator/{id} | Validator reward accumulator and bond totals | | GET /v0/economics/validator/{id}/bond/{account} | A single bond record | | GET /v0/economics/unbonding/{epoch} | Unbonding entries completing at this epoch | | GET /v0/economics/service-chain/{id}/bond | Service-chain registration bond | | GET /v0/economics/service-chain/{id}/usage/{epoch} | Service-chain epoch usage |

See Developer RPC for request and response shapes.

Operator model

Node startup is identity-bound. The node refuses to start when:

• chain_id in config does not match genesis.chain_id.
• expected_genesis_hash_hex does not match the computed genesis hash.
• An existing database at db_path was stamped by a different chain_id or genesis_hash.

The active validator set is derived from committed state, not from local config. A node that restarts with an existing database rejoins without wiping state. network_alias is informational; network safety is enforced by the pair (chain_id, genesis_hash).

Pages

• Getting started — install, config, startup sequence
• Protocol architecture — transaction envelope, block structure, consensus modes
• Accounts — account model, keys, addresses, handles
• Run a node — validator lifecycle, key roles, BFT cluster setup
• Developer RPC — full endpoint reference
• Developer wallet — wallet creation and keystore format