docs(releases): coordinator v2.1.0 migration

[SDavidson1177]

Description

Migrating to coordinator v2.1.0 is tedious and error prone, as the migration message must include all active provers, gateways and verifiers. This script simplifies migration by automatically constructing and submitting the migration message. This script allows migration to be performed either directly, or through a governance proposal.

Reference (Old PR): #883

Testing This Script

I manually tested this script on a custom devnet to ensure that it works. The following steps were followed:

1. Deploy a devnet that has the updated Multisig and Coordinator contracts already deployed. The specific Amplifier commit SHA was 62b966a8091d6e69fab87269811aef20007f7ead. In this case, the coordinator v2's code id was 1.

2. Checkout Amplifier tag coordinator-v1.1.0.

3. Build the coordinator v1.1.0 wasm file by running cargo wasm

4. Store the resulting coordinator.wasm file on the devnet by running axelard tx wasm store coordinator.wasm --from amplifier --gas auto --gas-adjustment 2 (Code id = 21)

5. Instantiate coordinator v1.1.0 by running axelard tx wasm instantiate 21 '{"governance_address": "axelar1qmwn4h49quvhu49jmq22g3k0mxe0wy66ry74v5", "service_registry": "axelar1k3rj2w96va80k2uxhfn7nw7nz9xachzwaywpwdz4zygh5pqs8rys783q7y"}' --from amplifier --gas auto --gas-adjustment 2 --label 'Coordinator1.1.0' --admin axelar1qmwn4h49quvhu49jmq22g3k0mxe0wy66ry74v5 (COORD = coordinator address)

6. This devnet had active chains 'ganache-2', 'ganache-3', 'sui' and 'stellar'. I provided coordinator v1.1.0 partial information by uploading provers only for ganache-2 and ganache-3.
   - axelard tx wasm execute $COORD '{"register_prover_contract": {"chain_name": "ganache-2", "new_prover_addr": "axelar1vf4klmh2sazym7fwn4jhn22wvtuvk5fdgakfry772y3ha3rx76zswh8vn4"}}' --from amplifier --gas auto --gas-adjustment 2
   - axelard tx wasm execute $COORD '{"register_prover_contract": {"chain_name": "ganache-3", "new_prover_addr": "axelar18sc4hkxtykcrm7a3hr6uwasw2nynv5zz33f7dlhn96xvfnyadprssm7zrq"}}' --from amplifier --gas auto --gas-adjustment 2

7. Verify that provers have been registered by querying all state axelard q wasm contract-state all $COORD. Found result:
   - key: chain_prover_mapganache-2, value: "axelar1vf4klmh2sazym7fwn4jhn22wvtuvk5fdgakfry772y3ha3rx76zswh8vn4"
   - key: chain_prover_mapganache-3, value: "axelar18sc4hkxtykcrm7a3hr6uwasw2nynv5zz33f7dlhn96xvfnyadprssm7zrq"

8. Perform dry migration to check migration message: npx ts-node cosmwasm/migrate/migrate.ts migrate 1 --address $COORD --deposit 20000000 -e devnet-solomon --dry. Output:

