XChain Platform Hub: Architecture

Position in the Data Pipeline

flowchart TD
    NODE["Coin Node<br>(bitcoind / litecoind / dogecoind)"]
    DECODER["xchain-decoder"]
    DECDB[("Decoder DB (MariaDB)")]
    INDEXER["xchain-indexer"]
    IDXDB[("Indexer DB (MariaDB)")]
    EXPLORER["xchain-explorer"]
    SYNC["xchain-sync"]
    REPLICAS["Validator replicas"]
    HUB["xchain-hub<br>- Config oracle (all services poll)<br>- Price oracle (CoinGecko, Kraken, CoinMarketCap)<br>- Cross-chain attestation<br>- SWAP lifecycle tracking<br>- Reorg propagation<br>- Governance"]
    P2P["P2P Validator Network"]

    NODE -->|JSON-RPC| DECODER
    DECODER --> DECDB
    DECDB --> INDEXER
    INDEXER --> IDXDB
    IDXDB --> EXPLORER
    IDXDB --> SYNC
    SYNC --> REPLICAS
    HUB --> SYNC
    HUB <--> P2P

The hub sits at the center of the platform. All other services depend on it for configuration discovery. In validator mode, it also serves as the decentralized coordination layer for pricing, cross-chain operations, and governance.

Operating Modes

flowchart LR
    subgraph STANDALONE["STANDALONE MODE<br>(P2P_VALIDATOR_ADDR not set)"]
        direction TB
        SA_API["api.js<br>Express + JSON-RPC"]
        SA_HUB["XChainHub<br>(orchestrator)"]
        SA_DB["db.js<br>MariaDB pool + circuit breaker"]
        SA_NOTE["Config writes go directly to MariaDB.<br>No P2P, no consensus."]
        SA_API --> SA_HUB --> SA_DB
        SA_DB -.-> SA_NOTE
    end

    subgraph VALIDATOR["VALIDATOR MODE<br>(P2P_VALIDATOR_ADDR set)"]
        direction TB
        VA_API["api.js<br>Express + JSON-RPC"]
        VA_HUB["XChainHub<br>(orchestrator)"]
        VA_PEER["PeerManager<br>P2P gossip layer"]
        VA_CONS["Consensus"]
        VA_ORACLE["OracleRound"]
        VA_CROSS["CrossChainEngine"]
        VA_REORG["ReorgHandler"]
        VA_GOV["Governance"]
        VA_REWARD["RewardTracker"]
        VA_SLASH["SlashDetector"]
        VA_SWAP["SwapTracker"]
        VA_DB["db.js<br>MariaDB pool + circuit breaker"]

        VA_API --> VA_HUB --> VA_PEER
        VA_PEER --> VA_CONS --> VA_GOV
        VA_PEER --> VA_ORACLE --> VA_REWARD
        VA_PEER --> VA_CROSS --> VA_SLASH
        VA_PEER --> VA_REORG --> VA_SWAP
        VA_GOV --> VA_DB
        VA_REWARD --> VA_DB
        VA_SLASH --> VA_DB
        VA_SWAP --> VA_DB
    end

In standalone mode, the hub is a simple config oracle. In validator mode, the XChainHub orchestrator wires together all subsystems via event-driven architecture.

Internal Components

Event-Driven Wiring

Subsystems communicate via Node.js EventEmitter events rather than direct method calls:

flowchart TD
    ORACLECONS["OracleConsensus"]
    REWARD["RewardTracker"]
    SLASH["SlashDetector"]
    ORACLEPUB["OraclePublisher<br>(queues for DOGE broadcast)"]
    PRICEAGG["PriceAggregator"]
    CHECKPOINT["StateCheckpointEngine"]
    DEXENGINE["CrossChainDexEngine"]
    CALLENGINE["CrossChainCallEngine"]
    BROADCASTER["HubDbBroadcaster<br>(forwards to WebSocket subscribers)"]
    ANCHORPUB["StateAnchorPublisher<br>(queues for DOGE ANCHOR broadcast)"]
    CROSSCHAIN["CrossChainEngine"]
    SWAP["SwapTracker"]
    REORG["ReorgHandler"]
    DOWNSTREAM["downstream indexer notification"]
    GOV["Governance"]
    PARAMAPPLY["parameter application"]

    ORACLECONS -->|round:finalized| REWARD
    ORACLECONS -->|round:finalized| SLASH
    ORACLECONS -->|round:finalized| ORACLEPUB
    PRICEAGG -->|row:inserted| BROADCASTER
    CHECKPOINT -->|row:inserted| BROADCASTER
    DEXENGINE -->|row:inserted| BROADCASTER
    CALLENGINE -->|row:inserted| BROADCASTER
    CHECKPOINT -->|checkpoint:finalized| ANCHORPUB
    CROSSCHAIN -->|attestation:finalized| SWAP
    REORG -->|reorg:confirmed| DOWNSTREAM
    GOV -->|proposal:passed| PARAMAPPLY

