Skip to main content
Canonical specification of the QBTC chain code. Source of truth for implementers, auditors, and researchers. Citations refer to the QBTC source code at github.com/btcq-org/qbtc.

​
1. Consensus

QBTC consensus is CometBFT, forked to replace Ed25519 with ML-DSA (CRYSTALS-Dilithium, FIPS 204) throughout the consensus signing path.
  • Source: github.com/btcq-org/cometbft.
  • Replaces crypto/ed25519 with crypto/mldsa for validator consensus keys, vote signing, and block-commit signatures.
  • ML-DSA-65 parameter set (NIST security level 3).
  • Signature size: 3309 bytes (~3.3 KB). Public key size: 1952 bytes (~2.0 KB). Per FIPS 204.
There is no ECDSA or Ed25519 dependency in the consensus path. The chain is post-quantum from genesis.

​
1.1 Validator set

  • Standard Cosmos x/staking for bonding and validator selection.
  • Validator consensus key: ML-DSA. Operator key: standard Cosmos signing curve.
  • Maximum validator set size and unbonding period: parameters at genesis (TBD before mainnet).

​
2. The custom module: x/qbtc

Single custom module covering everything QBTC-specific:

​
2.1 The Bitcoin UTXO mirror

The chain state contains a mirror of the Bitcoin UTXO set:
  • Initial state: built from a snapshot generated by the utxo-indexer binary, run against a Bitcoin full node at a reference height.
  • Continuous updates: each new Bitcoin block is ingested via ebifrost after validator attestation, and the mirror is updated (new outputs added, spent outputs reconciled).
  • Per-UTXO claim entry: each UTXO has an EntitledAmount field representing its outstanding QBTC claim. Set at ingestion, decremented to 0 upon successful claim.

​
2.2 Block ingestion (ebifrost)

Each validator runs a bifrost sidecar that connects to a Bitcoin RPC, watches for new blocks, signs them with the validator’s ML-DSA consensus key, and gossips them to peer validators via LibP2P. The ebifrost module accepts these signed blocks via gRPC and aggregates attestations. A block is ingested into QBTC state once more than 2/3 of bonded validator power has attested. Per x/qbtc/keeper/handler_msg_report_block.go:67–68:
// require more than 2/3 of total staking power to attest the block
The block is then injected as a special transaction in the next QBTC block via PrepareProposal/ProcessProposal.

​
2.3 Claim mechanism

A holder claims QBTC by submitting a MsgClaimWithProof transaction. Per proto/qbtc/qbtc/v1/msg_claim_with_proof.proto:18–64:
  • The message contains a ZK PLONK proof attesting ownership of a Bitcoin address, plus a list of up to 50 UTXOs belonging to that address, plus a destination QBTC address.
  • The on-chain verifier checks the proof against the public inputs (Hash160 of the BTC address, destination QBTC address).
  • For each referenced UTXO, the handler checks:
    1. The UTXO exists in QBTC’s state.
    2. Its EntitledAmount > 0 (not previously claimed).
    3. Its address matches the one proven.
  • If all checks pass, the cumulative EntitledAmount is transferred to the destination QBTC address, and each UTXO’s entry is set to 0.
Per x/qbtc/keeper/handle_msg_claim_with_proof.go:
  • Lines 59–169: claim verification and disbursement.
  • Lines 172–183: atomic batch handling via cache context (all-or-nothing).
Public inputs to the ZK circuit reveal:
  • Hash160 of the BTC address being claimed.
  • Destination QBTC address.
Hidden inputs to the ZK circuit:
  • BTC public key.
  • BTC private key.
  • ECDSA signature.
The BTC public key is never broadcast, making the migration itself quantum-safe.

​
2.4 Double-claim prevention and taint propagation

