Quantus · QTC · node operations, read from the source

Don't trust the network.
Be the network.

Running your own quantus-node is the single highest-leverage thing you can do on a young proof-of-work chain: you verify every block yourself, you serve the network, and you mine without trusting anyone's RPC. This desk is the operations console — exact launch commands built from the real CLI flags, the verified port map, the seven mainnet bootnodes, a sync monitor, a log forensics lab, and the real update procedure.

⚠ Every flag, port, and procedure below was read from Quantus-Network source on 2026-09-30 — sources in Method. No systemd example is published upstream, so this desk ships none — we don't invent ops runbooks. 100% client-side · nothing leaves your browser

01 Install paths

Three verified ways to get the quantus-node binary. Pick one — they all end at the same Launch Lab below. Hardware minimums from chain/MINING.md: 2+ CPU cores, 4 GB RAM, 100 GB disk, 3+ Mbps stable (below 3 Mbps the node likely can't stay synced). Recommended: 4+ cores, 8 GB+ RAM, 500 GB+ SSD, 10+ Mbps.

📦 Release tarballs recommended

Prebuilt quantus-node + quantus-miner pairs from the chain repo. Always upgrade the pair together — the QUIC handshake pins ALPN quantus-miner/2 and mismatched versions fail.

releases

https://github.com/Quantus-Network/chain/releases/latest

src: chain releases page · node v1.0.1+ required for mainnet

🤖 Setup script

The official installer from the docs site. setup fetches binaries and writes mining.conf (keeps your inner hash on re-runs with --force); start launches node + miner.

setup script

./quantus-mining.sh setup
./quantus-mining.sh start

src: docs/static/scripts/quantus-mining.sh · note: "New Docker setup is not supported" by the script

🐳 Docker override CMD

Official image ghcr.io/quantus-network/quantus-node:latest. The repo Dockerfile still defaults to the retired planck testnet — always override the chain explicitly.

docker

docker run -d --name quantus-node \
  -p 30333:30333 \
  -v quantus-data:/var/lib/quantus \
  ghcr.io/quantus-network/quantus-node:latest \
  --validator --base-path /var/lib/quantus \
  --chain mainnet --name my-node

src: chain/MINING.md Docker section + chain/Dockerfile (stale planck CMD — overridden here)

Linux ARM64 caveat: the docs mining guide notes there is no native quantus-miner release for Linux ARM64 — mine from macOS or Linux x86_64. The node itself runs on Ubuntu 20.04+, macOS 10.15+, or Windows 10/11 (native MSVC or WSL2).

02 Launch Lab

Build your exact quantus-node startup command from the real flags (chain/node/src/cli.rs + inherited Substrate sc_cli flags). The builder validates as you type — --miner-listen-port requires --validator, mining modes require a valid --rewards-inner-hash, and dangerous choices get flagged, not silently passed.

Node name Shown on telemetry. Letters, digits, dots, dashes, underscores; ≤ 40 chars.

Rewards inner hash Your 32-byte wormhole preimage (0x + 64 hex). Generate: quantus-node key quantus --scheme wormhole. Never shared — it stays in this page.

Miner listen port QUIC job server for quantus-miner. Binds 0.0.0.0.

Chain spec

Node key file Stable P2P identity. Generate: quantus-node key generate-node-key --file node_key.p2p

Base path Chain database lives here.

--validator — required for mining; without it --miner-listen-port fails at startup. --force-authoring — bypass the 24 h freshness gate. Bootstrap only; remove once synced. Experimental RPC endpoint listen-addr=127.0.0.1:9944,methods=unsafe,cors=all (from scripts/run_local_nodes.sh). Localhost only.

Prometheus port Blank = default. Verify yours with quantus-node --help — upstream docs list 9615 and 9616.

Miner auth token file Defaults to <base-path>/chains/<chain>/miner-auth-token (generated 0600 on first run).

Miner TLS cert SHA-256 file The node writes this next to the token; the miner pins it (TLS 1.3, ALPN quantus-miner/2).

CPU workers

GPU devices

--cuda-gpu — use the CUDA engine (quantus-miner).

Miner flags mirror quantus-miner/README.md (--cpu-workers, --gpu-devices, --cuda-gpu, --metrics-port 9900) and are also settable via MINER_* env vars. Miners must heartbeat every 5–15 s — the node drops idle miner connections after 60 s.

quantus-node launch command

# fill in your rewards inner hash above

quantus-miner serve command

03 Port & firewall map

Exactly one port should face the internet. Everything else stays on localhost (or your VPN). The miner QUIC port binds 0.0.0.0 — firewall it even though you only intend local miners.

Port	Proto	Service	Exposure	Source

Generate firewall rules P2P port defaults to 30333 — change it if you run --port elsewhere.

firewall

04 Bootnodes

The seven mainnet bootnodes, copied verbatim from chain/node/src/chain-specs/mainnet.json (the embedded spec — note the chain_spec.rs code path ships zero bootnodes, so the JSON is the authoritative source). You rarely need --bootnodes — the spec already carries them — but they matter for isolated or restricted networks.

--bootnodes flag (all seven)

Telemetry: telemetry.quantus.cat (endpoint /dns/shard-telemetry.quantus.cat/tcp/443/x-parity-wss/%2Fsubmit%2F in every live spec). Explorer: explorer.quantus.com.

05 Sync monitor

A fresh node syncs from genesis — there is no official snapshot or warp sync published anywhere upstream, and --state-pruning / --blocks-pruning flags are ignored (pruning is enforced in code: blocks KeepFinalized, state ArchiveCanonical). Expect ~15 minutes to a couple of hours; you're synced when the log switches from Syncing to Idle. Then the 24 h freshness gate (--max-tip-age) must pass before mining starts.

Your node's best block From the log line best: #… or curl below.

Network head Auto-probed from the public RPC; override manually if the probe fails.

Probing wss://rpc.quantus.network…

— blocks behind

Ask your node directly

local RPC

curl -s -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"chain_getHeader","params":[]}' \
  http://localhost:9944 | head -c 400

