latent-to · MichaelTrestman · Dec 10, 2025 · Dec 5, 2025 · Dec 5, 2025 · Dec 8, 2025
diff --git a/docs/concepts/halving.md b/docs/concepts/halving.md
@@ -1,3 +1,7 @@
+---
+title: "TAO Halving"
+---
+
 # TAO Halving
 
 This page explains the TAO halving mechanism and describes how it affects the creation and distribution of new tokens across the network.
@@ -6,6 +10,9 @@ This page explains the TAO halving mechanism and describes how it affects the cr
 
 **TAO halving** is a scheduled event in the Bittensor network where the block reward is reduced by 50%. This happens automatically at regular intervals based on the amount of TAO in circulation.
 
+Follow the approach of the halving at TAO.app's tokenomics dashboard: [tao.app/tokenomics](https://www.tao.app/tokenomics)
+
+
 :::info
 _Recycling_ of TAO from subnet registration fees can delay halving events. When tokens are recycled, they are returned to the emission pool and removed from circulation. This process continuously extends the time until the next halving threshold is reached.
 :::

diff --git a/docs/concepts/mev-shield/index.md b/docs/concepts/mev-shield/index.md
@@ -0,0 +1,90 @@
+---
+title: "MEV Shield: Encrypted Mempool Protection"
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+# MEV Shield: Encrypted Mempool Protection
+
+MEV Shield is a Bittensor security feature that protects transactions from maximal extractable value (MEV) attacks by keeping details hidden until they are on-chain. It (optionally) encrypts any Bittensor transaction until after block inclusion, preventing other users from profiting from any foreknowldge of your transaction details.
+
+See also: [MEV Shield Bittensor Python SDK Guide](/sdk/mev-protection).
+
+
+## How MEV Shield Works
+
+When you submit a transaction, it first enters the [_mempool_](../../resources/glossary.md#mempool), where it becomes visible to all network participants. This transparency allows for a variety of exploits where one user can profit from other user's predictable actions in a way that is considered parasitic or unfair.
+
+This is the _Maximal Extractable Value_ (_MEV_) problem.
+
+With MEV shield, transaction data is encrypted with a public key provided by the blockchain validator. The blockchain validator decrypts it right before finalizing the transaction, so the transaction details are inaccessible to would-be-MEV-attackers.
+
+## Basic Usage
+
+Both of Bittensor's official clients, the command line interface `BTCLI` and the Python SDK, enable MEV shield by default for sensitive operations. Under the hood, MEV-Shielded transactions are submitted by these clients (or directly by users) to the blockchain through the `mevShield::submit_encrypted()` extrinsic. 
+
+:::warning MEV shield with hotkey-signed extrinsics
+MEV shield should not be used for transactions that are signed by a hotkey. Attempting to use MEV shield with extrinsics signed by a hotkey will fail.
+
+Note that while it is technically possible to transfer TAO to a hotkey, which would, technically, allow you to use MEV protection for HK operations, this is neither intended nor advisable.
+
+**Because hotkeys are not intended to hold TAO, you are in *untested waters* if you do so, and there may be unintended consequences that could result in asset loss.**
+:::
+
+
+<Tabs groupId="mev-shield">
+
+  <TabItem value="btcli" label="BTCLI">
+
+BTCLI automatically applies MEV Shield to commands that are more prone to MEV attacks, such as staking, subnet creation, and proxy execution, while all other commands run without it.
+
+For these sensitive operations, MEV protection is enabled by default, but you can turn it off by adding the `--no-mev-protection` flag as shown:
+
+```bash
+# Add stake with MEV protection (default)
+btcli stake add \
+  --wallet.name my_wallet \
+  --wallet.hotkey my_hotkey \
+  --amount 10.0 \
+  --mev-protection # redundant, since this is the default behavior!
+
+# Remove stake without MEV protection
+btcli stake remove \
+  --wallet.name my_wallet \
+  --wallet.hotkey my_hotkey \
+  --amount 5.0 \
+  --no-mev-protection # Danger, you are giving your TAO to bots!
+
+```
+
+  </TabItem>
+
+  <TabItem value="sdk" label="Bittensor SDK">
+  When using the SDK, MEV Shield can be applied to any Bittensor extrinsic function using the `mev_protection` parameter. To do this:
+
+```python
+from bittensor import Subtensor, Wallet
+from bittensor.utils.balance import Balance
+
+# Initialize subtensor and wallet
+subtensor = Subtensor()
+wallet = Wallet()
+
+# Add stake with MEV protection enabled
+response = subtensor.add_stake(
+  wallet=wallet,
+  netuid=1,
+  hotkey_ss58='5C86aJ2uQawR6P6veaJQXNK9HaWh6NMbUhTiLs65kq4ZW3NH',
+  amount=Balance.from_tao(1),
+  mev_protection=True,  # Enable MEV Shield protection
+  wait_for_inclusion=True,
+  wait_for_finalization=True
+)
+
+print(response)
+```
+
+  </TabItem>
+
+</Tabs>
diff --git a/docs/keys/schedule-coldkey-swap.md b/docs/keys/schedule-coldkey-swap.md
@@ -28,8 +28,8 @@ The schedule coldkey swap feature works as follows:
 
 - The schedule coldkey swap feature enables you to schedule the swapping of source coldkey to a destination coldkey. If you feel your existing coldkey is potentially compromised, then use this feature to schedule a swap to a destination coldkey.
 - When you use this feature, it will not immediately swap your coldkeys and swap your TAO funds from the source coldkey to the destination coldkey. It will only schedule the swap event.
-- All scheduled coldkey swaps will be executed on-chain. **Your scheduled coldkey swap will execute on the mainnet approximately 5 days after you successfully scheduled the coldkey swap using the method described in this document.**
-- The source coldkey you used in this method will be locked when you schedule the swap. After the 5-day period has elapsed your original coldkey will be unlocked entirely.
+- All scheduled coldkey swaps will be executed on-chain. **Your scheduled coldkey swap will execute on the mainnet 36000 blocks (approximately 5 days) after you successfully scheduled the coldkey swap using the method described in this document.**
+- The source coldkey you used in this method will be locked when you schedule the swap. After the 36000-block period is elapsed your original coldkey will be unlocked entirely.
 - **Cost**: The cost of this coldkey swap transaction is 0.1 TAO. This must be available in your source coldkey.
 - Any subnet ownership from your source coldkey will move to the destination coldkey.
 - The delegated stake will be transferred from your source coldkey to the destination coldkey.
@@ -114,4 +114,4 @@ Scroll down to the bottom of the page and click on the **Submit Transaction** bu
 
 ## Verify
 
-Your scheduled coldkey swap will execute on the mainnet approximately 5 days after you successfully scheduled the coldkey swap using the above method. Check your destination coldkey after this period to verify.
+Your scheduled coldkey swap will execute on the mainnet 36000 blocks after you successfully scheduled the coldkey swap using the above method. Check your destination coldkey after approximately 5 days to verify.
diff --git a/docs/resources/glossary.md b/docs/resources/glossary.md
@@ -307,6 +307,7 @@ Unlike Bitcoin which halves based on block numbers, Bittensor implements halving
 The actual date of each halving is not fixed—it changes based on the amount of TAO being recycled each day.
 
 **See also:**
+
 - [TAO.app Halvings Tracker](https://tao.app/halvings)
 - [Emission](../learn/emissions.md)
 
@@ -386,6 +387,10 @@ The primary Bittensor blockchain network, used for production purposes and conne
 
 **See also:** [Bittensor Networks](../concepts/bittensor-networks.md), [Subtensor Nodes](../subtensor-nodes/)
 
+### Mempool
+
+The _mempool_ is a temporary holding area in blockchain networks where pending and unconfirmed transactions sit before being included in a block. When you submit a transaction, it first enters the mempool, where it becomes visible to all network participants.
+
 ### Metagraph
 
 A data structure that contains comprehensive information about the current state of a subnet, including detailed information on all the nodes (neurons) such as subnet validator stakes and subnet weights in the subnet. Metagraph aids in calculating emissions.
@@ -869,13 +874,15 @@ A position occupied by a subnet miner or subnet validator within a subnet, ident
 The process of withdrawing staked TAO from a validator hotkey, converting subnet-specific alpha tokens back to TAO through the subnet's automated market maker (AMM). Unstaking operations are subject to slippage—the transaction impacts pool prices, with larger amounts experiencing more slippage. Bittensor provides price protection mechanisms including tolerance limits and partial execution options to guard against unfavorable exchange rates.
 
 When you unstake:
+
 1. Alpha tokens are removed from the validator's hotkey and added to the subnet's alpha reserves
 2. The AMM calculates equivalent TAO using the current exchange rate
 3. TAO is removed from the subnet's TAO reserves and transferred to your coldkey
 
 Unstaking incurs blockchain transaction fees, which are recycled back into the TAO emission pool.
 
-**See also:** 
+**See also:**
+
 - [Staking/Delegation overview](../staking-and-delegation/delegation.md#unstaking)
 - [Managing Stake with btcli](../staking-and-delegation/managing-stake-btcli.md#unstaking-with-btcli)
 - [Managing Stake with SDK](../staking-and-delegation/managing-stake-sdk.md#unstaking-with-the-sdk)

diff --git a/docs/sdk/index.md b/docs/sdk/index.md
@@ -32,7 +32,7 @@ Manage your TAO stake across validators and subnets.
 
 - [Managing Stake (SDK)](../staking-and-delegation/managing-stake-sdk.md): Complete staking guide covering:
   - How to stake with the SDK
-  - How to unstake with the SDK  
+  - How to unstake with the SDK
   - How to move stake between validators
   - How to transfer stake
 - [Managing Root Claims](../staking-and-delegation/root-claims/managing-root-claims.md): Claim root network positions
@@ -47,14 +47,15 @@ Use proxies to delegate account permissions securely while keeping your coldkey
 - [Staking with a Proxy](../keys/proxies/staking-with-proxy.md): Perform staking operations through a proxy
 
 **By proxy type:**
+
 - **Proxy staking**: See [Staking with a Proxy](../keys/proxies/staking-with-proxy.md)
 - **Other proxy operations**: Execute any permitted call through a proxy (see [Working with Proxies](../keys/proxies/working-with-proxies.md))
 
 ## Advanced: Working with Blockchain Calls
 
 Compose and execute complex blockchain transactions using `GenericCall` and pallet-specific builders.
 
-- [Working with Blockchain Calls](../sdk/call): Create, compose, and execute calls with `GenericCall` and `CallBuilder` - essential for proxies, crowdloans, MEV protection, and fee estimation
+- [Working with Blockchain Calls](./call.md): Create, compose, and execute calls with `GenericCall` and `CallBuilder` - essential for proxies, crowdloans, MEV protection, and fee estimation
 
 ## Subnet Operations
 

diff --git a/docs/sdk/mev-protection.md b/docs/sdk/mev-protection.md
@@ -1,13 +1,16 @@
 ---
-title: "MEV Shield"
+title: "Using MEV Shield with the Bittensor SDK"
 ---
 
-import { SdkVersion } from "./_sdk-version.mdx";
+import { SdkVersion } from "./\_sdk-version.mdx";
 
 # MEV Shield
 
 The MEV Shield feature allows users to encrypt transactions to protect them from front running and other maximal extractable value (MEV) attacks that depend on attackers knowing the details of transactions when they enter the transaction pool.
 
+This page gives in-depth coverage of using MEV shield with the Bittensor Python SDK.
+For more overall context on MEV Shield, see:  [MEV Shield: Encrypted Mempool Protection](/concepts/mev-shield/).
+
 
 MEV Shield uses a simple encrypt-and-submit approach:
 
@@ -23,6 +26,14 @@ The SDK supports MEV Shield in two primary ways:
 1. MEV protection parameter - Add `mev_protection=True` to any supported extrinsic (recommended)
 2. Direct MEV Shield submission - Use `mev_submit_encrypted` for full control over encrypted transaction submission
 
+:::warning MEV shield with hotkey-signed extrinsics
+MEV shield should not be used for transactions that are signed by a hotkey. Attempting to use MEV shield with extrinsics signed by a hotkey will fail.
+
+Note that while it is technically possible to transfer TAO to a hotkey, which would, technically, allow you to use MEV protection for HK operations, this is neither intended nor advisable.
+
+**Because hotkeys are not intended to hold TAO, you are in *untested waters* if you do so, and there may be unintended consequences that could result in asset loss.**
+:::
+
 ### Core MEV Shield Methods
 
 These SDK methods encapsulate the core MEV shield functionality:
@@ -44,8 +55,9 @@ The `ExtrinsicResponse` object includes a `mev_extrinsic_receipt` field to store
 ### Extrinsic Functions
 
 In `Subtensor` and `AsyncSubtensor`, all methods that call extrinsics now accept the following keyword arguments:
-  - `mev_protection: bool = DEFAULT_MEV_PROTECTION` as a keyword-only argument
-  - `wait_for_revealed_execution: bool = True` as a keyword-only argument
+
+- `mev_protection: bool = DEFAULT_MEV_PROTECTION` as a keyword-only argument
+- `wait_for_revealed_execution: bool = True` as a keyword-only argument
 
 
 All extrinsic functions now support MEV protection:
@@ -65,14 +77,14 @@ All extrinsic functions now support MEV protection:
     - Transfer: `transfer_extrinsic`
     - Start Call: `start_call_extrinsic`
 
-
 ## Usage
 
 ### Option 1: MEV Protection via Extrinsic Parameter (Recommended)
 
 All extrinsics now support a `mev_protection` parameter (default: `False`). When set to `True`, the extrinsic is automatically encrypted and submitted through the MEV Shield pallet. This is the simplest way to use MEV protection—the SDK handles all the details including nonce management.
 
 When `mev_protection=True`:
+
 - The transaction is encrypted using ML-KEM-768 + XChaCha20Poly1305
 - The transaction remains encrypted in the mempool until validators decrypt and execute it
 - The `ExtrinsicResponse` will contain `mev_extrinsic_receipt` with the revealed execution details (if `wait_for_revealed_execution=True`, which is the default for extrinsics using MEV protection)
@@ -102,6 +114,7 @@ response = subtensor.add_stake(
 
 print(response)
 ```
+
 ```console
 ExtrinsicResponse:
     success: True
@@ -122,7 +135,6 @@ ExtrinsicResponse:
 
 For full control over the encryption and submission process, you can use the `mev_submit_encrypted` method on the `Subtensor` instance or call the `submit_encrypted_extrinsic` function directly.
 
-
 See [Working with Blockchain Calls](./call).
 
 ### Nonce management
@@ -141,7 +153,6 @@ This is because the submit call will be executed first (consuming nonce `X`), an
 
 **Alternative approach**: Use a different account as the submitter. This eliminates nonce coordination entirely—the inner call signer and the submit call signer have independent nonce sequences.
 
-
 #### Key Parameters
 
 - `signer_keypair` (optional): The keypair used to sign the inner call. This parameter is only available when calling `submit_encrypted_extrinsic` directly. If not provided, the wallet's coldkey is used as the default signer.
@@ -189,4 +200,4 @@ response = subtensor.mev_submit_encrypted(
 )
 
 print(response)
-```
+```
diff --git a/docs/staking-and-delegation/root-claims/managing-root-claims.md b/docs/staking-and-delegation/root-claims/managing-root-claims.md
@@ -22,8 +22,10 @@ Your claim type determines what happens to your root dividends when they're clai
 
 **Claim Types:**
 
-- **Swap**: Future Root Alpha Emissions are swapped to TAO and added to root stake (default)
-- **Keep**: Future Root Alpha Emissions are kept as Alpha tokens
+- **Swap** (default): Future Root Alpha Emissions are swapped to TAO and added to root stake.
+- **Keep**: Future Root Alpha Emissions are kept as Alpha tokens.
+- **KeepSubnets**: Keep Alpha for specific subnets only; all other subnets are swapped to TAO. This gives you fine-grained control over which subnet tokens you want to hold. Note that this is a new feature and not yet supported by BTCLI and the SDK (coming soon).
+
 
 <Tabs groupId="root-claim">
   <TabItem value="btcli" label="BTCLI">
@@ -123,14 +125,14 @@ asyncio.run(main())
 2. Select your coldkey account
 3. Choose the pallet: `subtensorModule` and choose the `setRootClaimType(newRootClaimType)` extrinsic.
 4. Select your desired claim type:
-   - `Swap` - for TAO accumulation
-   - `Keep` - for alpha retention
+   - `Swap` - convert all Alpha to TAO (default)
+   - `Keep` - retain all Alpha tokens
+   - `KeepSubnets` - keep Alpha for specific subnets only (requires specifying subnet IDs)
 5. Click **Submit Transaction** and sign.
 
   </TabItem>
 </Tabs>
 
----
 
 ## Monitor claim status and types
 

diff --git a/sidebars.js b/sidebars.js
@@ -204,7 +204,7 @@ const sidebars = {
     },
     {
       type: "category",
-      label: "Bittensor Python SDK",      
+      label: "Bittensor Python SDK",
       collapsible: true,
       collapsed: true,
       items: [
@@ -213,6 +213,7 @@ const sidebars = {
         "sdk/env-vars",
         "sdk/bt-api-ref",
         "sdk/subtensor-api",
+                         "sdk/mev-protection",
         "getting-started/install-wallet-sdk",
         "sdk/call",
         "sdk/migration-guide",
@@ -230,7 +231,7 @@ const sidebars = {
       items: [
         "concepts/bittensor-networks",
         "concepts/halving",
-        "sdk/mev-protection",
+        "concepts/mev-shield/index",
         "concepts/commit-reveal",
         "concepts/consensus-based-weights",
         "concepts/bt-logging-levels",