Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 2 additions & 6 deletions docs/btcli/btcli-permissions.md
Original file line number Diff line number Diff line change
Expand Up @@ -80,7 +80,7 @@ Some operations require a TAO balance or alpha stake balance to execute.

- Transfers of TAO fail if you lack the specified amount
- Staking and unstaking operations fail if they specify more than the owner has
- Registering a hotkey on a subnet to mine or validate has a fee that can be paid with TAO or proof-of-work.
- Registering a hotkey on a subnet to mine or validate requires paying the **current neuron registration burn** in TAO. The extrinsics `register` and `burned_register` share the same burn-based path for non-root subnets.
- Creating a subnet requires a fee, which is computed dynamically. The price to create a subnet doubles when someone creates a subnet, and then gradually decreases. This system is designed as a kind of distributed auction, where price is determined by what people are willing to pay given the uncertain estimation of what others are willing to pay.

### Validator Permit
Expand Down Expand Up @@ -270,7 +270,7 @@ See: [Coldkey and Hotkey Workstation Security](../keys/coldkey-hotkey-security)
#### Write commands (require coldkey)

- **`create`**: Create a subnet (requires burn fee)
- **`register/pow-register`**: Register a UID for the hotkey on a given subnet
- **`register`** (and **`pow-register`** alias): Register a UID for the hotkey on a given subnet; non-root registration is **burn-based**
- **`start`**: Starts a subnet's emission schedule
- **`set-identity`**: Sets on-chain identity for a given subnet.
- **`set-symbol`**: Sets on-chain symbol for a given subnet.
Expand All @@ -283,10 +283,6 @@ Subnet hyperparameters are set with `btcli sudo set`.

Creating subnets requires a coldkey with sufficient balance to cover burn costs.

<!-- Miner and validator registering a hotkey uses a coldkey, has a TAO cost unless proof-of-work -->

<!-- how does POW work??? -->

<details>
<summary>`btcli subnets`</summary>
#### `btcli subnets hyperparameters`
Expand Down
4 changes: 2 additions & 2 deletions docs/errors/subtensor.md
Original file line number Diff line number Diff line change
Expand Up @@ -332,11 +332,11 @@ The stake burn operation has exceeded its rate limit. Try again in the next temp

### `TooManyRegistrationsThisBlock`

Too many registrations in this block.
Too many registrations in this block. Neuron registration rate limits are removed for non-root subnets; this error does not apply to non-root neuron registration.

### `TooManyRegistrationsThisInterval`

Too many registration attempts in interval.
Too many registration attempts in interval. Per-interval neuron registration caps are removed for non-root subnets; this error does not apply to non-root neuron registration.

### `CouldNotJoinSenate`

Expand Down
13 changes: 12 additions & 1 deletion docs/evm-tutorials/neuron-precompile.md
Original file line number Diff line number Diff line change
Expand Up @@ -73,7 +73,18 @@ Registers a neuron in a subnet by burning TAO tokens.
- `hotkey` (bytes32): The hotkey public key (32 bytes) of the neuron to register

**Description:**
This function registers a new neuron in the specified subnet by burning a certain amount of TAO tokens. The amount burned depends on the current network conditions and subnet parameters. The hotkey represents the neuron's identity on the network.
This function registers a new neuron in the specified subnet by burning TAO at the **current dynamic registration price**. The price **decays** over time (governed by `BurnHalfLife`) and **increases** after each successful registration (governed by `BurnIncreaseMult`), clamped by `MinBurn` and `MaxBurn`. The hotkey represents the neuron's identity on the network.

#### `registerLimit`
Registers a neuron but **only if** the burn price does not exceed a caller-supplied cap (slippage protection).

**Parameters:**
- `netuid` (uint16): The subnet ID to register the neuron in
- `hotkey` (bytes32): The hotkey public key (32 bytes) of the neuron to register
- `limitPrice` (uint64): Maximum acceptable burn price in the chain’s fixed-point balance representation—confirm encoding with the deployed precompile ABI and metadata

**Description:**
Use this when you want the transaction to **fail** if the registration cost would be higher than `limitPrice`.

### Axon Services

Expand Down
12 changes: 12 additions & 0 deletions docs/learn/announcements.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,18 @@ title: "Announcements and Developments"

This page tracks recent and upcoming changes to the Bittensor protocol and other major events in the Bittensor ecosystem.

**April, 2026**

## Neuron registration rework

