Automated Address Management

When you publish or upgrade a package, its address (also called the package ID) is tracked in the Move.lock file. This happens automatically, so you don’t need to manually record or update hex addresses (for example, in the Move.toml file).

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 (run sui client active-env if unsure). For example, if your active environment is set to an RPC connected to 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.

Adopting automated address management

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:

1. Switch to your active environment for the chain where your package is published:

   sui client --switch --env <YOUR-CHAIN-ENVIRONMENT>

2. Run the 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.

3. Delete the published-at line in your Move.toml.

4. 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.

Package upgrade guidance

• When upgrading, you need the UpgradeCap ID of your package. Automated address management does not track UpgradeCap.
• When upgrading, set the [addresses] value for your package to 0x0 in Move.toml, and restore it with the ORIGINAL-ADDRESS after upgrading.

Troubleshooting

Conflicting addresses can occur if package data becomes inconsistent.

For example, a package may 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:

  • Fix the issue locally using the same steps, or contact the package maintainer to update it upstream.

Internal reference

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.