XChain Platform Explorer: Configuration

Configuration Sources

The explorer resolves configuration from multiple sources in priority order:

1. Environment variables: loaded from .env via dotenv
2. xchain-hub: fetched via JSON-RPC on startup and refreshed every 60 seconds
3. Local config.json: fallback file at src/config.json
4. NODE_CONFIG: JSON string environment variable (alternative to config.json file)

Hub-sourced configuration takes precedence for database connection details, allowing centralized management across all explorer instances. Environment variables control server-level settings (ports, SSL, debug mode).

Environment Variables

Server Settings

WebSocket

See WEBSOCKET.md for the full WebSocket API reference.

Hub Connection

Hub Mirror and Operational Reads

Decoder Health (for /api/status chain lag fields)

The explorer polls each coin’s decoder health endpoint to populate chain_tip, chain_lag_blocks, and decoder_health in /api/status. Configure the URL of each decoder’s JSON-RPC API:

When no decoder URL is configured for a coin, decoder_health is "unconfigured" and chain_tip/chain_lag_blocks are null for that coin.

Indexer API (native-coin fee pre-flight)

The public /{COIN}/api/feequote and /{COIN}/api/feeschedule endpoints proxy to the colocated xchain-indexer JSON-RPC API (which is not internet-facing) so the authoritative fee + oracle-price logic stays single-sourced. Configure the per-coin indexer API URL to enable them; when unset, those two endpoints return 503 (clients then fall back to paying the protocol fee in XCHAIN).

Contract simulation (Read Contract card)

The explorer can run a read-only contract call in the VM to power the contract page’s Read Contract card. It is off by default: the endpoint exists only when explicitly enabled.

Enabling it requires a canonical vendored VM

Setting EXPLORER_VM_QUERY_ENABLED=true is not sufficient on its own. Before it serves a simulation the explorer checks the vendored xchain-vm it loaded, and refuses when that VM is not the consensus epoch this explorer expects or is missing the contract-era gate exports. A refusing endpoint answers 503 with code VM_QUERY_VM_DRIFT and names the reason, and the same reason is logged once at boot whenever the flag is on.

The check exists because a deployed explorer’s bundled VM can go stale silently: the vendored copy is staged by the rollout, not by the git checkout, and its version string moves by a patch while its bytes move by a hundred kilobytes. Simulating in a stale VM would answer contract calls with results the indexers do not agree with, on the same service that serves contract-state proofs, so the endpoint fails closed instead.

The in-process check is coarser than a byte comparison, because a running process has no canonical copy to compare against. The full comparison is bin/check-explorer-vm-drift.sh <host> in the platform checkout: read-only over SSH, it hashes the deployed VM tree against canonical and reads the flag out of the running process. Run it before enabling the flag on a public explorer, and enable only once it reports OK.

SSL/TLS

SSL certificates are loaded from:

• {SSL_DIR}/cert.pem: TLS certificate
• {SSL_DIR}/private.pem: TLS private key
• {SSL_DIR}/ca.pem: Certificate authority chain

If SSL files are not found, only the HTTP server starts.

Font Awesome kit

The web UI loads its generic glyphs from a Font Awesome kit. The kit token is an account credential and the pro license flag is an entitlement claim, so both are supplied per deployment instead of being shipped in the source tree. The explorer assembles /js/fontawesome-kit.js at request time from the vendored kit loader plus these values.

With no token set, /js/fontawesome-kit.js returns an inert stub and the explorer makes no requests to fontawesome.com. The UI still renders: the coin/network glyphs in the navigation bar are local images served from the explorer itself, so only the generic Font Awesome glyphs are absent.

A value that does not match its expected shape (a non-numeric kit id, a license other than free/pro) is ignored with a warning rather than passed through to the browser.

Local Configuration File

The src/config.json file provides database connection details when xchain-hub is not available. Structure:

{
    "databases": {
        "BTC": {
            "mainnet": {
                "host": "localhost",
                "port": 3306,
                "user": "xchain_reader",
                "password": "your_password",
                "indexer": "XChain_BTC_Mainnet_Indexer",
                "decoder": "XChain_BTC_Mainnet_Decoder"
            },
            "testnet": { ... },
            "regtest": { ... }
        },
        "LTC": { ... },
        "DOGE": { ... }
    }
}

Each coin/network entry specifies both the Indexer database (primary data source) and the Decoder database (for raw transaction lookups).

An example template is provided at src/config.json.example.

