Validator Guide

Validators secure Allways by cranking the reservation draw, independently verifying both legs of every swap on-chain, and voting the outcomes. They also run the bond relay that carries TAO-backed collateral state between chains, and they score miners and set weights on Bittensor.

• Crank the stake-weighted reservation draw (resolve_pool)
• Verify source and destination transactions on every supported chain independently
• Vote to initiate, confirm, or time out swaps via the Solana program
• Relay TAO bonds: mirror locked vault bonds to Solana, carry timeout verdicts to the vault, unlock drained bonds — each by quorum
• Score miners and set weights on the Bittensor network

REQUIREMENTS

Docker · 2 CPUs · 4 GB RAM · a Bittensor wallet (coldkey + hotkey, with validator permit stake) · a funded Solana keypair (signs every on-chain vote) · a paid Solana RPC endpoint · a keyed Ethereum RPC endpoint (Dwellir recommended) · a reliable Bittensor (finney) endpoint — ideally your own lite node.

TIP

A validator must stay online continuously — one that isn't cranking and voting isn't earning and isn't securing anything.

The two keys a validator loads

A validator signs on two chains:

Key	Chain	What it signs
Bittensor coldkey + hotkey	Bittensor	Registration + validator permit; the hotkey sets weights and signs the dendrite transport
Solana keypair	Solana	Every on-chain vote — resolve_pool, vote_initiate, confirm_swap, timeout_swap, and (when routing a taker) finalize_reservation

The Solana keypair is the one that must be whitelisted on the contract (see Step 4) — that's what carries your stake weight into the draw and lets your votes count.

KEEP BOTH KEYS FUNDED

The hotkey pays Bittensor extrinsic fees (weights). The Solana keypair pays a fee on every vote and crank. Either running dry silently stops you participating — keep a buffer on both.

Step 1: Install and register

Follow Getting Started to install the CLI and configure your wallet. Register a hotkey on Subnet 7 (netuid 19 on testnet; a validator permit needs sufficient stake):

btcli subnet register --netuid 7 --wallet.name <coldkey> --wallet.hotkey <hotkey>

Step 2: Set up your Solana keypair

Validators sign every on-chain vote with a Solana keypair — no private key is needed for reading chains, but voting is a Solana transaction:

solana-keygen new -o ./data/solana/id.json

Mounted into the container at /root/.solana/id.json (override with SOLANA_KEYPAIR_PATH). Fund it with SOL for vote fees, and give this pubkey to the contract owner for whitelisting. Point at a paid Solana RPC (Helius, Triton, QuickNode, …) — the public endpoints will not sustain validator load.

Get a Helius API key (paid tier)

A validator scans the whole program and reads every swap leg on each ~12s pass, which runs past the free tier — budget for at least Helius's Developer plan ($49/mo, 10M credits); sustained or heavy swap volume can need Business ($499/mo, 100M credits). To set one up:

1. Sign up at helius.dev and subscribe to Developer (or higher).
2. Copy your API key from the dashboard.
3. Set both in .env — the key is composed onto the URL as the api-key param:

SOLANA_RPC_URL=https://mainnet.helius-rpc.com   # devnet.helius-rpc.com on testnet
SOLANA_RPC_API_KEY=YOUR_KEY

Get the cluster right: the neuron classifies the endpoint by genesis hash at boot and a testnet validator pointed at a mainnet Solana RPC refuses to start (as does a program-id↔cluster mismatch) — a wrong URL fails loudly instead of silently validating against the wrong cluster.

TIP

Track usage on the Helius dashboard. The Developer plan's 10M credits/month (~333k/day) covers average load with headroom, but many concurrent in-flight swaps can spike it — move up to Business if you're regularly near the cap.

RUN YOUR OWN FINNEY NODE

Your Bittensor endpoint matters as much as your Solana one. A lagging public finney RPC can make you unable to see a TAO leg that actually landed — and a validator that votes timeout on a delivered swap slashes an honest miner. It's also the endpoint the bond relay reads the vault through and writes its quorum votes to. Point the validator at your own finney lite node (or another endpoint you trust to stay current) rather than the public entrypoint.