Source Files

P2P Gossip Layer

The PeerManager provides the transport layer for all consensus protocols.

flowchart LR
    subgraph A["Validator A"]
        direction TB
        PMA["PeerManager"]
        SUBA["Consensus<br>Oracle<br>CrossChain<br>Governance"]
        PMA -->|message events| SUBA
        SUBA -->|message events| PMA
    end

    subgraph B["Validator B"]
        direction TB
        PMB["PeerManager"]
        SUBB["Consensus<br>Oracle<br>CrossChain<br>Governance"]
        PMB -->|message events| SUBB
        SUBB -->|message events| PMB
    end

    PMA -->|WebSocket outbound| PMB
    PMB -->|WebSocket inbound| PMA

Message Flow

1. Subsystem calls peerManager.broadcast(type, data) (or sendToPeer(addr, type, data) for a directed message).
2. PeerManager wraps data in an envelope, assigns a unique ID, signs with Ed25519 (if identity configured), and adds to seenIds dedup cache.
3. Message sent to all connected peers.
4. Receiving PeerManager checks seenIds, drops duplicates.
5. Verifies Ed25519 signature against registered validator pubkeys (if REQUIRE_SIGNATURES=true).
6. Emits message event; relays to other peers (flood-fill gossip).

Connection Management

• Outbound connections to SEED_NODES with exponential backoff (2s base, 60s max).
• Inbound connections on P2P_PORT (default 10001).
• Deduplicates bidirectional connections (if both A→B and B→A connect, one is dropped).
• Heartbeat broadcasts every 15 seconds (includes hub software version for upgrade coordination).
• WS ping/pong every 30 seconds to detect dead connections.
• Peer records persisted to p2p_peers table.

Envelope Wire Format

Every message on the gossip layer (regardless of which subsystem produced it) is a single JSON object with the same envelope shape. The subsystem-specific payload lives entirely inside data; everything else is transport metadata.

{
  "type":      "CAPABILITY_ACTIVATED",
  "id":        "v1:<sender-addr>:1743690000000:550e8400-e29b-41d4-a716-446655440000",
  "sender":    "<originating-validator-addr>",
  "timestamp": 1743690000000,
  "data":      { },
  "sig":       "<128-hex-char Ed25519 signature>"
}

Signature canonicalization. The signature covers a deterministic JSON serialization of exactly five fields, in this fixed key order (id, type, sender, timestamp, data) with sig itself excluded:

JSON.stringify({ id, type, sender, timestamp, data })

A verifier must reconstruct this exact string to check the signature. The signing key is the sender’s Ed25519 validator key; the verifier looks up sender in the validator registry to obtain the 64-hex-char public key. When REQUIRE_SIGNATURES=true, unsigned messages and messages from unknown senders are rejected; otherwise they are accepted (bootstrap mode).

Inbound processing order (in _handleInbound): JSON parse → reject non-object/array values → validate type/id/sender/timestamp → self-connection guard (drop messages whose sender is this node) → dedup against seenIds → per-peer rate limit → signature verification → emit message (and type-specific events) → relay to all peers except the source connection and the original sender.

Message Types

All types below ride the envelope above; only the data payload differs. Every node emits a generic message event for any valid inbound envelope; some types additionally emit a typed event.

Liveness:

Capability gossip (advertises which staking-backed capabilities a validator is running; emits a capability event). The receiver additionally requires that data.pubkey match the sender’s registered validator pubkey; a validator cannot advertise capabilities on behalf of another pubkey.

Consensus and coordination (carried over the same gossip layer; payloads are defined by their respective engines):

Unrecognized types are still deduplicated, signature-checked, and relayed (so the gossip mesh forwards message types a given node may not handle), but produce no local side effect beyond the generic message event.

PBFT Consensus

The consensus engine implements simplified PBFT for config writes:

sequenceDiagram
    participant L as Leader
    participant V as Validators (2f+1 required)
    L->>V: PRE_PREPARE
    Note right of V: Leader proposes config write
    V-->>L: PREPARE
    Note left of L: Validators acknowledge (collect 2f+1)
    L->>V: COMMIT
    Note right of V: Leader broadcasts commit
    V-->>L: COMMIT
    Note left of L: Validators confirm (collect 2f+1)
    Note over L,V: Apply config to MariaDB

Leader Selection

Leader for sequence N = validatorSet[(N + view) % validatorCount], where validators are sorted by pubkey.

View Change

If the leader fails to drive consensus within PBFT_TIMEOUT (default 30s):