Checkpoint Schema (Hub-Mirror Tables)

A few tables the explorer serves (state checkpoints, capability snapshots, cross-chain matches) are produced by the hub federation rather than the indexer, and xchain-sync never replicates them. Every serving coin/network therefore needs a checkpoint block in its database config, naming a schema on the same server and credentials as the indexer database:

"checkpoint": {
    "host": "localhost",
    "port": 3306,
    "user": "xchain_reader",
    "pass": "your_password",
    "name": "XChain_Hub_Mirror",
    "self_sync": true
}

There are two ways to provision that schema:

• Self-synced (recommended): set "self_sync": true and configure HUB_API_URL. The explorer creates the schema and its tables itself, downloads a snapshot from the hub, and then follows the hub’s live feed. No hub database needs to exist on the explorer’s server.
• Externally maintained: omit self_sync and point name at a real hub database on the same server (single-server deployments where the hub already runs locally).

Without a checkpoint block for a serving coin, the explorer refuses to start (see ALLOW_NO_COLOCATED_HUB_DB).

In self-sync mode the affected endpoints return HTTP 503 with code MIRROR_NOT_BOOTSTRAPPED until the first snapshot download completes, and afterwards include mirror_bootstrapped and mirror_lag_seconds fields so clients can judge freshness. GET /{COIN}/api/hub-mirror/status reports the mirror’s state. One detail to know: the anchor_txid audit field on cross-chain matches is filled in by the hub after anchor publication; the hub re-broadcasts the stamped row on the mirror feed, so a self-synced mirror picks it up shortly after the anchor lands (a mirror that was offline at that moment catches up on its next bootstrap). The legacy batch_root field only exists on rows stamped by a retired publisher and arrives with the snapshot. All trade-relevant fields arrive immediately.

Hub Discovery

When HUB_API_HOST and HUB_PORT are set, the explorer:

1. Connects to xchain-hub via JSON-RPC (ping to verify, then getallconfigs to fetch)
2. Receives database connection details for all configured coins and networks
3. Determines which coins are supported (defined in config) vs available (database reachable)
4. Starts a 60-second sync interval to refresh configuration

If the hub is unreachable, the explorer falls back to src/config.json or the NODE_CONFIG environment variable.

Config Change Events

The config module provides an event system for live updates:

const config = require('./config.js');
config.onConfigChanged(() => {
    // React to configuration changes (e.g., new coins available)
});

Coin-Specific Configuration

Each supported blockchain has a configuration file in src/configs/:

These files export a getConfig(network) function returning:

{
    chain: {
        name: "Bitcoin",
        tick: "BTC",
        site: "https://bitcoin.org"
    },
    address: {
        burn:      "...",   // Token burn address
        gas:       "...",   // XCHAIN gas token issuer
        protocol:  "...",   // Protocol development fund
        community: "...",   // Community development fund
        explorer:  "..."    // Explorer service address
    }
}

Addresses vary per network (mainnet, testnet, regtest).

Supported Coins and Prefixes

The config module builds a mapping of supported coins from the configuration:

These prefixes form the first segment of all API URLs (e.g., /BTC/api/token/MYTOKEN).

Rate Limiting

The explorer uses express-rate-limit middleware:

Rate limiting applies to all non-image endpoints (API, Explorer, and HTML).

CORS

Cross-Origin Resource Sharing is configured via the cors middleware. Allowed origins can be specified in the configuration. When not explicitly configured, CORS defaults to allowing all origins.

Security Headers

The explorer uses Helmet middleware to set security headers including:

• Content Security Policy (CSP)
• X-Content-Type-Options: nosniff
• X-Frame-Options
• Strict-Transport-Security (when HTTPS is active)
• X-XSS-Protection

Finality / Confirmation Depths

The explorer uses per-chain confirmation depths to determine when a receipt is considered final. These values are surfaced in the finality field of the /api/network response and mirror the hub’s cross-chain thresholds. They can be overridden per chain:

Database

The explorer reads from MariaDB databases following the naming convention:

XChain_{CHAIN}_{NETWORK}_Indexer    (primary: indexed state)
XChain_{CHAIN}_{NETWORK}_Decoder    (secondary: raw transaction data)

Connection pooling is managed by the mariadb npm package. The explorer maintains separate pool connections for Indexer and Decoder databases.

All queries use parameterized SQL (? placeholders) to prevent SQL injection. No ORM is used.

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.