docs/content/guides/developer/packages/automated-address-management.mdx
When you publish or upgrade a package, its address is tracked in the Move.lock file. A package's address is its package ID. This happens automatically, so you do not need to manually record or update hexadecimal addresses.
When you publish or upgrade your package on multiple Sui networks (Mainnet, Testnet, Devnet), automated address management tracks separate addresses for each chain. Tracking is based on your active environment. You can run sui client active-env to see your current environment. For example, if your active environment is testnet and you publish a package, the Move.lock records the address for that package and associates it with testnet.
Automated address management works for one package published to one or more Sui networks. If a package is republished to a network, tracked addresses for that network are overwritten.
Previously, a published-at entry in Move.toml was mandatory. It is no longer required if the data is tracked in Move.lock. For an existing package, you can migrate to automated tracking as follows:
sui client --switch --env <YOUR-CHAIN-ENVIRONMENT>
manage-package command with details of your published package:sui move manage-package --environment "$(sui client active-env)" \
--network-id "$(sui client chain-identifier)" \
--original-id 'ORIGINAL-ADDRESS' \
--latest-id 'LATEST-ADDRESS' \
--version-number 'VERSION-NUMBER'
ORIGINAL-ADDRESS: The address where your package was first published. If you never upgraded, this matches the published-at address in Move.toml.
LATEST-ADDRESS: The latest package address. If you never upgraded, this matches ORIGINAL-ADDRESS. If upgraded, it matches the current published-at address.
VERSION-NUMBER: 1 if you never upgraded. Otherwise, set to the upgrade count. Look up the package at LATEST-ADDRESS to confirm the version number.
Delete the published-at line in your Move.toml.
Set your package's address to 0x0 in the [addresses] section:
[package]
name = "Kiosk"
[dependencies]
# ... your dependencies ...
[addresses]
kiosk = "0x0"
Your package is now tracked. Repeat the steps to track addresses for additional environments.
When upgrading, you need the UpgradeCap ID of your package. Automated address management does not track UpgradeCap.
You must also set the [addresses] value for your package to 0x0 in Move.toml, and restore it with the ORIGINAL-ADDRESS after upgrading.
Conflicting addresses can occur if package data becomes inconsistent. For example, a package might still have a published-at value in Move.toml while also being tracked in Move.lock. The mismatch causes an error when publishing or upgrading.
To fix conflicts:
For your own package:
Delete the published-at value in Move.toml if it's no longer needed. Then set the package's address to 0x0 in [addresses].
Or, follow the adoption steps above.
For a dependency package:
This section explains the schema and internal operation of tracked addresses in Move.lock. Most developers do not need this detail.
Example schema in a Move.lock file:
[env]
[env.testnet]
chain-id = "4c78adac"
original-published-id = "0xa6041ac57f9151d49d00dcdc4f79f8c5ba1e399e1005dcb0fdd1c8632020d5a6"
latest-published-id = "0xa6041ac57f9151d49d00dcdc4f79f8c5ba1e399e1005dcb0fdd1c8632020d5a6"
published-version = "1"
[env.mainnet]
chain-id = "35834a8a"
original-published-id = "0xaee5759aedf6c533634cdd2de412f6e6dfc754a89b0ec554a73597348f334477"
latest-published-id = "0xaee5759aedf6c533634cdd2de412f6e6dfc754a89b0ec554a73597348f334477"
published-version = "1"
:::info
Each [env] table entry represents an environment. When a package is published, its entry is added or updated.
Entries are keyed by chain-id, not the [env.NAME]. This ensures addresses are resolved consistently even if users assign arbitrary environment names.
Key-value pairs correspond to the data described in adopting automated address management. Use the sui move manage-package command as the frontend to modify these values.
:::