diff --git a/bits/BIT-0006-subsubnets.md b/bits/BIT-0006-subsubnets.md new file mode 100644 index 0000000..f3da2a5 --- /dev/null +++ b/bits/BIT-0006-subsubnets.md @@ -0,0 +1,114 @@ +# BIT-0006: Sub-subnets + +- **BIT Number:** 0006 +- **Title:** Sub-subnets +- **Author(s):** Rhef, Greg Zaitsev +- **Discussions-to:** [URL for discussion thread] +- **Status:** Draft +- **Type:** Core +- **Created:** 2025-06-13 +- **Updated:** 2025-06-13 + +## πŸ” Abstract + +This BIT proposes the introduction of subsubnets, a hierarchical layer within each subnet to support multiple, independent weight spaces, emissions, and incentive flows under a single subnet umbrella. Subsubnets enable fine-grained control over miner task allocation, incentive distribution, and validator decision-making. Each subnet can define up to 8 subsubnets, with weights and rewards tracked independently per subsubnet. + +## πŸ”§ Motivation + +Subnets today treat miner weights as a single flat structure, limiting expressivity in multi-task or multi-objective networks. Introducing subsubnets allows a single subnet to support multiple distinct task markets, enabling specialized incentive tracking, validator scoring, and emission logic per group. This facilitates complex workloads, parallel task handling, and flexible protocol design without fragmenting network security or duplicating validator logic. + +## πŸ§ͺ Specification + +### Subsubnet Limits +- Each subnet defines a `desired_subsubnet_limit` hyperparameter (default = 1). +- A global limit `global_subsubnet_limit_per_subnet` acts as a ceiling. +- The active value `subsubnet_limit_in_force` is updated every subnet superblock (every 20 tempos) as: + +``` +subsubnet_limit_in_force = min( + desired_subsubnet_limit, + global_subsubnet_limit_per_subnet, + subsubnet_limit_in_force_last + global_subsubnet_decrease_per_subnet_superblock +) +``` + +### Weight Operations +- `set_weights`, `commit_weights`, and `reveal_weights` accept a `subsubnet_id` argument. +- Legacy operations default to `subsubnet_id = 0`. +- Weight writes are disallowed above the current `subsubnet_limit_in_force`. + +### Validator Permissions +- Only the subnet owner or sudo can change the `desired_subsubnet_limit` or emission proportions. +- Validators may set weights for any subsubnet within the current limit. + +### Emission Logic +- Emission is distributed across subsubnets according to a configured ratio (default Fibonacci: [1, 2, 3, 5, 8, 13, 21, 34]). +- Each subsubnet computes trust, consensus, and incentive separately. +- Final vtrust is aggregated across subsubnets weighted by their emissions. +- Rounding is preserved across subsubnet splits to ensure exact conservation of emitted tokens. + +### Edge Cases +- If a subsubnet has zero consensus, it enters β€œYuma emergency mode” and allocates emission proportional to stake. +- Miners without weights in a subsubnet receive no emission from it. +- Subsubnets with no miners are gracefully handled. + +### Compatibility +- Subnets with a single subsubnet behave exactly as today (ID 0). +- Legacy miners/validators interoperate with subsubnet-enabled subnets via `subsubnet_id = 0`. +- Storage and RPC interfaces remain backward-compatible. + +## βœ… Rationale + +Subsubnets allow a single subnet to support multiple incentive partitions, enabling more advanced use cases (e.g. routing, filtering, classification, multitask models). They preserve validator overhead by avoiding new subnets while enabling greater expressivity. The design enforces strict backward compatibility and safe transitions when limits change. + +## πŸ“˜ Reference Implementation + +- Will be implemented in the `subtensor` core repo. +- Interfaces for weight setting, emission, and validator ranking will be extended to include `subsubnet_id`. + +## 🧱 Backward Compatibility + +- All existing weight operations apply to `subsubnet_id = 0`. +- Subnets not opting into subsubnets will remain functionally identical. +- Miners and validators on older versions will continue functioning under subsubnet_id 0. + +## πŸ“ˆ Test Cases + +See BIT test document `subsubnet_test_plan.bit`. + +## πŸ’¬ Discussion + +- Emission proportion customization per subsubnet opens design space for subnet-specific task prioritization. +- Validator voting on miner subsubnet weights (via kappa) may be used for consensus and reward routing. +- Handling of dynamic emission distribution and cleanups when limits decrease must be conservative and race-free. + +## πŸ› οΈ Future Work + +- **Custom Emission Proportions**: Subnet owners will be able to customize the proportion of emission allocated to each subsubnet, enabling tailored incentive strategies based on task complexity or utility. + +- **Dynamic Global Subsubnet Limit**: A globally enforced ceiling on subsubnet counts will be adjustable over time. Reductions to this limit will automatically trigger cleanup of excess subsubnet data across all subnets. + +- **Hyperparameter Governance**: Subnet owners will gain control over additional subsubnet-specific hyperparameters beyond the subsubnet limit, allowing more granular tuning of behavior. + +- **Validator-Driven Incentive Routing**: Using the kappa stake majority mechanism, validators may vote to adjust miner incentive shares within subsubnets, supporting flexible prioritization of behaviors and tasks. + +- **Additional Governance Extensions**: Future extensions may include subsubnet-specific pruning policies, trust calculation curves, or dynamic validator selection strategies. + + +## πŸ” Security Considerations + +The introduction of subsubnets introduces additional state surfaces and per-subsubnet tracking, which must be secured against manipulation: + +- **Permission Enforcement**: Only subnet owners or sudo must be able to modify `desired_subsubnet_limit`, emission proportions, or trigger subsubnet resets. Improper permission checks could allow hostile takeovers of reward logic. + +- **Weight Isolation**: Weights across subsubnets must remain isolated. Cross-contamination could allow miners to gain rewards in unintended subsubnets. + +- **Rounding and Overflow**: Emission rounding and aggregation must be implemented carefully to prevent underflow/overflow or token inflation. + +- **Backward Compatibility**: Any logic paths introduced for subsubnet IDs must default to safe values (e.g., subsubnet_id = 0) to avoid denial-of-service for legacy miners and validators. + +- **Cleanups**: When limits are decreased, weight purging must be idempotent and bounded to prevent validator or miner state desynchronization. + +## Β© Copyright + +This document is licensed under [The Unlicense](https://unlicense.org/). diff --git a/bits/subsubnet-test-plan.md b/bits/subsubnet-test-plan.md new file mode 100644 index 0000000..bb98acf --- /dev/null +++ b/bits/subsubnet-test-plan.md @@ -0,0 +1,77 @@ +# Subsubnet Functionality BIT + +## Test Areas + +### βœ… Weight Cleanup +- [ ] Weights are cleaned when `subsubnet_limit_in_force` decreases +- [ ] For each subsubnet, when a miner is deregistered or leaves, their weights are cleaned across **all** subsubnets + +### βœ… Limit Update Logic +- [ ] Decreasing `desired_subsubnet_limit` reduces `subsubnet_limit_in_force` by no more than `global_subsubnet_decrease_per_subnet_superblock` +- [ ] Validate update timing during the subnet superblock (every 20 tempos) +- [ ] Confirm fallback to `min(desired_subsubnet_limit, global_subsubnet_limit_per_subnet)` + +### βœ… Validator Permissions & Hyperparameters +- [ ] Ensure only subnet owners (or sudo) can modify their subnet's subsubnet hyperparameters +- [ ] Max allowed `desired_subsubnet_limit` is 8 (ids 0-7) +- [ ] Validators **cannot** modify other subnets’ parameters +- [ ] `desired_subsubnet_limit` is readable by API per subnet and globally + +### βœ… Compatibility with Existing Systems +- [ ] Confirm `subsubnet_id = 0` acts as default fallback for weight operations +- [ ] Validate `set_weights`, `commit_weights`, `reveal_weights` apply correctly on subsubnet_id=0 +- [ ] Confirm legacy operations still work as expected when subsubnet feature is not used (regression) + +### βœ… Weight Setting Restrictions +- [ ] Prevent weight setting above `subsubnet_limit_in_force` +- [ ] Prevent CR2/CR3 weight commits/reveals for disabled subsubnets +- [ ] Validators **can** set weights above hyperparameter but below `subsubnet_limit_in_force` + +### βœ… Miner-Subsubnet Interaction +- [ ] Miner can participate in multiple or all subsubnets (bond, weights, rewards) +- [ ] Support miner existence with no weights on any subsubnet +- [ ] Support subsubnet existence with no miner weights at all +- [ ] Ensure correct weights can be retrieved per miner per subsubnet + +### βœ… Emissions and Incentives +- [ ] Ensure `subsubnet_limit_in_force` does not exceed global limit +- [ ] Validate weight independence across subsubnets +- [ ] Check total emission is split among subsubnets based on pre-defined distribution (Fibonacci default): + - id0 = 1 + - id1 = 2 + - id2 = 3 + - id3 = 5 + - id4 = 8 + - id5 = 13 + - id6 = 21 + - id7 = 34 +- [ ] Validate that per-subsubnet incentives are distributed proportionally to miner weights +- [ ] Trust, vtrust, consensus, etc. are calculated per subsubnet and then aggregated +- [ ] Rounding logic does not lose incentive +- [ ] Sum of all subsubnet emissions matches total emission + +### βœ… Emergency and Recycling Behavior +- [ ] Empty subsubnet enters "Yuma Emergency Mode", emission distributed by stake +- [ ] If consensus sum is 0 for a subsubnet, trigger emergency fallback +- [ ] Recycling incentives per subsubnet via validator vote by subnet owner ID +- [ ] Miner without any subsubnet weights receives **no** reward + +### βœ… Subnet Compatibility Testing +- [ ] Subnets with `desired_subsubnet_limit = 1` (id = 0 only) operate without change +- [ ] Regression tests confirm staking, pruning, emissions, and validator selection work as before +- [ ] Switching subsubnets off restores old behavior without side effects +- [ ] Storage layout and RPC responses remain compatible for older miners/validators +- [ ] Validate upgrade paths: backward compatibility for older nodes (v2+) + +### βœ… Governance and Parameter Controls +- [ ] Subnet owner can set incentive proportions per subsubnet +- [ ] Global subsubnet limit is dynamically adjustable +- [ ] Decreasing global limit propagates cleanups in all subnets +- [ ] Subnet owners can update subsubnet-specific hyperparameters +- [ ] Validator vote (via `kappa`) determines miner emission share per subsubnet + +--- + +## References +- Implements part of: Subsubnet BIP (TBD) +- Affects: Miner incentives, emission mechanics, subnet behavior