Running a node

This page covers the operational lifecycle of a Quantum Chain node after it’s installed.

Startup

A typical systemd unit:

# /etc/systemd/system/geth.service
[Unit]
Description=Quantum Chain geth
After=network-online.target

[Service]
Type=simple
User=geth
ExecStart=/usr/local/bin/geth \
  --datadir /var/lib/geth \
  --networkid 20803 \
  --syncmode snap \
  --http --http.addr 127.0.0.1 --http.api eth,net,web3 \
  --metrics --metrics.addr 127.0.0.1 --metrics.port 6060
Restart=on-failure
RestartSec=5
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target

systemctl enable --now geth
journalctl -u geth -f

Health and readiness

Quantum Chain exposes the standard geth health endpoints:

RPC method	Purpose
`eth_blockNumber`	Latest block; should advance every ~15s on mainnet
`eth_syncing`	Returns sync status; `false` when fully synced
`net_peerCount`	Number of connected peers
`admin_nodeInfo`	Node identity, enode URL

A simple liveness probe:

curl -s -X POST http://127.0.0.1:8545 \
  -H 'Content-Type: application/json' \
  --data '{"jsonrpc":"2.0","method":"eth_blockNumber","id":1,"params":[]}' \
  | jq -r '.result'

Metrics

Enable Prometheus-compatible metrics with:

geth ... --metrics --metrics.addr 0.0.0.0 --metrics.port 6060

Key metrics:

Metric	Meaning
`chain/head/block`	Latest block number
`chain/head/header`	Latest header number; `block - header` should be 0
`eth/db/chaindata/disk/size`	Database size in bytes
`p2p/peers`	Peer count
`txpool/pending`	Pending transactions in pool
`txpool/queued`	Future transactions
`system/cpu/sysload`	OS CPU load

Logs

Logs are structured. Increase verbosity with:

geth --verbosity 4    # 0=silent ... 5=debug

Or per-module via --vmodule consensus=4,p2p=3.

Sync states

State	Meaning
Receiving headers	First phase of snap sync
Importing block headers	Header chain catching up
Importing snapshot chunks	Downloading the latest state snapshot
Block synchronization	Block bodies and receipts
Synced	Up to head; tracking new blocks

Backups

Snap and full sync nodes are stateless — you can wipe and resync. Archive nodes hold irreplaceable historical state; back them up with:

systemctl stop geth
tar -C /var/lib --use-compress-program=zstd -cf /backup/geth-$(date +%F).tar.zst geth
systemctl start geth

For online backups without stopping the node, use a copy-on-write filesystem (ZFS, btrfs).

Upgrades

Quantum Chain releases ship as tagged commits in this repository.

Read the release notes for hard-fork activation blocks.
Build the new binary on a staging node.
Update validators within the upgrade window — sealers running an outdated binary after the fork height will produce blocks rejected by the network.
Roll RPC nodes after validators.

Pruning

To reclaim disk on a --gcmode full node:

systemctl stop geth
geth snapshot prune-state --datadir /var/lib/geth
systemctl start geth

prune-state rewrites the trie and may take several hours.

Get started

Operate

Build

JSON-RPC reference

Startup

Health and readiness

Metrics

Logs

Sync states

Backups

Upgrades

Pruning

Where to go next

​Startup

​Health and readiness

​Metrics

​Logs

​Sync states

​Backups

​Upgrades

​Pruning

​Where to go next

Startup

Health and readiness

Metrics

Logs

Sync states

Backups

Upgrades

Pruning

Where to go next