v431 release

.github/workflows/publish-sdk-dev.yml

@@ -53,6 +53,12 @@ jobs:
         working-directory: sdk/python
         run: uv build --out-dir ../../dist
 
+      # PEP 740 provenance, same as the rc/stable publish jobs. Running it on
+      # the dev channel means a broken attestation step fails here on every
+      # push to main instead of for the first time during a release.
+      - name: Generate PEP 740 attestations
+        uses: astral-sh/attest-action@f589a42a7efb6fe400b4f400de60b4bc90390027 # v0.0.6
+
       - name: Publish to TestPyPI
         run: |
           uv publish --trusted-publishing always \

.github/workflows/release-train.yml

@@ -360,6 +360,12 @@ jobs:
       - name: Build SDK wheel and sdist
         working-directory: sdk/python
         run: uv build --out-dir ../../dist
+      # PEP 740 provenance: sign every dist with this job's OIDC identity
+      # (must match the trusted publisher, so it runs here rather than in
+      # build-core-wheels.yml). uv publish uploads the resulting
+      # *.publish.attestation files alongside each dist.
+      - name: Generate PEP 740 attestations
+        uses: astral-sh/attest-action@f589a42a7efb6fe400b4f400de60b4bc90390027 # v0.0.6
       # --check-url makes a re-run after a partial upload idempotent: files
       # already on the index are skipped instead of failing with a 400
       # duplicate (e.g. the SDK wheel landed but bittensor-core didn't).

.github/workflows/watch-mainnet-release.yml

@@ -254,6 +254,14 @@ jobs:
         working-directory: sdk/python
         run: uv build --out-dir ../../dist
 
+      # PEP 740 provenance: sign every dist with this job's OIDC identity.
+      # Must happen here, not in build-core-wheels.yml — PyPI only accepts
+      # attestations whose Sigstore identity matches the trusted publisher
+      # doing the upload. uv publish picks up the *.publish.attestation
+      # files from dist/ automatically.
+      - name: Generate PEP 740 attestations
+        uses: astral-sh/attest-action@f589a42a7efb6fe400b4f400de60b4bc90390027 # v0.0.6
+
       # --check-url makes a re-run after a partial upload idempotent: files
       # already on the index are skipped instead of failing with a 400
       # duplicate (e.g. the SDK wheel landed but bittensor-core didn't).

docs/hyperparameters/activity-cutoff.mdx

@@ -0,0 +1,54 @@
+---
+title: activity_cutoff
+description: Blocks without setting weights after which a validator is inactive and excluded from consensus.
+---
+
+`activity_cutoff` is the window, in blocks, that a validator can go without
+setting weights before the epoch marks it inactive and removes its stake from
+consensus. Validators care because an expired cutoff silently zeroes their
+influence and dividends; owners tune it to keep consensus limited to
+validators that are actually evaluating miners.
+
+## How it works
+
+At each epoch (`pallets/subtensor/src/epoch/run_epoch.rs`), a neuron is
+inactive when `last_update + activity_cutoff` is less than the current block,
+where `last_update` is the block of its last accepted weight submission.
+Inactive stake is masked out of the active-stake vector before consensus, so
+an inactive validator contributes nothing to the
+[`kappa`](/docs/hyperparameters/kappa)-weighted median and earns no
+dividends until it sets weights again.
+
+The effective value is derived, not stored directly:
+`get_activity_cutoff_blocks` (`pallets/subtensor/src/utils/misc.rs`) computes
+`factor_milli × tempo / 1000`, clamped to at least 1 block. The per-mille
+factor is bounded to 1,000–50,000 (one to fifty tempos); the default 13,889
+at tempo 360 yields the legacy 5,000-block cutoff (~16.7 hours).
+
+## Reading and setting
+
+Inspect with:
+
+```
+btcli sudo get --netuid N --name activity_cutoff
+```
+
+This returns the effective block count. Owner-settable:
+
+```
+btcli sudo set --netuid N --name activity_cutoff --value 5000
+```
+
+The value is a raw block count (12s blocks), floor 360. Note that this
+dispatches the legacy absolute-blocks extrinsic; the epoch reads the
+factor-derived value, so the tempo-relative `set_activity_cutoff_factor`
+extrinsic (per-mille of [`tempo`](/docs/hyperparameters/tempo)) is the
+authoritative way to change what the epoch actually uses.
+
+## Related
+
+[`tempo`](/docs/hyperparameters/tempo) ·
+[`kappa`](/docs/hyperparameters/kappa) ·
+[`rho`](/docs/hyperparameters/rho) ·
+[`max_validators`](/docs/hyperparameters/max-validators) ·
+[`weights_rate_limit`](/docs/hyperparameters/weights-rate-limit)

