|
| 1 | +--- |
| 2 | +title: "UID Trimming" |
| 3 | +--- |
| 4 | + |
| 5 | +# UID Trimming |
| 6 | + |
| 7 | +UID trimming is a subnet management feature that allows subnet owners to reduce the number of neuron UIDs registered on their subnet, compressing the remaining UIDs to maintain consecutive indexing. UID trimming safely preserves high-performing and immune neurons, |
| 8 | + |
| 9 | +:::info UID trimming rate limit |
| 10 | +The chain's trim UID rate limit is 216,000 blocks (~30 days). Therefore, subnet owners can only make changes to their UID count every 30 days. |
| 11 | +::: |
| 12 | + |
| 13 | +- **Preserves Immune UIDs**: Both temporally immune UIDs and owner-owned UIDs are protected from trimming |
| 14 | +- **Emission-Based Selection**: UIDs are trimmed based on their emission scores, removing the lowest performers |
| 15 | +- **UID Compression**: After trimming, remaining UIDs are compressed to the left to maintain consecutive indexing |
| 16 | +- **Storage Migration**: All associated storage is properly migrated and cleaned up |
| 17 | +- **Configurable Limits**: Subnet owners can set minimum and maximum allowed UID counts |
| 18 | + |
| 19 | +:::info |
| 20 | + |
| 21 | +- The minimum UID count to which subnet owners can trim is currently 64. |
| 22 | +- The maximum number of immune UIDs must not exceed 80% of the maximum UID count. |
| 23 | + ::: |
| 24 | + |
| 25 | +## Emission-Based Selection |
| 26 | + |
| 27 | +UIDs are sorted by their emission scores in descending order. The trimming process: |
| 28 | + |
| 29 | +1. **Identifies Low Performers**: Starts from the lowest emitters and works upward |
| 30 | +2. **Skips Immune UIDs**: Bypasses any UIDs that are temporally or owner immune |
| 31 | +3. **Respects Limits**: Ensures the final count doesn't exceed the maximum allowed UIDs |
| 32 | + |
| 33 | +## For Subnet Owners |
| 34 | + |
| 35 | +Subnet trim UIDs using [`btcli sudo trim`](#uid-trimming-with-btcli) or the `sudo_trim_to_max_allowed_uids` extrinsic. |
| 36 | + |
| 37 | +**What happens:** |
| 38 | + |
| 39 | +- Owner-controlled UIDs are protected |
| 40 | +- Recently registered UIDs (within immunity period) are protected |
| 41 | +- UIDs with the lowest emission scores are removed first |
| 42 | +- Remaining UIDs are compressed to maintain consecutive indexing |
| 43 | +- All associated data (weights, bonds, etc.) is properly migrated |
| 44 | + |
| 45 | +## For Miners and Validators |
| 46 | + |
| 47 | +### Protection from Trimming |
| 48 | + |
| 49 | +You are protected from trimming if you have: |
| 50 | + |
| 51 | +1. **Temporal Immunity**: You registered recently (within the subnet's immunity period) |
| 52 | +2. **Owner Immunity**: Your UID is owned by the subnet owner (up to a configurable limit) |
| 53 | +3. **High Emissions**: Only low emissions neurons can be trimmed. |
| 54 | + |
| 55 | +### What Happens When Your UID Gets Trimmed |
| 56 | + |
| 57 | +When your UID is trimmed, all of your neuron data is **permanently deleted** from the blockchain, including: |
| 58 | + |
| 59 | +- UID-to-hotkey mapping |
| 60 | +- Block registration timestamp |
| 61 | +- Emission (incentive and dividends) history |
| 62 | +- All weights you set to other neurons (Validators only) |
| 63 | +- All bonds other neurons (Validators) had to you (Miners) |
| 64 | +- Axon information (IP, port, etc.) |
| 65 | +- Neuron certificates |
| 66 | +- Prometheus metrics |
| 67 | +- Last update timestamps |
| 68 | + |
| 69 | +**Your UID number will be reassigned** - the remaining UIDs are compressed to maintain consecutive numbering (e.g., if UIDs 5, 7, 9 remain after trimming, they become UIDs 0, 1, 2). |
| 70 | + |
| 71 | +### After Trimming |
| 72 | + |
| 73 | +If your UID was trimmed: |
| 74 | + |
| 75 | +- You must re-register to participate again |
| 76 | +- You will receive a new UID number |
| 77 | +- You start fresh with default scores |
| 78 | + |
| 79 | +### Source Code References |
| 80 | + |
| 81 | +- **Core Implementation**: `subtensor/pallets/subtensor/src/subnets/uids.rs` |
| 82 | + |
| 83 | +## UID trimming with BTCLI |
| 84 | + |
| 85 | +The `btcli sudo trim` command allows subnet owners to reduce the number of active UIDs on their subnet by trimming excess UIDs down to a specified maximum limit. |
| 86 | + |
| 87 | +:::warning Subnet Owner Only |
| 88 | +This is a **sudo operation** that can only be performed by the subnet owner (the wallet that created the subnet). |
| 89 | +::: |
| 90 | + |
| 91 | +### Basic usage |
| 92 | + |
| 93 | +```shell |
| 94 | +btcli sudo trim --netuid <NETUID> --max <MAX_UIDS> |
| 95 | +``` |
| 96 | + |
| 97 | +### Example |
| 98 | + |
| 99 | + |
| 100 | +To trim subnet 14 on a local chain to a maximum of 100 UIDs: |
| 101 | + |
| 102 | +```shell |
| 103 | +btcli sudo trim --netuid 14 --max 100 |
| 104 | +``` |
| 105 | +``` |
| 106 | +You are about to trim UIDs on SN3 to a limit of 100 [y/n] (n): y |
| 107 | +✅ Successfully trimmed UIDs on SN3 to 100 |
| 108 | +``` |
| 109 | + |
| 110 | +The command will: |
| 111 | + |
| 112 | +1. Verify that your wallet owns the specified subnet |
| 113 | +2. Display a confirmation prompt showing the trim operation details |
| 114 | +3. Execute the trim operation if confirmed |
| 115 | +4. Display the result of the operation |
| 116 | + |
| 117 | +:::note Transaction Fees |
| 118 | +UID trimming operations incur transaction fees for the underlying blockchain transactions they trigger. See [Transaction Fees in Bittensor](../learn/fees.md) for details. |
| 119 | +::: |
0 commit comments