Skip to content

Commit 8099812

Browse files
gztensorgztensor
committed
Add subsubnets proposal
1 parent 85d2b1b commit 8099812

File tree

2 files changed

+191
-0
lines changed

2 files changed

+191
-0
lines changed

‎bits/BIT-0006-subsubnets.md

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
# BIT-0006: Sub-subnets
2+
3+
- **BIT Number:** 0006
4+
- **Title:** Sub-subnets
5+
- **Author(s):** Rhef, Greg Zaitsev
6+
- **Discussions-to:** [URL for discussion thread]
7+
- **Status:** Draft
8+
- **Type:** Core
9+
- **Created:** 2025-06-13
10+
- **Updated:** 2025-06-13
11+
12+
## 🔍 Abstract
13+
14+
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.
15+
16+
## 🔧 Motivation
17+
18+
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.
19+
20+
## 🧪 Specification
21+
22+
### Subsubnet Limits
23+
- Each subnet defines a `desired_subsubnet_limit` hyperparameter (default = 1).
24+
- A global limit `global_subsubnet_limit_per_subnet` acts as a ceiling.
25+
- The active value `subsubnet_limit_in_force` is updated every subnet superblock (every 20 tempos) as:
26+
27+
```
28+
subsubnet_limit_in_force = min(
29+
desired_subsubnet_limit,
30+
global_subsubnet_limit_per_subnet,
31+
subsubnet_limit_in_force_last + global_subsubnet_decrease_per_subnet_superblock
32+
)
33+
```
34+
35+
### Weight Operations
36+
- `set_weights`, `commit_weights`, and `reveal_weights` accept a `subsubnet_id` argument.
37+
- Legacy operations default to `subsubnet_id = 0`.
38+
- Weight writes are disallowed above the current `subsubnet_limit_in_force`.
39+
40+
### Validator Permissions
41+
- Only the subnet owner or sudo can change the `desired_subsubnet_limit` or emission proportions.
42+
- Validators may set weights for any subsubnet within the current limit.
43+
44+
### Emission Logic
45+
- Emission is distributed across subsubnets according to a configured ratio (default Fibonacci: [1, 2, 3, 5, 8, 13, 21, 34]).
46+
- Each subsubnet computes trust, consensus, and incentive separately.
47+
- Final vtrust is aggregated across subsubnets weighted by their emissions.
48+
- Rounding is preserved across subsubnet splits to ensure exact conservation of emitted tokens.
49+
50+
### Edge Cases
51+
- If a subsubnet has zero consensus, it enters “Yuma emergency mode” and allocates emission proportional to stake.
52+
- Miners without weights in a subsubnet receive no emission from it.
53+
- Subsubnets with no miners are gracefully handled.
54+
55+
### Compatibility
56+
- Subnets with a single subsubnet behave exactly as today (ID 0).
57+
- Legacy miners/validators interoperate with subsubnet-enabled subnets via `subsubnet_id = 0`.
58+
- Storage and RPC interfaces remain backward-compatible.
59+
60+
## ✅ Rationale
61+
62+
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.
63+
64+
## 📘 Reference Implementation
65+
66+
- Will be implemented in the `subtensor` core repo.
67+
- Interfaces for weight setting, emission, and validator ranking will be extended to include `subsubnet_id`.
68+
69+
## 🧱 Backward Compatibility
70+
71+
- All existing weight operations apply to `subsubnet_id = 0`.
72+
- Subnets not opting into subsubnets will remain functionally identical.
73+
- Miners and validators on older versions will continue functioning under subsubnet_id 0.
74+
75+
## 📈 Test Cases
76+
77+
See BIT test document `subsubnet_test_plan.bit`.
78+
79+
## 💬 Discussion
80+
81+
- Emission proportion customization per subsubnet opens design space for subnet-specific task prioritization.
82+
- Validator voting on miner subsubnet weights (via kappa) may be used for consensus and reward routing.
83+
- Handling of dynamic emission distribution and cleanups when limits decrease must be conservative and race-free.
84+
85+
## 🛠️ Future Work
86+
87+
- **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.
88+
89+
- **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.
90+
91+
- **Hyperparameter Governance**: Subnet owners will gain control over additional subsubnet-specific hyperparameters beyond the subsubnet limit, allowing more granular tuning of behavior.
92+
93+
- **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.
94+
95+
- **Additional Governance Extensions**: Future extensions may include subsubnet-specific pruning policies, trust calculation curves, or dynamic validator selection strategies.
96+
97+
98+
## 🔐 Security Considerations
99+
100+
The introduction of subsubnets introduces additional state surfaces and per-subsubnet tracking, which must be secured against manipulation:
101+
102+
- **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.
103+
104+
- **Weight Isolation**: Weights across subsubnets must remain isolated. Cross-contamination could allow miners to gain rewards in unintended subsubnets.
105+
106+
- **Rounding and Overflow**: Emission rounding and aggregation must be implemented carefully to prevent underflow/overflow or token inflation.
107+
108+
- **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.
109+
110+
- **Cleanups**: When limits are decreased, weight purging must be idempotent and bounded to prevent validator or miner state desynchronization.
111+
112+
## © Copyright
113+
114+
This document is licensed under [The Unlicense](https://unlicense.org/).

‎bits/subsubnet-test-plan.md

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
# Subsubnet Functionality BIT
2+
3+
## Test Areas
4+
5+
### ✅ Weight Cleanup
6+
- [ ] Weights are cleaned when `subsubnet_limit_in_force` decreases
7+
- [ ] For each subsubnet, when a miner is deregistered or leaves, their weights are cleaned across **all** subsubnets
8+
9+
### ✅ Limit Update Logic
10+
- [ ] Decreasing `desired_subsubnet_limit` reduces `subsubnet_limit_in_force` by no more than `global_subsubnet_decrease_per_subnet_superblock`
11+
- [ ] Validate update timing during the subnet superblock (every 20 tempos)
12+
- [ ] Confirm fallback to `min(desired_subsubnet_limit, global_subsubnet_limit_per_subnet)`
13+
14+
### ✅ Validator Permissions & Hyperparameters
15+
- [ ] Ensure only subnet owners (or sudo) can modify their subnet's subsubnet hyperparameters
16+
- [ ] Max allowed `desired_subsubnet_limit` is 8 (ids 0-7)
17+
- [ ] Validators **cannot** modify other subnets’ parameters
18+
- [ ] `desired_subsubnet_limit` is readable by API per subnet and globally
19+
20+
### ✅ Compatibility with Existing Systems
21+
- [ ] Confirm `subsubnet_id = 0` acts as default fallback for weight operations
22+
- [ ] Validate `set_weights`, `commit_weights`, `reveal_weights` apply correctly on subsubnet_id=0
23+
- [ ] Confirm legacy operations still work as expected when subsubnet feature is not used (regression)
24+
25+
### ✅ Weight Setting Restrictions
26+
- [ ] Prevent weight setting above `subsubnet_limit_in_force`
27+
- [ ] Prevent CR2/CR3 weight commits/reveals for disabled subsubnets
28+
- [ ] Validators **can** set weights above hyperparameter but below `subsubnet_limit_in_force`
29+
30+
### ✅ Miner-Subsubnet Interaction
31+
- [ ] Miner can participate in multiple or all subsubnets (bond, weights, rewards)
32+
- [ ] Support miner existence with no weights on any subsubnet
33+
- [ ] Support subsubnet existence with no miner weights at all
34+
- [ ] Ensure correct weights can be retrieved per miner per subsubnet
35+
36+
### ✅ Emissions and Incentives
37+
- [ ] Ensure `subsubnet_limit_in_force` does not exceed global limit
38+
- [ ] Validate weight independence across subsubnets
39+
- [ ] Check total emission is split among subsubnets based on pre-defined distribution (Fibonacci default):
40+
- id0 = 1
41+
- id1 = 2
42+
- id2 = 3
43+
- id3 = 5
44+
- id4 = 8
45+
- id5 = 13
46+
- id6 = 21
47+
- id7 = 34
48+
- [ ] Validate that per-subsubnet incentives are distributed proportionally to miner weights
49+
- [ ] Trust, vtrust, consensus, etc. are calculated per subsubnet and then aggregated
50+
- [ ] Rounding logic does not lose incentive
51+
- [ ] Sum of all subsubnet emissions matches total emission
52+
53+
### ✅ Emergency and Recycling Behavior
54+
- [ ] Empty subsubnet enters "Yuma Emergency Mode", emission distributed by stake
55+
- [ ] If consensus sum is 0 for a subsubnet, trigger emergency fallback
56+
- [ ] Recycling incentives per subsubnet via validator vote by subnet owner ID
57+
- [ ] Miner without any subsubnet weights receives **no** reward
58+
59+
### ✅ Subnet Compatibility Testing
60+
- [ ] Subnets with `desired_subsubnet_limit = 1` (id = 0 only) operate without change
61+
- [ ] Regression tests confirm staking, pruning, emissions, and validator selection work as before
62+
- [ ] Switching subsubnets off restores old behavior without side effects
63+
- [ ] Storage layout and RPC responses remain compatible for older miners/validators
64+
- [ ] Validate upgrade paths: backward compatibility for older nodes (v2+)
65+
66+
### ✅ Governance and Parameter Controls
67+
- [ ] Subnet owner can set incentive proportions per subsubnet
68+
- [ ] Global subsubnet limit is dynamically adjustable
69+
- [ ] Decreasing global limit propagates cleanups in all subnets
70+
- [ ] Subnet owners can update subsubnet-specific hyperparameters
71+
- [ ] Validator vote (via `kappa`) determines miner emission share per subsubnet
72+
73+
---
74+
75+
## References
76+
- Implements part of: Subsubnet BIP (TBD)
77+
- Affects: Miner incentives, emission mechanics, subnet behavior

0 commit comments

Comments
 (0)