feat(sui): custom token linking v1 register coins and migrate legacy coin registrations (axelarnetwork#856)

Co-authored-by: Blockchain Guy <[email protected]>

Author: drewstaylor

common/utils.js

@@ -115,6 +115,11 @@ const isString = (arg) => {
     return typeof arg === 'string';
 };
 
+const isNonArrayObject = (arg) => {
+    if (!arg) return false;
+    return typeof arg === 'object' && Array.isArray(arg) === false;
+};
+
 const isNonEmptyString = (arg) => {
     return isString(arg) && arg !== '';
 };
@@ -426,6 +431,7 @@ function isValidSvmAddressFormat(address) {
 const validationFunctions = {
     isNonEmptyString,
     isNumber,
+    isNonArrayObject,
     isValidNumber,
     isValidDecimal,
     isNumberArray,
@@ -805,6 +811,7 @@ module.exports = {
     isStringArray,
     isStringLowercase,
     isNumber,
+    isNonArrayObject,
     isValidNumber,
     isValidDecimal,
     isNumberArray,

releases/sui/2025-07-ITS-0.0.0-snapshot.3e3ec75.md

@@ -0,0 +1,141 @@
+# Sui ITS 0.0.0-snapshot.3e3ec75
+
+|                | **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.3e3ec75)
+
+## 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 effected 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 effected 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.3e3ec75",
+```
+
+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
+
+### 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
+```
+
+### 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
+
+Test interchain token deployment and transfer with EVM(consensus and amplifier) chains and Stellar.

sui/README.md

@@ -229,6 +229,15 @@ policy should be one of the following:
 
 Provide `--txFilePath` with `--offline` to generate tx data file for offline signing.
 
+### Migrating Post-Upgrade
+
+After upgrading a package, state migrations (e.g. for [versioned](https://docs.sui.io/references/framework/sui/versioned) packages) can be called using the `migrate` command.
+
+
+```bash
+ts-node sui/deploy-contract.js migrate AxelarGateway
+```
+
 ### Multisig Operations
 
 To create a Multisig, follow the documentation [here](https://docs.sui.io/guides/developer/cryptography/multisig).
@@ -432,6 +441,84 @@ Remove trusted chains
 ts-node sui/its.js remove-trusted-chains <sourceChain> <sourceChain2> ...
 ```
 
+## Registering Coins
+
+### Register Coin from Info (symbol, name and decimals)
+
+```bash
+ts-node sui/its.js register-coin-from-info <symbol> <name> <decimals>
+```
+
+### Register Coin from Metadata 
+
+(see: [sui::coin::CoinMetadata](https://docs.sui.io/references/sui-api/sui-graphql/reference/types/objects/coin-metadata))
+
+```bash
+ts-node sui/its.js register-coin-from-metadata <symbol> <name> <decimals>
+```
+
+### Register Custom Coin
+
+If a `channel` id is present in the `options` array (e.g. `--channel <channel>`) it will be used, otherwise a new `channel` will be created and transferred to the sender. A `salt` for the registration transaction will automatically be created.
+
+```bash
+ts-node sui/its.js register-custom-coin <symbol> <name> <decimals>
+```
+
+## Migrating Legacy Coin Registrations
+
+### Migrate Coin Metadata
+
+_Added in v1 to fix coins that were not displaying correctly in wallet softwares. Only callable for coins with metadata owned by ITS. Will [publicly freeze](https://docs.sui.io/references/framework/sui/transfer#sui_transfer_public_freeze_object) a coin's metadata, making it a publicly shared object._
+
+```bash
+ts-node sui/its.js migrate-coin-metadata <symbol>
+```
+
+## Coin Linking
+
+### Give Unlinked Coin
+
+Deploys a coin on Sui, registers it as custom coin and gives its treasury capability to ITS. Treasury capability will be reclaimable if the `--treasuryCapReclaimer` flag is passed to the command options.
+
+```bash
+ts-node sui/its give-unlinked-coin [options] <symbol> <name> <decimals>
+```
+
+### Remove Unlinked Coin
+
+Removes a coin from ITS and returns its TreasuryCap to the caller. Caller must own the coin's TreasuryCapReclaimer.
+
+```bash
+ts-node sui/its remove-unlinked-coin [options] <symbol>
+```
+
+### Link Coin
+
+Deploys a source coin and links it with a destination chain coin. If a `channel` id is present in the `options` array (e.g. `--channel <channel>`) it will be used, otherwise a new `channel` will be created and transferred to the sender. A `salt` for the coin registration and linking transactions will automatically be created.
+
+```bash
+ts-node sui/its link-coin <symbol> <name> <decimals> <destinationChain> <destinationAddress>
+```
+
+## Treasury Management
+
+### Remove Treasury Cap
+
+Transfers the coin's `TreasuryCap` to the coin deployer and reclaims mint/burn permission from ITS.
+
+```bash
+ts-node sui/its remove-treasury-cap [options] <symbol>
+```
+
+### Restore Treasury Cap
+
+Restore a coin's TreasuryCap to ITS after calling remove-treasury-cap, giving mint/burn permission back to ITS.
+
+```bash
+ts-node sui/its restore-treasury-cap [options] <symbol>
+```
+
 ## Sui Contract Verification
 
 This script generates a `verification` folder inside the `move` directory, which contains ZIP files for each contract to be used for verification. Before zipping, a `deps` subdirectory is added to each contract, and the local dependency paths in the `Move.toml` file are updated to reference the `deps` folder. 

sui/contract.js

@@ -118,12 +118,10 @@ async function pause(keypair, client, chain, args, options) {
 
             let allowedFunctions = allowedFunctionsArray[version];
 
-            // Do not dissalow `allow_function` because that locks the gateway forever.
-            if (Number(version) === allowedFunctionsArray.length - 1) {
-                allowedFunctions = allowedFunctions.filter(
-                    (allowedFunction) => allowedFunction !== 'allow_function' && allowedFunction !== 'disallow_function',
-                );
-            }
+            // Do not disable `allow_function` because that locks the contract forever.
+            allowedFunctions = allowedFunctions.filter((allowedFunction) => {
+                return allowedFunction !== 'allow_function' && allowedFunction !== 'disallow_function';
+            });
 
             printInfo(`Functions that will be disallowed for version ${version}`, allowedFunctions);
 

sui/deploy-contract.js

@@ -25,7 +25,9 @@ const {
     getStructs,
     restrictUpgradePolicy,
     broadcastRestrictedUpgradePolicy,
+    broadcastFromTxBuilder,
 } = require('./utils');
+const GatewayCli = require('./gateway');
 
 /**
  * Move Package Directories
@@ -442,6 +444,47 @@ async function upgrade(keypair, client, supportedPackage, policy, config, chain,
     }
 }
 
+async function migrate(keypair, client, supportedPackage, config, chain, options) {
+    const { packageName } = supportedPackage;
+
+    validateParameters({
+        // Contract
+        isNonArrayObject: { contractEntry: chain.contracts[packageName] },
+        isNonEmptyString: { contractAddress: chain.contracts[packageName].address },
+        // OwnerCap
+        isNonArrayObject: { ownerEntry: chain.contracts[packageName].objects },
+        isNonEmptyString: { ownerAddress: chain.contracts[packageName].objects.OwnerCap },
+    });
+    const contractConfig = chain.contracts[packageName];
+    const ownerCap = contractConfig.objects.OwnerCap;
+
+    const builder = new TxBuilder(client);
+
+    switch (packageName) {
+        case 'AxelarGateway': {
+            const result = await GatewayCli.migrate(keypair, client, config, chain, contractConfig, null, options);
+            return await broadcast(client, keypair, result.tx, result.message, options);
+        }
+        case 'InterchainTokenService': {
+            const InterchainTokenService = contractConfig.objects.InterchainTokenService;
+
+            if (typeof InterchainTokenService !== 'string') throw new Error(`Cannot find object of specified contract: ${packageName}`);
+
+            await builder.moveCall({
+                target: `${contractConfig.address}::interchain_token_service::migrate`,
+                arguments: [InterchainTokenService, ownerCap],
+            });
+
+            break;
+        }
+        default: {
+            throw new Error(`Post-upgrade migration not supported for ${packageName}`);
+        }
+    }
+
+    if (packageName !== 'AxelarGateway') await broadcastFromTxBuilder(builder, keypair, `Migrate Package ${packageName}`, options);
+}
+
 async function syncPackages(keypair, client, config, chain, options) {
     // Remove the move directory and its contents if it exists
     fs.rmSync(moveDir, { recursive: true, force: true });
@@ -528,6 +571,7 @@ if (require.main === module) {
     // 2nd level commands
     const deployCmd = new Command('deploy').description('Deploy a Sui package');
     const upgradeCmd = new Command('upgrade').description('Upgrade a Sui package');
+    const migrateCmd = new Command('migrate').description('Migrate a Sui package after upgrading');
 
     // 3rd level commands for `deploy`
     const deployContractCmds = supportedPackages.map((supportedPackage) => {
@@ -557,21 +601,42 @@ if (require.main === module) {
             });
     });
 
+    // 3rd level commands for `migrate`
+    const migrateContractCmds = supportedPackages.map((supportedPackage) => {
+        const { packageName } = supportedPackage;
+        return new Command(packageName)
+            .description(`Migrate ${packageName} contract after upgrade`)
+            .command(`${packageName}`)
+            .addOption(new Option('--migrate-data <migrateData>', 'bcs encoded data to pass to the migrate function'))
+            .addOption(new Option('--sender <sender>', 'transaction sender'))
+            .addOption(new Option('--digest <digest>', 'digest hash for upgrade'))
+            .addOption(new Option('--offline', 'store tx block for sign'))
+            .addOption(new Option('--txFilePath <file>', 'unsigned transaction will be stored'))
+            .action((options) => {
+                mainProcessor([supportedPackage], options, migrate);
+            });
+    });
+
     const syncCmd = new Command('sync').description('Sync local Move packages with deployed addresses').action((options) => {
         mainProcessor([], options, syncPackages);
     });
 
     // Add 3rd level commands to 2nd level command `upgrade`
     upgradeContractCmds.forEach((cmd) => upgradeCmd.addCommand(cmd));
 
+    // Add 3rd level commands to 2nd level command `migrate`
+    migrateContractCmds.forEach((cmd) => migrateCmd.addCommand(cmd));
+
     // Add base options to all 2nd and 3rd level commands
     addOptionsToCommands(deployCmd, addBaseOptions);
     addOptionsToCommands(upgradeCmd, addBaseOptions);
+    addOptionsToCommands(migrateCmd, addBaseOptions);
     addBaseOptions(syncCmd);
 
     // Add 2nd level commands to 1st level command
     program.addCommand(deployCmd);
     program.addCommand(upgradeCmd);
+    program.addCommand(migrateCmd);
     program.addCommand(syncCmd);
 
     program.parse();