README.md

QNet Blockchain documentation

This directory is the documentation set for QNet Blockchain: the protocol the node implements, the economics it enforces, how to run a node, and the interfaces applications build against. Every document here was written against the source tree in this repository. Where a document and the code disagree, the code is authoritative — report the discrepancy rather than trusting the document.

The system in short

A single elected producer streams microblocks on a one-second slot. Producer rotation happens every ROTATION_INTERVAL_BLOCKS = 30 blocks. Finality comes from Checkpoint-BFT v2: a checkpoint is taken every CHECKPOINT_INTERVAL = 30 microblocks and certified by a quorum certificate, and a checkpoint is committed by the two-chain rule; each MACROBLOCK_INTERVAL = 90-microblock window seals its macroblock on that commit. Every consensus, identity and gossip signature is ML-DSA-65 (FIPS 204, CRYSTALS-Dilithium3). Bulk block and consensus traffic runs over QUIC; the node additionally makes HTTP-over-TCP node-to-node calls for block fetch, peer authentication and health probes, so TCP 9876/9877/8001 are required alongside UDP 10876. State is a flat account model over 45-character EON addresses, committed in a sparse Merkle tree. The protocol defines two node types, Light and Super.

Understand the protocol

Document	Covers
Whitepaper	The protocol as a whole, in one document
Architecture overview	Components, crate layout, and how a block moves through the node
Consensus	Microblock production, producer rotation, Checkpoint-BFT finality, failover
Cryptography	Signature scheme, hashes, address derivation, transport security
State	Accounts, the state commitment, RocksDB storage layout, transaction types
Networking	QUIC transport, handshake and peer identity, message types, discovery

Economics

Document	Covers
Economics overview	Emission schedule, reward pools, claims, transaction fees
Node activation	Phase 1 and Phase 2 activation, node registration, node types
1DEV token	The external 1DEV token on Solana and its role in Phase 1

Run a node

Document	Covers
Running a node	Requirements, install, and starting a node
Configuration	Environment variables, ports, and data directories
Maintenance	Monitoring, upgrades, restart behaviour, recovery

Build on it

Document	Covers
Developer overview	What the testnet offers developers, who talks to what, the limits to design around
dApp integration	The wallet provider a web page talks to: discovery, methods, results, errors, events
Sign-in	Signing users in with a wallet signature, checked on the server
Transactions	Transfer, token transfer, contract call and deploy: signed text, gas, fees, submit, status
Smart contracts	The WASM contract VM, host functions, limits, events, templates, token standards
SDK	@aiqnet/sdk: wallet connection, sign-in, transaction builders, node client, key files
CLI	The qnet command: keys, reads, transfers, contract deploys and calls
RPC API	The HTTP JSON-RPC and REST surface exposed by a node
Security	What developers must do to keep users and servers safe
1DEV burn contract	The Solana Anchor program behind Phase 1 activation burns
QNet Link v1	aiqnet.io ↔ wallet requests: the encrypted phone link, its relay, qnet_activateNode, test vectors
Light node messages	What the wallet key, the ping key and the device key sign for a light node: binding, answers, the device check, statements, status, test vectors
GALC v2 capsule	The genesis-signed capsule a wallet roots its light-client walk at, a few macroblocks below the certified head: fields, signatures, the node route, client rules, test vectors

Use the applications

Document	Covers
Mobile wallet	The React Native wallet and Light node client
Browser wallet	The browser extension wallet
Explorer	The block explorer front end and its backend
CLI	The read-only Python command-line tool

Repository documents

Document	Covers
README	Repository entry point
Contributing	Prerequisites, build and test commands, PR expectations
Security	Vulnerability disclosure policy and scope
Third-party notices	Third-party dependencies and their licences
Licence	Business Source License 1.1 for the node software

Suggested reading order

If you are new to the codebase, read architecture/overview.md first, then architecture/consensus.md and architecture/state.md. Operators can go straight to operators/running-a-node.md and operators/configuration.md. Application developers start with developers/overview.md.

Conventions used here

• Constants are given by their code name and value, for example MACROBLOCK_INTERVAL = 90. If a document states a constant, that constant exists in the source under that name.
• Limits and operating parameters are stated plainly where the mechanism they bound is described.
• Credentials, private keys and endpoint addresses are operator-supplied and are referred to by their variable name only.