Governance

[l0r1s]

Summary

Adds an on-chain governance stack to Subtensor: a two-stage referendum flow backed by signed collective voting, three new generic pallets, and the runtime wiring that turns them into Subtensor's concrete governance model.

Root calls now reach dispatch only after passing through both stages, replacing the current sudo-style path with a structured, auditable process.

This governance PR is the umbrella / top-of-stack description for the full governance work. The implementation is being split into smaller reviewable PRs, but this description should explain the complete model and link the split PRs together.

Technical explanation:
https://governance-visualization.a5ede37144f01bdc6a27.workers.dev

Non-technical explanation:
https://gov-novelty.a5ede37144f01bdc6a27.workers.dev

Split PR Stack

The full governance change is intentionally split into four PRs so each piece can be reviewed independently. The first three PRs add their pallets to the codebase only; they do not wire those pallets into the runtime. The final PR wires the stack together and adds the end-to-end tests.

• pallet-multi-collective (this PR Governance #2198) — generic collective membership pallet. Codebase-only, not runtime-wired.
• pallet-signed-voting extracted from governance umbrella PR #2713 — signed aye/nay voting backend. Codebase-only, not runtime-wired.
• pallet-referenda extracted from governance umbrella PR #2714 — generic track-based referendum state machine. Codebase-only, not runtime-wired.
• Extract runtime wiring from governance umbrella PR #2715 — runtime wiring + E2E PR — wires the pallets into Subtensor, defines the concrete governance model, and adds the TypeScript E2E coverage.

Governance Flow

1. A member of the Proposers collective submits a root call on the Triumvirate track.
2. The three-member Triumvirate votes to approve or reject.
3. On approval, the proposal is handed off to a separate review track. It is never directly submittable, so the first gate cannot be bypassed.
4. The review track is voted on by the deduplicated union of the Economic and Building collectives, who can fast-track, delay, or cancel enactment.
5. If the call survives review, the scheduler dispatches it as root through an atomic enact wrapper.

New Pallets

• pallet-multi-collective — generic membership storage for several named collectives under one CollectiveId. Root-gated add/remove/swap/set, plus periodic term hooks for rotating collectives.
• pallet-referenda — generic track-based referendum state machine. Supports PassOrFail (approve/reject/delegate) and Adjustable (timing decision over a scheduled call, with fast-track and cancel thresholds). Owns proposal queues, per-proposer quotas, terminal statuses, and atomic enact wrapping so dispatch and the Enacted status transition happen together.
• pallet-signed-voting — per-account aye/nay backend. Snapshots the eligible voter set when a poll opens and uses that snapshot for the entire poll, so later collective rotations cannot change who votes or shift the threshold denominator. Completed polls clean up vote records lazily during idle time.

All three pallets are runtime-agnostic and independently tested.

Runtime Wiring (runtime/src/governance)

Defines two static tracks:

Track	Voters	Strategy
0 triumvirate	Triumvirate (3)	PassOrFail, 7-day decision, 2/3 approve, 2/3 reject; approval delegates to track 1.
1 review	Economic ∪ Building (≤32, dedup)	Adjustable, 24h initial delay, 2-day max, 75% fast-track, 51% cancel, ease-out adjustment curve.

And five collectives via pallet-multi-collective:

• Proposers (curated, 1-20) — may submit proposals.
• Triumvirate (curated, fixed 3) — first-stage approval.
• Economic (rotating every 60 days, fixed 16) — top root-registered validator coldkeys by smoothed stake EMA.
• Building (rotating every 60 days, fixed 16) — top mature-subnet owners by best moving price.
• EconomicEligible (auto-synced, ≤64) — non-voting candidate pool feeding Economic.

Compile-time assertions tie pallet bounds (MaxQueued, MaxVoterSetSize, cleanup capacity, etc.) to the actual collective sizes so misconfiguration fails at build time. CollectiveId codec indices are treated as consensus-facing and pinned.

Economic and Building Selection

The runtime adds the rotation logic for both selectable collectives.

• Economic ranks EconomicEligible coldkeys by a root-registered EMA value combining liquid TAO with the TAO value of alpha across owned hotkeys. Sampling is incremental (8 subnets and ≤256 hotkeys per tick), runs once per block from Subtensor's on_initialize, and uses alpha 0.02. A 210-sample warmup (~30 days) gates eligibility.
• Building ranks subnet owners by their best mature subnet's moving price, ignoring subnets younger than 180 days, with at most one seat per coldkey.

Both rotations require a full member set; if selection cannot produce 16 accounts the rotation fails safely and the previous membership remains.

Subtensor Integration

• New root_registered module on pallet-subtensor: reference counting of root-registered hotkeys per coldkey, EMA storage, and an EmaValueProvider trait the runtime implements for the stake-value sample.
• Root registration and deregistration now sync EconomicEligible on 0 ↔ 1 transitions and initialize/clear EMA state accordingly.
• on_initialize advances the EMA sampler each block; coldkey/hotkey swaps and UID changes maintain the tracking invariants.
• Migration to seed the new root-registered hotkey counter from current state, plus try-state coverage that verifies the eligibility set matches the root-registered coldkey set.

Documentation

New READMEs covering the model end to end:

• docs/governance/README.md — overall flow, tracks, collectives, selection, lifecycle, review delay formula, events.
• runtime/src/governance/README.md — concrete runtime constants and rotation behavior.
• pallets/multi-collective/README.md, pallets/referenda/README.md, pallets/signed-voting/README.md — per-pallet architecture and configuration.

Testing and Benchmarks

• Extensive Rust unit coverage on all three new pallets and on the runtime governance helpers (membership ops, referendum transitions, voting and tally behavior, lazy cleanup, track invariants, rotation ranking, EMA sampling).
• TypeScript end-to-end suites under ts-tests/suites/dev/subtensor/governance covering submission and origin guards, collectives, quotas, queue limits, voting, voter-set union, review scheduling and recovery paths, full-flow execution, and runtime-upgrade behavior.
• Benchmarks and generated weights for every new extrinsic and governance hook path; benchmark scripts updated for the new pallets.

Safety Notes

• Active referenda use snapshot-based voter eligibility. Collective rotations do not affect in-flight polls.
• The review track is unreachable except through Triumvirate approval; this is a load-bearing runtime invariant.
• Governed calls dispatch through the referenda.enact wrapper, so stale scheduler entries on terminated referenda cannot run the inner call.
• Track decision strategies are snapshotted at submission, so a runtime upgrade that changes thresholds does not retroactively alter live referenda.

[github-actions]

AI review — see the sticky summary comment for the verdict and the inline comments below for specific findings.

[github-actions]

🔄 AI review updated — Skeptic: VULNERABLE

[github-actions]

🔄 AI review updated — Skeptic: SAFE Auditor: 👎

[github-actions]

🔄 AI review updated — Skeptic: SAFE Auditor: 👎

[github-actions]

AI review — see the sticky summary comment for the verdict and the inline comments below for specific findings.

[github-actions]

🔄 AI review updated — Skeptic: SAFE Auditor: 👎

[github-actions]

AI review — see the sticky summary comment for the verdict and the inline comments below for specific findings.

[github-actions]

🔄 AI review updated — Skeptic: SAFE Auditor: 👎

[github-actions]

🔄 AI review updated — Skeptic: SAFE Auditor: 👎

[github-actions]

🔄 AI review updated — Skeptic: SAFE Auditor: 👎