Subsub to mechanism

docs/learn/anatomy-of-incentive-mechanism.md

@@ -29,7 +29,8 @@ Subnets can implement multiple incentive mechanisms to evaluate different aspect
 - **Enable specialized competition**: Miners can excel in specific mechanisms that match their capabilities
 - **Provide transparent control**: All emission distributions and mechanism configurations are visible on-chain
 
-For detailed information about implementing and managing multiple incentive mechanisms, see [Multiple Incentive Mechanisms Within Subnets](../subnets/understanding-sub-subnets).
+
+For detailed information about implementing and managing multiple incentive mechanisms, see [Multiple Incentive Mechanisms Within Subnets](../subnets/understanding-multiple-mech-subnets).
 
 ## Subnet creator responsibilities
 

docs/resources/glossary.md

@@ -268,7 +268,8 @@ A portion of the TAO emission received by the subnet miners when they provide va
 
 A system that drives the behavior of subnet miners and governs consensus among subnet validators in a Bittensor subnet. Each subnet has one or more incentive mechanisms, which should be designed carefully to promote desired behaviors and penalize undesired ones. When multiple incentive mechanisms are used, each operates independently with separate bond pools for Yuma Consensus calculations, allowing subnet creators to distribute emissions across different types of work or evaluation criteria.
 
-**See also:** [Anatomy of Incentive Mechanism](../learn/anatomy-of-incentive-mechanism.md), [Multiple Incentive Mechanisms Within Subnets](../subnets/understanding-sub-subnets.md), [Understanding Subnets](../subnets/understanding-subnets.md)
+
+**See also:** [Anatomy of Incentive Mechanism](../learn/anatomy-of-incentive-mechanism.md), [Multiple Incentive Mechanisms Within Subnets](../subnets/understanding-multiple-mech-subnets), [Understanding Subnets](../subnets/understanding-subnets.md)
 
 ### Issuance
 
@@ -324,7 +325,8 @@ A data structure that contains comprehensive information about the current state
 
 A feature that allows subnets to implement multiple independent evaluation systems within a single subnet. Each mechanism operates with its own bond pool for Yuma Consensus calculations, enabling subnet creators to distribute emissions across different types of work or evaluation criteria. Validators must evaluate miners separately for each mechanism, and miner performance in one mechanism does not affect their rating in another.
 
-**See also:** [Multiple Incentive Mechanisms Within Subnets](../subnets/understanding-sub-subnets.md), [Anatomy of Incentive Mechanism](../learn/anatomy-of-incentive-mechanism.md)
+
+**See also:** [Multiple Incentive Mechanisms Within Subnets](../subnets/understanding-multiple-mech-subnets), [Anatomy of Incentive Mechanism](../learn/anatomy-of-incentive-mechanism.md)
 
 ### Miner Deregistration
 
@@ -611,7 +613,9 @@ The task-performing entity within a Bittensor subnet. A subnet miner is a type o
 
 The individual or entity responsible for defining the specific digital task to be performed by subnet miners, implementing one or more incentive mechanisms, and providing sufficient documentation for participation in the subnet. Subnet creators can configure multiple incentive mechanisms to distribute emissions across different types of work or evaluation criteria.
 
-**See also:** [Create a Subnet](../subnets/create-a-subnet.md), [Subnet Creators btcli Guide](../subnets/subnet-creators-btcli-guide.md), [Multiple Incentive Mechanisms Within Subnets](../subnets/understanding-sub-subnets.md)
+
+**See also:** [Create a Subnet](../subnets/create-a-subnet.md), [Subnet Creators btcli Guide](../subnets/subnet-creators-btcli-guide.md), [Multiple Incentive Mechanisms Within Subnets](../subnets/understanding-multiple-mech-subnets)
+
 
 ### Subnet Protocol
 
@@ -623,13 +627,17 @@ A unique set of rules defining interactions between subnet validators and miners
 
 A component of an incentive mechanism that defines how subnet miners' responses are evaluated, aiming to align subnet miner behavior with the subnet's goals and user preferences. It is a mathematical object that converts miner responses into numerical scores, enabling continuous improvement and competition among miners. When multiple incentive mechanisms are used, each has its own scoring model for independent evaluation.
 
