diff --git a/docs/btcli/btcli-permissions.md b/docs/btcli/btcli-permissions.md index 718c035d..e5474140 100644 --- a/docs/btcli/btcli-permissions.md +++ b/docs/btcli/btcli-permissions.md @@ -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 @@ -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. @@ -283,10 +283,6 @@ Subnet hyperparameters are set with `btcli sudo set`. Creating subnets requires a coldkey with sufficient balance to cover burn costs. - - - -
`btcli subnets` #### `btcli subnets hyperparameters` diff --git a/docs/errors/subtensor.md b/docs/errors/subtensor.md index 13a35b02..917831d0 100644 --- a/docs/errors/subtensor.md +++ b/docs/errors/subtensor.md @@ -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` diff --git a/docs/evm-tutorials/neuron-precompile.md b/docs/evm-tutorials/neuron-precompile.md index d95cc26c..be5dc1fe 100644 --- a/docs/evm-tutorials/neuron-precompile.md +++ b/docs/evm-tutorials/neuron-precompile.md @@ -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 diff --git a/docs/learn/announcements.md b/docs/learn/announcements.md index 9e3cde65..afbb65f8 100644 --- a/docs/learn/announcements.md +++ b/docs/learn/announcements.md @@ -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 diff --git a/docs/learn/chain-rate-limits.md b/docs/learn/chain-rate-limits.md index b3674a83..a48f52cb 100644 --- a/docs/learn/chain-rate-limits.md +++ b/docs/learn/chain-rate-limits.md @@ -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 diff --git a/docs/learn/neurons.md b/docs/learn/neurons.md index 5e13af68..9f4fc289 100644 --- a/docs/learn/neurons.md +++ b/docs/learn/neurons.md @@ -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 @@ -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: @@ -76,7 +76,7 @@ Only permitted neurons can set non-self weights, though all neurons can set self + +Run the command against your target network to see current hyperparameter names, values, and descriptions. ### Set hyperparameters on BTCLI {#set-hyperparameters} @@ -200,7 +154,8 @@ The number of blocks for the stake to become inactive for the purpose of epoch i **Permissions required to set**: Subnet owner **Description**: -`AdjustmentAlpha` is the rate at which difficulty and burn are adjusted up or down. + +Not used for neuron registration. Non-root neuron registration pricing is governed by [BurnHalfLife](#burnhalflife) and [BurnIncreaseMult](#burnincreasemult). ### AdjustmentInterval @@ -216,7 +171,7 @@ The number of blocks for the stake to become inactive for the purpose of epoch i **Description**: -`AdjustmentInterval` is number of blocks that pass between difficulty and burn adjustments. +Not used for neuron registration. Non-root neuron registration pricing is continuous and governed by [BurnHalfLife](#burnhalflife) and [BurnIncreaseMult](#burnincreasemult). ### AlphaSigmoidSteepness @@ -299,6 +254,38 @@ See [Yuma Consensus: Penalizing out-of-consensus bonds](../learn/yuma-consensus# Determines whether or not bonds are reset-enabled. +### BurnHalfLife + +**Type**: Confirm on target network (typically a block count) + +**Default**: Network-dependent; use `btcli subnet hyperparameters` + +**`btcli` setter**: Use the parameter name as listed by `btcli subnet hyperparameters` on your network (often `burn_half_life`) + +**Setter extrinsic**: See Subtensor `AdminUtils` / chain metadata for the subnet-owner setter corresponding to this storage (naming follows `sudo_set_*` conventions) + +**Permissions required to set**: Subnet owner (unless metadata indicates root-only) + +**Description**: + +**`BurnHalfLife`** sets the decay horizon (in blocks) for the **neuron registration burn cost** between registrations: a longer half-life means the price falls more slowly when nobody registers. + +### BurnIncreaseMult + +**Type**: Confirm on target network (floating-point multiplier in the runtime) + +**Default**: Network-dependent; use `btcli subnet hyperparameters` + +**`btcli` setter**: Use the parameter name as listed by `btcli subnet hyperparameters` on your network (often `burn_increase_mult`) + +**Setter extrinsic**: See Subtensor `AdminUtils` / chain metadata for the subnet-owner setter corresponding to this storage + +**Permissions required to set**: Subnet owner (unless metadata indicates root-only) + +**Description**: + +**`BurnIncreaseMult`** is the factor by which the **current** neuron registration burn cost is **multiplied when a registration succeeds** (before **`MinBurn`** / **`MaxBurn`** clamping). Higher values make rapid successive registrations more expensive. + ### CommitRevealPeriod **Type**: u64 @@ -349,9 +336,7 @@ Enables [Commit Reveal](../concepts/commit-reveal) **Description**: -Current dynamically computed value for the proof-of-work (POW) requirement for POW hotkey registration. Decreases over time but increases after new registrations, between the min and the maximum set by the Subnet owner. see [MaxDifficulty](#maxdifficulty). - - +Not used for neuron registration. Neuron registration uses TAO burn pricing; see [BurnHalfLife](#burnhalflife) and [BurnIncreaseMult](#burnincreasemult). ### EMAPriceHalvingPeriod @@ -481,7 +466,7 @@ Maximum validators on a subnet. **Description**: -The maximum of the dynamic range for TAO cost of burn registration on the subnet. +Upper bound for the **dynamic TAO burn** required for **neuron (UID) registration** on the subnet. This clamps the price together with [MinBurn](#minburn); **`BurnHalfLife`** and **`BurnIncreaseMult`** shape how the price moves over time and on each registration. ### MaxDifficulty @@ -497,7 +482,7 @@ The maximum of the dynamic range for TAO cost of burn registration on the subnet **Description**: -The maximum of the dynamic range for difficulty of proof-of-work registration on the subnet. +Not used for neuron registration. Neuron registration uses TAO burn pricing; see [MaxBurn](#maxburn). ### MaxRegistrationsPerBlock @@ -513,7 +498,7 @@ The maximum of the dynamic range for difficulty of proof-of-work registration on **Description**: -Maximum neuron registrations per block. Note: Actual limit may be lower, as there is also per interval limit [`TargetRegistrationsPerInterval`](#targetregistrationsperinterval). +Not used for neuron registration. Neuron admission is governed by continuous burn pricing; see [BurnHalfLife](#burnhalflife) and [BurnIncreaseMult](#burnincreasemult). ### MechanismCount @@ -589,7 +574,7 @@ Minimum number of weights for a validator to set when setting weights. **Description**: -The minimum of the range of the dynamic burn cost for registering on the subnet. +Lower bound for the **dynamic TAO burn** required for **neuron (UID) registration** on the subnet. This clamps the price together with [MaxBurn](#maxburn). ### MinDifficulty @@ -605,7 +590,7 @@ The minimum of the range of the dynamic burn cost for registering on the subnet. **Description**: -The minimum of the range of the proof-of-work for registering on the subnet. +Not used for neuron registration. Neuron registration uses TAO burn pricing; see [MinBurn](#minburn). ### MinNonImmuneUids @@ -638,7 +623,7 @@ Sets the minimum number non-immune UIDs that must remain in a subnet. It is only **Description**: -`NetworkPowRegistrationAllowed` is a flag that toggles PoW registrations on a subnet +Not used for neuron registration. Neuron registration is burn-based and always open; see [Understanding Neurons](../learn/neurons.md). ### NetworkRateLimit @@ -670,7 +655,7 @@ Rate limit for network registrations expressed in blocks **Description**: -`NetworkRegistrationAllowed` determines if burned registrations are allowed. If both burned and pow registrations are disabled, the subnet will not get emissions. +`NetworkRegistrationAllowed` determines whether neuron registration is enabled on the subnet. If disabled, the subnet will not receive new neurons. ### OwnerHyperparamRateLimit @@ -795,11 +780,7 @@ Changes the hotkey of the subnet owner on the subnet. **Description**: -Target number of neuron registrations allowed per interval. Interval is `AdjustmentInterval`. - -:::info -The hyperparameter triggers a rate limit when the registration attempts in the current interval exceed three times the `TargetRegistrationsPerInterval` value. -::: +Not used for neuron registration. Neuron admission is governed by continuous burn pricing; see [BurnHalfLife](#burnhalflife) and [BurnIncreaseMult](#burnincreasemult). ### Tempo diff --git a/docs/subtensor-nodes/subtensor-storage-query-examples.md b/docs/subtensor-nodes/subtensor-storage-query-examples.md index 70a51832..045be58f 100644 --- a/docs/subtensor-nodes/subtensor-storage-query-examples.md +++ b/docs/subtensor-nodes/subtensor-storage-query-examples.md @@ -58,7 +58,7 @@ import { SdkVersion } from "../sdk/_sdk-version.mdx"; ``` ## 4. AdjustmentAlpha -- **Description**: Alpha adjustment value for the network. +- **Description**: Alpha adjustment value for the network. Not used for neuron registration. - **Query Type**: `u16 -> u64` - **Parameters**: - `netuid`: `u16` @@ -74,7 +74,7 @@ import { SdkVersion } from "../sdk/_sdk-version.mdx"; ``` ## 5. AdjustmentInterval -- **Description**: Adjustment interval for networks. +- **Description**: Adjustment interval for networks. Not used for neuron registration. - **Query Type**: `u16 -> u16` - **Parameters**: - `netuid`: `u16` @@ -1194,7 +1194,7 @@ import { SdkVersion } from "../sdk/_sdk-version.mdx"; ``` ## 74. MaxRegistrationsPerBlock -- **Description**: Maximum registrations allowed per block. +- **Description**: Maximum registrations allowed per block. Neuron registration rate limits are removed for non-root subnets; this item is unused for non-root neuron registration. - **Query Type**: `u16 -> u16` - **Parameters**: - `block`: `u16` @@ -1419,7 +1419,7 @@ import { SdkVersion } from "../sdk/_sdk-version.mdx"; ``` ## 89. NetworkPowRegistrationAllowed -- **Description**: Whether PoW registration is allowed in the network. +- **Description**: Whether PoW registration is allowed in the network. Non-root neuron registration is burn-based; this flag is unused for that path. - **Query Type**: `u16 -> bool` - **Parameters**: - `netuid`: `u16` @@ -1748,7 +1748,7 @@ import { SdkVersion } from "../sdk/_sdk-version.mdx"; ``` ## 110. POWRegistrationsThisInterval -- **Description**: Number of PoW registrations in this interval. +- **Description**: Number of PoW registrations in this interval. Removed for non-root neuron registration; verify in metadata before use. - **Query Type**: `u16 -> u16` - **Parameters**: - `netuid`: `u16` @@ -2572,7 +2572,7 @@ import { SdkVersion } from "../sdk/_sdk-version.mdx"; ``` ## 161. TargetRegistrationsPerInterval -- **Description**: Target registrations per interval for the network. +- **Description**: Target registrations per interval for the network. Per-interval neuron registration caps are removed for non-root subnets; this item is unused for non-root neuron admission. - **Query Type**: `u16 -> u16` - **Parameters**: - `netuid`: `u16` diff --git a/docs/validators/validators-btcli-guide.md b/docs/validators/validators-btcli-guide.md index 4f032964..f85e5a60 100644 --- a/docs/validators/validators-btcli-guide.md +++ b/docs/validators/validators-btcli-guide.md @@ -35,7 +35,7 @@ Note that hotkeys are not encrypted by default, but can be password [optionally - Create and register a hotkey on a secure coldkey workstation then transfer the hotkey file or mnemonic to the validator workstation: `btcli wallet new-hotkey` , `btcli wallet regen-hotkey` - Transfer/rotate TAO and alpha stake in case of key compromise - Rotate hotkeys in case of compromise -- Register a hotkey on a subnet with `btcli subnets register`, `btcli subnets pow-register` +- Register a hotkey on a subnet with `btcli subnets register` (or `btcli subnets pow-register`); non-root registration is **burn-based** - Set validator take with `btcli sudo set-take` ### Validator node (hotkey workstation)