XChain Node: Configuration

Config File System

xchain-node uses a two-layer configuration system to generate environment variables for each managed service:

1. Hardcoded defaults: defined in ConfigService.js for each module type (40+ variables per coin-specific service)
2. Config file overrides: read from config/{coin}-{network} files in KEY=VALUE format

Config files are plain text with one variable per line. Values containing = (such as base64 tokens or passwords) are handled correctly; only the first = on each line is treated as the separator. Blank lines and lines without = are skipped.

Example config/bitcoin-mainnet:

NODE_EXPOSED_PORT=8333
DUST_AMOUNT=546
ENCODER_API_PORT=3003

When a config file is missing, xchain-node falls back to hardcoded defaults with a console warning.

Environment Variables

Coin-Specific Services

For each coin-specific service (encoder, decoder, utxo-tracker, indexer), xchain-node generates the following environment variables:

Regtest-only variables (added only when network === 'regtest'):

Shared Services

For shared services (hub, explorer, sync), a separate set of variables is generated without coin/network-specific values:

Two generated defaults worth knowing about:

• EXPLORER_PORT_HTTP / EXPLORER_PORT_HTTPS (and legacy EXPLORER_PORT) are honored from the host environment, so an operator can move the explorer’s published ports without editing generated config.
• On regtest, fresh indexer installs default INDEXER_ALLOW_UNAUTHENTICATED=true when no INDEXER_API_KEY is configured: the indexer otherwise fails closed and every gated method 401s, which no local single-operator regtest stack can pass. A config-file value or host INDEXER_API_KEY still wins; mainnet and testnet stay fail-closed.

Naming Conventions

Operator / Runtime Environment Variables

These variables are read by xchain-node itself at startup. They control runtime behaviour such as module source overrides, telemetry, bootstrap integrity, and the Docker naming prefix. Set them in the invoking shell or a systemd unit before running any xchain-node command.

Telemetry collector

These configure a hub acting as the telemetry collector, and are forwarded into its generated .env. They are distinct from XCHAIN_NODE_NO_TELEMETRY, which controls whether this node reports.

Bootstrap

Go-live gate

xchain-node runs a pre-flight check before deploying a mainnet write surface (and before the hub and sync shared services, which deploy with no coin/network). It refuses the deploy if the configuration is not launch-ready.

Note on XCHAIN_NODE_EXTERNAL_DB_ROOT_PASSWORD: this is a credential value. Pass it via your deployment environment or secrets manager; do not store it in config files checked into version control.

Host Environment Variables (path overrides)

These env vars override where xchain-node stores its filesystem state on the host. Set them in the shell, systemd unit, or host-provisioning playbook before invoking xchain-node install or any other command. All five fall back to their in-repo defaults if unset, so existing installs are unaffected.

⚠️ Testnet / regtest write to a network-prefixed subdirectory. Dogecoind and litecoind place block data under a per-network subdirectory of the datadir on every network except mainnet:

Coin / network	Blocks land in
DOGE / LTC mainnet	blocks/
DOGE testnet	testnet3/blocks/
LTC testnet	testnet4/blocks/
DOGE / LTC regtest	regtest/blocks/

This matters if you ever try to free up disk by hand-mounting only the bare blocks/ path, e.g. -v /misc/dogecoin/testnet/blocks:/root/.dogecoin/blocks. On testnet/regtest the daemon writes to testnet3/blocks/ (etc.), which that bind does not cover, so the mount silently catches nothing and blocks keep accumulating on the default disk. No error is raised.

XCHAIN_NODE_BLOCKS_DIR avoids this trap entirely: xchain-node starts the daemon with -blocksdir=/blocks, which the daemon honours on every network, so all per-network subdirectories land inside the mounted path (/blocks/testnet3/blocks/, /blocks/regtest/blocks/, …). A single host bind therefore covers mainnet, testnet, and regtest uniformly. See Disk Management for the full disk-offload guide.

Recommended setup for OVH RISE-3 chain-node boxes

On the RISE-3 archetype (small / partition, large /misc SATA mirror), set these before installing:

export XCHAIN_NODE_DATA_DIR=/misc/xchain-node-data
export XCHAIN_NODE_TMP_DIR=/misc/xchain-node-tmp
export XCHAIN_NODE_MODULES_DIR=/misc/xchain-node-modules
export XCHAIN_NODE_CRYPTO_NODES_DIR=/misc/xchain-node-crypto_nodes

Without these overrides the small / partition fills the moment a bootstrap is created (inner work archive + outer archive together can exceed 70 GB for BTC mainnet).

Internal Constants

NODE_PREFIX Validation

The NODE_PREFIX can be overridden via the NODE_PREFIX environment variable. It is validated against /^[a-z0-9][a-z0-9._-]*$/ on load: shell metacharacters, spaces, uppercase letters, and dollar signs are rejected with a clear error.

Port Validation

All port values are validated via validatePort() before reaching Docker command construction:

• Accepts integers 1–65535
• Accepts digit-only strings (“8332”) that parse to valid integers
• Rejects floats, NaN, Infinity, negative numbers, zero, strings with non-digit characters

Branch Name Validation

Branch names are validated against /^[a-zA-Z0-9._\-\/]+$/ in resolveArgs():

• Accepts: master, develop, feature/my-branch_v1.0
• Rejects: master;rm -rf /, master`whoami`, $(whoami)

Container ID Validation

Container IDs returned by docker run are validated against /^[a-f0-9]{64}$/:

• Must be exactly 64 lowercase hex characters
• Rejects IDs with injection payloads, wrong lengths, or non-hex characters

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.