Transit Fabric releases

Taken from the Transit Fabric source repository at commit 91be12e (91be12ef98b775c7f045124e6b8c686c15439650, main), file docs/specs/capacity-bonds.md. Links into the private source tree are shown as plain text. Raw Markdown · Red-team pack

Spec: capacity bonds

Status: draft · Implemented in crates/bwos-core/src/scoring/mod.rs · See ADR-0006

Bittensor has no native slashing for subnet-defined behavior. v0 therefore uses a reputation bond: the operator's future emissions are what's at risk. v1 may add an escrow contract on Bittensor EVM (OQ-2).

Declaration

Operators commit a capacity declaration on chain (hash) and serve the object:

{"v":0,"hotkey":"<ss58>","netuid":<int>,"window_from":<int>,"nodes":[{"node":"<pubkey hex>","mbps":3000,"cost_ppm":800000}],"hotkey_sig":"<hex>"}

A declaration has 1..=MAX_DECLARATION_NODES entries (MAX_DECLARATION_NODES = 1024), sorted and unique by node, and is signed with hotkey_sig. Each node entry may optionally declare cost_ppm, which must be in [MIN_COST_PPM = 200_000, MAX_COST_PPM = 2_000_000]; the default is 1_000_000 ppm = 1.00x (ADR-0018). An operator's declared cost_ppm sets its base hop transit cost for Mechanism 1 solvers AND scales its Mechanism 0 billable volume V_bill by cost_ppm / 1_000_000, so discounting cost_ppm attracts least-cost and low_latency_hd routes in exchange for a proportional per-byte rate discount.

Changes are judged field by field (ADR-0018 §3, can_update_declaration, TV-16):

Whether to allow immediate cost decreases that restart the raise clock is OQ-54; the current answer is no, because ADR-0018 stands.

Where the cooldown is enforced ([T56], PB-31)

validator::run_tempo never scores the raw TempoInput::declarations. It scores each node's declaration as it stands in the current cooldown epoch: the windows [k * CAP_CHANGE_WINDOWS, (k + 1) * CAP_CHANGE_WINDOWS) (validator::DeclarationEpoch, tempo_declaration_epoch).

What one read counts (validator::node_declarations). A declaration counts from the window after the chain commitment that names it. The validator reads the UID's on-chain commitment at block w * tempo - 1, the last block before window w, and the declaration it names counts from window w. Of that read, an entry counts only if all of these hold:

A declaration signed by any other hotkey, or an entry for a node bound to another UID, is ignored. It neither changes nor resets anything, and nobody can set a rival node's cost.

Per-node epoch state. State is kept per node, whichever UID the node is bound to:

So every cost_ppm change and every mbps raise takes effect at the next epoch boundary: changes in force are at least CAP_CHANGE_WINDOWS windows apart. A raise committed just before a boundary applies sooner than 24 windows after the previous change committed, but never sooner than 24 windows after the previous change took effect.

Billing at the solved-on cost (validator::billing_cost_ppm, run_tempo step 5). The production table for window W was solved on the snapshot built at W - 1, whose links were priced with each node's epoch cost at W - 1 (TempoOutcome::next_snapshot_costs, passed back with the snapshot as TempoInput::current_snapshot_costs) (pass Some even when the map is empty; None means billing at the epoch cost). Mechanism 0 bills each node's paid and free bytes at

min(epoch cost at W, cost in the solved-on snapshot)    (a node missing from the solved-on costs: 1_000_000)

So routes chosen at an old price are never billed at a higher one. That includes a raise at an epoch boundary, a withdrawal at a boundary, and a re-keyed node (sims epoch_boundary_raise: 0 mis-priced windows; rekey_mid_epoch: at most 1.0x the solved-on cost). A decrease is billed at once. When current_snapshot_costs is None (not supplied), the epoch cost is billed.

Determinism. The epoch state is a pure function of the chain reads from the epoch's first window, at most CAP_CHANGE_WINDOWS reads (the documented lookback bound). It has no other history, so every validator agrees whatever its local history:

Since Task 19b the declaration is named through the commitment manifest (ADR-0036): the manifest's capacity-declaration slot holds its hash, read at block w * tempo - 1 from manifests that cover w (identity.md §Commitment manifest). The domain is active from window 0 on local and test only; its mainnet activation is OQ-45. A UID's manifest lapses after two windows (covers), and its declaration with it, so operators re-commit at least every other window (OQ-210).

Verified capacity per node

measured  = lower median of achieved Mbps across capacity tests in the last CAP_PENALTY_WINDOWS windows
peak      = max(declared, declared Mbps of this node in each of the last CAP_PENALTY_WINDOWS windows)
if no tests yet:                verified = 0
elif measured >= declared:      verified = declared
elif measured >= declared * (1e6 - CAP_TOLERANCE_PPM)/1e6:
                                verified = measured