1. Validators broadcast PBFT_VIEW_CHANGE for view + 1.
2. Once 2f+1 view-change votes are collected, the new view is adopted.
3. The next leader (per the new view number) takes over.

Quorum

max(2f+1, ceil((N+1)/2)) where f = floor((N-1)/3), tolerates f Byzantine validators out of N total. The simple-majority floor matters for small federations: bare 2f+1 degenerates to a quorum of 1 at N=3 (f=0), which would let a single validator finalize alone. With the floor, N=3 requires 2 votes and N=2 requires both.

Oracle Pipeline

flowchart TD
    subgraph ROUND["Every ORACLE_ROUND_INTERVAL (default 10 min)"]
        S1["1. CHAIN TIP<br>OracleRound reads BTC chain tip from configs table<br>→ currentBtcBlockHeight, currentBtcBlockTime"]
        S2["2. FETCH<br>PriceFetcher queries CoinGecko + Kraken (keyless) + CoinMarketCap (if key set)<br>→ 3 coins x 12 fiats = 36 pairs per source<br>→ compute local median across sources"]
        S3["3. SUBMIT<br>Broadcast ORACLE_PRICE_SUBMIT via gossip<br>→ stored in oracle_submissions table"]
        S4["4. COLLECT<br>Wait ORACLE_SUBMISSION_WINDOW (default 3 min)<br>→ accumulate other validators' submissions"]
        S5["5. AGGREGATE<br>Round leader computes trimmed median:<br>→ sort submissions, discard top/bottom 15%<br>→ median of remaining values"]
        S6["6. SIGN<br>Each validator signs the canonical PRICE v0 payload<br>→ JSON.stringify({round, timestamp, sortedPairs})<br>→ Ed25519 via ValidatorIdentity"]
        S7["7. PROPOSE<br>Leader broadcasts ORACLE_PROPOSE (with sig)"]
        S8["8. PREPARE<br>Validators verify and send ORACLE_PREPARE (with their sig)<br>→ sigs stored on pending.signatures Map<br>→ collect 2f+1 prepares"]
        S9["9. COMMIT<br>Leader broadcasts ORACLE_COMMIT (with sig)<br>→ collect 2f+1 commits"]
        S10["10. FINALIZE<br>Store in price_snapshots (status='finalized')<br>→ reference_block = btcBlockHeight (not 0)<br>→ emit round:finalized event with collected sigs<br>→ RewardTracker distributes XCHAIN (pushes to BTC indexer)<br>→ SlashDetector checks for misbehavior<br>→ OraclePublisher queues for DOGE broadcast (if leader)"]

        S1 --> S2 --> S3 --> S4 --> S5 --> S6 --> S7 --> S8 --> S9 --> S10
    end

oracle_publish Capability Publishing Pipeline

After consensus finalizes a round, the OraclePublisher takes over:

flowchart TD
    S1["1. ROTATION<br>Leader = SHA256(round_number || pubkey) ordering<br>oracle_publish validators sorted deterministically"]
    S2["2. ENQUEUE<br>If local node is the leader, append to JSONL queue (fsync)"]
    S3["3. BROADCAST<br>EncoderClient.getUtxos(DOGE_ADDRESS)<br>→ EncoderClient.createTx(payload, P2SH encoding)<br>→ walletSignFn(psbtHex) [operator-provided signer]<br>→ EncoderClient.broadcastTx(signedHex)"]
    S4["4. CONFIRM<br>Remove from queue on successful broadcast"]
    S5["5. FAILOVER<br>If leader misses by 1 BTC block, next oracle_publish validator in rotation takes over and batches all missed rounds in a single tx"]

    S1 --> S2 --> S3 --> S4 --> S5

Price Sources

Supported fiat currencies: USD, CAD, AUD, MXN, GBP, JPY, CNY, CHF, BRL, INR, EUR, KRW.

CoinGecko and Kraken are both keyless, so every hub has two uncorrelated upstreams out of the box. CoinMarketCap is added as a third source only when COINMARKETCAP_API_KEY is configured. The local price for each pair is the median of values from all available sources.

Hub DB Sync Channel

For geographically distributed deployments, the hub broadcasts row inserts to indexers’ local hub DB copies via a WebSocket channel separate from the per-chain sync.

flowchart LR
    subgraph HUB["Hub"]
        direction TB
        PA["PriceAggregator<br>receiveValidatedRound/OraclePrice"]
        EMIT["emit row:inserted"]
        HDB["HubDbBroadcaster<br>WebSocket subs"]
        PA --> EMIT --> HDB
    end

    subgraph IDX["Indexer (HubDbSync client)"]
        direction TB
        XI["XChainIndexer<br>- hubDb (local)<br>- HubDbSync"]
        APPLY["Apply row to local hub DB<br>via INSERT IGNORE"]
        XI --> APPLY
    end

    HDB -->|ws send| XI

