Docs edits

docs/emissions.md

@@ -18,32 +18,40 @@ See the [Dynamic TAO White Paper](https://drive.google.com/file/d/1vkuxOFPJyUyoY
 
 ### Injection
 
-The first stage of emissions is *injection of liquidity* into the subnet pools. Liquidity is injected to each subnet in proportion to the price of its token compared to the price of other subnet tokens. This is designed to incentivize development on the most valuable subnets.
+The first stage of emissions is _injection of liquidity_ into the subnet pools. Liquidity is injected to each subnet in proportion to the price of its token compared to the price of other subnet tokens. This is designed to incentivize development on the most valuable subnets.
 
 Each block:
 
 - TAO is injected into the subnet's **TAO reserve**.
 - Alpha is injected into the subnet's **alpha reserve**.
-- Alpha is allocated to *alpha outstanding*, to be extracted by participants.
+- Alpha is allocated to _alpha outstanding_, to be extracted by participants.
 
 #### TAO reserve injection
 
 A subnet's TAO reserve injection is computed in proportion to the price of its alpha token over the sum of prices for all the subnets in Bittensor.
 
-Given set $\mathbb{S}$ of all subnets, and a total per block TAO emission $\Delta\bar{\tau}$, which begins at 1 TAO and follows a halving schedule, TAO emission $\Delta\tau_i$ to subnet $i$ with price $p_i$ is:
+<details>
+  <summary><strong>See how it's calculated!</strong></summary>
 
-$$
-\Delta\tau_i = \Delta\bar{\tau} \times
-\frac
-  {p_i}
-  {\sum_{j \in \mathbb{S}}
-\bigl(p_j)}
-$$
+    Given set $\mathbb{S}$ of all subnets, and a total per block TAO emission $\Delta\bar{\tau}$, which begins at 1 TAO and follows a halving schedule, TAO emission $\Delta\tau_i$ to subnet $i$ with price $p_i$ is:
+
+    $$
+    \Delta\tau_i = \Delta\bar{\tau} \times
+    \frac
+      {p_i}
+      {\sum_{j \in \mathbb{S}}
+    \bigl(p_j)}
+    $$
+
+</details>
 
 #### Alpha reserve injection
 
 Alpha is then injected in proportion to the price of the token, so that growth of a subnet's liquidity pools does not not change the price of the alpha token.
 
+<details>
+  <summary><strong>See how it's calculated!</strong></summary>
+
 Recall that token price for a subnet is its TAO in reserve divided by its alpha reserve:
 
 $$
@@ -63,15 +71,14 @@ $$
 When we fill in this equation with the previous formula for $\Delta\tau_i$, the price $p_i$ is cancelled out of the equation, yielding:
 
 $$
-\Delta\alpha_i = 
+\Delta\alpha_i =
   \frac
     {\Delta\bar{\tau}}
     {\sum_{j \in \mathbb{S}}
   \bigl(p_j)}
 $$
 
-
-However, alpha injection is also capped at 1 by the algorithm, to prevent runaway inflation. Therefore, with cap or *alpha emission rate* $\Delta\bar{\alpha_i}$, emission $\Delta\alpha_i$ to subnet $i$ is:
+However, alpha injection is also capped at 1 by the algorithm, to prevent runaway inflation. Therefore, with cap or _alpha emission rate_ $\Delta\bar{\alpha_i}$, emission $\Delta\alpha_i$ to subnet $i$ is:
 
 $$
 \Delta\alpha_i = \min\left\{
@@ -80,14 +87,15 @@ $$
     {\sum_{j \in \mathbb{S}}
   \bigl(p_j)},
   \Delta\bar{\alpha_i} \right\}
-
 $$
 
-The cap or *alpha emission rate* $\Delta\bar{\alpha_i}$ for subnet $i$, starts at 1 and follows a halving schedule identical to that of TAO, beginning when subnet $i$ is created.
+The cap or _alpha emission rate_ $\Delta\bar{\alpha_i}$ for subnet $i$, starts at 1 and follows a halving schedule identical to that of TAO, beginning when subnet $i$ is created.
+
+</details>
 
 #### Alpha outstanding injection
 
-Each block, liquidity is also set aside to be emitted to participants (validators, miners, stakers, and subnet creator). The quantity per block is equal to the *alpha emission rate* $\Delta\bar{\alpha_i}$ for subnet $i$.
+Each block, liquidity is also set aside to be emitted to participants (validators, miners, stakers, and subnet creator). The quantity per block is equal to the _alpha emission rate_ $\Delta\bar{\alpha_i}$ for subnet $i$.
 
 ### Extraction
 
@@ -96,38 +104,39 @@ At the end of each tempo (360 blocks), the quantity of alpha accumulated over ea
 1. 18% by subnet owner
 1. 41% of emissions go to miners. The allocation to particular miners is determined by [Yuma Consensus: Miner emissions#miner-emissions](./yuma-consensus).
 1. 41% by validators and their stakers.
-    1. First, the allocation to validators miners is determined by [Yuma Consensus: Validator Emissions](./yuma-consensus#validator-emissions).
-    1. Then, validators extract their take from that allocation.
-    1. Then, TAO and alpha are emitted to stakers in proportion to the validators' holdings in each token. TAO emissions are sourced by swapping a portion of alpha emissions to TAO through the subnet's liquidity pool.
 
-        For validator x's TAO stake $\tau_x$, and alpha stake $\alpha_x$, and the global TAO weight $w_{\tau}$:
+   1. First, the allocation to validators miners is determined by [Yuma Consensus: Validator Emissions](./yuma-consensus#validator-emissions).
+   1. Then, validators extract their take from that allocation.
+   1. Then, TAO and alpha are emitted to stakers in proportion to the validators' holdings in each token. TAO emissions are sourced by swapping a portion of alpha emissions to TAO through the subnet's liquidity pool.
+
+      For validator x's TAO stake $\tau_x$, and alpha stake $\alpha_x$, and the global TAO weight $w_{\tau}$:
 
-        - TAO is emitted to stakers on the root subnet (i.e. stakers in TAO) in proportion to the validator's stake weight's proportion of TAO.
+      - TAO is emitted to stakers on the root subnet (i.e. stakers in TAO) in proportion to the validator's stake weight's proportion of TAO.
 
-          $$
-          \text{proportional emissions (\%) to root stakers} 
-          = \frac{\tau_{x}{} \, w_{\tau}}
-                 {\alpha_{x} + \tau_{x} \, w_{\tau}}
-          $$
+        $$
+        \text{proportional emissions (\%) to root stakers}
+        = \frac{\tau_{x}{} \, w_{\tau}}
+               {\alpha_{x} + \tau_{x} \, w_{\tau}}
+        $$
 
-        - Alpha is emitted to stakers on the mining subnet (i.e. stakers in alpha) in proportion to the validator's stake weight's proportion of alpha:
-          $$
-          \text{proportional emissions (\%) to alpha stakers} 
-          = \frac{\alpha_{x}}
-                 {\alpha_{x} + \tau_{x} \, w_{\tau}}
-          $$        
+      - Alpha is emitted to stakers on the mining subnet (i.e. stakers in alpha) in proportion to the validator's stake weight's proportion of alpha:
+        $$
+        \text{proportional emissions (\%) to alpha stakers}
+        = \frac{\alpha_{x}}
+               {\alpha_{x} + \tau_{x} \, w_{\tau}}
+        $$
 
-        Validators who hold both root TAO and subnet alphas will extract both types of token.
+      Validators who hold both root TAO and subnet alphas will extract both types of token.
 
-    See [Core Dynamic TAO Concepts: Validator stake weight](../subnets/understanding-subnets#validator-stake-weight)
+   See [Core Dynamic TAO Concepts: Validator stake weight](../subnets/understanding-subnets#validator-stake-weight)
 
 ### Note on evolution of Bittensor token economy
 
 When Dynamic TAO is initiated, there will be no alpha in circulation, so validator's stake weights will be entirely determined by their share of TAO stake.
 
 But far more alpha than TAO is emitted into circulation every block. As a result, over time there will be more alpha relative to TAO in overall circulation, and the relative weight of a validator in a given subnet will depend more on their alpha stake share relative to their share of the TAO stake on Subnet Zero.
 
-In order to hasten the process of alpha gaining the majority of stake power in the network, the contribution of TAO stake to validator stake weight is reduced by a global parameter called *TAO weight*. Currently, this is planned to be **18%**, in order to achieve a weight parity between TAO and total alpha in approximately 100 days.
+In order to hasten the process of alpha gaining the majority of stake power in the network, the contribution of TAO stake to a validator's stake weight is reduced by a global parameter called _TAO weight_. Currently, this is planned to be **18%**, in order to achieve a weight parity between TAO and total alpha in approximately 100 days.
 
 <center>
 <ThemedImage
@@ -140,4 +149,4 @@ style={{width: 650}}
 />
 </center>
 
-<br />
+<br />

docs/miners/index.md

@@ -9,14 +9,14 @@ import useBaseUrl from '@docusaurus/useBaseUrl';
 
 ## Choosing a subnet
 
-All mining in Bittensor occurs within a subnet. Each subnet independently produces the digital commodities that are its purpose, each subnet creator defining a different _incentive mechanism_ for validators to use in judging miners' work. It is validators scores of miners' performance, according to this incentive mechanism, that determines the proportion of the subnet's emissions allocated to each miner. See [Emissions](../emissions.md).
+All mining in Bittensor occurs within a subnet. Each subnet independently produces the digital commodities that are its purpose. Each subnet creator defines a different _incentive mechanism_ for validators to use in judging miners' work. Its validators score miners' performances according to the subnet's incentive mechanism. These scores determine the proportion of the subnet's emissions allocated to each miner. See [Emissions](../emissions.md).
 
-Mining in Bittensor is not like mining Bitcoin or many other blockchains, it is active, creative, and competitive. Preparing to be a subnet miner involves researching the right subnet(s) for _you_ to mine, given your own expertise and access to hardware.
+Mining in Bittensor differs significantly from mining Bitcoin or other blockchains. It is active, creative, and competitive. Preparing to be a subnet miner involves researching the right subnet(s) for _you_ to mine, given your own expertise and access to hardware.
 
 Browse the subnets and explore links to their code repositories on [TAO.app' subnets listings](https://tao.app).
 
 :::tip Typical compute requirements
-Each subnet may have distinct hardware requirements, but this [minimum requirements template for subnet creators](https://github.com/opentensor/bittensor-subnet-template/blob/main/min_compute.yml) may give an idea of minimum memory, bandwidth and storage requirements for a typical subnet node.
+Each subnet may have distinct hardware requirements, but this [subnet minimum requirements template](https://github.com/opentensor/bittensor-subnet-template/blob/main/min_compute.yml#L14) may give an idea of the minimum memory, bandwidth and storage requirements for miners in a typical subnet node.
 
 Mining is not supported on Windows.
 :::
@@ -26,10 +26,10 @@ Mining is not supported on Windows.
 To participate as a miner, you must first register a hotkey with the subnet in order to receive a UID on that subnet.
 
 :::tip No need to create a subnet to mine
-You **do not** have to create a subnet to mine on the Bittensor network. Most miners work on established subnets.
+You **do not** have to create a subnet to mine on the Bittensor network. Most miners work on already established subnets.
 :::
 
-Registration has a cost in TAO, which fluctuates dynamically based on time since last registration. When you secure a UID slot in a subnet on the main chain, this TAO is sunk cost.
+Registration has a cost in TAO, which fluctuates dynamically based on the time since the last registration. When you secure a UID slot in a subnet on the main chain, this TAO is sunk cost and cannot be recovered.
 
 A subnet can have a maximum of 64 subnet validator UIDs and 192 subnet miner UIDs (256 total) in subnets other than Subnet 1.
 
@@ -41,22 +41,30 @@ When you delegate your TAO to a subnet validator, you attach your delegated TAO
 A hotkey can hold multiple UIDs across **separate** subnets. However, within one subnet, each UID must have a unique hotkey.
 :::
 
-Run the following command on your terminal, replacing `<your_preferred_netuid>`, `<my_coldkey>`, `<my_hotkey>`.
+To register your keys with a subnet, run the following command on your terminal, replacing `<your_preferred_netuid>`, `<my_coldkey>`, `<my_hotkey>`.
 `<your_preferred_netuid>` is the `netuid` of your preferred subnet.
 
 ```bash
 btcli subnet register --netuid <your_preferred_netuid>  --wallet.name  <my_coldkey> --wallet.hotkey <my_hotkey>
 ```
 
-For example, for subnet 1 (netuid of 1):
+For example, to register your keys with subnet 1—netuid of 1:
 
 ```bash
 btcli subnet register --netuid 1 --wallet.name test-coldkey --wallet.hotkey test-hotkey
 ```
 
 ## Miner deregistration
 
-Miners as well as validators can be deregistered if their emissions are low.
+A miner can be deregistered if it earns low emissions due to receiving low weights (ratings) from validators. Typical subnets have 256 UID slots per subnet, of which a maximum of 64 subnet can be occupied by validators. Each tempo, the lowest ranked slot is deregistered from the hotkey that holds it and assigned to a new registrant.
+
+- Every subnet has an `immunity_period` hyperparameter expressed in a number of blocks.
+  :::tip See
+  See [`immunity_period`](../subnets/subnet-hyperparameters.md#immunityperiod).
+  :::
+- A subnet miner or validator at a UID (in that subnet) has a defined number of blocks to improve its performance. This is known as `immunity_period`. When the `immunity_period` expires, that miner or validator can be deregistered if it has the lowest performance in the subnet and a new registration arrives.
+- A neuron's `immunity_period` starts when the miner or validator is registered into the subnet.
+Validators as well as miners can be deregistered if their emissions are low; either role requires a UID.
 
 Typically, subnets have 256 UID slots, with a maximum of 64 slots capable of serving as validators by default. This leaves 192 UIDs for miners, though if there are fewer than 64 eligible validators on a subnet, miners can occupy available slots.
 
@@ -132,7 +140,7 @@ btcli wallet overview --netuid
 
 After providing your wallet name when prompted, you will see output such as:
 
-| Parameter   | Value              | Description                                                                 |
+| 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.                           |

docs/subnets/create-a-subnet.md

@@ -127,4 +127,4 @@ Use the below command to start the subnet once `check-start` returns `Emission s
 
 ```bash
 btcli subnet start --netuid x
-```
+```