docs/hyperparameters/adjustment-alpha.mdx

@@ -0,0 +1,54 @@
+---
+title: adjustment_alpha
+description: Smoothing factor of the legacy difficulty/burn adjustment, stored as u64 (u64::MAX = 1.0).
+---
+
+The smoothing factor of Bittensor's original registration-price controller.
+When the chain adjusted burn and PoW difficulty once per
+[`adjustment_interval`](/docs/hyperparameters/adjustment-interval), this value
+blended the old price into the new one — an exponential moving average where
+higher alpha meant slower movement. Owners still see it in the hyperparameter
+listing; on the current chain it is inert.
+
+## How it works
+
+The value lives in `AdjustmentAlpha` storage as a u64 fraction where
+`u64::MAX` encodes 1.0. The mainnet default is **0**
+(`SubtensorInitialAdjustmentAlpha` in `runtime/src/lib.rs`) — in the legacy
+formula `next = alpha × current + (1 − alpha) × proposed`, zero meant no
+weight on the previous value, i.e. no smoothing at all.
+
+In the current runtime the legacy interval controller is gone, and **nothing
+reads this value** outside of the RPC/metagraph views: registration pricing is
+handled per block in `pallets/subtensor/src/subnets/registration.rs`, where
+each registration bumps the burn by
+[`burn_increase_mult`](/docs/hyperparameters/burn-increase-mult) and decay with
+half-life [`burn_half_life`](/docs/hyperparameters/burn-half-life) pulls it
+back toward [`min_burn`](/docs/hyperparameters/min-burn). The setter
+(`sudo_set_adjustment_alpha` in `pallets/admin-utils/src/lib.rs`) remains
+callable by the subnet owner, subject only to the owner rate limit and admin
+freeze window — but setting it changes nothing about how registrations are
+priced.
+
+<HyperparamBurnController />
+
+## Reading and setting
+
+```bash
+btcli sudo get --netuid 12 --name adjustment_alpha
+btcli sudo set --netuid 12 --name adjustment_alpha --value 0.5
+```
+
+Settable by the subnet owner or root. A value with a decimal point is a 0..1
+fraction (`0.5` = half weight on the previous value); a plain integer is the
+raw u64 (u64::MAX = 1.0).
+
+## Related
+
+- [`adjustment_interval`](/docs/hyperparameters/adjustment-interval) — the
+  legacy controller's cadence
+- [`target_regs_per_interval`](/docs/hyperparameters/target-regs-per-interval)
+  — the target it steered toward
+- [`burn_half_life`](/docs/hyperparameters/burn-half-life) /
+  [`burn_increase_mult`](/docs/hyperparameters/burn-increase-mult) — the
+  controller that replaced it

docs/hyperparameters/adjustment-interval.mdx

@@ -0,0 +1,51 @@
+---
+title: adjustment_interval
+description: Blocks between adjustments of the registration difficulty and burn cost (legacy cadence).
+---
+
+Historically the cadence of Bittensor's registration-price controller: every
+`adjustment_interval` blocks, the chain compared registrations against
+[`target_regs_per_interval`](/docs/hyperparameters/target-regs-per-interval)
+and moved the burn cost and PoW difficulty up or down. It matters today mostly
+as context — the current chain adjusts the burn price continuously instead.
+
+## How it works
+
+The parameter lives in `AdjustmentInterval` storage (u16 block count, default
+100 blocks ≈ 20 minutes, from `SubtensorInitialAdjustmentInterval` in
+`runtime/src/lib.rs`). In the current runtime, however, **no adjustment logic
+reads it**: the interval-based controller was replaced by a per-block
+mechanism in `pallets/subtensor/src/subnets/registration.rs` where each
+registration multiplies the burn by
+[`burn_increase_mult`](/docs/hyperparameters/burn-increase-mult) and the price
+decays every block with half-life
+[`burn_half_life`](/docs/hyperparameters/burn-half-life), clamped to
+\[[`min_burn`](/docs/hyperparameters/min-burn),
+[`max_burn`](/docs/hyperparameters/max-burn)\]. The value is still stored,
+returned by the `subnet_hyperparameters` query, and settable — the extrinsic
+(`sudo_set_adjustment_interval` in `pallets/admin-utils/src/lib.rs`) checks
+only that the subnet exists — but changing it has no effect on registration
+pricing. Even the root subnet's per-interval registration counter resets on
+the root epoch boundary (`tempo`), not on this interval.
+
+<HyperparamBurnController />
+
+## Reading and setting
+
+```bash
+btcli sudo get --netuid 12 --name adjustment_interval
+```
+
+Root/governance only — `sudo_set_adjustment_interval` requires the root
+origin, so subnet owners cannot change it. The value is a plain block count
+(12-second blocks).
+
+## Related
+
+- [`burn_half_life`](/docs/hyperparameters/burn-half-life) — the cadence's
+  replacement for burn decay
+- [`burn_increase_mult`](/docs/hyperparameters/burn-increase-mult) — the
+  per-registration response
+- [`adjustment_alpha`](/docs/hyperparameters/adjustment-alpha) — the smoothing
+  factor of the same legacy controller
+- [`target_regs_per_interval`](/docs/hyperparameters/target-regs-per-interval)

