Hub Decentralization
Overview
xchain-hub has evolved from a centralized config oracle into a fully decentralized validator network across nine implementation phases. Phases 0–5 shipped v1.0.0 → v2.0.0; Phase 6 (capability model + external attestation framework, 2026-05), Phase 7 (federation key rotation + quorum hardening, 2026-06), and Phase 8 (full-node verified tier: full_node capability, FullNodeChallengeRound, NODEPROOF verdicts, 2026-06) are all complete.
Motivation
Single point of failure
A centralized hub means the entire platform degrades when the hub process crashes or its database becomes unavailable. Services that cannot reach the hub fall back to stale local config or fail their startup checks. Cross-chain swaps stall until the hub recovers.
Single point of trust
A centralized hub operator controls configuration for all services. In a self-hosted deployment this is acceptable, but it creates a trust assumption that is difficult to remove as the platform grows. A malicious or misconfigured hub could redirect services to wrong endpoints or manipulate pricing data.
Scalability ceiling
A single-instance hub has limited horizontal scaling options. Under high coordination load (many concurrent cross-chain swaps), the hub becomes a bottleneck.
Capability Model
The validator network uses a capability model rather than fixed tiers. A validator stakes XCHAIN against an Ed25519 signing pubkey; that pubkey’s aggregate active stake auto-qualifies it for each of five independent capabilities whose min_stake it meets:
| Capability | Role | Default consumers |
|---|---|---|
price |
Fetch external prices and sign PBFT-finalized PRICE v0 rounds | PRICE v0 producers; OracleRound, OracleConsensus |
cross_chain |
Attest to cross-chain swap actions per chain-pair | CrossChainEngine |
oracle_publish |
Broadcast finalized PRICE v0 rounds on-chain (typically DOGE for low fees) | PRICE v0 publisher, formerly “Tier 3” |
attestation |
Fetch external attestation requests via registered providers (http_get, llm) and PBFT-finalize the response |
AttestationRound, AttestationConsensus |
full_node |
Pass the chain-derived possession challenges run by FullNodeChallengeRound (answer: the scriptPubKey of a seed-selected output in a buried block); passing qualifies a validator for the full-node reward tier, which ships inert and is not minted today |
FullNodeChallengeRound |
A single pubkey can hold any combination of capabilities, there is no overlap restriction. min_stake[capability] is governance-configurable; defaults are set by hub config. The historical model where the cross-chain tier required 5× the oracle stake is preserved by appropriate min_stake defaults but the protocol does not enforce a hierarchy.
price: Price Oracles
Validators with the price capability independently fetch cryptocurrency prices from multiple external sources (CoinGecko, Kraken and Coinbase are all keyless and always active; CoinMarketCap is optional when an API key is configured), submit them to the network, and reach consensus using a trimmed median algorithm (discard top/bottom 15%). This replaces centralized pricing with a manipulation-resistant oracle feed. Price rounds run on a configurable interval (default 10 minutes). Each round goes through: fetch → submit → collect → aggregate → PBFT finalize.
cross_chain: Cross-Chain Validators
Validators with the cross_chain capability attest to cross-chain swap actions. Matching reads each chain’s indexer, so a validator need not run full decoder and indexer stacks for every chain and can use xchain-sync to replicate the indexer + decoder databases. It still needs a coin node: the hub’s cross_chain self-test requires an rpc entry, the chain’s coin-node RPC, for every chain configured under cross_chain.chains (for BTC, cross_chain.chains.BTC.rpc; see Capability Configuration). A validator running only a sync replica lists cross_chain under DISABLED_CAPABILITIES (see Running a validator). Consensus is calculated per chain-pair; only validators supporting both chains in a swap participate in attestation, using a PBFT-derived consensus requiring quorum agreement over that pair’s validator set (stake-weighted and source-deduped at/above STAKE_WEIGHTED_QUORUM_ACTIVATION, otherwise the majority-floored count; see Quorum below).
oracle_publish: PRICE v0 Broadcasters
After a price round PBFT-finalizes, a validator with oracle_publish broadcasts the signed round on-chain (typically to DOGE for low tx fees). Leader rotation among oracle_publish-capable validators is deterministic via SHA256(round_number || pubkey) ordering with cascading failover at each subsequent block.
attestation: External Attestation Framework
Validators with attestation serve ATTEST v0 (request) actions emitted by VM contracts via xchain.attestation.request(...). Responsible-set selection is deterministic via SHA256(request_id || pubkey) ordering; the top redundancy validators fetch from the named provider (http_get or llm) and reach PBFT consensus on the response. Two consensus strategies are supported: byte_equality (all responses must be identical, used by http_get) and judge_model (an LLM judges semantic equivalence, used by llm). The signed bundle is submitted on-chain as ATTEST v1 (response), which fires the requesting contract’s callback EXECUTE.
Block-boundary snapshots
Every PBFT engine (config, oracle, attestation, cross-chain) locks its quorum at a specific block_index via CapabilitySnapshot.getSnapshot(capability, block_index). This queries the indexer’s getcapabilityvalidators RPC (60s cache) so every hub in the federation sees the same qualified set even as stake drifts mid-round. Self-tests are local to each hub; a failed self-test means the validator skips the round but is still counted in N. Nothing on-chain penalises a laggard: SLASH burns on equivocation proofs only, and the hub-local suspension lane is not a stake effect. Where ROLLCALL is active, a source absent for K consecutive rolled epochs is evicted from the capability set by deactivation, so N shrinks the way it does for any UNSTAKE.
Staking and Governance
All staking operations (STAKE, UNSTAKE, DELEGATE, COLLECT) are standard XChain actions on the BTC chain, processed by the indexer. STAKE comes in two semantic versions (VERSION=1 new stake, VERSION=2 top-up of an existing pubkey); both wire to VERSION|AMOUNT|SIGNING_PUBKEY. Active stake for a pubkey is SUM(amount) across rows where activation_block ≤ now < COALESCE(deactivation_block, +∞).
| Property | Value |
|---|---|
| Slashing (on-chain) | Stake is burned only on a permissionless SLASH proof of equivocation: two conflicting signatures over the same engine, round and view. Verified deterministically on every BTC indexer, no governance vote. |
| Suspension (hub-local) | Price deviation >5%, repeated deviations (3+ in 24h), non-participation (30+ missed rounds), attestation divergence on byte_equality providers. Adjudicated via governance vote; sets validators.status='suspended' and excludes the validator from PBFT rounds. On-chain stake is untouched, and no quorum read consults this status. |
| Eviction (on-chain, where ROLLCALL is active) | A source absent for K consecutive rolled epochs is deactivated, leaving the capability set through the ordinary stake predicate. Its stake refunds after the cooldown; nothing is burned. |
| Activation delay | 6 BTC blocks (~1 hour): protects against ≤5-block reorgs |
| Deactivation delay | 6 BTC blocks on UNSTAKE (same reorg safety) |
| Cooldown | 1000 BTC blocks before staked XCHAIN returns to source (configurable via STAKING.COOLDOWN_BLOCKS) |
| Delegation | DELEGATE manages signing keys, never stake: v0 adds a signing key that may sign for the broadcaster’s own capability stake and v2 revokes one (contract stakes use v1 / v3). A delegated key is backed by the delegating address’s active stake; staked amounts never move or change, and there is no third-party stake delegation. See DELEGATE. |
| Rewards | Not weighted by stake: stake decides which capabilities a pubkey qualifies for, not the size of its share. The per-round oracle budget is designed to split equally across the qualified signers of each finalized round, but no consensus rail mints an oracle round reward today, so none is claimable with COLLECT; the hub keeps a local per-round ledger for visibility only (see COLLECT reward sources and Reward Population Path). A pubkey may hold both price and oracle_publish; the claimable rewards tied to oracle_publish are the ANCHOR publisher rewards (anchor_bundle). |
Note: Capability staking above is BTC-only, so the activation/deactivation delays are stated in BTC blocks (~1 hour). Contract-targeted staking (STAKE v3 / UNSTAKE v1 / DELEGATE v1/v3) runs on every chain and calibrates this delay per chain for equivalent ~60-min reorg protection (6 blocks on BTC, 24 on LTC, 60 on DOGE) since a flat 6 blocks would give DOGE only ~6 minutes. See
protocol/Contract_Staking.md.
Decentralized Roles
| Hub Role | Decentralized Mechanism |
|---|---|
| Configuration | PBFT consensus for config writes across validator set; quorum locked at block boundary via CapabilitySnapshot |
| Service discovery | Hub config store, polled by all platform services |
| Price data | price-capable validators with trimmed median consensus; published on-chain by oracle_publish-capable validators |
| Cross-chain coordination | cross_chain-capable validator attestation with per-chain-pair PBFT |
| External attestation | attestation-capable validators fetch from registered providers (http_get, llm) and PBFT-finalize; result submitted on-chain as ATTEST v1 (response) |
| Full-node verification | full_node-capable validators answer chain-derived possession challenges (the scriptPubKey of a seed-selected output in a buried block) run by FullNodeChallengeRound; passing validators get a NODEPROOF verdict, and the full-node reward tranche it qualifies them for ships inert and is not minted today (see Rewards, and what is not live yet) |
| Governance | Off-chain PBFT voting with 7-day period, 2/3+ approval |
Transport auth follows on-chain key rotation
A validator’s P2P signing key is authorized by the union of the hub’s local validator registry and the on-chain effective signer set (polled from getactivevalidators at the BTC tip every 30 s, never fail-open). So when a validator rotates its signing key on-chain via DELEGATE, every peer’s transport auth follows automatically within one poll interval. No hand-edited registry on each hub. The operator procedure is in Operations → Validator Key Rotation.
Implementation Phases
| Phase | Name | Version | Status |
|---|---|---|---|
| 0 | MariaDB migration; Replace LevelDB with MariaDB | v1.0.0 | Complete |
| 1 | Multi-instance hub; Run multiple instances against shared MariaDB; consumer fallback via HUB_VALIDATORS |
v1.0.0 | Complete |
| 2 | Gossip + PBFT consensus; P2P gossip layer (WebSocket), PBFT consensus for config writes, Ed25519 validator identity, leader rotation, view change | v1.1.0–v1.3.0 | Complete |
| 3 | Decentralized price oracle; External price fetching, trimmed median aggregation, oracle PBFT consensus, price snapshots, reward tracking, slash detection, fee quotes | v1.4.0–v1.6.0 | Complete |
| 4 | Cross-chain coordination; Attestation engine, reorg propagation, SWAP lifecycle tracking, per-chain-pair validator filtering | v1.7.0–v1.9.0 | Complete |
| 5 | Open validator set + governance; Off-chain PBFT voting for parameter changes, version signaling in heartbeats | v2.0.0 | Complete |
| 6 | Capability model + external attestation framework; Replace Tier 1/2 with four independent capabilities (price, cross_chain, oracle_publish, attestation) auto-qualified by stake amount; block-boundary federation snapshots; external attestation framework (http_get byte_equality + llm judge_model providers); STAKE rewritten as `VERSION |
AMOUNT | SIGNING_PUBKEY` with v1=new / v2=top-up; UNSTAKE rewritten as pubkey-based |
| 7 | Federation key rotation + quorum hardening: addr-keyed rotatevalidator/deregistervalidator RPC; stake-key revocation via DELEGATE v2; Option A union-membership transport auth (on-chain effective signer set + local registry, never fail-open); anchor reward archive (shipped as the anchor_<chain> reward_type, since superseded by anchor_bundle, see COLLECT) + hub-local oracle/attest_fee reward separation; simple-majority quorum floor (max(2f+1, ceil((N+1)/2))) across all consensus engines |
2026-06 | Complete |
| 8 | Full-node verified tier: full_node capability and FullNodeChallengeRound; derived possession challenge (no broadcast of the question); answer = scriptPubKey of a seed-selected UTXO in a buried block, provably absent from a sync mirror; verdict collected as NODEPROOF; full-node reward tranche (oracle_full_node) defined but shipped inert (FULLNODE.REWARD_SHARE 0, no genesis verifiers), so no consensus rail mints it (see COLLECT); failed_full_node_challenge slash detection (later removed; tier is reward-only, no slashing) |
2026-06 (bcbe4b8) | Complete |
Architecture Summary
flowchart TD
EXT["External APIs<br>(CoinGecko, Kraken, Coinbase, CMC)"]
A["Validator A<br>PriceFetcher → OracleRound<br>PeerManager ↔ Consensus<br>CrossChainEngine<br>ReorgHandler<br>Governance<br>RewardTracker<br>SlashDetector"]
B["Validator B<br>(same stack)"]
C["Validator C<br>(same stack)"]
EXT --> A
A -->|gossip| B
B -->|gossip| C
Each validator runs the full hub stack. Communication happens via WebSocket-based P2P gossip with Ed25519-signed messages. All consensus decisions require quorum agreement, and which quorum rule applies is activation-gated (below).
Quorum
The rule is keyed on the round’s BTC-anchored snapshot block and network, so every hub and every indexer flips on the same anchor.
At or above STAKE_WEIGHTED_QUORUM_ACTIVATION: stake-weighted and source-deduplicated. Each voting validator’s pubkey resolves to its stake source in the federation snapshot, each source counts at most once however many of its keys vote, and the summed stake must satisfy 3 x tally > 2 x S, where S is the snapshot’s total stake over distinct sources. Three equally weighted sources therefore need all three votes. See protocol/reference-impl/consensus/stake_weighted_quorum.js.
Below activation: the legacy signer count max(2f+1, ceil((N+1)/2)) where f = floor((N-1)/3), tolerating 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.
Related
- Hub: hub architecture and API reference
- Architecture: internal subsystem design
- Cross-Chain Concepts: how cross-chain swaps work at the protocol level
- Gas Token: the XCHAIN token used for staking and fees
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.