Bittensor Operations

Bittensor Subnet 25 Operations & Commands Guide

This guide details operating procedures, command references, and telemetry monitoring for URNetwork Connect nodes participating in Bittensor Subnet 25.

---

1. Subnet 25 Architecture & Earning Mechanics

URNetwork Connect providers operate on a dual-incentive model:

1. Network Provider Traffic: Direct bandwidth earnings based on billable byte delivery and client session routing.
2. Bittensor Subnet 25 Incentive Pool: On-chain emissions distributed proportionally to verified miners based on Merkle-proven bandwidth scores across finalized payout epochs.

Identity & Wallet Model

• Network Account Token (jwt): The provider authenticates to the URNetwork control plane using a signed JWT stored at ~/.urnetwork/jwt (or container volume /home/urnet/.urnetwork/jwt).
• Claim Coldkey (ss58): Bittensor coldkey address (prefix 42, e.g. 5FjfHgd4K3H5Vge2igPtBYyWRbRKdgH84roTCnWwwtNgAhU5) registered with the platform to authorize and receive pool emissions.
• Mirror Account: EVM smart contract accounts mirrored on Subtensor via evm:<H160_address> hash derivation for non-custodial claims.

Two Distinct Miner Tiers: Pool Providers vs. Top 200 Head Fleets

Subnet 25 operates a two-channel architecture under a hard 256-UID metagraph ceiling (urfoundation/sn WHITEPAPER §8.4, §11.4; protocol/policy.go): 256 >= (Top-Level Head Miners ~200) + (NO-Pool UIDs) + (Validator UIDs)

The 41% miner emission is divided into two distinct processes:

Dimension	Tail Providers (Pool Process)	Top ~200 Fleets (Head Miner Process)
On-Chain Identity	No UID. Operates as a client_id inside an operator's pool.	Holds its own Subnet 25 Miner UID (claimed via burned_register).
Scoring Basis	Demand-coupled: deposit × quality across the operator's pool.	Pure measured routable-IP breadth (score(u) = Σ 1/claim(h) across verified /29 IPv4 & /48 IPv6 subnets).
Emission & Payout	Custodied in EVM Contract (STSubnet.sol). Requires Merkle inclusion proofs.	Native Bittensor Protocol Emission via Yuma Consensus credited as α stake directly to the coldkey.
Payout Timing	Finalized once per epoch (~7 days / 50,400 blocks).	Deposited every block (~12 seconds).
Gas & Claiming	Manual Claim Required: Operators submit an on-chain claimMiner transaction and pay gas.	Zero Gas, Zero Claims: Automated native emission. No EVM contract claims, no Merkle trees.
Intermediary	Operator commits the Merkle payout root (auditable on-chain).	Trust-minimized: Direct consensus-to-coldkey. No operator in the payout path.
Setup Required	Linked via POST /sn/wallet (or provider wallet set).	Requires Dual-Signed Fleet Binding (provider bind-head) linking provider server keys to the Bittensor Substrate hotkey.
Lifecycle Tournament	The Baseline On-Ramp: Guaranteed floor without UID registration burn.	The Merit Apex: Earns directly while in the top 200. If IP breadth falls below the cutoff, it is evicted by Yuma churn and falls back into the pool.

---

2. Coldkey Registration & Setup

Before claiming Subnet 25 emissions, link your Bittensor coldkey to your network account using any of the following methods.

Method 1: Single-Line curl (Direct API)

Run this single command on the machine running your provider:

curl -s -X POST "https://api.bringyour.com/sn/wallet" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(cat ~/.urnetwork/jwt)" \
  -d '{"coldkey_ss58": "5FjfHgd4K3H5Vge2igPtBYyWRbRKdgH84roTCnWwwtNgAhU5"}'

Returns {} on success.

Note

This is the same unsigned request that provider wallet set sends. The platform is moving wallet binding to a signed consent, and whether it still accepts the unsigned request is a server-side policy. If it is refused, set the wallet in the URnetwork app or web account.

