QUACDocs

Protocol

Post-quantum design

QUAC guarantees one thing above everything else: nothing classical can sign. This page explains how that's enforced at each layer, line by line, and what is still classical.

The three layers

Layer Who signs How QUAC enforces ML-DSA-65
Transactions Account holders The ML-DSA-only check in the ante handler (app/pqante.go)
Block votes Validators Consensus parameter validator.pub_key_types = ["ml_dsa_65"]
Key creation Users and operators Every key-type flag in quacd defaults to ml_dsa_65 (cmd/quacd/cmd/pqdefaults.go)

The first two are consensus rules: every honest node applies them, so breaking them would need more than two thirds of the voting power. The third is a convenience that stops users from creating keys the chain would reject.

Layer 1: transactions

What an ante handler is

In the Cosmos SDK, every transaction passes through an ante handler before its messages run. The default chain of checks:

  • validates basic fields,
  • deducts fees,
  • checks account sequence numbers,
  • registers the signer's public key on first use,
  • consumes gas for signature verification,
  • verifies the signatures.

If any step fails, the transaction is rejected: from the mempool in CheckTx, or with no state change in a block.

QUAC wraps that chain with one extra check that runs first. It's wired in at the end of setAnteHandler in app/app.go:

anteHandler, err := ante.NewAnteHandler(ante.HandlerOptions{
    AccountKeeper:   app.AccountKeeper,
    BankKeeper:      app.BankKeeper,
    SignModeHandler: txConfig.SignModeHandler(),
    FeegrantKeeper:  app.FeeGrantKeeper,
    SigGasConsumer:  PQSigVerificationGasConsumer, // QUAC: ML-DSA gas, see below
    // ...
})
// ...
// Only ML-DSA-65 signers get past this point.
app.SetAnteHandler(NewPQOnlyAnteHandler(app.AccountKeeper, anteHandler))

Running first matters. A transaction from a classical key fails before any fee is charged or any signature is verified, so nobody can pay to put a classical public key on chain.

IsPQPubKey: what counts as post-quantum

func IsPQPubKey(pk cryptotypes.PubKey) bool {
    switch pk := pk.(type) {
    case *mldsa65.PubKey:
        return true
    case multisig.PubKey:
        members := pk.GetPubKeys()
        if len(members) == 0 {
            return false
        }
        for _, m := range members {
            if !IsPQPubKey(m) {
                return false
            }
        }
        return true
    default:
        return false
    }
}
  • An ML-DSA-65 key passes.
  • A multisig passes only if every member is post-quantum, checked recursively, so nested multisigs are covered too. One classical member would let a quantum attacker forge that member's share of the signatures, so it taints the whole key.
  • An empty multisig is rejected: it has no member that could sign.
  • Everything else fails: secp256k1, secp256r1, Ed25519, BLS, Ethereum-style keys, and any key type added to the SDK later. The list is an allowlist, not a blocklist.

checkPQSigners: checking every signer

A Cosmos transaction can have several signers. For each one, the check looks at two possible sources of a public key:

for i, signer := range signers {
    // Key supplied in the transaction itself.
    if i < len(pubKeys) && pubKeys[i] != nil {
        if !IsPQPubKey(pubKeys[i]) {
            return errorsmod.Wrapf(sdkerrors.ErrInvalidPubKey,
                "signer %d uses %T; only %s keys are accepted on this chain", i, pubKeys[i], PQKeyType)
        }
        continue
    }

    // Key already registered on the account.
    acc := ak.GetAccount(ctx, signer)
    if acc == nil || acc.GetPubKey() == nil {
        if simulate {
            continue
        }
        return errorsmod.Wrapf(sdkerrors.ErrInvalidPubKey,
            "signer %d has no public key; the first transaction must include an %s key", i, PQKeyType)
    }
    if !IsPQPubKey(acc.GetPubKey()) {
        return errorsmod.Wrapf(sdkerrors.ErrInvalidPubKey,
            "signer %d account holds a %T key; only %s keys are accepted on this chain", i, acc.GetPubKey(), PQKeyType)
    }
}
  1. Key in the transaction. An account's first transaction carries its public key in the signer info. That key must pass IsPQPubKey.
  2. Key already on the account. Later transactions usually omit the key, because the chain stored it the first time. The check reads the stored key and applies the same test. This closes a back door: a classical key placed in genesis (where the ante handler never ran) still can't sign.
  3. No key anywhere. Outside simulation, a signer with no key is rejected with a clear message. Without a key there's nothing to verify against, and the SDK's later steps would fail anyway.

Simulation. Wallets estimate gas by simulating a transaction before signing it, and a simulated first transaction may not carry a key yet. The check lets that through. The real transaction must carry the key, and is checked then.

PQSigVerificationGasConsumer: honest gas estimates

The SDK charges gas for each signature verification through a "signature gas consumer". QUAC replaces the default with:

