Aptos move module upgrade policies and compatibility rules
Every Move-based chain faces the same tension. You want to fix bugs or add features. You also want users to trust that their assets will not break when a contract changes. Aptos and Sui solve this differently, but the core danger is identical: an upgrade that changes struct layout can permanently lock user assets.
The three aptos upgrade policies
Aptos defines three policies that a module publisher chooses at deployment.
Immutable. The module can never change. No upgrade path exists. This gives users maximum certainty: the code that exists today is the code forever. The trade-off is that discovered bugs or wanted features cannot be added.
Compatible. The default policy on Aptos. This allows upgrades, but only those the VM deems structurally safe. The rules are strict. You cannot delete public functions. You cannot change existing struct fields. You cannot add new fields to a struct that is used as a resource. You can add new functions. You can add new modules that depend on old ones. The VM checks every upgrade against the published bytecode before accepting it.
The default (which is Compatible). If the developer does not specify a policy, Aptos applies Compatible. This is the safe default for most projects, but it creates a false sense of security. A Compatible upgrade can still break user workflows, even if the bytecode passes the VM's checks.
How sui handles upgrades
Sui uses a different mechanism. Instead of a policy flag, Sui gives the module an UpgradeCap object. The owner of that object controls all upgrades to that package. Without the UpgradeCap, the module is effectively immutable.
When an upgrade happens, Sui checks compatibility at the object level. The same structural rules apply: you cannot change the shape of a struct that already exists in storage. You cannot remove or change public function signatures that other modules depend on. What you can do depends on the upgrade policy attached to the UpgradeCap:
- Compatible. Same rules as Aptos Compatible. Struct fields cannot be altered. Public entry functions cannot be removed.
- Additive. You can add new structs and new functions, but you cannot touch anything already published.
- Deprecated. The old package remains, but new versions are deployed under a new address.
The real risk: struct layout changes
The most dangerous change is one that alters a struct's memory layout. Consider a simple example:
struct Coin has key {
id: UID,
value: u64,
owner: address,
}
If an upgrade tries to remove the owner field, every existing Coin object on Sui or resource on Aptos immediately becomes unreadable. The chain cannot reconstruct the struct. The assets are stranded. Users can still see them on the ledger, but no function can unpack them.
On Aptos, if a Compatible upgrade attempts this, the VM rejects it. But here is where the risk lives: a developer could publish an immutable module with a buggy struct layout. Once immutable, even the developer cannot fix it. On Sui, the UpgradeCap owner can always upgrade - but only if the change is compatible. A destructive change is blocked at the system level.
A compatible change: adding a new function that reads an existing struct. An incompatible change: adding a new field to that struct.
On both chains, the consequence of an incompatible upgrade is silent loss. No error message tells the user their coins are now inaccessible. The data exists, the object persists, and no function can touch it.
What developers should know
The compatibility checks on both Aptos and Sui are enforced at the VM level. Neither chain lets a developer accidentally delete user funds. But the checks only cover structural compatibility. They do not guard against semantic changes - an upgrade that shifts decimal places, changes fee calculation logic, or introduces a new time lock. Those are code changes that pass compatibility checks and still steal value.
A well-designed module on either chain plans for upgrades before it publishes. On Aptos, that means choosing Compatible over Immutable. On Sui, it means retaining the UpgradeCap and understanding what the three upgrade policies actually allow. Neither approach is a guarantee. Both are better than no protection at all.
The safest choice is also the most restrictive: immutable code. The most flexible is managed upgrades with clear documentation of what changed. The worst outcome is a module that can be upgraded but isn't - because the developer lost the UpgradeCap or deployed without understanding the policy. That is where user assets get locked, not by malicious code, but by developer inattention.
Not financial advice. suiboxer.xyz publishes market data and general information about digital assets. Crypto assets are volatile and you can lose everything you put in. Nothing here is a recommendation to buy, sell or hold, and we make no price predictions.
Prices are sourced from third parties and may be delayed or wrong. Verify anything you intend to act on against a primary source.