XChain Platform Hub: Configuration

Environment Variables

Silent-failure variables (read this first)

Two variables degrade security when left empty. The hub starts and appears healthy either way, so the misconfiguration is easy to miss.

HUB_API_KEY: empty disables API authentication. When HUB_API_KEY is set, authentication fails closed: mutating methods (updateconfig, registervalidator, propose, vote, requestattestation, reportreorg, initiateswap, the oracle/price push methods) and the hub-DB WebSocket upgrade return 401 unless the caller presents the configured key.

When it is unset or empty, those paths are open, so the hub refuses to boot unless keyless operation is declared with HUB_ALLOW_UNAUTHENTICATED=true. Keyless remains supported (single-host regtest, a hub reachable only on a private network or behind an authenticating proxy), but it has to be a stated choice rather than the result of a forgotten variable. xchain-node sets the declaration automatically when it deploys a hub with no key in the host environment, except on mainnet, where the refusal stands.

Always set a strong, random HUB_API_KEY in production. Generate one with:

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

Clients then send it on each request (the indexer reads the same value as HUB_API_KEY, the encoder-facing services as their own *_ENCODER_API_KEY, and so on).

SIGNING_PRIVKEY_SECRET: empty means unsigned P2P messages and no federation identity. SIGNING_PRIVKEY_SECRET is the Ed25519 private key (a 32-byte seed, encoded as 64 hex characters) that authenticates this hub’s P2P messages to the rest of the validator federation. When the P2P cluster is enabled (see P2P_VALIDATOR_ADDR) but this key is empty, the hub loads no validator identity: outbound messages go out unsigned, and this hub has no verifiable identity among its peers. Nothing fails loudly; the hub simply never participates as an authenticated validator, and depending on peers’ REQUIRE_SIGNATURES its messages may be silently dropped.

Generate a key pair (the private seed is what you set; keep it secret):

# Private seed (set this as SIGNING_PRIVKEY_SECRET):
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

The corresponding public key is derived automatically at startup from the seed (the hub logs the first 16 hex characters of the pubkey when the identity loads). Each validator’s pubkey must be registered in the cluster so peers can verify its signatures.

The key format is validated: it must be exactly 64 hex characters. An invalid non-empty value throws at startup; only the empty case is silent.

Secret variable naming

Automatic secret redaction, in terminals, CI logs and assistant transcripts, keys on the variable name and matches _SECRET, _KEY, or _TOKEN. A name like HUB_DB_PASS matches nothing, so the value prints in full every time someone reads the env file.

Three hub secrets accept a _SECRET name, with the historical name kept as a deprecated fallback so no running deployment breaks:

The hub logs a warning at startup for each secret still supplied under the deprecated name. Setting both names to different values is a startup error, not a precedence rule: that shape is a half-finished rename, and picking a winner is how a hub keeps authenticating with the credential it was supposed to rotate away from. Renaming does not un-leak anything by itself: a credential that has already been read out loud still has to be rotated.

Core (Required)

These variables are required regardless of operating mode.

Telemetry Collector

The hub is the single collector for anonymous node-operator telemetry (the telemetry_pings table; see Database Schema below). The raw client IP is never stored: at ingest the hub derives a coarse country/region and a keyed one-way hash, then discards the IP.

Metrics and Log Shipping

The shared observability module adds a Prometheus scrape endpoint and a structured log shim. Both are off unless set here: with no variables the hub registers no extra route, starts no timer, and opens no socket.

P2P Gossip Layer

Validator mode is activated when P2P_VALIDATOR_ADDR is set. All P2P-dependent subsystems (consensus, oracle, cross-chain, reorg, governance) are no-ops without it.

Capability Configuration

Capability staking decides which of the five capabilities (price, cross_chain, oracle_publish, attestation, full_node) a validator is qualified and ready to serve. The hub loads this from the JSON file at HUB_CAPABILITY_CONFIG, applies it on startup, and hot-reloads on file change. It supplies two things:

• CAPABILITIES.<cap>.MIN_STAKE: the stake threshold a pubkey must meet (queried from the indexer) to qualify. If a capability has no configured MIN_STAKE, the hub treats it as not qualified (fail-closed); it does not default to 0.
• Per-capability self-test config blocks, checked locally so the hub only participates when it can actually serve:
  • price: { "sources": [...], "fiats": [...] }
  • cross_chain: { "chains": { "BTC": { "rpc": "..." }, ... } }
  • oracle_publish: { "doge_address": "...", "doge_wallet": "..." }
  • attestation: { "providers": { "<id>": false } } (omit a key to enable it)
• DISABLED_CAPABILITIES: array of capabilities to opt out of even when qualified.

