docs: canister snapshots guide

[marc0olo]

Summary

• Creating, listing, restoring, and deleting snapshots via icp-cli
• Downloading and uploading snapshots to disk (with --resume for interrupted transfers)
• Pre-upgrade backup/rollback workflow and state transfer between canisters examples
• Snapshot limits (10 per canister) and storage costs

Sync recommendation

informed by dfinity/icp-cli — docs/guides/canister-snapshots.md

[marc0olo]

Review: Canister Snapshots

Must fix

• Missing "certified variables" from snapshot contents: The page's intro says a snapshot captures "its compiled Wasm module, Wasm heap memory, stable memory, and chunk store". The IC interface spec (take_canister_snapshot, portal/docs/references/ic-interface-spec.md line 3082) explicitly states a snapshot consists of "wasm memory, stable memory, certified variables, wasm chunk store and wasm binary". Certified variables are missing from the page's list. Suggested fix: update the intro to read "compiled Wasm module, Wasm heap memory, stable memory, certified variables, and chunk store".

• Pre-upgrade backup example leaves canister stopped before deploy: In the "Example: pre-upgrade backup and rollback" section, the workflow stops the canister to create a snapshot but never starts it again before running icp deploy my-canister -e ic. Attempting to deploy an upgrade to a stopped canister will fail. A icp canister start my-canister -e ic line should be inserted after the snapshot create step (between the snapshot create and the # 2. Deploy the upgrade comment). Note: the upstream source guide (icp-cli/docs/guides/canister-snapshots.md) has the same omission — this is a pre-existing bug in source material that should be corrected here rather than replicated.

• State-transfer example missing stop/start for target canister before restore: In the "Example: transferring state between canisters", the icp canister snapshot restore <target-canister-id> call is made without first stopping the target canister. The IC interface spec (line 3115) and the icp-cli guide both state: "The canister must be stopped before restoring." The example needs icp canister stop <target-canister-id> -n ic before the restore and icp canister start <target-canister-id> -n ic after. The upstream source guide has the same omission — correct it here.

Suggestions

• Restore section description incomplete: The "Restoring from a snapshot" section says "Restoring replaces the canister's current Wasm module, heap memory, and stable memory with the snapshot contents." It omits certified variables and the chunk store, both of which are included in a snapshot and are replaced during restore. Consider updating to match the full list of snapshot components.

• State transfer use-case could clarify why download+upload is needed for cross-subnet: The page says this workflow is "the foundation of canister migration between subnets." A brief note clarifying that direct restore (load_canister_snapshot) only works within the same subnet — and that download+upload is what enables cross-subnet transfer — would prevent confusion about when each approach applies.

• -n ic explanation note breaks section flow: The note at line 122–126 ("All snapshot commands accept either canister names (with -e) or canister IDs (with -n). Use -n ic when the target canister is not part of your project") appears between the upload section and the state-transfer example. Consider moving it into the state-transfer example as a comment or note, since that is the context where it is first relevant.

Verified

• All icp canister snapshot subcommands (create, list, restore, delete, download, upload) verified against .sources/icp-cli/docs/reference/cli.md — all exist and match the documented usage.
• --replace flag for both snapshot create and snapshot upload verified against CLI reference — correct.
• --resume flag for both snapshot download and snapshot upload verified against CLI reference — correct.
• -o flag for snapshot download and -i flag for snapshot upload verified — correct.
• -e ic and -n ic flag usage verified — correct per CLI reference (names use -e, principals use -n).
• icp canister stop, icp canister start, icp deploy, icp canister call commands all verified against CLI reference — all exist.
• snapshots_size field in icp canister status output verified against IC interface spec (ic.did line 302 and ic-interface-spec.md line 2645) — valid field.
• 10-snapshot-per-canister limit verified against portal/docs/references/ic-interface-spec.md and icp-cli/docs/guides/canister-snapshots.md — correct.
• Stop requirement before taking and restoring snapshots verified against icp-cli/docs/guides/canister-snapshots.md and IC interface spec (lines 3092 and 3115).
• Internal link lifecycle.md resolves to docs/guides/canister-management/lifecycle.mdx — valid (Astro resolves .md links to .mdx).
• Internal link ../security/canister-upgrades.md resolves to docs/guides/security/canister-upgrades.md — valid.
• External link https://cli.internetcomputer.org/ — allowed domain per project rules.
• No dfx references, no mo:base imports, no banned URLs (internetcomputer.org/docs/ or docs.internetcomputer.org).
• Frontmatter complete (title, description, sidebar order) and consistent with page content.
• Build passes cleanly (npm run build).
• <\!-- Upstream: --> comment present at end of page.

[marc0olo]

<!-- feedback-addressed -->

Feedback addressed — PR #84 (Canister Snapshots)

Changes applied

Must fix — all three applied:

1. Added "certified variables" to snapshot contents (intro): Updated the intro sentence from "compiled Wasm module, Wasm heap memory, stable memory, and chunk store" to "compiled Wasm module, Wasm heap memory, stable memory, certified variables, and chunk store". The IC interface spec (take_canister_snapshot) explicitly lists certified variables as part of the snapshot state.

2. Fixed pre-upgrade backup example — start canister before deploy: Added icp canister start my-canister -e ic after the snapshot create step and before # 2. Deploy the upgrade. The upstream source (icp-cli/docs/guides/canister-snapshots.md) has the same omission; corrected here per reviewer's request. Deploying an upgrade to a stopped canister would fail — the fix matches the correct operational sequence (stop → snapshot → start → deploy → verify → cleanup or rollback).

3. Fixed state-transfer example — stop/start target canister around restore: Added icp canister stop <target-canister-id> -n ic before the restore call and icp canister start <target-canister-id> -n ic after it. The restore section clearly states "the canister must be stopped before restoring" — the example was inconsistent with that requirement. The upstream source had the same omission; corrected here.

Suggestions — all three applied:

4. Updated restore section description to include full state list: Changed "Restoring replaces the canister's current Wasm module, heap memory, and stable memory" to "Restoring replaces the canister's current Wasm module, heap memory, stable memory, certified variables, and chunk store" — consistent with the intro and the IC spec.

5. Added cross-subnet clarification to state-transfer example: Added a sentence explaining that direct restore (load_canister_snapshot) only works within the same subnet, and that download+upload is what enables cross-subnet transfer. This prevents confusion about when each approach applies.

6. Moved -n ic explanation to state-transfer example context: Removed the standalone note block that appeared between the upload section and the pre-upgrade example. Placed the -n ic explanation as prose at the top of the state-transfer example section, where it is first relevant. Also added an inline comment in the code block.

Items skipped

None. All feedback items were factually correct and improved the page.

Build note

The npm run build fails in this worktree due to a pre-existing infrastructure issue: .sources/examples submodule is not initialized (SSH key access is blocked in the sandbox), which causes https-outcalls.mdx to fail on a remark-snippet file reference. This error is unrelated to snapshots.md. The snapshots page is pure markdown with no snippet dependencies.