Component Map

This document describes all 14 XChain Platform services, their roles, inputs, outputs, and connections. Services are grouped by function. For detailed documentation on any individual service, see the corresponding subdirectory under ../components/.

Service Groups

Core Pipeline

These three services form the backbone of the platform. Data flows from coin node through decoder and indexer to explorer in one direction only.

xchain-decoder

Key technical details:

• Parses transactions using bitcoinjs-lib with coin-specific pre-processing: Litecoin requires stripping the HogEx flag; Dogecoin requires stripping AuxPoW merge-mining headers.
• Deobfuscates each output using AES-128-CTR with a key derived from the first input’s txid. Identifies XChain payloads by the XCHN magic prefix.
• Detects chain reorganizations by comparing stored block hashes. On reorg, rolls back to the last common ancestor before resuming.
• Tracks the mempool separately to support the dispenser protocol (unconfirmed transaction response).
• Runs as one instance per chain/network combination.

See ../components/decoder/ for full documentation.

xchain-indexer

Key technical details:

• Routes each ACTION string to one of ~30 dedicated handler classes (IssueAction, SendAction, OrderAction, PriceAction, etc.).
• Validates all fields before execution. Invalid actions are recorded with status invalid and produce no ledger effects.
• Maintains a double-entry ledger: every token movement is a credit to one address and a debit from another. Balance = SUM(credits) - SUM(debits). A sanity check asserts token_supply == net ledger total after each issuance.
• Holds XCHAIN gas in escrow for time-bounded operations (orders, dispensers). Releases escrow on expiration or cancellation.
• DEX matching engine handles ORDER and SWAP actions, matching bids and asks within each block.
• Processes expirations after each block: open orders and active dispensers past their block height are closed automatically.
• All writes for a block are wrapped in a single MariaDB transaction. Either the full block commits or it rolls back entirely.
• On reorg, rolls back across 40+ tables in a single transaction, then re-processes from the reorg block.
• Watchdog timer (5-minute default) restarts the indexer if it hangs during block processing.
• Runs as one instance per chain/network combination.

See ../components/indexer/ for full documentation.

xchain-explorer

Key technical details:

• Over 50 REST endpoints covering tokens, balances, orders, dispensers, transactions, events, market data, and more.
• JSON-RPC 2.0 interface compatible with Counterparty-style tooling.
• Bootstrap-based web UI with Highcharts for order book and market price visualization.
• Reads configuration from xchain-hub every 60 seconds (fee schedules, supported parameters, fiat pricing).
• Approximately 5,500 lines of SQL query logic. All queries are parameterized; no ORM.
• Supports SSL/TLS termination.
• Runs as one instance per chain/network combination.

See ../components/explorer/ for full documentation.

Data Replication

xchain-sync

Key technical details:

• Runs as a single instance serving all chains/networks on the node — discovers installed indexers by calling the hub’s getallconfigs method.
• Operates in two modes: server mode (polls indexer databases and serves data) and client mode (replicates from remote sync servers).
• Polls each indexer database for new blocks every 3 seconds (configurable). Builds a complete block payload from all affected tables and broadcasts to WebSocket subscribers.
• Full snapshots are streamed as gzip-compressed JSON for bootstrapping new validators.
• Incremental snapshots provide deltas since a given block height for catch-up after downtime.
• Data integrity is verified using the indexer’s existing per-block chained SHA256 hashes (ledger, actions, contracts). No additional Merkle tree implementation needed.
• Clients can sync from 2+ independent sources and cross-verify block hashes to detect tampered data.
• Reorg detection mirrors the indexer’s pattern: detects rollbacks in the source database and broadcasts reorg events. Clients roll back their local replicas using the same table lists as the indexer’s Rollback.js.

See ../components/sync/ for full documentation.

Transaction Creation

These services support the construction and submission of XChain transactions.

xchain-encoder

Key technical details:

