SX Edition — Server Daemon
The SX (Server eXperience) edition is the headless light node: a daemon plus a full management CLI, built for servers and automation. The binary is lightnode-sx. Light node versions are on their own line, separate from the chain version: both networks' channels carry 3.1.14 (13 November 2026). This page notes where a feature needs 3.1.11 or later.
Install
Prebuilt binaries are the easiest path. The light node client is a single static binary of roughly 13 MB, with no native libraries to install: Linux (amd64, arm64), macOS (Intel, Apple Silicon) and Windows (amd64, arm64) builds exist for both editions, 12 binaries in total per release. The node signs its own transactions, so nothing else (in particular, no qorechaind) is needed to register and run a node.
Verify the checksum before you run it. The release manifest at https://download.qore.host/<net>/lightnode/latest.json carries a sha256 for every binary, a checksums.url pointing at a SHA256SUMS file over the whole release, and that file's own checksums.sha256. Verify what you downloaded: it is the difference between running the binary that was built and running whatever landed at that URL. Take the version from the manifest, and take the binary and its SHA256SUMS from the same versioned path:
NET=mainnet # or testnet
V=$(curl -fsS https://download.qore.host/$NET/lightnode/latest.json | jq -r .version) # 3.1.14 on both networks today
F=lightnode-sx-linux-amd64 # see the artifact list in latest.json
curl -fsSLO https://download.qore.host/$NET/lightnode/v$V/$F
curl -fsSLO https://download.qore.host/$NET/lightnode/v$V/SHA256SUMS
grep " $F\$" SHA256SUMS | sha256sum -c - # macOS: shasum -a 256 -c -
chmod +x $F
Use the versioned SHA256SUMS (.../v$V/SHA256SUMS) with the versioned binary. The unversioned .../lightnode/SHA256SUMS belongs to the manifest and can lag behind a new release for a few hours, so a versioned binary checked against it can fail.
On Windows, compare certutil -hashfile lightnode-sx-<platform>.exe SHA256 against the manifest value. Both manifests accept 3.1.9 and later (minCompatible: 3.1.9). The source is public at github.com/qorechain/qorechain-lightnode (Apache 2.0). An Android build is attached to the GitHub release as a preview; it does not register and does not earn.
You can also build the binary from source or run it with Docker.
Build from source
The light node requires Go 1.26.1. Its post-quantum cryptography is a pure-Go implementation (no CGO, no native library), so cross-compiling for any of the six supported platforms works the same way any other Go binary does:
go build -o build/lightnode-sx ./cmd/lightnode-sx/
Build from the release tag the manifest names (git checkout v3.1.14 today). This produces build/lightnode-sx. Run it directly, or copy it onto your PATH. Before registering, sanity-check the post-quantum signing stack with selftest.
Docker
The released images are public and can be pulled anonymously: ghcr.io/qorechain/qorechain-lightnode-sx and ghcr.io/qorechain/qorechain-lightnode-ux, each tagged latest and v<version> (for example v3.1.14). The docker-compose.yml on the main branch of the source repository uses them and falls back to building from source (Dockerfile.sx, Dockerfile.ux) when the registry is not reachable. To pin a release, change the image: tag in the compose file; to build from a release tag instead, git checkout v<version> and run docker compose build. Keys, config and the data volume carry over when you update.
git clone https://github.com/qorechain/qorechain-lightnode
cd qorechain-lightnode
export QORE_LIGHTNODE_KEYRING_PASSPHRASE='...' # node keyring (node key + operator key)
export QORECHAIN_RPC_ADDR=https://rpc.qore.host # testnet: https://rpc-testnet.qore.host
docker compose pull # fetches the released image
# Once: the same setup as outside Docker, written into the data volume.
docker compose run --rm lightnode-sx onboard
docker compose run --rm lightnode-sx keys add-operator --recover
docker compose run --rm lightnode-sx register --delegate-to qorvaloper1...
docker compose up -d lightnode-sx
docker compose run --rm lightnode-sx status
Keep QORECHAIN_RPC_ADDR exported on every docker compose command: it overrides rpc_addr from the config. Since 3.1.10 the compose file defaults it to the mainnet RPC https://rpc.qore.host, so a testnet node must export https://rpc-testnet.qore.host or it will follow mainnet. The SX container persists its data, including the keyring, in a named volume mounted at /root/.qorechain-lightnode.
The node signs natively inside the container, so nothing else is required. The SX image still carries a released qorechaind (v3.2.0, linux/amd64 only, checked against a pinned digest) for the qorechaind fallback: docker-compose.yml mounts ~/.qorechaind (or QORECHAIND_HOME) at /root/.qorechaind and passes QORE_LIGHTNODE_QORECHAIND_PASSPHRASE for that path. A node whose operator key is in its own keyring does not use either.
Updating
-
Light node 3.1.11 and later, outside Docker. Every 6 hours the node reads
https://download.qore.host/<net>/lightnode/latest.jsonfor its own network (mainnet forqorechain-vladi, testnet forqorechain-diana, nothing for other chains). The manifest is only a hint. The node installs a release only if all of these hold:v<version>/SHA256SUMS.sigis a valid Ed25519 signature, by the release key built into the binary, over the network, the version and the contents ofSHA256SUMS;- the binary, fetched from the channel's own versioned path (manifest URLs are not followed), matches its signed checksum;
- the new binary runs and reports exactly
v<version>.
It then keeps the previous binary as
<name>.oldand restarts in place: the same process on Linux and macOS (so a systemd service stays up), while on Windows the new binary starts and the old one exits (set a service to restart on exit). -
Settings.
[update] mode = "auto"(default, also for a config without the section) announces and installs;"notify"announces only;"off"does not check. By hand:lightnode-sx update --check, thenlightnode-sx update, then restart the node. -
Seeing an announcement. The node logs a newer release and serves it on the local dashboard API at
GET /api/update(fieldsnetwork,mode,current,latest,min_compatible,notes,update_available,mandatory,can_install,blocked,last_check,last_error); the UX dashboard shows a banner. -
Container or unwritable folder. The node only announces: update the image or the file yourself.
-
Light node 3.1.11 and later install new releases by themselves within 6 hours of publication (checked on the testnet test node).
-
Light node 3.1.10 and earlier do not update themselves. Install 3.1.14 by hand once: download the versioned binary from the manifest path (see Install), verify it, replace the file and restart. After that the node follows its channel.
-
Docker. A Docker node is notified of a new release (log and
GET /api/update) but never replaces itself; the pull is the update:docker compose pull && docker compose up -d(keepQORECHAIN_RPC_ADDRexported). Building from the new source tag is the alternative.
Configure
The light node reads a TOML config file. By default it looks for config.toml in the home directory (~/.qorechain-lightnode/config.toml). You normally do not write this file by hand — the onboard wizard creates it for you — but it is useful to understand the options.
Two persistent flags apply to every command:
--config <path>— point at a config file in a non-default location.--home <dir>— override the home directory used for data and keys (defaults to~/.qorechain-lightnode).
The most relevant configuration options, at a usage level:
| Option | What it controls |
|---|---|
chain_id | The network identifier (qorechain-vladi on mainnet, qorechain-diana on testnet). onboard reads it from the RPC endpoint; if the endpoint could not be reached during onboard, the default qorechain-diana is left and you must set it yourself. Transactions are signed for this chain. |
rpc_addr | The chain RPC endpoint the daemon connects to. Leave empty to run in local-only mode. |
primary_addr / witness_addrs | The primary RPC endpoint, and the witness endpoints its reported header is corroborated against — see Why run a light node. At least one distinct, reachable witness is what moves the assurance value (logged at debug level) from trusted-single-source to corroborated-across-sources. |
trust_period / max_clock_drift | Accepted for compatibility but not currently used. Header trust comes from the primary/witness corroboration described above. |
data_dir | Where the node stores its database and headers. |
keyring_backend / key_name | Keyring backend (file, os, or test for local devnets only) and the name of the post-quantum key the node signs with. onboard sets key_name to the key it creates (validator); keys add-operator changes it to operator-pqc when it derives or recovers the key from the account's words. The file backend requires QORE_LIGHTNODE_KEYRING_PASSPHRASE in the environment. |
operator_address | The account this node belongs to (qor1...); validated at load. keys add-operator fills it in. Required for register, status and heartbeats. See The operator wallet. |
api_addr | The REST endpoint. onboard writes it into config.toml (mainnet https://api.qore.host, testnet https://api-testnet.qore.host). When empty, it is derived from rpc_addr (port 26657 becomes 1317; rpc. and rpc-testnet. hosts become api. and api-testnet.; for example https://rpc-testnet.qore.host gives https://api-testnet.qore.host), so it is only needed for endpoints that follow none of these conventions. Until 3.1.12 only the rpc. to api. mapping existed, so a testnet node with an empty api_addr could answer "404 page not found" on licence, register and status; set api_addr by hand on those versions, or update. |
[heartbeat] | On by default (enabled). interval_blocks (match the chain's heartbeat_interval, 1000), check_interval (default 60s) and gas (default 300000, the ceiling for a heartbeat's gas limit; with native signing the fee is 0.25 uqor per unit of gas). From 3.1.13 the node sets each heartbeat's gas limit to what the previous heartbeat used plus 25%, rounded up to 1,000 gas, and never above gas; the first heartbeat after a start, and the first after an out-of-gas refusal, use the ceiling. Measured on the testnet: limit 216,000, used 165,774, fee 54,000 uqor (0.054 QOR) per heartbeat instead of 75,000 uqor. The operator account must hold spendable QOR beyond the 1,000 QOR stake to pay these fees. Used only by the qorechaind fallback: fees (default 50000uqor), qorechaind_path (empty means qorechaind on PATH), qorechaind_home (empty means ~/.qorechaind), keyring_backend, and key_name (the qorechaind key holding the operator account; defaults to the top-level key_name). |
[delegation] | auto_claim (off by default: claims accrued light-node rewards to the operator account through the signer; the node never re-delegates from the server), the check interval, minimum reward to claim, rebalance_enabled (on by default) and min_reputation (warnings only; the node never moves stake). From 3.1.11 rebalance_enabled switches on warnings for a delegated validator that is jailed or not in the active set and for bonded stake below min_delegated_stake (1,000 QOR); min_reputation (default 0.5) applies where the network serves per-validator reputation scores, which is the testnet today. validators and split_weights are accepted but not currently acted on. |
[update] | mode: auto (default, also when the section is absent), notify (announce only) or off. Light node 3.1.11 and later. See Updating. |
[telemetry] | Whether telemetry is enabled and the refresh intervals for validators, network, bridge, and tokenomics. |
[dashboard] | The local dashboard API. The UX edition always serves it; the SX edition only with enabled = true. bind_addr (default 127.0.0.1:8420) and token (when set, every /api route and /ws require Authorization: Bearer <token>). See UX Edition. |
log_level / log_format | Logging verbosity (debug, info, warn, error) and format (text or json). Top-level keys: put them before the first [table]. |
Environment variables
| Variable | Used for |
|---|---|
QORE_LIGHTNODE_KEYRING_PASSPHRASE | Passphrase of the node keyring (keyring_backend = "file"), which holds the node's post-quantum key and the operator account key. Required for every command that opens the keyring and for start; the node refuses an empty one. |
QORE_LIGHTNODE_QORECHAIND_PASSPHRASE | Only for the qorechaind fallback: passphrase of the qorechaind keyring holding the operator key; piped to qorechaind on stdin, never on a command line. |
QORECHAIN_RPC_ADDR | Overrides rpc_addr (and primary_addr when it equalled rpc_addr). Set by docker-compose.yml. |
A witness on the same host as the primary is refused — a compromised endpoint would simply agree with itself, so it corroborates nothing. A plaintext http:// witness on a remote host is also refused, since an attacker who can rewrite that connection can answer as every witness at once; loopback http:// is fine. Point witnesses at RPC endpoints you have independent reasons to trust.
Delegation defaults enable the stake alerts and leave auto_claim off; see Rewards and Monitoring for what these do.
First run: onboard
On first launch, start will stop and point you at the onboarding wizard if no config file exists yet. Set the keyring passphrase first — onboard refuses to start without it, so it never generates a key it cannot store — then run the wizard:
export QORE_LIGHTNODE_KEYRING_PASSPHRASE='choose-a-passphrase'
lightnode-sx onboard
onboard walks you through setup in four steps:
- PQC self-test — runs the full Dilithium-5 roundtrip (the same checks as
selftest). If the PQC stack fails, the wizard refuses to continue. - Chain RPC endpoint — paste your QoreChain RPC URL (mainnet
https://rpc.qore.host, testnethttps://rpc-testnet.qore.host), or leave it blank to run in local-only mode. If you provide a URL, the wizard tests it live and reads the chain ID from it. - Node key — the wizard calls this the "validator private key", but it is the light node's own Dilithium-5 key, not a validator key. Paste a hex-encoded Dilithium-5 private key, or type
g(orgenerate) to mint a fresh keypair on this node. - Save — writes
config.toml(with the endpoint and chain ID) and stores the key in the keyring under the namevalidator(orvalidator-<hex>if that name is taken), settingkey_nameto it.
If you leave the endpoint blank, the daemon starts in local-only mode: the PQC stack is fully exercised, but the node does not sync any chain. Re-run onboard once your chain endpoint is ready to point the node at it.
onboard always overwrites the active config. Use --config to write to a non-default path, or --non-interactive to fail fast instead of prompting (useful in CI).
onboard does not know which account is yours. Before you run register, add the operator account with keys add-operator. It fills in operator_address for you. If the endpoint could not be reached during onboard, also check that chain_id in config.toml is qorechain-vladi (mainnet) or qorechain-diana (testnet), and that api_addr is set (onboard writes it; a testnet node on 3.1.12 or earlier with an empty api_addr may answer "404 page not found").
Run: start
Once onboarding has written a config, start the daemon:
build/lightnode-sx start
The daemon syncs headers, tracks delegations, and serves telemetry until interrupted. If you intentionally want to start without a config file (local-only, no chain RPC), pass --skip-onboarding-check.
Verify the PQC stack: selftest
At any time you can confirm the post-quantum stack is functional:
lightnode-sx selftest
selftest runs five checks against Dilithium-5 (ML-DSA-87) and completes in under a second:
- Keygen — generate a fresh keypair.
- Sign — sign a test message.
- Verify (valid sig) — confirm the signature verifies with the matching public key.
- Reject tampered signature — flip a byte of the signature; verification must reject it.
- Reject tampered message — flip a byte of the message; verification must reject it.
If any check fails, the binary exits non-zero with diagnostic output. This is the same test the onboarding wizard runs as its first step, and it is handy for pre-deployment verification and support diagnostics.
The operator wallet
The node's Dilithium-5 key is not a wallet. On QoreChain a post-quantum key is attached to an account; it does not create one. That is why keys list shows no address for it. Your operator address is an ordinary qor1… account that holds the licence and the stake, pays the fees and receives the light-node rewards. It must be an account whose recovery words you hold (your own words, Keplr, or qorechaind); a dedicated account is best. A custodial Dashboard wallet cannot run a node unless you export its seed. See The operator account.
Store the operator account key in the node's keyring:
# The account the licence is for: type its recovery words, then Enter
lightnode-sx keys add-operator --recover
# Or create a new account; its 24 words are shown once
lightnode-sx keys add-operator
keys add-operator:
- derives the account key from the words exactly as
qorechaindand Keplr do (m/44'/118'/0'/0/0), stores it in the keyring asoperator, and writes the account tooperator_addressinconfig.toml. Ifoperator_addressis already set to a different account, it refuses; - chooses the post-quantum key the node signs with, stores it as
operator-pqcand setskey_nameto it. If the account already has a post-quantum key — usually registered by a wallet from the same words — that key is rebuilt from the words (the wallet-adapter and Dashboard derivations, the same asqorechaind tx pqc recover-key). If the account has none, a key is derived from the words, so the words also restore the node's key. If the account's registered key is already the node's current key, that key is kept. If the account's key cannot be reproduced from the words, the command refuses and advises a dedicated account; - names where the licence comes from for the network in use: a Dashboard purchase on mainnet, the free self-service request on testnet;
- without
--recover, creates a new account and shows its 24 words once. Write them down; they are the only backup. Fund the account and buy the licence for its address before you register.
The keyring passphrase (QORE_LIGHTNODE_KEYRING_PASSPHRASE) protects this key as well as the node key. Then register:
lightnode-sx register --delegate-to qorvaloper1...
register checks the licence, attaches the post-quantum key unless the account already has it, delegates the missing stake only if you name a validator with --delegate-to, and registers the node; each step is confirmed in a block before the next. See Registration and Licensing for the details and for the register --print fallback for operators who keep the account key in a qorechaind keyring.
Protections added in 3.1.14
- Key import stays out of the process list.
keys import <name>reads the hex private key from standard input or from--key-file <file>. A key typed as a second argument is refused.--unsafe-argvrestores the old form with a warning. - The keystore is written atomically.
keystore/keys.encis replaced in one step and the previous version is kept askeystore/keys.enc.bak. After setup, back upkeys.enc(or your recovery words) somewhere off the machine. - Bounded auto-claim. The node checks at most every 10 minutes (a lower
compound_intervalis raised to10m) and submits at most one claim every 6 hours. - Bounded dashboard connections. The dashboard WebSocket accepts at most 32 connections.
- Bounded chain responses. Every chain REST response is capped at 4 MiB. At start the node warns if
api_addris plainhttp://to another machine: usehttps://.
Management commands
The SX CLI includes commands for inspecting node state and managing keys. Since 3.1.7 the UX binary (lightnode-ux) has the same commands.
| Command | Purpose |
|---|---|
onboard | Interactive first-run wizard. |
start | Run the daemon. |
selftest | Run the PQC self-test. |
status | Show node and light-client sync status (chain ID, latest height, catch-up state) plus the Signer (native or qorechaind), Operator, Licence and Registration lines. |
keys create <name> | Create a new Dilithium-5 node key and print its public key. |
keys list | List keys in the keyring (name, type, address if any, public key). |
keys show <name> | Print a key's type and full public key. |
keys import <name> [--key-file <file>] | Import a hex-encoded private key. From 3.1.14 the key is read from standard input, or from --key-file <file>. A key given as a second argument is refused, because it would show in the process list and in the shell history; --unsafe-argv restores the old form with a warning. |
keys export <name> [--out <file>] | Export a private key in hex. --out writes the file qorechaind --pqc-key reads (no trailing newline, mode 0600). |
keys add-operator [--recover] | Store the operator account key (new, or recovered from its words on standard input) and choose the post-quantum key; fills in operator_address. See The operator wallet. |
register [--delegate-to <qorvaloper>] [--print] | Register the node on chain: post-quantum key, missing stake, registration, each confirmed in a block. --print prints the qorechaind commands instead — see Registration and Licensing. |
validators | List bonded validators. |
delegation | Show the operator account's delegations, as mirrored into the local database by the running daemon. |
rewards | Show the operator account's pending staking rewards (not light-node rewards; see Rewards and Monitoring). |
network | Show network telemetry (recent synced headers) from the local database. |
update [--check] | Light node 3.1.11 and later. --check says whether a newer release exists; without it, verify, install and keep the previous binary as <name>.old. Restart the node afterwards. See Updating. |
version | Print the binary version. |
For staking, rewards, and monitoring details see Rewards and Monitoring. For getting registered on-chain, see Registration and Licensing.