docs/hyperparameters/alpha-high.mdx

@@ -0,0 +1,38 @@
+---
+title: alpha_high
+description: Upper bound of the liquid-alpha bonds EMA range — the smoothing rate for weights that deviate most from consensus.
+---
+
+`alpha_high` is the ceiling of the per-pair bonds EMA rate when [`liquid_alpha_enabled`](/docs/hyperparameters/liquid-alpha-enabled) is on. Pairs whose weights deviate strongly from consensus approach this rate, so their bonds move fastest. Subnet owners tune it to decide how quickly a bold, off-consensus position translates into bonds; validators care because it caps how fast conviction can build or unwind.
+
+## How it works
+
+Each epoch, `alpha_sigmoid` (`pallets/subtensor/src/epoch/run_epoch.rs`) maps a pair's deviation from consensus into the EMA rate:
+
+```
+alpha = alpha_low + sigmoid(diff) × (alpha_high − alpha_low)
+```
+
+The deviation is `weight − consensus` when a validator is raising its bond, or `bond − weight` when lowering it (both clamped to 0..1). As deviation grows past 0.5 the sigmoid saturates toward 1 and alpha approaches `alpha_high`; the result is clamped into the `alpha_low`..`alpha_high` window. The resulting per-pair matrix drives the bonds EMA `B(t) = alpha × W + (1 − alpha) × B(t−1)` in `mat_ema_alpha`. Defaults are (45875, 58982) — 0.7 and 0.9 of `u16::MAX`.
+
+Validation in `do_set_alpha_values`: liquid alpha must already be enabled (`LiquidAlphaDisabled`), and `alpha_high` must be at least 1638 (`u16::MAX / 40` ≈ 0.025), else `AlphaHighTooLow`. `alpha_low` may not exceed it.
+
+<HyperparamLiquidAlpha focus="alpha_high" />
+
+## Reading and setting
+
+```
+btcli sudo get --netuid N --name alpha_high
+```
+
+Stored as u16 (65535 = 1.0); the CLI accepts the raw integer or a 0..1 fraction with a decimal point:
+
+```
+btcli sudo set --netuid N --name alpha_high --value 0.9
+```
+
+On chain, [`alpha_low`](/docs/hyperparameters/alpha-low) and `alpha_high` live in one storage value set by a single `sudo_set_alpha_values` call. The CLI reads the current pair and resubmits it with only `alpha_high` changed, so the other side is preserved.
+
+## Related
+
+[`alpha_low`](/docs/hyperparameters/alpha-low), [`alpha_sigmoid_steepness`](/docs/hyperparameters/alpha-sigmoid-steepness), [`liquid_alpha_enabled`](/docs/hyperparameters/liquid-alpha-enabled), [`bonds_moving_avg`](/docs/hyperparameters/bonds-moving-avg), [`yuma3_enabled`](/docs/hyperparameters/yuma3-enabled)

docs/hyperparameters/alpha-low.mdx