func PQSigVerificationGasConsumer(meter storetypes.GasMeter, sig signing.SignatureV2, params authtypes.Params) error {
    if _, ok := sig.PubKey.(*secp256k1.PubKey); ok {
        meter.ConsumeGas(params.SigVerifyCostMlDsa65, "ante verify: ml_dsa_65 (simulated)")
        return nil
    }
    return ante.DefaultSigVerificationGasConsumer(meter, sig, params)
}

The reason is a detail of the SDK. When it simulates a transaction from an account with no key on chain, it substitutes a placeholder secp256k1 key so gas can still be metered. On a normal chain that charges the secp256k1 price. On QUAC, real secp256k1 signers never reach this function (the ML-DSA-only check rejected them first), so any secp256k1 key seen here is that placeholder. Charging the ML-DSA-65 price instead keeps gas estimates for first transactions accurate.

For real ML-DSA-65 keys and ML-DSA multisigs, the SDK default applies: SigVerifyCostMlDsa65 gas per signature (750 by default, an x/auth parameter that governance can change).

Errors you will see

Situation Code Message
Classical key in the transaction 8 (invalid pubkey) signer 0 uses *secp256k1.PubKey; only ml_dsa_65 keys are accepted on this chain
Classical key stored on the account (genesis) 8 signer 0 account holds a *secp256k1.PubKey key; …
First transaction without a key 8 signer 0 has no public key; the first transaction must include an ml_dsa_65 key

Layer 2: validator block signatures

CometBFT validators sign every prevote and precommit with their consensus key, a separate key held by the node (config/priv_validator_key.json), not the operator's account key.

The allowed consensus key types are a consensus parameter, stored on chain by the x/consensus module:

"consensus": {
  "params": {
    "validator": { "pub_key_types": ["ml_dsa_65"] }
  }
}

With only ml_dsa_65 listed:

  • MsgCreateValidator with any other consensus key type is rejected by x/staking.
  • Consensus key rotation (new in SDK v0.55) can only rotate to another ML-DSA-65 key.
  • CometBFT accepts only ML-DSA-65 votes in commits.

You don't have to edit this by hand. quacd init writes the chosen consensus algorithm into genesis, and QUAC makes ml_dsa_65 the default, so a plain quacd init already produces an ML-DSA-only chain. The testnet genesis script also asserts it:

assert g["consensus"]["params"]["validator"]["pub_key_types"] == ["ml_dsa_65"]

Cost: each commit carries one 3,309-byte signature per validator. With 100 validators that is about 330 KB per block for signatures alone, which is why QUAC starts with a small validator set. CometBFT v0.40 raised MaxSignatureSize and the per-validator commit size limit to fit ML-DSA-65.

Layer 3: CLI defaults

cmd/quacd/cmd/pqdefaults.go walks the whole quacd command tree once at start-up and switches the default of every key-algorithm flag:

var pqKeyFlags = []string{
    "key-type",           // keys add, testnet: account keys
    "algo",               // older alias some commands still use
    "consensus-key-algo", // init, testnet: validator consensus keys
}

func setPQFlagDefaults(cmd *cobra.Command) {
    for _, name := range pqKeyFlags {
        for _, fs := range []*pflag.FlagSet{cmd.Flags(), cmd.PersistentFlags()} {
            if f := fs.Lookup(name); f != nil {
                _ = f.Value.Set(quacapp.PQKeyType)
                f.DefValue = quacapp.PQKeyType
            }
        }
    }
    for _, c := range cmd.Commands() {
        setPQFlagDefaults(c)
    }
}

It is called from NewRootCmd after all commands, including auto-generated ones, are attached. So quacd keys add mywallet creates an ML-DSA-65 key, and quacd init creates an ML-DSA-65 consensus key, without any flags. You can still pass --key-type secp256k1; the chain will refuse that key, as the Quickstart shows.

Addresses and quantum attacks

An address is SHA-256 of the public key, truncated to 20 bytes. Hashes are not broken by Shor's algorithm. Grover's algorithm gives only a quadratic speed-up against hash preimages, which leaves a 160-bit hash with about 80 bits of quantum security against finding a key for a given address.

More importantly, on QUAC knowing the public key doesn't help an attacker: it is an ML-DSA-65 key, and recovering its private key is the lattice problem that ML-DSA's security rests on.

What is still classical

Component Algorithm Risk Plan
Node-to-node links (P2P) Ed25519 node identity, X25519 key exchange, ChaCha20-Poly1305 A quantum attacker could impersonate a peer or decrypt recorded gossip. Blocks and transactions are public anyway, and consensus votes are still ML-DSA-signed. Post-quantum P2P handshake in CometBFT. See Roadmap.
TLS to public endpoints Whatever Cloudflare negotiates (hybrid X25519+ML-KEM where the browser supports it) Same as any website. Out of chain scope.
Governance — A governance proposal could in principle add a classical key type back to pub_key_types, or a software upgrade could remove the ML-DSA-only check. A public commitment that QUAC will never do this.

See Security model for the full picture.

Edit this page on GitHub