Architecture
QUAC is a Cosmos SDK application chain. This page explains how the parts fit together and where QUAC differs from a stock Cosmos SDK chain.
The stack
┌───────────────────────────────────────────────────────────────┐
│ Clients: quacd CLI, explorer, faucet, wallets │
│ REST :1317 gRPC :9090 CometBFT RPC :26657 │
└───────────────┬───────────────────────────────┬───────────────┘
│ │
┌───────────────▼───────────────────────────────▼───────────────┐
│ QUAC application (app/) Cosmos SDK v0.55.1 │
│ │
│ Ante handler: ML-DSA-only check → SDK default chain │
│ (app/pqante.go) fees, sequence, sigs │
│ │
│ Modules: auth bank staking mint distribution slashing │
│ gov upgrade feegrant authz evidence epochs │
│ consensus genutil vesting │
└───────────────────────────────┬───────────────────────────────┘
│ ABCI (in-process)
┌───────────────────────────────▼───────────────────────────────┐
│ CometBFT v0.40.0: P2P gossip :26656, BFT consensus, mempool │
│ Validator votes signed with ML-DSA-65 consensus keys │
└───────────────────────────────────────────────────────────────┘
CometBFT orders transactions into blocks and runs consensus. It knows nothing about balances or accounts. It hands each block to the application over ABCI (Application Blockchain Interface), in the same process.
The application (app/) is the state machine: it checks and executes transactions and keeps all chain state (balances, stakes, parameters) in an IAVL Merkle tree.
Why Cosmos SDK
Cosmos SDK v0.55 and CometBFT v0.40 are the first releases with native ML-DSA-65 support:
- Account keys: the
cosmos.crypto.mldsa65key type covers keyring storage, mnemonic recovery, transaction signing and verification, and anx/authgas parameter for verification (SigVerifyCostMlDsa65). - Validator consensus keys:
ml_dsa_65can be listed inconsensus_params.validator.pub_key_types. CometBFT v0.40 raised its signature size limits so 3,309-byte votes fit in commits.
So QUAC needs no fork of either project. QUAC's own code turns the support on and makes it the only option. That is a small amount of code, and it is what the next pages document.
Repository layout
app/ the chain application
app.go module wiring (derived from SDK simapp v0.55.1)
config.go chain identity: denom, address prefixes, key type
pqante.go ML-DSA-only transaction check and gas accounting
tokenomics.go mint policy, supply cap, coin metadata
export.go genesis.go … state export, genesis types, upgrades
params/ encoding configuration
cmd/
quacd/ node + CLI binary
cmd/root.go root command, client config
cmd/commands.go command tree, server config (min gas price)
cmd/pqdefaults.go makes ML-DSA-65 the default for every key flag
cmd/testnet.go in-process multi-node testnet helpers
quacfaucet/ testnet faucet service
scripts/devnet.sh single-node local chain
deploy/testnet/ genesis ceremony and server install for quac-testnet-1
website/ quantcoin.world: landing page, explorer, faucet page
docs/ these docs (rendered to docs.quantcoin.world)
tools/docsgen/ the docs site generator
Modules
QUAC runs the standard Cosmos SDK module set. The ones that matter most:
| Module | Role on QUAC |
|---|---|
auth |
Accounts, sequence numbers, signature verification parameters (including the ML-DSA-65 gas cost). |
bank |
Balances and transfers. Carries the QUAC denomination metadata. |
staking |
Validators, delegations, voting power. Bond denom is uquac. |
mint |
Block rewards under QUAC's inflation band and supply cap. |
distribution |
Splits rewards and fees among validators and delegators; keeps a community pool. |
slashing |
Penalizes validators that double-sign or stay offline. |
gov |
On-chain proposals and parameter changes. |
upgrade |
Coordinated software upgrades at a chosen height. |
consensus |
Stores CometBFT consensus parameters on chain, including the allowed validator key types. |
What QUAC adds to a stock SDK app
The application wiring in app/app.go follows the SDK reference app closely. QUAC changes four things, each covered in its own page:
- Chain identity (
app/config.go):quacaddress prefixes and theuquacdenom, set before anything else runs. → Accounts and transactions - ML-DSA-only ante handler (
app/pqante.go): wraps the SDK's transaction checks. → Post-quantum design - Monetary policy (
app/tokenomics.go): inflation band, supply cap and coin metadata, baked into default genesis. → Monetary policy - CLI defaults (
cmd/quacd/cmd/pqdefaults.go): ML-DSA-65 as the default for every key-type flag. → Post-quantum design
Life of a transaction
- A wallet builds a transaction, signs it with the account's ML-DSA-65 private key, and broadcasts it to a node (REST
POST /cosmos/tx/v1beta1/txs, gRPC, or CometBFT RPC). - CheckTx. The node runs the ante handler in check mode. The ML-DSA-only check runs first; then the SDK checks fees against the node's minimum gas price, account sequence and signature. Transactions that pass enter the mempool and are gossiped to peers.
- Proposal. The block proposer for this height takes transactions from its mempool into a block proposal.
- Consensus. Validators prevote and precommit, each vote signed with their ML-DSA-65 consensus key. With more than two thirds of voting power precommitted, the block is final.
- FinalizeBlock. Every node executes the block: begin-block logic (minting, reward distribution, slashing), then each transaction (the ante handler again in deliver mode, then the messages), then end-block logic (validator set updates).
- Commit. The new state root becomes the block's app hash, and the next block's header records it.
Ports
| Port | Service | Notes |
|---|---|---|
| 26656 | CometBFT P2P | Node-to-node gossip. |
| 26657 | CometBFT RPC | Blocks, transactions, broadcast. Local only on the public testnet. |
| 1317 | REST API (gRPC-gateway) | What the explorer and most wallets use. |
| 9090 | gRPC | The devnet and testnet move this to 9190, because 9090 is often taken by monitoring tools. |