UR

# 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; provider probing, tunnel confinement, geolocation, bandwidth, and
egress-health tooling live in the sibling `operator-proxy` repository.

**Network Operators** run the servers. Independent **providers** carry ingress/egress
traffic. Independent **validators** run the [`VALIDATOR.md`](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`](WHITEPAPER.md); the design rationale versus
the rest of the Bittensor field is in [`COMPARISON.md`](COMPARISON.md).

---

## Mechanism at a glance

![UR Subnet — mechanism at a glance](diagrams/mechanism.png)

Money flows in three coupled channels, all in α:

1. **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.

2. **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).

3. **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_id`s ⇄ 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.

![UR Subnet vs. the Bittensor norm — design‑decision alignment matrix](diagrams/comparison_matrix.png)

Full analysis, per‑theme and per‑subnet, is in [`COMPARISON.md`](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 own