Canister upgrades and stable memory

Motoko takes a different approach. The documentation describes orthogonal persistence as the property that a Motoko actor's variables persist across upgrades automatically, without the developer writing serialisation code. A Motoko canister declares its state as ordinary variables, and the runtime handles the transition across an upgrade.

The documentation is careful about the limits. Orthogonal persistence applies to the actor's state, and it works because the Motoko runtime manages the mapping between the language's values and the canister's memory. A developer who wants explicit control can still use stable variables and the system functions for pre-upgrade and post-upgrade, and the documentation describes the interaction between the two mechanisms.

The practical consequence is that a Motoko canister is harder to break by forgetting a hook, and a Rust canister is easier to break that way. That is not a claim that one language is better; it is a statement about where the responsibility sits. In Motoko the runtime carries it by default; in Rust the developer carries it explicitly.

In Rust the developer manages persistence. The documentation describes the stable structures the CDK provides — stable vectors, stable logs, stable cell, stable B-tree maps and sets — which store their data in stable memory directly rather than in the heap. A canister built on stable structures keeps its data across an upgrade without a serialisation step, because the data was never in the heap to begin with.

The alternative is to keep state in the heap and move it in the hooks. The documentation describes the pre-upgrade hook as the place to write the heap state into stable memory and the post-upgrade hook as the place to read it back. This works, but it has a cost: the serialisation happens inside the upgrade, and a large state can exceed the instruction limit for a single message. The documentation notes that the upgrade can be split across multiple messages when that happens.

The documentation also describes the memory limits. A canister's stable memory is much larger than its heap, and the heap itself is bounded. A canister that needs to hold a lot of data must use stable memory, which in Rust means stable structures and in Motoko means the runtime's persistence. The Motoko versus Rust page compares the two approaches in more detail.

The documentation describes what happens when an upgrade fails. If the new module cannot be installed, or if the pre-upgrade hook traps, the upgrade does not complete and the canister continues running the old code. That is a safety property: a broken upgrade does not leave the canister in a half-updated state. The cost is that the canister is still running the old code, which may be the thing the upgrade was meant to fix.

The more dangerous failure is a successful upgrade that loses data. If the pre-upgrade hook does not write everything the post-upgrade hook expects, the canister comes up with a partial state. The documentation's guidance is to test upgrades against a copy of production state, which is the only way to be sure the hooks agree.

The documentation also notes that a canister's controllers can upgrade it, and that the management canister exposes the upgrade operation. That means the authority to change a canister's code is the authority to change its behaviour entirely, which is why the SNS handover is a meaningful act rather than a symbolic one.