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

In server mode, 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.

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.

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
• 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
• COINPay: coinpays, coinpay_obligations, coinpay_expires, coinpay_statuses
• Staking: stakes, unstakes, delegations, validator_rewards, reward_claims
• VM: contracts, contract_state, contract_executions, contract_emissions, contract_balances, 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.

Connection Pool Configuration

Each chain/network gets its own MariaDB connection pool with these parameters (matching the indexer’s db.js defaults):

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.