else:                           verified = measured * (1e6 - OVERCLAIM_PENALTY_PPM)/1e6
if measured < peak * (1e6 - CAP_TOLERANCE_PPM)/1e6:
                                verified = min(verified, measured * (1e6 - OVERCLAIM_PENALTY_PPM)/1e6)

Team tests and the ramp (ADR-0039, Phase B Task 4Dc). Once team tests replace single-agent tests, the rule above is replaced by the one below. A team test pushes the ramped rate, capped at the team's budgets (measurement.md §Team capacity tests), not the declaration. So comparing with the declaration would haircut every honest node while its ramp climbs, and every node faster than the team can push. Each test is therefore recorded as (team_t, pushed_t, ratio_t), from measurement.md's combining rule:

S_t         = Σ rate_i over the whole scheduled team, revealed or not   (cohort member n: Σ_i rate_{i,n})
pushed_t    = the rate test t is judged on:
                team test:                min(declared at t, S_t)
                cohort member n:          min(declared_n at t, S_t)
                legacy single-agent test: the peak declaration over the span (below)
j           = the lower-median revealed member by c_i / rate_i, c_i = min(m_i, rate_i), ties to the lower hotkey
median_t    = c_j * S_t / rate_j
measured_t  = min(Σ c_i over the revealed members, median_t)
team_t      = min(declared, measured_t + bg_t)  after Task 12b
            = min(declared, measured_t)         before Task 12b (bg_t lifts only the ratio)
              in kbps, floored to whole Mbps once
