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=4003

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:

Naming Conventions

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.