Method 2: Host / Bare-Metal CLI

# Register coldkey for the local provider
provider wallet set 5FjfHgd4K3H5Vge2igPtBYyWRbRKdgH84roTCnWwwtNgAhU5

provider wallet set and provide --wallet=<coldkey> send the unsigned network wallet request, which the platform may refuse under its signed wallet rules. Without --legacy-network-wallet they do not send it: wallet set exits 1, and provide logs the refusal and keeps providing. Set the wallet in the URnetwork app or web account, or add --legacy-network-wallet to send the unsigned request anyway.

Method 3: Docker Deployments

Pass your coldkey directly via docker-compose.yml or container flags:

services:
  provider:
    image: ghcr.io/full-bars/meso-miner:latest
    command: ["provide", "--wallet=5FjfHgd4K3H5Vge2igPtBYyWRbRKdgH84roTCnWwwtNgAhU5", "--legacy-network-wallet"]
    volumes:
      - ur_config_1:/home/urnet/.urnetwork

Beginner FAQ: Why Didn't My Browser Wallet Pop Up to Sign?

If you are used to Web3 dApps prompting your browser extension (like Talisman, SubWallet, Polkadot{.js}, or MetaMask) to approve transactions, you might wonder why linking your wallet here didn't trigger a popup:

1. Linking your wallet (Step 1 — Direct Deposit Setup):

   • Think of this like giving an employer your account number for direct deposit.
   • You are only telling URNetwork where to send your rewards. Because sharing a public wallet address cannot move or spend funds from your wallet, no signature, password, or browser wallet popup is required.
   • The system verifies your node using your local authentication file (~/.urnetwork/jwt).

2. Claiming your rewards (Step 2 — Withdrawing Tokens):

   • This is where your browser wallet extension is used.
   • At the end of every reward cycle (epoch), emissions are calculated and locked on the blockchain. When you go to claim those tokens to your wallet on the web dashboard or portal, your browser wallet extension will pop up and ask you to click Approve / Sign to finalize the on-chain transfer.

---

3. Real-Time Status & Telemetry (sn-status)

Use sn-status to inspect your global ranking, bandwidth delivery, coldkey linkage, and Top 200 cutoff eligibility in real time without exposing credentials in the process table.

Commands

# Host CLI (systemd / bare-metal)
urnet-tools sn-status

# Docker CLI (delegates directly into running container)
urnet-docker sn-status

# Provider binary directly
provider sn-status

# JSON format for monitoring agents and Prometheus scrapers
urnet-tools sn-status --json

Dashboard Output

════════════════════════════════════════════════════════════════════════════════
  URNetwork Subnet 25 — Node & Miner Status