DB corruption recovery

purge & resync

quantus-node purge-chain --chain mainnet
# then relaunch from the Launch Lab — full resync from genesis

Honest gap: no official snapshots, no state-size estimates published. The 100 GB / 500 GB figures in MINING.md are hardware requirements, not measured chain sizes — this desk won't present them as chain size.

06 Log forensics

Paste node log output — the desk matches it against the known log lines from the upstream docs and mining guide, and tells you what each one means and what to do. Nothing is uploaded; matching runs entirely in your browser.

No input yet.

Know your healthy lines

Log line	Meaning
"Mining rewards will be sent to wormhole address …"	Startup self-check: the node derived your reward address from `--rewards-inner-hash`. Confirm it matches the `Address` from `quantus-node key quantus --scheme wormhole`.
Syncing …	Catching up. Normal for a fresh node.
Idle (N peers), best: #…	Synced and idling between 12 s blocks. This is the healthy steady state.
Verification failed	Version mismatch — the node is out of step with the network (often stalls with 0 peers). Upgrade to the latest node+miner pair.
miner connection idle timeout	The node drops miner connections after 60 s without a keep-alive; miners must heartbeat every 5–15 s (the bundled miner does every 5 s).

07 Update desk

Two different upgrades, two different procedures. Binary upgrades need the matching pair; runtime upgrades need no restart at all.

🔧 Node binary updates

Watch the releases page. Download the matching node+miner pair (independent tags — the QUIC handshake pins ALPN quantus-miner/2). With the setup script, ./quantus-mining.sh setup --force refreshes binaries only and keeps your inner hash and wormhole address; pin pairs with NODE_VERSION/MINER_VERSION in mining.conf. Docker: stop, remove, pull :latest, re-run.

Symptom of a stale node: sync stalls mid-chain with Verification failed errors and 0 peers — that's the network leaving your binary behind, not a network outage.

src: docs mining guide · chain/MINING.md · research brief §10

⚖ Runtime upgrades (no restart)

Governance-only — pallet-sudo is removed. Tech-referenda on the fast_upgrade track (8-of-10 genesis collective votes, ~30 min) execute system.authorize_upgrade(code_hash); then the permissionless quantus runtime apply (system.apply_authorized_upgrade) delivers the WASM. No node restart required. Note: Polkadot-JS cannot sign these calls (Dilithium) — use the quantus CLI.

src: chain/docs/RUNTIME_UPGRADE_VIA_GOVERNANCE.md + RUNTIME_UPDATE.md

08 Chain specs & networks

--chain accepts the embedded specs below, the _live_spec variants built from Rust code, or a path to a JSON spec file (chain/node/src/command.rs load_spec). --dev spins an ephemeral dev chain with Alice/Bob authorities.

Spec	Token	Decimals	SS58	Notes

Planck is retired. Several upstream examples (Dockerfile CMD, MINING.md docker run) still say planck — they are stale. Mainnet is --chain mainnet and requires node v1.0.1+. Planck's PLK has no carryover to mainnet QTC.

09 Method & sources

Every operational fact on this page was read from Quantus-Network source on 2026-09-30. What we could not verify is listed as gaps, not published as fact.

Hardware requirements, QUIC miner protocol, auth token + TLS pinning, keep-alive rules: chain/MINING.md, docs/docs/guides/mining.md, docs/static/skills/mining-skill.md
Custom CLI flags (--rewards-inner-hash, --miner-listen-port, --miner-auth-token-file, --enable-peer-sharing, --max-tip-age, sync tuning): chain/node/src/cli.rs
Mandatory pruning (KeepFinalized / ArchiveCanonical, CLI flags ignored): chain/README.md "Database Storage Configuration"
Canonical startup command: docs mining guide (verified against cli.rs flag requirements)
Bootnodes (7): chain/node/src/chain-specs/mainnet.json (authoritative — chain_spec.rs code path ships none)
Chain spec loading + --dev: chain/node/src/command.rs load_spec; SS58 189 + QTC/12 decimals: chain/node/src/chain_spec.rs, chain/runtime/src/lib.rs
Docker image + stale planck CMD: chain/MINING.md, chain/Dockerfile; setup script: docs/static/scripts/quantus-mining.sh
quantus-miner flags + benchmark subcommand: quantus-miner/README.md
Runtime upgrade flow: chain/docs/RUNTIME_UPGRADE_VIA_GOVERNANCE.md, chain/docs/RUNTIME_UPDATE.md
Gaps (deliberately absent): no systemd unit published upstream · no official snapshots / warp sync / state-size figures · Prometheus default disputed (9615 in current guide + skill + sc-cli default vs 9616 in older MINING.md table — verify with --help)