UR Subnet

A Bittensor subnet for a decentralized privacy network.

This repository (sn) is the reference implementation of the UR Subnet — the EVM contract suite, miner and validator software, chain tooling, and the real-testnet integration harness. The operator/API implementation lives in the sibling server repository.

Network Operators run the servers. Independent providers carry ingress/egress traffic. Independent validators run the VALIDATOR.md routing‑verification protocol — walking server‑assigned chains of providers to prove real‑time transit and measure which providers are the weakest links. Bittensor's Yuma Consensus turns that measurement into emission. Everything is denominated in the subnet's native token — α, branded $UR.

The full specification is in WHITEPAPER.md; the design rationale versus the rest of the Bittensor field is in COMPARISON.md.

Mechanism at a glance

Money flows in three coupled channels, all in α:

Deposits — the demand signal, conviction stake, and a buyback. Each NO deposits α through the coordinator, sized to its real usage at an off‑chain published rate (no on‑chain oracle). Deposits are the costly signal of real demand — and they are never distributed: every exact deposit is transferred into the immutable STReserveSink and staked on the fixed reserve hotkey (compounding dividends, with no outbound bytecode). A NO's cumulative locked α (its conviction) sets its tier → rate: zero conviction pays the baseline rate; more conviction lowers it — the onboarding and alignment lever.
Emission (Yuma Consensus). The Bittensor coinbase pays the standard 18% owner / 41% miner / 41% validator α split. Each tempo (~72 min), independent validators score both miner tiers from their own trails, submit weights under commit‑reveal, and Yuma's stake‑weighted median + clipping + vtrust turns those scores into miner emission — so the validators' evaluation is what moves the money. Validator emission flows natively (∝ stake × vtrust).
Settlement (7‑day epoch). Over each epoch the immutable settlement vault captures pool miner emission and providers claim their α directly from the vault with cryptographic proofs. A NO directs where its pool's rewards go but never holds anyone else's funds.

Two miner tiers, in parallel

Because one NO may serve 100k+ providers — far beyond a subnet's ~256 UID cap — the miner side runs two tiers inside one mechanism, divided by a governance share θ:

