docs: automated address management updates (#18549)

## Description Updates docs to reflect #18470 changes. ## Test plan N/A docs --- ## Release notes Check each box that your changes affect. If none of the boxes relate to your changes, release notes aren't required. For each box you select, include information after the relevant heading that describes the impact of your changes that a user might notice and any actions they must take to implement updates. - [ ] Protocol: - [ ] Nodes (Validators and Full nodes): - [ ] Indexer: - [ ] JSON-RPC: - [ ] GraphQL: - [ ] CLI: - [ ] Rust SDK: --------- Co-authored-by: ronny-mysten <[email protected]>
MystenLabs · Jul 8, 2024 · d72f793 · d72f793
1 parent 2568b8a
commit d72f793
Show file tree

Hide file tree

Showing 2 changed files with 41 additions and 37 deletions.
diff --git a/docs/content/concepts/sui-move-concepts/packages/automated-address-management.mdx b/docs/content/concepts/sui-move-concepts/packages/automated-address-management.mdx
@@ -27,7 +27,21 @@ Previously a `published-at` entry was **mandatory** in the `Move.toml` file, whi
       - `ORIGINAL-ADDRESS` should be the address your package was first published at. If you never upgraded your package, this the same address as your `published-at` address in the `Move.toml`
       - `LATEST-ADDRESS` should be the latest package address. If you never upgraded your package, it is the same as `ORIGINAL-ADDRESS`. If you upgraded your package, this is the same address as your current `published-at` address in the `Move.toml`.
       - `VERSION-NUMBER` is `1` if you never upgraded your package. Otherwise, it is a number greater than `1` depending on how many times you upgraded your package. In this case, look up the package at `LATEST-ADDRESS` to determine the version number.
-1. Delete the `published-at` line in your `Move.toml`. Your package is now tracked. You can repeat the above steps to track addresses for additional environments.
+1. Delete the `published-at` line in your `Move.toml`.
+1. Set your package's address to `0x0` in the `[addresses]` section. For example:
+
+```toml
+[package]
+name = "Kiosk"
+
+[dependencies]
+# ... your dependencies ...
+
+[addresses]
+kiosk = "0x0"
+```
+
+Your package is now tracked. You can repeat the above steps to track addresses for additional environments.
 
 ## Package upgrade guidance
 
@@ -44,7 +58,7 @@ For example, you might have an existing package with a `published-at` value in t
 Here are steps to remediate conflicting addresses:
 
 - If the conflict is in a package you maintain:
-  - Delete the `published-at` value in your `Move.toml` if this published address is no longer needed
+  - Delete the `published-at` value in your `Move.toml` if this published address is no longer needed. Then set the package's address to `0x0` in the `[addresses]` section.
   - Alternatively, follow the steps to [adopt automated address management](#adopting-automated-address-management-for-published-packages)
 
 - If the conflict is in a package that you do not maintain (such as a dependency), consider fixing the issue locally with the steps above, or contacting the maintainer to upstream changes.

diff --git a/docs/content/concepts/sui-move-concepts/packages/upgrade.mdx b/docs/content/concepts/sui-move-concepts/packages/upgrade.mdx
@@ -377,23 +377,28 @@ The result includes an **Object changes** section with two pieces of information
 
 You can identify the different objects using the `Object.objectType` value in the response. The `UpgradeCap` entry has a value of `String("0x2::package::UpgradeCap")` and the `objectType` for the package reads `String("<PACKAGE-ID>::sui_package::<MODULE-NAME>")`
 
-To make sure your other packages can use this package as a dependency, you must update the `Move.toml` manifest file for your package to include this information.
-
 <Tabs>
 
 <TabItem value="automated-address-management" label="Automated Addresses">
 
-Add an entry for the package in the `[addresses]` section that points to the value of the on-chain ID:
+:::info
 
-```toml
-[addresses]
-sui_package = "<ORIGINAL-PACKAGE-ID>"
-```
+Beginning with the Sui `v1.29.0` release, published addresses are automatically managed in the `Move.lock` file and you do not need to take further action.
+
+If the package was published or upgraded with a Sui version prior to `v1.29.0`, you can follow [the guide for adopting automated address management](automated-address-management#adopting-automated-address-management-for-published-packages). Alternatively, refer to the `Manual Addresses` tab above for further steps.
+
+:::
+
+After a while, you decide to upgrade your `sui_package` to include some requested features.
 
 </TabItem>
 
 <TabItem value="manual-address-management" label="Manual Addresses">
 
+If your package has not [adopted automated address management](automated-address-management#adopting-automated-address-management-for-published-packages) you'll need to take the following manual steps.
+
+To make sure your other packages can use this package as a dependency, you must update the `Move.toml` manifest file for your package to include published information.
+
 Update the alias address and add a new `published-at` entry in the `[package]` section, both pointing to the value of the on-chain ID:
 
 ```toml
@@ -406,28 +411,8 @@ published-at = "<ORIGINAL-PACKAGE-ID>"
 sui_package = "<ORIGINAL-PACKAGE-ID>"
 ```
 
-</TabItem>
-
-</Tabs>
-
-
 After a while, you decide to upgrade your `sui_package` to include some requested features. Before running the `upgrade` command, you need to edit the manifest again.
 
-<Tabs>
-
-<TabItem value="automated-address-management" label="Automated Addresses">
-
-In the `[addresses]` section, you update the `sui_package` address value to `0x0` again so the validator issues a new address for the upgrade package.
-
-```toml
-[addresses]
-sui_package = "0x0"
-```
-
-</TabItem>
-
-<TabItem value="manual-address-management" label="Manual Addresses">
-
 In the `[addresses]` section, you update the `sui_package` address value to `0x0` again so the validator issues a new address for the upgrade package. You can leave the `published-at` value the same, because it is only read by the toolchain when publishing a dependent package. The saved manifest now resembles the following:
 
 ```toml
@@ -440,12 +425,13 @@ published-at = "<ORIGINAL-PACKAGE-ID>"
 sui_package = "0x0"
 ```
 
+With the new manifest and code in place, you can proceed.
+
 </TabItem>
 
 </Tabs>
 
-
-With the new manifest and code in place, it's time to use the `sui client upgrade` command to upgrade your package. Pass the `UpgradeCap` ID (the `<UPGRADE-CAP-ID>` value from the example) to the `--upgrade-capability` flag.
+Run `sui client upgrade` command to upgrade your package. Pass the `UpgradeCap` ID (the `<UPGRADE-CAP-ID>` value from the example) to the `--upgrade-capability` flag.
 
 ```shell
 sui client upgrade --gas-budget <GAS-BUDGET-AMOUNT> --upgrade-capability <UPGRADE-CAP-ID>
@@ -542,12 +528,14 @@ The result provides a new ID for the upgraded package.
 
 <TabItem value="automated-address-management" label="Automated Addresses">
 
-After upgrading, return the original `sui_package` ID value in the `[addresses]` section:
+:::info
+
+Beginning with the Sui `v1.29.0` release, upgraded addresses are automatically managed in the `Move.lock` file and you do not need to take further action.
+
+If the package was published or upgraded with a Sui version prior to `v1.29.0`, you may follow [the guide for adopting automated address management](automated-address-management#adopting-automated-address-management-for-published-packages). Alternatively, refer to the `Manual Addresses` tab above for further steps.
+
+:::
 
-```toml
-[addresses]
-sui_package = "<ORIGINAL-PACKAGE-ID>"
-```
 </TabItem>
 
 <TabItem value="manual-address-management" label="Manual Addresses">
@@ -567,8 +555,10 @@ sui_package = "<ORIGINAL-PACKAGE-ID>"
 
 Note the `published-at` value changes with every upgrade and needs to be updated after every upgrade.
 
+The ID for the `sui_package` in the `[addresses]` section always points to the original package ID after upgrading. You must always change that value back to `0x0`, however, before running the `upgrade` command so the validator knows to create a new ID for the upgrade.
+
 </TabItem>
 
 </Tabs>
 
-The ID for the `sui_package` in the `[addresses]` section always points to the original package ID after upgrading. You must always change that value back to `0x0`, however, before running the `upgrade` command so the validator knows to create a new ID for the upgrade.
+