ColdkeySwapAnnounced

Event v385 → v402, v411 → v422, v423 → v440, v441 → current #70

Emitted when a coldkey commits to a future swap by publishing the hash of its replacement. This freezes the account.

Useful for: stakersdelegatorswalletsexchangesanalytics

The Big Picture

From v385 a coldkey swap is a commit-reveal with a waiting period. This event is the commit: it publishes only the BlakeTwo256 hash of the destination, so the new coldkey stays private until execution. The delay gives the real owner a window to notice an unauthorised rotation and dispute it, and the freeze is what makes that window useful, because an attacker who announced cannot drain the account while it runs.

Why This Matters

Announcing is not a reservation you can ignore. From the moment this event fires, the coldkey cannot stake, unstake, set weights, register, transfer, or even submit a system remark. Anything your service does on behalf of that coldkey will start failing with ColdkeySwapAnnounced until the swap executes, is cleared, or is reset by root.

Example Scenario

You announce a swap to a new coldkey. ColdkeySwapAnnounced fires with the hash. Your staking bot immediately starts failing on add_stake. The account stays frozen for ColdkeySwapAnnouncementDelay blocks, after which you call swap_coldkey_announced with the actual new coldkey and the hash is checked against it.

Common Questions

Why is only a hash published?: So the destination stays private during the waiting period. The new coldkey is revealed only when swap_coldkey_announced is called, and the runtime checks that its BlakeTwo256 hash matches what was announced.
How long is the wait?: ColdkeySwapAnnouncementDelay blocks, read from storage. It is a governance-set value; the genesis default in InitialColdkeySwapAnnouncementDelay is 36000 blocks. Read the storage item rather than assuming the default still holds.
Can I change my mind about the destination?: Announce again. A reannouncement is allowed once the current announcement is past its executable block plus ColdkeySwapReannouncementDelay, and it does not charge the swap cost a second time. Before that it fails with ColdkeySwapReannouncedTooEarly.

Use Cases

Warn a user that announcing a swap will lock their account
Detect the start of a key rotation before the new key is revealed
Freeze downstream automation for an account that is mid-rotation
Measure how many announcements go on to execute

How to Use This Event

→ Pair with ColdkeySwapped, ColdkeySwapCleared or ColdkeySwapReset to close the lifecycle
→ Treat an announced coldkey as read-only in any balance or staking automation
→ Read ColdkeySwapAnnouncements for the executable block rather than recomputing the delay

From Chain Metadata

A coldkey swap announcement has been made.

Triggers

Emitted by

announce_coldkey_swap

Preconditions

Caller is the coldkey being replaced
Either no announcement exists, or the previous one is past its reannouncement window
On a first announcement, the caller can pay the key swap cost

Effects

Postconditions

ColdkeySwapAnnouncements[who] holds (executableAtBlock, newColdkeyHash)
executableAtBlock is the current block plus ColdkeySwapAnnouncementDelay
Almost every other call signed by this coldkey is rejected until the swap resolves

Side Effects

The key swap cost is charged on the first announcement only, not on a reannouncement
Only announce, swap, dispute, clear and the shield pallet submit_encrypted stay callable

Event Data

#	Name	Type	Description
0	who	AccountId	who: Account address (32 bytes, SS58-encoded) (hex -> SS58)
1	new_coldkey_hash	H256 T::Hash	new_coldkey_hash: Cryptographic hash (32 bytes)

Code Examples

import { createClient, Binary } from "polkadot-api";
import { getWsProvider } from "polkadot-api/ws";
import { sub } from "@polkadot-api/descriptors"; // generated by: npx papi add sub -w wss://entrypoint-finney.opentensor.ai:443

const client = createClient(getWsProvider("wss://entrypoint-finney.opentensor.ai:443"));
const api = client.getTypedApi(sub);

// Subscribe to ColdkeySwapAnnounced events
client.finalizedBlock$.subscribe(async (block) => {
  const events = await api.event.SubtensorModule.ColdkeySwapAnnounced.get(block.hash);
  for (const evt of events) {
    console.log("ColdkeySwapAnnounced:", evt.payload);
  }
});

Version History

Version:

v385 block 7,782,670 2 args

v411 block 8,283,784 2 args

v423 block 8,486,593 2 args

v441 block 8,765,683 2 args Current

Runtime Info

View Source

Pallet Index: 7
Event Index: 70
First Version: v385
Current Version: v472

Back to SubtensorModule Events