Skip to content

Commit 4f8def3

Browse files
committed
docs(canister-management): fix danger callout accuracy in migration guide
Two corrections in the "Choosing your approach" section: - Replace "load-bearing" with "whether the canister ID can change" and "The canister ID cannot change when" — avoids informal construction metaphor, says the same thing in plain ICP terms - Rewrite danger callout: "no recovery path" was wrong. Snapshot transfer retains the source canister, so the original tECDSA/vetKeys remain accessible through it until the source is deleted. Callout now explains the recovery window (stop target, switch back, do full migration) and names the actual point of no return (source canister deleted).
1 parent fae7ad6 commit 4f8def3

1 file changed

Lines changed: 5 additions & 3 deletions

File tree

‎docs/guides/canister-management/canister-migration.md‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ Consider migrating a canister when:
1818

1919
## Choosing your approach
2020

21-
Your options depend on whether the canister ID is load-bearing:
21+
Your options depend on whether the canister ID can change:
2222

2323
| Approach | State | Canister ID | Source canister | Complexity |
2424
|---|---|---|---|---|
@@ -27,14 +27,16 @@ Your options depend on whether the canister ID is load-bearing:
2727

2828
**Snapshot transfer** is the simpler path and is appropriate when you can accept a new canister ID. Create a new canister on the desired subnet, transfer state via snapshots, and switch over. The source canister is retained and can be deleted afterward.
2929

30-
**Full migration** is required when the canister ID must be preserved. A canister ID is load-bearing in these situations:
30+
**Full migration** is required when the canister ID must be preserved. The canister ID cannot change when:
3131

3232
- **Threshold signatures (tECDSA / tSchnorr)**: The IC derives signing keys by cryptographically binding them to the calling canister's principal. Any Bitcoin or Ethereum addresses derived from those keys are permanently tied to the original canister ID. Changing the ID means losing access to those signing keys and any assets they control.
3333
- **vetKeys**: vetKey derivation includes the canister's principal. A new ID produces entirely different decryption keys, making previously encrypted data permanently inaccessible.
3434
- **External references**: Other canisters, frontends, or off-chain systems that reference the canister by ID will break. This includes Internet Identity: users who authenticated via a canister-ID-based domain (for example, `<canister-id>.icp0.io`) will lose access to their sessions.
3535

3636
:::danger
37-
Choosing snapshot transfer when the canister ID is load-bearing causes permanent, irreversible loss. Any threshold signature keys (tECDSA / tSchnorr) and the Bitcoin or Ethereum addresses derived from them are gone. Any data encrypted under a vetKey becomes permanently inaccessible. There is no recovery path. Verify whether your canister derives threshold signatures or vetKeys before choosing an approach.
37+
If your canister uses threshold signatures (tECDSA / tSchnorr) or vetKeys, snapshot transfer splits state from keys: the target canister gets a new ID and therefore different signing and decryption keys. Any Bitcoin or Ethereum addresses and any encrypted data tied to the original canister ID become inaccessible from the new canister.
38+
39+
You still have a recovery window: the source canister is retained after snapshot transfer, so the original keys remain accessible through it. Stop the target, switch back to the source, and perform full migration instead — before deleting the source canister. Once the source is deleted, those keys and any assets or data tied to them are permanently gone.
3840
:::
3941

4042
## Migrating without preserving the canister ID

0 commit comments

Comments
 (0)