Extend Aptos package state without breaking an existing resource layout
A compatible package upgrade must preserve the layout of existing resources. Adding a display field directly to a deployed resource can fail compatibility checks.
Keep the original resource and add a companion type
Suppose Position containing units has already been published. Keep its fields unchanged and define a separate PositionLabel resource. Publish the companion at a suitable address through a signer authorized to store it. Existing Position values continue to use their original layout.
struct Position has key { units: u64 }
struct PositionLabel has key { label: vector<u8> }
Handle unmigrated holders in the read path
An old holder may have Position while PositionLabel is absent. Read the label conditionally and return the documented default. Before preparing the release, inspect its package entry in code::PackageRegistry and verify the current upgrade policy. An immutable package cannot deploy this addition by upgrading the existing package.