Reference client operations

Build, run, and operate a Quantum node.

Use the hosted Sandbox for application integration. Run the reference client when you need independent RPC, chain indexing, private-network development, or validator operations.

Build Initialize Run Secure RPC Monitor Backup and upgrade Troubleshoot

Build from source

Produce the reference client and tools.

Requirement	Version or purpose
Go	1.24 or newer
GNU Make	Build entrypoints
C compiler	gcc or clang for native dependencies
Git	Source checkout

terminal

git clone https://github.com/Quantum-Chain-PTE-LTD/go-quantum-chain.git
cd go-quantum-chain
make geth
./build/bin/geth version

make geth builds the node at build/bin/geth. Use make all when you also need tools such as abigen, bootnode, clef, ethkey, evm, and rlpdump.

Application developersYou do not need to compile a node to use the JavaScript or Python SDK. The hosted Sandbox RPC is the shortest integration path.

Chain initialization

Initialize with the exact network genesis.

A node database is tied to its genesis block. Obtain the released genesis and peer configuration for the network you intend to join, verify them through your distribution channel, then initialize an empty data directory once.

terminal

export QUANTUM_DATADIR=/var/lib/quantum-chain
export QUANTUM_GENESIS=/etc/quantum-chain/genesis.json

sudo install -d -o quantum -g quantum -m 0750 "$QUANTUM_DATADIR"
sudo -u quantum ./build/bin/geth \
  --datadir "$QUANTUM_DATADIR" \
  init "$QUANTUM_GENESIS"

Identity check--networkid does not replace genesis initialization. After startup, confirm chain ID and block zero hash against the published network identity before serving traffic.

Genesis fields that define a Quantum network

Field	Meaning
`config.chainId`	Transaction replay-protection domain
`config.quantumVerificationBlock`	Activation height for Quantum signature verification rules
`config.clique.period`	Configured seconds between blocks
`config.clique.epoch`	Clique checkpoint interval
`extraData`	Initial Clique sealer set
`alloc`	Optional genesis balances

Runtime profiles

Keep public application RPC separate from node administration.

Read and submit node

systemd ExecStart

/usr/local/bin/geth \
  --datadir /var/lib/quantum-chain \
  --networkid 20804 \
  --syncmode snap \
  --port 30303 \
  --maxpeers 50 \
  --http \
  --http.addr 127.0.0.1 \
  --http.port 8545 \
  --http.api qc,net,web3 \
  --ws \
  --ws.addr 127.0.0.1 \
  --ws.port 8546 \
  --ws.api qc,net,web3 \
  --metrics \
  --metrics.addr 127.0.0.1 \
  --metrics.port 6060

This example uses Sandbox network ID 20804. Use the network ID and genesis for your actual target. A Mainnet node uses network ID 20803.

Storage profiles

Profile	Typical flags	Use
Standard full node	`--syncmode snap --gcmode full`	Current-state RPC and normal application traffic
Full synchronization	`--syncmode full --gcmode full`	Replay and validation from genesis without archive state
Archive	`--syncmode full --gcmode archive`	Historical state queries at every block, with high storage cost

Validator profile

A validator needs an authorized Clique sealer account, the correct validator key material, stable peers, and the approved network operations procedure. It adds --mine and an authorized --miner.etherbase. Do not turn an application RPC node into a validator by copying flags from a tutorial.

RPC security

Bind locally and publish through a controlled edge.

Keep HTTP, WebSocket, metrics, and authenticated engine interfaces on private or loopback addresses.
Expose only qc, net, and web3 to normal applications.
Do not publish admin, debug, personal, miner, engine, or txpool namespaces.
Place public RPC behind TLS, source controls where appropriate, rate limits, request-size limits, and timeouts.
Do not use unlocked node accounts for public application signing.
Keep validator signing and application transaction signing in separate security boundaries.

Unsafe unlock--unlock and --allow-insecure-unlock are development mechanisms. They are not a production wallet architecture.

Health and monitoring

Measure head progress, synchronization, peers, and resources.

liveness check

curl --fail-with-body http://127.0.0.1:8545 \
  -H 'content-type: application/json' \
  --data '{"jsonrpc":"2.0","id":1,"method":"qc_blockNumber","params":[]}'

Signal	Healthy interpretation
`qc_blockNumber`	Returns promptly and advances with the network
`qc_syncing`	`false` after synchronization, otherwise progress is moving
`net_peerCount`	Nonzero on a networked node and stable for the deployment
Head age	Latest block timestamp remains within the expected block cadence
Disk and database	Free space remains above the operational reserve
Transaction pool	Pending and queued growth stays within expected workload bounds

Enable Prometheus-compatible metrics with --metrics. Keep the metrics listener private. Use --verbosity for temporary diagnostic detail and return it to the normal operational level after investigation.

Backup and upgrade

Treat node data and signing data differently.

A standard full node can be rebuilt from the signed release, genesis, peer configuration, and the network. Archive data may be expensive to reconstruct. Validator and wallet key material is not replaceable by resynchronizing.

Inventory genesis, static peers, service unit, proxy configuration, and monitoring rules.
Stop the node or take a storage-consistent snapshot before copying the database.
Protect validator and wallet key backups under their own recovery procedures.
Stage every client upgrade on a non-validator node first.
Verify chain identity, sync, RPC, transaction decoding, and receipt handling.
Roll validators only inside the coordinated network upgrade window.

Release coordinationRead release notes for protocol activation heights. A validator running incompatible rules can produce blocks that other nodes reject.

Troubleshooting

Start with identity, head, and peers.

Symptom	Check	Action
Wrong chain ID or genesis	Query `qc_chainId` and block zero	Stop. Point at the intended data directory and genesis. Never sign while identity is uncertain.
Head does not advance	`qc_syncing`, peer count, latest timestamp	Check peer reachability, bootnodes or static peers, disk, and system time.
Zero peers	P2P port, advertised address, peer configuration	Open TCP and UDP P2P traffic as required and verify enode records.
RPC connection refused	`--http`, bind address, port, proxy target	Fix the private listener or reverse proxy. Do not bypass controls by exposing admin APIs.
RPC method not found	`--http.api` or gateway method policy	Enable only the required namespace on a private node, or use a supported hosted method.
Transaction remains queued	Pending nonce and earlier transaction gaps	Reconcile nonce ownership. Do not submit more transactions blindly.
Insufficient funds	Balance, value, gas limit, gas price	Fund the correct network address and account for maximum transaction cost.
HTTP 403 on hosted Sandbox	Public egress address	Ask Quantum Chain to approve the source. This is edge access control, not a JSON-RPC error.

JSON-RPC referenceInspect request shapes, response conventions, and retries.Protocol overviewReview network identity, account derivation, and transaction format.