A claimed UTXO’s EntitledAmount is set to 0. Subsequent attempts to claim the same UTXO fail at the validation step (line 66, 123 of handle_msg_claim_with_proof.go). When the ebifrost module ingests a new Bitcoin block, the claimed status propagates to descendant UTXOs. If a transaction spends from any claimed UTXO, the outputs of that transaction inherit the claimed status in proportion to the value contributed by claimed inputs. A child of a fully-claimed parent has EntitledAmount = 0 and cannot be claimed. Propagation makes governance reclamation (§2.5) permanent: once a UTXO is reclaimed, the Bitcoin holder cannot recover the QBTC entitlement by spending the UTXO through Bitcoin to a new address.

​
2.5 Minting paths, the Reserve Module, and validator emission

There are two minting paths, and only two. Path 1: User claim. A successful MsgClaimWithProof mints QBTC into the claimer’s account, equal to the sum of the referenced UTXOs’ BTC values. Path 2: Governance reclamation. Through standard x/gov proposals, validators vote on which dormant exposed-key UTXOs (older than 17 years, with on-chain public keys) to reclaim. The voting period is the standard Cosmos parameter (default ~2 weeks, set by governance). When a proposal passes:
  1. Each referenced UTXO is marked as claimed in the mirror (EntitledAmount → 0), identically to a user claim.
  2. QBTC equal to the reclaimed BTC value is minted on the chain and split across three on-chain accounts at a fixed ratio:
    • 90% → Reserve Module (funds validator emission)
    • 5% → Development Fund (governance-gated spend)
    • 5% → Ecosystem Fund (governance-gated spend)
  3. Descendant UTXOs inherit the claimed status via the propagation described in §2.4.
The Reserve Module is the only direct source of per-block validator emission. The Development and Ecosystem funds are on-chain accounts spent via separate x/gov proposals.

​
Validator emission, from the Reserve Module

Per x/qbtc/keeper/network_manager.go:24–47:
  • ProcessNetworkReward() is called per block.
  • It computes:
  • The released amount is transferred from ReserveModuleName to the standard Cosmos fee collector, which then distributes to validators and delegators via x/distribution.
Constants (per constants/constants.go):
  • EmissionCurve = 5
  • BlocksPerYear = 5,256,000 (10 × 60 × 24 × 365, i.e. 10 blocks per minute)
The Reserve Module’s balance evolves as a function of governance activity: it grows when reclamation proposals pass and decreases as validators are paid.

​
Cap invariant

At any time:
The cap holds because no Bitcoin UTXO can be claimed twice (the claimed_flag propagates per §2.4), each claim mints exactly the BTC amount of that UTXO, and Bitcoin’s total supply is capped at 21M. No inflationary minting exists anywhere in the chain code. See Tokenomics for the economic framing.

​
2.6 Governance

QBTC uses standard Cosmos x/gov. Proposals follow the standard voting period, deposit requirements, and threshold rules. Dormant-UTXO reclamation proposals (§2.5 Path 2) are enacted through x/gov rather than as automatic chain rules. The validator set sets the activation parameters (UTXO categories, cutoffs, dispute windows) through governance.

​
3. Tokenomics summary

  • Total supply cap: 21 million QBTC.
  • Initial claim mirror: sized to match the Bitcoin UTXO set at the mirror’s reference height.
  • Reserve Module: a module account that holds QBTC reclaimed by governance, drawn down per block to validators via the emission formula above.
  • Development Fund (5%) and Ecosystem Fund (5%) from each governance reclamation. Both governance-gated.
  • No genesis allocation to any party.
See Tokenomics for the full breakdown.

​
4. Modules in use (Cosmos SDK standard)

Standard SDK semantics apply for all of these.

​
5. Binaries

​
References

  • github.com/btcq-org/qbtc (chain implementation)
  • github.com/btcq-org/cometbft (forked CometBFT)
  • Standard Cosmos SDK documentation at docs.cosmos.network.
  • NIST FIPS 204 (ML-DSA specification).
Last modified on June 12, 2026