@@ -0,0 +1,38 @@
+---
+title: alpha_low
+description: Lower bound of the liquid-alpha bonds EMA range — the smoothing rate for weights that sit at consensus.
+---
+
+`alpha_low` is the floor of the per-pair bonds EMA rate when [`liquid_alpha_enabled`](/docs/hyperparameters/liquid-alpha-enabled) is on. It is the rate applied to validator–miner pairs whose weights match consensus — the slow, steady end of the liquid-alpha range. Subnet owners tune it to set how sluggish bonds are in the default case; validators care because it governs how fast their conviction decays or accrues when they are not deviating.
+
+## How it works
+
+Each epoch, `alpha_sigmoid` (`pallets/subtensor/src/epoch/run_epoch.rs`) computes a per-pair rate:
+
+```
+alpha = alpha_low + sigmoid(diff) × (alpha_high − alpha_low)
+```
+
+where `diff` is the pair's deviation from consensus and the sigmoid rises with [`alpha_sigmoid_steepness`](/docs/hyperparameters/alpha-sigmoid-steepness). At zero deviation the sigmoid is near 0, so alpha sits at `alpha_low`; the result is always clamped into the `alpha_low`..`alpha_high` window. Defaults are (45875, 58982), i.e. 0.7 and 0.9 of `u16::MAX`.
+
+Validation in `do_set_alpha_values`: liquid alpha must already be enabled (`LiquidAlphaDisabled`), `alpha_low` must be at least 1638 (`u16::MAX / 40` ≈ 0.025) and at most `alpha_high`, else `AlphaLowOutOfRange`.
+
+<HyperparamLiquidAlpha focus="alpha_low" />
+
+## Reading and setting
+
+```
+btcli sudo get --netuid N --name alpha_low
+```
+
+Stored as u16 (65535 = 1.0); the CLI accepts the raw integer or a 0..1 fraction with a decimal point:
+
+```
+btcli sudo set --netuid N --name alpha_low --value 0.7
+```
+
+On chain, `alpha_low` and [`alpha_high`](/docs/hyperparameters/alpha-high) live in one storage value set by a single `sudo_set_alpha_values` call. The CLI reads the current pair and resubmits it with only `alpha_low` changed, so the other side is preserved.
+
+## Related
+
+[`alpha_high`](/docs/hyperparameters/alpha-high), [`alpha_sigmoid_steepness`](/docs/hyperparameters/alpha-sigmoid-steepness), [`liquid_alpha_enabled`](/docs/hyperparameters/liquid-alpha-enabled), [`bonds_moving_avg`](/docs/hyperparameters/bonds-moving-avg), [`yuma3_enabled`](/docs/hyperparameters/yuma3-enabled)

docs/hyperparameters/alpha-sigmoid-steepness.mdx

@@ -0,0 +1,37 @@
+---
+title: alpha_sigmoid_steepness
+description: Slope of the liquid-alpha sigmoid mapping consensus deviation to the bonds EMA rate; negative values (root only) invert the curve.
+---
+
+`alpha_sigmoid_steepness` shapes the transition between [`alpha_low`](/docs/hyperparameters/alpha-low) and [`alpha_high`](/docs/hyperparameters/alpha-high) when [`liquid_alpha_enabled`](/docs/hyperparameters/liquid-alpha-enabled) is on. Subnet owners tune it to make the liquid-alpha response gradual (small values) or nearly a step function (large values); validators care because it decides how much deviation from consensus is needed before their bonds start moving at the fast rate.
+
+## How it works
+
+For each validator–miner pair, `alpha_sigmoid` (`pallets/subtensor/src/epoch/run_epoch.rs`) computes
+
+```
+sigmoid = 1 / (1 + e^(-(steepness / 100) × (diff − 0.5)))
+alpha   = alpha_low + sigmoid × (alpha_high − alpha_low)
+```
+
+where `diff` is the pair's deviation from consensus, clamped to 0..1. The stored i16 is divided by 100, so the default 1000 gives an effective slope of 10: alpha sits near `alpha_low` for small deviations, crosses the midpoint at `diff = 0.5`, and saturates near `alpha_high` beyond it. Steepness near 0 flattens the curve to the midpoint of the range; very large values approximate a hard threshold at 0.5.
+
+Negative steepness inverts the curve — consensus-aligned pairs get the fast rate — and `sudo_set_alpha_sigmoid_steepness` in `pallets/admin-utils/src/lib.rs` reserves that to root: a subnet owner passing a negative value gets `NegativeSigmoidSteepness`.
+
+<HyperparamLiquidAlpha focus="alpha_sigmoid_steepness" />
+
+## Reading and setting
+
+```
+btcli sudo get --netuid N --name alpha_sigmoid_steepness
+```
+
+Plain integer (i16); owners may set 0 or positive values:
+
+```
+btcli sudo set --netuid N --name alpha_sigmoid_steepness --value 1000
+```
+
+## Related
+
+[`alpha_low`](/docs/hyperparameters/alpha-low), [`alpha_high`](/docs/hyperparameters/alpha-high), [`liquid_alpha_enabled`](/docs/hyperparameters/liquid-alpha-enabled), [`yuma3_enabled`](/docs/hyperparameters/yuma3-enabled)

docs/hyperparameters/bonds-moving-avg.mdx

