Convictions (stake locks)

[gztensor]

Description

• Implements an exponential lock mechanism where coldkeys can lock alpha stake to a specific hotkey per subnet, building conviction over time.
• Lock state uses lazy evaluation: locked_mass decays as exp(-dt/tau) * X and conviction grows as the time-integral of locked mass via exp(-dt/tau) * (Y + dt * X).
• Enforces lock invariant on unstake (validate_remove_stake) and move/transfer (validate_stake_transition): total coldkey alpha on subnet must remain >= current locked amount.
• New extrinsic lock_stake with TauBlocks configurable decay timescale (default ~30 days).
• 52 tests covering: green-path operations, incremental top-ups, decay math, invariant enforcement, multi-subnet locks, conviction aggregation, subnet king queries, lock cleanup, swap interactions, and edge cases.

Updates:

• Request 2026-04-19 (const): Can change the hotkey of a lock but when you do it resets the conviction. Implementation: TODO
• 2026-04-21: Implementation decision - coldkey swap will fail if new coldkey already has any locks. Hotkey swap will reset conviction.

Known gaps

• 1. do_recycle_alpha / do_burn_alpha bypass lock — calls decrease_stake_for_hotkey_and_coldkey_on_subnet without lock check.
• 2. clear_small_nomination_if_required bypasses lock — removes nominator alpha without lock validation.
• 3. Subnet dissolution orphans Lock entries — destroy_alpha_in_out_stakes removes all Alpha but not Lock storage; stale locks persist across netuid reuse.
• 4. Coldkey swap does not migrate Lock entries.
• 5. Hotkey swap does not update Lock entries.
• 6. subnet_king needs optimization to avoid O(n) Lock iteration (another map possibly).

Implementation checklist

• Hotkey conviction RPC
• Allow moving from one hotkey to another without resetting conviction if coldkey owns both hotkeys
• Extrinsic to switch hotkey in the lock (with loss of conviction)
• Do not store zero entries in Lock and HotkeyLock maps
• Bake in flexibility in state maps to lock to multiple hotkeys, enforce 1-1 lock in code

Questions

• Does hotkey account need to exist in order for coldkeys to be able to lock to it? Currently it is not enforced.

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Other (please describe):

Checklist

• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have run ./scripts/fix_rust.sh to ensure my code is formatted and linted correctly
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• Any dependent changes have been merged and published in downstream modules