Pool tier (tail, 1−θ) — the on‑ramp. Each NO is a single vault‑owned pool UID; validators weight it implied_usage × quality (implied usage = the NO's deposit ÷ its tier rate). Its providers are not UIDs — they are paid inside the pool by Merkle claim. Low provider barrier (join a NO; the provider needs no UID or burn because the immutable vault owns one shared, burn-registered pool UID per NO), baseline reward.
Top‑level miners (head, θ) — the supply apex. The top ~200 fleets by split‑adjusted distinct routable egress‑IP count (real VPN supply breadth, not traffic volume) each claim their own miner UID, are steered directly by validators, and are paid natively to their own hotkey — no contract custody, no Merkle claim, no operator in the payout path. A fleet is matched to its UID by a dual‑signed client_ids ⇄ hotkey binding.

A provider starts in a pool, graduates to a top slot as its routable‑IP breadth grows, and falls back if it slips — with Bittensor's native deregistration churn running that tournament. A client_id earns in exactly one tier at a time (no double‑pay). Start tail‑weighted (θ ≈ 0.3) and widen it as the top‑miner set and validator consensus mature.

Custody and trust model

No operator custody. The owner and NOs never hold or distribute anyone else's α. The immutable vault is the sole custodian of in‑transit pool emission; every payout is a direct on‑chain pull claim; the head is paid natively.
Finalized claims are sacrosanct from day one — no upgrade, pause, or admin action can block or claw back a finalized claim.
The buyback reserve is one‑way — no contract function ever sources a transfer out of it.
Split governance.STReserveSink and STSettlementVault are non-upgradeable from launch. Only STCoordinator is UUPS-upgradeable: testnet uses a dedicated value-capped owner, while mainnet requires a distinct 2-of-3 Safe, followed by a ≥1-epoch timelock.

How this compares to the Bittensor field

The UR Subnet follows the Bittensor core almost everywhere and diverges only deliberately. Of the major design decisions, 12 are aligned with prevailing practice, 2 are divergent (reward settlement/custody and the worker‑payout trust model — both toward trustlessness), and 2 are genuinely novel bets: coupling miner reward to real, revenue‑backed demand (implied_usage × quality) and tiering miners into a trust‑minimized pooled tail plus a directly‑paid head.

Full analysis, per‑theme and per‑subnet, is in COMPARISON.md.

Participate

Register a network operator

Register a network‑operator key, then run the /verify server and deposit α. See the provider/operator documentation at https://ur.xyz. Operators register a client_id with the subnet used for root contracts, so they can independently audit their contracts. In the launch phase, operator admission is owner‑gated.

Each epoch, an NO commits the Merkle payout root that splits its pool among its providers. It directs the split; the immutable vault holds and pays.

Register a provider (ingress or egress)

Follow the provider documentation at https://ur.xyz. Providers work with network operators — the default list of operators in the code is a good place to start, and you can add more with -no <domain> (repeatable) or -nofile <path> (one operator domain per line).

Providers register a client_id with the subnet, and are paid inside their NO's pool by Merkle claim against that NO's payout root. A provider whose routable‑IP breadth ranks among the network's top ~200 fleets can claim its own top‑level miner UID and be paid directly by validator emission steering — no pool, no operator in the payout path. It links its client_ids to its wallet/hotkey with a dual‑signed binding so validators can attribute its measured breadth to that slot. See WHITEPAPER.md §8.4 and §11.4.

Register a validator

Validators stake their own α, run the VALIDATOR.md routing‑verification protocol (walking provider chains to measure quality and routable‑IP breadth), and each tempo score both miner tiers under commit‑reveal — the pools by implied_usage × quality and the head by routable‑IP breadth. Validators earn Bittensor‑native dividends (∝ stake × scoring accuracy) — v1's only validator reward. No NO owns a validator; the set is permissionless and Bittensor‑native.

The epoch lifecycle (a block is the 7‑day settlement epoch, ≈ 50 400 chain blocks):

When	What
`t = 0`	A keeper calls `closeOperatorEpoch`; the vault captures that NO's pool emission at the boundary.
`t ≤ +4h`	Each NO commits its payout‑list root for the epoch.
`t < +48h`	Audit window — committed roots and content-addressed payout artifacts are public and reproducible.
`+48h`	`finalizeOperatorEpoch`: the vault fixes the per‑NO entitlement and claims open.

Top‑level miners need no settlement — Yuma pays their UID natively each tempo.

One mechanism, two scoring channels

Release 1.0 fixes mechanism_count = 1. Pool UIDs and direct head UIDs share one native weight vector; validators normalize the head to θ and the pool tail to 1−θ before CRv4 commit. A second sub-mechanism is explicitly out of scope because it would partition the finite UID budget and undermine the intended ~200-member head.

Repository layout

Path	What
`WHITEPAPER.md`	The full subnet specification.
`VALIDATOR.md`	The off‑chain routing‑verification (`/verify`) protocol.
`COMPARISON.md`	Design‑decision comparison versus the Bittensor field.
`diagrams/`	The diagrams above (SVG sources + generators).
`evm/`	Reserve sink, settlement vault, UUPS coordinator, tests, and generated artifacts.
`validator/`	The validator binary.
`miner/`, `cli/`	Release miner/operator tooling.
`stctl/`	Explicitly quarantined pre-1.0 monolith diagnostic; not a release write path.
`crv4/`, `merkle/`, `ss58/`, `stabi/`	Supporting libraries (commit‑reveal v4, Merkle trees, address encoding, contract bindings).
`sim-testnet/`	Spend-capped Go harness for testnet setup, launch, scenarios, evidence, and analysis.

UR Subnet

A Bittensor subnet for a decentralized privacy network.

This repository (sn) is the reference implementation of the UR Subnet — the EVM contract suite, miner and validator software, chain tooling, and the real-testnet integration harness. The operator/API implementation lives in the sibling server repository.

Network Operators run the servers. Independent providers carry ingress/egress traffic. Independent validators run the VALIDATOR.md routing‑verification protocol — walking server‑assigned chains of providers to prove real‑time transit and measure which providers are the weakest links. Bittensor's Yuma Consensus turns that measurement into emission. Everything is denominated in the subnet's native token — α, branded $UR.

The full specification is in WHITEPAPER.md; the design rationale versus the rest of the Bittensor field is in COMPARISON.md.

Mechanism at a glance

Money flows in three coupled channels, all in α:

Deposits — the demand signal, conviction stake, and a buyback. Each NO deposits α through the coordinator, sized to its real usage at an off‑chain published rate (no on‑chain oracle). Deposits are the costly signal of real demand — and they are never distributed: every exact deposit is transferred into the immutable STReserveSink and staked on the fixed reserve hotkey (compounding dividends, with no outbound bytecode). A NO's cumulative locked α (its conviction) sets its tier → rate: zero conviction pays the baseline rate; more conviction lowers it — the onboarding and alignment lever.
Emission (Yuma Consensus). The Bittensor coinbase pays the standard 18% owner / 41% miner / 41% validator α split. Each tempo (~72 min), independent validators score both miner tiers from their own trails, submit weights under commit‑reveal, and Yuma's stake‑weighted median + clipping + vtrust turns those scores into miner emission — so the validators' evaluation is what moves the money. Validator emission flows natively (∝ stake × vtrust).
Settlement (7‑day epoch). Over each epoch the immutable settlement vault captures pool miner emission and providers claim their α directly from the vault with cryptographic proofs. A NO directs where its pool's rewards go but never holds anyone else's funds.

Two miner tiers, in parallel

Because one NO may serve 100k+ providers — far beyond a subnet's ~256 UID cap — the miner side runs two tiers inside one mechanism, divided by a governance share θ:

Pool tier (tail, 1−θ) — the on‑ramp. Each NO is a single vault‑owned pool UID; validators weight it implied_usage × quality (implied usage = the NO's deposit ÷ its tier rate). Its providers are not UIDs — they are paid inside the pool by Merkle claim. Low provider barrier (join a NO; the provider needs no UID or burn because the immutable vault owns one shared, burn-registered pool UID per NO), baseline reward.
Top‑level miners (head, θ) — the supply apex. The top ~200 fleets by split‑adjusted distinct routable egress‑IP count (real VPN supply breadth, not traffic volume) each claim their own miner UID, are steered directly by validators, and are paid natively to their own hotkey — no contract custody, no Merkle claim, no operator in the payout path. A fleet is matched to its UID by a dual‑signed client_ids ⇄ hotkey binding.

A provider starts in a pool, graduates to a top slot as its routable‑IP breadth grows, and falls back if it slips — with Bittensor's native deregistration churn running that tournament. A client_id earns in exactly one tier at a time (no double‑pay). Start tail‑weighted (θ ≈ 0.3) and widen it as the top‑miner set and validator consensus mature.

Custody and trust model

No operator custody. The owner and NOs never hold or distribute anyone else's α. The immutable vault is the sole custodian of in‑transit pool emission; every payout is a direct on‑chain pull claim; the head is paid natively.
Finalized claims are sacrosanct from day one — no upgrade, pause, or admin action can block or claw back a finalized claim.
The buyback reserve is one‑way — no contract function ever sources a transfer out of it.
Split governance.STReserveSink and STSettlementVault are non-upgradeable from launch. Only STCoordinator is UUPS-upgradeable: testnet uses a dedicated value-capped owner, while mainnet requires a distinct 2-of-3 Safe, followed by a ≥1-epoch timelock.

How this compares to the Bittensor field

The UR Subnet follows the Bittensor core almost everywhere and diverges only deliberately. Of the major design decisions, 12 are aligned with prevailing practice, 2 are divergent (reward settlement/custody and the worker‑payout trust model — both toward trustlessness), and 2 are genuinely novel bets: coupling miner reward to real, revenue‑backed demand (implied_usage × quality) and tiering miners into a trust‑minimized pooled tail plus a directly‑paid head.

Full analysis, per‑theme and per‑subnet, is in COMPARISON.md.

Participate

Register a network operator

Register a network‑operator key, then run the /verify server and deposit α. See the provider/operator documentation at https://ur.xyz. Operators register a client_id with the subnet used for root contracts, so they can independently audit their contracts. In the launch phase, operator admission is owner‑gated.

Each epoch, an NO commits the Merkle payout root that splits its pool among its providers. It directs the split; the immutable vault holds and pays.

Register a provider (ingress or egress)

Follow the provider documentation at https://ur.xyz. Providers work with network operators — the default list of operators in the code is a good place to start, and you can add more with -no <domain> (repeatable) or -nofile <path> (one operator domain per line).

Providers register a client_id with the subnet, and are paid inside their NO's pool by Merkle claim against that NO's payout root. A provider whose routable‑IP breadth ranks among the network's top ~200 fleets can claim its own top‑level miner UID and be paid directly by validator emission steering — no pool, no operator in the payout path. It links its client_ids to its wallet/hotkey with a dual‑signed binding so validators can attribute its measured breadth to that slot. See WHITEPAPER.md §8.4 and §11.4.

Register a validator

Validators stake their own α, run the VALIDATOR.md routing‑verification protocol (walking provider chains to measure quality and routable‑IP breadth), and each tempo score both miner tiers under commit‑reveal — the pools by implied_usage × quality and the head by routable‑IP breadth. Validators earn Bittensor‑native dividends (∝ stake × scoring accuracy) — v1's only validator reward. No NO owns a validator; the set is permissionless and Bittensor‑native.

The epoch lifecycle (a block is the 7‑day settlement epoch, ≈ 50 400 chain blocks):

When	What
`t = 0`	A keeper calls `closeOperatorEpoch`; the vault captures that NO's pool emission at the boundary.
`t ≤ +4h`	Each NO commits its payout‑list root for the epoch.
`t < +48h`	Audit window — committed roots and content-addressed payout artifacts are public and reproducible.
`+48h`	`finalizeOperatorEpoch`: the vault fixes the per‑NO entitlement and claims open.

Top‑level miners need no settlement — Yuma pays their UID natively each tempo.

One mechanism, two scoring channels

Release 1.0 fixes mechanism_count = 1. Pool UIDs and direct head UIDs share one native weight vector; validators normalize the head to θ and the pool tail to 1−θ before CRv4 commit. A second sub-mechanism is explicitly out of scope because it would partition the finite UID budget and undermine the intended ~200-member head.

Repository layout

Path	What
`WHITEPAPER.md`	The full subnet specification.
`VALIDATOR.md`	The off‑chain routing‑verification (`/verify`) protocol.
`COMPARISON.md`	Design‑decision comparison versus the Bittensor field.
`diagrams/`	The diagrams above (SVG sources + generators).
`evm/`	Reserve sink, settlement vault, UUPS coordinator, tests, and generated artifacts.
`validator/`	The validator binary.
`miner/`, `cli/`	Release miner/operator tooling.
`stctl/`	Explicitly quarantined pre-1.0 monolith diagnostic; not a release write path.
`crv4/`, `merkle/`, `ss58/`, `stabi/`	Supporting libraries (commit‑reveal v4, Merkle trees, address encoding, contract bindings).
`sim-testnet/`	Spend-capped Go harness for testnet setup, launch, scenarios, evidence, and analysis.

UR Subnet

A Bittensor subnet for a decentralized privacy network.

This repository (sn) is the reference implementation of the UR Subnet — the EVM contract suite, miner and validator software, chain tooling, and the real-testnet integration harness. The operator/API implementation lives in the sibling server repository.

Network Operators run the servers. Independent providers carry ingress/egress traffic. Independent validators run the VALIDATOR.md routing‑verification protocol — walking server‑assigned chains of providers to prove real‑time transit and measure which providers are the weakest links. Bittensor's Yuma Consensus turns that measurement into emission. Everything is denominated in the subnet's native token — α, branded $UR.

The full specification is in WHITEPAPER.md; the design rationale versus the rest of the Bittensor field is in COMPARISON.md.

Mechanism at a glance

Money flows in three coupled channels, all in α:

Deposits — the demand signal, conviction stake, and a buyback. Each NO deposits α through the coordinator, sized to its real usage at an off‑chain published rate (no on‑chain oracle). Deposits are the costly signal of real demand — and they are never distributed: every exact deposit is transferred into the immutable STReserveSink and staked on the fixed reserve hotkey (compounding dividends, with no outbound bytecode). A NO's cumulative locked α (its conviction) sets its tier → rate: zero conviction pays the baseline rate; more conviction lowers it — the onboarding and alignment lever.
Emission (Yuma Consensus). The Bittensor coinbase pays the standard 18% owner / 41% miner / 41% validator α split. Each tempo (~72 min), independent validators score both miner tiers from their own trails, submit weights under commit‑reveal, and Yuma's stake‑weighted median + clipping + vtrust turns those scores into miner emission — so the validators' evaluation is what moves the money. Validator emission flows natively (∝ stake × vtrust).
Settlement (7‑day epoch). Over each epoch the immutable settlement vault captures pool miner emission and providers claim their α directly from the vault with cryptographic proofs. A NO directs where its pool's rewards go but never holds anyone else's funds.

Two miner tiers, in parallel

Because one NO may serve 100k+ providers — far beyond a subnet's ~256 UID cap — the miner side runs two tiers inside one mechanism, divided by a governance share θ:

Pool tier (tail, 1−θ) — the on‑ramp. Each NO is a single vault‑owned pool UID; validators weight it implied_usage × quality (implied usage = the NO's deposit ÷ its tier rate). Its providers are not UIDs — they are paid inside the pool by Merkle claim. Low provider barrier (join a NO; the provider needs no UID or burn because the immutable vault owns one shared, burn-registered pool UID per NO), baseline reward.
Top‑level miners (head, θ) — the supply apex. The top ~200 fleets by split‑adjusted distinct routable egress‑IP count (real VPN supply breadth, not traffic volume) each claim their own miner UID, are steered directly by validators, and are paid natively to their own hotkey — no contract custody, no Merkle claim, no operator in the payout path. A fleet is matched to its UID by a dual‑signed client_ids ⇄ hotkey binding.

A provider starts in a pool, graduates to a top slot as its routable‑IP breadth grows, and falls back if it slips — with Bittensor's native deregistration churn running that tournament. A client_id earns in exactly one tier at a time (no double‑pay). Start tail‑weighted (θ ≈ 0.3) and widen it as the top‑miner set and validator consensus mature.

Custody and trust model

No operator custody. The owner and NOs never hold or distribute anyone else's α. The immutable vault is the sole custodian of in‑transit pool emission; every payout is a direct on‑chain pull claim; the head is paid natively.
Finalized claims are sacrosanct from day one — no upgrade, pause, or admin action can block or claw back a finalized claim.
The buyback reserve is one‑way — no contract function ever sources a transfer out of it.
Split governance.STReserveSink and STSettlementVault are non-upgradeable from launch. Only STCoordinator is UUPS-upgradeable: testnet uses a dedicated value-capped owner, while mainnet requires a distinct 2-of-3 Safe, followed by a ≥1-epoch timelock.

How this compares to the Bittensor field

The UR Subnet follows the Bittensor core almost everywhere and diverges only deliberately. Of the major design decisions, 12 are aligned with prevailing practice, 2 are divergent (reward settlement/custody and the worker‑payout trust model — both toward trustlessness), and 2 are genuinely novel bets: coupling miner reward to real, revenue‑backed demand (implied_usage × quality) and tiering miners into a trust‑minimized pooled tail plus a directly‑paid head.

Full analysis, per‑theme and per‑subnet, is in COMPARISON.md.

Participate

Register a network operator

Register a network‑operator key, then run the /verify server and deposit α. See the provider/operator documentation at https://ur.xyz. Operators register a client_id with the subnet used for root contracts, so they can independently audit their contracts. In the launch phase, operator admission is owner‑gated.

Each epoch, an NO commits the Merkle payout root that splits its pool among its providers. It directs the split; the immutable vault holds and pays.

Register a provider (ingress or egress)

Follow the provider documentation at https://ur.xyz. Providers work with network operators — the default list of operators in the code is a good place to start, and you can add more with -no <domain> (repeatable) or -nofile <path> (one operator domain per line).

Providers register a client_id with the subnet, and are paid inside their NO's pool by Merkle claim against that NO's payout root. A provider whose routable‑IP breadth ranks among the network's top ~200 fleets can claim its own top‑level miner UID and be paid directly by validator emission steering — no pool, no operator in the payout path. It links its client_ids to its wallet/hotkey with a dual‑signed binding so validators can attribute its measured breadth to that slot. See WHITEPAPER.md §8.4 and §11.4.

Register a validator

Validators stake their own α, run the VALIDATOR.md routing‑verification protocol (walking provider chains to measure quality and routable‑IP breadth), and each tempo score both miner tiers under commit‑reveal — the pools by implied_usage × quality and the head by routable‑IP breadth. Validators earn Bittensor‑native dividends (∝ stake × scoring accuracy) — v1's only validator reward. No NO owns a validator; the set is permissionless and Bittensor‑native.

The epoch lifecycle (a block is the 7‑day settlement epoch, ≈ 50 400 chain blocks):

When	What
`t = 0`	A keeper calls `closeOperatorEpoch`; the vault captures that NO's pool emission at the boundary.
`t ≤ +4h`	Each NO commits its payout‑list root for the epoch.
`t < +48h`	Audit window — committed roots and content-addressed payout artifacts are public and reproducible.
`+48h`	`finalizeOperatorEpoch`: the vault fixes the per‑NO entitlement and claims open.

Top‑level miners need no settlement — Yuma pays their UID natively each tempo.

One mechanism, two scoring channels

Release 1.0 fixes mechanism_count = 1. Pool UIDs and direct head UIDs share one native weight vector; validators normalize the head to θ and the pool tail to 1−θ before CRv4 commit. A second sub-mechanism is explicitly out of scope because it would partition the finite UID budget and undermine the intended ~200-member head.

Repository layout

Path	What
`WHITEPAPER.md`	The full subnet specification.
`VALIDATOR.md`	The off‑chain routing‑verification (`/verify`) protocol.
`COMPARISON.md`	Design‑decision comparison versus the Bittensor field.
`diagrams/`	The diagrams above (SVG sources + generators).
`evm/`	Reserve sink, settlement vault, UUPS coordinator, tests, and generated artifacts.
`validator/`	The validator binary.
`miner/`, `cli/`	Release miner/operator tooling.
`stctl/`	Explicitly quarantined pre-1.0 monolith diagnostic; not a release write path.
`crv4/`, `merkle/`, `ss58/`, `stabi/`	Supporting libraries (commit‑reveal v4, Merkle trees, address encoding, contract bindings).
`sim-testnet/`	Spend-capped Go harness for testnet setup, launch, scenarios, evidence, and analysis.

UR Subnet

A Bittensor subnet for a decentralized privacy network.

This repository (sn) is the reference implementation of the UR Subnet — the EVM contract suite, miner and validator software, chain tooling, and the real-testnet integration harness. The operator/API implementation lives in the sibling server repository.

Network Operators run the servers. Independent providers carry ingress/egress traffic. Independent validators run the VALIDATOR.md routing‑verification protocol — walking server‑assigned chains of providers to prove real‑time transit and measure which providers are the weakest links. Bittensor's Yuma Consensus turns that measurement into emission. Everything is denominated in the subnet's native token — α, branded $UR.

The full specification is in WHITEPAPER.md; the design rationale versus the rest of the Bittensor field is in COMPARISON.md.

Mechanism at a glance

Money flows in three coupled channels, all in α:

Deposits — the demand signal, conviction stake, and a buyback. Each NO deposits α through the coordinator, sized to its real usage at an off‑chain published rate (no on‑chain oracle). Deposits are the costly signal of real demand — and they are never distributed: every exact deposit is transferred into the immutable STReserveSink and staked on the fixed reserve hotkey (compounding dividends, with no outbound bytecode). A NO's cumulative locked α (its conviction) sets its tier → rate: zero conviction pays the baseline rate; more conviction lowers it — the onboarding and alignment lever.
Emission (Yuma Consensus). The Bittensor coinbase pays the standard 18% owner / 41% miner / 41% validator α split. Each tempo (~72 min), independent validators score both miner tiers from their own trails, submit weights under commit‑reveal, and Yuma's stake‑weighted median + clipping + vtrust turns those scores into miner emission — so the validators' evaluation is what moves the money. Validator emission flows natively (∝ stake × vtrust).
Settlement (7‑day epoch). Over each epoch the immutable settlement vault captures pool miner emission and providers claim their α directly from the vault with cryptographic proofs. A NO directs where its pool's rewards go but never holds anyone else's funds.

Two miner tiers, in parallel

Because one NO may serve 100k+ providers — far beyond a subnet's ~256 UID cap — the miner side runs two tiers inside one mechanism, divided by a governance share θ:

Pool tier (tail, 1−θ) — the on‑ramp. Each NO is a single vault‑owned pool UID; validators weight it implied_usage × quality (implied usage = the NO's deposit ÷ its tier rate). Its providers are not UIDs — they are paid inside the pool by Merkle claim. Low provider barrier (join a NO; the provider needs no UID or burn because the immutable vault owns one shared, burn-registered pool UID per NO), baseline reward.
Top‑level miners (head, θ) — the supply apex. The top ~200 fleets by split‑adjusted distinct routable egress‑IP count (real VPN supply breadth, not traffic volume) each claim their own miner UID, are steered directly by validators, and are paid natively to their own hotkey — no contract custody, no Merkle claim, no operator in the payout path. A fleet is matched to its UID by a dual‑signed client_ids ⇄ hotkey binding.

A provider starts in a pool, graduates to a top slot as its routable‑IP breadth grows, and falls back if it slips — with Bittensor's native deregistration churn running that tournament. A client_id earns in exactly one tier at a time (no double‑pay). Start tail‑weighted (θ ≈ 0.3) and widen it as the top‑miner set and validator consensus mature.

Custody and trust model

No operator custody. The owner and NOs never hold or distribute anyone else's α. The immutable vault is the sole custodian of in‑transit pool emission; every payout is a direct on‑chain pull claim; the head is paid natively.
Finalized claims are sacrosanct from day one — no upgrade, pause, or admin action can block or claw back a finalized claim.
The buyback reserve is one‑way — no contract function ever sources a transfer out of it.
Split governance.STReserveSink and STSettlementVault are non-upgradeable from launch. Only STCoordinator is UUPS-upgradeable: testnet uses a dedicated value-capped owner, while mainnet requires a distinct 2-of-3 Safe, followed by a ≥1-epoch timelock.

How this compares to the Bittensor field

The UR Subnet follows the Bittensor core almost everywhere and diverges only deliberately. Of the major design decisions, 12 are aligned with prevailing practice, 2 are divergent (reward settlement/custody and the worker‑payout trust model — both toward trustlessness), and 2 are genuinely novel bets: coupling miner reward to real, revenue‑backed demand (implied_usage × quality) and tiering miners into a trust‑minimized pooled tail plus a directly‑paid head.

Full analysis, per‑theme and per‑subnet, is in COMPARISON.md.

Participate

Register a network operator

Register a network‑operator key, then run the /verify server and deposit α. See the provider/operator documentation at https://ur.xyz. Operators register a client_id with the subnet used for root contracts, so they can independently audit their contracts. In the launch phase, operator admission is owner‑gated.

Each epoch, an NO commits the Merkle payout root that splits its pool among its providers. It directs the split; the immutable vault holds and pays.

Register a provider (ingress or egress)

Follow the provider documentation at https://ur.xyz. Providers work with network operators — the default list of operators in the code is a good place to start, and you can add more with -no <domain> (repeatable) or -nofile <path> (one operator domain per line).

Providers register a client_id with the subnet, and are paid inside their NO's pool by Merkle claim against that NO's payout root. A provider whose routable‑IP breadth ranks among the network's top ~200 fleets can claim its own top‑level miner UID and be paid directly by validator emission steering — no pool, no operator in the payout path. It links its client_ids to its wallet/hotkey with a dual‑signed binding so validators can attribute its measured breadth to that slot. See WHITEPAPER.md §8.4 and §11.4.

Register a validator

Validators stake their own α, run the VALIDATOR.md routing‑verification protocol (walking provider chains to measure quality and routable‑IP breadth), and each tempo score both miner tiers under commit‑reveal — the pools by implied_usage × quality and the head by routable‑IP breadth. Validators earn Bittensor‑native dividends (∝ stake × scoring accuracy) — v1's only validator reward. No NO owns a validator; the set is permissionless and Bittensor‑native.

The epoch lifecycle (a block is the 7‑day settlement epoch, ≈ 50 400 chain blocks):

When	What
`t = 0`	A keeper calls `closeOperatorEpoch`; the vault captures that NO's pool emission at the boundary.
`t ≤ +4h`	Each NO commits its payout‑list root for the epoch.
`t < +48h`	Audit window — committed roots and content-addressed payout artifacts are public and reproducible.
`+48h`	`finalizeOperatorEpoch`: the vault fixes the per‑NO entitlement and claims open.

Top‑level miners need no settlement — Yuma pays their UID natively each tempo.

One mechanism, two scoring channels

Release 1.0 fixes mechanism_count = 1. Pool UIDs and direct head UIDs share one native weight vector; validators normalize the head to θ and the pool tail to 1−θ before CRv4 commit. A second sub-mechanism is explicitly out of scope because it would partition the finite UID budget and undermine the intended ~200-member head.

Repository layout

Path	What
`WHITEPAPER.md`	The full subnet specification.
`VALIDATOR.md`	The off‑chain routing‑verification (`/verify`) protocol.
`COMPARISON.md`	Design‑decision comparison versus the Bittensor field.
`diagrams/`	The diagrams above (SVG sources + generators).
`evm/`	Reserve sink, settlement vault, UUPS coordinator, tests, and generated artifacts.
`validator/`	The validator binary.
`miner/`, `cli/`	Release miner/operator tooling.
`stctl/`	Explicitly quarantined pre-1.0 monolith diagnostic; not a release write path.
`crv4/`, `merkle/`, `ss58/`, `stabi/`	Supporting libraries (commit‑reveal v4, Merkle trees, address encoding, contract bindings).
`sim-testnet/`	Spend-capped Go harness for testnet setup, launch, scenarios, evidence, and analysis.

UR Subnet

A Bittensor subnet for a decentralized privacy network.

This repository (sn) is the reference implementation of the UR Subnet — the EVM contract suite, miner and validator software, chain tooling, and the real-testnet integration harness. The operator/API implementation lives in the sibling server repository.

Network Operators run the servers. Independent providers carry ingress/egress traffic. Independent validators run the VALIDATOR.md routing‑verification protocol — walking server‑assigned chains of providers to prove real‑time transit and measure which providers are the weakest links. Bittensor's Yuma Consensus turns that measurement into emission. Everything is denominated in the subnet's native token — α, branded $UR.

The full specification is in WHITEPAPER.md; the design rationale versus the rest of the Bittensor field is in COMPARISON.md.

Mechanism at a glance

Money flows in three coupled channels, all in α:

Deposits — the demand signal, conviction stake, and a buyback. Each NO deposits α through the coordinator, sized to its real usage at an off‑chain published rate (no on‑chain oracle). Deposits are the costly signal of real demand — and they are never distributed: every exact deposit is transferred into the immutable STReserveSink and staked on the fixed reserve hotkey (compounding dividends, with no outbound bytecode). A NO's cumulative locked α (its conviction) sets its tier → rate: zero conviction pays the baseline rate; more conviction lowers it — the onboarding and alignment lever.
Emission (Yuma Consensus). The Bittensor coinbase pays the standard 18% owner / 41% miner / 41% validator α split. Each tempo (~72 min), independent validators score both miner tiers from their own trails, submit weights under commit‑reveal, and Yuma's stake‑weighted median + clipping + vtrust turns those scores into miner emission — so the validators' evaluation is what moves the money. Validator emission flows natively (∝ stake × vtrust).
Settlement (7‑day epoch). Over each epoch the immutable settlement vault captures pool miner emission and providers claim their α directly from the vault with cryptographic proofs. A NO directs where its pool's rewards go but never holds anyone else's funds.

Two miner tiers, in parallel

Because one NO may serve 100k+ providers — far beyond a subnet's ~256 UID cap — the miner side runs two tiers inside one mechanism, divided by a governance share θ:

Pool tier (tail, 1−θ) — the on‑ramp. Each NO is a single vault‑owned pool UID; validators weight it implied_usage × quality (implied usage = the NO's deposit ÷ its tier rate). Its providers are not UIDs — they are paid inside the pool by Merkle claim. Low provider barrier (join a NO; the provider needs no UID or burn because the immutable vault owns one shared, burn-registered pool UID per NO), baseline reward.
Top‑level miners (head, θ) — the supply apex. The top ~200 fleets by split‑adjusted distinct routable egress‑IP count (real VPN supply breadth, not traffic volume) each claim their own miner UID, are steered directly by validators, and are paid natively to their own hotkey — no contract custody, no Merkle claim, no operator in the payout path. A fleet is matched to its UID by a dual‑signed client_ids ⇄ hotkey binding.

A provider starts in a pool, graduates to a top slot as its routable‑IP breadth grows, and falls back if it slips — with Bittensor's native deregistration churn running that tournament. A client_id earns in exactly one tier at a time (no double‑pay). Start tail‑weighted (θ ≈ 0.3) and widen it as the top‑miner set and validator consensus mature.

Custody and trust model

No operator custody. The owner and NOs never hold or distribute anyone else's α. The immutable vault is the sole custodian of in‑transit pool emission; every payout is a direct on‑chain pull claim; the head is paid natively.
Finalized claims are sacrosanct from day one — no upgrade, pause, or admin action can block or claw back a finalized claim.
The buyback reserve is one‑way — no contract function ever sources a transfer out of it.
Split governance.STReserveSink and STSettlementVault are non-upgradeable from launch. Only STCoordinator is UUPS-upgradeable: testnet uses a dedicated value-capped owner, while mainnet requires a distinct 2-of-3 Safe, followed by a ≥1-epoch timelock.

How this compares to the Bittensor field

The UR Subnet follows the Bittensor core almost everywhere and diverges only deliberately. Of the major design decisions, 12 are aligned with prevailing practice, 2 are divergent (reward settlement/custody and the worker‑payout trust model — both toward trustlessness), and 2 are genuinely novel bets: coupling miner reward to real, revenue‑backed demand (implied_usage × quality) and tiering miners into a trust‑minimized pooled tail plus a directly‑paid head.

Full analysis, per‑theme and per‑subnet, is in COMPARISON.md.

Participate

Register a network operator

Register a network‑operator key, then run the /verify server and deposit α. See the provider/operator documentation at https://ur.xyz. Operators register a client_id with the subnet used for root contracts, so they can independently audit their contracts. In the launch phase, operator admission is owner‑gated.

Each epoch, an NO commits the Merkle payout root that splits its pool among its providers. It directs the split; the immutable vault holds and pays.

Register a provider (ingress or egress)

Follow the provider documentation at https://ur.xyz. Providers work with network operators — the default list of operators in the code is a good place to start, and you can add more with -no <domain> (repeatable) or -nofile <path> (one operator domain per line).

Providers register a client_id with the subnet, and are paid inside their NO's pool by Merkle claim against that NO's payout root. A provider whose routable‑IP breadth ranks among the network's top ~200 fleets can claim its own top‑level miner UID and be paid directly by validator emission steering — no pool, no operator in the payout path. It links its client_ids to its wallet/hotkey with a dual‑signed binding so validators can attribute its measured breadth to that slot. See WHITEPAPER.md §8.4 and §11.4.

Register a validator

Validators stake their own α, run the VALIDATOR.md routing‑verification protocol (walking provider chains to measure quality and routable‑IP breadth), and each tempo score both miner tiers under commit‑reveal — the pools by implied_usage × quality and the head by routable‑IP breadth. Validators earn Bittensor‑native dividends (∝ stake × scoring accuracy) — v1's only validator reward. No NO owns a validator; the set is permissionless and Bittensor‑native.

The epoch lifecycle (a block is the 7‑day settlement epoch, ≈ 50 400 chain blocks):

When	What
`t = 0`	A keeper calls `closeOperatorEpoch`; the vault captures that NO's pool emission at the boundary.
`t ≤ +4h`	Each NO commits its payout‑list root for the epoch.
`t < +48h`	Audit window — committed roots and content-addressed payout artifacts are public and reproducible.
`+48h`	`finalizeOperatorEpoch`: the vault fixes the per‑NO entitlement and claims open.

Top‑level miners need no settlement — Yuma pays their UID natively each tempo.

One mechanism, two scoring channels

Release 1.0 fixes mechanism_count = 1. Pool UIDs and direct head UIDs share one native weight vector; validators normalize the head to θ and the pool tail to 1−θ before CRv4 commit. A second sub-mechanism is explicitly out of scope because it would partition the finite UID budget and undermine the intended ~200-member head.

Repository layout

Path	What
`WHITEPAPER.md`	The full subnet specification.
`VALIDATOR.md`	The off‑chain routing‑verification (`/verify`) protocol.
`COMPARISON.md`	Design‑decision comparison versus the Bittensor field.
`diagrams/`	The diagrams above (SVG sources + generators).
`evm/`	Reserve sink, settlement vault, UUPS coordinator, tests, and generated artifacts.
`validator/`	The validator binary.
`miner/`, `cli/`	Release miner/operator tooling.
`stctl/`	Explicitly quarantined pre-1.0 monolith diagnostic; not a release write path.
`crv4/`, `merkle/`, `ss58/`, `stabi/`	Supporting libraries (commit‑reveal v4, Merkle trees, address encoding, contract bindings).
`sim-testnet/`	Spend-capped Go harness for testnet setup, launch, scenarios, evidence, and analysis.

UR Subnet

A Bittensor subnet for a decentralized privacy network.

This repository (sn) is the reference implementation of the UR Subnet — the EVM contract suite, miner and validator software, chain tooling, and the real-testnet integration harness. The operator/API implementation lives in the sibling server repository.

Network Operators run the servers. Independent providers carry ingress/egress traffic. Independent validators run the VALIDATOR.md routing‑verification protocol — walking server‑assigned chains of providers to prove real‑time transit and measure which providers are the weakest links. Bittensor's Yuma Consensus turns that measurement into emission. Everything is denominated in the subnet's native token — α, branded $UR.

The full specification is in WHITEPAPER.md; the design rationale versus the rest of the Bittensor field is in COMPARISON.md.

Mechanism at a glance

Money flows in three coupled channels, all in α:

Deposits — the demand signal, conviction stake, and a buyback. Each NO deposits α through the coordinator, sized to its real usage at an off‑chain published rate (no on‑chain oracle). Deposits are the costly signal of real demand — and they are never distributed: every exact deposit is transferred into the immutable STReserveSink and staked on the fixed reserve hotkey (compounding dividends, with no outbound bytecode). A NO's cumulative locked α (its conviction) sets its tier → rate: zero conviction pays the baseline rate; more conviction lowers it — the onboarding and alignment lever.
Emission (Yuma Consensus). The Bittensor coinbase pays the standard 18% owner / 41% miner / 41% validator α split. Each tempo (~72 min), independent validators score both miner tiers from their own trails, submit weights under commit‑reveal, and Yuma's stake‑weighted median + clipping + vtrust turns those scores into miner emission — so the validators' evaluation is what moves the money. Validator emission flows natively (∝ stake × vtrust).
Settlement (7‑day epoch). Over each epoch the immutable settlement vault captures pool miner emission and providers claim their α directly from the vault with cryptographic proofs. A NO directs where its pool's rewards go but never holds anyone else's funds.

Two miner tiers, in parallel

Because one NO may serve 100k+ providers — far beyond a subnet's ~256 UID cap — the miner side runs two tiers inside one mechanism, divided by a governance share θ:

Pool tier (tail, 1−θ) — the on‑ramp. Each NO is a single vault‑owned pool UID; validators weight it implied_usage × quality (implied usage = the NO's deposit ÷ its tier rate). Its providers are not UIDs — they are paid inside the pool by Merkle claim. Low provider barrier (join a NO; the provider needs no UID or burn because the immutable vault owns one shared, burn-registered pool UID per NO), baseline reward.
Top‑level miners (head, θ) — the supply apex. The top ~200 fleets by split‑adjusted distinct routable egress‑IP count (real VPN supply breadth, not traffic volume) each claim their own miner UID, are steered directly by validators, and are paid natively to their own hotkey — no contract custody, no Merkle claim, no operator in the payout path. A fleet is matched to its UID by a dual‑signed client_ids ⇄ hotkey binding.

A provider starts in a pool, graduates to a top slot as its routable‑IP breadth grows, and falls back if it slips — with Bittensor's native deregistration churn running that tournament. A client_id earns in exactly one tier at a time (no double‑pay). Start tail‑weighted (θ ≈ 0.3) and widen it as the top‑miner set and validator consensus mature.

Custody and trust model

No operator custody. The owner and NOs never hold or distribute anyone else's α. The immutable vault is the sole custodian of in‑transit pool emission; every payout is a direct on‑chain pull claim; the head is paid natively.
Finalized claims are sacrosanct from day one — no upgrade, pause, or admin action can block or claw back a finalized claim.
The buyback reserve is one‑way — no contract function ever sources a transfer out of it.
Split governance.STReserveSink and STSettlementVault are non-upgradeable from launch. Only STCoordinator is UUPS-upgradeable: testnet uses a dedicated value-capped owner, while mainnet requires a distinct 2-of-3 Safe, followed by a ≥1-epoch timelock.

How this compares to the Bittensor field

The UR Subnet follows the Bittensor core almost everywhere and diverges only deliberately. Of the major design decisions, 12 are aligned with prevailing practice, 2 are divergent (reward settlement/custody and the worker‑payout trust model — both toward trustlessness), and 2 are genuinely novel bets: coupling miner reward to real, revenue‑backed demand (implied_usage × quality) and tiering miners into a trust‑minimized pooled tail plus a directly‑paid head.

Full analysis, per‑theme and per‑subnet, is in COMPARISON.md.

Participate

Register a network operator

Register a network‑operator key, then run the /verify server and deposit α. See the provider/operator documentation at https://ur.xyz. Operators register a client_id with the subnet used for root contracts, so they can independently audit their contracts. In the launch phase, operator admission is owner‑gated.

Each epoch, an NO commits the Merkle payout root that splits its pool among its providers. It directs the split; the immutable vault holds and pays.

Register a provider (ingress or egress)

Follow the provider documentation at https://ur.xyz. Providers work with network operators — the default list of operators in the code is a good place to start, and you can add more with -no <domain> (repeatable) or -nofile <path> (one operator domain per line).

Providers register a client_id with the subnet, and are paid inside their NO's pool by Merkle claim against that NO's payout root. A provider whose routable‑IP breadth ranks among the network's top ~200 fleets can claim its own top‑level miner UID and be paid directly by validator emission steering — no pool, no operator in the payout path. It links its client_ids to its wallet/hotkey with a dual‑signed binding so validators can attribute its measured breadth to that slot. See WHITEPAPER.md §8.4 and §11.4.

Register a validator

Validators stake their own α, run the VALIDATOR.md routing‑verification protocol (walking provider chains to measure quality and routable‑IP breadth), and each tempo score both miner tiers under commit‑reveal — the pools by implied_usage × quality and the head by routable‑IP breadth. Validators earn Bittensor‑native dividends (∝ stake × scoring accuracy) — v1's only validator reward. No NO owns a validator; the set is permissionless and Bittensor‑native.

The epoch lifecycle (a block is the 7‑day settlement epoch, ≈ 50 400 chain blocks):

When	What
`t = 0`	A keeper calls `closeOperatorEpoch`; the vault captures that NO's pool emission at the boundary.
`t ≤ +4h`	Each NO commits its payout‑list root for the epoch.
`t < +48h`	Audit window — committed roots and content-addressed payout artifacts are public and reproducible.
`+48h`	`finalizeOperatorEpoch`: the vault fixes the per‑NO entitlement and claims open.

Top‑level miners need no settlement — Yuma pays their UID natively each tempo.

One mechanism, two scoring channels

Release 1.0 fixes mechanism_count = 1. Pool UIDs and direct head UIDs share one native weight vector; validators normalize the head to θ and the pool tail to 1−θ before CRv4 commit. A second sub-mechanism is explicitly out of scope because it would partition the finite UID budget and undermine the intended ~200-member head.

Repository layout

Path	What
`WHITEPAPER.md`	The full subnet specification.
`VALIDATOR.md`	The off‑chain routing‑verification (`/verify`) protocol.
`COMPARISON.md`	Design‑decision comparison versus the Bittensor field.
`diagrams/`	The diagrams above (SVG sources + generators).
`evm/`	Reserve sink, settlement vault, UUPS coordinator, tests, and generated artifacts.
`validator/`	The validator binary.
`miner/`, `cli/`	Release miner/operator tooling.
`stctl/`	Explicitly quarantined pre-1.0 monolith diagnostic; not a release write path.
`crv4/`, `merkle/`, `ss58/`, `stabi/`	Supporting libraries (commit‑reveal v4, Merkle trees, address encoding, contract bindings).
`sim-testnet/`	Spend-capped Go harness for testnet setup, launch, scenarios, evidence, and analysis.

UR Subnet

A Bittensor subnet for a decentralized privacy network.

This repository (sn) is the reference implementation of the UR Subnet — the EVM contract suite, miner and validator software, chain tooling, and the real-testnet integration harness. The operator/API implementation lives in the sibling server repository.

Network Operators run the servers. Independent providers carry ingress/egress traffic. Independent validators run the VALIDATOR.md routing‑verification protocol — walking server‑assigned chains of providers to prove real‑time transit and measure which providers are the weakest links. Bittensor's Yuma Consensus turns that measurement into emission. Everything is denominated in the subnet's native token — α, branded $UR.

The full specification is in WHITEPAPER.md; the design rationale versus the rest of the Bittensor field is in COMPARISON.md.

Mechanism at a glance

Money flows in three coupled channels, all in α:

Deposits — the demand signal, conviction stake, and a buyback. Each NO deposits α through the coordinator, sized to its real usage at an off‑chain published rate (no on‑chain oracle). Deposits are the costly signal of real demand — and they are never distributed: every exact deposit is transferred into the immutable STReserveSink and staked on the fixed reserve hotkey (compounding dividends, with no outbound bytecode). A NO's cumulative locked α (its conviction) sets its tier → rate: zero conviction pays the baseline rate; more conviction lowers it — the onboarding and alignment lever.
Emission (Yuma Consensus). The Bittensor coinbase pays the standard 18% owner / 41% miner / 41% validator α split. Each tempo (~72 min), independent validators score both miner tiers from their own trails, submit weights under commit‑reveal, and Yuma's stake‑weighted median + clipping + vtrust turns those scores into miner emission — so the validators' evaluation is what moves the money. Validator emission flows natively (∝ stake × vtrust).
Settlement (7‑day epoch). Over each epoch the immutable settlement vault captures pool miner emission and providers claim their α directly from the vault with cryptographic proofs. A NO directs where its pool's rewards go but never holds anyone else's funds.

Two miner tiers, in parallel

Because one NO may serve 100k+ providers — far beyond a subnet's ~256 UID cap — the miner side runs two tiers inside one mechanism, divided by a governance share θ:

Pool tier (tail, 1−θ) — the on‑ramp. Each NO is a single vault‑owned pool UID; validators weight it implied_usage × quality (implied usage = the NO's deposit ÷ its tier rate). Its providers are not UIDs — they are paid inside the pool by Merkle claim. Low provider barrier (join a NO; the provider needs no UID or burn because the immutable vault owns one shared, burn-registered pool UID per NO), baseline reward.
Top‑level miners (head, θ) — the supply apex. The top ~200 fleets by split‑adjusted distinct routable egress‑IP count (real VPN supply breadth, not traffic volume) each claim their own miner UID, are steered directly by validators, and are paid natively to their own hotkey — no contract custody, no Merkle claim, no operator in the payout path. A fleet is matched to its UID by a dual‑signed client_ids ⇄ hotkey binding.

A provider starts in a pool, graduates to a top slot as its routable‑IP breadth grows, and falls back if it slips — with Bittensor's native deregistration churn running that tournament. A client_id earns in exactly one tier at a time (no double‑pay). Start tail‑weighted (θ ≈ 0.3) and widen it as the top‑miner set and validator consensus mature.

Custody and trust model

No operator custody. The owner and NOs never hold or distribute anyone else's α. The immutable vault is the sole custodian of in‑transit pool emission; every payout is a direct on‑chain pull claim; the head is paid natively.
Finalized claims are sacrosanct from day one — no upgrade, pause, or admin action can block or claw back a finalized claim.
The buyback reserve is one‑way — no contract function ever sources a transfer out of it.
Split governance.STReserveSink and STSettlementVault are non-upgradeable from launch. Only STCoordinator is UUPS-upgradeable: testnet uses a dedicated value-capped owner, while mainnet requires a distinct 2-of-3 Safe, followed by a ≥1-epoch timelock.

How this compares to the Bittensor field

The UR Subnet follows the Bittensor core almost everywhere and diverges only deliberately. Of the major design decisions, 12 are aligned with prevailing practice, 2 are divergent (reward settlement/custody and the worker‑payout trust model — both toward trustlessness), and 2 are genuinely novel bets: coupling miner reward to real, revenue‑backed demand (implied_usage × quality) and tiering miners into a trust‑minimized pooled tail plus a directly‑paid head.

Full analysis, per‑theme and per‑subnet, is in COMPARISON.md.

Participate

Register a network operator

Register a network‑operator key, then run the /verify server and deposit α. See the provider/operator documentation at https://ur.xyz. Operators register a client_id with the subnet used for root contracts, so they can independently audit their contracts. In the launch phase, operator admission is owner‑gated.

Each epoch, an NO commits the Merkle payout root that splits its pool among its providers. It directs the split; the immutable vault holds and pays.

Register a provider (ingress or egress)

Follow the provider documentation at https://ur.xyz. Providers work with network operators — the default list of operators in the code is a good place to start, and you can add more with -no <domain> (repeatable) or -nofile <path> (one operator domain per line).

Providers register a client_id with the subnet, and are paid inside their NO's pool by Merkle claim against that NO's payout root. A provider whose routable‑IP breadth ranks among the network's top ~200 fleets can claim its own top‑level miner UID and be paid directly by validator emission steering — no pool, no operator in the payout path. It links its client_ids to its wallet/hotkey with a dual‑signed binding so validators can attribute its measured breadth to that slot. See WHITEPAPER.md §8.4 and §11.4.

Register a validator

Validators stake their own α, run the VALIDATOR.md routing‑verification protocol (walking provider chains to measure quality and routable‑IP breadth), and each tempo score both miner tiers under commit‑reveal — the pools by implied_usage × quality and the head by routable‑IP breadth. Validators earn Bittensor‑native dividends (∝ stake × scoring accuracy) — v1's only validator reward. No NO owns a validator; the set is permissionless and Bittensor‑native.

The epoch lifecycle (a block is the 7‑day settlement epoch, ≈ 50 400 chain blocks):

When	What
`t = 0`	A keeper calls `closeOperatorEpoch`; the vault captures that NO's pool emission at the boundary.
`t ≤ +4h`	Each NO commits its payout‑list root for the epoch.
`t < +48h`	Audit window — committed roots and content-addressed payout artifacts are public and reproducible.
`+48h`	`finalizeOperatorEpoch`: the vault fixes the per‑NO entitlement and claims open.

Top‑level miners need no settlement — Yuma pays their UID natively each tempo.

One mechanism, two scoring channels

Release 1.0 fixes mechanism_count = 1. Pool UIDs and direct head UIDs share one native weight vector; validators normalize the head to θ and the pool tail to 1−θ before CRv4 commit. A second sub-mechanism is explicitly out of scope because it would partition the finite UID budget and undermine the intended ~200-member head.

Repository layout

Path	What
`WHITEPAPER.md`	The full subnet specification.
`VALIDATOR.md`	The off‑chain routing‑verification (`/verify`) protocol.
`COMPARISON.md`	Design‑decision comparison versus the Bittensor field.
`diagrams/`	The diagrams above (SVG sources + generators).
`evm/`	Reserve sink, settlement vault, UUPS coordinator, tests, and generated artifacts.
`validator/`	The validator binary.
`miner/`, `cli/`	Release miner/operator tooling.
`stctl/`	Explicitly quarantined pre-1.0 monolith diagnostic; not a release write path.
`crv4/`, `merkle/`, `ss58/`, `stabi/`	Supporting libraries (commit‑reveal v4, Merkle trees, address encoding, contract bindings).
`sim-testnet/`	Spend-capped Go harness for testnet setup, launch, scenarios, evidence, and analysis.

UR Subnet

A Bittensor subnet for a decentralized privacy network.

This repository (sn) is the reference implementation of the UR Subnet — the EVM contract suite, miner and validator software, chain tooling, and the real-testnet integration harness. The operator/API implementation lives in the sibling server repository.

Network Operators run the servers. Independent providers carry ingress/egress traffic. Independent validators run the VALIDATOR.md routing‑verification protocol — walking server‑assigned chains of providers to prove real‑time transit and measure which providers are the weakest links. Bittensor's Yuma Consensus turns that measurement into emission. Everything is denominated in the subnet's native token — α, branded $UR.

The full specification is in WHITEPAPER.md; the design rationale versus the rest of the Bittensor field is in COMPARISON.md.

Mechanism at a glance

Money flows in three coupled channels, all in α:

Deposits — the demand signal, conviction stake, and a buyback. Each NO deposits α through the coordinator, sized to its real usage at an off‑chain published rate (no on‑chain oracle). Deposits are the costly signal of real demand — and they are never distributed: every exact deposit is transferred into the immutable STReserveSink and staked on the fixed reserve hotkey (compounding dividends, with no outbound bytecode). A NO's cumulative locked α (its conviction) sets its tier → rate: zero conviction pays the baseline rate; more conviction lowers it — the onboarding and alignment lever.
Emission (Yuma Consensus). The Bittensor coinbase pays the standard 18% owner / 41% miner / 41% validator α split. Each tempo (~72 min), independent validators score both miner tiers from their own trails, submit weights under commit‑reveal, and Yuma's stake‑weighted median + clipping + vtrust turns those scores into miner emission — so the validators' evaluation is what moves the money. Validator emission flows natively (∝ stake × vtrust).
Settlement (7‑day epoch). Over each epoch the immutable settlement vault captures pool miner emission and providers claim their α directly from the vault with cryptographic proofs. A NO directs where its pool's rewards go but never holds anyone else's funds.

Two miner tiers, in parallel

Because one NO may serve 100k+ providers — far beyond a subnet's ~256 UID cap — the miner side runs two tiers inside one mechanism, divided by a governance share θ:

Pool tier (tail, 1−θ) — the on‑ramp. Each NO is a single vault‑owned pool UID; validators weight it implied_usage × quality (implied usage = the NO's deposit ÷ its tier rate). Its providers are not UIDs — they are paid inside the pool by Merkle claim. Low provider barrier (join a NO; the provider needs no UID or burn because the immutable vault owns one shared, burn-registered pool UID per NO), baseline reward.
Top‑level miners (head, θ) — the supply apex. The top ~200 fleets by split‑adjusted distinct routable egress‑IP count (real VPN supply breadth, not traffic volume) each claim their own miner UID, are steered directly by validators, and are paid natively to their own hotkey — no contract custody, no Merkle claim, no operator in the payout path. A fleet is matched to its UID by a dual‑signed client_ids ⇄ hotkey binding.

A provider starts in a pool, graduates to a top slot as its routable‑IP breadth grows, and falls back if it slips — with Bittensor's native deregistration churn running that tournament. A client_id earns in exactly one tier at a time (no double‑pay). Start tail‑weighted (θ ≈ 0.3) and widen it as the top‑miner set and validator consensus mature.

Custody and trust model

No operator custody. The owner and NOs never hold or distribute anyone else's α. The immutable vault is the sole custodian of in‑transit pool emission; every payout is a direct on‑chain pull claim; the head is paid natively.
Finalized claims are sacrosanct from day one — no upgrade, pause, or admin action can block or claw back a finalized claim.
The buyback reserve is one‑way — no contract function ever sources a transfer out of it.
Split governance.STReserveSink and STSettlementVault are non-upgradeable from launch. Only STCoordinator is UUPS-upgradeable: testnet uses a dedicated value-capped owner, while mainnet requires a distinct 2-of-3 Safe, followed by a ≥1-epoch timelock.

How this compares to the Bittensor field

The UR Subnet follows the Bittensor core almost everywhere and diverges only deliberately. Of the major design decisions, 12 are aligned with prevailing practice, 2 are divergent (reward settlement/custody and the worker‑payout trust model — both toward trustlessness), and 2 are genuinely novel bets: coupling miner reward to real, revenue‑backed demand (implied_usage × quality) and tiering miners into a trust‑minimized pooled tail plus a directly‑paid head.

Full analysis, per‑theme and per‑subnet, is in COMPARISON.md.

Participate

Register a network operator

Register a network‑operator key, then run the /verify server and deposit α. See the provider/operator documentation at https://ur.xyz. Operators register a client_id with the subnet used for root contracts, so they can independently audit their contracts. In the launch phase, operator admission is owner‑gated.

Each epoch, an NO commits the Merkle payout root that splits its pool among its providers. It directs the split; the immutable vault holds and pays.

Register a provider (ingress or egress)

Follow the provider documentation at https://ur.xyz. Providers work with network operators — the default list of operators in the code is a good place to start, and you can add more with -no <domain> (repeatable) or -nofile <path> (one operator domain per line).

Providers register a client_id with the subnet, and are paid inside their NO's pool by Merkle claim against that NO's payout root. A provider whose routable‑IP breadth ranks among the network's top ~200 fleets can claim its own top‑level miner UID and be paid directly by validator emission steering — no pool, no operator in the payout path. It links its client_ids to its wallet/hotkey with a dual‑signed binding so validators can attribute its measured breadth to that slot. See WHITEPAPER.md §8.4 and §11.4.

Register a validator

Validators stake their own α, run the VALIDATOR.md routing‑verification protocol (walking provider chains to measure quality and routable‑IP breadth), and each tempo score both miner tiers under commit‑reveal — the pools by implied_usage × quality and the head by routable‑IP breadth. Validators earn Bittensor‑native dividends (∝ stake × scoring accuracy) — v1's only validator reward. No NO owns a validator; the set is permissionless and Bittensor‑native.

The epoch lifecycle (a block is the 7‑day settlement epoch, ≈ 50 400 chain blocks):

When	What
`t = 0`	A keeper calls `closeOperatorEpoch`; the vault captures that NO's pool emission at the boundary.
`t ≤ +4h`	Each NO commits its payout‑list root for the epoch.
`t < +48h`	Audit window — committed roots and content-addressed payout artifacts are public and reproducible.
`+48h`	`finalizeOperatorEpoch`: the vault fixes the per‑NO entitlement and claims open.

Top‑level miners need no settlement — Yuma pays their UID natively each tempo.

One mechanism, two scoring channels

Release 1.0 fixes mechanism_count = 1. Pool UIDs and direct head UIDs share one native weight vector; validators normalize the head to θ and the pool tail to 1−θ before CRv4 commit. A second sub-mechanism is explicitly out of scope because it would partition the finite UID budget and undermine the intended ~200-member head.

Repository layout

Path	What
`WHITEPAPER.md`	The full subnet specification.
`VALIDATOR.md`	The off‑chain routing‑verification (`/verify`) protocol.
`COMPARISON.md`	Design‑decision comparison versus the Bittensor field.
`diagrams/`	The diagrams above (SVG sources + generators).
`evm/`	Reserve sink, settlement vault, UUPS coordinator, tests, and generated artifacts.
`validator/`	The validator binary.
`miner/`, `cli/`	Release miner/operator tooling.
`stctl/`	Explicitly quarantined pre-1.0 monolith diagnostic; not a release write path.
`crv4/`, `merkle/`, `ss58/`, `stabi/`	Supporting libraries (commit‑reveal v4, Merkle trees, address encoding, contract bindings).
`sim-testnet/`	Spend-capped Go harness for testnet setup, launch, scenarios, evidence, and analysis.

Name		Name	Last commit message	Last commit date
api		api
cli		cli
clientauth		clientauth
cmd/sp2		cmd/sp2
crv4		crv4
deploy/testnet		deploy/testnet
diagrams		diagrams
docs		docs
evm		evm
iterations		iterations
merkle		merkle
miner		miner
payoutartifact		payoutartifact
protocol		protocol
scripts		scripts
seed		seed
sim-testnet		sim-testnet
ss58		ss58
stabi		stabi
stctl		stctl
third_party/npipe		third_party/npipe
validator		validator
.gitignore		.gitignore
COMPARISON.md		COMPARISON.md
FINALIZE.md		FINALIZE.md
IMPLEMENTATION_STATUS.md		IMPLEMENTATION_STATUS.md
PLAN.md		PLAN.md
PROJECTION.md		PROJECTION.md
README.md		README.md
VALIDATOR.md		VALIDATOR.md
WHITEPAPER.md		WHITEPAPER.md
WHITEPAPER_DISCUSS.md		WHITEPAPER_DISCUSS.md
build.sh		build.sh
go.mod		go.mod
go.sum		go.sum
price.yml		price.yml

Name		Name	Last commit message	Last commit date
api		api
cli		cli
clientauth		clientauth
cmd/sp2		cmd/sp2
crv4		crv4
deploy/testnet		deploy/testnet
diagrams		diagrams
docs		docs
evm		evm
iterations		iterations
merkle		merkle
miner		miner
payoutartifact		payoutartifact
protocol		protocol
scripts		scripts
seed		seed
sim-testnet		sim-testnet
ss58		ss58
stabi		stabi
stctl		stctl
third_party/npipe		third_party/npipe
validator		validator
.gitignore		.gitignore
COMPARISON.md		COMPARISON.md
FINALIZE.md		FINALIZE.md
IMPLEMENTATION_STATUS.md		IMPLEMENTATION_STATUS.md
PLAN.md		PLAN.md
PROJECTION.md		PROJECTION.md
README.md		README.md
VALIDATOR.md		VALIDATOR.md
WHITEPAPER.md		WHITEPAPER.md
WHITEPAPER_DISCUSS.md		WHITEPAPER_DISCUSS.md
build.sh		build.sh
go.mod		go.mod
go.sum		go.sum
price.yml		price.yml

Name		Name	Last commit message	Last commit date
api		api
cli		cli
clientauth		clientauth
cmd/sp2		cmd/sp2
crv4		crv4
deploy/testnet		deploy/testnet
diagrams		diagrams
docs		docs
evm		evm
iterations		iterations
merkle		merkle
miner		miner
payoutartifact		payoutartifact
protocol		protocol
scripts		scripts
seed		seed
sim-testnet		sim-testnet
ss58		ss58
stabi		stabi
stctl		stctl
third_party/npipe		third_party/npipe
validator		validator
.gitignore		.gitignore
COMPARISON.md		COMPARISON.md
FINALIZE.md		FINALIZE.md
IMPLEMENTATION_STATUS.md		IMPLEMENTATION_STATUS.md
PLAN.md		PLAN.md
PROJECTION.md		PROJECTION.md
README.md		README.md
VALIDATOR.md		VALIDATOR.md
WHITEPAPER.md		WHITEPAPER.md
WHITEPAPER_DISCUSS.md		WHITEPAPER_DISCUSS.md
build.sh		build.sh
go.mod		go.mod
go.sum		go.sum
price.yml		price.yml

Name		Name	Last commit message	Last commit date
api		api
cli		cli
clientauth		clientauth
cmd/sp2		cmd/sp2
crv4		crv4
deploy/testnet		deploy/testnet
diagrams		diagrams
docs		docs
evm		evm
iterations		iterations
merkle		merkle
miner		miner
payoutartifact		payoutartifact
protocol		protocol
scripts		scripts
seed		seed
sim-testnet		sim-testnet
ss58		ss58
stabi		stabi
stctl		stctl
third_party/npipe		third_party/npipe
validator		validator
.gitignore		.gitignore
COMPARISON.md		COMPARISON.md
FINALIZE.md		FINALIZE.md
IMPLEMENTATION_STATUS.md		IMPLEMENTATION_STATUS.md
PLAN.md		PLAN.md
PROJECTION.md		PROJECTION.md
README.md		README.md
VALIDATOR.md		VALIDATOR.md
WHITEPAPER.md		WHITEPAPER.md
WHITEPAPER_DISCUSS.md		WHITEPAPER_DISCUSS.md
build.sh		build.sh
go.mod		go.mod
go.sum		go.sum
price.yml		price.yml

Name		Name	Last commit message	Last commit date
api		api
cli		cli
clientauth		clientauth
cmd/sp2		cmd/sp2
crv4		crv4
deploy/testnet		deploy/testnet
diagrams		diagrams
docs		docs
evm		evm
iterations		iterations
merkle		merkle
miner		miner
payoutartifact		payoutartifact
protocol		protocol
scripts		scripts
seed		seed
sim-testnet		sim-testnet
ss58		ss58
stabi		stabi
stctl		stctl
third_party/npipe		third_party/npipe
validator		validator
.gitignore		.gitignore
COMPARISON.md		COMPARISON.md
FINALIZE.md		FINALIZE.md
IMPLEMENTATION_STATUS.md		IMPLEMENTATION_STATUS.md
PLAN.md		PLAN.md
PROJECTION.md		PROJECTION.md
README.md		README.md
VALIDATOR.md		VALIDATOR.md
WHITEPAPER.md		WHITEPAPER.md
WHITEPAPER_DISCUSS.md		WHITEPAPER_DISCUSS.md
build.sh		build.sh
go.mod		go.mod
go.sum		go.sum
price.yml		price.yml

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

UR Subnet

Mechanism at a glance

Two miner tiers, in parallel

Custody and trust model

How this compares to the Bittensor field

Participate

Register a network operator

Register a provider (ingress or egress)

Register a validator

One mechanism, two scoring channels

Repository layout

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

UR Subnet

Mechanism at a glance

Two miner tiers, in parallel

Custody and trust model

How this compares to the Bittensor field

Participate

Register a network operator

Register a provider (ingress or egress)

Register a validator

One mechanism, two scoring channels

Repository layout

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

UR Subnet

Mechanism at a glance

Two miner tiers, in parallel

Custody and trust model

How this compares to the Bittensor field

Participate

Register a network operator

Register a provider (ingress or egress)

Register a validator

One mechanism, two scoring channels

Repository layout

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Uh oh!

Latest commit

History

Folders and files

Repository files navigation