Step 3: Configure UTXO-family chains (BTC)

Every UTXO-family spoke follows one pattern, keyed by the chain's env prefix (BTC_* for Bitcoin). Validators only read and verify transactions — no private key is needed. Verification runs over Esplora HTTP APIs; choose your source:

Option A: Public Esplora (quick start / testing)

Public APIs (Blockstream primary, Mempool.space fallback). Fine while bootstrapping or on testnet, not recommended for a whitelisted validator (see the warning):

BTC_NETWORK=mainnet          # or testnet4 on testnet

Option B: Paid / private Esplora

Point at a paid/keyed Esplora endpoint (or your own self-hosted Esplora). BTC_ESPLORA_URLS is an ordered, comma-separated list of URL or URL|API_KEY (first is primary, the rest are fallbacks):

BTC_NETWORK=mainnet
BTC_ESPLORA_API_KEY_HEADER=api-key
BTC_ESPLORA_URLS=https://xbt-mainnet.gomaestro-api.org/v0/esplora|YOUR_MAESTRO_KEY,https://mempool.space/api

VERIFICATION ACCESS IS CRITICAL

Free public APIs rate-limit and have no SLA. That's harmless while bootstrapping, but once you're whitelisted and voting on real swaps, an outage means you can't verify — and a validator that can't verify can't vote. Worse, deferred confirmation relies on validators watching a slow source leg; if you can't read the chain you may miss the extension window and let an honest swap time out. Use a paid/keyed Esplora endpoint (Option B) before you start participating.

Step 3b: Configure EVM-family chains

Every EVM-family spoke follows one pattern, keyed by the network's env prefix, shared by every asset on it (ETH_*, ARB_*, …). Validators only read and verify transactions — no private key is needed. Verification runs over standard JSON-RPC; free public defaults (PublicNode, then dRPC) are baked in and fine while bootstrapping or on testnet.

For a whitelisted validator the same rule as Bitcoin applies: add a keyed subscription. The verification loop re-reads the state-relevant ETH leg of every in-flight swap on each ~12s pass, and a rate-limited free endpoint failing mid-swap is how honest miners get timed out. We recommend Dwellir — its $49/mo tier is a flat 25M responses/month (no compute-unit weighting), which covers validator ETH load with an order of magnitude of headroom.

1. Sign up at dashboard.dwellir.com and subscribe.
2. Create an API key — it composes into the endpoint URL path.
3. Set ETH_RPC_URLS in .env — an ordered, comma-separated failover list; put the keyed endpoint first, keep the free ones as fallbacks, and prune dead URLs (every listed endpoint is consulted):

ETH_NETWORK=mainnet          # or sepolia on testnet
ETH_RPC_URLS=https://api-ethereum-mainnet.n.dwellir.com/YOUR_DWELLIR_KEY,https://ethereum-rpc.publicnode.com,https://eth.drpc.org

(Testnet endpoint pattern is the same: api-ethereum-sepolia.n.dwellir.com/YOUR_DWELLIR_KEY.)

Every other EVM asset is the same pattern under its own prefix — the asset's id uppercased (live ids: the pair matrix): {PREFIX}_NETWORK (mainnet | the chain's testnet; left unset it follows the neuron — a testnet neuron defaults each spoke to its testnet) and {PREFIX}_RPC_URLS (ordered failover list, keyed endpoint first — keys compose into the URL path). Free defaults are baked in for every supported chain; a whitelisted validator should add a keyed endpoint per asset it verifies.

:::note VALIDATORS BOOT EVERY CHAIN The validator starts a provider for every supported chain and fails fast if one is unreachable — you verify all pairs, not just the ones you care about. The baked-in free defaults satisfy this out of the box; if you override any *_RPC_URLS, make sure every listed endpoint actually serves that chain (each one is checked at startup). :::

Step 4: Get whitelisted

Voting is gated to a whitelisted validator set. Give the contract owner your Solana pubkey (the vote signer) — they run:

# Run by the contract admin:
alw admin add-vali <your_validator_solana_pubkey>

