fix: sui migration release doc

releases/sui/2025-07-ITS-0.0.0-snapshot.4d2e35d.md

@@ -0,0 +1,243 @@
+# Sui ITS 0.0.0-snapshot.a9aee72
+
+|                | **Owner**                              |
+|----------------|----------------------------------------|
+| **Created By** | @drewstaylor <[email protected]>     |
+| **Deployment** | @blockchainguyy <[email protected]> |
+
+| **Network**          | **Deployment Status** | **Date** |
+|----------------------|-----------------------|----------|
+| **Devnet Amplifier** | TBD                   | TBD      |
+| **Stagenet**         | TBD                   | TBD      |
+| **Testnet**          | TBD                   | TBD      |
+| **Mainnet**          | TBD                   | TBD      |
+
+[Release](https://www.npmjs.com/package/@axelar-network/axelar-cgp-sui/v/0.0.0-snapshot.a9aee72)
+
+## Deployment
+
+```bash
+# Clone latest main and update deps
+npm ci && npm run build
+```
+
+Create a `.env` config. Use `all` for `CHAINS` to run the cmd for every EVM chain, or set a specific chain. On `devnet-amplifier` chain name will be set to `sui-2`.
+
+```yaml
+PRIVATE_KEY=<sui-deployer-key>
+PRIVATE_KEY_TYPE="mnemonic" # Optional
+SIGNATURE_SCHEME=secp256k1
+ENV=<devnet-amplifier|stagenet|testnet|mainnet>
+CHAIN=sui
+```
+
+### ITS Contract Admin & Roles
+
+Many of the below commands require either Owner or Operator privileges on the ITS contract.
+
+#### OwnerCap
+
+Some commands require a wallet that owns the contract's admin capability (`OwnerCap`). By default, this will be the address that deployed the ITS v0 contract.
+
+The commands requiring this capability are:
+* [Upgrading the ITS move contract][]
+* [Enabling the Upgrade][]
+* [Disabling the Legacy Contract][]
+
+#### OperatorCap
+
+Migrating legacy coin metadata requires a `OperatorCap` capability. This is any address added as an operator for the affected coin. By default, the address that deployed and initialized the ITS v0 contract possesses a `OperatorCap`.
+
+The commands requiring this capability are:
+* [Migrating Legacy Tokens][]
+
+### Fetching Legacy Tokens
+
+To fix the issue of some tokens not displaying correctly in wallets, we need to fetch the affected tokens. This list can be fetched before, or after the upgrade.
+
+```bash
+# Save legacy tokens for later migration
+ts-node sui/tokens legacy-coins
+```
+
+### Upgrading the ITS move contract ###
+
+1. Update the release dependency in `package.json`
+
+```diff
+- "@axelar-network/axelar-cgp-sui": "1.1.3",
++ "@axelar-network/axelar-cgp-sui": "0.0.0-snapshot.4d2e35d",
+```
+
+and run
+```bash
+npm i
+```
+
+2. Update the move contracts locally
+
+```bash
+node sui/deploy-contract sync
+```
+3. Do the upgrade tx
+
+```bash
+# Upgrade InterchainTokenService v0 -> v1
+ts-node sui/deploy-contract upgrade InterchainTokenService any_upgrade
+```
+
+### Enabling the Upgrade ###
+
+Migrate version control state to enable the upgrade. 
+
+```bash
+ts-node sui/deploy-contract migrate InterchainTokenService
+```
+
+## Checklist
+
+The following post-upgrade tasks should be performed after the rollout
+
+- [ ] Disable the legacy ITS contract
+- [ ] Verify Version Control state (v0 and v1)
+- [ ] Re-deploy Example contract
+- [ ] Fetch metadata of legacy coins (if not already fetched)
+- [ ] Migrate metadata of legacy coins
+- [ ] Test ITS token deployment and transfers
+- [ ] Test custom token linking
+
+### Disabling the Legacy Contract ###
+
+```bash
+# Disallow all functions in the legacy ITS package
+ts-node sui/contract pause --functions "all" --version "0" InterchainTokenService
+```
+
+### Verify Version Control State
+
+1. All functions should be enabled on v1
+
+```bash
+ts-node sui/its check-version-control 1
+```
+
+2. Only `allow_function` and `disallow_function` should be enabled on v0
+
+```bash
+ts-node sui/its check-version-control 0
+```
+
+### Re-deploy Example contract
+
+Manually Configure Move.toml and Lock File of the `InterchainTokenService` package
+
+Edit `./sui/move/interchain_token_service/Move.toml` with the following changes:
+
+1. Remove the published at field
+```diff
+-   published-at = "..."
+```
+
+2. Update the package address in the `addresses` block:
+
+```diff
+    [addresses]
+-   interchain_token_service = "0x..."
++   interchain_token_service = "0x0"
+```
+
+Edit `./sui/move/interchain_token_service/Move.lock` with the following changes:
+
+1. Append the following blocks to the Lock file:
+
+```diff
++   
++   [env]
++   
++   [env.testnet]
++   chain-id = "4c78adac"
++   original-published-id = "..."
++   latest-published-id = "..."
++   published-version = "2"
+```
+
+2. Ensure the value of `original-published-id` matches the value of `chains.sui.contracts.InterchainTokenService.versions["0"]`, and the value of `latest-published-id` matches the value of `chains.sui.contracts.InterchainTokenService.address`, in the contracts config.
+
+Now, you can re-deploy the Example contract:
+
+```bash
+ts-node sui/deploy-contract deploy Example
+```
+
+### Migrating Legacy Tokens
+
+```bash
+# Migrate legacy tokens in batches of 10 coins per tx
+ts-node sui/its migrate-coin-metadata-all --batch 10
+# Or
+# Migrate legacy tokens in batches of 10, with verbose logging
+ts-node sui/its migrate-coin-metadata-all --batch 10 --logging 10
+```
+
+### Test ITS token deployment and transfers
+
+Test Sui Token Deployment using either lock / unlock or mint / burn token manager
+
+```bash
+# Register token with manager type: lock / unlock
+ts-node sui/its-example deploy-token --origin TST "Test Token" 6
+```
+```bash
+# Register token with manager type: mint / burn
+ts-node sui/its-example deploy-token --tokenManagerMode "mint_burn" --origin TST "Test Token" 6
+```
+
+Testing Sui <-> EVM transfers
+
+1. Send Token Deployment to Another Chain
+```bash
+ts-node sui/its-example send-deployment [coin-symbol] [chain] [gas-value]
+# Example:
+# ts-node sui/its-example send-deployment TST avalanche-fuji 0.5
+```
+
+2. Send Tokens to an EVM Chain
+```bash
+ts-node sui/its-example send-token [coin-symbol] [chain] [recepient-address] [gas-value] [amount-to-send]
+# Example:
+# ts-node sui/its-example send-token TST avalanche-fuji 0xba76c6980428A0b10CFC5d8ccb61949677A61233 0.5 1000
+```
+
+3. Send Tokens Back to Sui, from an EVM Chain
+```bash
+ts-node evm/its interchain-transfer sui [token-id] [recipient] [amount-to-send] --gasValue [gas-value] -n [evm-chain]
+# Example: 
+# ts-node evm/its interchain-transfer sui 0x334e3a13a8d0a8fc8ab5c7828fa4c664821f0a514e2ed447de9d9103352d7873 0x76f89a9b56dc580aed9f97e2b3bd03d8d24464e38522da9464c15103761c6707 25 --gasValue 5000 -n avalanche-fuji
+```
+
+Testing Sui <-> Stellar deployment and transfers:
+
+1. Deploy token to stellar from `<chainName>`
+```bash
+ts-node evm/interchainTokenFactory --action deployRemoteInterchainToken --destinationChain stellar --salt "salt1234" --gasValue [gas-value] -y -n $CHAIN
+```
+
+2. Transfer token to stellar
+```bash
+ts-node evm/its interchain-transfer stellar [token-id] [recipient] 1 --gasValue [gas-value] -n $CHAIN
+```
+
+3. Transfer token back from stellar
+```bash
+ts-node stellar/its interchain-transfer [token-id] $CHAIN [destination-address] 1 --gas-amount [gas-amount]
+```
+
+### Test custom token linking
+
+Deploy a custom token and link it to the token on the origin chain.
+
+```bash
+ts-node sui/its link-coin [coin-symbol] [coin-description] [coin-decimals] [destination-chain] [destination-token-address]
+# Example
+# ts-node sui/its link-coin LINK "Custom link coin" 10 ethereum-sepolia 0x3fc29836e84e471a053d2d9e80494a867d670ead
+```