Governance

Cargo.toml

@@ -64,6 +64,7 @@ pallet-subtensor = { path = "pallets/subtensor", default-features = false }
 pallet-subtensor-swap = { path = "pallets/swap", default-features = false }
 pallet-subtensor-swap-runtime-api = { path = "pallets/swap/runtime-api", default-features = false }
 pallet-subtensor-swap-rpc = { path = "pallets/swap/rpc", default-features = false }
+pallet-multi-collective = { path = "pallets/multi-collective", default-features = false }
 procedural-fork = { path = "support/procedural-fork", default-features = false }
 safe-math = { path = "primitives/safe-math", default-features = false }
 share-pool = { path = "primitives/share-pool", default-features = false }
@@ -87,6 +88,7 @@ enumflags2 = "0.7.9"
 futures = "0.3.30"
 hex = { version = "0.4", default-features = false }
 hex-literal = "0.4.1"
+impl-trait-for-tuples = "0.2.3"
 jsonrpsee = { version = "0.24.9", default-features = false }
 libsecp256k1 = { version = "0.7.2", default-features = false }
 lencode = "0.1.6"
@@ -117,7 +119,7 @@ toml_edit = "0.22"
 derive-syn-parse = "0.2"
 Inflector = "0.11"
 cfg-expr = "0.15"
-itertools = "0.10"
+itertools = { version = "0.10", default-features = false }
 macro_magic = { version = "0.5", default-features = false }
 frame-support-procedural-tools = { version = "10.0.0", default-features = false }
 proc-macro-warning = { version = "1", default-features = false }

build.rs