REST Bootstrap Endpoints

WebSocket Channel

Indexers bootstrap by fetching the REST snapshots (paginated by since_id) then subscribe to the WebSocket for live updates. Failed sends apply backpressure handling, connections exceeding WS_BACKPRESSURE_LIMIT buffered messages are dropped.

Trimmed Median

Given N validator submissions for a coin pair:

1. Sort all submissions by price.
2. Discard the top 15% and bottom 15%.
3. Compute the median of the remaining values.

This resists manipulation: an attacker would need to control >30% of validators to significantly shift the price.

Cross-Chain Attestation

flowchart TD
    S1["1. REQUEST<br>requestattestation(source_chain, source_action_index, dest_chain)"]
    S2["2. PROPOSE<br>Leader broadcasts XCHAIN_ATTEST_PROPOSE<br>→ includes attestation_id: '{source_chain}:{action_index}:{dest_chain}'"]
    S3["3. PREPARE<br>Validators send XCHAIN_ATTEST_PREPARE<br>→ only validators supporting BOTH chains participate<br>→ collect 2f+1 from eligible validator subset"]
    S4["4. COMMIT<br>Leader broadcasts XCHAIN_ATTEST_COMMIT<br>→ collect 2f+1 commits"]
    S5["5. FINALIZE<br>Store in attestations table (status='attested')<br>→ emit attestation:finalized event<br>→ SwapTracker auto-progresses matching swaps"]

    S1 --> S2 --> S3 --> S4 --> S5

Confirmation Thresholds

Higher on the lower-hashpower chains to approach Bitcoin-comparable settlement assurance. Per-chain, configurable via XCHAIN_CONFIRMATIONS_<COIN>.

Supported Chain Pairs

BTC-LTC, BTC-DOGE, LTC-DOGE.

Per-Chain-Pair Validators

Validators declare which chains they support via the chains column. Only validators supporting both chains in a pair participate in attestation consensus. Validators with NULL chains support all chain-pairs (backward compatible).

Reorg Handling

flowchart TD
    S1["1. REPORT<br>reportreorg(chain, reorg_height, timestamp, old_hash, new_hash)<br>→ old_hash/new_hash = the reporter's observed block hash at reorg_height before and after the reorg<br>→ receiving hub verifies new_hash against its OWN indexer (getblockhashes) before broadcasting"]
    S2["2. ALERT<br>Broadcast REORG_ALERT via gossip (carries the hash pair)"]
    S3["3. CONSENSUS<br>PBFT round: XCHAIN_REORG_PREPARE / XCHAIN_REORG_COMMIT<br>→ the digest binds reorgId, chain, height, timestamp AND the hash pair, so a Byzantine leader cannot swap hashes per-follower<br>→ each hub co-signs ONLY after its own indexer serves new_hash at reorg_height, within height bounds (&le; own tip, &ge; tip - REORG_MAX_DEPTH) and on the federation network; otherwise it abstains<br>→ 2f+1 agreement = 2f+1 independent observations"]
    S4["4. ROLLBACK<br>Hub state cleanup:<br>→ DELETE attestations after reorg timestamp for affected chain<br>→ Mark price_snapshots as 'disputed'"]
    S5["5. NOTIFY<br>Store in reorg_attestations table<br>→ emit reorg:confirmed event"]

    S1 --> S2 --> S3 --> S4 --> S5

Governance

flowchart TD
    S1["1. PROPOSE<br>propose(parameter, current_value, proposed_value, rationale)<br>→ only active validators can propose<br>→ stored in governance_proposals (status='voting')"]
    S2["2. GOSSIP<br>Broadcast GOV_PROPOSE via P2P"]
    S3["3. VOTE<br>vote(proposal_id, vote) [approve/reject]<br>→ stored in governance_votes<br>→ broadcast GOV_VOTE via P2P"]
    S4["4. TALLY<br>Automatic tally every 60 seconds:<br>→ check if voting period (7 days) has ended<br>→ quorum: 50% minimum participation<br>→ approval: 2/3+ of validator set<br>→ broadcast GOV_RESULT via P2P"]
    S5["5. APPLY<br>If passed: emit proposal:passed event<br>→ downstream parameter application"]

    S1 --> S2 --> S3 --> S4 --> S5

Constraints

Reward and Slash System

Rewards

On each finalized oracle round, ORACLE_REWARD_PER_ROUND (default “10.00000000”) XCHAIN is distributed equally among validators who submitted a price in that round. Rewards are recorded in the validator_rewards table with claimed=0 and are collectable via a COLLECT action on the BTC chain (handled by the indexer, not the hub).

Slash Detection

Three offense types are monitored:

Detection is recorded in the slash_proposals table. Actual stake slashing is executed by the indexer, not the hub.

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.