stable-memory
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
-
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 aftericp deploy. UseStableBTreeMapinstead. -
Forgetting
#[post_upgrade]handler (Rust) -- Without apost_upgradefunction, the canister may silently reset state or behave unexpectedly after upgrade. Always define both#[init]and#[post_upgrade].
More from dfinity/icskills
icp-cli
Guides use of the icp command-line tool for building and deploying Internet Computer applications. Covers project configuration (icp.yaml), recipes, environments, canister lifecycle, and identity management. Use when building, deploying, or managing any IC project. Use when the user mentions icp, dfx, canister deployment, local network, or project setup. Do NOT use for canister-level programming patterns like access control, inter-canister calls, or stable memory — use domain-specific skills instead.
134internet-identity
Integrate Internet Identity authentication. Covers passkey and OpenID login flows, delegation handling, and principal-per-app isolation. Use when adding login, sign-in, auth, passkeys, or Internet Identity to a frontend or canister. Do NOT use for wallet integration or ICRC signer flows — use wallet-integration instead.
126asset-canister
Deploy frontend assets to the IC. Covers certified assets, SPA routing with .ic-assets.json5, content encoding, and programmatic uploads. Use when hosting a frontend, deploying static files, or setting up SPA routing on IC. Do NOT use for canister-level code patterns or custom domain setup — use custom-domains instead.
126https-outcalls
Make HTTPS requests from canisters to external web APIs. Covers transform functions for consensus, cycle cost management, response size limits, and idempotency patterns. Use when a canister needs to call an external API, fetch data from the web, or make HTTP requests. Do NOT use for EVM/Ethereum calls — use evm-rpc instead.
121canister-security
IC-specific security patterns for canister development in Motoko and Rust. Covers access control, anonymous principal rejection, reentrancy prevention (CallerGuard pattern), async safety (saga pattern), callback trap handling, cycle drain protection, and safe upgrade patterns. Use when writing or modifying any canister that modifies state, handles tokens, makes inter-canister calls, or implements access control.
119certified-variables
Serve cryptographically verified responses from query calls using Merkle trees and subnet BLS signatures. Covers certified data API, RbTree/CertTree construction, witness generation, and frontend certificate validation. Use when query responses need verification, certified data, or response authenticity proofs.
116