{
  "CAPABILITIES": {
    "price":          { "MIN_STAKE": "1000.00000000" },
    "oracle_publish": { "MIN_STAKE": "500.00000000" }
  },
  "DISABLED_CAPABILITIES": ["cross_chain", "attestation"],
  "price": { "sources": ["coingecko"], "fiats": ["USD"] },
  "oracle_publish": { "doge_address": "D...", "doge_wallet": "/data/.dogecoin/wallet.dat" }
}

xchain-node validator init generates a starter file and xchain-node install mounts it into the hub container automatically. See OPERATIONS.md → Validator Mode.

PBFT Consensus

Hub-DB WebSocket (GET /hub-db/subscribe)

Caps on the live-update channel indexers subscribe to. See API.

Indexer tip freshness

The hub reads the BTC chain tip to anchor consensus rounds. These gates stop a stale tip from locking an out-of-date validator set into a round.

Oracle

Oracle Publishing

Controls OraclePublisher, which broadcasts finalized price rounds on-chain as DOGE PRICE actions.

Rewards and Slashing

ANCHOR Publishing

Controls StateAnchorPublisher (commits checkpoints and the cross-chain match archive on-chain via the DOGE ANCHOR action) and RewardTracker (anchor-publish reward amount).

Why those magnitudes (before you retune them)

None of the ANCHOR knobs is consensus data: hubs on different values still produce mutually verifiable anchors. Three of them do encode a real bound, and the full derivation is in ANCHOR.md:

• ANCHOR_CHUNK_MAX_BYTES = 6000 reserves head room under the protocol’s 8192-byte MAX_ACTION_DATA_LENGTH ceiling, because chunk 0 shares its action with the checkpoint prefix (~322 bytes) and the signature lists (194 bytes per (PUBKEY, SIG) pair, doubled on a v6). What is left is about nine signature pairs on a v1, or 4+4 on a v6, so lower this as the federation grows: a 5+5 v6 quorum needs ~5860 or less, a 7+7 quorum ~5080. Exceeding the ceiling is silent, since the decoder simply drops the action.
• ANCHOR_MATCH_BATCH_SIZE = 200 is an early-flush latency trigger and ANCHOR_MAX_BATCH = 1000 is the per-cycle DOGE spend bound. Archive rows are signature-dominated and barely compress (~0.55 KB of gzip+base64 per settled match), so 1000 rows is ~550 KB, ~93 chunks, ~93 DOGE transactions in a cycle; 200 rows is ~19.
• ANCHOR_ELECTION_TOLERANCE_BLOCKS = 36 is ~6 hours of BTC blocks per failover rank, counted in blocks rather than wall clock so every hub agrees on the unlock without clock sync. The ordering carries the meaning: signing round (120s) + DOGE burial (60 confs, ~1h) << 36 blocks (~6h) << ANCHOR_INTERVAL_MS (24h). Roughly 6 to 144 blocks keeps both bounds; a wrong value costs duplicate DOGE spend or delayed anchoring, never a divergence.

Attestation Publishing

Controls AttestationPublisher, which writes the validator network’s answers to contract attestation requests back on-chain.

Attestation Relay

Controls AttestationRelay, the driver that carries attestation requests to the validator network and the response leg back. Attestation staking lives on Bitcoin, so an ATTEST request made on an origin chain (LTC, DOGE) is relayed to BTC as a v3 request, and the finalized answer is relayed back to the origin chain as a v4 response. The relay therefore needs a broadcast rail on every origin chain it serves, not just on the home chain.

Per-origin-chain broadcast rail

The variables below are read dynamically (process.env[coin + '_ENCODER_URL'] and friends) for each origin chain, so a static scan of the source will not list them; <COIN> is any allowed coin other than BTC, so today LTC and DOGE. Each also resolves from the hub’s p2pConfig; the env var wins.

Leaving an origin chain’s rail unconfigured does not fail loudly. The v4 response is still consensus-finalized and then held forever, behind one startup warning (no <COIN> broadcast rail). Responses are held rather than dropped, so the recovery is to configure the rail and restart, but nothing re-warns in the meantime. Check attest_relay on /health to see the hold: a rising awaiting_broadcast with a flat responses_relayed is this misconfiguration.

The home (BTC) rail reuses the BTC attestation publisher variables above (BTC_ENCODER_URL, BTC_ADDRESS, BTC_PUBKEY_HEX, BTC_INDEXER_API_URL). Origin rails are deliberately kept separate from it: an operator broadcast hook configured for one chain would put an LTC payload on BTC, where it is rejected outright after burning a real BTC fee. Spend limits come from the shared spend guard under the ATTEST prefix (see Effector Spend Policy below), and confirmation depths from XCHAIN_CONFIRMATIONS_<COIN>.

