Skip to content

Commit 9004fa0

Browse files
MichaelTrestmanchideraao
MichaelTrestman
and
chideraao
authored
subnet mechanisms continued (#98)
* wip * wip * wip * wip * wip * wip * wip * wip * wip * wip * wip * wip * wip * wip * wip * wip * Apply suggestions from code review Co-authored-by: Dera Okeke <[email protected]> * wip * wip * wip * wip --------- Co-authored-by: Dera Okeke <[email protected]>
1 parent 1adb53f commit 9004fa0

File tree

6 files changed

+347
-20
lines changed

6 files changed

+347
-20
lines changed

‎docs/learn/announcements.md‎

Lines changed: 12 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -6,19 +6,21 @@ title: "Announcements and Developments"
66
This page tracks recent and upcoming changes to the Bittensor protocol and other major events in the Bittensor ecosystem.
77

88

9-
## Sub-Subnets
9+
## Multiple Incentive Mechanisms Within Subnets
1010

11-
**Status**: In develoment
12-
- **What**: Sub-subnets allow subnet owners to apportion emissions across multiple sub-subnets, each running Yuma Consensus independently
11+
**Status**: In development
12+
- **What**: Multiple incentive mechanisms allow subnet owners to apportion emissions across different evaluation criteria, each running Yuma Consensus independently with separate bond pools
1313
- **Key Features**:
14-
- Enables up to 8 sub-subnets (IDs 0-7) within each main subnet for multi-task validation
15-
- Fully backward-compatible with existing miners and validators via sub-subnet ID 0
16-
- Each sub-subnet has its own weight matrix and independent emissions
17-
- All validators participate in all sub-subnets with identical stake weights
18-
- Miners automatically participate in ALL sub-subnets when registering for a subnet
14+
- Enables up to 2 incentive mechanisms (IDs 0,1) within each subnet for multi-task validation.
15+
- Fully backward-compatible with existing miners and validators via mechanism ID 0
16+
- Each mechanism has its own weight matrix and independent bond pools for consensus calculations
17+
- All validators participate in all mechanisms with identical stake weights
18+
- Miners can automatically participate in any of the subnet's mechanisms when registering for a subnet
1919
- **Emission distribution control**: Subnet owners can set custom emission distributions using the `sudo_set_subsubnet_emission_split` extrinsic
20-
- **Immediate sub-subnet number setting**: No onset period - changes take effect immediately
21-
- **Rate limiting**: Subnet owners can set sub-subnet numbers once per 7200 blocks
20+
- **Immediate mechanism number setting**: No onset period - changes take effect immediately
21+
- **Rate limiting**: Subnet owners can set mechanism numbers once per 7200 blocks
22+
23+
For detailed information, see: [Multiple Incentive Mechanisms Within Subnets](../subnets/understanding-multiple-mech-subnets)
2224

2325
## Hyperparameter Rate Limiting
2426
**Status**: WIP

‎docs/subnets/managing-mechanisms-btcli.md‎

Lines changed: 150 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,150 @@
1+
---
2+
title: "Managing Multiple Incentive Mechanisms with BTCLI"
3+
---
4+
5+
# Managing Multiple Incentive Mechanisms with BTCLI
6+
7+
This tutorial shows how to configure and manage multiple incentive mechanisms in a single subnet using BTCLI.
8+
9+
For background on the concepts, see [Understanding Multiple Incentive Mechanisms](understanding-multiple-mech-subnets).
10+
11+
See also: [Managing Mechanisms with SDK](managing-mechanisms-with-sdk).
12+
13+
**Prerequisites**
14+
- A local Subtensor chain running. See: [Run a Local Bittensor Blockchain Instance](../local-build/deploy)
15+
- A local subnet created (and emissions started). See: [Create a Subnet (Locally)](../local-build/create-subnet)
16+
- Wallets provisioned and funded for local development. See: [Provision Wallets](../local-build/provision-wallets)
17+
- BTCLI installed (development version required for mechanism commands)
18+
19+
::::tip
20+
Substitute your subnet's netuid, which you can find with `btcli subnet list`.
21+
::::
22+
23+
:::warning Runtime limit
24+
As of the current Subtensor runtime, a subnet can have a maximum of 2 mechanisms. Attempts to set a higher count will be rejected by the chain (runtime enforces `MaxMechanismCount = 2`).
25+
26+
:::
27+
28+
## Check initial state
29+
30+
The following command will check the count of your subnet's incentive mechanisms and display the emissions split among them.
31+
32+
33+
```bash
34+
btcli subnet mech count --netuid 6 --network local
35+
btcli subnet mech emissions --netuid 6 --network local
36+
```
37+
```
38+
Subnet 6 currently has 1 mechanism.
39+
(Tip: 1 mechanism means there are no mechanisms beyond the main subnet)
40+
41+
Subnet 6 only has the primary mechanism (mechanism 0). No emission split to display.
42+
```
43+
44+
## Create a second mechanism
45+
46+
Create a second incentive mechanism by specifying the desired count as two for your subnet.
47+
48+
```bash
49+
btcli subnet mech set --mech-count 2 --netuid 6 --network local
50+
```
51+
```
52+
Subnet 6 currently has 1 mechanism. Set it to 2? [y/n]: y
53+
✅ Mechanism count set to 2 for subnet 6
54+
```
55+
56+
57+
Check the state to confirm the change
58+
59+
```bash
60+
btcli subnet mech count --netuid 6 --network local
61+
btcli subnet mech emissions --netuid 6 --network local
62+
```
63+
```
64+
Subnet 6 currently has 2 mechanisms.
65+
(Tip: 1 mechanism means there are no mechanisms beyond the main subnet)
66+
[13:44:15] Warning: Verify your local subtensor is running on port 9944. subtensor_interface.py:85
67+
68+
Subnet 6 • Emission split
69+
Network: local
70+
71+
Mechanism Index Weight (u16) Share (%)
72+
─────────────────────────────────────────────
73+
0 32768 50.000763
74+
1 32767 49.999237
75+
Total 65535 100.000000
76+
─────────────────────────────────────────────
77+
78+
79+
Totals are expressed as a fraction of 65535 (U16_MAX).
80+
No custom split found; displaying an even distribution.
81+
```
82+
83+
84+
## Set a custom 90/10 emission split
85+
86+
Let's allocate only 10% of our subnet's emissions to the second subnet.
87+
88+
89+
```bash
90+
btcli subnet mech emissions-split --netuid 6 --network local --split "90,10" --wallet-name alice
91+
```
92+
```
93+
Subnet 6 • Emission split
94+
Network: local
95+
96+
Mechanism Index Weight (u16) Share (%)
97+
─────────────────────────────────────────────
98+
0 32768 50.000763
99+
1 32767 49.999237
100+
Total 65535 100.000000
101+
─────────────────────────────────────────────
102+
103+
104+
Totals are expressed as a fraction of 65535 (U16_MAX).
105+
No custom split found; displaying an even distribution.
106+
107+
Proposed emission split
108+
Subnet 6
109+
110+
Mechanism Index Weight (u16) Share (%)
111+
─────────────────────────────────────────────
112+
0 58982 90.000000
113+
1 6553 10.000000
114+
115+
Total 65535 100.000000
116+
─────────────────────────────────────────────
117+
118+
119+
Proceed with these emission weights? [y/n] (y): y
120+
🌍 📡 Setting emission split for subnet 6...
121+
✅ Emission split updated for subnet 6
122+
```
123+
124+
125+
We can confirm this by running the getter command again:
126+
127+
```bash
128+
btcli subnet mech emissions --netuid 6 --network local
129+
```
130+
```
131+
132+
Subnet 6 • Emission split
133+
Network: local
134+
135+
Mechanism Index Weight (u16) Share (%)
136+
─────────────────────────────────────────────
137+
0 58982 90.000763
138+
1 6553 9.999237
139+
Total 65535 100.000000
140+
─────────────────────────────────────────────
141+
142+
143+
Totals are expressed as a fraction of 65535 (U16_MAX).
144+
```
145+
146+
## Troubleshooting
147+
148+
- Rate limiting: mechanism count changes are restricted (on mainnet) to once per ~24 hours (7200 blocks).
149+
- Permissions: emission split and count updates require the subnet owner wallet.
150+
- Local chain connectivity: ensure your local chain is running and the `network` parameter in your BTCLI config is set to `local`.

‎docs/subnets/managing-mechanisms-with-sdk.md‎

Lines changed: 160 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,160 @@
1+
---
2+
title: "Managing Multiple Incentive Mechanisms with SDK"
3+
---
4+
5+
# Managing Multiple Incentive Mechanisms with SDK
6+
7+
This tutorial shows how to configure and manage multiple incentive mechanisms in a single subnet using the Bittensor Python SDK.
8+
9+
For background on the concepts, see [Understanding Multiple Incentive Mechanisms](./understanding-multiple-mech-subnets).
10+
11+
See also [Managing Mechanisms with BTCLI](./managing-mechanisms-btcli).
12+
13+
14+
**Prerequisites**
15+
- A local Subtensor chain running. See: [Run a Local Bittensor Blockchain Instance](../local-build/deploy)
16+
- A local subnet created (and emissions started). See: [Create a Subnet (Locally)](../local-build/create-subnet)
17+
- Wallets provisioned and funded for local development. See: [Provision Wallets](../local-build/provision-wallets)
18+
- BTCLI installed (development version required for mechanism commands)
19+
20+
21+
:::tip
22+
Substitute your subnet's netuid, which you can find with `btcli subnet list`.
23+
:::
24+
25+
:::warning Runtime limit
26+
As of the current Subtensor runtime, a subnet can have a maximum of 2 mechanisms. Attempts to set a higher count will be rejected by the chain (runtime enforces `MaxMechanismCount = 2`).
27+
:::
28+
29+
30+
## Initialize SDK and wallet
31+
32+
The following snippet initializes the Bittensor SDK, imports the needed modules, connects to the local blockchain, and initializes the wallet object for the Alice wallet.
33+
34+
Run this at the top of each script below.
35+
36+
```python
37+
import bittensor as bt
38+
from bittensor.core.extrinsics.sudo import (
39+
sudo_set_mechanism_emission_split_extrinsic,
40+
sudo_set_mechanism_count_extrinsic,
41+
)
42+
43+
# Connect to local chain
44+
subtensor = bt.Subtensor(network="local")
45+
46+
# Load the subnet owner wallet (assumes wallet is provisioned locally)
47+
wallet = bt.Wallet(name="alice")
48+
49+
netuid = 7
50+
print("SDK version:", bt.__version__)
51+
print(f"Connected to {subtensor.network} — managing subnet {netuid} with wallet {wallet.name}")
52+
```
53+
54+
```text
55+
SDK version: 9.10.1
56+
Connected to local — managing subnet 7 with wallet alice
57+
```
58+
59+
## Read current mechanism configuration
60+
61+
Add the below snippet to display the current mechanism count on subnet 7 (or whatever subnet you have set above).
62+
63+
```python
64+
# Mechanism count
65+
mech_count = subtensor.get_mechanism_count(netuid=netuid)
66+
print(f"Subnet {netuid} mech count: {mech_count} ")
67+
68+
# Current emission split (chain-stored values)
69+
raw_split = subtensor.get_mechanism_emission_split(netuid=netuid)
70+
71+
# Normalize to percentages by sum (works for either u16-scaled or raw values)
72+
if not raw_split == None:
73+
_total = max(1, sum(raw_split))
74+
percentages = [round((v / _total) * 100, 6) for v in raw_split]
75+
print("Percentages:", percentages)
76+
else:
77+
print("No split defined.")
78+
```
79+
80+
```
81+
Subnet 7 mech count: 1
82+
No split defined.
83+
```
84+
85+
86+
## Create a second mechanism
87+
88+
Use the sudo extrinsic to increase the mechanism count to 2 for your subnet owner wallet.
89+
90+
```python
91+
# Increase mechanism count to 2
92+
ok, err = sudo_set_mechanism_count_extrinsic(
93+
subtensor=subtensor,
94+
wallet=wallet,
95+
netuid=netuid,
96+
mech_count=2,
97+
)
98+
print("Set mech count success:", ok)
99+
if not ok:
100+
print("Error:", err)
101+
102+
# Verify the change
103+
new_count = subtensor.get_mechanism_count(netuid=netuid)
104+
print(f"Subnet {netuid} mech count (after): {new_count}")
105+
106+
# Read split again; if None, display implied equal distribution
107+
split_after = subtensor.get_mechanism_emission_split(netuid=netuid)
108+
109+
print("split:")
110+
print(split_after)
111+
```
112+
113+
```text
114+
Set mech count success: True
115+
Subnet 7 mech count (after): 2
116+
split:
117+
[50, 50]
118+
```
119+
120+
## Set a custom 60/40 emission split
121+
122+
```python
123+
new_split = [60, 40]
124+
125+
ok, err = sudo_set_mechanism_emission_split_extrinsic(
126+
subtensor=subtensor,
127+
wallet=wallet,
128+
netuid=netuid,
129+
maybe_split=new_split,
130+
)
131+
132+
print("Update success:", ok)
133+
if not ok:
134+
print("Error:", err)
135+
```
136+
137+
```text
138+
Update success: True
139+
140+
141+
```
142+
143+
## Verify the change
144+
145+
```python
146+
split_after = subtensor.get_mechanism_emission_split(netuid=netuid)
147+
print("split:")
148+
print(split_after)
149+
```
150+
151+
```text
152+
split:
153+
[60, 40]
154+
```
155+
156+
## Troubleshooting
157+
158+
- Rate limiting: mechanism count changes are restricted (on mainnet) to once per ~24 hours (7200 blocks).
159+
- Permissions: emission split and count updates require the subnet owner wallet.
160+
- Local chain connectivity: ensure your local chain is running and your SDK points to `network="local"`.

‎docs/subnets/metagraph.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,8 @@ You can access metagraph data through multiple interfaces:
3030

3131
The `btcli` command-line interface provides access to a subset of metagraph information (corresponding to "lite" mode in the SDK). For full metagraph data including weights and bonds, use the Python SDK with `lite=False`.
3232

33+
<!-- Note that if the subnet has multiple incentive mechanisms, you will be prompted to specify the id of the mechanism unless you specify it with the `--mech-id` flag. See [Multiple Incentive Mechanisms Within Subnets](../subnets/understanding-multiple-mech-subnets). -->
34+
3335
```bash
3436
# Dump metagraph subset to file (lite mode)
3537
btcli subnets metagraph --netuid 14 --network finney \

0 commit comments

Comments
 (0)