> ## 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.

# Protocol Specification

> Canonical specification of the QBTC chain: state, ingestion, claim verification, taint propagation, emission, and governance.

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:
  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:
  ```
  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 = 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:

```
total_QBTC_minted = sum(user claims) + sum(governance reclamations)
                  ≤ 21,000,000 QBTC
```

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](tokenomics.md) 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](tokenomics.md) 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                  |

Standard SDK semantics apply for all of these.

## 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).