Table of Contents
A subnet hyperparameter is a per-subnet value stored on-chain that the Bittensor protocol reads when it runs key subnet operations.
In practical terms, hyperparameters are the dials around a subnet’s incentive mechanism. They do not define what the subnet’s miners produce or how validators evaluate that work. That part is the subnet’s incentive mechanism, which is off-chain code maintained by the subnet team. Hyperparameters instead control chain-side conditions around the mechanism, such as how often epochs settle, whether registration is enabled, how many UIDs the subnet can hold, how long new neurons are protected from pruning, and how validator weights are constrained.
The official Bittensor hyperparameters reference describes them as readable through btcli sudo get --netuid N, backed by the subnet_hyperparameters read, and owner-settable values can be changed by the subnet owner with btcli sudo set through the set_hyperparameter intent. Bittensor’s hyperparameters reference also lists each parameter’s unit, owner-settable status, purpose, and source in on-chain storage.
A subnet has several parts:
- An off-chain task and scoring process
- Validators that evaluate miners
- Miners that perform the requested work
- On-chain registration, weight, epoch, and payment rules
Hyperparameters live in the fourth category. They are not the subnet’s business model or codebase, but they affect how the chain surrounds that codebase with rules.
For example, tempo controls the block interval between subnet epochs. Tempo is one subnet hyperparameter among many, a chain-side setting that shapes when a subnet’s accumulated rewards settle.
Who Can Change Hyperparameters?
Not every hyperparameter belongs to the subnet owner. Bittensor’s hyperparameters fall into two broad control tiers: owner-settable values and root-only values.
Owner-settable hyperparameters are values the subnet owner can change within protocol-defined limits. Examples include tempo, immunity_period, registration_allowed, min_burn, max_burn, max_allowed_uids, bonds_moving_avg, transfers_enabled, and owner_cut_enabled, based on the current Bittensor reference table.
Root-only hyperparameters require broader chain administration rather than a normal subnet-owner action. Examples include kappa, max_weights_limit, activity_cutoff, max_regs_per_block, max_validators, yuma_version, subnet_is_active, and subnet_emission_enabled.
That does not mean a subnet owner has no power. A subnet owner controls meaningful parts of the subnet’s operating environment, including owner-settable hyperparameters and the off-chain incentive mechanism. But a subnet owner does not control every on-chain parameter and cannot unilaterally change root-only rows. Our guide to who controls Bittensor explains the broader distinction between subnet owners, sudo/root-level authority, and protocol governance.
Owner-Settable Does Not Mean Unlimited
Even when a value is owner-settable, the owner is still constrained.
The official running-a-subnet guide says owner-settable hyperparameters go through set-hyperparameter, while they can be read through subnet-hyperparameters. It also describes two important chain-side constraints: owner changes are rate-limited, and owner admin calls are rejected during the final blocks of a tempo while an epoch is being computed.
The registration burn guide makes the same point for burn-related controls: owner-settable values can be changed through btcli sudo set, but those changes are rate-limited and only allowed outside the subnet’s weights window.
So “owner-settable” means the owner has a defined administrative path. It does not mean values can be changed constantly, outside allowed ranges, or during protected chain windows.
How To Check A Subnet’s Hyperparameters
The main read command is:
btcli sudo get --netuid NReplace N with the subnet’s netuid. This reads the subnet’s hyperparameters through the subnet_hyperparameters query. The SDK-facing form shown in Bittensor’s subnet guide is:
btcli query subnet-hyperparameters --netuid 42 --jsonA subnet owner changing an owner-settable value uses a set path such as:
btcli sudo set --netuid 42 --name min_burn --value 500000000The important habit is checking the live subnet instead of assuming a default applies everywhere.
Raw on-chain values are primary. Some values are stored as blocks, some as flags, some as rao amounts, and some as fixed-point fractions. The Bittensor reference notes that fixed-point fractions and rao amounts may also accept a human-readable decimal form. For example, a fraction stored as a u16 may use 65,535 as 1.0, while a TAO amount may be stored in rao.
This is why hyperparameter printouts can be confusing at first. A number may be obvious only after you know the unit. A value such as 360 may represent blocks. A value such as 32767 may represent a fraction close to 0.5 when the maximum is 65,535. A value such as 500000 may represent rao, not 500,000 TAO.
The Main Kinds Of Hyperparameters
Bittensor has dozens of subnet hyperparameters, and the list can change as the protocol evolves. It is more useful to group them by what they control than to memorize every row.
Timing Hyperparameters
Timing parameters shape when subnet operations happen.
The clearest example is tempo, which is measured in blocks and controls the number of blocks between consensus epochs. If a subnet has the default tempo of 360 blocks, and Bittensor produces a block roughly every 12 seconds, the subnet’s epoch cadence is about 72 minutes. However, live subnet values can differ.
Another timing-related value is activity_cutoff, which affects how inactivity is treated. The current running-a-subnet guide also discusses activity_cutoff_factor, which calculates an effective cutoff from tempo.
Timing settings define the rhythm of subnet behavior. They affect when rewards settle, when validators need to participate, and how quickly certain subnet conditions update.
Registration And Capacity Hyperparameters
Registration and capacity parameters shape how participants enter a subnet and how many UIDs it can support.
Examples include:
| Hyperparameter | What It Helps Control |
|---|---|
registration_allowed | Whether burn registration is enabled |
network_pow_registration_allowed | Whether proof-of-work registration is enabled |
min_burn / max_burn | The floor and ceiling for the registration price |
burn_half_life | How quickly registration price decays over time |
burn_increase_mult | How much registration price rises after a successful registration |
max_allowed_uids | The subnet’s UID capacity before pruning or trimming rules matter |
immunity_period | How long a newly registered neuron is protected from pruning |
The registration burn guide gives concrete defaults for several burn-related values: min_burn defaults to 500,000 rao, or τ0.0005; max_burn defaults to 100 TAO; burn_half_life defaults to 360 blocks; and burn_increase_mult defaults to 1.26.
The running-a-subnet guide lists max_allowed_uids with a default of 256 and says owners cannot trim below a floor of 64 UIDs. The same guide lists immunity_period with a default of 4,096 blocks, while noting that specific subnets can configure their own values within the rules.
This is where many learner mistakes happen. If an article says “the immunity period is 4,096 blocks,” it may be quoting a chain default. That does not guarantee every live subnet currently uses that value.
Weights And Consensus Hyperparameters
Weights and consensus parameters shape how validator submissions are constrained and processed.
Examples include min_allowed_weights, max_weights_limit, kappa, and yuma_version. Some are owner-settable, while others are root-only. In the current Bittensor reference, min_allowed_weights is owner-settable, while max_weights_limit, kappa, and yuma_version are root-only.
The most recognizable one is probably kappa, which appears in discussions of Yuma Consensus. In brief, kappa is the active-stake threshold used in the consensus calculation. It is important, but it is not something a normal subnet owner can freely tune.
Hyperparameters help define the guardrails around validator weights. They do not replace the validator scoring task itself. Validators still evaluate miners according to the subnet’s incentive mechanism, while the chain applies constraints and reward logic around those submissions.
Validator Hyperparameters
Validator-related hyperparameters help determine who can participate as a validator in a reward-relevant way.
One important example is max_validators, listed as root-only in the current hyperparameters reference. The running-a-subnet guide describes root-only parameters including max_allowed_validators, with a default of 128.
This is another case where ownership limits matter. A subnet owner can define the work and set certain subnet rules, but validator caps and other root-only settings sit outside normal owner control.
Bonds And Smoothing Hyperparameters
Bonds-related hyperparameters affect smoothing and bond behavior in the subnet’s reward system.
Examples include bonds_moving_avg, liquid_alpha_enabled, alpha_high, alpha_low, and bonds_penalty. The details can get technical quickly, especially when liquid alpha and Yuma variants are involved, so a learner does not need to master them on first pass.
At the category level, these parameters influence how quickly bond-related signals update, whether certain smoothing mechanisms are enabled, and how out-of-consensus bond behavior is handled. They are part of the chain-side math around incentives and dividends, not the off-chain work that miners perform.
Owner Economics And Subnet Switches
Some hyperparameters relate to owner economics, stake transfers, collateral, or subnet-level switches.
Examples include:
| Category | Examples |
|---|---|
| Owner Economics | owner_cut_enabled, owner_cut_auto_lock_enabled |
| Transfers | transfers_enabled |
| Collateral | collateral_lock_share, collateral_drain_ratio |
| Root Switches | subnet_is_active, subnet_emission_enabled |
The running-a-subnet guide explains that a subnet being “on” involves two separate flags. The owner’s one-shot start action is tracked by subnet_is_active, while root controls whether the subnet receives its TAO emission share through subnet_emission_enabled.
This split is a useful example of the broader pattern. Some switches are part of owner operations. Others are root-level controls. Both can affect a subnet, but they do not belong to the same administrator.
Why The Same Setting Differs Between Subnets
The same Bittensor protocol can produce different subnet behavior because hyperparameters are per-subnet values.
A default value is a starting point or reference point, not always the live value for every subnet. Subnet owners may configure owner-settable values within their allowed ranges, while root-only values can change through broader chain administration.
This is why you should treat universal claims carefully. If someone says:
- “Tempo is 360 blocks”
- “The immunity period is 4,096 blocks”
- “The registration price floor is τ0.0005”
- “The subnet has 256 UID slots”
The right follow-up is: on which subnet, and at what time?
Those statements may be true as defaults. They may also be true for many live subnets. But Bittensor is built around many subnets, and each one has its own on-chain state. A serious reader checks the subnet rather than relying only on a generic explainer.
This is especially important for stakers and miners. A subnet’s registration environment, epoch cadence, UID capacity, immunity window, validator constraints, and emissions switches can all shape the practical experience of participating in that subnet.
What Subnet Owners Can’t Change
Subnet owners cannot change every hyperparameter, ignore protocol bounds, or rewrite Bittensor’s global rules.
They can set owner-settable values, operate within rate limits, and define the off-chain incentive mechanism. They cannot use btcli sudo set to change root-only rows such as kappa, max_weights_limit, max_validators, subnet_is_active, or subnet_emission_enabled when those are marked root-only in the current reference.
They also cannot turn a hyperparameter into the incentive mechanism itself. If a subnet’s validators score miners based on model outputs, scraping quality, inference responses, data labeling, routing performance, or some other task, that scoring logic is part of the subnet’s off-chain mechanism. Hyperparameters are the chain-side settings around that mechanism.
A useful mental model is:
- The incentive mechanism says what useful work is and how it is scored.
- Hyperparameters say how the chain handles certain subnet rules around registration, epochs, weights, capacity, bonds, and switches.
- Root-only controls sit above the subnet owner and require broader chain authority.
Once you understand that separation, many Bittensor docs become easier to read. When you see a term such as tempo, immunity_period, kappa, or max_allowed_uids, you can ask three questions: what does it control, who can change it, and what value does this subnet use right now?
Conclusion
Subnet hyperparameters are the settings behind every Bittensor subnet’s on-chain behavior.
They are not the subnet’s off-chain code, and they are not all controlled by the subnet owner. They are per-subnet chain values that help determine how registration works, when epochs settle, how weights are constrained, how many UIDs a subnet can support, which switches are enabled, and where owner control ends.
FAQs
What Is A Bittensor Subnet Hyperparameter?
A Bittensor subnet hyperparameter is a per-subnet on-chain setting that the protocol reads when it runs subnet operations such as registration, epochs, weights, pruning, validation, and certain emissions switches. It is a chain-side value, not the subnet’s off-chain incentive mechanism.
Are Hyperparameters The Same On Every Subnet?
No. Each subnet has its own hyperparameter values. Many values start from chain defaults, but owner-settable values can differ across subnets, and root-only values can change through broader chain administration.
Can A Subnet Owner Change Every Hyperparameter?
No. Subnet owners can change only owner-settable hyperparameters within protocol-defined limits. Root-only values, such as kappa, max_weights_limit, max_validators, and some subnet switches, are outside normal owner control.
Can Owners Change Settings Anytime?
No. Owner changes are bounded by protocol rules, rate limits, and protected windows around epoch computation. Bittensor’s guides describe owner-settable changes as rate-limited and blocked during certain weights or admin freeze windows.
Is The Incentive Mechanism A Hyperparameter?
No. The incentive mechanism is the subnet’s off-chain logic for defining useful work and scoring miners. Hyperparameters are on-chain settings around the subnet, such as timing, registration, capacity, weights, and certain switches.
How Do I Check A Subnet’s Tempo Or Immunity Period?
Use btcli sudo get --netuid N, replacing N with the subnet’s netuid. You can also use SDK query paths such as btcli query subnet-hyperparameters --netuid 42 --json to read the current values.
Why Do Two Articles Give Different Immunity Periods?
One article may be quoting a chain default, while another may be describing a live subnet’s configured value. Because hyperparameters are per-subnet, the safest approach is to check the specific subnet’s current value before relying on a number.