-**See also:** [Anatomy of Incentive Mechanism](../learn/anatomy-of-incentive-mechanism.md), [Multiple Incentive Mechanisms Within Subnets](../subnets/understanding-sub-subnets.md), [Understanding Subnets](../subnets/understanding-subnets.md)
+
+**See also:** [Anatomy of Incentive Mechanism](../learn/anatomy-of-incentive-mechanism.md), [Multiple Incentive Mechanisms Within Subnets](../subnets/understanding-multiple-mech-subnets), [Understanding Subnets](../subnets/understanding-subnets.md)
+
 
 ### Subnet Task
 
 A key component of any incentive mechanism that defines the work the subnet miners will perform. The task should be chosen to maximize subnet miner effectiveness at the intended use case for the subnet. When multiple incentive mechanisms are used within a subnet, each mechanism can define different tasks for miners to perform.
 
-**See also:** [Understanding Subnets](../subnets/understanding-subnets.md), [Anatomy of Incentive Mechanism](../learn/anatomy-of-incentive-mechanism.md), [Multiple Incentive Mechanisms Within Subnets](../subnets/understanding-sub-subnets.md)
+
+**See also:** [Understanding Subnets](../subnets/understanding-subnets.md), [Anatomy of Incentive Mechanism](../learn/anatomy-of-incentive-mechanism.md), [Multiple Incentive Mechanisms Within Subnets](../subnets/understanding-multiple-mech-subnets)
+
 
 ### Subnet Weights
 
@@ -955,15 +963,18 @@ The directory path where the generated Bittensor wallets are stored locally on t
 
 A matrix formed from the ranking weight vectors of all subnet validators in a subnet, used as input for the Yuma Consensus module to calculate emissions to that subnet. When multiple incentive mechanisms are used, each mechanism has its own weight matrix for independent consensus calculations.
 
