XChain Platform Indexer Sync: Configuration

Environment Variables

Common (Both Modes)

These variables are required regardless of whether the service runs in server or client mode.

Server Mode

By default, no database environment variables are needed. The service discovers all indexer and decoder database connections by calling the hub’s getallconfigs method. The hub returns the db_host, db_port, name (database name), user, and pass for every installed indexer and decoder.

Setting REPLICA_DB_HOST overrides that default: the server instead connects to a local replica database, using REPLICA_DB_HOST/REPLICA_DB_PORT/REPLICA_DB_USER/REPLICA_DB_PASS in place of the hub-provided db_host/db_port/user/pass (the database name still comes from the hub, so the replica must use the same name). The hub is still queried, only to enumerate which chains/networks exist. This is how a re-serving tier, a box that already pulled the databases as a client, serves those local replicas onward to downstream clients instead of the authoritative DB coordinates. See Operations: read-only-replica deployment for the full pattern, including pairing this with REPLICA_DB_READONLY when the local replica is fed by something other than this process (for example MariaDB binlog replication).

Client Mode

In client mode, the service connects to remote sync servers and replicates their data into local MariaDB databases.

Hub Discovery

The service calls the local xchain-hub’s getallconfigs JSON-RPC method at startup and every 5 minutes thereafter. The hub returns an envelope { configs, seq, watermark }, where configs holds the nested configuration tree:

{
  "configs": {
    "bitcoin": {
      "mainnet": {
        "xchain-indexer": {
          "host": "xchain-node-bitcoin-mainnet-xchain-indexer",
          "port": "3004",
          "db_host": "mariadb",
          "db_port": "3306",
          "name": "XChain_BTC_Mainnet_Indexer",
          "user": "xchain_indexer_bitcoin_mainnet",
          "pass": "xchain-password"
        }
      },
      "testnet": {
        "xchain-indexer": { ... }
      }
    },
    "dogecoin": {
      "mainnet": {
        "xchain-indexer": { ... }
      }
    }
  },
  "seq": 42,
  "watermark": 1717400000
}

The nested config tree lives under result.configs (not at the top level). seq is the last committed consensus sequence number; watermark is an epoch-seconds high-water mark of the configs table. A consumer may retain watermark and pass it back as the since_updated_at request param on its next getallconfigs call to receive only the rows that changed since the previous poll (delta polling); omitting it returns the full tree.

The service iterates result.configs and, for each coin/network that has an xchain-indexer or xchain-decoder entry, extracts the following fields and creates a separate Database instance with the corresponding dbType (indexer or decoder):

A separate MariaDB connection pool is created per chain/network/dbType.

Database Naming

The sync service uses the same database naming convention as the rest of the platform:

XChain_{TICKER}_{Network}_{Component}

In server mode, the service reads from the authoritative indexer and decoder databases; the same ones the indexer/decoder write to.

In client mode, the service creates replica databases with the same names and schema. Indexer replicas contain an exact copy of the indexer data; decoder replicas contain 8 of the 9 decoder tables (mempool_transactions excluded).

Database Schema

Indexer replicas

Indexer replica databases use the same full schema as the authoritative indexer. The SQL table definitions are shipped with the sync service in src/sql/. Tables include:

• Core: blocks, transactions, actions
• Index/Dedup: index_addresses, index_tickers, index_transactions, index_actions, index_statuses, index_coins, index_fiats, index_memos, index_mime_types, index_pubkeys
• Ledger: credits, debits, escrows, balances, fees, tokens
• Action-specific: sends, issues, destroys, airdrops, dividends, orders, dispensers, swaps, broadcasts, messages, files, links, lists, callbacks, sleeps, sweeps, mints, batches, bet_feeds, bets
• Lifecycle: order_matches, order_expires, order_edits, order_cancels, order_statuses, swap_matches, swap_expires, swap_edits, swap_cancels, swap_statuses, dispenser_closes, dispenser_expires, dispenser_edits, dispenser_cancels, dispenser_statuses, dispenses, bet_feed_statuses, bet_statuses, bet_cancels, bet_resolves
• COINPay: coinpays, coinpay_obligations, coinpay_expires, coinpay_statuses
• Staking: stakes, unstakes, delegations, validator_rewards, reward_claims
• VM: contracts, contract_state, contract_executions, contract_emissions, deposits, withdrawals
• Mapping: mappings_actions, mappings_files
• Other: addresses, markets, events, list_edits, list_items, list_items_invalid

One additional table is used by the sync service itself for indexer replicas only:

• sync_meta: transparency log ((block_index, block_time, ledger_hash, actions_hash, contract_hash, logged_at)) indexer only, not created for decoder replicas

Decoder replicas

Decoder replica databases use a smaller schema derived from the decoder DB. Of the 9 tables in the decoder DB, xchain-sync replicates 8 (mempool_transactions is excluded as it is non-deterministic across nodes):

• blocks, transactions, transaction_outputs, dispensers
• index_addresses, index_transactions, pubkeys, events

The transparency log table (sync_meta) is not created for decoder replicas.

Note on dispensers replication: dispensers is present in the replica but does NOT ride the per-block WebSocket stream. The decoder soft-expires dispenser rows each block (updating expired_block_index) and defers hard-purges to a separate job; neither mutation is block-bound. Streaming only inserted rows would cause a follower’s count to grow monotonically above the source. Instead, dispensers converges to the current source state via full snapshot only. Do not use the per-block row count for dispensers as a completeness signal.

Connection Pool Configuration

Each chain/network/dbType gets its own MariaDB connection pool (from db.js, sized by poolSizing.js). Pool sizes are per dbType, because the two dbTypes carry very different loads: the indexer pool absorbs the poller’s ~113-query-per-block fan-out plus any in-flight snapshot streams, while the decoder pool replicates 8 narrow tables.

Resolution order for every knob above: <NAME>_<DBTYPE>, then the flat <NAME>, then the per-dbType default. Values are clamped to [2, 100] so no single setting can starve the poller or exhaust MariaDB’s max_connections.

Sizing budget: a source serving 3 chains x 2 dbTypes opens 6 pools, so the defaults cost 3 x (12 + 6) = 54 connections.

Measured on a regtest indexer schema with test/perf/pool-fanout-load.js (113 queries/block, 5 ms per query, median of 8 blocks): pool 3 = 213 ms/block, pool 5 = 129 ms, pool 12 = 55 ms, pool 20 = 34 ms. Run that script inside a container that already holds the DB credentials to re-measure on your own hardware before raising a pool.

Circuit Breaker

Each connection pool has an independent circuit breaker:

When a circuit opens, all queries to that chain/network fail fast until the cooldown period expires. Other chains’ circuits are unaffected.

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.