ratio_t     = team test:                min(1e6, (c_j * S_t + bg_t * rate_j) * 1e6 / (rate_j * pushed_t))
                                        none with fewer than CAP_TEAM_MIN_VALIDATORS revealed members
              legacy single-agent test: min(1e6, achieved_t * 1e6 / pushed_t)
              (a test with fewer than two revealed members, or with pushed_t = 0, isn't a sample)
measured    = lower median of team_t (or achieved_t) over the tests in the last CAP_PENALTY_WINDOWS windows,
              leaving out a budget-starved cohort member's tests (ratio only)
ratio       = lower median of ratio_t over the same tests that have one
if no tests yet:                                       verified = 0
elif no test has a ratio_t, or ratio >= 1e6 - CAP_TOLERANCE_PPM:
                                                       verified = min(declared, measured)
else:                                                  verified = min(declared, measured) * (1e6 - OVERCLAIM_PENALTY_PPM) / 1e6

All of it is u128 integer arithmetic with floor division, and lower medians sort ascending and take index (n-1)/2. ratio_t is one division with no intermediate floor, so an honest node gets exactly 1e6 (round 5 A; worked example in measurement.md §Team capacity tests: C = 1000, four members at 275).

In code (Task 4Dc, fix round 1). validator::team_verified_capacity is this rule over a node's validator::CapTestRecords (team, pushed, ratio_ppm, ratio_only). run_tempo uses it in team mode (TempoInput.block_hashes supplied and endpoint dedupe on: team mode MUST NOT run while the endpoint stake trigger fails, Task 4Dc fix round 5, T124), through validator::team_verified_capacities (review R1):

The single-agent rule's peak check. The overclaim haircut is checked against the peak declaration over the rolling window ([C-04], RT2-4), so lowering a declaration after a failed test does not lift the haircut early: it lasts until the overclaimed declaration is more than CAP_PENALTY_WINDOWS windows old. Validators keep one node -> declared Mbps map per window (TempoOutcome::declared_capacities, passed back as TempoInput::declaration_history; validator::tempo_verified_capacities). The same rule applies to an honest downgrade: an operator that removes capacity should lower its declaration at least CAP_PENALTY_WINDOWS windows before the measured capacity falls below peak * (1 - CAP_TOLERANCE_PPM).

Only capacity tests acknowledged by the node under test count (measurement.md, cap-test-ack, RT2-3): a cap:<node> sample without a valid node-signed ack for that validator and window is scored as a failed (0 Mbps) test, so several node keys cannot borrow one operator's real sink.

Failed or unreachable capacity tests are recorded as 0 Mbps samples (measurement.md), so a node that goes dark loses verified capacity once failures reach the lower median. Verified capacity also bounds Mechanism 0 usage credit: a node is never credited more bytes per window than verified_mbps * 125_000 * WINDOW_BLOCKS * BLOCK_SECONDS (scoring.md, [SCR-11]).

Endpoint dedupe ([T24]). For scoring, verified capacity is pooled per dedupe group (nodes whose validator-observed public endpoint shares an IPv4 /24, or for IPv6-only endpoints an IPv6 /32 (tunnel-broker /48s share the broker's /32), across UIDs; one group per node, no transitive merging): the group is credited at most its largest single verified capacity, split pro rata among its members (scoring.md §Endpoint dedupe, scoring::dedupe_diverse_node_capacities). N node keys behind one pipe that pass N sequential tests (OQ-18) therefore earn one pipe's capacity term. ASN alone does not pool capacity.

Cohort credit ([T28], OQ-18, OQ-20). Let P be the group's members with verified capacity > 0. Every cohort C (2..=MAX_CAP_COHORT_NODES nodes, measurement.md §Cohort capacity tests) whose members are all in P is a candidate, and the group is credited

pool = max(largest single verified, max over candidates C of min(cohort_verified(C), Σ_{n in C} verified(n)))

instead of the largest single verified capacity, where cohort_verified(C) is the lower median of that exact membership's aggregated cohort throughput (Σ acked bytes * 8 / common span) over the last CAP_COHORT_FRESH_ENTRIES (8) cohort-history entries; a cohort not re-tested within them has no credit. In team mode a cohort counts toward its group's credit only with at least CAP_COHORT_TEAM_MIN_SAMPLES (2) samples in that span (Task 4Dc fix round 5, red team B1(b), T125); with fewer it has no credit, so it can't raise the group above its largest single. A cohort test started short at its last chance (measurement.md §Team capacity tests) records its aggregate capped at Σ max(verified_prev(n), CAP_RAMP_FLOOR_MBPS) over its members (red team L3, B1(a)). A cohort falls due about once per 2.5 windows, so with no attacker about 4% of cohort-windows have lapsed credit, about 15% in team mode with two samples required, and the group is paid as its largest member for them (Task 4Dc red team L1, T116(a), T125, OQ-95). The team schedule's round-robin weight is this pooled figure, with a node that has no endpoint weighing 0 and, while dedupe is off, each UID's lower-median node (validator::schedule_weights, T114, T124). The pool is split pro rata as above (zero-capacity members get 0). Candidates are never summed: disjoint chunks of a group above 16 nodes, or cohorts tested at different times, could have been served one after another by one pipe. Honest operators with separate uplinks in one /24 (or one provider IPv6 /32) are therefore paid up to what validators measured at the same time (sim colocated_cohort_honest: 1.000x, 0.333x with sequential tests only), while N keys on one pipe still earn one pipe, whether tested sequentially or in a cohort (sim sequential_key_replay: 1.000x / 0.998x). A cohort containing a node outside P does not count. A zero-capacity key bound into the /24, a key rotated every window, or a new member does not void an earlier cohort result (red-team Pass-7 cohort_burner_griefer: attacker 1.256x and co-located victims 0.573x before, 1.000x / 1.000x after); a 17-node group keeps its best 16-node chunk. The group's credit can never exceed the verified sum of a cohort's members or what that cohort test measured.

CAP_TOLERANCE_PPM (10%) protects honest operators from the OVERCLAIM_PENALTY_PPM (20%) haircut during minor measurement jitter without ever crediting unmeasured phantom capacity above measured. Over-declaring is strictly worse than or at best equal to declaring honestly, with one residual after Task 12b: a node that stalls real routed traffic during its tests and carries it just outside them can gain up to about 1.11x through credited background (about 1.48x estimated with one colluding team member), as set out below and in measurement.md §Background traffic.

Why declaring honestly stays the best strategy under the ramp (ADR-0039). Compare the alternatives with declaring your real capacity C from day one:

Peer-load calls (ADR-0056 with red-team revision 1; specified and simulated, not scored)

Once peer-load tests score (measurement.md §Peer-load capacity tests), they replace the team-test rule above for the nodes they call.

sample    = 0                                                   if the call is short
          = min(declared, usable, slices_run × floor(Σ h / n))   otherwise; hidden slices only
verified  = 0                                                   if the bond applies in the current cooldown epoch
          = min(declared, lower median of the samples of calls and retests ending in the last CAP_PEER_LOOKBACK_WINDOWS windows)
          = 0                                                   with no such sample

Short calls and retests. A call is short when slices_run × upper_median(h) < min(declared, slices_run × slice) × (1e6 − CAP_TOLERANCE_PPM) / 1e6.

The bond. The node's capacity credit is zeroed from the window the bond applies in to the next multiple of CAP_CHANGE_WINDOWS when either:

Why the upper median. A majority of the hidden slices must be short, so two griefing validators of four cost a sample half its value but can't make a call short. Applying the bond takes a majority in both the call and its retest: P(majority)² a call (sim capacity_validator_grief_quorum).

What can make a call short, and what can't.

Source duty. A source whose duty record's median delivered ratio is below CAP_PEER_DUTY_MIN_PPM (0.95), over at least CAP_PEER_DUTY_MIN_SLICES slices, is charged the same bond on its own capacity credit (peer_load::source_duty_charged). The node under test never is.

What the bond deters, and what it doesn't (sim capacity_burst_renter_calls; founder, 2026-11-08, OQ-43):

The helpers are peer_load::call_outcome, bond_applies, strikes_apply, verified_kbps and source_duty_charged, pure u128 arithmetic.

v1 escrow (not built)

An EVM contract holding stake per operator, slashed on a validator-majority attestation of failed tests. Needs: attestation format, quorum, appeal window, and who receives slashed funds. Tracked in OQ-2.