diff --git a/docs/keys/coldkey-swap.md b/docs/keys/coldkey-swap.md
index 24f4e7a5..5ad7998a 100644
--- a/docs/keys/coldkey-swap.md
+++ b/docs/keys/coldkey-swap.md
@@ -524,3 +524,12 @@ print(response)
A coldkey swap announcement can only be cleared after the [ColdkeySwapReannouncementDelay](https://github.com/opentensor/subtensor/blob/devnet-ready/runtime/src/lib.rs#:~:text=pub%20const%20InitialColdkeySwapReannouncementDelay) period has elapsed. By default, this is 7,200 blocks (~1 day) after the initial announcement delay expires. The announcement must also not be under dispute to be cleared.
:::
+
+## Conviction locks and coldkey swap
+
+If the coldkey being swapped has [conviction locks](../staking-and-delegation/conviction-staking.md) on any subnet, the swap behavior depends on the destination coldkey's lock state:
+
+- **Destination coldkey has active locked mass on any subnet**: the swap is **rejected**. The destination coldkey must have no active locks before the swap can proceed.
+- **Destination coldkey has only expired or zero-mass locks**: the swap proceeds. The source coldkey's locks are transferred to the destination coldkey and consolidated with any existing (zero-mass) lock records there.
+
+Locked mass and conviction are preserved through the swap — the lock follows the coldkey identity to the new key pair.
diff --git a/docs/staking-and-delegation/conviction-staking.md b/docs/staking-and-delegation/conviction-staking.md
new file mode 100644
index 00000000..034331b9
--- /dev/null
+++ b/docs/staking-and-delegation/conviction-staking.md
@@ -0,0 +1,285 @@
+---
+title: "Conviction and locked stake"
+---
+
+# Conviction and locked stake
+
+The locked stake features lets coldkey holders lock alpha stake to a specific hotkey on a subnet. Locked stake builds **conviction**, a score that grows over time toward the locked amount. Conviction provides a public, on-chain signal of long-term commitment that cannot be silently reversed.
+
+Conviction provides information about subnet owners and other large investors in a subnet. A subnet owner whose alpha is locked has made a cryptographic commitment: unwinding a large position requires calling `unlock_stake` and then waiting through an exponential decay period before the stake can be withdrawn. This gives other stakers advance warning before any large exit completes.
+
+:::note Testnet launch
+Conviction staking is live on testnet (spec version 403) as of May 2026 and is tentatively scheduled for mainnet on May 13, 2026.
+:::
+
+## The stake lock mechanism
+
+Locking stake binds a specific amount of a coldkey's staked alpha, on a subnet to a specific delegate (stake recipient) hotkey. The lock enforces one invariant:
+
+> **Total alpha staked by the coldkey on that subnet ≥ locked amount**
+
+Everything above the locked amount is freely unstakable. The coldkey can also continue to stake additional alpha at any time: the lock only blocks the staked balance from dropping below the locked amount.
+
+Locks are **indefinite**: they persist until the coldkey explicitly calls `unlock_stake`. There is no expiry and no need to periodically renew a lock.
+
+One lock per coldkey per subnet is enforced. If a lock already exists for a coldkey on a subnet, additional `lock_stake` calls top up the locked amount (provided the hotkey matches the existing lock).
+
+## Conviction
+
+The conviction score grows over time, from zero toward the locked amount. It therefore provides a combined signal of how long _and_ how much a staker had invested in the subnet.
+
+Growth follow an exponential curve:
+
+$$c_1 = m - (m - c_0) \cdot e^{-\Delta t / \tau}$$
+
+where:
+
+- $c_0$: conviction at last update
+- $c_1$: conviction now
+- $m$: locked mass (alpha units)
+- $\Delta t$: blocks elapsed since last update
+- $\tau$: maturity time constant: **648,000 blocks (≈ 90 days)**
+
+## Dynamics locking and unlocking
+
+When someone locks stake, their conviction increases over time, up to the locked amount. When someone unlocks stake, their available unlocked stake increases over time up to the amount the just unlocked.
+
+The same formula governs both curves, only the time constant differs. The lifecycle graph below shows how they interact in sequence:
+
+**Conviction growth**: `f(t) = 1 − exp(−t / τ)`, τ = 648,000 blocks ≈ 90 days. Dot marks one time constant (63.2% of max).
+**Unlock availability**: `f(t) = 1 − exp(−t / τ)`, τ = 216,000 blocks ≈ 30 days. Dot marks one time constant (63.2% of unlocked amount available). Both x-axes span 3τ.
+
+
+
+
+
+
+ See how it's calculated!
+
+_Scenario: lock 100α at day 0; call `unlock_stake(50α)` at day 90. Conviction (blue) drops instantly by the unlocked amount and then rebuilds toward the new lower ceiling. Unlocked α (orange) becomes gradually withdrawable over the following ~30 days._
+
+To understand the design intent, notice that the math is about _closing a gap_, either gap between locked amount and eventual conviction, or unlocked amount and available amount.
+
+If we re-arrange the equation to focus on the gap:
+
+```
+gap = m - c0 (distance between current conviction and max)
+c1 = m - gap × exp(-dt/τ)
+```
+
+`exp(-dt/τ)` is a number between 0 and 1, the fraction of the gap that remains after `dt` blocks.
+
+So:
+
+- `dt = 0` → `exp(0) = 1` → gap unchanged → c1 = c0 ✓
+- `dt = τ` (90 days) → `exp(-1) ≈ 0.368` → 36.8% of the gap remains → you've closed ~63% of it
+- `dt → ∞` → `exp(-∞) = 0` → gap gone → c1 = m ✓
+
+Starting from c0 = 0 (fresh lock of 100 alpha):
+
+```
+gap = 100 - 0 = 100
+at 90 days: c1 = 100 - 100 × 0.368 = 63.2
+at 180 days: c1 = 100 - 100 × 0.135 = 86.5
+```
+
+Conviction is always closing in on `m`, getting closer every block, never quite arriving.
+
+**Example:** Lock 100 alpha at block 0 with no prior lock.
+
+| Elapsed time | Conviction |
+| ------------ | ---------- |
+| 0 days | 0 |
+| 30 days | ≈ 28.3 |
+| 62 days | ≈ 50.0 |
+| 90 days | ≈ 63.2 |
+| 180 days | ≈ 86.5 |
+| 270 days | ≈ 95.0 |
+
+Maximum conviction equals the locked mass. Topping up an existing lock adds to locked mass immediately; conviction continues growing from its current value toward the new (higher) maximum.
+
+
+
+## Extrinsics
+
+### `lock_stake`
+
+```
+api.tx.subtensorModule.lockStake(hotkey, netuid, amount)
+```
+
+Locks `amount` alpha from the coldkey's stake on `netuid` to `hotkey`.
+
+- If no lock exists for this coldkey on `netuid`, a new lock is created with conviction 0.
+- If a lock already exists, `amount` is added to the locked mass. The hotkey must match the existing lock. Use `move_lock` first if switching hotkeys.
+- `amount` must not exceed the coldkey's available (unlocked) alpha on the subnet.
+
+**Errors:**
+
+- `InsufficientStakeForLock`: available alpha is less than `amount`
+- `LockHotkeyMismatch`: a lock exists for a different hotkey on this subnet
+- `AmountTooLow`: amount is zero
+
+**Event emitted:** `StakeLocked { coldkey, hotkey, netuid, amount }`
+
+### `unlock_stake`
+
+```
+api.tx.subtensorModule.unlockStake(netuid, amount)
+```
+
+Begins the process of unlocking `amount` alpha from the coldkey's existing lock on `netuid`.
+
+- Immediately reduces locked mass by `amount` and conviction by `amount`.
+- The unlocked amount enters an exponential decay period. It becomes gradually withdrawable over time with a time constant of **216,000 blocks (≈ 30 days)**: roughly half is available after 30 days, ~86% after 60 days, and so on.
+- While stake is in the unlocking period, it **cannot be unstaked or re-locked**. The available stake formula excludes both locked and unlocking amounts.
+
+**Errors:**
+
+- `UnlockAmountTooHigh`: amount exceeds current locked mass
+
+**Event emitted:** `StakeUnlocked { coldkey, hotkey, netuid, amount }`
+
+:::note Unlock transactions are public
+Calling `unlock_stake` emits the `StakeUnlocked` event on-chain immediately, before any stake is actually withdrawable. This is by design: the unlock period exists specifically so that other stakers can observe the signal and act accordingly. An unlock by a subnet owner should be interpreted as a potential intent to reduce their position, not a completed exit.
+:::
+
+### `move_lock`
+
+```
+api.tx.subtensorModule.moveLock(destination_hotkey, netuid)
+```
+
+Reassigns the coldkey's existing lock on `netuid` from its current hotkey to `destination_hotkey`.
+
+- **Conviction resets to zero** when the old and new hotkeys are owned by different coldkeys.
+- Conviction is **preserved** when both hotkeys are owned by the same coldkey (moving between your own hotkeys).
+- The locked mass and unlocking mass are preserved in both cases.
+
+This gives the previous hotkey's stakers a window to react before conviction rebuilds on the new hotkey.
+
+**Errors:**
+
+- `NoExistingLock`: no lock exists for this coldkey on the subnet
+
+**Event emitted:** `LockMoved { coldkey, origin_hotkey, destination_hotkey, netuid }`
+
+:::note Locking does not affect emissions
+Locking stake does not change the amount of emissions you receive. Emissions are determined by stake weight and consensus participation. Conviction is a governance/signaling mechanism only.
+:::
+
+## Subnet owner auto-locking
+
+When a subnet owner receives their distribution cut each epoch, **it is automatically locked** to the subnet owner's hotkey. If the owner already has a lock, the auto-lock tops it up using the existing lock's hotkey. If no lock exists, the auto-lock targets the subnet owner's hotkey.
+
+This means subnet owners start accumulating locked alpha and conviction from the moment they own a subnet. Unlocking requires a conscious `unlock_stake` transaction followed by the 30-day unlock delay.
+
+## Key swap behavior
+
+**Hotkey swap (system-level):** When a hotkey is swapped via `btcli wallet swap-hotkey`, all locks targeting the old hotkey are transferred to the new hotkey. Conviction is **not** reset, because the same coldkey owns both hotkeys.
+
+**Coldkey swap:** A coldkey swap fails if the destination coldkey already has **active locked mass** on any subnet. The swap succeeds if the destination coldkey only has expired or zero-mass locks.
+
+## Transferring locked stake
+
+When stake is moved to another coldkey **within the same subnet**, lock obligations follow the alpha proportionally. The runtime resolves how much of the transfer carries lock state:
+
+1. **Freely available alpha transfers first**: alpha above the locked + unlocking amount moves with no lock implications.
+2. **Unlocking alpha is drawn next**: if the transfer exceeds freely available alpha, the shortfall comes from the source's unlocking mass. That amount arrives at the destination still in its decay period.
+3. **Locked alpha is drawn last**: if the transfer still exceeds what's available, the remainder comes from locked mass. Conviction transfers proportionally. This step **fails with `LockHotkeyMismatch`** if the destination coldkey already has a lock pointing at a different hotkey.
+
+**Cross-subnet moves are different**: moving stake between subnets goes through unstake → TAO transfer → restake, which must satisfy `ensure_available_stake`. You cannot drag locked or unlocking alpha across subnets.
+
+## Querying conviction
+
+Two runtime API calls expose conviction state on-chain:
+
+| Method | Returns |
+| --------------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| `get_hotkey_conviction(hotkey, netuid)` | Current total conviction for `hotkey` on `netuid`, summed over all coldkeys that have locked to it |
+| `get_most_convicted_hotkey_on_subnet(netuid)` | The hotkey with the highest conviction on `netuid`, or `None` if no locks exist |
+
+Conviction is a rolling value, so querying at different blocks yields different results as time passes and the exponential grows.
+
+Explorer tools like [tao.app](https://www.tao.app) and [taostats.io](https://taostats.io/) are expected to surface per-subnet lock state, including subnet owner lock percentage and conviction scores, providing investors with at-a-glance commitment signals.
+
+## Storage
+
+Lock state is stored in two maps:
+
+- `Lock[(coldkey, netuid, hotkey)]`: per-coldkey lock record containing locked mass, unlocking mass, conviction score, and last update block
+- `HotkeyLock[(netuid, hotkey)]`: aggregate lock totals per hotkey (used for conviction queries without iterating all coldkeys)
+
+The maturity time constant (`MaturityRate`) and unlock time constant (`UnlockRate`) are configurable runtime storage values, defaulting to 648,000 and 216,000 blocks respectively. These values can be adjusted by governance. The unlock and maturity windows are key parameters in the mechanism's attack surface, and tuning them changes how quickly conviction can build or unwind.
+
+## Appendix: implementation
+
+The conviction formula is closed-form with no iteration or history, because the runtime stores only a checkpoint at the last mutation and evaluates forward on demand.
+
+**What's stored** (`LockState`, `lib.rs`):
+
+```rust
+pub struct LockState {
+ pub locked_mass: AlphaBalance, // constant between user actions
+ pub unlocked_mass: AlphaBalance, // amount pending the 30-day decay
+ pub conviction: U64F64, // c0: conviction at last_update
+ pub last_update: u64, // block number of last write
+}
+```
+
+No history. Just a snapshot at a single block. The four fields are sufficient to reconstruct conviction at any future block.
+
+**The formula** (`calculate_matured_values`, `lock.rs`):
+
+```rust
+let decay = Self::exp_decay(dt, tau); // exp(-dt/tau)
+let new_conviction =
+ mass_fixed.saturating_sub(
+ decay.saturating_mul(mass_fixed.saturating_sub(conviction))
+ );
+// = m - exp(-dt/tau) * (m - c0)
+```
+
+One call, no loop. This is the same equation shown in the [Conviction](#conviction) section above.
+
+**On-demand evaluation** (`roll_forward_lock`, `lock.rs`):
+
+```rust
+pub fn roll_forward_lock(lock: LockState, now: u64) -> LockState {
+ let dt = now.saturating_sub(lock.last_update);
+ let (new_unlocked_mass, new_conviction) =
+ Self::calculate_matured_values(
+ lock.locked_mass, lock.unlocked_mass, lock.conviction, dt,
+ );
+ LockState {
+ locked_mass: lock.locked_mass,
+ unlocked_mass: new_unlocked_mass,
+ conviction: new_conviction,
+ last_update: now,
+ }
+}
+```
+
+**The mutation pattern** (from `do_lock_stake`, `lock.rs`):
+
+```rust
+// Roll to current block before modifying
+let lock = Self::roll_forward_lock(existing, now);
+let new_locked = lock.locked_mass.saturating_add(amount);
+Self::insert_lock_state(coldkey, netuid, hotkey, LockState {
+ locked_mass: new_locked,
+ unlocked_mass: lock.unlocked_mass,
+ conviction: lock.conviction, // current conviction becomes new c0
+ last_update: now, // checkpoint resets to now
+});
+```
+
+Every mutation (`lock_stake`, `unlock_stake`, `move_lock`) calls `roll_forward_lock` first. This advances conviction to the current block and writes it as the new `c0`. From that point, the stored `(c0, m, last_update)` triple is sufficient to evaluate conviction at any future block without needing history.
+
+Conviction is therefore a pure function of elapsed time between mutations. Given the stored checkpoint, conviction at any future block `b` is:
+
+```
+c(b) = m - (m - c0) × exp(-(b - last_update) / τ)
+```
+
+This is exactly what `get_hotkey_conviction` evaluates when queried. You can also project forward: if no mutations occur between now and block `b`, the formula gives the exact future conviction. A mutation (top-up, partial unlock, `move_lock`) resets `c0` and `last_update` to a new checkpoint, restarting the forecast from there.
diff --git a/docs/staking-and-delegation/delegation.md b/docs/staking-and-delegation/delegation.md
index 94d02c79..2081a8f7 100644
--- a/docs/staking-and-delegation/delegation.md
+++ b/docs/staking-and-delegation/delegation.md
@@ -56,6 +56,8 @@ As a TAO holder, you will stake to a validator’s hotkey on a specific subnet.
**Price protection**: Bittensor provides built-in price protection mechanisms to prevent unfavorable unstaking transactions. You can set tolerance limits and enable partial execution. See [Price Protection When Staking](../learn/price-protection.md) for more information.
**Transaction fees**: Unstaking operations incur blockchain transaction fees. These fees are recycled back into the TAO emission pool. See [Transaction Fees in Bittensor](../learn/fees.md).
+
+**Conviction locks**: If you or the previous owner of your stake has called `lock_stake` on a subnet, a portion of your alpha may be locked and cannot be unstaked immediately. Locked stake must first be unlocked via `unlock_stake`, after which a ≈30-day exponential decay period applies before the stake is fully withdrawable. See [Conviction Staking](./conviction-staking.md) for details.
:::
### Unstaking methods
diff --git a/docs/subnets/create-a-subnet.md b/docs/subnets/create-a-subnet.md
index 81d7da78..c34a42ba 100644
--- a/docs/subnets/create-a-subnet.md
+++ b/docs/subnets/create-a-subnet.md
@@ -115,6 +115,13 @@ Output:
Newly created subnets are inactive by default and do not begin emitting until they have been started by the subnet owner. This allows subnet owners to configure the subnet, register and activate validators, and onboard miners before activation.
:::
+:::note Subnet owner alpha is automatically locked
+
+The subnet owner's share of each epoch's emissions is **automatically locked** via [conviction staking](../staking-and-delegation/conviction-staking.md). Locked alpha accrues conviction over time and cannot be unstaked immediately — unlocking requires an explicit `unlock_stake` transaction followed by a ≈30-day decay period.
+
+This is intentional: it gives investors a public, cryptographic signal of the owner's commitment. Tools like [tao.app](https://www.tao.app) and community dashboards are expected to surface per-subnet lock and conviction data.
+:::
+
### Start the subnet
Use the following command to start the subnet:
diff --git a/docs/subtensor-api/events.md b/docs/subtensor-api/events.md
index 0fe35546..83fd5b3f 100644
--- a/docs/subtensor-api/events.md
+++ b/docs/subtensor-api/events.md
@@ -957,6 +957,11 @@ Generated from a live snapshot of the Subtensor runtime on **2026-04-24**. Conne
- **interface**: `api.events.subtensorModule.KappaSet`
- **summary**: Kappa is set for a subnet.
+### `LockMoved(coldkey: AccountId, origin_hotkey: AccountId, destination_hotkey: AccountId, netuid: NetUid)`
+
+- **interface**: `api.events.subtensorModule.LockMoved`
+- **summary**: A conviction lock has been moved from one hotkey to another. Emitted by `move_lock`. Conviction is reset to zero when the hotkeys have different owners; preserved when the same coldkey owns both.
+
### `MaxAllowedUidsSet(NetUid, u16)`
- **interface**: `api.events.subtensorModule.MaxAllowedUidsSet`
@@ -1145,6 +1150,11 @@ Generated from a live snapshot of the Subtensor runtime on **2026-04-24**. Conne
- **interface**: `api.events.subtensorModule.StakeAdded`
- **summary**: stake has been transferred from the a coldkey account onto the hotkey staking account.
+### `StakeLocked(coldkey: AccountId, hotkey: AccountId, netuid: NetUid, amount: AlphaBalance)`
+
+- **interface**: `api.events.subtensorModule.StakeLocked`
+- **summary**: Alpha stake has been locked to a hotkey on a subnet. Emitted by `lock_stake` and by the automatic owner lock on each epoch's distribution.
+
### `StakeMoved(AccountId, AccountId, NetUid, AccountId, NetUid, TaoBalance)`
- **interface**: `api.events.subtensorModule.StakeMoved`
@@ -1178,6 +1188,11 @@ Generated from a live snapshot of the Subtensor runtime on **2026-04-24**. Conne
(origin_coldkey, destination_coldkey, hotkey, origin_netuid, destination_netuid, amount)
+### `StakeUnlocked(coldkey: AccountId, hotkey: AccountId, netuid: NetUid, amount: AlphaBalance)`
+
+- **interface**: `api.events.subtensorModule.StakeUnlocked`
+- **summary**: Alpha stake has been moved from the locked state into the unlock decay period. Emitted by `unlock_stake`. The stake is not immediately available — it becomes gradually withdrawable over ≈30 days.
+
### `StartCallDelaySet(u64)`
- **interface**: `api.events.subtensorModule.StartCallDelaySet`
diff --git a/docs/subtensor-api/extrinsics.md b/docs/subtensor-api/extrinsics.md
index 45216e46..e3bc5761 100644
--- a/docs/subtensor-api/extrinsics.md
+++ b/docs/subtensor-api/extrinsics.md
@@ -2118,6 +2118,26 @@ Generated from a live snapshot of the Subtensor runtime on **2026-04-24**. Conne
- `NonAssociatedColdKey` — The hotkey we are delegating is not owned by the calling coldkey.
- `DelegateTakeTooHigh` — The delegate is setting a take which is not greater than the previous.
+### `lockStake(hotkey: AccountId, netuid: NetUid, amount: AlphaBalance)`
+
+- **interface**: `api.tx.subtensorModule.lockStake`
+- **summary**: Locks `amount` alpha from the signing coldkey's stake on `netuid` to `hotkey`, building conviction over time. If no lock exists for this coldkey on `netuid`, a new lock is created with conviction 0. If a lock already exists, `amount` is added to the locked mass (the hotkey must match). The lock is indefinite — it persists until `unlock_stake` is called. See [Conviction Staking](../staking-and-delegation/conviction-staking.md) for full mechanics.
+
+ **Errors:**
+
+ - `InsufficientStakeForLock` — Available (unlocked) alpha is less than `amount`.
+ - `LockHotkeyMismatch` — A lock already exists for a different hotkey on this subnet.
+ - `AmountTooLow` — Amount is zero.
+
+### `moveLock(destination_hotkey: AccountId, netuid: NetUid)`
+
+- **interface**: `api.tx.subtensorModule.moveLock`
+- **summary**: Moves the signing coldkey's existing lock on `netuid` from its current hotkey to `destination_hotkey`. The locked and unlocking mass are preserved. Conviction is reset to zero if the old and destination hotkeys are owned by different coldkeys; conviction is preserved if both are owned by the same coldkey. See [Conviction Staking](../staking-and-delegation/conviction-staking.md) for full mechanics.
+
+ **Errors:**
+
+ - `NoExistingLock` — No lock exists for this coldkey on the subnet.
+
### `moveStake(origin_hotkey: AccountId, destination_hotkey: AccountId, origin_netuid: NetUid, destination_netuid: NetUid, alpha_amount: AlphaBalance)`
- **interface**: `api.tx.subtensorModule.moveStake`
@@ -2960,6 +2980,15 @@ Generated from a live snapshot of the Subtensor runtime on **2026-04-24**. Conne
Will charge based on the weight even if the hotkey is already associated with a coldkey.
+### `unlockStake(netuid: NetUid, amount: AlphaBalance)`
+
+- **interface**: `api.tx.subtensorModule.unlockStake`
+- **summary**: Begins unlocking `amount` alpha from the signing coldkey's existing lock on `netuid`. The locked mass is reduced by `amount` immediately and the same amount enters an exponential unlock period (time constant ≈ 30 days). Stake in the unlock period cannot be unstaked or re-locked until it has decayed sufficiently. See [Conviction Staking](../staking-and-delegation/conviction-staking.md) for the decay formula.
+
+ **Errors:**
+
+ - `UnlockAmountTooHigh` — Amount exceeds the current locked mass.
+
### `unstakeAll(hotkey: AccountId)`
- **interface**: `api.tx.subtensorModule.unstakeAll`
diff --git a/docs/subtensor-api/rpc.md b/docs/subtensor-api/rpc.md
index 14685631..b3a11328 100644
--- a/docs/subtensor-api/rpc.md
+++ b/docs/subtensor-api/rpc.md
@@ -15,9 +15,24 @@ Generated from a live snapshot of the Subtensor runtime on **2026-04-24**. Conne
- **[payment](#payment)**
- **[rpc](#rpc)**
- **[state](#state)**
+- **[subtensorModule (Runtime API)](#subtensormodule-runtime-api)**
- **[system](#system)**
- **[web3](#web3)**
+## `subtensorModule` (Runtime API)
+
+These methods are exposed via the Subtensor **Runtime API** and are accessed through `api.call.subtensorModuleRuntimeApi.*` rather than `api.rpc.*`.
+
+### `getHotkeyConviction(hotkey: AccountId32, netuid: NetUid)`: `U64F64`
+
+- **interface**: `api.call.subtensorModuleRuntimeApi.getHotkeyConviction`
+- **summary**: Returns the current total conviction for `hotkey` on `netuid`, aggregated over all coldkeys that have locked to this hotkey. Conviction grows exponentially toward the total locked mass with a time constant of ≈90 days. See [Conviction Staking](../staking-and-delegation/conviction-staking.md).
+
+### `getMostConvictedHotkeyOnSubnet(netuid: NetUid)`: `Option`
+
+- **interface**: `api.call.subtensorModuleRuntimeApi.getMostConvictedHotkeyOnSubnet`
+- **summary**: Returns the hotkey with the highest total conviction on `netuid`, or `None` if no locks exist on the subnet. Conviction is evaluated at the current block (rolled forward lazily). See [Conviction Staking](../staking-and-delegation/conviction-staking.md).
+
## `author`
### `hasKey(publicKey: Bytes, keyType: Text)`: `bool`
diff --git a/scripts/gen_conviction_graph.py b/scripts/gen_conviction_graph.py
new file mode 100644
index 00000000..89b9a115
--- /dev/null
+++ b/scripts/gen_conviction_graph.py
@@ -0,0 +1,138 @@
+"""
+Generate conviction-curve.svg for the conviction staking docs page.
+
+Two curves, both normalized to fraction of maximum (0→1):
+ - Conviction growth: f(t) = 1 - exp(-t / 90) τ = 648,000 blocks ≈ 90 days
+ - Unlock availability: f(t) = 1 - exp(-t / 30) τ = 216,000 blocks ≈ 30 days
+
+Output: ../static/img/conviction-curve.svg
+"""
+import math
+import os
+
+# ── layout ──────────────────────────────────────────────────────────────────
+W, H = 720, 400
+ML, MR, MT, MB = 65, 30, 45, 55 # margins
+PW = W - ML - MR # plot width = 625
+PH = H - MT - MB # plot height = 300
+
+X_MAX = 270 # days on x-axis
+Y_MAX = 1.0
+
+def px(day):
+ return ML + (day / X_MAX) * PW
+
+def py(frac):
+ return MT + PH - (frac / Y_MAX) * PH
+
+# ── curves ───────────────────────────────────────────────────────────────────
+N = 800
+
+def conviction(t):
+ return 1 - math.exp(-t / 90)
+
+def unlock_access(t):
+ return 1 - math.exp(-t / 30)
+
+pts_conv = [(i * X_MAX / N, conviction(i * X_MAX / N)) for i in range(N + 1)]
+pts_unlock = [(i * X_MAX / N, unlock_access(i * X_MAX / N)) for i in range(N + 1)]
+
+def polyline(pts):
+ return " ".join(f"{px(x):.2f},{py(y):.2f}" for x, y in pts)
+
+# ── colours ──────────────────────────────────────────────────────────────────
+BLUE = "#3b82f6"
+ORANGE = "#f97316"
+AXIS = "#374151"
+GRID = "#e5e7eb"
+TEXT = "#111827"
+MUTED = "#6b7280"
+
+# ── build ────────────────────────────────────────────────────────────────────
+o = []
+
+def l(s):
+ o.append(s)
+
+l(f'')
+
+# ── write ─────────────────────────────────────────────────────────────────────
+out = os.path.join(os.path.dirname(__file__), "../static/img/conviction-curve.svg")
+with open(out, "w") as f:
+ f.write("\n".join(o))
+
+print(f"Written: {os.path.abspath(out)}")
diff --git a/scripts/gen_conviction_lifecycle.py b/scripts/gen_conviction_lifecycle.py
new file mode 100644
index 00000000..cb96bb0f
--- /dev/null
+++ b/scripts/gen_conviction_lifecycle.py
@@ -0,0 +1,189 @@
+"""
+Generate conviction-lifecycle.svg — a single sequential timeline showing:
+
+ Scenario: lock 100α at day 0, call unlock_stake(50α) at day 90.
+
+ Phase 1 (day 0-90):
+ - Conviction grows from 0 toward 100α ceiling: c(t) = 100·(1−exp(−t/90))
+ - At day 90, conviction ≈ 63.2α
+
+ Unlock event (day 90):
+ - locked_mass: 100 → 50
+ - conviction: 63.2 → 13.2 (drops by 50, the unlocked amount)
+ - unlocked_mass: 0 → 50 (enters 30-day decay period)
+
+ Phase 2 (day 90-300):
+ - Conviction rebuilds from 13.2 toward new ceiling 50:
+ c(t) = 50 − (50−13.2)·exp(−(t−90)/90)
+ - Unlocked α becomes available:
+ available(t) = 50·(1−exp(−(t−90)/30))
+
+Output: ../static/img/conviction-lifecycle.svg
+"""
+import math, os
+
+# ── scenario constants ────────────────────────────────────────────────────────
+LOCK_AMOUNT = 100 # initial lock
+UNLOCK_AMOUNT = 50 # amount unlocked at UNLOCK_DAY
+UNLOCK_DAY = 90
+TAU_CONV = 90 # conviction τ (days)
+TAU_UNLOCK = 30 # unlock τ (days)
+X_MAX = 300
+
+c_at_unlock = LOCK_AMOUNT * (1 - math.exp(-UNLOCK_DAY / TAU_CONV)) # ≈ 63.2
+c_after_unlock = c_at_unlock - UNLOCK_AMOUNT # ≈ 13.2
+locked_after = LOCK_AMOUNT - UNLOCK_AMOUNT # = 50
+
+def conviction(t):
+ if t <= UNLOCK_DAY:
+ return LOCK_AMOUNT * (1 - math.exp(-t / TAU_CONV))
+ else:
+ dt = t - UNLOCK_DAY
+ return locked_after - (locked_after - c_after_unlock) * math.exp(-dt / TAU_CONV)
+
+def unlock_avail(t):
+ if t < UNLOCK_DAY:
+ return 0
+ dt = t - UNLOCK_DAY
+ return UNLOCK_AMOUNT * (1 - math.exp(-dt / TAU_UNLOCK))
+
+# ── layout ───────────────────────────────────────────────────────────────────
+W, H = 720, 400
+MT, MB = 52, 60
+ML, MR = 65, 28
+PW = W - ML - MR # 627
+PH = H - MT - MB # 288
+Y_MAX = 110 # a bit above 100 for headroom
+
+def px(day): return ML + (day / X_MAX) * PW
+def py(alpha): return MT + PH * (1 - alpha / Y_MAX)
+
+N = 800
+conv_pts = [(t, conviction(t)) for t in (i * X_MAX / N for i in range(N + 1))]
+unlock_pts = [(t, unlock_avail(t)) for t in (i * X_MAX / N for i in range(N + 1))]
+
+def polyline(pts):
+ return " ".join(f"{px(x):.2f},{py(y):.2f}" for x, y in pts)
+
+BLUE = "#3b82f6"
+ORANGE = "#f97316"
+AXIS = "#374151"
+GRID = "#e5e7eb"
+TEXT = "#111827"
+MUTED = "#6b7280"
+RED = "#ef4444"
+
+o = []
+def l(s): o.append(s)
+
+l(f'')
+
+out = os.path.join(os.path.dirname(__file__), "../static/img/conviction-lifecycle.svg")
+with open(out, "w") as f:
+ f.write("\n".join(o))
+print(f"Written: {os.path.abspath(out)}")
diff --git a/scripts/gen_conviction_panels.py b/scripts/gen_conviction_panels.py
new file mode 100644
index 00000000..f94558d2
--- /dev/null
+++ b/scripts/gen_conviction_panels.py
@@ -0,0 +1,134 @@
+"""
+Generate conviction-panels.svg — two clean side-by-side charts:
+ Left: Conviction growth f(t) = 1 − exp(−t / 90) τ = 90 days
+ Right: Unlock availability f(t) = 1 − exp(−t / 30) τ = 30 days
+
+Both y-axes run 0→1 (fraction of maximum). Each x-axis spans 3τ.
+Output: ../static/img/conviction-panels.svg
+"""
+import math, os
+
+# ── layout ───────────────────────────────────────────────────────────────────
+W, H = 720, 370
+MT, MB = 50, 72 # top / bottom margins
+ML, MR = 62, 22 # outer left / right margins
+GAP = 28 # gap between panels
+PH = H - MT - MB # plot height = 248
+PW = (W - ML - MR - GAP) // 2 # each panel plot width = 304
+
+P1X = ML # left panel plot-area left edge
+P2X = ML + PW + GAP # right panel plot-area left edge
+
+X1, X2 = 270, 90 # x-range for each panel (3τ each)
+
+def x1(d): return P1X + (d / X1) * PW
+def x2(d): return P2X + (d / X2) * PW
+def yy(f): return MT + PH * (1 - f)
+
+N = 600
+conv_pts = [(d, 1 - math.exp(-d / 90)) for d in (i * X1 / N for i in range(N + 1))]
+unlock_pts = [(d, 1 - math.exp(-d / 30)) for d in (i * X2 / N for i in range(N + 1))]
+
+def polyline(pts, xfn):
+ return " ".join(f"{xfn(x):.2f},{yy(y):.2f}" for x, y in pts)
+
+BLUE = "#3b82f6"
+ORANGE = "#f97316"
+AXIS = "#374151"
+GRID = "#e5e7eb"
+TEXT = "#111827"
+MUTED = "#6b7280"
+
+o = []
+def l(s): o.append(s)
+
+l(f'')
+
+out = os.path.join(os.path.dirname(__file__), "../static/img/conviction-panels.svg")
+with open(out, "w") as f:
+ f.write("\n".join(o))
+print(f"Written: {os.path.abspath(out)}")
diff --git a/sidebars.js b/sidebars.js
index 9f381804..1b56c0cc 100644
--- a/sidebars.js
+++ b/sidebars.js
@@ -54,7 +54,7 @@ const sidebars = {
"learn/emissions",
"learn/ema",
"learn/yuma-consensus",
- "learn/yc3-blog",
+ "learn/yc3-blog",
"concepts/weight-copying-in-bittensor",
"learn/yuma3-migration-guide",
"learn/fees",
@@ -113,6 +113,7 @@ const sidebars = {
"staking-and-delegation/stakers-btcli-guide",
"staking-and-delegation/managing-stake-btcli",
"staking-and-delegation/managing-stake-sdk",
+ "staking-and-delegation/conviction-staking",
"keys/proxies/staking-with-proxy",
{
type: "category",
diff --git a/static/img/conviction-curve.svg b/static/img/conviction-curve.svg
new file mode 100644
index 00000000..b76a6fa7
--- /dev/null
+++ b/static/img/conviction-curve.svg
@@ -0,0 +1,72 @@
+
\ No newline at end of file
diff --git a/static/img/conviction-lifecycle.svg b/static/img/conviction-lifecycle.svg
new file mode 100644
index 00000000..c7bea038
--- /dev/null
+++ b/static/img/conviction-lifecycle.svg
@@ -0,0 +1,83 @@
+
\ No newline at end of file
diff --git a/static/img/conviction-panels.svg b/static/img/conviction-panels.svg
new file mode 100644
index 00000000..0b4ce65a
--- /dev/null
+++ b/static/img/conviction-panels.svg
@@ -0,0 +1,82 @@
+
\ No newline at end of file