stable-memory

Store data in stable memory rather than heap memory. In Rust use StableBTreeMap from ic-stable-structures with a MemoryManager; in Motoko use a persistent actor from mo:core 2.0 where all let and var declarations persist automatically.

Initialize a MemoryManager, assign each structure a unique MemoryId, and wrap the StableBTreeMap in thread_local RefCell. Keys need Storable plus Ord; values need Storable, typically implemented with ciborium CBOR serialization and Bound::Unbounded.

Data stored in thread_local RefCell heap variables is wiped on every upgrade. Only data written to stable memory via stable structures or Motoko persistent actor declarations survives a redeploy.

Serializing large heap data structures to stable memory inside pre_upgrade exceeds the fixed instruction limit for upgrade hooks, trapping and bricking the canister. StableBTreeMap writes directly to stable memory and needs no serialization step.

No. Each stable structure must have a unique MemoryId from the MemoryManager. Reusing an id makes two structures interpret the same stable memory bytes, silently corrupting each other's data.

No. In mo:core 2.0 persistent actors, all let and var declarations are automatically stable. Writing stable let produces warning M0218, and no pre_upgrade or post_upgrade hooks are required.