From 1ffbe6f2462d0567d282d53c0c3f3e75512b62ff Mon Sep 17 00:00:00 2001 From: Dera Okeke Date: Thu, 29 Jan 2026 12:17:08 +0100 Subject: [PATCH 1/2] doc updates --- docs/resources/glossary.md | 12 +++ docs/subnets/index.md | 127 +++++++++++++++++++++++ docs/subnets/understanding-subnets.md | 24 +++-- docs/tutorials/basic-subnet-tutorials.md | 10 +- sidebars.js | 2 +- 5 files changed, 158 insertions(+), 17 deletions(-) create mode 100644 docs/subnets/index.md diff --git a/docs/resources/glossary.md b/docs/resources/glossary.md index 87128e451e..9328bb6d7a 100644 --- a/docs/resources/glossary.md +++ b/docs/resources/glossary.md @@ -614,6 +614,16 @@ The process of registering keys with a subnet and purchasing a UID slot. **See also:** [Subnet Miners](../miners/), [Subnet Validators](../validators/), [Working with Subnets](../subnets/working-with-subnets.md) +### Relative stake weight + +A validator's relative stake weight in a subnet is the validator's individual stake expressed as a proportion of the total stake held by all active validators within the subnet. It measures a single validator's "share" of the total pool and directly determines how much influence their votes have on miner scoring and the distribution of network emissions. + +A validator's relative influence in a subnet is calculated as: + +$$ +\text{Relative Stake Weight} = \frac{\text{Stake Weight}_i}{\sum_{v \in \text{validators}} \text{Stake Weight}_v} +$$ + ### Root Proportion For a given subnet, the relative weight of TAO staked to validators on that subnet through staking to the Root Subnet (rather than directly to the subnet). Mathematically it is the ratio of stake on Root to the total issuance of the subnet's alpha token. @@ -699,6 +709,8 @@ $$ \text{Relative Stake Weight} = \frac{\text{Stake Weight}_i}{\sum_{v \in \text{validators}} \text{Stake Weight}_v} $$ +See [Relative stake weight](#relative-stake-weight). + **Consensus Power:** - **Weight Setting**: Higher stake weight means more influence when setting weights diff --git a/docs/subnets/index.md b/docs/subnets/index.md new file mode 100644 index 0000000000..f21b4223e2 --- /dev/null +++ b/docs/subnets/index.md @@ -0,0 +1,127 @@ +## Emissions and Earnings + +### Root Subnet Earnings + +Root validators earn through a dividend mechanism: + +- **Root Dividends**: A portion of each subnet's Alpha emissions is allocated to root validators based on the subnet's "root proportion" +- **Root Proportion**: Determined by the amount of TAO staked on the root subnet relative to the subnet's total value +- **Distribution**: Root dividends are distributed proportionally to root validators based on their stake +- **Claiming**: Root validators can claim their dividends, with options to: + - Swap Alpha to TAO and stake it back on root (default) + - Keep Alpha as-is + - Keep Alpha for specific subnets while swapping others + +### Mining Subnet Earnings + +Mining subnets distribute emissions through a 50/50 split: + +- **Miner Incentive (50%)**: Distributed to miners based on validator consensus on their utility +- **Validator Dividends (50%)**: Distributed to validators based on their bonds with miners and consensus participation +- **Root Proportion**: A portion of validator dividends goes to root validators based on the subnet's root proportion +- **Owner Cut**: Subnet owners receive a percentage cut of emissions (configurable) + +Earnings are calculated using Yuma Consensus, which: + +- Rewards validators for agreeing with stake-weighted consensus +- Rewards miners based on consensus-clipped validator weights +- Penalizes validators who weight above consensus +- Uses exponential moving averages for bonds to reward early discovery + +## Mining and Validating + +### Mining (Servers) + +Miners in non-root subnets: + +- **Role**: Provide the actual utility or service that the subnet is designed for +- **Registration**: Must burn TAO (converted to Alpha) to register +- **Earnings**: Receive 50% of subnet emissions based on validator consensus +- **Consensus**: Validators evaluate miner performance and assign weights +- **Activity**: Must remain active and serve requests to maintain their position + +### Validating + +Validators exist in both root and mining subnets: + +**Root Validators:** + +- Evaluate and weight other subnets (not individual miners) +- Set weights on subnets to indicate their perceived value +- Earn dividends from all subnets based on root proportion +- Must have sufficient stake to maintain position + +**Mining Subnet Validators:** + +- Evaluate and weight miners within their subnet +- Set weights on miners to indicate their perceived utility +- Earn 50% of subnet emissions (minus root proportion) +- Bond with miners using exponential moving averages +- Consensus-clipping prevents manipulation by penalizing weights above consensus + +## Registration and Creation + +### Subnet Creation + +Creating a new subnet requires: + +1. **Lock Cost**: Pay a TAO lock amount that increases with each subnet creation +2. **Pruning**: If the subnet limit is reached, the lowest-performing subnet is dissolved and its netuid is recycled +3. **Initial Pool**: A portion of the lock amount goes into the subnet's TAO/Alpha liquidity pool +4. **Recycle**: The remaining lock amount (after pool allocation) is recycled back into the network +5. **Owner**: The creator becomes the subnet owner and can configure parameters + +The lock cost formula: + +- Starts at minimum lock amount +- Doubles with each subnet creation +- Decreases over time based on blocks since last creation +- Minimum lock amount is enforced + +### Registration to Subnets + +**Root Subnet Registration:** + +- Free (no burn required) +- Requires sufficient stake on the hotkey +- If full, replaces the validator with lowest stake +- Automatically sets registrant as delegate + +**Mining Subnet Registration:** + +- Requires burning TAO tokens +- Burn amount is converted to Alpha through the subnet's AMM +- The burned Alpha reduces the subnet's AlphaOut supply +- Registration can be rate-limited per block and per interval +- If subnet is full, replaces the lowest-performing UID + +### Burn vs Recycle + +Both mechanisms reduce Alpha supply but serve different purposes: + +**Burn:** + +- Permanently removes Alpha from circulation +- Reduces SubnetAlphaOut +- Used during registration to enter a subnet +- Tokens are destroyed and cannot be recovered + +**Recycle:** + +- Returns Alpha to the network's recycling pool +- Reduces SubnetAlphaOut +- Used when exiting a subnet or managing supply +- Recycled tokens can be used for future registrations +- Applied during subnet creation for excess lock amounts + +The choice between burn and recycle affects the subnet's token economics: + +- Burn reduces total supply permanently (deflationary) +- Recycle maintains supply but removes it from active circulation (temporary deflationary) + +Both operations require: + +- Sufficient stake in Alpha on the subnet +- The subnet must have subtoken enabled +- Cannot be performed on root subnet +- Must have sufficient liquidity in SubnetAlphaOut diff --git a/docs/subnets/understanding-subnets.md b/docs/subnets/understanding-subnets.md index 368edc0c97..73aede62a4 100644 --- a/docs/subnets/understanding-subnets.md +++ b/docs/subnets/understanding-subnets.md @@ -7,7 +7,7 @@ import useBaseUrl from '@docusaurus/useBaseUrl'; # Understanding Subnets -In Bittensor, a subnet is an incentive-based competition marketplace that produces a specific kind of digital commodity related to artificial intelligence. It consists of a community of miners that produce the commodity, and a community of validators that measure the miners' work to ensure its quality. Often, parties that serve as validators do so in order to run applications that make use of the services provided by the miners. +In Bittensor, a subnet is an incentive-based competition marketplace that produces a specific kind of digital commodity related to artificial intelligence. It consists of a community of miners that produce the commodity, and a community of validators that measure the miners' work to ensure its quality. Often , parties that serve as validators do so in order to run applications that make use of the services provided by the miners. Emissions of TAO (τ) from Bittensor—are distributed among miners and validators based on their performance within subnets, and based on the relative performance of subnets within Bittensor. @@ -15,8 +15,8 @@ Emissions of TAO (τ) from Bittensor—are distributed among miners and vali The illustration below shows the main components of a subnet: -1. A subnet's [incentive mechanism](../learn/anatomy-of-incentive-mechanism) defines the work that miners must perform, and the work that validators must perform to evaluate the miners' work. The incentive mechanism is unique to the subnet, and maintained off-chain by the subnet creator in the form of a code-repository that defines the interface for miners and validators to participate. For example, see [Subnet 1](https://github.com/macrocosm-os/prompting). -2. **Miners** perform some useful work as defined in the subnet's incentive mechanism. For example, in Subnet 1, miners serve chat prompt completion. +1. A subnet's [incentive mechanism](../learn/anatomy-of-incentive-mechanism) defines the work that miners must perform, and the work that validators must perform to evaluate the miners' work. The incentive mechanism is unique to the subnet, and maintained off-chain by the subnet creator in the form of a code-repository that defines the interface for miners and validators to participate. For example, see [Subnet 14](https://github.com/latent-to/taohash). +2. **Miners** perform some useful work as defined in the subnet's incentive mechanism. In Subnet 14, miners perform Proof-of-Work to earn direct Bitcoin/Bitcoin Cash rewards alongside Alpha tokens. 3. **Validators** independently evaluate the task performed by the subnet miners, according to standards defined by the subnet's incentive mechanism. 4. Validators each score the performance of each miner over the most recent time period. The matrix of these scores, by each validator for each miner, serves as input to **Yuma Consensus**. 5. The Yuma Consensus algorithm operates on-chain, and determines emissions to miners, validators, and subnet creators across the platform, based on performance. @@ -49,7 +49,7 @@ These subnet tokens contrast with TAO ($$\tau$$), the token of the Bittensor net ::: The _price_ of a subnet's alpha token is determined by the ratio of TAO in that subnet's reserve to its alpha in reserve. Alpha currency that is not held in reserve but is which is held in the hotkeys of subnet participants is referred to as _alpha outstanding_. -Run the `btcli subnet list` command with the Dynamic TAO-enabled `btcli` to view information about the subnets and their currency reserves on Bittensor testnet. +Run the `btcli subnet list` command to view information about the subnets and their currency reserves on Bittensor testnet. ```txt ┃ ┃ Price ┃ Market Cap ┃ ┃ ┃ ┃ ┃ @@ -109,23 +109,27 @@ See [Emissions](../learn/emissions.md). ## Decentralized evaluation of subnets -The relative value or _weight_ of subnets within Bittensor is critically important as it determines emissions to different subnets and their participant miners and validators. Prior to Dynamic TAO, relative weight among subnets within the Bittensor network were determined by Yuma Consensus over the evaluations of the Root Network validators. This gives a fundamentally centralizing role to the holders of Root Network validator keys. +The relative value or _weight_ of subnets within Bittensor is critically important as it determines emissions to different subnets and their participant miners and validators. This weight is determined organically according to net TAO flows into and out of each subnet. -In Dynamic TAO, the relative weight is determined organically according to net TAO flows into and out of each subnet. As TAO-holders stake TAO into subnets in exchange for the subnet-specific alpha, they are essentially 'voting with their TAO' for the value of the subnet. Subnets with more staking than unstaking receive higher emissions, while subnets with net outflows receive reduced or zero emissions. This flow-based model rewards subnets that attract genuine user engagement. In return, stakers extract a share of the subnet's emissions. +As TAO-holders stake TAO into subnets in exchange for the subnet-specific alpha, they are essentially 'voting with their TAO' for the value of the subnet. Subnets with more staking than unstaking receive higher emissions, while subnets with net outflows receive reduced or zero emissions. This flow-based model rewards subnets that attract genuine user engagement. In return, stakers extract a share of the subnet's emissions. :::tip Flow-Based Model Active As of November 2025, emissions are based on net TAO flows (staking minus unstaking) rather than token prices. See [Emissions](../learn/emissions.md) for details. ::: -## Subnet Zero +## Root subnet -In Dynamic TAO, Subnet Zero—or _Root Subnet_—is a special subnet. It is the only subnet that does not have its own $\alpha$ currency. No miners can register on subnet zero, and no validation work is performed. However validators can register, and $\tau$-holders can stake to those validators, as with any other subnet. This offers a mechanism for $\tau$-holders to stake $\tau$ into validators in a subnet-agnostic way. This works because the weight of a validator in a subnet includes both their share of that subnet's $\alpha$ and their share of TAO staked into the root subnet. +Root subnet—or _Subnet Zero_—is a special subnet on Bittensor. It is the only subnet without its own alpha currency. No miners can register on subnet zero, and no validation work is performed. However validators can register on the root subnet, and TAO holders can stake to those validators, as with any other subnet. This offers a mechanism for TAO holders to stake TAO into validators in a subnet-agnostic way. This works because the weight of a validator in a subnet includes both their share of that subnet's TAO and their share of TAO staked into the root subnet. + +::: Staking on Root +Staking to a Root validator provides exposure to their entire network performance, allowing you to earn rewards across every subnet where that validator is active. You can choose to accumulate these dividends as subnet alpha or have them automatically converted to TAO. For more information, see [root claims](../staking-and-delegation/root-claims/index.md) +::: Over time, the emissions generated by TAO staked into Subnet Zero will decrease, relative to stake held in the alpha currency of active subnets. See [Note on evolution of Bittensor token economy](../learn/emissions.md#note-on-evolution-of-bittensor-token-economy). ## Validator stake weight -A validator's stake weight in a subnet equals their alpha stake plus their TAO stake times the `tao_weight` parameter: +A validator's stake weight in a subnet equals their alpha stake plus their TAO stake multiplied by the `tao_weight` parameter: $$ @@ -138,7 +142,7 @@ $$ A validator's stake weight in Subnet Zero is simply their staked TAO. ::: -A validator's relative stake weight (their stake weight over the total stake weight) in a subnet determines their voting power when evaluating miners, and determines their share of emissions. +A validator's [relative stake weight](../resources/glossary.md#relative-stake-weight) in a subnet determines their voting power when evaluating miners, and determines their share of emissions. $$ diff --git a/docs/tutorials/basic-subnet-tutorials.md b/docs/tutorials/basic-subnet-tutorials.md index 41c8ff8a94..baafbbe0e5 100644 --- a/docs/tutorials/basic-subnet-tutorials.md +++ b/docs/tutorials/basic-subnet-tutorials.md @@ -4,10 +4,8 @@ title: "Basic Subnet Tutorials" # Basic Subnet Tutorials -If you are new to subnets, start with these beginner tutorials with [Bittensor Subnet Template](https://github.com/opentensor/bittensor-subnet-template/blob/main/README.md): - -- **Running locally**: Follow the step-by-step instructions described in this tutorial: [Running Subnet Locally](https://github.com/opentensor/bittensor-subnet-template/blob/main/docs/running_on_staging.md). -- **Running on Bittensor testchain**: Follow the step-by-step instructions described in this tutorial: [Running on the Testchain](https://github.com/opentensor/bittensor-subnet-template/blob/main/docs/running_on_testnet.md). -- **Running on Bittensor mainchain**: Follow the step-by-step instructions described in this tutorial: [Running on the Mainchain](https://github.com/opentensor/bittensor-subnet-template/blob/main/docs/running_on_mainnet.md). - +If you are new to subnets, start with these beginner tutorials with [Bittensor Subnet Template](https://github.com/opentensor/subnet-template/blob/main/README.md): +- **Running locally**: Follow the step-by-step instructions described in this tutorial: [Running Subnet Locally](../local-build/create-subnet.md). +- **Running on Bittensor testchain**: Follow the step-by-step instructions described in this tutorial: [Running on the Testchain](https://github.com/opentensor/subnet-template/blob/main/README.md). +- **Running on Bittensor mainchain**: Follow the step-by-step instructions described in this tutorial: [Running on the Mainchain](../subnets/create-a-subnet.md). diff --git a/sidebars.js b/sidebars.js index dd26ca019b..5734ce0e53 100644 --- a/sidebars.js +++ b/sidebars.js @@ -167,7 +167,6 @@ const sidebars = { collapsible: true, collapsed: true, items: [ - "subnets/metagraph", "subnets/create-a-subnet", { type: "category", @@ -182,6 +181,7 @@ const sidebars = { "subnets/working-with-subnets", "subnets/managing-mechanisms-with-sdk", "subnets/managing-mechanisms-btcli", + "subnets/metagraph", "subnets/uid-trimming", "subnets/subnet-deregistration", "subnets/walkthrough-prompting", From d9fcae0d853b831c21686a0fa4c1825e6f4c96ca Mon Sep 17 00:00:00 2001 From: Dera Okeke Date: Thu, 29 Jan 2026 12:23:53 +0100 Subject: [PATCH 2/2] fixed commit --- docs/subnets/index.md | 127 ------------------------------------------ 1 file changed, 127 deletions(-) delete mode 100644 docs/subnets/index.md diff --git a/docs/subnets/index.md b/docs/subnets/index.md deleted file mode 100644 index f21b4223e2..0000000000 --- a/docs/subnets/index.md +++ /dev/null @@ -1,127 +0,0 @@ -## Emissions and Earnings - -### Root Subnet Earnings - -Root validators earn through a dividend mechanism: - -- **Root Dividends**: A portion of each subnet's Alpha emissions is allocated to root validators based on the subnet's "root proportion" -- **Root Proportion**: Determined by the amount of TAO staked on the root subnet relative to the subnet's total value -- **Distribution**: Root dividends are distributed proportionally to root validators based on their stake -- **Claiming**: Root validators can claim their dividends, with options to: - - Swap Alpha to TAO and stake it back on root (default) - - Keep Alpha as-is - - Keep Alpha for specific subnets while swapping others - -### Mining Subnet Earnings - -Mining subnets distribute emissions through a 50/50 split: - -- **Miner Incentive (50%)**: Distributed to miners based on validator consensus on their utility -- **Validator Dividends (50%)**: Distributed to validators based on their bonds with miners and consensus participation -- **Root Proportion**: A portion of validator dividends goes to root validators based on the subnet's root proportion -- **Owner Cut**: Subnet owners receive a percentage cut of emissions (configurable) - -Earnings are calculated using Yuma Consensus, which: - -- Rewards validators for agreeing with stake-weighted consensus -- Rewards miners based on consensus-clipped validator weights -- Penalizes validators who weight above consensus -- Uses exponential moving averages for bonds to reward early discovery - -## Mining and Validating - -### Mining (Servers) - -Miners in non-root subnets: - -- **Role**: Provide the actual utility or service that the subnet is designed for -- **Registration**: Must burn TAO (converted to Alpha) to register -- **Earnings**: Receive 50% of subnet emissions based on validator consensus -- **Consensus**: Validators evaluate miner performance and assign weights -- **Activity**: Must remain active and serve requests to maintain their position - -### Validating - -Validators exist in both root and mining subnets: - -**Root Validators:** - -- Evaluate and weight other subnets (not individual miners) -- Set weights on subnets to indicate their perceived value -- Earn dividends from all subnets based on root proportion -- Must have sufficient stake to maintain position - -**Mining Subnet Validators:** - -- Evaluate and weight miners within their subnet -- Set weights on miners to indicate their perceived utility -- Earn 50% of subnet emissions (minus root proportion) -- Bond with miners using exponential moving averages -- Consensus-clipping prevents manipulation by penalizing weights above consensus - -## Registration and Creation - -### Subnet Creation - -Creating a new subnet requires: - -1. **Lock Cost**: Pay a TAO lock amount that increases with each subnet creation -2. **Pruning**: If the subnet limit is reached, the lowest-performing subnet is dissolved and its netuid is recycled -3. **Initial Pool**: A portion of the lock amount goes into the subnet's TAO/Alpha liquidity pool -4. **Recycle**: The remaining lock amount (after pool allocation) is recycled back into the network -5. **Owner**: The creator becomes the subnet owner and can configure parameters - -The lock cost formula: - -- Starts at minimum lock amount -- Doubles with each subnet creation -- Decreases over time based on blocks since last creation -- Minimum lock amount is enforced - -### Registration to Subnets - -**Root Subnet Registration:** - -- Free (no burn required) -- Requires sufficient stake on the hotkey -- If full, replaces the validator with lowest stake -- Automatically sets registrant as delegate - -**Mining Subnet Registration:** - -- Requires burning TAO tokens -- Burn amount is converted to Alpha through the subnet's AMM -- The burned Alpha reduces the subnet's AlphaOut supply -- Registration can be rate-limited per block and per interval -- If subnet is full, replaces the lowest-performing UID - -### Burn vs Recycle - -Both mechanisms reduce Alpha supply but serve different purposes: - -**Burn:** - -- Permanently removes Alpha from circulation -- Reduces SubnetAlphaOut -- Used during registration to enter a subnet -- Tokens are destroyed and cannot be recovered - -**Recycle:** - -- Returns Alpha to the network's recycling pool -- Reduces SubnetAlphaOut -- Used when exiting a subnet or managing supply -- Recycled tokens can be used for future registrations -- Applied during subnet creation for excess lock amounts - -The choice between burn and recycle affects the subnet's token economics: - -- Burn reduces total supply permanently (deflationary) -- Recycle maintains supply but removes it from active circulation (temporary deflationary) - -Both operations require: - -- Sufficient stake in Alpha on the subnet -- The subnet must have subtoken enabled -- Cannot be performed on root subnet -- Must have sufficient liquidity in SubnetAlphaOut