From b68b8b31ba4233882eec8493d87a12803f134c3b Mon Sep 17 00:00:00 2001 From: Dera Okeke Date: Tue, 15 Jul 2025 23:43:44 +0100 Subject: [PATCH 01/12] wallet creation updates --- docs/working-with-keys.md | 89 +++++++++++++++++++++++++++++++++------ 1 file changed, 75 insertions(+), 14 deletions(-) diff --git a/docs/working-with-keys.md b/docs/working-with-keys.md index 9a18e1048..927be555f 100644 --- a/docs/working-with-keys.md +++ b/docs/working-with-keys.md @@ -4,6 +4,8 @@ title: "Creating/Importing a Bittensor Wallet" import ThemedImage from '@theme/ThemedImage'; import useBaseUrl from '@docusaurus/useBaseUrl'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; # Creating/Importing a Bittensor Wallet @@ -23,11 +25,49 @@ The most critical operational goal when handling Bittensor wallets is to avoid l ## Creating a wallet with `btcli` -### Creating a coldkey-only wallet + + +If you plan to validate or mine in a subnet, you must have both a coldkey and a hotkey. If you already have a coldkey, you can [create a new hotkey](?create-wallet=hotkey) for it. -Users that will not mine, validate, manage subnets or participate in governance do not need a hotkey, and for simplicity's sake should use coldkey-only wallets. +To create a new coldkey and hotkey, run the following command in the terminal: -Run the following command to create a coldkey-only wallet. +```bash +btcli wallet create --wallet.name --wallet.hotkey +``` + +:::info +Use the below command to generate the hotkey. Replace `` with the name of the coldkey generated above, and `` with a name for your hotkey. + +For example, + +```bash +btcli wallet create --wallet.name test-coldkey --wallet.hotkey test-hotkey +``` + +::: + +Next, you'll be prompted to configure the wallet by setting a password for the coldkey, and choosing the desired mnemonic length. Completing the prompts creates a complete Bittensor wallet by setting up both coldkey and hotkeys. A unique mnemonic is generated for each key and output to the terminal upon creation. + +:::tip Regenerating the wallet keys +Take note of the mnemonics in the response as they are required to regenerate your coldkey and hotkey. To regenerate your coldkey, run the following command in the terminal: + +```sh +btcli wallet regen_coldkey --mnemonic "word1 word2 ... word12" +``` + +Similarly, run the following command in the terminal to regenerate your hotkey: + +```sh +btcli wallet regen_hotkey --mnemonic "word1 word2 ... word12" +``` + +::: + + + +If a user does not intend to mine, validate, manage subnets, or participate in governance, a hotkey is not required. In such cases, a coldkey-only wallet is recommended for simplicity. + +Run the following command to create a coldkey-only wallet: ```bash btcli wallet new_coldkey --wallet.name @@ -44,48 +84,69 @@ You will see the terminal output like the following, which includes your all-imp ```text IMPORTANT: Store this mnemonic in a secure (preferable offline place), as anyone who has possession of this mnemonic can use it to regenerate the key and access your tokens. -The mnemonic to the new coldkey is: paddle disagree swamp hill innocent enemy name shrug produce steak pupil joke -You can use the mnemonic to recreate the key with `btcli` in case it gets lost. +The mnemonic to the new hotkey is: **** *** **** **** ***** **** *** **** **** **** ***** ***** +You can use the mnemonic to recreate the key in case it gets lost. ``` -### Creating a hotkey +:::tip Regenerating the coldkey +Take note of the mnemonic in the response as it is required to regenerate your coldkey. To regenerate your coldkey, run the following command in the terminal: -If you plan to validate or mine in a subnet, you must create both a coldkey and a hotkey. +```sh +btcli wallet regen_coldkey --mnemonic "word1 word2 ... word12" +``` + +::: -First, create a coldkey as described above in the [Creating a coldkey using `btcli`](#creating-a-coldkey-using-btcli). Then, provide this coldkey as a parameter to generate a hotkey. This will pair the hotkey with the coldkey. See below. + + +If you plan to validate or mine in a subnet, you must create both a coldkey and a hotkey. -Use the below command to generate the hotkey. Replace `` with the name of the coldkey generated above, and `` with a name for your hotkey. +Before creating a hotkey, you must have created a coldkey as described in the [creating a coldkey tab](?create-wallet=coldkey). Next, provide this coldkey as a parameter to generate a hotkey. This will pair the hotkey with the coldkey as shown: ```bash btcli wallet new_hotkey --wallet.name --wallet.hotkey ``` +:::info +Use the below command to generate the hotkey. Replace `` with the name of the coldkey generated above, and `` with a name for your hotkey. + For example, ```bash btcli wallet new_hotkey --wallet.name test-coldkey --wallet.hotkey test-hotkey ``` +::: + You will see the terminal log like below. The mnemonic is hidden for security reasons. ```text IMPORTANT: Store this mnemonic in a secure (preferably offline place), as anyone who has possession of this mnemonic can use it to regenerate the key and access your tokens. The mnemonic to the new hotkey is: **** *** **** **** ***** **** *** **** **** **** ***** ***** -You can use the mnemonic to recreate the key in case it gets lost. The command to use to regenerate the key using this mnemonic is: -btcli w regen_hotkey --mnemonic **** *** **** **** ***** **** *** **** **** **** ***** ***** +You can use the mnemonic to recreate the key in case it gets lost. ``` :::tip Regenerating the hotkey -Make a note of the above command option `regen_hotkey` showing how to regenerate your hotkey in case you lose it. +Take note of the mnemonic in the response as it is required to regenerate your hotkey. To regenerate your hotkey, run the following command in the terminal: + +```sh +btcli wallet regen_hotkey --mnemonic "word1 word2 ... word12" +``` + ::: + + + +--- + ### Encrypting the hotkey -By default, the hotkey is not encrypted on the device, whereas the coldkey is encrypted. To encrypt your hotkey, run this command: +By default, a hotkey is not encrypted on the device, whereas the coldkey is encrypted. To encrypt your hotkey, include the `--use-password` in the hotkey creation command as shown: ```bash -btcli wallet new_hotkey --use-password +btcli wallet new_hotkey --use-password --wallet.name test-coldkey --wallet.hotkey test-hotkey ``` ## Creating a wallet using Python From 6b7747855a1d499c921446af26f1d2dcaca7a469 Mon Sep 17 00:00:00 2001 From: Dera Okeke Date: Wed, 16 Jul 2025 23:18:10 +0100 Subject: [PATCH 02/12] wallet creation updates (wip) --- docs/local-build/provision-wallets.md | 26 +++++---- docs/working-with-keys.md | 77 +++++++++++++++++++++++---- 2 files changed, 83 insertions(+), 20 deletions(-) diff --git a/docs/local-build/provision-wallets.md b/docs/local-build/provision-wallets.md index 3ba4cb238..1582258a7 100644 --- a/docs/local-build/provision-wallets.md +++ b/docs/local-build/provision-wallets.md @@ -11,35 +11,42 @@ Every local blockchain is pre-provisioned with an "Alice" account, which is load ## Access the Alice account To access the handy pre-provisioned development "Alice" account on your local chain, use: + ```shell btcli wallet create --uri alice ``` -Confirm Alice's massive $\tau$ bag. +Next, you will be prompted to configure the wallet by setting a name for the wallet's coldkey and hotkey. -```shell - btcli w balance --wallet.name alice --network ws://127.0.0.1:9945 +:::tip +To access the 'Alice' wallet, you must use the assigned coldkey name and include the local subtensor chail URL as shown + +```sh +btcli wallet balance --wallet.name alice --network ws://127.0.0.1:9945 ``` +The following should be returned in the console: + ```console Wallet Coldkey Balance Network: custom - Wallet Name Coldkey Address Free Balance Staked Value Staked (w/slippage) Total Balance Total (w/slippage) + Wallet Name Coldkey Address Free Balance Staked Value Total Balance ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ - alice 5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY τ 999,999.8999 τ 0.0000 τ 0.0000 τ 999,999.8999 τ 999,999.8999 + alice 5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY 1,000,000.0000 τ 0.0000 τ 1,000,000.0000 τ - - Total Balance τ 999,999.8999 τ 0.0000 τ 0.0000 τ 999,999.8999 τ 999,999.8999 + Total Balance 1,000,000.0000 τ 0.0000 τ 1,000,000.0000 τ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ``` +::: + ## Provision wallets -You will need wallets for the different personas, i.e., subnet owner, subnet validator and subnet miner, in the subnet. +You will need wallets for the different personas, i.e., subnet owner, subnet validator and subnet miner, in the subnet. -- The owner wallet creates and controls the subnet. +- The owner wallet creates and controls the subnet. - The validator and miner will be registered to the subnet created by the owner. This ensures that the validator and miner can run the respective validator and miner scripts. ### Create a coldkey-only wallet for the subnet creator role (they do not need a hotkey): @@ -69,6 +76,7 @@ btcli wallet new_hotkey \ btcli wallet new_coldkey \ --wallet.name validator ``` + ```bash btcli wallet new_hotkey \ --wallet.name validator \ diff --git a/docs/working-with-keys.md b/docs/working-with-keys.md index 927be555f..ce8db1382 100644 --- a/docs/working-with-keys.md +++ b/docs/working-with-keys.md @@ -25,7 +25,7 @@ The most critical operational goal when handling Bittensor wallets is to avoid l ## Creating a wallet with `btcli` - + If you plan to validate or mine in a subnet, you must have both a coldkey and a hotkey. If you already have a coldkey, you can [create a new hotkey](?create-wallet=hotkey) for it. @@ -46,7 +46,7 @@ btcli wallet create --wallet.name test-coldkey --wallet.hotkey test-hotkey ::: -Next, you'll be prompted to configure the wallet by setting a password for the coldkey, and choosing the desired mnemonic length. Completing the prompts creates a complete Bittensor wallet by setting up both coldkey and hotkeys. A unique mnemonic is generated for each key and output to the terminal upon creation. +Next, you will be prompted to configure the wallet by setting a password for the coldkey, and choosing the desired mnemonic length. Completing the prompts creates a complete Bittensor wallet by setting up both coldkey and hotkeys. A unique mnemonic is generated for each key and output to the terminal upon creation. :::tip Regenerating the wallet keys Take note of the mnemonics in the response as they are required to regenerate your coldkey and hotkey. To regenerate your coldkey, run the following command in the terminal: @@ -151,6 +151,10 @@ btcli wallet new_hotkey --use-password --wallet.name test-coldkey --wallet.hotke ## Creating a wallet using Python + + +If you plan to validate or mine in a subnet, you must have both a coldkey and a hotkey. + Copy and paste the following three lines into your Python interpreter. Replace the string values for `name` (`my_coldkey`) and `hotkey` (`my_hotkey`) with your own. ```python showLineNumbers @@ -172,24 +176,75 @@ The mnemonic to the new coldkey is: **** **** **** **** **** **** **** **** **** **** **** **** -You can use the mnemonic to recreate the key in case it gets lost. The command to use to regenerate the key using this mnemonic is: -btcli w regen_coldkey --mnemonic **** **** **** **** **** **** **** **** **** **** **** **** - -Specify password for key encryption: +You can use the mnemonic to recreate the key with `btcli` in case it gets lost. +Enter your password: Retype your password: +Encrypting... +wallet(test-coldkey, test-hotkey, ~/.bittensor/wallets/) +``` + +:::info Encrypting the hotkey +Since the coldkey is encrypted by default, the command above only encrypts the newly created coldkey. To encrypt your hotkey when creating a wallet, include the `hotkey_use_password=True` parameter in the `wallet.create_if_non_existent()` method as shown: + +```python showLineNumbers +import bittensor as bt +wallet = bt.wallet(name = 'my_coldkey', hotkey = 'my_hotkey') +wallet.create_if_non_existent(hotkey_use_password=True) +``` + +Then, you will be prompted to configure the wallet by setting a password for both the coldkey and the hotkey. +::: + + +If a user does not intend to mine, validate, manage subnets, or participate in governance, a hotkey is not required. In such cases, a coldkey-only wallet is recommended for simplicity. + +Copy and paste the following lines into your Python interpreter. Replace the string values for `name` (`my_coldkey`) with your own. + +```python showLineNumbers +import bittensor as bt +wallet = bt.wallet(name = 'my_coldkey') +wallet.create_new_coldkey() +``` + +You will be prompted to input a password for the coldkey and then see the terminal output, which includes your all-important seed phrase, a.k.a. the _mnemonic_ to the coldkey. + +```text IMPORTANT: Store this mnemonic in a secure (preferable offline place), as anyone who has possession of this mnemonic can use it to regenerate the key and access your tokens. -The mnemonic to the new hotkey is: +The mnemonic to the new hotkey is: **** *** **** **** ***** **** *** **** **** **** ***** ***** +You can use the mnemonic to recreate the key in case it gets lost. +``` -**** **** **** **** **** **** **** **** **** **** **** **** + + +If you plan to validate or mine in a subnet, you must have both a coldkey and a hotkey. -You can use the mnemonic to recreate the key in case it gets lost. The command to use to regenerate the key using this mnemonic is: -btcli w regen_hotkey --mnemonic **** **** **** **** **** **** **** **** **** **** **** **** +Before creating a hotkey, you must have created a coldkey as described in the [creating a coldkey tab](?create-wallet=coldkey). Next, provide this coldkey as a parameter to generate a hotkey. This will pair the hotkey with the coldkey as shown: -wallet(test-coldkey, test-hotkey, ~/.bittensor/wallets/) +```python showLineNumbers +import bittensor as bt +wallet = bt.wallet(name = 'my_coldkey') +wallet.create_new_hotkey() ``` +:::info Encrypting the hotkey +To encrypt your hotkey when creating a wallet, include the `use_password=True` parameter in the `wallet.create_new_hotkey()` method as shown: + +```python showLineNumbers +import bittensor as bt +wallet = bt.wallet(name = 'my_coldkey') +wallet.create_new_hotkey(use_password=True) +``` + +Then, you will be prompted to configure the wallet by setting a password for both the hotkey. +::: + + + + +--- + ## Location and addresses of the local wallets Both `btcli` and the Bittensor Python SDK use a local wallet/key store. By default, this is located on your machine at `~/.bittensor/wallets`. Use the below command to list them: From 4a006fadab1a089de4d8022016de45ddd19f7fcf Mon Sep 17 00:00:00 2001 From: Dera Okeke Date: Fri, 18 Jul 2025 00:34:58 +0100 Subject: [PATCH 03/12] subnet creation (wip) --- docs/btcli.md | 2 +- docs/glossary.md | 144 ++++++++++++++++---------- docs/local-build/create-subnet.md | 130 ++++++++--------------- docs/local-build/deploy.md | 2 +- docs/local-build/provision-wallets.md | 44 ++++---- docs/subnets/create-a-subnet.md | 4 +- docs/working-with-keys.md | 10 +- 7 files changed, 164 insertions(+), 172 deletions(-) diff --git a/docs/btcli.md b/docs/btcli.md index 9bf229139..c0bdcae4c 100644 --- a/docs/btcli.md +++ b/docs/btcli.md @@ -681,7 +681,7 @@ btcli wallet transfer [OPTIONS] | `--destination`, `--dest`, `-d` | TEXT | Destination address (ss58) of the wallet (coldkey). | | `--amount`, `-a` | FLOAT | Amount (in TAO) to transfer. | | `--all` | | Transfer all available balance. | -| `--all`, `-a` | | Whether to display the balances for all the wallets. | +| `--all` | | Whether to display the balances for all the wallets. | | `--period`, `-era` | INTEGER | Length (in blocks) for which the transaction should be valid. | | `--wallet-name`, `--name`, `--wallet_name`, `--wallet.name` | TEXT | Name of the wallet. | | `-p`, `--wallet-path`, `--wallet_path`, `--wallet.path` | TEXT | Path where the wallets are located. For example: `/Users/btuser/.bittensor/wallets`. | diff --git a/docs/glossary.md b/docs/glossary.md index e499742fa..a3e4b43ff 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -4,7 +4,7 @@ title: "Glossary" # Glossary -## A +## A ### Active UID @@ -40,10 +40,16 @@ A digital wallet that holds the core ownership in the Bittensor network and serv ### Block -A unit of data in the Bittensor blockchain, containing a collection of transactions and a unique identifier (block hash). A single block is processed every 12 seconds in the Bittensor blockchain. +A unit of data in the Bittensor blockchain, containing a collection of transactions and a unique identifier (block hash). A single block is processed every 12 seconds in the Bittensor blockchain. **See also:** [Subtensor API](./sdk/subtensor-api.md) +### Burn cost + +This refers to the required amount of TAO to be recycled when creating a new subnet, i.e., cost of registering a new subnet. + +**See also:** [Burn cost](./subnets/create-a-subnet.md#burn-cost) + ## C ### Coldkey @@ -65,7 +71,9 @@ The commit reveal feature is designed to solve the weight-copying problem by giv **See also:** [Commit Reveal](./subnets/commit-reveal.md) ### Consensus Score + + The consensus score is calculated as the stake-weighted median of all weights assigned to a specific neuron by validators. This creates a consensus threshold that filters out outlier weights, ensuring that only weights near the median consensus are used in final rank calculations. **See also:** [Yuma Consensus](./yuma-consensus.md), [Consensus-Based Weights](./subnets/consensus-based-weights.md) @@ -73,29 +81,34 @@ The consensus score is calculated as the stake-weighted median of all weights as #### Mathematical Definition: For each neuron $j$, the consensus score $C_j$ is calculated as: + $$ C_j = \text{weighted\_median}(\{w_{ij} \mid i \in \text{validators}\}, \{s_i \mid i \in \text{validators}\}, \kappa) $$ Where: + - $w_{ij}$ is the weight assigned by validator $i$ to neuron $j$ - $s_i$ is the stake of validator $i$ - $\kappa$ is the consensus majority ratio (typically 51%) - $\text{weighted\_median}$ is the stake-weighted median function Calculation Process: + 1. **Weight collection**: Gather all weights assigned to each neuron by validators 2. **Stake weighting**: Apply stake weights to validator opinions 3. **Median calculation**: Find stake-weighted median using κ parameter (typically 51%) 4. **Threshold establishment**: Consensus score becomes clipping threshold for weights Properties and Interpretation: + - **Range**: [0, 1] normalized values - **High Consensus**: Values close to 1 indicate strong validator agreement - **Low Consensus**: Values close to 0 indicate weak validator agreement - **Outlier Detection**: Weights below consensus score are clipped to 0 Network Security Properties: + - **Anti-Manipulation**: Consensus filtering prevents weight manipulation by outliers - **Stake-Weighted**: Higher stake validators have more influence in consensus - **Dynamic Threshold**: Consensus adapts to changing network conditions @@ -104,25 +117,28 @@ Network Security Properties: #### Relationship to Other Metrics **Consensus vs Trust:** + - **Consensus**: Stake-weighted median of weights (consensus threshold) - **Trust**: Ratio of final rank to pre-rank (consensus alignment impact) - **Relationship**: Consensus determines weight clipping, Trust measures the impact **Consensus vs Ranks:** + - **Consensus**: Threshold for weight filtering - **Ranks**: Final performance scores after consensus filtering - **Relationship**: Consensus influences rank calculation through weight clipping **Consensus vs Validator Trust:** + - **Consensus**: Per-neuron consensus thresholds - **Validator Trust**: Sum of clipped weights set by each validator - **Relationship**: Validator trust measures validator influence in consensus -**Source**: +**Source**: + - [`bittensor/bittensor/core/metagraph.py:360-372`](https://github.com/opentensor/bittensor/blob/main/bittensor/core/metagraph.py#L360-372) - [`subtensor/pallets/subtensor/src/epoch/run_epoch.rs:595`](https://github.com/opentensor/subtensor/blob/main/pallets/subtensor/src/epoch/run_epoch.rs#L595) - ## D ### Delegate @@ -137,15 +153,13 @@ The amount of TAO staked by the delegate themselves. **See also:** [Managing Stake with btcli](./staking-and-delegation/managing-stake-btcli.md), [Managing Stake with SDK](./staking-and-delegation/managing-stake-sdk.md) - - ### Delegation Also known as staking, delegating TAO to a validator (who is thereby the delegate), increases the validator's stake and secure a validator permit. **See also:** [Delegation](./staking-and-delegation/delegation.md), [Managing Stake with btcli](./staking-and-delegation/managing-stake-btcli.md) -### Dendrite +### Dendrite A client instance used by subnet validators and subnet miners to transmit information to axons on subnet miners and subnet validators. Dendrites communicate with axons using the server-client (Axon-dendrite) protocol. @@ -157,7 +171,7 @@ The process of removing a subnet miner or a subnet validator from the subnet due **See also:** [Miner Deregistration](./miners/#miner-deregistration), [Subnet Miners](./miners/) -## E +## E ### EdDSA Cryptographic Keypairs @@ -199,7 +213,7 @@ A development-only configuration that accelerates block production to 250ms inte **See also:** [Create a local instance](./local-build/deploy.md?local-chain=docker#2-run-the-container) -## H +## H ### Hotkey @@ -213,7 +227,7 @@ Authentication mechanism for delegates and nominators and for delegates particip **See also:** [Coldkey-Hotkey Security](./getting-started/coldkey-hotkey-security.md), [Working with Keys](./working-with-keys.md) -## I +## I ### Immunity Period @@ -233,7 +247,7 @@ A system that drives the behavior of subnet miners and governs consensus among s **See also:** [Anatomy of Incentive Mechanism](./learn/anatomy-of-incentive-mechanism.md), [Understanding Subnets](./subnets/understanding-subnets.md) -## L +## L ### Lite Node @@ -259,7 +273,7 @@ In the context of machine learning, a mathematical function that measures the di **See also:** [Anatomy of Incentive Mechanism](./learn/anatomy-of-incentive-mechanism.md), [Understanding Subnets](./subnets/understanding-subnets.md) -## M +## M ### Mainchain @@ -285,7 +299,7 @@ A sequence of words used to regenerate keys, in case of loss, and restore coldke **See also:** [Handle Seed Phrase](./keys/handle-seed-phrase.md), [Working with Keys](./working-with-keys.md) -## N +## N ### NaCl Format @@ -307,8 +321,7 @@ Neurons participate in the network through axon servers (miners) and dendrite cl **See also:** [Understanding Neurons](./learn/neurons.md), [Subnet Validators](./validators/), [Subnet Miners](./miners/), [NeuronInfo class](pathname:///python-api/html/autoapi/bittensor/core/chain_data/neuron_info/index.html) - -## N +## N ### Nominate @@ -328,7 +341,7 @@ A development-only configuration that adheres to Subtensor’s default 12-second **See also:** [Create a local instance](./local-build/deploy.md?local-chain=docker#2-run-the-container) -## O +## O ### Objective Function @@ -336,7 +349,7 @@ In the context of machine learning and subnet operations, this refers to the goa **See also:** [Anatomy of Incentive Mechanism](./learn/anatomy-of-incentive-mechanism.md), [Understanding Subnets](./subnets/understanding-subnets.md) -## P +## P ### Private Key @@ -368,7 +381,7 @@ A publicly accessible node in the Bittensor network that can be run as a lite no **See also:** [Subtensor Nodes](./subtensor-nodes/), [Managing Subtensor Connections](./sdk/managing-subtensor-connections.md) -## R +## R ### RAO @@ -382,28 +395,31 @@ This metagraph property represents the final aggregate judgment of a each miner, Ranks are calculated as the stake-weighted sum of consensus-clipped weights and directly determine emissions to miners. - **See also:** [Emissions](./emissions.md), [Yuma Consensus](./yuma-consensus.md), [Subnet Metagraph](./subnets/metagraph) **Relationship to Other Metrics:** + - **Ranks vs Consensus**: Ranks are calculated using consensus-clipped weights - **Ranks vs Trust**: Trust measures how much consensus clipping affected the rank - **Ranks vs Incentive**: Ranks are normalized to become incentive values - **Ranks vs Validator Trust**: Validator trust measures validator influence in consensus **Calculation Process:** + 1. **Pre-ranks**: Initial stake-weighted sum of all weights before consensus filtering 2. **Consensus calculation**: Stake-weighted median of weights per neuron (consensus threshold) 3. **Weight clipping**: Weights clipped at consensus threshold to remove outliers 4. **Final ranks**: Stake-weighted sum of clipped weights (the rank value) **Properties and Interpretation:** + - **Range**: [0, 1] normalized values after final normalization - **High Rank**: Values close to 1 indicate strong consensus-based performance - **Low Rank**: Values close to 0 indicate weak consensus-based performance - **Incentive Distribution**: Ranks directly determine incentive allocation to miner neurons **Network Security Properties:** + - **Consensus-Based**: Ranks reflect network consensus rather than individual validator opinions - **Outlier Protection**: Consensus clipping prevents manipulation by outlier weights - **Stake-Weighted**: Higher stake validators have more influence in rank calculation @@ -414,22 +430,23 @@ For each neuron $j$, the rank $R_j$ is calculated as: $$R_j = \sum_{i \in \text{validators}} S_i \cdot \overline{W_{ij}}$$ Where: + - $S_i$ is the stake of validator $i$ - $\overline{W_{ij}}$ is the consensus-clipped weight from validator $i$ to neuron $j$ - The sum is taken over all validators in the subnet -**Source**: +**Source**: + - [`bittensor/bittensor/core/metagraph.py:325-331`](https://github.com/opentensor/bittensor/blob/main/bittensor/core/metagraph.py#L325-331) - [`subtensor/pallets/subtensor/src/epoch/run_epoch.rs:605`](https://github.com/opentensor/subtensor/blob/main/pallets/subtensor/src/epoch/run_epoch.rs#L605) - ### Recycling, burning, and locking "Recycling TAO" means that this TAO is put back into the Bittensor emissions system. Instead of minting new TAO this recycled TAO that is in the recycle bin will be used again in the new emissions. This happens in two cases: -- When you register either as a subnet validator or a subnet miner and get a `UID` in return, the registration cost TAO you pay is recycled. +- When you register either as a subnet validator or a subnet miner and get a `UID` in return, the registration cost TAO you pay is recycled. - Emissions are recycled for those subnets that have registration turned off or paused. When TAO is burned it is permanently removed from circulation, reducing total supply. @@ -450,7 +467,7 @@ 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) -## S +## S ### SS58 Encoded @@ -466,23 +483,21 @@ A group of elected delegates formed from the top K delegate hotkeys, responsible ### Stake -The amount of currency tokens delegated to a validator UID in a subnet. Includes both self-stake (from the validator's own cold-key) and stake delegated from others. +The amount of currency tokens delegated to a validator UID in a subnet. Includes both self-stake (from the validator's own cold-key) and stake delegated from others. Stake determines a validator's weight in consensus as well as their emissions. **See also:** [Managing Stake with btcli](./staking-and-delegation/managing-stake-btcli.md), [Managing Stake with SDK](./staking-and-delegation/managing-stake-sdk.md), [Delegation](./staking-and-delegation/delegation.md) - - ### Stake Weight The computed total stake value for a validator that determines their consensus power and emissions in a subnet. Stake weight combines a validator's alpha stake and TAO stake using the TAO weight parameter to calculate their total influence in the network. **See also:** [TAO Weight](#tao-weight), [Understanding Subnets](./subnets/understanding-subnets.md) - **Mathematical Definition:** For a validator with alpha stake $\alpha$ and TAO stake $\tau$, the stake weight $W$ is calculated as: + $$ W = {\alpha + \tau \ \times w_{\tau}} $$ @@ -490,16 +505,19 @@ $$ Where $w_{\tau}$ is the global TAO weight parameter (currently 0.18) 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} $$ **Consensus Power:** + - **Weight Setting**: Higher stake weight means more influence when setting weights - **Validator Permits**: Stake weight determines eligibility for validator permits - **Bond Formation**: Stake weight influences bond calculations and retention **Validator Emissions:** + - **Relative Distribution**: Higher stake weight -> higher emission share **Code References:** @@ -507,7 +525,6 @@ $$ - **Yuma Consensus**: [`subtensor/pallets/subtensor/src/epoch/run_epoch.rs:530`](https://github.com/opentensor/subtensor/blob/main/pallets/subtensor/src/epoch/run_epoch.rs#L530) - **Validator dividend distribution**: [`subtensor/pallets/subtensor/src/coinbase/run_coinbase.rs:165`](https://github.com/opentensor/subtensor/blob/main/pallets/subtensor/src/coinbase/run_coinbase.rs#L165) - ### Staking The process of attaching TAO to a hotkey, i.e., locking TAO to a hotkey, to participate as a subnet validator, and to secure a validator permit. @@ -528,7 +545,7 @@ The framework that governs the behavior of subnet miners and ensures consensus a ### Subnet Miner -The task-performing entity within a Bittensor subnet. A subnet miner is a type of node in a Bittensor subnet that is connected only to subnet validators. Subnet miners are isolated from the external world and communicate bidirectionally with subnet validators. A subnet miner is responsible for performing tasks given to them by the subnet validators in that subnet. +The task-performing entity within a Bittensor subnet. A subnet miner is a type of node in a Bittensor subnet that is connected only to subnet validators. Subnet miners are isolated from the external world and communicate bidirectionally with subnet validators. A subnet miner is responsible for performing tasks given to them by the subnet validators in that subnet. **See also:** [Subnet Miner Documentation](./miners/) @@ -582,7 +599,7 @@ A data object used by subnet validators and subnet miners as the main vehicle to **See also:** [Subnet Miners](./miners/), [Subnet Validators](./validators/) -## T +## T ### TAO ($\tau$) @@ -595,9 +612,10 @@ The cryptocurrency of the Bittensor network, used to incentivize participation i A global parameter (currently set to 0.18) that determines the relative influence of TAO stake versus alpha stake when calculating a validator's total stake weight, a critical value that influence's a validator's consensus power and emissions. **See also:** [Stake Weight](#stake-weight) + ### Tempo -A 360-block period during which the Yuma Consensus calculates emissions to subnet participants based on the latest available ranking weight matrix. A single block is processed every 12 seconds, hence a 360-block tempo occurs every 4320 seconds or 72 minutes. +A 360-block period during which the Yuma Consensus calculates emissions to subnet participants based on the latest available ranking weight matrix. A single block is processed every 12 seconds, hence a 360-block tempo occurs every 4320 seconds or 72 minutes. **See also:** [Yuma Consensus](./yuma-consensus.md), [Emissions](./emissions.md) @@ -619,31 +637,35 @@ In the Yuma Consensus algorithm, trust represents how much a miner's rank was af **See also:** [Yuma Consensus](./yuma-consensus.md), [Subnet Metagraph](./subnets/metagraph) - **Mathematical Definition:** For each neuron $j$, the trust $T_j$ is calculated as: + $$ T_j = \frac{R_j}{P_j} $$ Where: + - $R_j$ is the final rank after consensus clipping - $P_j$ is the pre-rank before consensus clipping - The ratio indicates the proportion of original support that survived consensus filtering Interpretation: + - **Range**: [0, 1] where 1.0 indicates perfect consensus alignment - **`Trust = 1.0`**: Neuron's rank unchanged by consensus (high consensus alignment) - **`Trust < 1.0`**: Neuron's rank reduced by consensus clipping (lower value means more reduction) - **`Trust = 0.0`**: Neuron's rank eliminated by consensus (no consensus support) Calculation Process: + 1. **Pre-ranks calculation**: $P_j = \sum_{i} S_i \cdot W_{ij}$ (stake-weighted sum of all weights) 2. **Consensus filtering**: Weights clipped at consensus threshold to remove outliers 3. **Final ranks calculation**: $R_j = \sum_{i} S_i \cdot \overline{W_{ij}}$ (stake-weighted sum of clipped weights) 4. **Trust calculation**: $T_j = R_j / P_j$ (ratio of final to pre-rank) **Relationship to Other Metrics:** + - **Trust vs Consensus**: Trust measures the impact of consensus filtering - **Trust vs Ranks**: Trust is the ratio of final rank to pre-rank - **Trust vs Validator Trust**: Trust is per-neuron, Validator Trust is per-validator @@ -651,26 +673,21 @@ Calculation Process: **Metric Comparison Table** -| Metric | Purpose | Calculation | Range | Interpretation | -|--------|---------|-------------|-------|----------------| -| **Consensus** | Consensus threshold | Stake-weighted median of weights per neuron | [0, 1] | Higher = stronger validator agreement | -| **Ranks** | Performance scoring | Stake-weighted sum of clipped weights | [0, 1] | Higher = better performance after consensus | -| **Trust** | Consensus alignment | Final rank / Pre-rank | [0, 1] | 1.0 = no clipping, < 1.0 = some clipping | -| **Validator Trust** | Validator influence | Sum of clipped weights per validator | [0, 1] | Higher = more consensus-aligned validator | +| Metric | Purpose | Calculation | Range | Interpretation | +| ------------------- | ------------------- | ------------------------------------------- | ------ | ------------------------------------------- | +| **Consensus** | Consensus threshold | Stake-weighted median of weights per neuron | [0, 1] | Higher = stronger validator agreement | +| **Ranks** | Performance scoring | Stake-weighted sum of clipped weights | [0, 1] | Higher = better performance after consensus | +| **Trust** | Consensus alignment | Final rank / Pre-rank | [0, 1] | 1.0 = no clipping, < 1.0 = some clipping | +| **Validator Trust** | Validator influence | Sum of clipped weights per validator | [0, 1] | Higher = more consensus-aligned validator | + +**Source**: -**Source**: - [`bittensor/bittensor/core/metagraph.py:380-393`](https://github.com/opentensor/bittensor/blob/main/bittensor/core/metagraph.py#L380-393) - [`subtensor/pallets/subtensor/src/epoch/run_epoch.rs:608`](https://github.com/opentensor/subtensor/blob/main/pallets/subtensor/src/epoch/run_epoch.rs#L608) - - - - The relationship between these metrics creates a feedback loop: consensus determines weight clipping, which affects ranks and trust, which influences validator trust, which feeds back into future consensus calculations. This system ensures that the network rewards neurons with strong validator agreement while penalizing those with controversial or outlier weight assignments, creating a robust mechanism for maintaining network quality and security. - - -## U +## U ### UID Slot @@ -678,7 +695,7 @@ A position occupied by a subnet miner or subnet validator within a subnet, ident **See also:** [Subnet Miners](./miners/), [Subnet Validators](./validators/), [Working with Subnets](./subnets/working-with-subnets.md) -## V +## V ### Validator Permit @@ -692,10 +709,9 @@ A list of subnet IDs (netuids) indicating which subnets a delegate is authorized **See also:** [Validator Permits](#validator-permit), [Delegation](./staking-and-delegation/delegation.md), [Validator Requirements](./validators/index.md#requirements-for-validation) - ### Validator -A type of node in a subnet that creates tasks, evaluates the performance of subnet miners and sets weights based on their output. A subnet validator is connected only to subnet miners and to the external world. Subnet validators receive inputs from the external world and communicate bidirectionally with subnet miners. +A type of node in a subnet that creates tasks, evaluates the performance of subnet miners and sets weights based on their output. A subnet validator is connected only to subnet miners and to the external world. Subnet validators receive inputs from the external world and communicate bidirectionally with subnet miners. **See also:** [Subnet Validators](./validators/), [Validators btcli Guide](./validators/validators-btcli-guide.md) @@ -713,39 +729,44 @@ For each validator $i$, the validator trust $T_{vi}$ is calculated as: $$T_{vi} = \sum_{j \in \text{neurons}} \overline{W_{ij}}$$ Where: + - $\overline{W_{ij}}$ is the consensus-clipped weight from validator $i$ to neuron $j$ - The sum is taken over all neurons in the subnet - Validator trust measures the total influence a validator has in consensus **Calculation Process:** + 1. **Weight setting**: Validators set weights to all neurons in the subnet 2. **Consensus calculation**: Stake-weighted median of weights per neuron (consensus threshold) 3. **Weight clipping**: Weights clipped at consensus threshold to remove outliers 4. **Validator trust calculation**: Sum of all clipped weights set by each validator **Properties and Interpretation:** + - **Range**: [0, 1] normalized values - **High Validator Trust**: Values close to 1 indicate strong consensus alignment - **Low Validator Trust**: Values close to 0 indicate outlier weight assignments - **Validator Influence**: Higher validator trust means more influence in consensus decisions **Network Security Properties:** + - **Consensus Alignment**: Validator trust measures how well validators align with consensus - **Outlier Detection**: Low validator trust indicates potential manipulation attempts - **Validator Quality**: High validator trust indicates quality validation services - **Economic Incentives**: Validator trust influences validator rewards and bond retention -**Source**: +**Source**: + - [`bittensor/bittensor/core/metagraph.py:397-409`](https://github.com/opentensor/bittensor/blob/main/bittensor/core/metagraph.py#L397-409) - [`subtensor/pallets/subtensor/src/epoch/run_epoch.rs:600`](https://github.com/opentensor/subtensor/blob/main/pallets/subtensor/src/epoch/run_epoch.rs#L600) **Relationship to Other Metrics:** + - **Validator Trust vs Trust**: Validator trust is per-validator, Trust is per-neuron - **Validator Trust vs Consensus**: Validator trust measures validator influence in consensus - **Validator Trust vs Ranks**: Validator trust influences rank calculation through consensus - **Validator Trust vs Bonds**: Validator trust affects bond retention and validator permits - ### Validator-Miner Bonds Bonds represent the "investment" a validator has made in evaluating a specific miner. This bonding mechanism is integral to the Yuma Consensus' design intent of incentivizing high-quality performance by miners, and honest evaluation by validators. @@ -757,6 +778,7 @@ The instant bond $\Delta B_{ij}$ of validator $i$ to miner $j$ is calculated as: $$\Delta B_{ij} = \frac{S_i \cdot \widetilde{W_{ij}}}{\sum_{k \in \mathbb{V}} S_k \cdot \widetilde{W_{kj}}}$$ Where: + - $S_i$ is validator $i$'s stake - $\widetilde{W_{ij}}$ is the bond-weight (penalty-adjusted weight) - The denominator normalizes by the total bond-weight for miner $j$ across all validators @@ -766,6 +788,7 @@ Bond-weights are penalized when validators overstate miner performance: $$\widetilde{W_{ij}} = (1-\beta)W_{ij} + \beta\overline{W_{ij}}$$ Where: + - $W_{ij}$ is the original weight set by validator $i$ for miner $j$ - $\overline{W_{ij}}$ is the consensus-clipped weight - $\beta$ is the bonds penalty factor (configurable hyperparameter) @@ -779,52 +802,62 @@ Where $\alpha$ is the EMA smoothing factor. **Bond Mechanics and Design:** **Consensus Alignment:** + - Validators who stay near consensus build stronger EMA bonds - Bonds are penalized when validators overstate miner performance - The EMA smooths out abrupt swings in validator behavior - Bonds incentivize consistent alignment with consensus **Bond Retention:** + - Neurons retain bonds only if they keep validator permits - Bonds are cleared when neurons lose validator permits - Bonds are stored as sparse matrices in blockchain state **Bond Decay:** + - Bonds decay over time based on the `bonds_moving_avg` parameter - Higher decay rates make bonds more responsive to recent performance - Lower decay rates allow bonds to persist longer **Economic Alignment:** + - Bonds create long-term relationships between validators and miners - Validators are incentivized to discover and support promising miners early - Bond strength reflects validator confidence in miner performance **Dynamic Adjustment:** + - Bonds adapt to changing network conditions and consensus - EMA smoothing prevents exploitation of rapid bond changes - Bonds provide stability while allowing for network evolution **Retrieval:** + - Bonds can be queried via the `bonds()` method in the Subtensor API - Metagraph includes bonds matrix accessible via `metagraph.B` property - Bonds are included in neuron information structures **Related hyperparameters:** + - `bonds_penalty`: Controls penalty for out-of-consensus weights (0-65535) - `bonds_moving_avg`: Controls bond decay rate (typically 900,000) - `liquid_alpha_enabled`: Enables dynamic alpha adjustment for bonds **Validator Permits:** + - Bonds are retained only by neurons with validator permits - Loss of validator permit clears all bonds for that neuron - Bonds align with permit retention for economic security **Emission Distribution:** + - Bonds directly determine validator emission shares - Strong bonds lead to higher validator rewards - Bonds create market-based incentive alignment **Code References:** + - [Bond calculation in epoch execution]https://github.com/opentensor/subtensor/blob/main/pallets/subtensor/src/epoch/run_epoch.rs:631) - [EMA bond computation]https://github.com/opentensor/subtensor/blob/main/pallets/subtensor/src/epoch/math.rs:1475) - [Bonds API method]https://github.com/opentensor/subtensor/blob/main/bittensor/core/async_subtensor.py:931) @@ -840,8 +873,7 @@ Effectively, this represents the fee percentage that validators charge delegator **See also:** [Emissions](./emissions.md) - -## W +## W ### Wallet Address @@ -869,10 +901,10 @@ The ranking weight vectors for each subnet are transmitted to the blockchain, wh **See also:** [Consensus-Based Weights](./subnets/consensus-based-weights.md), [Yuma Consensus](./yuma-consensus.md) -## Y +## Y ### Yuma Consensus -The consensus mechanism in the Bittensor blockchain that computes emissions to participants. +The consensus mechanism in the Bittensor blockchain that computes emissions to participants. -**See also:** [Yuma Consensus](./yuma-consensus.md) \ No newline at end of file +**See also:** [Yuma Consensus](./yuma-consensus.md) diff --git a/docs/local-build/create-subnet.md b/docs/local-build/create-subnet.md index 9a4363e9c..a0c62fe24 100644 --- a/docs/local-build/create-subnet.md +++ b/docs/local-build/create-subnet.md @@ -8,14 +8,14 @@ This page covers creating a subnet on a locally deployed Subtensor blockchain, w For creating a subnet on Bittensor test and main network, see [Create a Subnet](../subnets/create-a-subnet). -Prerequisites: +## Prerequisites: - [Deploy a Subtensor chain locally](./deploy) -- [Provision wallets for the sn-creator, miner, and validator users for this tutorial.](./provision-wallets) +- [Provision wallets for the subnet creator, miner, and validator users for this tutorial.](./provision-wallets) +- Sufficient amount of TAO in your subnet creator wallet to cover the [burn cost](../glossary.md#burn-cost). ## Create subnet - ```shell btcli subnet create \ --subnet-name awesome-first-subnet \ @@ -23,94 +23,37 @@ btcli subnet create \ --network ws://127.0.0.1:9945 ``` -### Trouble shoot - -#### Insufficient funds - -If you are following this tutorial for the first time, the `subnet create` command will faill with an insufficient balance error. - -The coldkey signing the `subnet create` transaction must have a sufficient $\tau$ balance to cover the burn cost of subnet creation, so called because the funds cannot be recovered. - -```console -Subnet burn cost: τ 1,000.0000 -Your balance of: τ 0.0000 is not enough to burn τ 1,000.0000 to register a subnet. -``` - -Transfer funds from the Alice account to cover it and try again. Consult `btcli w list` and carefully check the ss58 address of the destination coldkey (in this case, the one with the name `sn-creator`). - -```shell -btcli wallet transfer \ ---amount 1001 \ ---wallet.name alice \ ---destination "5C9xw4..." \ ---network ws://127.0.0.1:9945 -``` - -#### Network Rate Limit Error - -If you see a network rate limit error, you may need to adjust the `SubtensorInitialNetworkRateLimit` chain state parameter. - -See [Clone and tweak the Subtensor source](./deploy#clone-and-tweak-the-subtensor-source) - -### Burn cost - -The burn cost for subnet creation is dynamic; it lowers gradually and doubles every time a subnet is created. - -:::tip try it live - -Check the burn cost to create a subnet on Bittensor main network and test network: - - - - - -```shell -btcli subnet burn-cost --network finney -``` - - - - -```shell -btcli subnet burn-cost --network test -``` - - - -::: - ## Fund your subnet To remedy your liquidity shortfall, transfer $\tau$ from the Alice account and try again. 1. First, get the ss58 address for the destination wallet for the transfer: - ```shell - btcli w list - ``` - ```shell - ... - ── Coldkey sn-creator ss58_address 5C9xw4gDyu11ocdpWrmhT1sbi4xEHCpzEMsyMA4jGfAZQofQ - └── Hotkey default ss58_address 5GVsCAY6RuSuoAA1E77xsHJ9PjdZJjJrRkNFDxVtRKPnw7TR - ``` + ```shell + btcli w list + ``` + ```shell + ... + ── Coldkey sn-creator ss58_address 5C9xw4gDyu11ocdpWrmhT1sbi4xEHCpzEMsyMA4jGfAZQofQ + └── Hotkey default ss58_address 5GVsCAY6RuSuoAA1E77xsHJ9PjdZJjJrRkNFDxVtRKPnw7TR + ``` 1. Execute the transfer from `alice` to the sn-creator wallet - ```console - btcli wallet transfer \ - --amount 1001 \ - --wallet.name alice \ - --destination "5GVsCAY6RuSuoAA1E77xsHJ9PjdZJjJrRkNFDxVtRKPnw7TR" \ - --subtensor.chain_endpoint ws://127.0.0.1:9945 - ``` - - ```shell - Do you want to transfer: - amount: τ 1,001.0000 - from: alice : 5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY - to: 5GVsCAY6RuSuoAA1E77xsHJ9PjdZJjJrRkNFDxVtRKPnw7TR - for fee: τ 0.0001 [y/n]: y - 🌏 📡 Transferring... - ``` - + ```console + btcli wallet transfer \ + --amount 1001 \ + --wallet.name alice \ + --destination "5GVsCAY6RuSuoAA1E77xsHJ9PjdZJjJrRkNFDxVtRKPnw7TR" \ + --subtensor.chain_endpoint ws://127.0.0.1:9945 + ``` + + ```shell + Do you want to transfer: + amount: τ 1,001.0000 + from: alice : 5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY + to: 5GVsCAY6RuSuoAA1E77xsHJ9PjdZJjJrRkNFDxVtRKPnw7TR + for fee: τ 0.0001 [y/n]: y + 🌏 📡 Transferring... + ``` ## Success @@ -177,3 +120,22 @@ btcli subnet list \ │ │ │ │ │ 2.01k/29.00 │ │ │ │ │ │ │ │ (6931.03%) │ │ │ ``` + +## Troubleshooting + +### Insufficient funds + +The coldkey signing the `subnet create` transaction must have a sufficient $\tau$ balance to cover the burn cost of subnet creation, so called because the funds cannot be recovered. + +```console +Subnet burn cost: τ 1,000.0000 +Your balance of: τ 0.0000 is not enough to burn τ 1,000.0000 to register a subnet. +``` + +To fix this, transfer TAO from the Alice account to cover this transaction and try again. For more information, see [Transfer TAO to wallets](./provision-wallets.md#transfer-tao-to-wallets) + +### Network Rate Limit Error + +If you see a network rate limit error, you may need to adjust the `SubtensorInitialNetworkRateLimit` chain state parameter. + +See [Clone and tweak the Subtensor source](./deploy#clone-and-tweak-the-subtensor-source) diff --git a/docs/local-build/deploy.md b/docs/local-build/deploy.md index e1557c642..97915173f 100644 --- a/docs/local-build/deploy.md +++ b/docs/local-build/deploy.md @@ -1,5 +1,5 @@ --- -title: "Build and Deploy the Blockchain" +title: "Create a Local Bittensor Blockchain Instance" toc_max_heading_level: 2 --- diff --git a/docs/local-build/provision-wallets.md b/docs/local-build/provision-wallets.md index 1582258a7..67dab7206 100644 --- a/docs/local-build/provision-wallets.md +++ b/docs/local-build/provision-wallets.md @@ -8,6 +8,10 @@ Now that your local Subtensor chain is deployed, you can provision wallets to se Every local blockchain is pre-provisioned with an "Alice" account, which is loaded with one million $\tau$. +## Prerequisites + +To follow along with the rest of this tutorial, ensure that you have a local chain running. To set up a local chain, see [Create a local blockchain instance](./deploy.md). + ## Access the Alice account To access the handy pre-provisioned development "Alice" account on your local chain, use: @@ -46,39 +50,33 @@ The following should be returned in the console: You will need wallets for the different personas, i.e., subnet owner, subnet validator and subnet miner, in the subnet. -- The owner wallet creates and controls the subnet. +- The subnet owner wallet creates and controls the subnet. - The validator and miner will be registered to the subnet created by the owner. This ensures that the validator and miner can run the respective validator and miner scripts. -### Create a coldkey-only wallet for the subnet creator role (they do not need a hotkey): +To create a wallet, run the following command in your terminal: ```bash btcli wallet new_coldkey \ ---wallet.name sn-creator +--wallet.name WALLET_NAME \ +--hotkey WALLET_HOTKEY \ +--network ws://127.0.0.1:9945 ``` -### Set up the miner's wallet with a coldkey and hotkey: +Replace `WALLET_NAME` and `WALLET_HOTKEY` with the appropriate identifiers for each role—subnet creator, miner, or validator. -```bash -btcli wallet new_coldkey \ ---wallet.name miner -``` +### Transfer TAO to wallets -```bash -btcli wallet new_hotkey \ ---wallet.name miner \ ---wallet.hotkey default +After creating your wallets, transfer some TAO from the `Alice` account to them to cover the transaction fees required for onchain operations. To transfer TAO, run the following command in your terminal: +```sh +btcli wallet transfer \ +--wallet.name alice \ +--destination DESTINATION_ADDRESS \ +--network ws://127.0.0.1:9945 ``` -### Set up the validator's wallet with a coldkey and hotkey: +Replace `DESTINATION_ADDRESS` with the wallet address you want to send the TAO to. -```bash -btcli wallet new_coldkey \ ---wallet.name validator -``` - -```bash -btcli wallet new_hotkey \ ---wallet.name validator \ ---wallet.hotkey default -``` +:::info +Run the `btcli wallets list` command and carefully check the ss58 address of the destination coldkey that you want to fund. +::: diff --git a/docs/subnets/create-a-subnet.md b/docs/subnets/create-a-subnet.md index b22c97d1a..30a3d8bb2 100644 --- a/docs/subnets/create-a-subnet.md +++ b/docs/subnets/create-a-subnet.md @@ -21,7 +21,7 @@ Prospective subnet creators should familiarize themselves with the space of exis ### Burn cost -The burn cost for subnet creation is dynamic; it lowers gradually and doubles every time a subnet is created. +This refers to the required amount of TAO to be recycled when creating a new subnet. The burn cost for subnet creation is dynamic and reflects the current cost to register a new subnet. Its value lowers gradually and doubles every time a subnet is created. :::tip try it live @@ -68,7 +68,7 @@ Subnet creations are limited to **one subnet creation per 7200 blocks** (approxi - [Install the most recent version of BTCLI](../getting-started/install-btcli). -- [Create a wallet](../getting-started/wallets.md#creating-a-local-wallet). +- [Create a wallet](../getting-started/wallets.md#creating-a-local-wallet). - To create a subnet on test chain, your wallet must have sufficient test net TAO. Inquire in [Discord](https://discord.com/channels/799672011265015819/1107738550373454028/threads/1331693251589312553) to obtain TAO on Bittensor test network. - To create a subnet on main network (finney) requires a substantial investment of TAO, depending on current registration cost for new subnets. diff --git a/docs/working-with-keys.md b/docs/working-with-keys.md index ce8db1382..92a628419 100644 --- a/docs/working-with-keys.md +++ b/docs/working-with-keys.md @@ -27,7 +27,7 @@ The most critical operational goal when handling Bittensor wallets is to avoid l -If you plan to validate or mine in a subnet, you must have both a coldkey and a hotkey. If you already have a coldkey, you can [create a new hotkey](?create-wallet=hotkey) for it. +If you intend to mine or validate within a subnet, or create and manage a subnet, you’ll need both a coldkey and a hotkey. If you already have a coldkey, you can [create a new hotkey](?create-wallet=hotkey) for it. To create a new coldkey and hotkey, run the following command in the terminal: @@ -99,7 +99,7 @@ btcli wallet regen_coldkey --mnemonic "word1 word2 ... word12" -If you plan to validate or mine in a subnet, you must create both a coldkey and a hotkey. +If you plan to validate or mine in a subnet, you must create both a coldkey and a hotkey. A hotkey is also required when creating and managing subnets. Before creating a hotkey, you must have created a coldkey as described in the [creating a coldkey tab](?create-wallet=coldkey). Next, provide this coldkey as a parameter to generate a hotkey. This will pair the hotkey with the coldkey as shown: @@ -153,9 +153,9 @@ btcli wallet new_hotkey --use-password --wallet.name test-coldkey --wallet.hotke -If you plan to validate or mine in a subnet, you must have both a coldkey and a hotkey. +If you intend to mine or validate within a subnet, or create and manage a subnet, you’ll need both a coldkey and a hotkey. If you already have a coldkey, you can [create a new hotkey](?create-wallet=hotkey) for it. -Copy and paste the following three lines into your Python interpreter. Replace the string values for `name` (`my_coldkey`) and `hotkey` (`my_hotkey`) with your own. +To create a wallet with Python, copy and paste the following three lines into your Python interpreter. Replace the string values for `name` (`my_coldkey`) and `hotkey` (`my_hotkey`) with your own. ```python showLineNumbers import bittensor as bt @@ -218,7 +218,7 @@ You can use the mnemonic to recreate the key in case it gets lost. -If you plan to validate or mine in a subnet, you must have both a coldkey and a hotkey. +If you plan to validate or mine in a subnet, you must have both a coldkey and a hotkey. A hotkey is also required when creating and managing subnets. Before creating a hotkey, you must have created a coldkey as described in the [creating a coldkey tab](?create-wallet=coldkey). Next, provide this coldkey as a parameter to generate a hotkey. This will pair the hotkey with the coldkey as shown: From d2efcf75ad9f5c06f33fb406fd62799706c5f0db Mon Sep 17 00:00:00 2001 From: Dera Okeke Date: Thu, 24 Jul 2025 23:06:36 +0100 Subject: [PATCH 04/12] cleaned up subnet creation --- docs/local-build/create-subnet.md | 126 ++++++++---------------------- docs/local-build/deploy.md | 14 +++- 2 files changed, 45 insertions(+), 95 deletions(-) diff --git a/docs/local-build/create-subnet.md b/docs/local-build/create-subnet.md index d65b45cff..22787d220 100644 --- a/docs/local-build/create-subnet.md +++ b/docs/local-build/create-subnet.md @@ -10,56 +10,15 @@ For creating a subnet on Bittensor test and main network, see [Create a Subnet]( ## Prerequisites: +Before continuing with the rest of this tutorial, make sure you've completed the following: + - [Deploy a Subtensor chain locally](./deploy) - [Provision wallets for the subnet creator, miner, and validator users for this tutorial.](./provision-wallets) - Sufficient amount of TAO in your subnet creator wallet to cover the [burn cost](../glossary.md#burn-cost). -## Create subnet - -```shell -btcli subnet create \ ---subnet-name awesome-first-subnet \ ---wallet.name sn-creator \ ---network ws://127.0.0.1:9945 -``` - -## Fund your subnet - -To remedy your liquidity shortfall, transfer $\tau$ from the Alice account and try again. - -1. First, get the ss58 address for the destination wallet for the transfer: - ```shell - btcli w list - ``` - ```shell - ... - ── Coldkey sn-creator ss58_address 5C9xw4gDyu11ocdpWrmhT1sbi4xEHCpzEMsyMA4jGfAZQofQ - └── Hotkey default ss58_address 5GVsCAY6RuSuoAA1E77xsHJ9PjdZJjJrRkNFDxVtRKPnw7TR - ``` -1. Execute the transfer from `alice` to the sn-creator wallet - - ```console - btcli wallet transfer \ - --amount 1001 \ - --wallet.name alice \ - --destination "5GVsCAY6RuSuoAA1E77xsHJ9PjdZJjJrRkNFDxVtRKPnw7TR" \ - --subtensor.chain_endpoint ws://127.0.0.1:9945 - ``` - - ```shell - Do you want to transfer: - amount: τ 1,001.0000 - from: alice : 5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY - to: 5GVsCAY6RuSuoAA1E77xsHJ9PjdZJjJrRkNFDxVtRKPnw7TR - for fee: τ 0.0001 [y/n]: y - 🌏 📡 Transferring... - ``` +## Create a subnet -## Success - -Create some subnets. - -For example: +Now, let us create a new subnet on the local chain. To create a new subnet, run the following command in your terminal: ```shell btcli subnet create \ @@ -68,6 +27,8 @@ btcli subnet create \ --network ws://127.0.0.1:9945 ``` +You will then be prompted to provide the wallet hotkey as well as configure the subnet as shown: + ```console Subnet burn cost: τ 1,000.0000 Your balance is: τ 1,001.0000 @@ -77,31 +38,14 @@ Decrypting... 🌏 📡 Registering subnet.. ``` -```shell - btcli subnet create \ ---subnet-name awesome-second-subnet \ ---wallet.name sn-creator \ ---network ws://127.0.0.1:9945 -``` - -```console -Subnet burn cost: τ 1,999.9405 -▰▱▱▱▱▱▱ 📡Retrieving lock cost from custom... -Your balance is: τ 2,003.0000 -Do you want to burn τ 1,999.9405 to register a subnet? [y/n]: Please enter Y or N -Do you want to burn τ 1,999.9405 to register a subnet? [y/n]: y -Enter your password: -Decrypting... -✅ Registered subnetwork with netuid: 3 -``` - -1. List your subnets +To check on your newly created subnets, run the following command in your terminal: ```shell -btcli subnet list \ ---network ws://127.0.0.1:9945 +btcli subnet list --network ws://127.0.0.1:9945 ``` +A list of all subnets in your local subtensor instance is returned: + ```console Subnets Network: custom @@ -109,47 +53,49 @@ btcli subnet list \ Netuid ┃ Name ┃ (τ_in/α_in) ┃ (α * Price) ┃ Emission (τ) ┃ α_in) ┃ (α_out) ┃ Supply (α) ┃ Tempo (k/n) ━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━━ 0 │ τ root │ 1.0000 τ/Τ │ τ 0.00 │ τ 0.0000 │ -, - │ Τ 0.00 │ 0.00 Τ /21M │ -/- - 2 │ β │ 1.0000 τ/β │ τ 1.00k │ τ 0.0000 │ τ 1.00k, │ 0.00 β │ 1.00k β │ 29/360 + 2 │ β │ 0.0000 τ/β │ τ 1.00k │ τ 0.0000 │ τ 1.00k, │ 0.00 β │ 1.00k β │ 29/360 │ awesome-fi… │ │ │ │ 1.00k β │ │ /21M │ - 3 │ γ │ 1.0000 τ/γ │ τ 1.00k │ τ 0.0000 │ τ 1.00k, │ 0.00 γ │ 1.00k γ │ 29/360 - │ awesome-se… │ │ │ │ 1.00k γ │ │ /21M │ - 1 │ α apex │ 1.0000 τ/α │ τ 11.00 │ τ 0.0000 │ τ 10.00, │ 1.00 α │ 11.00 α │ 29/100 + 1 │ α apex │ 0.0000 τ/α │ τ 11.00 │ τ 0.0000 │ τ 10.00, │ 1.00 α │ 11.00 α │ 29/100 │ │ │ │ │ 10.00 α │ │ /21M │ ────────┼─────────────┼─────────────┼─────────────┼──────────────┼─────────────┼──────────────┼─────────────┼───────────── - 4 │ │ τ 3.0 │ │ τ 0.0 │ τ │ │ │ + 4 │ │ τ 1.0 │ │ τ 0.0 │ τ │ │ │ │ │ │ │ │ 2.01k/29.00 │ │ │ │ │ │ │ │ (6931.03%) │ │ │ ``` -## Start emissions on your subnet +## Start emissions on the subnet To activate your subnet, beginning emissions and allowing staking, run: ``` -btcli subnet start --netuid 2 \ +btcli subnet start --netuid NETUID \ --wallet.name sn-creator \ --network ws://127.0.0.1:9945 ``` -## Troubleshooting +Replace `NETUID` with the netuid of the subnet you want to enable emissions on. -### Insufficient funds +After a while, you can confirm that the subnet's emissions have started by inspecting your subnet's token economy. You'll see a non-zero amount in the *Emission* column, indicating the subnet creator key accumulates emissions. -The coldkey signing the `subnet create` transaction must have a sufficient $\tau$ balance to cover the burn cost of subnet creation, so called because the funds cannot be recovered. +You can confirm the emissions by running the `btcli subnets list` command: ```console -Subnet burn cost: τ 1,000.0000 -Your balance of: τ 0.0000 is not enough to burn τ 1,000.0000 to register a subnet. + Subnets + Network: custom + ┃ ┃ Price ┃ Market Cap ┃ ┃ P (τ_in, ┃ Stake ┃ ┃ + Netuid ┃ Name ┃ (τ_in/α_in) ┃ (α * Price) ┃ Emission (τ) ┃ α_in) ┃ (α_out) ┃ Supply (α) ┃ Tempo (k/n) +━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━━ + 0 │ τ root │ 1.0000 τ/Τ │ τ 0.00 │ τ 0.0000 │ -, - │ Τ 0.00 │ 0.00 Τ /21M │ -/- + 2 │ β │ 1.0000 τ/β │ τ 1.81k │ τ 1.0000 │ τ 1.00k, │ 414.00 β │ 1.81k β │ 29/360 + │ awesome-fi… │ │ │ │ 1.00k β │ │ /21M │ + 1 │ α apex │ 0.0000 τ/α │ τ 11.00 │ τ 0.0000 │ τ 10.00, │ 1.00 α │ 11.00 α │ 29/100 + │ │ │ │ │ 10.00 α │ │ /21M │ +────────┼─────────────┼─────────────┼─────────────┼──────────────┼─────────────┼──────────────┼─────────────┼───────────── + 4 │ │ τ 1.0 │ │ τ 1.0 │ τ │ │ │ + │ │ │ │ │ 1.41k/562.00│ │ │ + │ │ │ │ │ (6931.03%) │ │ │ ``` -To fix this, transfer TAO from the Alice account to cover this transaction and try again. For more information, see [Transfer TAO to wallets](./provision-wallets.md#transfer-tao-to-wallets) - -### Network Rate Limit Error - -If you see a network rate limit error, you may need to adjust the `SubtensorInitialNetworkRateLimit` chain state parameter. - -See [Clone and tweak the Subtensor source](./deploy#clone-and-tweak-the-subtensor-source) - ## Troubleshooting ### Insufficient funds @@ -161,10 +107,4 @@ Subnet burn cost: τ 1,000.0000 Your balance of: τ 0.0000 is not enough to burn τ 1,000.0000 to register a subnet. ``` -To fix this, transfer TAO from the Alice account to cover this transaction and try again. For more information, see [Transfer TAO to wallets](./provision-wallets.md#transfer-tao-to-wallets) - -### Network Rate Limit Error - -If you see a network rate limit error, you may need to adjust the `SubtensorInitialNetworkRateLimit` chain state parameter. - -See [Clone and tweak the Subtensor source](./deploy#clone-and-tweak-the-subtensor-source) +To fix this, transfer TAO from the Alice account to cover this transaction and try again. For more information, see [Transfer TAO to wallets](./provision-wallets.md#transfer-tao-to-wallets). diff --git a/docs/local-build/deploy.md b/docs/local-build/deploy.md index c4d55ec7c..4ce4a2501 100644 --- a/docs/local-build/deploy.md +++ b/docs/local-build/deploy.md @@ -53,15 +53,25 @@ Below are examples of how to run the container using each mode: - Fast blocks: Fast block mode reduces block processing time to _250ms per block_, enabling rapid chain progression. It allows faster feedback cycles for operations such as staking, subnet creation, and registration, making them ideal for local testing scenarios. To run the container in fast block mode, run the following command in your terminal: ```bash - docker run --rm --name test_local_chain_ -p 9944:9944 -p 9945:9945 ghcr.io/opentensor/subtensor-localnet:devnet-ready + docker run --name test_local_chain_ -p 9944:9944 -p 9945:9945 ghcr.io/opentensor/subtensor-localnet:devnet-ready ``` - Non-fast blocks: Non-fast block mode uses the default _12-second block time_, aligning with subtensor block intervals. While this mode utilizes the default block processing time, it also incorporates some enhancements—for example, subnets become eligible to start one minute after creation. To run the container in non-fast block mode, run the following command in your terminal: ```bash - docker run --rm --name test_local_chain_ -p 9944:9944 -p 9945:9945 ghcr.io/opentensor/subtensor-localnet:devnet-ready False + docker run --name test_local_chain_ -p 9944:9944 -p 9945:9945 ghcr.io/opentensor/subtensor-localnet:devnet-ready False ``` +:::info +By default, exiting the Docker container persists the state of the local chain instance running on it. You can resume running the container by running the following command: + +```sh +docker start /test_local_chain_ +``` + +For more information, see official [Docker documentation](https://docs.docker.com/reference/cli/docker/container/run/). +::: + ### 3. Verify your setup You can verify your local blockchain instance by checking the list of subnets available on your local blockchain. To do this, run the following command in the terminal: From 648979bdc2e0a142df414d44627e2738b36fb8e7 Mon Sep 17 00:00:00 2001 From: Dera Okeke Date: Tue, 29 Jul 2025 20:38:02 +0100 Subject: [PATCH 05/12] wip --- docs/local-build/create-subnet.md | 4 +++ docs/local-build/deploy.md | 4 +-- docs/local-build/provision-wallets.md | 20 ++++++++++-- docs/miners/index.md | 40 ++++++++++++------------ docs/validators/index.md | 45 +++++++++++++-------------- 5 files changed, 65 insertions(+), 48 deletions(-) diff --git a/docs/local-build/create-subnet.md b/docs/local-build/create-subnet.md index 22787d220..9cf77c139 100644 --- a/docs/local-build/create-subnet.md +++ b/docs/local-build/create-subnet.md @@ -108,3 +108,7 @@ Your balance of: τ 0.0000 is not enough to burn τ 1,000.0000 to register a sub ``` To fix this, transfer TAO from the Alice account to cover this transaction and try again. For more information, see [Transfer TAO to wallets](./provision-wallets.md#transfer-tao-to-wallets). + +## Next steps + +With emissions now active on your subnet, you can begin registering and running miners and validators to participate in the network. diff --git a/docs/local-build/deploy.md b/docs/local-build/deploy.md index 4ce4a2501..f8ebf86a2 100644 --- a/docs/local-build/deploy.md +++ b/docs/local-build/deploy.md @@ -53,13 +53,13 @@ Below are examples of how to run the container using each mode: - Fast blocks: Fast block mode reduces block processing time to _250ms per block_, enabling rapid chain progression. It allows faster feedback cycles for operations such as staking, subnet creation, and registration, making them ideal for local testing scenarios. To run the container in fast block mode, run the following command in your terminal: ```bash - docker run --name test_local_chain_ -p 9944:9944 -p 9945:9945 ghcr.io/opentensor/subtensor-localnet:devnet-ready + docker run --name local_chain -p 9944:9944 -p 9945:9945 ghcr.io/opentensor/subtensor-localnet:devnet-ready ``` - Non-fast blocks: Non-fast block mode uses the default _12-second block time_, aligning with subtensor block intervals. While this mode utilizes the default block processing time, it also incorporates some enhancements—for example, subnets become eligible to start one minute after creation. To run the container in non-fast block mode, run the following command in your terminal: ```bash - docker run --name test_local_chain_ -p 9944:9944 -p 9945:9945 ghcr.io/opentensor/subtensor-localnet:devnet-ready False + docker run --name local_chain -p 9944:9944 -p 9945:9945 ghcr.io/opentensor/subtensor-localnet:devnet-ready False ``` :::info diff --git a/docs/local-build/provision-wallets.md b/docs/local-build/provision-wallets.md index 560ad5a35..03a9e62a3 100644 --- a/docs/local-build/provision-wallets.md +++ b/docs/local-build/provision-wallets.md @@ -48,10 +48,12 @@ The following should be returned in the console: ## Provision wallets -You will need wallets for the different personas, i.e., subnet owner, subnet validator and subnet miner, in the subnet. +To proceed with this tutorial, you’ll need to create separate wallets for each role on the Bittensor blockchain. Specifically, create three wallets: one each for the subnet owner, validator, and miner. -- The subnet owner wallet creates and controls the subnet. -- The validator and miner will be registered to the subnet created by the owner. This ensures that the validator and miner can run the respective validator and miner scripts. +- The subnet owner wallet creates and controls the subnet—`sn-creator`. +- The validator and miner wallets will be registered on the created subnet—`test-validator` and `test-miner`. + +Using separate wallets for each role ensures they can independently run their respective processes and scripts. To create a wallet, run the following command in your terminal: @@ -80,3 +82,15 @@ Replace `DESTINATION_ADDRESS` with the wallet address you want to send the TAO t :::info Run the `btcli wallets list` command and carefully check the ss58 address of the destination coldkey that you want to fund. ::: + +To confirm your wallet balances, run the following command in your terminal: + +```sh +btcli wallet balance --wallet.name WALLET_NAME --network ws://127.0.0.1:9945 +``` + +## Next steps + +Now that you have created the necessary wallets and funded them with TAO, you can proceed to create a subnet on the local chain. This will enable you to register validators and miners, configure subnet parameters, and begin participating in the network’s consensus and emissions processes. + +To begin, see [Create a subnet locally](create-subnet.md). diff --git a/docs/miners/index.md b/docs/miners/index.md index a303cfe11..02e8ff951 100644 --- a/docs/miners/index.md +++ b/docs/miners/index.md @@ -74,7 +74,6 @@ Deregistration only occurs on subnets where all 256 UID slots are occupied. If a Each tempo, the '[neuron](../learn/neurons)' (miner _or_ validator node) with the lowest 'pruning score' (based solely on emissions), and that is no longer within its [immunity period](../subnets/subnet-hyperparameters.md#immunityperiod), risks being replaced by a newly registered neuron, who takes over that UID. - :::info Deregistration is based on emissions The subnet does not distinguish between miners and validators for the purpose of deregistration. The chain only looks at emissions (represented as 'pruning score'). Whenever a new registration occurs in the subnet, the neuron with the lowest emissions will get deregistered. ::: @@ -88,12 +87,13 @@ A subnet neuron (miner or validator) at a UID (in that subnet) has `immunity_per **Implementation Details:** Immunity status is calculated dynamically using the formula `is_immune = (current_block - registered_at) < immunity_period`, where: + - `current_block` is the current blockchain block number - `registered_at` is the block number when the neuron was registered - `immunity_period` is the configured protection period for the subnet (default: 4096 blocks ≈ 13.7 hours) - **Code References:** + - [`subtensor/pallets/subtensor/src/utils/misc.rs:442-448`](https://github.com/opentensor/subtensor/blob/main/pallets/subtensor/src/utils/misc.rs#L442-448) - Immunity status calculation - [`subtensor/pallets/subtensor/src/subnets/registration.rs:409-485`](https://github.com/opentensor/subtensor/blob/main/pallets/subtensor/src/subnets/registration.rs#L409-485) - Pruning algorithm with immunity priority @@ -153,24 +153,24 @@ btcli wallet overview --netuid After providing your wallet name when prompted, you will see output such as: -| Parameter | Example value | Description | -| :---------- | :----------------- | :-------------------------------------------------------------------------- | -| COLDKEY | my_coldkey | The name of the coldkey associated with your slot. | -| HOTKEY | my_first_hotkey | The name of the hotkey associated with your slot. | -| UID | 5 | The index of the uid out of available uids. | -| ACTIVE | True | The validator has set weights within the subnet's activity_cutoff | -| STAKE(τ) | 71.296 | The amount of stake in this wallet. | -| RANK | 0.0629 | This miner's absolute ranking according to validators on the network. | -| TRUST | 0.2629 | This miner's trust as a proportion of validators on the network. | -| CONSENSUS | 0.89 | This validator's aggregate consensus score. | -| INCENTIVE | 0.029 | This miner's incentive, TAO emission, is attained via mining. | -| DIVIDENDS | 0.001 | This validator's dividends, TAO emission, are attained via validating. | -| EMISSION | 29_340_153 | This miner's total emission in RAO (10^(-9) TAO) per block. | -| VTRUST | 0.96936 | This validator's trust score as a validator. | -| VPERMIT | \* | For validators: The uid is considered active for validating on this subnet. | -| UPDATED | 43 | Blocks since this miner set weights on the chain. | -| AXON | 131.186.56.85:8091 | The entrypoint advertised by this miner on the bittensor blockchain. | -| HOTKEY_SS58 | 5F4tQyWr... | The ss58-encoded address of the miner's hotkey. | +| Parameter | Example value | Description | +| :---------- | :----------------- | :------------------------------------------------------------------------------------- | +| COLDKEY | my_coldkey | The name of the coldkey associated with your slot. | +| HOTKEY | my_first_hotkey | The name of the hotkey associated with your slot. | +| UID | 5 | Unique identifier of the neuron. | +| ACTIVE | True | Whether or not the uid is considered active. | +| STAKE(τ) | 71.296 | The amount of stake in this wallet. | +| RANK | 0.0629 | This miner's absolute ranking according to validators on the network. | +| TRUST | 0.2629 | This miner's trust score as a proportion of validators on the network. | +| CONSENSUS | 0.89 | The consensus score of the neuron. | +| INCENTIVE | 0.029 | Thencentive score representing the miner's incentive alignment. | +| DIVIDENDS | 0.001 | The dividends earned by the neuron for validating on the subnet. | +| EMISSION | 29_340_153 | The emission in RAO (p) received by the neuron. | +| VTRUST | 0.96936 | The validator trust score indicating the network's trust in the neuron as a validator. | +| VPERMIT | \* | Whether this neuron is considered eligible for validating on this subnetwork. | +| UPDATED | 43 | Blocks since the neuron set weights on the chain. | +| AXON | 131.186.56.85:8091 | The entrypoint advertised by this miner on the bittensor blockchain. | +| HOTKEY_SS58 | 5F4tQyWr... | The ss58-encoded address of the miner's hotkey. | ## Checking miner registration status diff --git a/docs/validators/index.md b/docs/validators/index.md index 5ad175762..1e7a4e27e 100644 --- a/docs/validators/index.md +++ b/docs/validators/index.md @@ -98,11 +98,13 @@ A subnet neuron (miner or validator) at a UID (in that subnet) has `immunity_per **Implementation Details:** Immunity status is calculated dynamically using the formula `is_immune = (current_block - registered_at) < immunity_period`, where: + - `current_block` is the current blockchain block number - `registered_at` is the block number when the neuron was registered - `immunity_period` is the configured protection period for the subnet (default: 4096 blocks ≈ 13.7 hours) **Code References:** + - [`subtensor/pallets/subtensor/src/utils/misc.rs:442-448`](https://github.com/opentensor/subtensor/blob/main/pallets/subtensor/src/utils/misc.rs#L442-448) - Immunity status calculation - [`subtensor/pallets/subtensor/src/subnets/registration.rs:409-485`](https://github.com/opentensor/subtensor/blob/main/pallets/subtensor/src/subnets/registration.rs#L409-485) - Pruning algorithm with immunity priority @@ -151,11 +153,10 @@ import bittensor as bt subnet = bt.metagraph(1) wallet = bt.wallet( name = 'my_coldkey', hotkey = 'my_validator_hotkey' ) my_uid = subnet.hotkeys.index( wallet.hotkey.ss58_address ) -print(f'Validator permit: {subnet.validator_permit(my_uid)}') +print(f'Validator permit: {subnet.validator_permit[my_uid]}') ``` -## Validator Permits - +## Validator Permits Validator permits control which neurons can participate in validation activities within a subnet. The system operates on a stake-weighted basis, ensuring that only high-stake, trusted neurons can influence consensus. @@ -184,14 +185,12 @@ To obtain a validator permit, a neuron must meet these criteria: - **Top K Ranking**: Be among the top K neurons by stake weight - **Active Status**: Maintain active participation in the subnet - ### Code References - Validator permit calculation: [`subtensor/pallets/subtensor/src/epoch/run_epoch.rs:520-523`](https://github.com/opentensor/subtensor/blob/main/pallets/subtensor/src/epoch/run_epoch.rs#L520-523) - Top-K selection algorithm: [`subtensor/pallets/subtensor/src/epoch/math.rs:250-260`](https://github.com/opentensor/subtensor/blob/main/pallets/subtensor/src/epoch/math.rs#L250-260) - Access control: [`subtensor/pallets/subtensor/src/subnets/weights.rs:745-748`](https://github.com/opentensor/subtensor/blob/main/pallets/subtensor/src/subnets/weights.rs#L745-748) - ## Inspecting UIDs After you obtain a UID slot, you can view the status of your registered wallet by running: @@ -202,24 +201,24 @@ btcli wallet overview --netuid After providing your wallet name at the prompt, you will see output like: -| Parameter | Example value | Description | -| :---------- | :----------------- | :------------------------------------------------------------------------- | -| COLDKEY | my_coldkey | The name of the coldkey associated with your slot. | -| HOTKEY | my_first_hotkey | The name of the hotkey associated with your slot. | -| UID | 5 | The index of the uid out of available uids. | -| ACTIVE | True | Whether or not the uid is considered active. | -| STAKE(τ) | 71.296 | The amount of stake in this wallet. | -| RANK | 0.0629 | This miner's absolute ranking according to validators on the network. | -| TRUST | 0.2629 | This miner's trust as a proportion of validators on the network. | -| CONSENSUS | 0.89 | This validator's aggregate consensus score. | -| INCENTIVE | 0.029 | This miner's incentive, TAO emission, is attained via mining. | -| DIVIDENDS | 0.001 | This validator's dividends, TAO emission, are attained via validating. | -| EMISSION | 29_340_153 | This miner's total emission in RAO (10^(-9) TAO) per block. | -| VTRUST | 0.96936 | This validator's trust score as a validator. | -| VPERMIT | \* | Whether this miner is considered active for validating on this subnetwork. | -| UPDATED | 43 | Blocks since this miner set weights on the chain. | -| AXON | 131.186.56.85:8091 | The entrypoint advertised by this miner on the bittensor blockchain. | -| HOTKEY_SS58 | 5F4tQyWr... | The ss58-encoded address of the miner's hotkey. | +| Parameter | Example value | Description | +| :---------- | :----------------- | :------------------------------------------------------------------------------------- | +| COLDKEY | my_coldkey | The name of the coldkey associated with your slot. | +| HOTKEY | my_first_hotkey | The name of the hotkey associated with your slot. | +| UID | 5 | Unique identifier of the neuron. | +| ACTIVE | True | Whether or not the uid is considered active. | +| STAKE(τ) | 71.296 | The amount of stake in this wallet. | +| RANK | 0.0629 | This miner's absolute ranking according to validators on the network. | +| TRUST | 0.2629 | This miner's trust score as a proportion of validators on the network. | +| CONSENSUS | 0.89 | The consensus score of the neuron. | +| INCENTIVE | 0.029 | Thencentive score representing the miner's incentive alignment. | +| DIVIDENDS | 0.001 | The dividends earned by the neuron for validating on the subnet. | +| EMISSION | 29_340_153 | The emission in RAO (p) received by the neuron. | +| VTRUST | 0.96936 | The validator trust score indicating the network's trust in the neuron as a validator. | +| VPERMIT | \* | Whether this neuron is considered eligible for validating on this subnetwork. | +| UPDATED | 43 | Blocks since the neuron set weights on the chain. | +| AXON | 131.186.56.85:8091 | The entrypoint advertised by this miner on the bittensor blockchain. | +| HOTKEY_SS58 | 5F4tQyWr... | The ss58-encoded address of the miner's hotkey. | ### Meaning of ACTIVE From fe96783afdb1085a1050bfcf0f09761fb7e334bb Mon Sep 17 00:00:00 2001 From: Dera Okeke Date: Wed, 6 Aug 2025 22:28:01 +0100 Subject: [PATCH 06/12] localnet docs wip --- docs/local-build/create-subnet.md | 2 +- docs/local-build/mine-validate.md | 138 ++++++++++++++++++++++++++---- sidebars.js | 12 +-- 3 files changed, 127 insertions(+), 25 deletions(-) diff --git a/docs/local-build/create-subnet.md b/docs/local-build/create-subnet.md index 9cf77c139..50728a2f1 100644 --- a/docs/local-build/create-subnet.md +++ b/docs/local-build/create-subnet.md @@ -8,7 +8,7 @@ This page covers creating a subnet on a locally deployed Subtensor blockchain, w For creating a subnet on Bittensor test and main network, see [Create a Subnet](../subnets/create-a-subnet). -## Prerequisites: +## Prerequisites Before continuing with the rest of this tutorial, make sure you've completed the following: diff --git a/docs/local-build/mine-validate.md b/docs/local-build/mine-validate.md index 888b21663..649ec113c 100644 --- a/docs/local-build/mine-validate.md +++ b/docs/local-build/mine-validate.md @@ -1,45 +1,147 @@ --- -title: "Mine and Validate (Locally)" +title: "Mining and Validating on Localnet" --- -# Mine and Validate (Locally) +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; -This page continues the tutorial series on local Bittensor development. In this installment, we will deploy minimal, local servers for a miner and validators, serving requests, setting weights, and earning emissions. +# Mining and Validating on Localnet +This page walks through mining and validating on a local Bittensor network. It covers how to register a neuron on a subnet, then run the miner and validator scripts to begin earning emissions. + +For mining and validating on the Bittensor mainnet, see [Mining in Bittensor](../miners/index.md) and [Validating in Bittensor](../validators/index.md). ## Prerequisites +Before continuing with the rest of this tutorial, make sure you've completed the following: + - [Deploy a Subtensor chain locally](./deploy) -- [Provision wallets for the sn-creator, miner, and validator users for this tutorial.](./provision-wallets) -- [Create a Subnet on your local chain](./create-subnet) +- [Provision wallets for the subnet creator, miner, and validator users for this tutorial.](./provision-wallets) +- [Created and started a subnet](./create-subnet) to enable emissions. + +This guide uses Opentensor's [_subnet template_](https://github.com/opentensor/subnet-template/tree/main) repo. The repo provides a minimal implementation for building a custom subnet on the Bittensor network and includes the core logic for the miner and validator. -## Register +## 1. Register the hotkeys -Register the subnet miner and validator with the following commands: +To participate in a subnet, you must first register a hotkey on it. This registration assigns the wallet a unique identifier (UID), which is required to interact with and receive emissions from the subnet. + +To register the hotkey, run the following command in your terminal, replacing `NETUID`, `WALLET_NAME`, and `WALLET_HOTKEY` with the target subnet ID, the name of the wallet, and the associated hotkey, respectively, as shown: ```bash -btcli subnet register \ ---wallet.name validator \ ---wallet.hotkey default \ ---network ws://127.0.0.1:9945 +btcli subnets register --netuid NETUID \ +--wallet-name WALLET_NAME \ +--hotkey WALLET_HOTKEY ``` + +You will be prompted to confirm the registration fee and enter your wallet password to authorize the transaction. + +
+Show Sample Output + +```console +Warning: Verify your local subtensor is running on port 9944. subtensor_interface.py:88 +Using the specified network local from config + + Register to netuid: 2 + Network: local + + Netuid ┃ Symbol ┃ Cost (Τ) ┃ Hotkey ┃ Coldkey +━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + 2 │ γ │ τ 0.0985 │ 5FErfAJc3Wf32TVLQTtM....TRTrgMF4sjYWfq49oMCxXxqS │ 5Gxhv5iZGBvvR6YJeEdLmvZ7hS....dHc43fLqMVkhki7j4 +────────┼────────┼──────────┼──────────────────────────────────────────────────┼────────────────────────────────────────────────── + │ │ │ │ +Your balance is: 99,999.9000 τ +The cost to register by recycle is 0.0985 τ +Do you want to continue? [y/n] (n): y +Enter your password: +Decrypting... +Balance: + 99,999.9000 τ ➡ 99,999.8015 τ +✅ Registered on netuid 3 with UID 2 +``` + +
+ +Repeat the registration process for both the miner and validator hotkeys. + +## 2. Acquire validator permit + +To qualify as a validator on a subnet, a registered node must have a validator permit. This permit allows nodes to submit miner evaluations and set weights on a subnet. For more information, see [validator permits] + +To get validator permits on the demo subnet, you need to stake sufficient TAO to the validator hotkey. To do this, run the following command in the terminal: + ```bash -btcli subnet register \ ---netuid 2 \ ---wallet.name miner \ ---wallet.hotkey default \ ---network ws://127.0.0.1:9945 +btcli stake add --netuid NETUID \ +--wallet-name WALLET_NAME \ +--hotkey WALLET_HOTKEY \ +--partial ``` +Replace `NETUID`, `WALLET_NAME`, and `WALLET_HOTKEY` with the target subnet ID, the name of the wallet, and the associated hotkey, respectively. +Once you've staked enough TAO to the validator hotkey, the validator becomes eligible to submit evaluations and set weights on the subnet. You can verify that the validator has been granted a permit using any of the following methods: + + + +Run the following command in the terminal: +```bash +btcli wallet overview --wallet.name WALLET_NAME +``` +Replace the `WALLET_NAME` with the name of the validator wallet. + +
+Show Sample Output + +```console +Warning: Verify your local subtensor is running on port 9944. subtensor_interface.py:88 +Using the specified network local from config + Wallet + + test-validator : 5Gxhv5iZGBvvR6YJeEd...bE6FdHc43fLqMVkhki7j4 + Network: local +Subnet: 2: New subnett β + + COLDKEY HOTKEY UID ACTIVE STAKE(β) RANK TRUST CONSENSUS INCENTIVE DIVIDENDS EMISSION(… VTRUST VPE… UPDAT… AXON HOTKEY_SS58 + ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────── + test-validator test-validator 1 False 287.57 0.00 0.00 0.00 0.00 0.00 38841066.… 0.00 * 5908 none 5FErfAJc3W + ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────── + 1 287.57 β 0.0000 0.0000 0.0000 0.0000 0.0000 ρ38841066 0.0000 + +``` + +
+ +If the validator wallet has a validator permit, an asterisk (`*`) will appear under the `VPERMIT` column for the corresponding subnet in the response table. + + + +Input the following lines in your Python environment, replacing `NETUID`, `WALLET_NAME`, and `WALLET_HOTKEY` with the target subnet ID, the name of the wallet, and the associated hotkey, respectively. + +```python +import bittensor as bt +network=bt.subtensor(network="local") +subnet = network.metagraph(NETUID) +wallet = bt.wallet( name = 'WALLET_NAME', hotkey = 'HOTKEY' ) +my_uid = subnet.hotkeys.index( wallet.hotkey.ss58_address ) +print(f'Validator permit: {subnet.validator_permit[my_uid]}') +``` + +The command outputs `True` or `False` depending on whether the validator hotkey has a permit. + + + +--- ### Troubleshoot + #### Insufficient funds + If you have not added TAO to your validator wallet, you'll see an error like the following: ```console Insufficient balance τ 0.0000 to register neuron. Current recycle is τ 1.0000 TAO ``` + Transfer funds from the Alice account to cover it and try again. Consult `btcli w list` and carefully check the ss58 address of the destination coldkey (in this case, the one with the name `validator`). ```shell @@ -50,10 +152,10 @@ btcli wallet transfer \ --network ws://127.0.0.1:9945 ``` - ### Successful registration Repeat the above steps to successfully register your miner and validator once they are funded + ```console netuid: 2 @@ -122,4 +224,4 @@ Subnet: 2: awesome-first-subnet β ```shell python3 neurons/miner.py netuid=2 -chain_endpoint=ws://127.0.0.1:9945 wallet_name=miner wallet_hotkey=default -``` \ No newline at end of file +``` diff --git a/sidebars.js b/sidebars.js index 1823641be..a59dfa242 100644 --- a/sidebars.js +++ b/sidebars.js @@ -86,9 +86,9 @@ const sidebars = { label: "Liquidity Positions (Uniswap)", collapsible: true, collapsed: true, - items: [ - 'liquidity-positions/liquidity-positions', - 'liquidity-positions/managing-liquidity-positions' + items: [ + "liquidity-positions/liquidity-positions", + "liquidity-positions/managing-liquidity-positions", ], }, { @@ -98,14 +98,14 @@ const sidebars = { collapsed: true, items: [ "subnets/metagraph", - "subnets/create-a-subnet", + "subnets/create-a-subnet", "subnets/subnet-creators-btcli-guide", "subnets/subnet-hyperparameters", "subnets/working-with-subnets", "subnets/walkthrough-prompting", "tutorials/basic-subnet-tutorials", "tutorials/ocr-subnet-tutorial", - "subnets/yuma3-migration-guide" + "subnets/yuma3-migration-guide", ], }, { @@ -178,7 +178,7 @@ const sidebars = { "local-build/deploy", "local-build/provision-wallets", "local-build/create-subnet", - // "local-build/mine-validate" + "local-build/mine-validate", ], }, From 0575c31820a5d7781ef2276f3eb7bbd4e6185e39 Mon Sep 17 00:00:00 2001 From: Dera Okeke Date: Sat, 9 Aug 2025 01:43:07 +0100 Subject: [PATCH 07/12] run miner & validator --- docs/local-build/mine-validate.md | 106 +++++++++++++++++++++++++++--- 1 file changed, 98 insertions(+), 8 deletions(-) diff --git a/docs/local-build/mine-validate.md b/docs/local-build/mine-validate.md index 649ec113c..9bb055767 100644 --- a/docs/local-build/mine-validate.md +++ b/docs/local-build/mine-validate.md @@ -30,7 +30,8 @@ To register the hotkey, run the following command in your terminal, replacing `N ```bash btcli subnets register --netuid NETUID \ --wallet-name WALLET_NAME \ ---hotkey WALLET_HOTKEY +--hotkey WALLET_HOTKEY \ +--network ws://127.0.0.1:9945 ``` You will be prompted to confirm the registration fee and enter your wallet password to authorize the transaction. @@ -47,7 +48,7 @@ Using the specified network local from config Netuid ┃ Symbol ┃ Cost (Τ) ┃ Hotkey ┃ Coldkey ━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ - 2 │ γ │ τ 0.0985 │ 5FErfAJc3Wf32TVLQTtM....TRTrgMF4sjYWfq49oMCxXxqS │ 5Gxhv5iZGBvvR6YJeEdLmvZ7hS....dHc43fLqMVkhki7j4 + 2 │ β │ τ 0.0985 │ 5FErfAJc3Wf32TVLQTtM....TRTrgMF4sjYWfq49oMCxXxqS │ 5Gxhv5iZGBvvR6YJeEdLmvZ7hS....dHc43fLqMVkhki7j4 ────────┼────────┼──────────┼──────────────────────────────────────────────────┼────────────────────────────────────────────────── │ │ │ │ Your balance is: 99,999.9000 τ @@ -64,6 +65,48 @@ Balance: Repeat the registration process for both the miner and validator hotkeys. +To confirm the registration of your hotkeys in the subnet, run the following command in your terminal: + +```sh +btcli subnet show --netuid NETUID --network ws://127.0.0.1:9945 +``` + +The command returns detailed information about a subnet including its registered neurons and their state. + +
+Show Sample Output + +```console + +Warning: Verify your local subtensor is running on port 9944. subtensor_interface.py:89 + + + + Subnet 2: New subnet + Network: local + + UID ┃ Stake (β) ┃ Alpha (β) ┃ Tao (τ) ┃ Dividends ┃ Incentive ┃ Emissions (β) ┃ Hotkey ┃ Coldkey ┃ Identity +━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━ + 0 │ 5.04 β │ 5.04 β │ τ 0.00 │ 0.000000 │ 0.000000 │ 9.017303 β │ 5DFZTw │ 5Dc1Qu │ (*Owner controlled) + 1 │ 0.00 β │ 1.00 β │ τ 0.00 │ 0.000000 │ 0.000000 │ 0.000000 β │ 5FErfA │ 5GxHV5 │ ~ + 2 │ 0.00 β │ 1.00 β │ τ 0.00 │ 0.000000 │ 0.000000 │ 0.000000 β │ 5Ft364 │ 5GuuKE │ ~ +─────┼───────────┼───────────┼─────────┼───────────┼───────────┼───────────────┼────────┼─────────┼───────────────────── + │ 5.04 β │ 5.04 β │ 0.00 β │ 0.000 │ │ 9.017303 β │ │ │ + + +Subnet 1: apex + Owner: 5Dc1Qujw9DjXZTzV3MwzrrAr9P1MJhSrvWGWqi1eSuyUpnhM + Rate: 1.0056 τ/β + Emission: τ 0.0000 + TAO Pool: τ 1.10k + Alpha Pool: 1.10 β + Tempo: 8/10 + Registration cost (recycled): τ 0.0845 + +``` + +
+ ## 2. Acquire validator permit To qualify as a validator on a subnet, a registered node must have a validator permit. This permit allows nodes to submit miner evaluations and set weights on a subnet. For more information, see [validator permits] @@ -74,7 +117,8 @@ To get validator permits on the demo subnet, you need to stake sufficient TAO to btcli stake add --netuid NETUID \ --wallet-name WALLET_NAME \ --hotkey WALLET_HOTKEY \ ---partial +--partial \ +--network ws://127.0.0.1:9945 ``` Replace `NETUID`, `WALLET_NAME`, and `WALLET_HOTKEY` with the target subnet ID, the name of the wallet, and the associated hotkey, respectively. @@ -85,7 +129,7 @@ Once you've staked enough TAO to the validator hotkey, the validator becomes eli Run the following command in the terminal: ```bash -btcli wallet overview --wallet.name WALLET_NAME +btcli wallet overview --wallet.name WALLET_NAME --network ws://127.0.0.1:9945 ``` Replace the `WALLET_NAME` with the name of the validator wallet. @@ -99,7 +143,7 @@ Using the specified network local from config test-validator : 5Gxhv5iZGBvvR6YJeEd...bE6FdHc43fLqMVkhki7j4 Network: local -Subnet: 2: New subnett β +Subnet: 2: New subnet β COLDKEY HOTKEY UID ACTIVE STAKE(β) RANK TRUST CONSENSUS INCENTIVE DIVIDENDS EMISSION(… VTRUST VPE… UPDAT… AXON HOTKEY_SS58 ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────── @@ -107,11 +151,12 @@ Subnet: 2: New subnett β ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────── 1 287.57 β 0.0000 0.0000 0.0000 0.0000 0.0000 ρ38841066 0.0000 + Wallet free balance: 99,994.3638 τ ``` -If the validator wallet has a validator permit, an asterisk (`*`) will appear under the `VPERMIT` column for the corresponding subnet in the response table. +If the validator wallet has a validator permit, an asterisk (`*`) is shown under the `VPERMIT` column for the corresponding subnet in the response table. @@ -130,9 +175,54 @@ The command outputs `True` or `False` depending on whether the validator hotkey ---- +:::info Validator Permits on Localnet Subnets +On localnet subnets, competition for permits is typically minimal. After staking TAO to the validator hotkey, the neuron should become eligible for a validator permit. If it does not yet have one, wait until the end of the subnet’s tempo. +::: + +## 3. Pull the `subnet-template` repo + +The `subnet-template` repo contains the core logic for the subnet miner and validator. It features a simple `dummy` protocol where miners multiply input values by 2, while validators evaluate responses and update network weights based on performance. + +To begin, clone the subnet-template GitHub repository and navigate into its directory: + +```sh +git clone https://github.com/opentensor/subnet-template.git +cd subnet-template +``` + +## 4. Run the miner and validator + +After getting the validator permits, you can now run the validator alongside the miner to begin participating in the subnet. + +Begin by starting the miner process to produce and submit work to the subnet. Then, run the validator process to evaluate miner outputs and set weights for the network. + +### Start the miner process + +To start the miner, run the following Python script in the `subnet-template` directory: + +```sh +python validator.py \ + --wallet.name WALLET_NAME \ + --wallet.hotkey HOTKEY \ + --netuid NETUID \ + --subtensor.network local +``` + +The script launches an Axon server on port `8901`, which the miner uses to receive incoming requests from validators. + +### Start the validator process + +To start the validator process, run the following Python script in the `subnet-template` directory: + +```sh +python validator.py \ + --wallet.name WALLET_NAME \ + --wallet.hotkey HOTKEY \ + --netuid NETUID \ + --subtensor.network local +``` -### Troubleshoot +## Troubleshoot #### Insufficient funds From 9a811d51c650e51f4e40fcbe1c9f9fb3782c5dd3 Mon Sep 17 00:00:00 2001 From: Dera Okeke Date: Mon, 11 Aug 2025 17:34:32 +0100 Subject: [PATCH 08/12] localnet wip: emissions --- docs/local-build/mine-validate.md | 114 +++++++++++------------------- 1 file changed, 40 insertions(+), 74 deletions(-) diff --git a/docs/local-build/mine-validate.md b/docs/local-build/mine-validate.md index 9bb055767..5dd42e814 100644 --- a/docs/local-build/mine-validate.md +++ b/docs/local-build/mine-validate.md @@ -94,13 +94,13 @@ Warning: Verify your local subtensor is running on port 9944. │ 5.04 β │ 5.04 β │ 0.00 β │ 0.000 │ │ 9.017303 β │ │ │ -Subnet 1: apex - Owner: 5Dc1Qujw9DjXZTzV3MwzrrAr9P1MJhSrvWGWqi1eSuyUpnhM +Subnet 2: New subnet + Owner: 5Dc1Qu2pDfWuDzt3c5wJV2LxRXAmVqZYsAib72e59H3vnRVn Rate: 1.0056 τ/β Emission: τ 0.0000 TAO Pool: τ 1.10k Alpha Pool: 1.10 β - Tempo: 8/10 + Tempo: 8/360 Registration cost (recycled): τ 0.0845 ``` @@ -201,10 +201,11 @@ Begin by starting the miner process to produce and submit work to the subnet. Th To start the miner, run the following Python script in the `subnet-template` directory: ```sh -python validator.py \ +python miner.py \ --wallet.name WALLET_NAME \ --wallet.hotkey HOTKEY \ --netuid NETUID \ + --axon.port 8901 \ --subtensor.network local ``` @@ -222,96 +223,61 @@ python validator.py \ --subtensor.network local ``` -## Troubleshoot +This script begins the process of sending inputs to the miners and setting weights based on miner responses. -#### Insufficient funds +:::info miner and validator logs +Use the `--logging.info` flag to print miner and validator log messages directly to the console. This helps you monitor activity in real time without checking log files. +::: -If you have not added TAO to your validator wallet, you'll see an error like the following: +## 5. Check your emissions -```console -Insufficient balance τ 0.0000 to register neuron. Current recycle is τ 1.0000 TAO -``` +After weights have been successfully set on the subnet, you can check the updated emissions distribution at the end of the subnet's [tempo](../glossary.md#tempo). -Transfer funds from the Alice account to cover it and try again. Consult `btcli w list` and carefully check the ss58 address of the destination coldkey (in this case, the one with the name `validator`). +To check the subnet's emissions, run the following command in the terminal: -```shell -btcli wallet transfer \ ---amount 11 \ ---wallet.name alice \ ---destination "5EEy34..." \ ---network ws://127.0.0.1:9945 +```sh +btcli subnet show --netuid NETUID --network ws://127.0.0.1:9945 ``` -### Successful registration +The command returns detailed information about a subnet, including its registered neurons, their current state, and updated emission earnings. -Repeat the above steps to successfully register your miner and validator once they are funded +
+Show Sample Output ```console -netuid: 2 +Using the specified network local from config +Warning: Verify your local subtensor is running on port 9944. subtensor_interface.py:89 - Register to netuid: 2 - Network: custom - Netu… ┃ Sym… ┃ Cost (… ┃ Hotkey ┃ Coldkey -━━━━━━━╇━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ - 2 │ β │ τ 1.00… │ 5CffqSVhydFJHBSbbgfVLAVkoNBTsv3wLj2Tsh1cr2kfa… │ 5EEy34R4gfXe5SG62nz1nDuh3KAovRLpKLm4ccSv7qkNhn… -───────┼──────┼─────────┼────────────────────────────────────────────────┼───────────────────────────────────────────────── - │ │ │ │ -Your balance is: τ 11.0000 -The cost to register by recycle is τ 1.0000 -Do you want to continue? [y/n] (n): y -Enter your password: -Decrypting... -Balance: - τ 11.0000 ➡ τ 10.0000 -✅ Registered on netuid 2 with UID 1 -▰▱▱▱▱▱▱ 📡 Recycling TAO for Registration... -``` -### Check your registration + Subnet 2: New subnet + Network: local -Confirm your registration on the subnet with the following command: + UID ┃ Stake (β) ┃ Alpha (β) ┃ Tao (τ) ┃ Dividends ┃ Incentive ┃ Emissions (β) ┃ Hotkey ┃ Coldkey ┃ Identity +━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━ + 0 │ 109.80 β │ 109.80 β │ τ 0.00 │ 0.000000 │ 0.000000 │ 0.000000 β │ 5DFZTw │ 5Dc1Qu │ (*Owner controlled) + 1 │ 354.68 β │ 354.68 β │ τ 0.00 │ 1.000000 │ 0.000000 │ 148.010826 β │ 5FErfA │ 5Gxhv5 │ Test validator + 2 │ 148.01 β │ 148.01 β │ τ 0.00 │ 0.000000 │ 1.000000 │ 148.010826 β │ 5GRLEv │ 5EnNgi │ Test miner +─────┼───────────┼───────────┼─────────┼───────────┼───────────┼───────────────┼────────┼─────────┼───────────────────── + │ 612.49 β │ 612.49 β │ 0.00 β │ 1.000 │ │ 296.0217 β │ │ │ -```shell -btcli wallet overview --wallet.name validator --network ws://127.0.0.1:9945 -btcli wallet overview --wallet.name miner --network ws://127.0.0.1:9945 +Subnet 2: New subnet + Owner: 5Dc1Qu2pDfWuDzt3c5wJV2LxRXAmVqZYsAib72e59H3vnRVn + Rate: 1.0054 τ/β + Emission: τ 0.0000 + TAO Pool: τ 1.62k + Alpha Pool: 1.61k β + Tempo: 23/360 + Registration cost (recycled): τ 0.1000 ``` -```console - Wallet - - validator : 5EEy34R4gfXe5SG62nz1nDuh3KAovRLpKLm4ccSv7qkNhnqw - Network: custom -Subnet: 2: awesome-first-subnet β - - COLDKEY HOTKEY UID AC… STA… RANK TRU… CON… INC… DIV… EMI… VTR… … U… AXON HOTKE… - ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────── - valida… default 1 Tr… 0.00 0.00 0.00 0.00 0.00 0.00 0.0… 0.00 51 none 5Cffq… - ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────── - 1 0.0… 0.0… 0.0… 0.0… 0.0… 0.0… ρ0 0.0… - - - Wallet balance: τ10.0 - - Wallet - - miner : 5DA7UsaYbk1UnhhtTxqpwdqjuxhQ2rW7D6GTN1S1S5tC2NRV - Network: custom -Subnet: 2: awesome-first-subnet β - - COLDKEY HOTKEY UID AC… STA… RANK TRU… CON… INC… DIV… EMI… VTR… … U… AXON HOTKE… - ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────── - miner default 2 Tr… 0.00 0.00 0.00 0.00 0.00 0.00 0.0… 0.00 22 none 5Capz… - ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────── - 1 0.0… 0.0… 0.0… 0.0… 0.0… 0.0… ρ0 0.0… +Note the increase in the miner neuron's `Incentive` column and the validator neuron's `Dividend` column as well as the `Emissions` on both neurons. +
- Wallet balance: τ10.0 -``` +For more information on a subnet's emission distribution, see [Emissions](../emissions.md). -```shell -python3 neurons/miner.py netuid=2 -chain_endpoint=ws://127.0.0.1:9945 wallet_name=miner wallet_hotkey=default -``` +## Troubleshoot From f66a0336bf6fd8939fe5686e4dd6d1b1100f9224 Mon Sep 17 00:00:00 2001 From: Dera Okeke Date: Tue, 12 Aug 2025 10:55:50 +0100 Subject: [PATCH 09/12] mine and validation docs done --- docs/local-build/deploy.md | 10 ++---- docs/local-build/mine-validate.md | 60 +++++++++++++++++++++++++++++-- 2 files changed, 60 insertions(+), 10 deletions(-) diff --git a/docs/local-build/deploy.md b/docs/local-build/deploy.md index f8ebf86a2..db43924f4 100644 --- a/docs/local-build/deploy.md +++ b/docs/local-build/deploy.md @@ -53,21 +53,17 @@ Below are examples of how to run the container using each mode: - Fast blocks: Fast block mode reduces block processing time to _250ms per block_, enabling rapid chain progression. It allows faster feedback cycles for operations such as staking, subnet creation, and registration, making them ideal for local testing scenarios. To run the container in fast block mode, run the following command in your terminal: ```bash - docker run --name local_chain -p 9944:9944 -p 9945:9945 ghcr.io/opentensor/subtensor-localnet:devnet-ready + docker run --rm --name local_chain -p 9944:9944 -p 9945:9945 ghcr.io/opentensor/subtensor-localnet:devnet-ready ``` - Non-fast blocks: Non-fast block mode uses the default _12-second block time_, aligning with subtensor block intervals. While this mode utilizes the default block processing time, it also incorporates some enhancements—for example, subnets become eligible to start one minute after creation. To run the container in non-fast block mode, run the following command in your terminal: ```bash - docker run --name local_chain -p 9944:9944 -p 9945:9945 ghcr.io/opentensor/subtensor-localnet:devnet-ready False + docker run --rm --name local_chain -p 9944:9944 -p 9945:9945 ghcr.io/opentensor/subtensor-localnet:devnet-ready False ``` :::info -By default, exiting the Docker container persists the state of the local chain instance running on it. You can resume running the container by running the following command: - -```sh -docker start /test_local_chain_ -``` +By default, exiting the Docker container removes the image container with the local chain instance; thus, deleting the state of the local chain instance running on it. You can modify this behavior by when running the container wihtout the `--rm` flag. For more information, see official [Docker documentation](https://docs.docker.com/reference/cli/docker/container/run/). ::: diff --git a/docs/local-build/mine-validate.md b/docs/local-build/mine-validate.md index 5dd42e814..69ec9df45 100644 --- a/docs/local-build/mine-validate.md +++ b/docs/local-build/mine-validate.md @@ -89,7 +89,7 @@ Warning: Verify your local subtensor is running on port 9944. ━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━ 0 │ 5.04 β │ 5.04 β │ τ 0.00 │ 0.000000 │ 0.000000 │ 9.017303 β │ 5DFZTw │ 5Dc1Qu │ (*Owner controlled) 1 │ 0.00 β │ 1.00 β │ τ 0.00 │ 0.000000 │ 0.000000 │ 0.000000 β │ 5FErfA │ 5GxHV5 │ ~ - 2 │ 0.00 β │ 1.00 β │ τ 0.00 │ 0.000000 │ 0.000000 │ 0.000000 β │ 5Ft364 │ 5GuuKE │ ~ + 2 │ 0.00 β │ 1.00 β │ τ 0.00 │ 0.000000 │ 0.000000 │ 0.000000 β │ 5GRLEv │ 5EnNgi │ ~ ─────┼───────────┼───────────┼─────────┼───────────┼───────────┼───────────────┼────────┼─────────┼───────────────────── │ 5.04 β │ 5.04 β │ 0.00 β │ 0.000 │ │ 9.017303 β │ │ │ @@ -226,7 +226,7 @@ python validator.py \ This script begins the process of sending inputs to the miners and setting weights based on miner responses. :::info miner and validator logs -Use the `--logging.info` flag to print miner and validator log messages directly to the console. This helps you monitor activity in real time without checking log files. +Use the `--logging.info` flag to print miner and validator log messages directly to the console. This helps you monitor activity in real time. ::: ## 5. Check your emissions @@ -280,4 +280,58 @@ Note the increase in the miner neuron's `Incentive` column and the validator neu For more information on a subnet's emission distribution, see [Emissions](../emissions.md). -## Troubleshoot +## Troubleshooting errors + +This section discusses errors that could arise while running the validator or miner, and provides steps to diagnose and resolve them. + +**Insufficient funds** + +The coldkey signing the `btcli subnet register` transaction must have a sufficient $\tau$ balance to cover the recycling cost of the registration. + +
+Show sample error + +```console +Insufficient balance 0.0000 τ to register neuron. Current recycle is 0.0970 τ TAO. +``` + +
+ +**Unregistered miner or validator**: +This occurs when you attempt to run a miner or validator on a subnet where it is not registered. + +
+Show sample error + +```console +Your miner: Wallet (Name: 'test-miner', Hotkey: 'test-miner', Path: '~/.bittensor/wallets/') is not registered to chain connection: Network: local, Chain: ws://127.0.0.1:9944  +Run 'btcli register' and try again. +``` + +
+ +**`NeuronNoValidatorPermit`** + +This means that the neuron is attempting to set weights without a validator permit. Try fix this, you must stake sufficient TAO to the validator hotkey and wait till the end of the subnet's tempo. + +
+Show sample error + +```console +Failed set weights. Error: Subtensor returned `NeuronNoValidatorPermit(Module)` error. This means: `The caller is attempting to set non-self weights without being a permitted validator. | Please consult https://docs.bittensor.com/errors/subtensor#neuronnovalidatorpermit`. +``` + +
+ +**`WeightVecLengthIsLow`**: + +This error occurs when the validator attempts to set weights for fewer elements than allowed. It often happens when all neurons in the subnet are unresponsive, causing the validator to try setting zero weights for each of them. + +
+Show sample error + +```console +Error: Subtensor returned `WeightVecLengthIsLow(Module)` error. This means: `The dispatch is attempting to set weights on chain with fewer elements than are allowed. | Please consult https://docs.bittensor.com/errors/subtensor#weightveclengthislow`. +``` + +
From 1bd38a69156fe4a20b088f9b0f79cb17159f6a37 Mon Sep 17 00:00:00 2001 From: Dera Okeke Date: Tue, 12 Aug 2025 11:43:13 +0100 Subject: [PATCH 10/12] minor edit --- docs/local-build/mine-validate.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/local-build/mine-validate.md b/docs/local-build/mine-validate.md index 69ec9df45..7ad47ce1c 100644 --- a/docs/local-build/mine-validate.md +++ b/docs/local-build/mine-validate.md @@ -21,7 +21,7 @@ Before continuing with the rest of this tutorial, make sure you've completed the This guide uses Opentensor's [_subnet template_](https://github.com/opentensor/subnet-template/tree/main) repo. The repo provides a minimal implementation for building a custom subnet on the Bittensor network and includes the core logic for the miner and validator. -## 1. Register the hotkeys +## 1. Register the neuron hotkeys To participate in a subnet, you must first register a hotkey on it. This registration assigns the wallet a unique identifier (UID), which is required to interact with and receive emissions from the subnet. From ec610782be8e6e28cd70f79a4e15759c806e9cde Mon Sep 17 00:00:00 2001 From: Dera Okeke Date: Wed, 13 Aug 2025 15:54:53 +0100 Subject: [PATCH 11/12] typo fixes --- docs/learn/ema.md | 29 ++++++++++++++++------------- 1 file changed, 16 insertions(+), 13 deletions(-) diff --git a/docs/learn/ema.md b/docs/learn/ema.md index f9f453561..924d7538d 100644 --- a/docs/learn/ema.md +++ b/docs/learn/ema.md @@ -1,19 +1,19 @@ --- title: "Exponential Moving Averages (EMAs)in Bittensor" --- + # Exponential Moving Averages (EMAs) in Bittensor -The exponential moving average (EMA) is a [mathematical technique](https://en.wikipedia.org/wiki/Exponential_smoothing) for tracking a dynamic quantity, such as a token price, over time. Specifically, EMA is a weighted moving average that exponentially decreases the weight of older data point. This extracts a signal reflecting where the value has spent *most* of its time *most recently*, stabilizing or 'smoothing' the constant noise of rapid, largely random fluctuations. +The exponential moving average (EMA) is a [mathematical technique](https://en.wikipedia.org/wiki/Exponential_smoothing) for tracking a dynamic quantity, such as a token price, over time. Specifically, EMA is a weighted moving average that exponentially decreases the weight of older data point. This extracts a signal reflecting where the value has spent _most_ of its time _most recently_, stabilizing or 'smoothing' the constant noise of rapid, largely random fluctuations. Bittensor uses EMAs to smooth two critical dynamical values during the emission process: - Emissions to each subnet are determined by an EMA-smoothed representation of subnet price each tempo. This protects emissions from price volatility or intentional manipulation. -- Emissions to participants of each subnet are determined by EMAs of instantaneous validator-miner bond-strengths. This plays an important roll in ensuring that validators and miners are fairly rewarded for innovation, as measured by eventual consensus (rather than immediate consensus) about miner weights. +- Emissions to participants of each subnet are determined by EMAs of instantaneous validator-miner bond-strengths. This plays an important role in ensuring that validators and miners are fairly rewarded for innovation, as measured by eventual consensus (rather than immediate consensus) about miner weights. ## Mathematical definition - The EMA of a changing value at a given time is determined by weighted average of the current value and the EMA at the last time step. The parameter factor, or 'smoothing factor' is called $\alpha$. $$ @@ -30,14 +30,12 @@ The alpha parameter controls how quickly the EMA responds to changes: Note that this alpha parameter is distinct from and unrelated to the usage of 'alpha' to refer to subnet-specific currencies. ::: - - ## Subnet Price Emission Smoothing This use of EMA smoothing protects the network's economic model from price manipulation by making emissions extremely slow to respond to price changes. **How It Works**: -The price EMA uses a sophisticated dynamic alpha calculation to ensures that new subnets have even slower price adaptation than mature ones. +The price EMA uses a sophisticated dynamic alpha calculation to ensure that new subnets have even slower price adaptation than mature ones. $$ \alpha = \frac{ \mathrm{base\_alpha} \times \mathrm{blocks\_since\_start}}{\mathrm{blocks\_since\_start} + \mathrm{halving\_blocks}} @@ -48,6 +46,7 @@ The value for **base_alpha** in the above is currently ~0.0003 for Bittensor mai ::: See: + - [Yuma Consensus/Coinbase emission source code](https://github.com/opentensor/subtensor/blob/main/pallets/subtensor/src/epoch/run_epoch.rs#L223) - [Default alpha value for subnet price smoothing](https://github.com/opentensor/subtensor/blob/main/pallets/subtensor/src/lib.rs#L828) @@ -56,20 +55,24 @@ See: This smoothing function ensures that relationships between validators and miners evolve gradually, preventing sudden manipulation while rewarding validators who discover promising miners early. ### Basic Bond EMA (Liquid Alpha Disabled) + **Default Mode**: Single $\alpha$ for all validator-miner pairs + - **Default $\alpha$**: ~0.1 (10%) - **Response Time**: 7-22 blocks for significant changes (~1-4 minutes) - **Formula** - The EMA of the bond (BondEMA)of a validator i for a miner j, at time t, is the $\alpha$-weighted average of the instantaneous bond and the previous timestep's BondEMA: - $$ - BondEMA_{ij}^{(t)} = \alpha \times \, InstantBond_{ij} + (1-\alpha)\,BondEMA_{ij}^{(t-1)} - $$ + The EMA of the bond (BondEMA)of a validator i for a miner j, at time t, is the $\alpha$-weighted average of the instantaneous bond and the previous timestep's BondEMA: + $$ + BondEMA_{ij}^{(t)} = \alpha \times \, InstantBond_{ij} + (1-\alpha)\,BondEMA_{ij}^{(t-1)} + $$ ### Advanced Bond EMA (Liquid Alpha Enabled) + **Consensus-Based Mode**: Dynamic $\alpha$ per validator-miner pair based on consensus alignment -- **$\alpha$ Range**: Dynamic between $\alpha$_low and $\alpha$_high (default: 0.7 to 0.9) -- **Sigmoid Steepness**: Controls transition rate between $\alpha$_low and $\alpha$_high (default: 1000) + +- **$\alpha$ Range**: Dynamic between $\alpha$\_low and $\alpha$\_high (default: 0.7 to 0.9) +- **Sigmoid Steepness**: Controls transition rate between $\alpha$\_low and $\alpha$\_high (default: 1000) - **Individual Alpha**: Each validator-miner pair gets its own $\alpha$ value - **Response Time**: 1-13 blocks depending on consensus alignment (~12 seconds to 2.6 minutes) -See [Liquid Alpha/Consensus-Based Weights](../subnets/consensus-based-weights) \ No newline at end of file +See [Liquid Alpha/Consensus-Based Weights](../subnets/consensus-based-weights) From 8b6fc508142d689b4f7518f444529360af20e0a0 Mon Sep 17 00:00:00 2001 From: Dera Okeke Date: Wed, 13 Aug 2025 20:35:42 +0100 Subject: [PATCH 12/12] minor edits --- docs/local-build/mine-validate.md | 7 ++++--- docusaurus.config.js | 2 +- 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/local-build/mine-validate.md b/docs/local-build/mine-validate.md index 7ad47ce1c..1390c08bd 100644 --- a/docs/local-build/mine-validate.md +++ b/docs/local-build/mine-validate.md @@ -109,7 +109,7 @@ Subnet 2: New subnet ## 2. Acquire validator permit -To qualify as a validator on a subnet, a registered node must have a validator permit. This permit allows nodes to submit miner evaluations and set weights on a subnet. For more information, see [validator permits] +To qualify as a validator on a subnet, a registered node must have a validator permit. This permit allows nodes to submit miner evaluations and set weights on a subnet. For more information, see [validator permits](../validators/index.md#requirements-for-validation). To get validator permits on the demo subnet, you need to stake sufficient TAO to the validator hotkey. To do this, run the following command in the terminal: @@ -297,7 +297,8 @@ Insufficient balance 0.0000 τ to register neuron. Current recycle is 0.0970 τ -**Unregistered miner or validator**: +**Unregistered miner or validator** + This occurs when you attempt to run a miner or validator on a subnet where it is not registered.
@@ -323,7 +324,7 @@ Failed set weights. Error: Subtensor returned `NeuronNoValidatorPermit(Module)`
-**`WeightVecLengthIsLow`**: +**`WeightVecLengthIsLow`** This error occurs when the validator attempts to set weights for fewer elements than allowed. It often happens when all neurons in the subnet are unresponsive, causing the validator to try setting zero weights for each of them. diff --git a/docusaurus.config.js b/docusaurus.config.js index c08b6e4c0..dfc319b76 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -190,7 +190,7 @@ const config = { alt: "Bittensor", src: "img/logo.svg", srcDark: "img/logo-dark-mode.svg", - href: "https://learnbittensor.org", + href: "https://docs.learnbittensor.org", style: { objectFit: "contain", width: 21,