• Selects encoding format based on payload size: OP_RETURN (≤80 bytes/output, 76 bytes user data, 1 tx), multisig (~61 bytes/key, 1 tx), P2SH (≤476 bytes, 2 tx), P2WSH (≤9,956 bytes, 2 tx).
• P2SH and P2WSH use a two-transaction pattern: fund tx commits funds to a script; reveal tx spends it, embedding the data in the unlocking script.
• Obfuscates payloads with AES-128-CTR. Key and IV are derived from the first input’s txid — deterministic and reversible by any party with the txid.
• Available as a Node.js JSON-RPC service and as a browser bundle via webpack.
• The encoder itself has no per-chain specialization; coin node interaction happens at the caller level.

See ../components/encoder/ for full documentation.

xchain-utxo-tracker

Key technical details:

• LevelDB key schema uses single-character prefixes: B=block, T=transaction, I=input, O=output, H/J=address hints.
• Processes blocks in batches of 100, writing each batch atomically to LevelDB.
• Maintains 10 blocks of undo history to support chain reorganization rollback.
• Tracks the mempool for real-time unconfirmed UTXO state.
• Supports bootstrap from tar archives to avoid re-indexing from genesis.
• Outputs are indexed by scriptPubKey hash, enabling efficient address lookups.
• Runs as one instance per chain/network combination.

See ../components/utxo-tracker/ for full documentation.

xchain-sdk

Key technical details:

• Exposes 30 action construction methods (one per ACTION type) and 48 explorer query wrappers.
• Batch builder allows multiple actions to be combined into a single BATCH action string.
• Discovers service endpoints via xchain-hub.
• Implements retry with exponential backoff and connection pooling for all outbound calls.
• Supports request hooks (pre/post processing middleware).
• Three deployment modes: Node.js library, JSON-RPC microservice, browser bundle via webpack.

See ../components/sdk/ for full documentation.

Infrastructure

These services manage deployment, configuration, and testing.

xchain-hub

Key technical details:

• Operates in two modes: standalone (simple config oracle) and validator mode (full PBFT consensus, P2P gossip, oracle, cross-chain attestation, governance).
• Supports multi-instance deployment — multiple hub instances against shared MariaDB, with consumer fallback via HUB_VALIDATORS.
• Config writes go through PBFT consensus in validator mode (PRE_PREPARE → PREPARE → COMMIT with 2f+1 quorum).
• Decentralized price oracle: validators fetch from CoinGecko/CoinMarketCap, aggregate via trimmed median (discard top/bottom 15%), finalize via PBFT.
• Cross-chain attestation engine with per-chain-pair validator subsets and confirmation thresholds (BTC: 6, LTC: 12, DOGE: 60; env-tunable via XCHAIN_CONFIRMATIONS_<COIN>).
• SWAP lifecycle tracking: initiated → attested → executed → settled.
• Off-chain governance: 7-day voting period, 2/3+ approval, 50% quorum, parameter change bounds enforcement.
• Reward tracking and slash detection for oracle participants.
• Ed25519 validator identity for P2P message signing.
• Explorer and SDK poll the hub every 60 seconds to refresh their config caches.

See ../components/hub/ for full documentation.

xchain-node

Key technical details:

• Downloads and configures coin nodes (bitcoind, litecoind, dogecoind) alongside all platform services.
• Creates Docker containers with a consistent naming scheme: xchain-node-{service}-{coin}-{network}.
• All containers share a Docker bridge network, enabling DNS-based service discovery.
• Blessed TUI provides a real-time status dashboard in the terminal.
• Supports create, start, stop, update, and monitor operations per container.
• A single xchain-node installation can manage multiple chains and networks simultaneously.

See ../components/node/ for full documentation.

xchain-regtest-miner

Key technical details:

• On detecting mempool transactions, waits up to 30 seconds (resetting to 5 seconds on each new arrival) before mining.
• Inbound JSON-RPC control API: ping, send_funds, fill_mempool, continue_mining, set_mining_time.
• Only used in regtest; not deployed in testnet or mainnet environments.

See ../components/regtest-miner/ for full documentation.

xchain-e2e-test

Key technical details:

