Running a Node

• qbtcd — the chain daemon (Cosmos SDK + the ML-DSA CometBFT fork). This is the node.
• bifrost — the sidecar that connects to a Bitcoin full node, watches for new Bitcoin blocks, and relays them to the chain. See Architecture for how the two 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.
• A reachable Bitcoin full node with RPC enabled (host, port, RPC username, and password).
• For building from source instead of using release binaries: Go 1.22+ and Make.

​

Quick install (recommended)

curl -sSL https://raw.githubusercontent.com/btcq-org/qbtc/main/scripts/install.sh | bash

curl -sSL https://raw.githubusercontent.com/btcq-org/qbtc/main/scripts/install.sh | bash -s -- -v 1.0.22

QBTC_VERSION=1.0.22 bash -c "$(curl -sSL https://raw.githubusercontent.com/btcq-org/qbtc/main/scripts/install.sh)"

curl -sSL https://raw.githubusercontent.com/btcq-org/qbtc/main/scripts/install.sh -o qbtc-install.sh
less qbtc-install.sh
bash qbtc-install.sh

​

What the installer creates

​

Configure bifrost

vim ~/.bifrost/config.json

{
  "listen_addr": "0.0.0.0:30006",
  "http_listen_addr": "0.0.0.0:30007",
  "external_ip": "",
  "bitcoin": {
    "host": "127.0.0.1",
    "port": 8332,
    "rpc_user": "bitcoinrpc",
    "password": "securepassword",
    "local_db_path": "/home/youruser/.bifrost/db"
  },
  "qbtc_grpc_address": "localhost:9090",
  "cometbft_rpc_address": "http://localhost:26657"
}

​

Start the node

sudo systemctl start qbtcd
sudo systemctl start bifrost

sudo systemctl status qbtcd bifrost
sudo journalctl -u qbtcd -f

sudo systemctl enable qbtcd bifrost

​

Ports

​

Building from source

git clone https://github.com/btcq-org/qbtc.git
cd qbtc
make build

make test
go test -tags=testing ./x/qbtc/zk/...

./scripts/start-node.sh

​

Keeping your node updated

​

Minor / patch releases (no consensus break)

1. /usr/local/bin/qbtcd
2. ~/.qbtc/cosmovisor/current/bin/qbtcd

# stop services
sudo systemctl stop qbtcd bifrost

# download the release binaries (or build them), then replace both copies
sudo install -m 755 qbtcd  /usr/local/bin/qbtcd
sudo install -m 755 qbtcd  ~/.qbtc/cosmovisor/current/bin/qbtcd
sudo install -m 755 bifrost /usr/local/bin/bifrost

# restart
sudo systemctl start qbtcd bifrost
qbtcd version    # confirm the new version

​

Major / consensus-breaking upgrades (governance)

# <upgrade-name> is the name in the passed proposal
mkdir -p ~/.qbtc/cosmovisor/upgrades/<upgrade-name>/bin
install -m 755 qbtcd ~/.qbtc/cosmovisor/upgrades/<upgrade-name>/bin/qbtcd

​

Chain ID for transactions

qbtcd tx ... --chain-id qbtc

​

Querying without your own node

​

Becoming a validator

1. Consensus keys are ML-DSA, not Ed25519. The validator pubkey you submit has @type /cosmos.crypto.mldsa.PubKey. You get it from qbtcd comet show-validator exactly as on any Cosmos chain — the key material is just post-quantum.
2. Account keys are also ML-DSA, not secp256k1. qbtcd keys add generates a post-quantum account key. This is unusual (most Cosmos chains use secp256k1 accounts) and means generic secp256k1 tooling and hardware wallets will not sign QBTC transactions.
3. A validator must also run bifrost and register it on-chain. Block production depends on validators attesting Bitcoin blocks (see Architecture). Beyond running the sidecar, you publish its peer address with a custom x/qbtc transaction so other validators can reach it — see Register your bifrost peer address. Skipping this leaves your validator unable to attest.

​

Network parameters (current testnet)

​

Step by step

1. Sync a full node and run bifrost (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 key):
   qbtcd keys add my-validator
   # note the qbtc1... address it prints
   
