Skip to content

Commit a58465e

Browse files
MichaelTrestmanchideraaomcjkula
authored
rate limits (#85)
* wip * rate limit doc updates * removed .md file * rate limit updates * wip * wip * wip * wip * Update docs/learn/chain-rate-limits.md Co-authored-by: Maciej Kula <[email protected]> * Update docs/learn/chain-rate-limits.md Co-authored-by: Maciej Kula <[email protected]> * Update docs/learn/chain-rate-limits.md Co-authored-by: Maciej Kula <[email protected]> * Update docs/learn/chain-rate-limits.md Co-authored-by: Maciej Kula <[email protected]> * wip --------- Co-authored-by: Dera Okeke <[email protected]> Co-authored-by: Maciej Kula <[email protected]>
1 parent dfccfab commit a58465e

File tree

4 files changed

+198
-30
lines changed

4 files changed

+198
-30
lines changed

‎docs/learn/chain-rate-limits.md‎

Lines changed: 164 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,164 @@
1+
# Bittensor Rate Limits
2+
3+
This page reviews all rate limits implemented in the Bittensor blockchain (Subtensor). Rate limits prevent spam, ensure network stability, and maintain fair access to network resources. Rate limits in Bittensor are implemented as block-based cooldown periods. When a rate-limited operation succeeds, subsequent attempts to perform the same operation must wait for a specified number of [blocks](../resources/glossary.md#block) to pass before they can be executed again. Unsuccessful operations may be re-tried.
4+
5+
:::info
6+
To check/confirm confirm current rate limits and other chain state variables on the blockchain, use the Polkadot.js chain explorer.
7+
8+
To view the chain state for Bittensor main network ('finney'), visit [`https://polkadot.js.org/apps`](https://polkadot.js.org/apps), choose Bittensor network, and click **Chain State** under the **Developer** tab, or visit:
9+
10+
[`https://polkadot.js.org/apps/?rpc=wss%3A%2F%2Fbittensor-finney.api.onfinality.io%2Fpublic-ws#/chainstate`](https://polkadot.js.org/apps/?rpc=wss%3A%2F%2Fbittensor-finney.api.onfinality.io%2Fpublic-ws#/chainstate).
11+
12+
Most relevant attributes are under the `subtensorModule`.
13+
:::
14+
15+
## Global rate limits
16+
17+
This section discusses rate limits that apply globally across the entire network.
18+
19+
### General transaction rate limit
20+
21+
This is the default transaction rate limit in Bittensor, but it currently only applies to hotkey swaps (other rate limited transsactions are handled by custom rate limits).
22+
23+
- **Rate Limit**: 1 block (12 sec)
24+
- **Configuration**: `TxRateLimit` in [runtime/src/lib.rs](https://github.com/opentensor/subtensor/blob/main/runtime/src/lib.rs#L1144)
25+
- **Error message**: [`TxRateLimitExceeded`](../errors/subtensor.md#txratelimitexceeded)
26+
27+
### Delegate take rate limit
28+
29+
This rate limit prevents frequent changes to delegate take percentages.
30+
31+
- **Rate Limit**: 216,000 blocks (~30 days)
32+
- **Configuration**: `TxDelegateTakeRateLimit` in [runtime/src/lib.rs](https://github.com/opentensor/subtensor/blob/main/runtime/src/lib.rs#L1145)
33+
- **Error message**: [`DelegateTxRateLimitExceeded`](../errors/subtensor.md#delegatetxratelimitexceeded)
34+
35+
### Child key take rate limit
36+
37+
This rate limit prevents the owner of a child hotkey from making frequent changes to the child key take percentages. This protects against rapid manipulation of child key relationships and ensures stability in the child key delegation system.
38+
39+
- **Rate Limit**: 216,000 blocks (~30 days)
40+
- **Configuration**: `TxChildkeyTakeRateLimit` in [runtime/src/lib.rs](https://github.com/opentensor/subtensor/blob/main/runtime/src/lib.rs#L1146)
41+
- **Error message**:[ `TxChildkeyTakeRateLimitExceeded`](../errors/subtensor.md#txchildkeytakeratelimitexceeded)
42+
43+
### Hotkey set rate limit
44+
45+
This rate limit prevents a user from swapping a hotkey too frequently.
46+
47+
- **Rate Limit**: 1,000 blocks (~3.3 hours)
48+
- **Configuration**: [macros/errors.rs](https://github.com/opentensor/subtensor/blob/main/pallets/subtensor/src/macros/errors.rs#L93)
49+
- **Error message**: [`HotKeySetTxRateLimitExceeded`](../errors/subtensor.md#hotkeysettxratelimitexceeded)
50+
51+
### UID trimming rate limit
52+
53+
This rate limit controls how frequently subnet owners can trim UIDs on their subnets. This prevents disruptions in subnet stability and excessive network reorganization.
54+
55+
- **Rate Limit**: 216,000 blocks (~30 days) on main net; 1 block in 'fastblocks' development mode.
56+
- **Configuration**: `MaxUidsTrimmingRateLimit` [macros/errors.rs](https://github.com/opentensor/subtensor/blob/main/pallets/subtensor/src/lib.rs#L620-L624)
57+
- **Error message**: [`TxRateLimitExceeded`](../errors/subtensor.md#txratelimitexceeded)
58+
59+
### Network registration rate rimit
60+
61+
This rate limit prevents frequent creation of new subnets.
62+
63+
- **Rate Limit**: 28,800 blocks (~4 days)
64+
- **Configuration**: `NetworkRateLimit` in [runtime/src/lib.rs](https://github.com/opentensor/subtensor/blob/main/runtime/src/lib.rs#L1155)
65+
- **Error message**: [`NetworkTxRateLimitExceeded`](../errors/subtensor.md#networktxratelimitexceeded)
66+
67+
## Subnet-specific rate limits
68+
69+
This section discusses rate limits that apply within a specific subnet on the network. These limits are typically configurable at the subnet level.
70+
71+
### Serving rate limits
72+
73+
This rate limit controls how frequently neurons can update their serving information (axon and prometheus data) on the Bittensor network. This rate limit can be modified by changing the `serving_rate_limit` parameter in the subnet hyperparameters. For more information, see [subnet hyperparameters](../subnets/subnet-hyperparameters.md#servingratelimit).
74+
75+
- **Rate Limit**: Configurable per subnet (default: 50 blocks)
76+
- **Configuration**: `ServingRateLimit` in [runtime/src/lib.rs](https://github.com/opentensor/subtensor/blob/main/runtime/src/lib.rs#L1138)
77+
- **Error message**: [`ServingRateLimitExceeded`](../errors/subtensor.md#servingratelimitexceeded)
78+
79+
### Subnet owner hyperparameter update rate limit
80+
81+
This rate limit controls how frequently a subnet owner can change subnet hyperparameters (e.g., `kappa`, `rho`, `serving_rate_limit`, etc.). The limit is enforced independently per hyperparameter, so updating one parameter does not block updating a different one during the same window.
82+
83+
- **Rate Limit**: Tempo(netuid) × OwnerHyperparamRateLimit (default: 2 tempos; with default tempo 360, that is 720 blocks)
84+
- **Configuration**:
85+
- Global multiplier: `OwnerHyperparamRateLimit` (root) via `sudo_set_owner_hparam_rate_limit`
86+
- Tempo per subnet: `Tempo` (root) via `sudo_set_tempo`
87+
- **Implementation**: [rate_limiting.rs](https://github.com/opentensor/subtensor/blob/main/pallets/subtensor/src/utils/rate_limiting.rs#L41-L49)
88+
- **Error message**: [`TxRateLimitExceeded`](../errors/subtensor.md#txratelimitexceeded)
89+
90+
Note: All subnet owner operations are disallowed during the final blocks of each tempo as governed by `AdminFreezeWindow`. This restriction is in addition to the above rate limit.
91+
92+
### Mechanism configuration rate limits
93+
94+
These limits govern how often a subnet owner can change the number of incentive mechanisms and the emission split among them. For background on mechanisms, see [Multiple Incentive Mechanisms Within Subnets](../subnets/understanding-multiple-mech-subnets.md).
95+
96+
#### Mechanism count update rate limit
97+
98+
- **Rate Limit**: 7,200 blocks (~24 hours)
99+
- **Implementation**: [utils/rate_limiting.rs](https://github.com/opentensor/subtensor/blob/main/pallets/subtensor/src/utils/rate_limiting.rs#L28-L29)
100+
- **Error message**: [`TxRateLimitExceeded`](../errors/subtensor.md#txratelimitexceeded)
101+
102+
#### Mechanism emission split update rate limit
103+
104+
- **Rate Limit**: 7,200 blocks (~24 hours) on main net; 1 block in 'fastblocks' development mode.
105+
- **Implementation**: [utils/rate_limiting.rs](https://github.com/opentensor/subtensor/blob/main/pallets/subtensor/src/utils/rate_limiting.rs#L28-L29)
106+
- **Error message**: [`TxRateLimitExceeded`](../errors/subtensor.md#txratelimitexceeded)
107+
108+
### Staking operations rate limits
109+
110+
This rate limit controls how frequently a user can perform staking operations (add/remove stake, move stake) to a particular subnet (netuid).
111+
112+
- **Rate Limit**: 1 per block
113+
- **Configuration**: [macros/errors.rs](https://github.com/opentensor/subtensor/blob/main/pallets/subtensor/src/macros/errors.rs#L222)
114+
- **Error message**: [`StakingOperationRateLimitExceeded`](../errors/subtensor.md#stakingoperationratelimitexceeded)
115+
116+
### Weights rate limits
117+
118+
This section covers rate limits related to setting weights on a subnet. This rate limit can be modified by changing the `weights_rate_limit` parameter in the subnet hyperparameters. For more information, see [subnet hyperparameters](../subnets/subnet-hyperparameters.md#weightsratelimit--commitmentratelimit).
119+
120+
#### Weights setting rate limit
121+
122+
This rate limit controls how frequently a subnet validator can set weights to the network.
123+
124+
- **Rate Limit**: Configurable per subnet (default: 100 blocks)
125+
- **Configuration**: `WeightsSetRateLimit` per subnet
126+
- **Implementation**: [subnets/weights.rs](https://github.com/opentensor/subtensor/blob/main/pallets/subtensor/src/subnets/weights.rs#L723-731)
127+
- **Error message**: [`SettingWeightsTooFast`](../errors/subtensor.md#settingweightstoofast)
128+
129+
#### Commit-reveal weights rate limit
130+
131+
This rate limit controls how frequently a subnet validator can set commit on to the Bittensor chain. Changing the `weights_rate_limit` parameter in the subnet's hyperparameters also modifies this rate limit. For more information, see [subnet hyperparameters](../subnets/subnet-hyperparameters.md#weightsratelimit--commitmentratelimit).
132+
133+
- **Rate Limit**: Uses the same rate limit as [weights setting rate limit](#weights-setting-rate-limit)
134+
- **Implementation**: [subnets/weights.rs](https://github.com/opentensor/subtensor/blob/main/pallets/subtensor/src/subnets/weights.rs#L65-71)
135+
- **Error message**: [`CommittingWeightsTooFast`](../errors/subtensor.md#committingweightstoofast)
136+
137+
### Registration rate limits
138+
139+
This section covers rate limits related to neuron registrations on a subnet.
140+
141+
#### Per-block registration limit
142+
143+
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).
144+
145+
- **Rate Limit**: Configurable per subnet (default: 1 registration per block)
146+
- **Configuration**: `MaxRegistrationsPerBlock` in [runtime/src/lib.rs](https://github.com/opentensor/subtensor/blob/main/runtime/src/lib.rs#L1123)
147+
- **Error message**: [`TooManyRegistrationsThisBlock`](../errors/subtensor.md#toomanyregistrationsthisblock)
148+
149+
#### Per-interval registration limit
150+
151+
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.
152+
153+
- **Rate Limit**: 3x the target registrations per interval
154+
- **Configuration**: `TargetRegistrationsPerInterval` in [runtime/src/lib.rs](https://github.com/opentensor/subtensor/blob/main/runtime/src/lib.rs#L1122)
155+
- **Error message**: [`TooManyRegistrationsThisInterval`](../errors/subtensor.md#toomanyregistrationsthisinterval)
156+
157+
## Subtensor Node Rate Limits
158+
159+
When querying OTF-provided lite nodes, then the following rate limits apply. We strongly encourage you to run your own local lite node.
160+
161+
- Any OTF-provided lite node will rate limit the requests to one request per second, per IP address. Note that this rate limit may change dynamically based on the network or application requirements.
162+
- A request can be either WS/WSS or HTTP/HTTPS.
163+
- If you exceed the rate limit, you will receive the error code 429. You will then have to wait until the rate limit window has expired.
164+
- You can avoid OTF-lite node rate limits by running your own local lite node. You can run a lite node either [Using Docker](../subtensor-nodes/using-docker.md#using-lite-nodes) or [Using Source](../subtensor-nodes/using-source#lite-node-on-mainchain).

‎docs/subnets/subnet-hyperparameters.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -521,6 +521,22 @@ Deprecated.
521521

522522
Rate limit for calling `serve_axon` and `serve_prometheus` extrinsics used by miners.
523523

524+
### OwnerHyperparamRateLimit
525+
526+
**Type**: u16
527+
528+
**Default**: 2 (tempos)
529+
530+
**`btcli` setter**: none
531+
532+
**Setter extrinsic**: `sudo_set_owner_hparam_rate_limit`
533+
534+
**Permissions required to set**: Root
535+
536+
**Description**:
537+
538+
Global multiplier that rate-limits how frequently a subnet owner can update subnet hyperparameters. The cooldown window equals `Tempo(netuid) × OwnerHyperparamRateLimit` blocks. The rate limit is tracked independently per hyperparameter; changing `kappa` does not block an immediate change to `rho`, for example.
539+
524540
### SubnetIsActive
525541

526542
**Type**: Bool

‎docs/subtensor-nodes/subtensor-rate-limits.md‎

Lines changed: 0 additions & 12 deletions
This file was deleted.

‎sidebars.js‎

Lines changed: 18 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@ const sidebars = {
2323
"index",
2424
{
2525
type: "category",
26-
label: "Releases and Announcements",
26+
label: "Releases and Announcements",
2727
collapsible: true,
2828
collapsed: true,
2929
items: [
@@ -37,7 +37,7 @@ const sidebars = {
3737
id: "learn/announcements",
3838
label: "Announcements",
3939
},
40-
]
40+
],
4141
},
4242
"btcli/btcli-playground",
4343
{
@@ -47,7 +47,7 @@ const sidebars = {
4747
collapsible: true,
4848
collapsed: true,
4949
items: [
50-
"learn/introduction",
50+
"learn/introduction",
5151
"resources/questions-and-answers",
5252
"subnets/understanding-subnets",
5353
"learn/anatomy-of-incentive-mechanism",
@@ -60,19 +60,20 @@ const sidebars = {
6060
"learn/yuma-consensus",
6161
"learn/yc3-blog",
6262
"learn/yuma3-migration-guide",
63-
"learn/fees",
63+
"learn/fees",
64+
"learn/chain-rate-limits",
6465
{
65-
type: "category",
66-
label: "Navigating Subtensor Codebase",
67-
link: { type: "doc", id: "navigating-subtensor/index" },
68-
collapsible: true,
69-
collapsed: true,
70-
items: [
71-
"navigating-subtensor/emissions-coinbase",
72-
"navigating-subtensor/epoch",
73-
"navigating-subtensor/swap-stake",
74-
],
75-
},
66+
type: "category",
67+
label: "Navigating Subtensor Codebase",
68+
link: { type: "doc", id: "navigating-subtensor/index" },
69+
collapsible: true,
70+
collapsed: true,
71+
items: [
72+
"navigating-subtensor/emissions-coinbase",
73+
"navigating-subtensor/epoch",
74+
"navigating-subtensor/swap-stake",
75+
],
76+
},
7677
"resources/community-links",
7778
],
7879
},
@@ -227,12 +228,11 @@ const sidebars = {
227228
items: [
228229
"subtensor-nodes/subtensor-node-requirements",
229230
"subtensor-nodes/using-source",
230-
"subtensor-nodes/using-docker",
231-
"subtensor-nodes/subtensor-rate-limits",
231+
"subtensor-nodes/using-docker",
232232
"subtensor-nodes/subtensor-storage-query-examples",
233233
],
234234
},
235-
235+
236236
{
237237
type: "category",
238238
label: "Bittensor EVM",

0 commit comments

Comments
 (0)