Coldkey Swap
A coldkey swap migrates a Bittensor wallet’s entire on-chain identity to a new coldkey key pair. The official Rotate or Swap your Coldkey documentation describes it as an operation that moves on-chain identity, including TAO balances and subnet ownership, to a new cryptographic key pair, and recommends it when a coldkey may have been leaked or compromised.
Why a Coldkey Swap Exists
A coldkey secures a wallet’s identity and assets, so a leaked coldkey threatens everything that wallet controls. The Coldkey and Hotkey Workstation Security guide frames the coldkey as the security-critical key behind TAO and subnet ownership, in contrast to the operational hotkey used for day-to-day subnet work.
Coldkey swap exists for that boundary. It gives an owner a recovery path that re-homes the full on-chain identity under a fresh coldkey instead of abandoning the wallet’s registrations and ownership.
References: Rotate or Swap your Coldkey, Coldkey and Hotkey Workstation Security
How a Swap Unfolds
A coldkey swap is deliberately staged rather than instant. The swap documentation describes an initiation step in which the owner announces the swap on chain and supplies the destination address as a published hash, which triggers a mandatory waiting period that locks the wallet against transfers and staking.
A pending lock-out period then elapses before the swap can finalize. The documentation states this window is currently 36,000 blocks, roughly five days, during which the swap can be disputed but not completed. The staged sequence and its dispute path are implemented in the Subtensor coldkey swap source code.
References: Rotate or Swap your Coldkey, Subtensor coldkey swap source code
Coldkey Swap Versus a Transfer
A coldkey swap is not always the right tool. The swap documentation notes that a swap is only necessary to migrate a coldkey that holds subnet ownerships or registrations. A holder who only keeps and stakes TAO does not need a swap and can instead move assets to a new coldkey through ordinary balance and stake transfers.
For readers, the distinction is scope: transfers move funds between coldkeys, while a coldkey swap migrates the identity itself, including registrations and ownership that a plain transfer cannot carry.
References: Rotate or Swap your Coldkey, Wallets, Coldkeys and Hotkeys in Bittensor
Same-Owner Boundary
A coldkey swap is a self-directed migration, not a sale or handoff to an unrelated party. The owner initiates the swap and names the destination wallet, so the operation re-homes the same identity under a new key the owner controls rather than transferring ownership to someone else.
For readers, coldkey swap should be read as identity continuity under a safer key, not as a change of who ultimately owns the wallet.
References: Rotate or Swap your Coldkey, Coldkey and Hotkey Workstation Security
What Happens During the Lock Period
Once a coldkey swap is initiated, the wallet enters a restricted period before finalization. The official Rotate or Swap your Coldkey documentation explains that initiation publishes the destination as a hash and triggers a mandatory waiting period during which the wallet is locked against transfers and staking.
For readers, that lock is part of the design rather than an incidental delay. The owner cannot keep rearranging balances or stake while the migration is pending, which reduces the chance that a compromised key continues moving assets during recovery. The lock period also gives observers time to notice an unexpected swap announcement before the identity migration completes.
Reference: Rotate or Swap your Coldkey
Why the Dispute Window Exists
The documentation describes a pending lock-out period — currently about 36,000 blocks, roughly five days — before the swap can finalize. During that window the swap can be disputed but not completed. The Subtensor coldkey swap implementation implements that staged sequence and its dispute path on chain.
The dispute window matters when a swap was not authorized by the true coldkey owner. The official coldkey swap documentation and SDK material describe disputing as an action the coldkey with an active announcement can call, requiring the coldkey private key. If an attacker gained temporary access and announced a migration to an attacker-controlled destination, the legitimate coldkey owner has time to dispute the pending swap before the identity move becomes final. A coldkey swap is therefore not an instant key handoff; it is a deliberate recovery process with a public waiting period built in.
References: Rotate or Swap your Coldkey, Subtensor coldkey swap source code
Coldkey Swap Versus Hotkey Swap
Coldkey swap and hotkey swap solve different security problems. A coldkey swap migrates the full on-chain identity — balances, registrations, and ownership tied to the coldkey — to a new coldkey pair. A hotkey swap rotates subnet participation from one operational hotkey to another while the same coldkey remains in control.
The security documentation recommends hotkey swap when an operational key may have leaked but the coldkey is still trusted. Coldkey swap is the heavier recovery path when the security-critical key itself may be compromised. Readers should not treat the two operations as interchangeable: one changes wallet identity at the coldkey layer, the other changes the operational hotkey that carries subnet-facing work under an unchanged coldkey owner. Choosing the wrong recovery path can either leave a compromised coldkey in control or trigger unnecessary identity migration when only the operational key needed rotation.
References: Rotate or Swap your Coldkey, Coldkey and Hotkey Workstation Security, Wallets, Coldkeys and Hotkeys in Bittensor
Relationship to Coinbase
Coldkey swap and coinbase address related but different parts of Bittensor wallet identity and emission vocabulary. A coldkey swap migrates a wallet’s full on-chain identity — including TAO balances, subnet ownerships, and all associated hotkeys — to a new coldkey, as described by the Rotate or Swap your Coldkey documentation. Coinbase is the per-block Subtensor mechanism that accumulates pending emissions and triggers the Yuma Consensus epoch round at each subnet’s epoch boundary, distributing miner incentives and validator dividends, as described by the Coinbase Implementation.
Coldkey swap does not pause, reset, or interrupt coinbase. Coinbase fires every block regardless of whether a wallet identity migration is in progress. What the swap transfers is control over the hotkey-identified positions that coinbase credits: once a coldkey swap finalizes, the new coldkey owns those hotkeys and therefore governs all the emission outcomes that coinbase has distributed or will distribute to them. The swap operates at the identity-ownership layer; coinbase continues accumulating and distributing emissions to the same hotkey-identified participant positions throughout.
References: Rotate or Swap your Coldkey, Coinbase Implementation
Relationship to Hotkey Swap
Coldkey swap and hotkey swap address different security concerns and operate at different layers of the Bittensor wallet model. A coldkey swap migrates the wallet’s full on-chain identity — including TAO balances, subnet ownerships, and registrations — to a new coldkey pair, as described in the Rotate or Swap your Coldkey documentation. A hotkey swap moves subnet participation from an old hotkey to a new hotkey owned by the same coldkey, as described in the Coldkey and Hotkey Workstation Security documentation.
For readers, coldkey swap changes the controlling identity of the wallet — the security-critical key that owns TAO balances and subnet ownership — while hotkey swap changes the operational key under the unchanged controlling identity. The two are not interchangeable: a coldkey swap addresses a compromised controlling key, while a hotkey swap addresses a compromised operational key. A reader who understands coldkey swap can use hotkey swap to recognize the lighter-weight operational-key recovery path that leaves the coldkey and its on-chain identity intact.
References: Rotate or Swap your Coldkey, Coldkey and Hotkey Workstation Security
Relationship to Transferring Stake
Coldkey swap and transferring stake are related but distinct parts of Bittensor stake-management vocabulary. A coldkey swap migrates the wallet’s full on-chain identity — including TAO balances, subnet ownerships, and registrations — to a new coldkey pair. Transferring stake is the operation that changes which coldkey owns a particular staked position while keeping that stake on the same validator and subnet, as described in the Staking and delegation overview: Transferring stake.
For readers, a coldkey swap migrates the entire wallet’s on-chain identity in one staged operation, while transferring stake moves a single staked position to a different owning coldkey without changing the validator. The two are not interchangeable: a coldkey swap touches balances, subnet ownerships, and registrations together, while transferring stake is a targeted stake-side ownership reassignment. A reader who understands coldkey swap can use transferring stake to recognize the narrower operation that reassigns ownership of one staked position without invoking a full identity migration.
References: Rotate or Swap your Coldkey, Staking and delegation overview: Transferring stake
Relationship to Yuma Consensus
Coldkey Swap and Yuma Consensus describe related parts of Bittensor’s incentive system. Yuma Consensus is the on-chain process that aggregates validator weight signals within a subnet into miner incentives and validator dividends, applying consensus clipping, bonding, and emission calculation (Yuma Consensus).
For readers, coldkey swap names a specific part of that incentive picture, while Yuma Consensus names the consensus process that turns validator weights into the resulting incentives and dividends.
Reader Boundary
Coldkey swap should not be read as a step-by-step command guide, a live parameter quote, or a recommendation to swap any specific wallet. The lock-out length and other values can change on chain, so current figures belong in official references and live chain state. This article describes the concept of migrating a wallet’s on-chain identity to a new coldkey.
Development Stage Context
The Introduction to Bittensor describes subnet development as moving from local testing to testchain and then mainchain. For coldkey swap, that sequence changes how readers should interpret evidence about on-chain identity migration.
In local testing, a coldkey swap can be exercised inside an isolated environment to check whether the staged migration process runs correctly. That is useful for verifying the swap flow, but it remains isolated feedback from a local environment and does not involve real on-chain identity or TAO balances.
On testchain, coldkey swap behavior can be observed in a shared testing network. This gives stronger evidence about how the staged dispute window, balance migration, and hotkey inheritance work than a private local run, while still keeping the result separate from production mainchain identity state.
On mainchain, a coldkey swap migrates a participant’s actual on-chain identity, TAO balances, and subnet ownership to a new coldkey. The Rotate or Swap your Coldkey documentation describes the swap as a staged on-chain process, so production coldkey swap context is tied to real wallet identity on the active network.
The Bittensor Networks reference separates mainnet, testnet, and localnet. A coldkey swap observed in one environment should not be read as identical evidence about identity migration in another environment.
For readers, this keeps coldkey swap examples from sounding stronger than their environment supports. Local, testchain, and mainchain contexts can all describe the on-chain identity migration process, but they do not carry the same interpretive weight.
Identity Continuity Boundary
Coldkey swap should be read as continuity of an on-chain identity under a new coldkey, not as an ordinary value transfer. The swap documentation describes moving the wallet’s on-chain identity, while wallet documentation separates coldkey authority from the broader wallet container (Rotate or Swap your Coldkey, Wallets, Coldkeys and Hotkeys).
That distinction matters when an article discusses subnet ownership or registrations. A balance transfer can move funds, but a coldkey swap is the concept for moving the identity relationships that remain attached to the wallet’s on-chain presence.
Associated Hotkeys Migrate With the Swapped Coldkey
Official Rotate or Swap your Coldkey documentation describes the swap as migrating the wallet’s on-chain identity, including subnet ownership and the hotkeys associated with that identity. Coldkey swap therefore moves control over existing hotkey registrations rather than leaving them on the old coldkey.
Readers should treat hotkey inheritance as part of the identity migration concept. A finalized swap re-homes the coldkey that governs those operational keys under the destination key pair (Wallets, Coldkeys and Hotkeys).