Skip to main content
Test network. A test network has run since March 2026 and may be reset. Mainnet is a fresh genesis, planned for early 2027. The instructions below stand up a node against the current public test network. Endpoints, the chain ID, and the pinned version can change before mainnet — always cross-check the chain repository for the latest values.
Launch build. This page describes the launch build: ML-DSA-65 keys, and a Bitcoin reader built into qbtcd. The current test network runs an earlier build, and until the relaunch the install script installs that earlier build.
A QBTC node is one process, qbtcd: the chain daemon (Cosmos SDK with the ML-DSA CometBFT fork). Validators also need a Bitcoin full node (Bitcoin Core with RPC enabled). The Bitcoin reader inside qbtcd reads new Bitcoin blocks from it, and the validator attests those blocks in its consensus votes. The Bitcoin node can run on the same machine or a separate one. See Architecture for how the parts fit together.

Prerequisites

  • A Linux host (the installer targets linux-amd64 release binaries and systemd).
  • curl, tar, sudo, sha256sum, and systemctl available on the host.
  • Validators only: a reachable Bitcoin Core node with RPC enabled (host, port, RPC username, and password).
  • For building from source instead of using release binaries: Go 1.26+ and Make.
The chain repo ships an install script that downloads the qbtcd binary to /usr/local/bin, optionally sets up Cosmovisor for upgrade management, initializes the node home directory, downloads the genesis file, and installs a systemd service.
To pin a specific version (recommended for reproducibility — check the releases page for the current version):
or via environment variable:
Piping a remote script straight into bash runs unreviewed code as your user. If you prefer to inspect it first:

What the installer creates

Configure the Bitcoin reader (validators)

Validators must turn on the Bitcoin reader and point it at a Bitcoin Core node they trust. Edit the [btc_reader] section of ~/.qbtc/config/app.toml:
The reader fetches each block from your Bitcoin node, checks its hash and merkle root, and caches it. Your validator then attests the cached blocks in its consensus votes. A full node that does not validate can leave enable = false.

Start the node

Check status and follow logs:
To start automatically on boot:

Ports

Open 26656 to peers so your node can sync. Keep 26657, 9090, and the Bitcoin RPC port firewalled to localhost or trusted hosts.

State sync (fast bootstrap)

Syncing a QBTC node from genesis can take a long time — blocks contain ML-DSA signatures and Bitcoin block data, so the chain grows quickly. CometBFT state sync lets a new node download a recent state snapshot from peers and skip replaying history, reducing bootstrap time from hours to minutes.

Configure state sync

  1. Get the current trust height and trust hash. The QBTC explorer statesync page always shows fresh values. Copy them from there — they change as the chain advances and the values below will be stale by the time you read this.
  2. Edit ~/.qbtc/config/config.toml — find the [state-sync] section and fill in the values from the explorer:
    The height and hash above are illustrative — always use the current values from the explorer.
  3. Enable snapshots in ~/.qbtc/config/app.toml so your node can also serve state sync to others:
  4. Reset chain data if the node has already started syncing from genesis:
  5. Start the node and watch for state sync to kick in:
State sync skips verifying the full block history — you are trusting that the snapshot is correct. Always use a trust height and hash from the official explorer or a validator you know personally. Do not copy values from anonymous posts.

Building from source

If you would rather build the binaries yourself:
make build produces the chain binaries into ./build/: qbtcd, zkprover (the local ZK proof CLI — see Architecture), proof-service (the optional hosted PLONK prover), and utxo-indexer (builds the bootstrap UTXO seed). Run the test suite with:
For a throwaway local devnet, the repo includes a helper:

Keeping your node updated

New qbtcd releases are published on the releases page. There are two kinds of update, and they are handled differently.
Stay current. When the team schedules an on-chain upgrade, a node still running the old binary can halt or fall out of consensus at the upgrade height. Running behind also means missing blocks and risking downtime jailing if you validate.

Minor / patch releases (no consensus break)

For a routine version bump, you replace the binaries directly — no governance proposal. The qbtcd binary lives in two places, and both must be updated so it does not matter whether systemd launches the daemon directly or through Cosmovisor:
  1. /usr/local/bin/qbtcd
  2. ~/.qbtc/cosmovisor/current/bin/qbtcd

Major / consensus-breaking upgrades (governance)

Consensus-breaking upgrades ship through an on-chain software-upgrade proposal and are applied by Cosmovisor at the scheduled block height. Because the installer sets DAEMON_ALLOW_DOWNLOAD_BINARIES=false, Cosmovisor will not fetch the binary for you — stage it ahead of the upgrade height:
At the upgrade height Cosmovisor stops the old binary, switches the current symlink, and (with DAEMON_RESTART_AFTER_UPGRADE=true) restarts automatically. Follow the release notes for the exact upgrade name and height.

Chain ID for transactions

The live test network reports its chain ID as qbtc (confirmed from …/cosmos/base/tendermint/v1beta1/blocks/latest). The installer’s client config currently sets a different value, so if you sign and broadcast transactions, pass the chain ID explicitly to avoid a signature-mismatch error:
Always confirm the current chain ID from a live block before broadcasting — it changes at mainnet relaunch.

