Skip to main content

Automated Address Management (Legacy, pre-v1.63)

Legacy documentation

The pre-v1.63 address management system used Move.lock and published-at fields in Move.toml. See Move Package Management for the current system, and the migration guide for how to migrate.

When you publish or upgrade a package, the Move.lock file tracks its address. 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 depends 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 you republish a package to a network, the new addresses overwrite the tracked addresses for that network.

How do I adopt automated address management?​

Previously, a published-at entry in Move.toml was mandatory. You no longer need it if Move.lock tracks the data. 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>
  1. 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 you first published your package. 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 you 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.

  • Shell substitution fills in --environment and --network-id from sui client active-env and sui client chain-identifier. sui client chain-identifier returns the chain ID of the active network, which Move.lock stores as chain-id (for example, 4c78adac in the Testnet entry under Internal reference). If your shell does not support $(...), run the two commands separately and paste their output in place of the substitutions.

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

  2. Set your package's address to 0x0 in the [addresses] section:

[package]
name = "Kiosk"

[dependencies]
# ... your dependencies ...

[addresses]
kiosk = "0x0"

Move.lock now tracks your package. To confirm, check that Move.lock contains an [env.<YOUR-CHAIN-ENVIRONMENT>] entry with the values you supplied; see Internal reference for the expected format. Repeat the steps to track addresses for additional environments.

How do I upgrade a tracked package?​

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.

How do I fix conflicting addresses?​

Conflicting addresses can occur if package data becomes inconsistent. For example, a package might still have a published-at value in Move.toml while Move.lock also tracks it. 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​

Move.lock stores tracked addresses using the schema and internal rules that follow. 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 you publish a package, the Sui CLI adds or updates its entry.

  • The chain-id keys each entry, not the [env.NAME]. This ensures that addresses resolve consistently even if you 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.