Effector Spend Policy

Every hub effector that spends real coin on-chain runs behind a shared spend guard: a balance floor, a rolling per-window spend ceiling (hard-clamped at a $2000 admission ceiling), and a per-capability runtime pause. The knobs below take a per-effector <PREFIX>; the four prefixes are ORACLE_PUBLISH, ATTEST, ANCHOR, and FULLNODE. Each variable also resolves from p2pConfig; the env var wins. The spend ceiling is default-enabled: unset config yields the $2000 clamp, never “off”.

Runtime pause is operator-driven via JSON-RPC (auth-gated): pauseeffectorspend / resumeeffectorspend take { label } (the effector’s guard label, e.g. OraclePublisher), and geteffectorspendstatus lists every effector’s live state. A pause halts the effector’s primary/leader spend path immediately, with no restart.

State Checkpoints

Controls StateCheckpointEngine, which produces the quorum-signed per-block state-hash checkpoints that light clients and xchain-sync replicas verify against.

Full-Node Challenge

Controls FullNodeChallengeRound, the periodic possession challenge proving a validator runs a real coin full node rather than mirroring the decoder and indexer databases. Feeds the full-node verified reward tier and the on-chain NODEPROOF action.

Retraction Consensus

XCHAIN Price Derivation

The XCHAIN/USD price is derived from platform-realized fills rather than an external feed. These read the indexer database holding those fills.

LLM Attestation Provider

Backs the ATTEST path where a contract asks an approved model a question. See Attestation.

Cost note. Each on-chain checkpoint anchor spends real DOGE on three transactions (BTC + LTC + DOGE checkpoints all broadcast on the DOGE chain). State recovery (recovery.js) only needs the latest anchored checkpoint per chain, so anchoring every intermediate checkpoint_seq is optional. With daily checkpoints (CHECKPOINT_INTERVAL_BLOCKS=144), ANCHOR_CHECKPOINT_EVERY_N=2 halves anchor spend (on-chain recovery point then trails the tip by up to ~2 checkpoint intervals). checkpoint_seq is consensus data, so the gate is deterministic across every hub.

Operator Signer

Cross-Chain

Regtest-only seams. Both engines honour these only when the hub’s network is regtest, and read them as NaN/false everywhere else, so a stray environment variable or config row can never reach the signed snapshot anchor or seed a validator on mainnet or testnet. They deliberately share names between the DEX and XCALL engines so a no-BTC regtest stack is configured once.

Genesis and Regtest Binding

Regtest-only genesis overrides, ignored on mainnet and testnet, which always use the frozen bundled values. Consensus-relevant: they bind the local chain’s genesis anchor.

Fee Destination Override

Reorg

Governance

Database Schema

The hub uses 20 MariaDB tables, auto-created on startup from src/sql/:

Config Storage

Unique constraint on (coin, network, module, param_name) for upsert behavior.

Validator Management

Oracle

Cross-Chain

State Checkpoints and Capability Snapshots

Governance

Rewards and Slashing

Telemetry

Capability Registry

Config Table Detail

Config is served as a nested object: { coin: { network: { module: { param: value } } } }.

Connection Pool

DB_CONNECT_TIMEOUT, DB_ACQUIRE_TIMEOUT, and DB_QUERY_TIMEOUT are read by the indexer’s pool with the same names and the same defaults.

Circuit Breaker

When the circuit opens, all database queries fail fast until the cooldown period expires. Retries use exponential backoff with jitter to prevent thundering herd.

Validator Identity

Ed25519 keys are used for P2P message signing and verification:

• Private key: 32-byte seed from SIGNING_PRIVKEY_SECRET (64 hex chars), wrapped in PKCS8 DER for Node.js crypto.
• Public key: extracted as raw 32-byte SPKI, stored as 64 hex chars.
• Signing: canonical payload is JSON with sorted fields (id, type, sender, timestamp, data).
• Generation: ValidatorIdentity.generate() produces a random keypair.

const { ValidatorIdentity } = require('./src/ValidatorIdentity');
const { privkey, pubkey } = ValidatorIdentity.generate();
// privkey: 64-char hex string for SIGNING_PRIVKEY_SECRET
// pubkey:  64-char hex string for registervalidator

Copyright © 2025–2026 Dankest, LLC

Based on XChain Platform by Dankest, LLC – https://dankest.llc

Licensed under the GNU Affero General Public License v3.0 (AGPL-3.0-or-later) with a commercial license available for proprietary use.

You may use, modify, and distribute this material under the terms of the License. See LICENSE and NOTICE for full terms. See the licensing overview.