Neuron Pruning
RegistrationPerformance-based removal of the weakest neuron when a new registration occurs on a full subnet.
Neuron Pruning Flow
Neuron Pruning
- New neuron registers on a full subnet (all UIDs occupied)
- Recycle register call for unused UIDs
Click items to navigate to their reference pages.
The Big Picture
Neuron pruning is natural selection for Bittensor. When a subnet is full and a new neuron wants in, the worst performer gets replaced. This ensures subnets maintain quality over time — neurons must continuously prove their value or risk being pruned.
Why This Matters
If you're running a miner, understanding pruning means understanding survival. Your incentive score must stay above the minimum or a new registration will take your UID. Immunity period is your grace period.
Example Scenario
Subnet 1 has 256 UIDs, all occupied. Miner M wants to register. The runtime scans pruning scores: UID 42 has the lowest score (0.001) and was registered 1000 blocks ago (immunity=200 blocks, so eligible). UID 42 is evicted, Miner M takes that slot.
Common Questions
- Does the pruned neuron lose their stake?
- No. Stake stays with the hotkey. Only the UID assignment is revoked. The pruned hotkey can re-register later.
- How long is the immunity period?
- It varies by subnet — typically 300-1000 blocks (1-3 hours). The subnet owner configures it via the ImmunityPeriod hyperparameter.
Use Cases
- Understanding miner survival requirements
- Monitoring pruning risk for your UIDs
- Planning registration timing
- Building miner health monitoring tools
When all UID slots on a subnet are occupied and a new registration occurs, the runtime must evict one existing neuron. The neuron with the lowest pruning score is selected, provided it has passed the immunity period (new neurons are protected from immediate pruning).
The pruning score is derived from the neuron's emission amount — essentially how much value the network assigns to it. Neurons that consistently receive zero emission are candidates for pruning. A min_non_immune_uids safety floor ensures at least that many non-immune neurons exist before pruning from them; if no non-immune candidates are available, the algorithm falls back to pruning immune UIDs.
Triggers
- New neuron registers on a full subnet (all UIDs occupied)
- Recycle register call for unused UIDs
Inputs (4)
| Item | Type | Role |
|---|---|---|
| Emission SubtensorModule | storage | Per-UID emission amounts used as pruning score |
| ImmunityPeriod SubtensorModule | storage | Blocks after registration before pruning eligible |
| MaxAllowedUids SubtensorModule | storage | Maximum neuron slots per subnet |
| BlockAtRegistration SubtensorModule | storage | Registration block per UID for immunity check |
Outputs (3)
| Item | Type | Role |
|---|---|---|
| NeuronRegistered SubtensorModule | event | Emitted for the new neuron taking the pruned UID |
| Keys SubtensorModule | storage | Updated UID → hotkey mapping after replacement |
| Uids SubtensorModule | storage | Updated hotkey → UID mapping |
Source Files
pallets/subtensor/src/subnets/registration.rs Formulas
Min-Score Selection
The neuron with the lowest pruning score that has passed the immunity period is selected for eviction.
candidates = UIDs where (block - registration_block) >= immunity_period AND hotkey is not an immortal owner hotkey AND len(non_immune) >= min_non_immune_uids (safety floor) pruned_uid = argmin(emission[candidates]) // Tie-break: lowest emission → oldest registration → lowest UID // Safety floor: min_non_immune_uids ensures a minimum pool of non-immune neurons // Falls back to pruning immune UIDs if no non-immune candidates available