Deployment

This guide covers deploying the XChain Platform from scratch, from a single-chain regtest setup to a full multi-chain mainnet installation.

Prerequisites

Software

• Docker — Engine 20.10 or later. Docker must be accessible to the current user (add user to docker group or run as root).
• Node.js — v18 or later (required to run xchain-node CLI).
• Git — to clone xchain-node.

Verify Docker is working before proceeding:

docker info

Disk Space

Blockchain data can be substantial. Budget accordingly before starting a mainnet sync:

Add headroom for the indexer and decoder databases. A full BTC + LTC + DOGE mainnet deployment should have at least 1.5 TB of free disk space. For regtest, a few gigabytes is sufficient.

Network Ports

Each service exposes a JSON-RPC port. Make sure these are not blocked by firewall rules on the host if external access is needed. Default ports differ per coin and network. See Configuration for a full port listing.

Installing xchain-node

xchain-node is the CLI tool that installs, starts, stops, and monitors all other services as Docker containers.

git clone https://github.com/XChain-Platform/xchain-node
cd xchain-node
npm install

Optionally install the xchain-node symlink globally:

# Follow the steps in INSTALL.md inside the xchain-node directory

After installation, verify the CLI is working:

xchain-node --help
# or if installed globally:
xchain-node --help

Running the Installer

The install command clones the target service from GitHub, builds its Docker image, and registers it with the hub. The all keyword installs every service for a given chain and network in the correct dependency order.

xchain-node install main all bitcoin mainnet

Arguments: install <branch> <service> [chain] [network]

• branch — Git branch to install from (e.g., main).
• service — all, or a specific service name such as xchain-decoder.
• chain — bitcoin, litecoin, dogecoin, or all.
• network — mainnet, testnet, or regtest.

The installer automatically ensures xchain-hub is installed first, since other services depend on it for configuration.

Starting Services

Start all services for a chain:

xchain-node start all bitcoin mainnet

Start a single service:

xchain-node start xchain-decoder bitcoin mainnet

Check running container status:

xchain-node ps

Deployment Configurations

Full Multi-Chain Mainnet (BTC + LTC + DOGE)

A full mainnet deployment runs one coin node, decoder, indexer, encoder, and UTXO tracker per chain, plus one shared hub, explorer, and MariaDB instance.

Install each chain in sequence:

xchain-node install main all bitcoin mainnet
xchain-node install main all litecoin mainnet
xchain-node install main all dogecoin mainnet

Minimum recommended resources for the full three-chain stack:

Single-Chain Deployment

If only one chain is needed, install only that chain:

xchain-node install main all litecoin mainnet

This reduces resource requirements proportionally. A single-chain LTC or DOGE deployment can run comfortably on a 4-core, 8 GB RAM machine with 250 GB of disk.

Regtest Deployment (Development / Testing)

Regtest uses local blockchain simulation with no real network sync. This is the fastest way to bring up a fully working stack for development or testing.

xchain-node install main all bitcoin regtest
xchain-node start all bitcoin regtest

Regtest also installs xchain-regtest-miner, which automatically mines blocks when transactions appear in the mempool.

To skip bootstrap archive downloads and force a full parse from block 0:

xchain-node --no-bootstrap install main all bitcoin regtest

Private Deployment (Regtest as Production)

Some operators run a private XChain instance on a permissioned regtest network. The setup is identical to a standard regtest deployment. Control block production via the regtest-miner or by calling generatetoaddress directly on the coin node.

Initial Sync

After starting a mainnet coin node for the first time, it must download and verify the entire blockchain. This can take anywhere from several hours (LTC, DOGE) to multiple days (BTC) depending on disk I/O speed and network bandwidth.

The decoder waits for the coin node to report verificationprogress >= 0.99 before it begins processing blocks. You can monitor coin node sync progress by checking the decoder logs:

xchain-node logs xchain-decoder bitcoin mainnet

The decoder will log when it begins processing blocks after the coin node finishes syncing.

Bootstrap Archives (Optional)

xchain-node can restore a pre-built LevelDB snapshot for the UTXO tracker to avoid rescanning the entire blockchain. This is controlled by the bootstrap command:

xchain-node bootstrap restore xchain-utxo-tracker bitcoin mainnet

Use --no-bootstrap on install to skip this entirely and do a full parse.

Bootstrap signatures

Each published bootstrap archive can carry a detached Ed25519 signature (<archive>.sig). When the consumer machine has the publisher’s public key pinned (src/config/bootstrap_signing_pubkey.pem in the xchain-node checkout, or a path in XCHAIN_NODE_BOOTSTRAP_PUBKEY), the signature is verified before any restore — the checksum embedded inside the archive only detects transport corruption, while the signature proves the archive is the one the publisher built.

By default an unsigned bootstrap restores with a loud warning. Set XCHAIN_NODE_REQUIRE_SIGNED_BOOTSTRAP=1 to refuse unsigned archives outright (recommended once your publisher signs all of them).

Publishers: generate a keypair once —

openssl genpkey -algorithm ed25519 -out bootstrap_signing_key.pem
openssl pkey -in bootstrap_signing_key.pem -pubout -out bootstrap_signing_pubkey.pem

— keep the private key on the publishing host only, set XCHAIN_NODE_BOOTSTRAP_SIGNING_KEY=/path/to/bootstrap_signing_key.pem there so bootstrap create emits a .sig beside each archive, upload the .sig next to the archive, and distribute the public key to consumers (commit it as src/config/bootstrap_signing_pubkey.pem).

Verifying the Pipeline

Once all services are running, verify data is flowing through the pipeline:

1. Coin node is synced: Check decoder logs for active block processing (block numbers should be incrementing).

2. Decoder is writing to its database:

xchain-node exec xchain-decoder bitcoin mainnet \
  "mysql -u root XChain_BTC_Mainnet_Decoder -e 'SELECT MAX(block_index) FROM blocks;'"

3. Indexer is processing decoder output: The indexer block height should be close to (or equal to) the decoder block height. Check indexer logs:

xchain-node logs xchain-indexer bitcoin mainnet

4. Explorer is serving data: Hit the explorer’s HTTP endpoint. By default the explorer runs on port 18080:

curl http://localhost:18080/btc/api/ping

Log Locations

Logs are written to Docker container stdout/stderr. Access them via xchain-node:

xchain-node logs xchain-decoder bitcoin mainnet      # full logs
xchain-node tail xchain-decoder bitcoin mainnet      # follow (tail -f)
xchain-node monitor                                  # multi-pane live monitor (all services)
xchain-node tailmonitor                              # tail + monitor combined

Direct Docker access:

docker logs xchain-node-bitcoin-mainnet-xchain-decoder
docker logs -f xchain-node-bitcoin-mainnet-xchain-decoder

Stopping and Restarting Services

Stop all services for a chain:

xchain-node stop all bitcoin mainnet

Stop a single service:

xchain-node stop xchain-indexer bitcoin mainnet

Restart a service:

xchain-node restart xchain-decoder bitcoin mainnet

Restarting a service does not affect its database. The decoder and indexer resume from where they left off.

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.