════════════════════════════════════════════════════════════════════════════════
  Provider:         urnetwork.service (State: /var/lib/urnetwork)
  Network:          miner-node-01 (f078e470-36d0-48e0-bb15-b5d1e2e9c1aa)
  Global Rank:      #7 [Public] — Tier 1 Elite (Rank #7 Globally)
  Net Bandwidth:    1,234,567.89 MiB (1205.63 GiB) provided
  Coldkey (SS58):   5FjfHgd4K3H5Vge2igPtBYyWRbRKdgH84roTCnWwwtNgAhU5
  Coldkey (Hex):    0xa21b...
  Subnet Epoch:     #1054 (Start: #1054000, Finalize: #1054720)
  Contract:         0x5FbDB2315678afecb367f032d93F642f64180aa3 (Chain ID: 964)
  Payout Share:     4.85% (485 bps in Epoch #1053)
════════════════════════════════════════════════════════════════════════════════

Ranking Tiers & Eligibility

• Tier 1 Elite (Rank 1–10): Top global emission allocation; highest validator query preference.
• Tier 2 High-Volume (Rank 11–50): High yield; fast validator probe acceptance.
• Tier 3 Active (Rank 51–200): Subnet 25 emission cutoff eligibility boundary.
• Unranked / Sub-200: Displays exact distance to Top 200 emission threshold.

---

4. Epoch Payout Claims

Subnet 25 uses cryptographic Merkle tree payout roots committed on-chain at the conclusion of each epoch.

Epoch Stages

1. Active Epoch ($e$): Nodes stream billable bandwidth; validators collect signed trails.
2. Commit Window: Validator consensus commits the payout root hash.
3. Dispute / Finalization: Payout root is locked on-chain (finalize_block).
4. Claim Window: Verified claims become redeemable.

Claim credential (required)

provider claim authenticates with the login of a client that served traffic, because only such a client has a payout. Pass exactly one of:

Flag	Credential
--store-client=<key>	The client token of one identity in ~/.urnetwork/.client_jwts.json. The key is a proxy address or direct. Pick an identity that served traffic.
--provider-jwt=<path>	A client token in a file.
--legacy-coldkey=<coldkey_ss58>	The network token plus this coldkey. Only for an epoch without a provider artifact.

The network token alone is refused, and so is an expired client token (start the provider so it renews, or pass a fresher file). A command with no credential flag exits 1 and names these options. The examples below show --store-client=direct; substitute your own credential flag.

Workflow 1: Air-Gapped / Offline Calldata (Recommended)

Generates ABI-encoded calldata and cryptographic inclusion proofs without exposing private keys on the provider host:

provider claim --store-client=direct --epoch=1053

Output yields ready-to-submit calldata compatible with snclaim or web3 wallets.

Workflow 2: Direct On-Chain Submission

Submit the claim transaction directly with a local private key file and RPC endpoint:

provider claim \
  --store-client=direct \
  --epoch=1053 \
  --rpc=https://rpc.subtensor.network \
  --key_file=/path/to/coldkey_evm.key

Dry Run Verification

Simulate verification and root matching without broadcasting transactions:

provider claim --store-client=direct --epoch=1053 --rpc=https://rpc.subtensor.network --dry-run

---

5. Head Node Delegation (bind-head)

Head nodes aggregate proofs from client nodes for on-chain batch verification.

Binding a Hotkey

provider bind-head \
  --manifest=<fleet_manifest_file> \
  --hotkey_seed_file=<sr25519_seed_file> \
  --valid_from_epoch=<n> --valid_to_epoch=<n> \
  [--client_id=<hex16>] [--client_seed_file=<file>] \
  [--rpc=<rpc_url>]... [--key_file=<key_file>] [--dry-run]

Important

The retired --hotkey / --registrant / --contract flags are gone. The binding now reads the fleet manifest (coordinator, chain id, netuid, members) and binds the sr25519 hotkey whose seed file you pass — the seed must match the manifest hotkey, and the command rejects a mismatch. Seed files must be regular files readable only by their owner. Without --key_file the command prints the calldata for offline broadcast; with --key_file it submits through --rpc.

Unbinding a Hotkey

provider unbind-head \
  --manifest=<fleet_manifest_file> \
  --effective_epoch=<n> \
  [--client_id=<hex16>] [--client_seed_file=<file>] \
  [--offline] [--rpc=<rpc_url>]... [--key_file=<key_file>] [--dry-run]

Tip

The command is air-gapped-friendly, but signing without an on-chain cross-check is explicit: without --rpc pass --offline, and the output warns that the generation and effective epoch were not verified against any coordinator (labelled offline (local domain)). Re-run with --rpc to cross-check the coordinator's canonical digest before broadcasting, and pass --key_file to submit.

---

6. Operational Security Guidelines

1. Never pass tokens via CLI flags: Avoid passing tokens in process flags (-jwt=... or -pass=...) where they are visible in ps aux or /proc/<pid>/cmdline.
2. File Permissions: Ensure ~/.urnetwork/jwt and private keys are set to 0600 permissions.
3. Container Isolation: Ensure each container mount uses a dedicated Docker volume (e.g. ur_config_1, ur_config_2) to prevent state corruption.