{
  router: 'axelar17axj4laqhjtvxcppxndh3symwap5zj59vw2xsck2g94s0p27qzeqflcuh8',
  multisig: 'axelar1gc9fzyuq7d0djwz5luwl699gacgeddyet6fjtlsuyg99hk67z2nsx5008e',
  chain_contracts: [
    {
      chain_name: 'ganache-2',
      gateway_address: 'axelar127ty3unnq0z9zyvx2x98szdltmqrhxsx3vur36shcrm0khr3070s43uln7',
      verifier_address: 'axelar1kws4tc3xlgxtgtjhggvsyedcslng07ht3x8nes2yvkmpywc0duksdt8jnj',
      prover_address: 'axelar1vf4klmh2sazym7fwn4jhn22wvtuvk5fdgakfry772y3ha3rx76zswh8vn4'
    },
    {
      chain_name: 'ganache-3',
      gateway_address: 'axelar1lmnn52qn9khg6c7hkpu02m4rn70rmm3jqjc79maxldu3ys7y9sdqqw2g68',
      verifier_address: 'axelar1q5zecsgdcyjpv5cl6d6vmvn2v2msgfxly7l7askyv725cspc52aquvjlsr',
      prover_address: 'axelar18sc4hkxtykcrm7a3hr6uwasw2nynv5zz33f7dlhn96xvfnyadprssm7zrq'
    },
    {
      chain_name: 'stellar',
      gateway_address: 'axelar1x87ahtnq70ercg9z07pygd5crml9w0hs73k5hnxffpxwfpq2erfqg43jgt',
      verifier_address: 'axelar1snkn7w8wxueta7d7exzlxv8qh0vgapya7ehg7tk35hr9g52epdxshjfm4f',
      prover_address: 'axelar16wfuqm9t8s0ce3w6jcs5ygmhva3f23geesshrwww6vk43ccnawyqdzrckt'
    },
    {
      chain_name: 'sui',
      gateway_address: 'axelar1fgw034qc53jqg9ycvfcpjc0wj5p30pfg2kh4w5nkpsqpr82aktvsjd5erg',
      verifier_address: 'axelar16ecl5pj7xlzyt0w6y5ugkw4cyyw0kve4cqxu8ecdehzelm76s9qsnk92h4',
      prover_address: 'axelar1k02rghjat08lnn7nhgjpguevkynmwnceaqdurxnrlqsmflu9kt0secr7w3'
    }
  ]

9. Migration message looked fine, as it filled in the missing sui and stellar information. The migration script is run now: npx ts-node cosmwasm/migrate/migrate.ts migrate 1 --address $COORD --deposit 20000000 -e devnet-solomon --proposal -m $MNEMONIC

10. Query the devnet for the proposal information: axelard q gov proposal 3. Output:

content:
  '@type': /cosmwasm.wasm.v1.MigrateContractProposal
  code_id: "1"
  contract: axelar1cwfwu380znew9d7c4krngfhmvv24ehftzg4qw83ynsmkr27774gsze7gnu
  description: Migrate Coordinator v2.1.0
  msg:
    chain_contracts:
    - chain_name: ganache-2
      gateway_address: axelar127ty3unnq0z9zyvx2x98szdltmqrhxsx3vur36shcrm0khr3070s43uln7
      prover_address: axelar1vf4klmh2sazym7fwn4jhn22wvtuvk5fdgakfry772y3ha3rx76zswh8vn4
      verifier_address: axelar1kws4tc3xlgxtgtjhggvsyedcslng07ht3x8nes2yvkmpywc0duksdt8jnj
    - chain_name: ganache-3
      gateway_address: axelar1lmnn52qn9khg6c7hkpu02m4rn70rmm3jqjc79maxldu3ys7y9sdqqw2g68
      prover_address: axelar18sc4hkxtykcrm7a3hr6uwasw2nynv5zz33f7dlhn96xvfnyadprssm7zrq
      verifier_address: axelar1q5zecsgdcyjpv5cl6d6vmvn2v2msgfxly7l7askyv725cspc52aquvjlsr
    - chain_name: stellar
      gateway_address: axelar1x87ahtnq70ercg9z07pygd5crml9w0hs73k5hnxffpxwfpq2erfqg43jgt
      prover_address: axelar16wfuqm9t8s0ce3w6jcs5ygmhva3f23geesshrwww6vk43ccnawyqdzrckt
      verifier_address: axelar1snkn7w8wxueta7d7exzlxv8qh0vgapya7ehg7tk35hr9g52epdxshjfm4f
    - chain_name: sui
      gateway_address: axelar1fgw034qc53jqg9ycvfcpjc0wj5p30pfg2kh4w5nkpsqpr82aktvsjd5erg
      prover_address: axelar1k02rghjat08lnn7nhgjpguevkynmwnceaqdurxnrlqsmflu9kt0secr7w3
      verifier_address: axelar16ecl5pj7xlzyt0w6y5ugkw4cyyw0kve4cqxu8ecdehzelm76s9qsnk92h4
    multisig: axelar1gc9fzyuq7d0djwz5luwl699gacgeddyet6fjtlsuyg99hk67z2nsx5008e
    router: axelar17axj4laqhjtvxcppxndh3symwap5zj59vw2xsck2g94s0p27qzeqflcuh8
  title: Migrate Coordinator v2.1.0
deposit_end_time: "2025-09-09T21:09:21.903064413Z"
final_tally_result:
  abstain: "0"
  "no": "0"
  no_with_veto: "0"
  "yes": "0"
proposal_id: "3"
status: PROPOSAL_STATUS_DEPOSIT_PERIOD
submit_time: "2025-09-09T21:07:51.903064413Z"
total_deposit:
- amount: "20000000"
  denom: usolomon
voting_end_time: "0001-01-01T00:00:00Z"
voting_start_time: "0001-01-01T00:00:00Z"

Greptile Summary

Updated On: 2025-09-08 21:02:17 UTC

This PR adds comprehensive release documentation for the Coordinator v2.1.0 CosmWasm contract deployment. The new release introduces significant functionality that allows the coordinator to programmatically deploy and register gateway, voting verifier, and multisig prover contracts for new chains, effectively automating the chain integration process.

The release requires a coordinated upgrade of three interconnected contracts: Coordinator (v1.1.0 → v2.1.0), Router (v1.2.0 → v1.3.0), and Multisig (v2.1.0 → v2.3.0). All three contracts require state migration, with the Router and Multisig contracts now storing the coordinator's address for proper authorization. The deployment process is structured in phases: upload new bytecode for all three contracts, then migrate each contract in sequence.

The documentation follows the established pattern used throughout the /releases/cosmwasm directory, providing detailed deployment instructions for all environments (devnet-amplifier, stagenet, testnet, mainnet), comprehensive verification steps, and environment-specific configuration tables. This change integrates well with the existing release documentation structure and maintains consistency with other CosmWasm contract releases in terms of format and completeness.

Important Files Changed

Changed Files

Filename	Score	Overview
releases/cosmwasm/2025-09-Coordinator-v2.1.0.md	4/5	Adds comprehensive release documentation for Coordinator v2.1.0 with multi-contract upgrade instructions and verification steps

Confidence score: 4/5

• This PR is safe to merge with minimal risk as it only adds documentation without affecting any executable code
• Score reflects well-structured documentation following established patterns, though some verification commands need completion
• Pay attention to the incomplete verification command on line 118 which needs the actual command to verify coordinator contract version

Sequence Diagram

sequenceDiagram
    participant User
    participant "Governance Proposal System" as Gov
    participant "Router Contract" as Router
    participant "Multisig Contract" as Multisig
    participant "Coordinator Contract" as Coordinator

    User->>Gov: "Submit proposal to upload Router v1.3.0 bytecode"
    Gov-->>User: "Proposal submitted with code ID"
    
    User->>Gov: "Submit migration proposal for Router to v1.3.0"
    Note over User,Gov: Migration message includes coordinator address
    Gov->>Router: "Migrate to v1.3.0 with coordinator address"
    Router-->>Gov: "Migration successful"
    
    User->>Gov: "Submit proposal to upload Multisig v2.3.0 bytecode"
    Gov-->>User: "Proposal submitted with code ID"
    
    User->>Gov: "Submit migration proposal for Multisig to v2.3.0"
    Note over User,Gov: Migration message includes coordinator address
    Gov->>Multisig: "Migrate to v2.3.0 with coordinator address"
    Multisig-->>Gov: "Migration successful"
    
    User->>Gov: "Submit proposal to upload Coordinator v2.1.0 bytecode"
    Gov-->>User: "Proposal submitted with code ID"
    
    User->>Gov: "Submit migration proposal for Coordinator to v2.1.0"
    Note over User,Gov: Uses migrate.ts script to generate migration message
    Gov->>Coordinator: "Migrate to v2.1.0"
    Coordinator-->>Gov: "Migration successful"
    
    Note over Router,Coordinator: Router now stores coordinator address and gives it execution permissions
    Note over Multisig,Coordinator: Multisig now stores coordinator address and gives it execution permissions
    Note over Coordinator: Coordinator can now deploy and register gateway, voting verifier, and multisig prover contracts
    
    User->>Router: "Query contract info to verify v1.3.0"
    Router-->>User: "Contract version: 1.3.0"
    
    User->>Multisig: "Query contract info to verify v2.3.0"
    Multisig-->>User: "Contract version: 2.3.0"
    
    User->>Coordinator: "Query contract info to verify v2.1.0"
    Coordinator-->>User: "Contract version: 2.1.0"

Loading

[greptile-apps]

_{1 file reviewed, no comments}

_{Edit Code Review Bot Settings | Greptile}

[nbayindirli]

lgtm w nits

[kulikthebird]

Two minor little comments from me