You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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).
Copy file name to clipboardExpand all lines: docs/guides/canister-management/canister-migration.md
+5-3Lines changed: 5 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -18,7 +18,7 @@ Consider migrating a canister when:
18
18
19
19
## Choosing your approach
20
20
21
-
Your options depend on whether the canister ID is load-bearing:
21
+
Your options depend on whether the canister ID can change:
22
22
23
23
| Approach | State | Canister ID | Source canister | Complexity |
24
24
|---|---|---|---|---|
@@ -27,14 +27,16 @@ Your options depend on whether the canister ID is load-bearing:
27
27
28
28
**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.
29
29
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:
31
31
32
32
-**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.
33
33
-**vetKeys**: vetKey derivation includes the canister's principal. A new ID produces entirely different decryption keys, making previously encrypted data permanently inaccessible.
34
34
-**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.
35
35
36
36
:::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.
0 commit comments