3. Fund the account. On testnet, send your qbtc1… address to the team and they fund it. Confirm the balance:
   qbtcd query bank balances "$(qbtcd keys show my-validator -a)"
   
4. Get your consensus pubkey:
   qbtcd comet show-validator
   # → {"@type":"/cosmos.crypto.mldsa.PubKey","key":"..."}
   
5. Write validator.json — paste the pubkey output verbatim into the pubkey field:
   {
     "pubkey": {"@type":"/cosmos.crypto.mldsa.PubKey","key":"PASTE_FROM_STEP_4"},
     "amount": "1000000000qbtc",
     "moniker": "my-validator",
     "commission-rate": "0.1",
     "commission-max-rate": "0.2",
     "commission-max-change-rate": "0.01",
     "min-self-delegation": "1"
   }
   
   amount is your self-bond, in base units (1000000000qbtc = 10 QBTC). It must be ≤ your funded balance.
6. Submit the transaction:
   qbtcd tx staking create-validator validator.json \
     --from my-validator \
     --chain-id qbtc \
     --gas auto --gas-adjustment 1.3
   
7. Verify you are bonded:
   qbtcd query staking validator "$(qbtcd keys show my-validator --bech val -a)"
   
   or via the public gateway: …/qbtc-rpc/cosmos/staking/v1beta1/validators.

​

Register your bifrost peer address

• It is order-enforced. The set-node-peer-address transaction is rejected unless the signer is an already-bonded validator (the handler requires validator.Status == Bonded, otherwise it returns unauthorized: validator is not bonded). Run it before create-validator, or while your validator is still unbonded or jailed, and it fails. Confirm BOND_STATUS_BONDED from the verify step above first.
• Bonding alone is not enough. Your validator’s bifrost also has to be discoverable so other validators’ bifrost processes can connect and exchange Bitcoin blocks. A bonded but unregistered validator cannot attest BTC blocks and risks downtime jailing.

1. Set external_ip and restart bifrost. Confirm external_ip in ~/.bifrost/config.json is your node’s public IP (see the bifrost config tip), then:
   sudo systemctl restart bifrost
   
2. Read your full peer address from the bifrost HTTP API. It returns <peerID>@<external_ip>:<p2p-port> ready to use:
   curl http://127.0.0.1:30007/peerid
   # → 12D3KooWE2iVgm3YXDKwGX7Asqz7Q4JpoDZ12Vj8G6vVQMNVJEq9@149.28.169.249:30006
   
   If the IP comes back as 0.0.0.0, external_ip is unset — fix step 1 first.
3. Register it on-chain with the custom x/qbtc message, signed by your validator account:
   qbtcd tx qbtc set-node-peer-address \
     --peer-address "12D3KooWE2iVgm3YXDKwGX7Asqz7Q4JpoDZ12Vj8G6vVQMNVJEq9@149.28.169.249:30006" \
     --chain-id qbtc \
     --from my-validator
   
4. Verify peering and the on-chain mapping:
   curl http://127.0.0.1:30007/connected-peers     # live bifrost connections
   curl http://127.0.0.1:30007/validator-peers      # validator peers seen
   qbtcd query qbtc all-node-peer-addresses          # the on-chain registry
   
   The custom x/qbtc queries are served by your own node, not the public REST gateway. If a subcommand differs on your build, check qbtcd query qbtc --help.

​

Placement and latency

• Run close to the rest of the active set. Minimize round-trip latency to the other validators. On the current testnet the majority of voting power runs in Singapore — place your validator in or near the region where the active set is concentrated (confirm the current location with the team) rather than across an ocean.
• Measure before you commit to a region. A few hundred milliseconds of RTT to your peers is enough to miss large blocks. Check latency first.
• Do not change the consensus timeouts on your own. timeout_propose, timeout_commit, and the related values in config.toml are effectively network-wide; the team may tune them for large post-quantum blocks, so follow the published values rather than diverging unilaterally.

​

Running multiple validators

​

See also

• Architecture, how qbtcd, bifrost, and the Bitcoin node fit together.
• Consensus & Validators, validator economics and emission.
• Chain repository, source of truth for versions and endpoints.