**Status**: Merged in Subtensor ([PR #2382](https://github.com/opentensor/subtensor/pull/2382)); rolling out with network upgrades. Tracking issue: [#2351](https://github.com/opentensor/subtensor/issues/2351).

- **What**: Non-root neuron (UID) registration moves to a **continuous TAO-burn** model, similar in spirit to subnet registration pricing. Legacy **adjustment-interval** mechanics, separate **burned** vs **PoW** admission paths, and **neuron registration rate limits** (including per-interval caps) are removed on upgraded runtimes.
- **Extrinsics**: `register` and `burned_register` remain; both use the **same** burn-based flow under the hood (legacy `register` fields are compatibility-only). **`root_register` / root subnet** behavior is **unchanged**.
- **New owner-tunable pricing hyperparameters**: `BurnHalfLife` (blocks over which the registration cost decays) and `BurnIncreaseMult` (multiplier applied to the current price when a registration succeeds). **`MinBurn`** and **`MaxBurn`** still cap the dynamic price.
- **Optional slippage guard**: `register_limit` (and the EVM neuron precompile `registerLimit`) lets callers specify a maximum acceptable burn; the call fails if the price would exceed it.
- **Docs**: See [Understanding Neurons](neurons.md), [Subnet hyperparameters](../subnets/subnet-hyperparameters.md), [Rate limits](chain-rate-limits.md), and [Neuron precompile](../evm-tutorials/neuron-precompile.md). Confirm exact parameter names, types, and defaults on your target network with `btcli subnet hyperparameters` and chain metadata.

**February, 2026**

## Subnet stake burn
Expand Down
20 changes: 2 additions & 18 deletions docs/learn/chain-rate-limits.md
Original file line number Diff line number Diff line change
Expand Up @@ -156,25 +156,9 @@ This rate limit controls how frequently a subnet validator can set weights to th
- Error message: [`SettingWeightsTooFast`](../errors/subtensor.md#settingweightstoofast)
- Effective Period: Formula is `Tempo × WeightsSetRateLimit × 12 seconds`

### Registration rate limits
### Neuron (UID) registration

This section covers rate limits related to neuron registrations on a subnet.

#### Per-block registration limit

This rate limit controls how frequently registrations can occur on a particular subnet. This rate limit can be modified by changing the `max_regs_per_block` parameter in the subnet hyperparameters. For more information, see [subnet hyperparameters](../subnets/subnet-hyperparameters.md#maxregistrationsperblock).

- Rate Limit: Configurable per subnet (default: 1 registration per block)
- Chain State Variable: `MaxRegistrationsPerBlock`
- Error message: [`TooManyRegistrationsThisBlock`](../errors/subtensor.md#toomanyregistrationsthisblock)

#### Per-interval registration limit

This rate limit controls the frequency of neuron registrations within an [interval](../subnets/subnet-hyperparameters#adjustmentinterval). This limit occurs when registration attempts in the current interval exceed three times the target registrations per interval.

- Rate Limit: 3x the target registrations per interval
- Chain State Variable: `TargetRegistrationsPerInterval`
- Error message: [`TooManyRegistrationsThisInterval`](../errors/subtensor.md#toomanyregistrationsthisinterval)
Neuron registration is **continuous**: there are no registration windows, rate limits, or per-block/per-interval caps. Admission is governed by a **dynamic TAO burn price** that decays over time and rises with each registration. See [Understanding Neurons](neurons.md) and [subnet hyperparameters](../subnets/subnet-hyperparameters.md).

## Subtensor Node Rate Limits

Expand Down
6 changes: 3 additions & 3 deletions docs/learn/neurons.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ Additionally, the Metagraph serves as a global directory for managing subnet nod

## Complete Neuron Lifecycle

1. **Registration** → Neuron registers via PoW or burned registration
1. **Registration** → Neuron pays the **dynamic TAO burn** to obtain a UID (`register` and `burned_register` share one burn-based flow for non-root subnets; `root_register` is separate)
2. **UID Assignment** → Neuron receives unique UID within subnet
3. **Immunity Period** → Neuron is protected from pruning for configurable blocks
4. **Performance Building** → Neuron accumulates rank, trust, consensus, and incentive
Expand All @@ -41,7 +41,7 @@ Additionally, the Metagraph serves as a global directory for managing subnet nod

### Registration and UID Assignment

Neurons register with subnets through proof-of-work or burned registration methods, receiving a unique UID (User ID) within their subnet. The registration process follows an append-or-replace algorithm where new neurons either expand the subnet or replace existing low-performing neurons.
Neurons register with subnets by paying the **current dynamic TAO burn** for their subnet, receiving a unique UID (User ID). Non-root registration is always open: the burn price **decays** over time (set by the owner-configurable `BurnHalfLife` hyperparameter) and **increases** each time a registration succeeds (scaled by `BurnIncreaseMult`), clamped between `MinBurn` and `MaxBurn`. The extrinsics `register` and `burned_register` share the same burn path for non-root subnets. To guard against price movement, callers can use `register_limit(netuid, hotkey, limit_price)`—the registration fails if the actual burn would exceed `limit_price`. **Root** (`root_register`) follows separate rules. The registration process follows an append-or-replace algorithm where new neurons either expand the subnet or replace existing low-performing neurons.

See:

Expand Down Expand Up @@ -76,7 +76,7 @@ Only permitted neurons can set non-self weights, though all neurons can set self
<!-- TODO: Add detailed implementation sections from glossary:
- Neuron Data Structures (NeuronInfo vs NeuronInfoLite)
- Blockchain Storage Implementation (Core Storage Maps, Performance Metrics Storage)
- Registration Process (PoW, Burned, Root registration methods)
- Registration Process (burn-based non-root registration, `register_limit`, Root registration)
- Lifecycle Management (Append vs Replace, Pruning Algorithm, Immunity Period)
- API and Retrieval (Python SDK methods, Blockchain RPC methods)
- State Management (Active Status, Validator Permits, Performance Metrics)
Expand Down
2 changes: 1 addition & 1 deletion docs/local-build/mine-validate.md
Original file line number Diff line number Diff line change
Expand Up @@ -309,7 +309,7 @@ This section discusses errors that could arise while running the validator or mi

**Insufficient funds**

The coldkey signing the `btcli subnet register` transaction must have a sufficient $\tau$ balance to cover the recycling cost of the registration.
The coldkey signing the `btcli subnet register` transaction must have a sufficient $\tau$ balance to cover the registration burn cost.

<details>
<summary><strong>Show sample error</strong></summary>
Expand Down
4 changes: 3 additions & 1 deletion docs/miners/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,9 @@ To participate as a miner, you must first register a hotkey with the subnet in o
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 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.
Registration has a cost in TAO that fluctuates dynamically: the price **decays** over time and **increases** each time a registration succeeds. The subnet owner controls the decay rate (`BurnHalfLife`) and increase factor (`BurnIncreaseMult`), with floor and ceiling set by `MinBurn` and `MaxBurn`. When you secure a UID slot in a subnet on the main chain, this TAO is sunk cost and cannot be recovered.

To protect against price movement between when you check the cost and when your transaction lands, use `register_limit` with a `limit_price`—the registration will fail if the burn would exceed your specified price.

A subnet can have a maximum of 64 subnet validator UIDs and 192 subnet miner UIDs (256 total) in subnets other than Subnet 1.

Expand Down
2 changes: 1 addition & 1 deletion docs/miners/miners-btcli-guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -63,7 +63,7 @@ Miners will need coldkeys to manage their TAO and alpha currency, as well as hot

`btcli wallet new-hotkey` , `btcli wallet regen-hotkey`, : Create and register a hotkey on a secure coldkey workstation then transfer the hotkey file or mnemonic to the mining workstation.

`btcli subnets register`, `btcli subnets pow-register`: register a UID
`btcli subnets register`: register a UID; neuron registration is **TAO burn**-based

## Key rotation

Expand Down
4 changes: 2 additions & 2 deletions docs/resources/glossary.md
Original file line number Diff line number Diff line change
Expand Up @@ -610,9 +610,9 @@ The process of recreating a lost or deleted coldkey or hotkey using the associat

### Register

The process of registering keys with a subnet and purchasing a UID slot.
The process of registering keys with a subnet and purchasing a UID slot by paying the **dynamic neuron registration burn** (TAO). The burn price is bounded by **`MinBurn`** and **`MaxBurn`**, decays over time (governed by `BurnHalfLife`), and increases on each registration (scaled by `BurnIncreaseMult`). The extrinsics `register` and `burned_register` share the same non-root burn path. **Root** registration is separate.

**See also:** [Subnet Miners](../miners/), [Subnet Validators](../validators/), [Working with Subnets](../subnets/working-with-subnets.md)
**See also:** [Subnet Miners](../miners/), [Subnet Validators](../validators/), [Working with Subnets](../subnets/working-with-subnets.md), [Understanding Neurons](../learn/neurons.md)

### Relative stake weight

Expand Down
Loading