Whitelisting is what carries your stake weight into the reservation draw and makes your votes count toward consensus. While the subnet is bootstrapping, this step may be skipped — but until you're whitelisted, you don't influence outcomes.

Step 5: Bind your hotkey

Bind your Solana keypair to your Bittensor hotkey — this is how the network knows which stake backs your pubkey:

alw bind-hotkey

It binds the wallet/hotkey you set with alw config in Getting Started to the Solana keypair from Step 2 — it prints both before asking you to confirm. Same command miners use; one binding per pubkey, and the binding is permanent: re-running with the same hotkey refreshes the signature (idempotent), but a bound pubkey can never switch to a different hotkey — to change, bind a fresh Solana keypair. Run it after Step 4: the anti-squat gate only admits collateralized miners and whitelisted validators, so an un-whitelisted pubkey can't bind yet.

Why it matters: validators periodically post every whitelisted validator's stake to the contract by consensus (floor(alpha_stake / 35k) buckets, ~every 12 hours, all at the same block boundary), and the reservation draw weights your requests by that number. No binding = weight 0 — your routed requests stop winning seats, and every pool entry you pay for is charged the full base reservation fee: the fee is discounted by 2 × your share of total draw weight (capped at 95%, 0.001 SOL floor), so weight 0 means no discount. The validator warns at startup if your pubkey is unbound; it keeps running either way.

ALREADY RUNNING BUT NEVER BOUND? BIND NOW

If your validator predates the binding requirement (or you skipped this step), run alw bind-hotkey now. Until you do, your draw weight is 0 — routed swaps through you rarely win seats and pay the undiscounted reservation fee. Binding is permanent to the hotkey you choose, so bind the hotkey your validator actually runs.

Step 6: Run the validator

docker compose -f docker-compose.vali.yml up -d

The compose file includes Watchtower for auto-updates; hand-built images pinned to a branch disable it.

STAGED ROLLOUT — THE AUTHORITY LADDER

VALIDATOR_MODE sets how much authority the process exercises; climb it one rung at a time:

• watch — verifies swaps and computes scores but casts no on-chain votes (logs WOULD …) and sets no weights. Watch it here before it can slash or move emissions.
• vote — casts Solana consensus votes but still sets no Bittensor weights.
• full (default when unset) — votes and sets weights: production.

An unknown value refuses to start rather than silently running at full authority. The legacy VALIDATOR_DEV_MODE=1 still maps to watch but is ignored whenever VALIDATOR_MODE is set.

The validator polls every 12 seconds and must stay online continuously.

What the validator does

Once running, the validator operates two loops:

Reservation crank + verification loop (every ~12s):

Scoring loop (~hourly): replay crown-time over the window, score miners, and set Bittensor weights.

Bond relay (whenever TAO-backed miners are in play): miners can back quotes with a TAO bond held in an immutable vault on Bittensor, but Solana can't read a Bittensor bond and the vault can't read a Solana verdict — so validators carry state between the chains, each write landing by quorum on the receiving side:

• Mirror — attest each miner's locked vault bond onto the Solana contract, so TAO-backed purses can activate and their quotes can be checked against the bond.
• Slash relay — when a TAO-backed swap times out, carry the verdict to the vault; on quorum there the user is reimbursed in TAO from the miner's bond. This relay is why a TAO reimbursement lands shortly after the timeout rather than instantly.
• Unlock — when a TAO-backed miner deactivates and its in-flight swaps and timeout windows drain, vote to unlock the bond so the miner can withdraw it.

Key behaviours

• Consensus voting — every state transition (initiate, confirm, timeout, activate) needs a quorum of whitelisted validators to agree before it executes.
• Independent verification — each validator verifies both legs itself; no trust between validators.
• Abstention — if a validator can't verify a transaction, it abstains rather than voting falsely.
• Deferred confirmation — a source deposit is accepted seen-but-unconfirmed; the crank extends the deadline while confirmations accrue and only attests once the leg is confirmed and fresh. Don't slow the forward step — the extension window is time-bounded.
• Permissionless crank — resolve_pool is permissionless, so every validator cranks every closed pool; racing txs are benign no-ops.

For the full system design, see How It Works.