• Uses BIP39/BIP32 wallet generation to create deterministic test addresses.
• Tests run in order and share blockchain and indexer state — each test builds on the output of prior tests.
• Discovers service endpoints from xchain-hub.
• Requires xchain-regtest-miner to be running to advance blocks.

See ../components/e2e-test/ for full documentation.

xchain-dashboard

Key technical details:

• Standalone-runnable with no plugins loaded — serves login, user management, audit log, styleguide, welcome page, and /health on port 7800.
• Discovers plugins via XCHAIN_DASHBOARD_PLUGINS=/abs/path/to/plugin[,/abs/path/to/plugin2]. Each path is require()d and must resolve to a manifest object with required fields name, mountPath, router, sidebar, and settings.
• Plugin routers are mounted at their declared mountPath; sidebar entries are merged into the global chrome automatically.
• A bundled monitor plugin is always loaded regardless of the env var.
• Auth is opt-in: AUTH_REQUIRED=true enables session-based login (MariaDB-backed sessions, bcrypt passwords). Without it, all requests run as a synthetic admin.
• First-run setup wizard at /setup collects MariaDB credentials and writes data/config.json.
• Roles: admin, operator, viewer. Routes opt in to gating via requireAuth / requireRole.
• Session secret persisted in data/session-secret so logins survive restarts; override with SESSION_SECRET env var.

See ../components/dashboard/ for full documentation.

Full Connection Diagram

                         +------------------+
                         |   xchain-hub     |  (MariaDB)
                         | config + oracle  |
                         +------------------+
                           ^    ^    ^    ^
                    config |    |    |    | config
                           |    |    |    |
         +-----------+     |    |    |    |     +-----------+
         | xchain-   |-----+    |    |    +-----| xchain-   |
         |   sdk     |          |    |          | explorer  |
         +-----------+          |    |          +-----------+
               |                |    |                |
               | JSON-RPC       |    |         SQL    |
               v                |    |         reads  v
         +-----------+          |    |     +------------------+
         | xchain-   |          |    |     | Indexer MariaDB  |
         |  encoder  |          |    |     | XChain_{C}_{N}_  |
         +-----------+          |    |     | Indexer          |
               |                |    |     +------------------+
               | PSBT           |    |                ^
               v                |    |         SQL    |
         User signs +           |    |         writes |
         broadcasts             |    |     +-----------+
               |                |    |     | xchain-   |
               v                |    +-----| indexer   |
         +-----------+          |          +-----------+
         | Coin Node |          |                ^
         | (bitcoind |          |          SQL   |
         |  etc.)    |          |          reads |
         +-----------+          |     +------------------+
               ^    |           |     | Decoder MariaDB  |
               |    | JSON-RPC  |     | XChain_{C}_{N}_  |
          mine |    | polling   |     | Decoder          |
               |    v           |     +------------------+
         +-----------+          |                ^
         | regtest-  |          |         SQL    |
         |  miner    |          |         writes |
         +-----------+          |     +-----------+
                                +-----| xchain-   |
         +-----------+                | decoder   |
         | utxo-     |<-- polling ----+-----------+
         | tracker   |-- LevelDB         ^
         +-----------+                   |
               ^                  JSON-RPC polling
               | JSON-RPC                |
               | queries           +-----------+
               +-------------------| Coin Node |
                                   +-----------+

Multi-Chain Deployment

Each core pipeline service (decoder, indexer, explorer, utxo-tracker, encoder) runs as a separate instance per chain/network combination. xchain-hub runs as a single shared instance across all chains.

A full mainnet deployment across all three supported chains requires:

Adding a new chain means adding one more set of pipeline instances (coin node + decoder + indexer + explorer + utxo-tracker + encoder) and registering them with the hub.

Deployment Configurations

Minimal (regtest development):

• 1 coin node (regtest)
• decoder + indexer + explorer + encoder + utxo-tracker (all pointing to regtest)
• xchain-hub
• xchain-regtest-miner
• xchain-e2e-test (run on demand)

Full mainnet:

• 3 coin nodes + full pipeline set per coin + xchain-hub + xchain-node
• No regtest-miner or e2e-test in production

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.