QUACDocs

Protocol

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.mldsa65 key type covers keyring storage, mnemonic recovery, transaction signing and verification, and an x/auth gas parameter for verification (SigVerifyCostMlDsa65).
  • Validator consensus keys: ml_dsa_65 can be listed in consensus_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:

  1. Chain identity (app/config.go): quac address prefixes and the uquac denom, set before anything else runs. → Accounts and transactions
  2. ML-DSA-only ante handler (app/pqante.go): wraps the SDK's transaction checks. → Post-quantum design
  3. Monetary policy (app/tokenomics.go): inflation band, supply cap and coin metadata, baked into default genesis. → Monetary policy
  4. 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

  1. 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).
  2. 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.
  3. Proposal. The block proposer for this height takes transactions from its mempool into a block proposal.
  4. 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.
  5. 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).
  6. 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.

Edit this page on GitHub