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.
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-amd64release binaries andsystemd). curl,tar,sudo,sha256sum, andsystemctlavailable 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.
Quick install (recommended)
The chain repo ships an install script that downloads theqbtcd 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.
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:
enable = false.
Start the node
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
- 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.
-
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. -
Enable snapshots in
~/.qbtc/config/app.tomlso your node can also serve state sync to others: -
Reset chain data if the node has already started syncing from genesis:
-
Start the node and watch for state sync to kick in:
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:
Keeping your node updated
Newqbtcd releases are published on the releases page. There are two kinds of update, and they are handled differently.
Minor / patch releases (no consensus break)
For a routine version bump, you replace the binaries directly — no governance proposal. Theqbtcd binary lives in two places, and both must be updated so it does not matter whether systemd launches the daemon directly or through Cosmovisor:
/usr/local/bin/qbtcd~/.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 setsDAEMON_ALLOW_DOWNLOAD_BINARIES=false, Cosmovisor will not fetch the binary for you — stage it ahead of the upgrade height:
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 asqbtc (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:
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 SDKx/staking flow (qbtcd tx staking create-validator), with three QBTC-specific differences:
- Consensus keys are ML-DSA-65, not Ed25519.
qbtcd initcreates an ML-DSA-65 consensus key by default. The validator pubkey you submit has@type/cosmos.crypto.mldsa65.PubKey. You get it fromqbtcd comet show-validator, as on any Cosmos chain. - Account keys are ML-DSA-65 only. The chain rejects all other key types, including secp256k1, ed25519 and multisig.
qbtcd keys addcreates an ML-DSA-65 key by default (--key-type ml_dsa_65). - 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).
Network parameters (current test network)
Verified live; all change at mainnet relaunch.Step by step
-
Sync a full node and enable the Bitcoin reader (sections above). Wait until
qbtcdis caught up (qbtcd status→sync_info.catching_up: false). -
Create your validator account key (this is an ML-DSA-65 key):
-
Fund the account. On the test network, send your
qbtc1…address to the team and they fund it. Confirm the balance: -
Get your consensus pubkey:
-
Write
validator.json— paste the pubkey output verbatim into thepubkeyfield:amountis your self-bond, in base units (1000000000qbtc= 10 QBTC). It must be ≤ your funded balance. -
Submit the transaction:
-
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.
- Do not change the consensus timeouts on your own.
timeout_propose,timeout_commit, and related values inconfig.tomlare 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
- Architecture, how
qbtcd, its Bitcoin reader, and the Bitcoin node fit together. - Consensus & Validators, validator economics and emission.
- Chain repository, source of truth for versions and endpoints.