This directory is the documentation set for the 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.
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.
| 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 |
| 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 |
| Document |
Covers |
| Running a node |
Requirements, install, and starting a node |
| Configuration |
Environment variables, ports, and data directories |
| Maintenance |
Monitoring, upgrades, restart behaviour, recovery |
| 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 |
| 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 |
| 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 |
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.
- 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.