swap_hotkey

Call Re-added v136 → v163, v195 → v274, v276 → current #70

Swaps hotkey to a new address.

View calls on chain

Click items to navigate. Pan and zoom to explore.

Used by: minersvalidatorsdevelopers

The Big Picture

Hotkeys are your public identity on subnets - validators query them, weights target them. swap_hotkey lets you change this identity without losing your UIDs or stake associations. The new hotkey inherits everything from the old one. This is essential for security rotations and infrastructure migrations.

Why This Matters

Your hotkey may be exposed on servers, in configs, or through operational access. Periodically rotating it limits damage from unknown compromises. Swapping preserves your registrations - you don't have to re-register on every subnet.

Example Scenario

Your miner runs on a cloud server with hotkey exposed in config. For security, you want to rotate quarterly. Generate new_hotkey. Call swap_hotkey(old_hotkey, new_hotkey). Your UIDs on subnets 1, 3, and 18 transfer to new_hotkey. Update your miner config, re-serve axon endpoint, continue mining.

Common Questions

Do I keep my UIDs after swapping?
Yes - UIDs are preserved. You're changing the key, not the registration. No re-registration needed.
What about stake from delegators?
Stake follows the coldkey-hotkey relationship. After swap, delegators are staked to your new hotkey. They don't need to do anything.
Do I need to re-serve my axon?
Yes - serve_axon records your endpoint under your hotkey. After swap, serve again with the new hotkey so validators can find you.
What if someone is using my target hotkey?
Swap fails. The new hotkey must be completely unused (not registered anywhere). Generate a fresh key to guarantee availability.

Use Cases

  • Rotate hotkey for security without losing registrations
  • Replace compromised hotkey while preserving UIDs
  • Migrate mining operation to new infrastructure
  • Key hygiene - periodic rotation as best practice

From Chain Metadata

The extrinsic for user to change its hotkey in subnet or all subnets.

Input Parameters

#NameTypeDescription
0
hotkey
AccountId Hot wallet address (active operations) (hex -> SS58)
1
new_hotkey
AccountId new_hotkey (AccountId) (hex -> SS58)
2
netuid
Option netuid (Option)

Permissions

Origin
Unknown
Required Role
Any

Permission data inferred from metadata. May be incomplete.

Requirements

  • Caller owns the hotkey (via coldkey)
  • New hotkey not already registered on any subnet
  • Swap conditions met

Effects

Postconditions

  • All registrations transferred to new hotkey
  • All stake associations preserved
  • Old hotkey becomes unused
  • UIDs preserved across swap

Side Effects

  • Axon/Prometheus endpoints need re-registration
  • External systems referencing old hotkey need updating

Code Examples

import { ApiPromise, WsProvider } from "@polkadot/api";
import { stringCamelCase } from "@polkadot/util";

const provider = new WsProvider("wss://entrypoint-finney.opentensor.ai:443");
const api = await ApiPromise.create({ provider });

// Build swap_hotkey call
const hotkey = "5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY";
const new_hotkey = "5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY";
const netuid = 1;

const call = api.tx[stringCamelCase("SubtensorModule")][stringCamelCase("swap_hotkey")](
  hotkey,
  new_hotkey,
  netuid
);

Version History

v136 block 1,756,781 2 args
v195 block 3,791,350 2 args
v276 block 5,781,672 3 args Current

Runtime Info

View Source
Pallet Index
7
Call Index
70
First Version
v136
Current Version
v393
Back to SubtensorModule Calls