@@ -29,45 +29,52 @@ fn main() {
     // as we process each Rust file
     let (tx, rx) = channel();
 
-    // Parse each rust file with syn and run the linting suite on it in parallel
-    rust_files.par_iter().for_each_with(tx.clone(), |tx, file| {
-        let is_test = file.display().to_string().contains("test");
-        let Ok(content) = fs::read_to_string(file) else {
-            return;
-        };
-        let Ok(parsed_tokens) = proc_macro2::TokenStream::from_str(&content) else {
-            return;
-        };
-        let Ok(parsed_file) = syn::parse2::<syn::File>(parsed_tokens) else {
-            return;
-        };
+    let pool = rayon::ThreadPoolBuilder::new()
+        .stack_size(64 * 1024 * 1024)
+        .build()
+        .expect("build script lint thread pool can be created");
 
-        let track_lint = |result: Result| {
-            let Err(errors) = result else {
+    pool.install(|| {
+        // Parse each rust file with syn and run the linting suite on it in parallel.
+        rust_files.par_iter().for_each_with(tx.clone(), |tx, file| {
+            let is_test = file.display().to_string().contains("test");
+            let Ok(content) = fs::read_to_string(file) else {
                 return;
             };
-            let relative_path = file.strip_prefix(workspace_root).unwrap_or(file.as_path());
-            for error in errors {
-                let loc = error.span().start();
-                let file_path = relative_path.display();
-                // note that spans can't go across thread boundaries without losing their location
-                // info so we we serialize here and send a String
-                tx.send(format!(
-                    "cargo:warning={}:{}:{}: {}",
-                    file_path, loc.line, loc.column, error,
-                ))
-                .unwrap();
-            }
-        };
+            let Ok(parsed_tokens) = proc_macro2::TokenStream::from_str(&content) else {
+                return;
+            };
+            let Ok(parsed_file) = syn::parse2::<syn::File>(parsed_tokens) else {
+                return;
+            };
+
+            let track_lint = |result: Result| {
+                let Err(errors) = result else {
+                    return;
+                };
+                let relative_path = file.strip_prefix(workspace_root).unwrap_or(file.as_path());
+                for error in errors {
+                    let loc = error.span().start();
+                    let file_path = relative_path.display();
+                    // note that spans can't go across thread boundaries without losing their location
+                    // info so we we serialize here and send a String
+                    tx.send(format!(
+                        "cargo:warning={}:{}:{}: {}",
+                        file_path, loc.line, loc.column, error,
+                    ))
+                    .unwrap();
+                }
+            };
 
-        track_lint(ForbidAsPrimitiveConversion::lint(&parsed_file));
-        track_lint(ForbidKeysRemoveCall::lint(&parsed_file));
-        track_lint(RequireFreezeStruct::lint(&parsed_file));
-        track_lint(RequireExplicitPalletIndex::lint(&parsed_file));
+            track_lint(ForbidAsPrimitiveConversion::lint(&parsed_file));
+            track_lint(ForbidKeysRemoveCall::lint(&parsed_file));
+            track_lint(RequireFreezeStruct::lint(&parsed_file));
+            track_lint(RequireExplicitPalletIndex::lint(&parsed_file));
 
-        if is_test {
-            track_lint(ForbidSaturatingMath::lint(&parsed_file));
-        }
+            if is_test {
+                track_lint(ForbidSaturatingMath::lint(&parsed_file));
+            }
+        });
     });
 
     // Collect and print all errors after the parallel processing is done

common/Cargo.toml

@@ -25,6 +25,7 @@ substrate-fixed.workspace = true
 subtensor-macros.workspace = true
 runtime-common.workspace = true
 approx = { workspace = true, optional = true }
+impl-trait-for-tuples.workspace = true
 
 [lints]
 workspace = true

common/src/lib.rs

@@ -16,10 +16,12 @@ use subtensor_macros::freeze_struct;
 
 pub use currency::*;
 pub use evm_context::*;
+pub use traits::*;
 pub use transaction_error::*;
 
 mod currency;
 mod evm_context;
+mod traits;
 mod transaction_error;
 
 /// Balance of an account.

common/src/traits.rs

@@ -0,0 +1,34 @@
+use frame_support::pallet_prelude::*;
+
+/// Handler for when the members of a collective have changed.
+pub trait OnMembersChanged<CollectiveId, AccountId> {
+    /// A collective's members have changed, `incoming` members have joined and
+    /// `outgoing` members have left.
+    fn on_members_changed(
+        collective_id: CollectiveId,
+        incoming: &[AccountId],
+        outgoing: &[AccountId],
+    );
+    /// Worst-case upper bound on `on_members_changed`'s weight. The
+    /// implementation is responsible for bounding its own iteration over
+    /// `incoming`/`outgoing` against the relevant `MaxMembers` constant.
+    fn weight() -> Weight;
+}
+
+#[impl_trait_for_tuples::impl_for_tuples(10)]
+impl<CollectiveId: Clone, AccountId> OnMembersChanged<CollectiveId, AccountId> for Tuple {
+    fn on_members_changed(
+        collective_id: CollectiveId,
+        incoming: &[AccountId],
+        outgoing: &[AccountId],
+    ) {
+        for_tuples!( #( Tuple::on_members_changed(collective_id.clone(), incoming, outgoing); )* );
+    }
+
+    fn weight() -> Weight {
+        #[allow(clippy::let_and_return)]
+        let mut weight = Weight::zero();
+        for_tuples!( #( weight.saturating_accrue(Tuple::weight()); )* );
+        weight
+    }
+}

pallets/multi-collective/Cargo.toml

@@ -0,0 +1,54 @@
+[package]
+name = "pallet-multi-collective"
+version = "1.0.0"
+authors = ["Bittensor Nucleus Team"]
+edition.workspace = true
+license = "Apache-2.0"
+homepage = "https://bittensor.com"
+description = "Membership for named collectives, with per-call origins and optional scheduled rotation."
+readme = "README.md"
+
+[lints]
+workspace = true
+
+[package.metadata.docs.rs]
+targets = ["x86_64-unknown-linux-gnu"]
+
+[dependencies]
+codec = { workspace = true, features = ["max-encoded-len"] }
+scale-info = { workspace = true, features = ["derive"] }
+frame-benchmarking = { workspace = true, optional = true }
+frame-system = { workspace = true }
+frame-support = { workspace = true }
+impl-trait-for-tuples = { workspace = true }
+num-traits = { workspace = true }
+subtensor-runtime-common = { workspace = true }
+
+[dev-dependencies]
+sp-io = { workspace = true, default-features = true }
+sp-core = { workspace = true, default-features = true }
+sp-runtime = { workspace = true, default-features = true }
+
+[features]
+default = ["std"]
+std = [
+    "codec/std",
+    "scale-info/std",
+    "frame-benchmarking?/std",
+    "frame-system/std",
+    "frame-support/std",
+    "num-traits/std",
+    "subtensor-runtime-common/std",
+]
+runtime-benchmarks = [
+	"frame-benchmarking/runtime-benchmarks",
+	"frame-support/runtime-benchmarks",
+	"frame-system/runtime-benchmarks",
+	"sp-runtime/runtime-benchmarks",
+	"subtensor-runtime-common/runtime-benchmarks",
+]
+try-runtime = [
+	"frame-support/try-runtime",
+	"frame-system/try-runtime",
+	"sp-runtime/try-runtime"
+]

pallets/multi-collective/README.md

@@ -0,0 +1,99 @@
+# pallet-multi-collective
+
+Membership storage for one or more named collectives, keyed by a
+runtime-defined `CollectiveId`. Each collective is configured by a
+`CollectivesInfo` impl: name, min/max members, optional term duration.
+
+The pallet only stores membership. Voting, proposing, and tallying are
+left to the consumer (e.g. `pallet-referenda` + `pallet-signed-voting`),
+which read members through the `CollectiveInspect` trait.
+
+## Concepts
+
+| Type | Provided by | Purpose |
+| ---- | ----------- | ------- |
+| `CollectiveId` | runtime | Enum naming each collective. |
+| `CollectivesInfo` | runtime | Returns the static config for each id (name, bounds, term). |
+| `CollectiveInfo` | this crate | `{ name, min_members, max_members, term_duration }`. |
+| `Members<_>` | this crate | `BoundedVec<AccountId, MaxMembers>` per id, sorted by `AccountId`. |
+
+## Extrinsics
+
+| Call | Origin | Effect |
+| ---- | ------ | ------ |
+| `add_member`    | `T::AddOrigin`    | Insert one member. Fails on `AlreadyMember`, `TooManyMembers`, `CollectiveNotFound`. |
+| `remove_member` | `T::RemoveOrigin` | Remove one member. Fails on `NotMember`, `TooFewMembers`, `CollectiveNotFound`. |
+| `swap_member`   | `T::SwapOrigin`   | Atomic remove + insert. Count is preserved, so the per-collective `min_members` / `max_members` bounds are not re-checked; works at either boundary. |
+| `set_members`   | `T::SetOrigin`    | Replace the full list. Sorts the input and rejects `DuplicateAccounts` if any duplicates are present (the input is not silently deduplicated). |
+| `force_rotate`  | `T::RotateOrigin` | Trigger `OnNewTerm` for a rotating collective on demand. |
+
+Every mutation fires `T::OnMembersChanged` with the incoming and
+outgoing accounts so downstream pallets can react (e.g. clean up
+votes). The Subtensor runtime currently wires this to `()`: active
+polls snapshot the voter set at creation, so member changes cannot
+retroactively invalidate votes, and no cleanup is needed.
+
+## Rotation
+
+A collective whose `CollectiveInfo::term_duration` is `Some(d)` rotates
+every `d` blocks: `on_initialize` calls `T::OnNewTerm::on_new_term(id)`
+when `block_number % d == 0`. The runtime-supplied handler typically
+recomputes membership from on-chain data and writes it back through
+`set_members`.
+
+`force_rotate` runs the same hook on demand. Used to bootstrap the
+first term (the natural cadence only fires after the first boundary,
+which can be days or months in) and as a privileged override during
+incidents. Calls against a collective with `term_duration: None` are
+rejected with `CollectiveDoesNotRotate`.
+
+Curated collectives (no term duration) are managed directly via the
+membership extrinsics.
+
+## Integrity check
+
+`integrity_test` runs at runtime construction and panics on a
+misconfigured `CollectivesInfo`:
+
+- `min_members > T::MaxMembers` (collective can't reach its min)
+- `max_members > T::MaxMembers` (storage can't hold the declared max)
+- `min_members > max_members` (collective is unreachable)
+- `term_duration: Some(0)` (silently disables rotation; use `None` to opt out)
+
+## Migrations
+
+Pinned at `StorageVersion::new(0)` to satisfy try-runtime CLI; the
+project tracks migration runs through a per-pallet `HasMigrationRun`
+storage map (see `pallet-crowdloan`), not via FRAME's `StorageVersion`
+bump. Add a `migrations` module and an `on_runtime_upgrade` hook on
+the next breaking change to `Members<_>` or any future persisted state.
+
+## Configuration
+
+```rust
+parameter_types! {
+    pub const MaxMembers: u32 = 20;
+}
+
+impl pallet_multi_collective::Config for Runtime {
+    type CollectiveId    = CollectiveId;
+    type Collectives     = Collectives;
+    type AddOrigin       = AsEnsureOriginWithArg<EnsureRoot<AccountId>>;
+    type RemoveOrigin    = AsEnsureOriginWithArg<EnsureRoot<AccountId>>;
+    type SwapOrigin      = AsEnsureOriginWithArg<EnsureRoot<AccountId>>;
+    type SetOrigin       = AsEnsureOriginWithArg<EnsureRoot<AccountId>>;
+    type RotateOrigin    = AsEnsureOriginWithArg<EnsureRoot<AccountId>>;
+    type OnMembersChanged = ();
+    type OnNewTerm       = TermManagement;
+    type MaxMembers      = MaxMembers;
+    type WeightInfo      = pallet_multi_collective::weights::SubstrateWeight<Runtime>;
+}
+```
+
+`T::MaxMembers` bounds storage; per-collective `max_members` from
+`CollectivesInfo` may be smaller but never larger (enforced by
+`integrity_test`).
+
+## License
+
+Apache-2.0.