XChain Platform Indexer

What is xchain-indexer

xchain-indexer is the state-processing engine of the XChain Platform. It reads decoded blockchain transactions from the Decoder database, validates and executes each ACTION according to protocol rules, maintains authoritative token state (balances, supplies, ownership, DEX orders, dispensers) in a separate MariaDB database, and makes that indexed data available for querying by xchain-explorer. The indexer runs as a long-lived Node.js process with an embedded Express JSON-RPC API server.

Every XChain ACTION — SEND, ISSUE, MINT, ORDER, DISPENSER, SWAP, and 22 more — passes through the indexer. The indexer determines whether the action is valid (checking balances, permissions, token rules, allow/block lists, sleep states), records the action with its status, updates the ledger (credits, debits, escrows), recalculates balances, and runs a sanity check after every block to guarantee consistency between token supplies and ledger totals.

Features

26 ACTION types — ADDRESS, AIRDROP, ATTEST, BATCH, BROADCAST, CALLBACK, COLLECT, DELEGATE, DEPLOY, DEPOSIT, DESTROY, DISPENSER, DISPENSE, DIVIDEND, EXECUTE, FILE, ISSUE, LINK, LIST, MESSAGE, MINT, ORDER, SEND, SLEEP, STAKE, SWAP, SWEEP, UNSTAKE, WITHDRAW
Multi-chain support — Bitcoin, Litecoin, and Dogecoin on mainnet, testnet, and regtest
Atomic block processing — every block is wrapped in a database transaction; failures roll back cleanly
Block reorganization handling — detects reorgs from the Decoder DB, rolls back affected data, and re-indexes
Double-entry ledger — all token movements recorded as credits, debits, and escrows
Sanity checking — after every block, verifies token supplies match the sum of credits minus debits
DEX engine — ORDER matching, SWAP matching, DISPENSER triggering with automatic expiration
Staking — capability staking (STAKE v1/v2, UNSTAKE v0, DELEGATE v0/v2, COLLECT) is BTC-only; contract-targeted staking (STAKE v3, UNSTAKE v1, DELEGATE v1/v3) works on any chain
Virtual Machine — DEPLOY, EXECUTE, DEPOSIT, WITHDRAW with isolated-vm sandbox and gas metering
Unified Gas Fee Schedule — gas-based fee system for VM and staking actions, replaces per-action flat fees post-activation
Protocol versioning — actions activate at specific block heights or timestamps per network
Action mapping — creates address↔ticker↔action_index cross-references for fast lookups
Circuit-breaker DB connections — automatic failure detection and recovery for database connectivity
Watchdog timeout — configurable per-block processing timeout detects deadlocks
978 tests — unit, integration, e2e, fuzz, chaos, mutation, boundary, smoke, performance, regression

Documentation

Document	Description
Architecture	Data pipeline, internal components, action handlers, block processing pipeline
Configuration	Environment variables, coin-specific config, indexer constants
Actions	All 30 ACTION types, categories, format versions, protocol versioning
Database	Full schema reference — core, ledger, action, state, index, and mapping tables
Ledger	Double-entry ledger, balance calculation, sanity checks, gas token fees
Operations	Running, Docker, API endpoints, resilience, troubleshooting

Installation

Clone the repository and install dependencies from within the xchain-indexer directory:

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

Quick Start

Create a .env file with the required environment variables (see Configuration for full details):

DECODER_DB_HOST=localhost
DECODER_DB_PORT=3306
DECODER_DB_NAME=XChain_BTC_Mainnet_Decoder
DECODER_DB_USER=xchain_reader
DECODER_DB_PASS=your_password

INDEXER_DB_HOST=localhost
INDEXER_DB_PORT=3306
INDEXER_DB_NAME=XChain_BTC_Mainnet_Indexer
INDEXER_DB_USER=xchain_writer
INDEXER_DB_PASS=your_password

INDEXER_API_PORT=3000
INDEXER_COIN=BTC
INDEXER_NETWORK=mainnet

Start the indexer:

npm run api

On startup, the indexer:

Validates all required environment variables
Starts the Express JSON-RPC API server
Creates the Indexer database if it doesn’t exist
Creates all required tables if they don’t exist
Begins the block polling loop

Scripts

Command	Description
`npm run api`	Start the indexer and API server
`npm test`	Run unit tests (~820 tests)
`npm run test:integration`	Integration tests (~929 tests, requires MariaDB)
`npm run test:e2e`	End-to-end tests (43 tests, requires full stack)
`npm run test:boundary`	Boundary condition tests
`npm run test:smoke`	Smoke tests (unit + connected)
`npm run test:security`	Security tests
`npm run test:fuzz`	Fuzz tests (property-based)
`npm run test:fuzz:quick`	Quick fuzz (1,000 iterations, tier1)
`npm run test:fuzz:full`	Full fuzz (10,000 iterations)
`npm run test:chaos`	Chaos engineering tests
`npm run test:mutation`	Mutation tests
`npm run test:mutation:tier1`	Tier1 mutation tests
`npm run test:mutation:report`	Mutation tests with coverage report
`npm run test:perf`	All performance tests
`npm run test:regression`	Regression tests (tagged across all suites)
`npm run test:regression:fast`	Fast regression (tier1 + tier4, unit only)
`npm run test:regression:full`	Full regression suite
`npm run test:nodb`	All tests that don’t require a database
`npm run test:full`	Complete test suite

Dependencies

Runtime

Package	Purpose
`express`	HTTP server for the JSON-RPC API
`express-json-rpc-router`	JSON-RPC 2.0 request routing
`helmet`	HTTP security headers
`cors`	Cross-Origin Resource Sharing
`dotenv`	Environment variable loading from `.env` files
`mariadb`	MariaDB/MySQL client with connection pooling
`mathjs`	Arbitrary-precision arithmetic for token amounts and fees

Development

Package	Purpose
`mocha`	Test framework
`sinon`	Mocking, stubbing, and spying for tests
`fast-check`	Property-based (fuzz) testing

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.