Documentation Index
Fetch the complete documentation index at: https://docs.qbtc.net/llms.txt
Use this file to discover all available pages before exploring further.
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:
| Subfolder | Responsibility |
|---|
keeper/ | State and message handlers for claims, UTXO mirror, network rewards |
types/ | Protobuf message types, validation |
module/ | Cosmos module wiring, genesis state loader |
zk/ | PLONK circuits, on-chain verifier |
ebifrost/ | ”Enshrined bifrost”: accepts gossiped BTC blocks from validator sidecars |
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:
- The UTXO exists in QBTC’s state.
- Its
EntitledAmount > 0 (not previously claimed).
- 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:
- Each referenced UTXO is marked as claimed in the mirror (
EntitledAmount → 0), identically to a user claim.
- 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)
- 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:
release = reserve_balance / (EmissionCurve × BlocksPerYear)
- 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 = 5BlocksPerYear = 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:
total_QBTC_minted = sum(user claims) + sum(governance reclamations)
≤ 21,000,000 QBTC
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)
| Module | Purpose |
|---|
auth | Accounts |
bank | Native token transfers |
staking | Validator bonding |
slashing | Validator misbehavior penalties |
distribution | Reward distribution |
gov | On-chain governance |
upgrade | Coordinated upgrades |
evidence | Misbehavior evidence |
feegrant | Fee delegation |
authz | Authorization grants |
consensus | Consensus parameters |
params | Module parameters |
epochs | Time-based triggers |
group | Multi-account governance |
crisis | Invariant checks |
| IBC v10 | Inter-Blockchain Communication |
| ICS-27 | Interchain accounts |
| IBC transfer | Cross-chain token transfers |
wasmd (CosmWasm) | Smart contracts |
tokenfactory | Token issuance |
5. Binaries
| Binary | Purpose |
|---|
qbtcd | Chain daemon |
bifrost | Bitcoin block watcher sidecar |
proof-service | PLONK prover (HTTP service) |
zkprover | PLONK prover (CLI) |
utxo-indexer | Genesis UTXO snapshot builder |
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).
