Stable Memory & Canister Upgrades

What This Is

Stable memory is persistent storage on Internet Computer that survives canister upgrades. Heap memory (regular variables) is wiped on every upgrade. Any data you care about MUST be in stable memory, or it will be lost the next time the canister is deployed.

Prerequisites

• For Motoko: mops with core = "2.0.0" in mops.toml
• For Rust: ic-stable-structures = "0.7" in Cargo.toml

Canister IDs

No external canister dependencies. Stable memory is a local canister feature.

Mistakes That Break Your Build

1. Using thread_local! { RefCell<T> } for user data (Rust) -- This is heap memory. It is wiped on every canister upgrade. All user data, balances, settings stored this way will vanish after icp deploy. Use StableBTreeMap instead.

2. Forgetting #[post_upgrade] handler (Rust) -- Without a post_upgrade function, the canister may silently reset state or behave unexpectedly after upgrade. Always define both #[init] and #[post_upgrade].