@@ -0,0 +1,38 @@
+---
+title: bonds_moving_avg
+description: Smoothing factor for the validator bonds EMA — higher retains more of past bonds each epoch.
+---
+
+`bonds_moving_avg` controls how slowly validator bonds track a validator's current weights. Subnet owners tune it to decide how long validators must hold a position before their bonds (and thus dividends) catch up; validators care because it sets how fast early, correct weight calls pay off.
+
+## How it works
+
+Bonds are an exponential moving average over each validator–miner pair. Every epoch the chain computes
+
+```
+B(t) = alpha × ΔB + (1 − alpha) × B(t−1)
+```
+
+where `alpha = 1 − bonds_moving_avg / 1,000,000` (`compute_ema_bonds_normal` in `pallets/subtensor/src/epoch/run_epoch.rs`). The default 900,000 gives alpha = 0.1: each epoch a bond moves 10% of the way toward the validator's instant bond. Higher values mean stickier bonds and slower dividend response; lower values make bonds chase current weights quickly, weakening the reward for early conviction.
+
+The flat rate applies on the classic consensus path, and also on the [`yuma3_enabled`](/docs/hyperparameters/yuma3-enabled) path whenever [`liquid_alpha_enabled`](/docs/hyperparameters/liquid-alpha-enabled) is off (`compute_disabled_liquid_alpha`). With liquid alpha on, the per-pair sigmoid rate replaces it entirely.
+
+Subnet owners can set at most 975,000 (`BondsMovingAverageMaxReached` in `pallets/admin-utils/src/lib.rs`); only root can go higher.
+
+<HyperparamLiquidAlpha focus="bonds_moving_avg" />
+
+## Reading and setting
+
+```
+btcli sudo get --netuid N --name bonds_moving_avg
+```
+
+Stored over 1,000,000 (900000 = 0.9). The set command accepts either the raw integer or the human fraction with a decimal point:
+
+```
+btcli sudo set --netuid N --name bonds_moving_avg --value 0.9
+```
+
+## Related
+
+[`liquid_alpha_enabled`](/docs/hyperparameters/liquid-alpha-enabled), [`alpha_low`](/docs/hyperparameters/alpha-low), [`alpha_high`](/docs/hyperparameters/alpha-high), [`bonds_penalty`](/docs/hyperparameters/bonds-penalty), [`yuma3_enabled`](/docs/hyperparameters/yuma3-enabled)

docs/hyperparameters/bonds-penalty.mdx

@@ -0,0 +1,35 @@
+---
+title: bonds_penalty
+description: How much out-of-consensus weight is excluded from bond accrual, from none (0) to full clipping (1).
+---
+
+`bonds_penalty` decides whether validators build bonds from their raw weights or only from the consensus-clipped portion. Subnet owners use it to punish (or tolerate) weight-setting that deviates from the stake-weighted consensus; validators care because it determines whether an out-of-consensus bet still accrues bonds.
+
+## How it works
+
+Before the bonds EMA runs, the epoch interpolates between raw and clipped weight matrices (`pallets/subtensor/src/epoch/run_epoch.rs`, around the "Bonds and Dividends" step):
+
+```
+weights_for_bonds = (1 − penalty) × weights + penalty × clipped_weights
+```
+
+- `bonds_penalty = 0`: bonds accrue from raw weights — deviating from consensus costs nothing in bond terms.
+- `bonds_penalty = 1` (the default, stored as 65535): bonds accrue only from consensus-clipped weights, so any weight above the stake-weighted median is ignored for bonding.
+
+Values in between blend the two. The interpolated matrix feeds the bonds EMA on both the classic path and the [`yuma3_enabled`](/docs/hyperparameters/yuma3-enabled) path, so the penalty applies regardless of which consensus variant is active. See the [Yuma Consensus overview](/docs/concepts/emissions#yuma-consensus) for where this sits in the epoch.
+
+## Reading and setting
+
+```
+btcli sudo get --netuid N --name bonds_penalty
+```
+
+Stored as u16 (65535 = 1.0, full penalty). The set command accepts the raw integer or a 0..1 fraction with a decimal point:
+
+```
+btcli sudo set --netuid N --name bonds_penalty --value 1.0
+```
+
+## Related
+
+[`bonds_moving_avg`](/docs/hyperparameters/bonds-moving-avg), [`bonds_reset_enabled`](/docs/hyperparameters/bonds-reset-enabled), [`liquid_alpha_enabled`](/docs/hyperparameters/liquid-alpha-enabled), [`yuma3_enabled`](/docs/hyperparameters/yuma3-enabled)