-**See also:** [Yuma Consensus](../learn/yuma-consensus.md), [Consensus-Based Weights](../concepts/consensus-based-weights.md), [Multiple Incentive Mechanisms Within Subnets](../subnets/understanding-sub-subnets.md)
+
+**See also:** [Yuma Consensus](../learn/yuma-consensus.md), [Consensus-Based Weights](../concepts/consensus-based-weights.md), [Multiple Incentive Mechanisms Within Subnets](../subnets/understanding-multiple-mech-subnets)
+
 
 ### Weight Vector
 
 A vector maintained by each subnet validator, with each element representing the weight assigned to a subnet miner based on its performance. When multiple incentive mechanisms are used, validators maintain separate weight vectors for each mechanism.
 
 The ranking weight vectors for each subnet are transmitted to the blockchain, where they combine to form the [weight matrix](#weight-matrix) (or matrices when multiple mechanisms are used) that is input for Yuma Consensus.
 
-**See also:** [Consensus-Based Weights](../concepts/consensus-based-weights.md), [Yuma Consensus](../learn/yuma-consensus.md), [Multiple Incentive Mechanisms Within Subnets](../subnets/understanding-sub-subnets.md)
+**See also:** [Consensus-Based Weights](../concepts/consensus-based-weights.md), [Yuma Consensus](../learn/yuma-consensus.md), [Multiple Incentive Mechanisms Within Subnets](../subnets/understanding-multiple-mech-subnets)
+
 
 ## Y
 

docs/subnets/understanding-multiple-mech-subnets.md

@@ -0,0 +1,133 @@
+---
+title: "Multiple Incentive Mechanisms Within Subnets"
+---
+
+import ThemedImage from '@theme/ThemedImage';
+import useBaseUrl from '@docusaurus/useBaseUrl';
+
+#  Multiple Incentive Mechanisms Within Subnets
+
+This page explores how subnets can implement multiple incentive mechanisms to distribute emissions across different evaluation criteria.
+
+For an introduction to incentive mechanisms in general, see [Understanding Incentive Mechanisms](../learn/anatomy-of-incentive-mechanism). For the basics of subnets, miners, validators, and the blockchain, see [Components of the Bittensor platform](../learn/neurons).
+
+Historically, each subnet operates with a single **incentive mechanism**, a function that validators run to assign weights to miners based on the value of their work. Subnets can now support **multiple incentive mechanisms**, allowing a subnet creator to apportion the subnet's emissions across different evaluation criteria, each running Yuma Consensus _independently_ with separate bond pools to evaluate miners' performance on distinct tasks.
+
+Each miner receives emissions separately from each incentive mechanism, so a miner's performance in one mechanism does not affect their rating in another, and their emissions for each epoch are summed across all mechanisms. Validators receive dividends as a weighted sum of their performance across all incentive mechanisms - they cannot choose which mechanisms to validate, and if they don't validate all mechanisms, they receive proportionally reduced emissions. Multiple incentive mechanisms don't change the total emissions to a subnet, but create a way for subnet creators to distribute those emissions to miners working on different tasks. This mechanism affords subnet creators a transparent, on-chain way to exercise fine-grained control over the work they are incentivizing, keeping miner effort focused on work that is most needed at a time.
+
+Each incentive mechanism has its own:
+
+- **Weight matrix**: Each validator sets weights for each miner on each of the subnet's incentive mechanisms.
+- **Independent bond pools**: Each mechanism maintains separate bonding relationships for Yuma Consensus calculations.
+- **Independent emissions**: Since they depend on weights set by validators, a miner's emissions from each mechanism are independent.
+- **Transparent on-chain data**: All incentive mechanism configurations and the flow of emissions are visible on-chain.
+- **Emission distribution**: Subnet creators can control what percentage of total emissions goes to each mechanism using the `sudo_set_subsubnet_emission_split` extrinsic. <!-- See: subtensor/pallets/admin-utils/src/lib.rs:1891-1910 -->
+
+### Takeaways
+
+1. **Same Validators, Same Stake**: All validators participate in all incentive mechanisms within a subnet with identical stake weights.
+2. **Same Miners**: All miners registered on a subnet can participate in any or all of its incentive mechanisms.
+3. **Owner-Controlled Proportions**: The holder of the _subnet creator_ key sets the emission distribution among incentive mechanisms.
+4. **Separate Bond Pools**: Each incentive mechanism maintains separate bonding relationships for independent Yuma Consensus calculations.
+
+## What Should Stakers Know?
+
+**Core Impact:**
+
+- **No change to your staking mechanics**: Your stake is delegated to a validator on a subnet, and applies across all incentive mechanisms equally.
+- **Same total emissions**: The subnet's total emissions remain unchanged - multiple mechanisms only redistribute these emissions internally among miners and validators.
+- **Transparent allocation**: All emission proportions are visible on-chain, so you can see exactly how subnet owners are distributing emissions.
+
+**What This Means for Your Strategy:**
+
+- **No immediate action required**: Your existing staking strategy doesn't need to change
+- **Enhanced monitoring**: You may want to track individual mechanism performance to understand subnet health
+- **Risk assessment**: Factor in incentive mechanism design when evaluating subnet quality
+- **Community oversight**: Use transparency to hold subnet owners accountable for fair emission distribution
+
+## What Should Miners Know?
+
+**Automatic Participation:**
+
+- **No separate registration**: When you register for a subnet, you are eligible to participate in any of its incentive mechanisms
+- **Same UID across all mechanisms**: You use the same UID for all incentive mechanisms within a subnet
+
+**Performance Tracking:**
+
+- **Independent scoring**: Your performance is independent across different mechanisms, e.g. mechanism 0 doesn't affect your rating in mechanism 1.
+- **Separate incentive columns**: You'll see individual incentive amounts for each mechanism in metagraph data.
+- **Cumulative emissions**: Your total emissions = sum of emissions from all mechanisms where you participate.
+
+## What Should Validators Know?
+
+### Core Changes
+
+- **Separate weight setting**: You must set weights independently for each incentive mechanism.
+- **Independent evaluation**: Each mechanism requires separate assessment according to its specific criteria.
+- **Separate bond pools**: Each mechanism maintains independent bonding relationships for Yuma Consensus calculations.
+- **Same stake weight**: Your stake weight is identical across all mechanisms - no additional stake required.
+- **Weighted dividend calculation**: Your dividends are calculated as a weighted sum of your performance across all mechanisms. If you don't validate on all mechanisms, you will receive proportionally reduced emissions.
+
+### Operational Changes
+
+**1. Evaluation Workload:**
+
+- **Multiple assessments**: You must evaluate miners separately for each mechanism's tasks
+- **Different criteria**: Each mechanism may have distinct evaluation standards
+
+**2. Data Structure Changes:**
+
+- **Two-dimensional weights**: Weights are now set for each miner on each mechanism.
+- **Separate incentive tracking**: Each mechanism tracks incentives independently
+- **Extended metagraph**: New columns for mechanism weights and incentives
+
+## What Should Subnet Creators/Developers Know?
+
+### Core Changes
+
+- **Emission distribution**: You can control what percentage of total emissions goes to each incentive mechanism using the `sudo_set_subsubnet_emission_split` extrinsic. When the number of mechanisms is set, the emission distribution is reset to an even split, but you can set it again with custom proportions.
+
+  :::info
+  The `sudo_set_subsubnet_emission_split` extrinsic accepts an optional vector parameter. If the parameter is `None`, the distribution is set to an even split. When it's not `None`, it reflects the proportion of emissions each mechanism gets. The proportion is calculated as `value / 65535`. For example, in a subnet with two mechanisms and vector `[13107, 52428]`, mechanism 0 gets 20% and mechanism 1 gets 80%. <!-- See: subtensor/pallets/subtensor/src/subnets/subsubnet.rs:173-175 -->
+  :::
+
+- **Incentive mechanism design**: You define the specific tasks and evaluation criteria for each mechanism
+- **Transparent configuration**: All mechanism settings are visible on-chain for community oversight
+- **Single subnet slot**: No need to register multiple subnets for multiple competitions
+- **Immediate mechanism number setting**: The number of mechanisms is set immediately when changed. <!-- See: subtensor/pallets/subtensor/src/subnets/subsubnet.rs:91-116 -->
+- **Rate limiting**: Subnet owners can set the number of mechanisms once per 7200 blocks to prevent frequent changes. <!-- See: subtensor/pallets/subtensor/src/lib.rs:1842-1844 -->
+
+:::tip
+Ensure proportions sum to 100% when setting them, or the request will be rejected.
+:::
+
+## Example Emissions Split
+
+For each subnet, the subnet creator keeps 18% of emissions, 41% is allocated to miners, and 41% to validators and their stakers, unless the subnet creator has reduced their take. Of the 41% that goes to miners and validators, here is an estimated emission distribution across three incentive mechanisms for each 100 $\tau$ earned on the subnet:
+
+- Mechanism 0 (60%): 100 $\tau$ _.41 _ .6 = 24.6
+- Mechanism 1 (30%): 100 $\tau$ _.41 _ .3 = 12.3
+- Mechanism 2 (10%): 100 $\tau$ _.41 _ .1 = 4.1
+
+:::info Setting Custom Proportions
+To achieve the above distribution, the subnet owner would submit the `sudo_set_subsubnet_emission_split` extrinsic with the vector `[39321, 19660, 6554]` (calculated as 60% × 65535, 30% × 65535, 10% × 65535).
+:::
+
+Note that a miner who excels in mechanism 0 but performs poorly in others might receive more emissions than a miner who performs moderately across all mechanisms, depending on the emission proportions and their relative performance.
+
+## On-Chain Data Structure
+
+Multiple incentive mechanisms extend the existing metagraph with additional columns:
+
+```
+UID | Hotkey | Stake | Mechanism 0 Weights | Mechanism 1 Weights | Mechanism 0 Incentive | Mechanism 1 Incentive
+-----|--------|-------|---------------------|---------------------|----------------------|----------------------
+123  | 5ABC...| 1000  | [0.3, 0.2, 0.1...] | [0.1, 0.4, 0.2...] | 0.05 τ               | 0.02 τ
+456  | 7DEF...| 800   | [0.2, 0.3, 0.2...] | [0.2, 0.3, 0.1...] | 0.03 τ               | 0.04 τ
+```
+
+## Backward Compatibility
+
+- Existing subnets continue with only one incentive mechanism (mechanism 0) collecting all emissions by default
+- All existing API calls default to mechanism 0
+- No breaking changes to current functionality

sidebars.js

@@ -51,7 +51,8 @@ const sidebars = {
         "resources/questions-and-answers",
         "subnets/understanding-subnets",
         "learn/anatomy-of-incentive-mechanism",
-        "subnets/understanding-sub-subnets",
+
+        "subnets/understanding-multiple-mech-subnets",
         "learn/neurons",
 
         "learn/emissions",