Querying without your own node

To read chain state without running a full node, use the public Cosmos REST gateway documented in the API Reference. It proxies the standard /cosmos/... module queries and the x/qbtc params route. CometBFT RPC is not exposed.

Becoming a validator

Validator creation is the standard Cosmos SDK x/staking flow (qbtcd tx staking create-validator), with three QBTC-specific differences:
  1. Consensus keys are ML-DSA-65, not Ed25519. qbtcd init creates an ML-DSA-65 consensus key by default. The validator pubkey you submit has @type /cosmos.crypto.mldsa65.PubKey. You get it from qbtcd comet show-validator, as on any Cosmos chain.
  2. Account keys are ML-DSA-65 only. The chain rejects all other key types, including secp256k1, ed25519 and multisig. qbtcd keys add creates an ML-DSA-65 key by default (--key-type ml_dsa_65).
  3. A validator must also run the Bitcoin reader. Validators attest Bitcoin blocks in their consensus votes (vote extensions). A Bitcoin block enters QBTC state only when validators with more than 2/3 of voting power attest it. Enable the reader before you bond (see Configure the Bitcoin reader).
You do not send tokens to anyone to create a validator. create-validator bonds QBTC from your own validator account — it moves your own balance from liquid to bonded (self-delegation). There is no deposit address to pay into. To fund your account on the current test network (which has no public faucet), generate your validator account first and ask the team for test-network QBTC to your qbtc1… address (via Discord).

Network parameters (current test network)

Verified live; all change at mainnet relaunch.
Never run the same consensus key on two nodes. Double-signing is slashed 5% and tombstones the validator permanently. For multiple validators, each needs its own node home, its own consensus key, its own Bitcoin reader configuration, and its own funded account.

Step by step

  1. Sync a full node and enable the Bitcoin reader (sections above). Wait until qbtcd is caught up (qbtcd status → sync_info.catching_up: false).
  2. Create your validator account key (this is an ML-DSA-65 key):
    The HD derivation path for QBTC accounts is m/44'/118'/0'/0/0. QBTC derives a 32-byte seed on that path from your BIP-39 mnemonic and uses it to generate the ML-DSA-65 key. The same mnemonic therefore gives a different address on QBTC than on a secp256k1 Cosmos chain. qbtcd keys add handles this automatically.
  3. Fund the account. On the test network, send your qbtc1… address to the team and they fund it. Confirm the balance:
  4. Get your consensus pubkey:
  5. Write validator.json — paste the pubkey output verbatim into the pubkey field:
    amount is your self-bond, in base units (1000000000qbtc = 10 QBTC). It must be ≤ your funded balance.
  6. Submit the transaction:
  7. Verify you are bonded:
    or via the public gateway: …/qbtc-rpc/cosmos/staking/v1beta1/validators.

Placement and latency

QBTC blocks are large, and this makes network latency a real operational consideration. ML-DSA-65 consensus signatures are about 3.3 KB each (versus 64 bytes for Ed25519), and when a Bitcoin block is ingested it is shipped into a QBTC block that can be very large. A validator that is network-distant from the rest of the active set may not receive and precommit these large blocks within the consensus timeouts — so it misses precommits and is jailed for downtime, even while it keeps up fine on small blocks. This has been observed in practice: a validator with roughly 225 ms RTT to the majority of voting power consistently missed precommits on large blocks and was jailed, while its small-block participation was unaffected. ML-DSA block sizes magnify latency problems that would be invisible on a standard Cosmos chain. When choosing where to run your validator, the factors to weigh are:
  • RTT to the current active set. Query qbtcd query staking validators (or the chain gateway) to see which validators are active, find where they are hosted, and measure round-trip latency from your intended machine before committing to a region. A few hundred milliseconds is enough to miss large blocks during Bitcoin ingestion events.
  • Active set distribution changes over time. As more validators join, the geographic concentration of voting power may shift. A region that gives low latency today might become higher-latency relative to a future set.
  • Network decentralisation. A geographically distributed active set is more resilient — geographic diversity has value for the network as a whole, even if it means some individual validators accept higher latency variance.
There is no single right answer here. What matters is that you understand your latency to the peers that hold the majority of voting power before you go live, and that you monitor it as the validator set evolves.
  • Do not change the consensus timeouts on your own. timeout_propose, timeout_commit, and related values in config.toml are effectively network-wide; the team may tune them to accommodate large post-quantum blocks, so follow the published values rather than diverging unilaterally.

Running multiple validators

Repeat the whole flow per validator, on separate machines (or separate --home directories and ports), each with its own account, its own consensus key, and its own Bitcoin reader configuration. Fund each account separately; each self-bonds independently.
The exact subcommand names and flags above follow Cosmos SDK v0.55. If anything differs on your build, the binary is the source of truth — check qbtcd tx staking create-validator --help and qbtcd comet --help. See Consensus & Validators for the economic model.

See also

Last modified on November 8, 2026