Skip to content

docs(release): update CW template for coordinator v2 #876

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 15 commits into
base: feat/coordinator_script
Choose a base branch
from
Open

docs(release): update CW template for coordinator v2 #876

Changes from all commits
Commits
Show all changes
15 commits
Select commit Hold shift + click to select a range
100c482
docs: update CW contracts deployment - new Coordinator
kulikthebird Jul 18, 2025
58ea502
chore: update docs
kulikthebird Aug 8, 2025
0045023
chore: add note about admins
kulikthebird Aug 8, 2025
aa80079
chore: consistent naming
kulikthebird Aug 8, 2025
9d93fc3
docs: add contract-admin & formatting
kulikthebird Aug 14, 2025
33fe524
chore: remove TODO
kulikthebird Aug 14, 2025
29286d0
docs: remove redundant step
kulikthebird Aug 14, 2025
6debbab
Merge remote-tracking branch 'origin/feat/coordinator_script' into do…
kulikthebird Aug 14, 2025
d03ba80
docs: add multisig admin support & switch positions - first finish th…
kulikthebird Aug 14, 2025
2d1ebc8
Merge remote-tracking branch 'origin/feat/coordinator_script' into do…
kulikthebird Aug 14, 2025
e459344
docs: remove params that are taken from .env
kulikthebird Aug 14, 2025
f233dee
docs: don't test coordinator implementation here
kulikthebird Aug 16, 2025
5dc0422
Merge remote-tracking branch 'origin/feat/coordinator_script' into do…
kulikthebird Aug 18, 2025
dddc449
docs: update template doc
kulikthebird Aug 18, 2025
a5fdf0a
Merge branch 'feat/coordinator_script' into docs/update_cw_contracts_…
nbayindirli Aug 22, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
184 changes: 41 additions & 143 deletions releases/cosmwasm/EVM-CosmWasm-Release-Template.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,7 @@ ENV=<devnet-amplifier|stagenet|testnet|mainnet>
CHAIN=<chain name>
```

| Network | `deployer address` |
| Network | `DEPLOYER_ADDRESS` |
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure where the deployer address is actually used at the moment. The instantiate message needs to be run by a governance account

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it will change once we have the AddOperator functionality implemented in the Coordinator contract

| -------------------- | ----------------------------------------------- |
| **Devnet-amplifier** | `axelar1zlr7e5qf3sz7yf890rkh9tcnu87234k6k7ytd9` |
| **Stagenet** | `axelar1pumrull7z8y5kc9q4azfrmcaxd8w0779kg6anm` |
Expand All @@ -61,48 +61,19 @@ Gateway (v1.1.1) -> "storeCodeProposalCodeHash": "2ba600ee0d162184c9387eaf6fad65
MultisigProver (v1.1.1) -> "storeCodeProposalCodeHash": "00428ef0483f103a6e1a5853c4b29466a83e5b180cc53a00d1ff9d022bc2f03a"
```

- Add config in `$ENV.json` to deploy Amplifier contracts.

| Network | `governanceAddress` | `adminAddress` |
| Network | `GOVERNANCE_ADDRESS` | `MULTISIG_ADMIN_ADDRESS` |
| -------------------- | ----------------------------------------------- | ----------------------------------------------- |
| **Devnet-amplifier** | `axelar1zlr7e5qf3sz7yf890rkh9tcnu87234k6k7ytd9` | `axelar1zlr7e5qf3sz7yf890rkh9tcnu87234k6k7ytd9` |
| **Stagenet** | `axelar10d07y265gmmuvt4z0w9aw880jnsr700j7v9daj` | `axelar1l7vz4m5g92kvga050vk9ycjynywdlk4zhs07dv` |
| **Testnet** | `axelar10d07y265gmmuvt4z0w9aw880jnsr700j7v9daj` | `axelar17qafmnc4hrfa96cq37wg5l68sxh354pj6eky35` |
| **Mainnet** | `axelar10d07y265gmmuvt4z0w9aw880jnsr700j7v9daj` | `axelar1pczf792wf3p3xssk4dmwfxrh6hcqnrjp70danj` |

| Network | `serviceName` | `votingThreshold` | `signingThreshold` | `confirmationHeight` |
| -------------------- | ------------- | ----------------- | ------------------ | -------------------- |
| **Devnet-amplifier** | `validators` | `["6", "10"]` | `["6", "10"]` | `1` |
| **Stagenet** | `amplifier` | `["51", "100"]` | `["51", "100"]` | `1` |
| **Testnet** | `amplifier` | `["51", "100"]` | `["51", "100"]` | `1` |
| **Mainnet** | `amplifier` | `["2", "3"]` | `["2", "3"]` | `1` |

```bash
# Add under `config.axelar.contracts.VotingVerifier` based on Network
"$CHAIN" : {
"governanceAddress": "[governance address]",
"serviceName": "[service name]",
"sourceGatewayAddress": "[external gateway address]",
"votingThreshold": "[voting threshold]",
"blockExpiry": 10,
"confirmationHeight": 1000000, # if $CHAIN uses a custom finality mechanism such as the "finalized" tag, set this value very high (i.e. 1000000) to prevent accidental use
"msgIdFormat": "hex_tx_hash_and_event_index",
"addressFormat": "eip55"
}

# Add under `config.axelar.contracts.MultisigProver` based on Network
"$CHAIN" : {
"governanceAddress": "[governance address]",
"adminAddress": "[admin address]",
"signingThreshold": "[signing threshold]",
"serviceName": "[service name]",
"verifierSetDiffThreshold": 0,
"encoder": "abi",
"keyType": "ecdsa"
}
Comment on lines -81 to -102
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

why are we removing these. There are certain configuration that still need to be published and the scripts dont do that

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's covered by the new script

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

#901

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • see the ts-node cosmwasm/coordinator.ts instantiate command below. It is automatically saved in the config file

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

i dont agree with this approach, in the new scripts and PR you have set constant DEFAULT value that only matches testnet, but you can see that the values are not equivalent across all the environments so this would make it harder for deployer since now they need to still pass values in manually.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

User can override the DEFAULT values by using CLI options - everything can be updated when using a single CLI command. The default values were taken directly from this document. We can always remove them and make the options required to be provided by a user

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please check the new configure command

```

### Instantiate Amplifier contracts
| Network | `SERVICE_NAME` | `VOTING_THRESHOLD` | `SIGNING_THRESHOLD` | `CONFIRMATION_HEIGHT` |
| -------------------- | -------------- | ------------------ | ------------------- | --------------------- |
| **Devnet-amplifier** | `validators` | `["6", "10"]` | `["6", "10"]` | `1` |
| **Stagenet** | `amplifier` | `["51", "100"]` | `["51", "100"]` | `1` |
| **Testnet** | `amplifier` | `["51", "100"]` | `["51", "100"]` | `1` |
| **Mainnet** | `amplifier` | `["2", "3"]` | `["2", "3"]` | `1` |

| Network | `CONTRACT_ADMIN` |
| -------------------- | ----------------------------------------------- |
Expand All @@ -113,22 +84,29 @@ MultisigProver (v1.1.1) -> "storeCodeProposalCodeHash": "00428ef0483f103a6e1a585

`CONTRACT_ADMIN` is the wasm contract admin address for contract upgrades.

1. Instantiate `VotingVerifier`

1. Configure a new chain. Use `ts-node cosmwasm/coordinator.ts configure --help` to see all the parameters that can be set up. Otherwise default values will be assigned.
```bash
ts-node ./cosmwasm/deploy-contract.js instantiate -c VotingVerifier --fetchCodeId --instantiate2 --admin $CONTRACT_ADMIN
ts-node cosmwasm/coordinator.ts configure \
--contract-admin "$CONTRACT_ADMIN" \
--multisig-admin "$MULTISIG_ADMIN_ADDRESS" \
--service-name "$SERVICE_NAME" \
--voting-threshold "$VOTING_THRESHOLD" \
--signing-threshold "$SIGNING_THRESHOLD" \
--confirmation-height "$CONFIRMATION_HEIGHT" \
--source-gateway-address "$SOURCE_GATEWAY_ADDRESS"
```

2. Instantiate `Gateway`

2. Review changes made by the previous command to the `$ENV.json` config file. Instantiate **Gateway**, **Verifier** and **Prover** contracts using **Coordinator**
```bash
ts-node ./cosmwasm/deploy-contract.js instantiate -c Gateway --fetchCodeId --instantiate2 --admin $CONTRACT_ADMIN
ts-node cosmwasm/coordinator.ts instantiate \
--run-as "$GOVERNANCE_ADDRESS"
```

3. Instantiate `MultisigProver`

3. Register the new chain in the **Coordinator** contract:
```bash
ts-node ./cosmwasm/deploy-contract.js instantiate -c MultisigProver --fetchCodeId --instantiate2 --admin $CONTRACT_ADMIN
ts-node cosmwasm/coordinator.ts register-deployment \
--run-as "$GOVERNANCE_ADDRESS"
```

4. Set environment variables
Expand All @@ -137,11 +115,9 @@ ts-node ./cosmwasm/deploy-contract.js instantiate -c MultisigProver --fetchCodeI

```bash
VOTING_VERIFIER=$(cat ./axelar-chains-config/info/$ENV.json | jq ".axelar.contracts.VotingVerifier[\"$CHAIN\"].address" | tr -d '"')
GATEWAY=$(cat ./axelar-chains-config/info/$ENV.json | jq ".axelar.contracts.Gateway[\"$CHAIN\"].address" | tr -d '"')
MULTISIG_PROVER=$(cat ./axelar-chains-config/info/$ENV.json | jq ".axelar.contracts.MultisigProver[\"$CHAIN\"].address" | tr -d '"')
MULTISIG=$(cat ./axelar-chains-config/info/$ENV.json | jq .axelar.contracts.Multisig.address | tr -d '"')
REWARDS=$(cat ./axelar-chains-config/info/$ENV.json | jq .axelar.contracts.Rewards.address | tr -d '"')
ROUTER=$(cat ./axelar-chains-config/info/$ENV.json | jq .axelar.contracts.Router.address | tr -d '"')
```

- Gov proposal environment variables. Update these for each network
Expand All @@ -153,68 +129,15 @@ ROUTER=$(cat ./axelar-chains-config/info/$ENV.json | jq .axelar.contracts.Router
| **Testnet** | `axelar17qafmnc4hrfa96cq37wg5l68sxh354pj6eky35` | `1000000uaxl` |
| **Mainnet** | `axelar1pczf792wf3p3xssk4dmwfxrh6hcqnrjp70danj` | `1000000uaxl` |

```bash
PROVER_ADMIN=[prover admin who is responsible for the contract's operations]
REWARD_AMOUNT=[reward amount]
EPOCH_DURATION=[epoch duration according to the environment]
```

- Add a community post for the mainnet proposal. i.e: https://community.axelar.network/t/proposal-add-its-hub-to-mainnet/3227
- Note: [ITS proposal](../evm/EVM-ITS-Release-Template.md) should also be submitted at this time if possible.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this step is already in the guide here, as step 10 (now step 6)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I refactored a little bit the - Note: all the following governance proposals should be submitted at one time so deployment doesn't get held up while waiting for voting. [ITS proposal](../evm/EVM-ITS-Release-Template.md) should also be submitted at this time if possible. note. It says that we can proceed with ITS in parallel, though I didn't check if that makes sense - only wanted to keep it as it was

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

lets just add the instruction to go to step 6 for the proposal instructions rather than linking the external guide

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I read the EVM-ITS-Release-Template.md and it seems that the doc and the step.7 are something different. This should be analyzed from the ITS perspective once again


- Note: all the following governance proposals should be submitted at one time so deployment doesn't get held up while waiting for voting. [ITS proposal](../evm/EVM-ITS-Release-Template.md) should also be submitted at this time if possible.

5. Register Gateway at the Router

```bash
ts-node cosmwasm/submit-proposal.js execute \
-c Router \
-t "Register Gateway for $CHAIN" \
-d "Register Gateway address for $CHAIN at Router contract" \
--msg "{
\"register_chain\": {
\"chain\": \"$CHAIN\",
\"gateway_address\": \"$GATEWAY\",
\"msg_id_format\": \"hex_tx_hash_and_event_index\"
}
}"
```

6. Register prover contract on coordinator

```bash
ts-node cosmwasm/submit-proposal.js execute \
-c Coordinator \
-t "Register Multisig Prover for $CHAIN" \
-d "Register Multisig Prover address for $CHAIN at Coordinator contract" \
--msg "{
\"register_prover_contract\": {
\"chain_name\": \"$CHAIN\",
\"new_prover_addr\": \"$MULTISIG_PROVER\"
}
}"
```

7. Authorize `$CHAIN` Multisig Prover on Multisig

```bash
ts-node cosmwasm/submit-proposal.js execute \
-c Multisig \
-t "Authorize Multisig Prover for $CHAIN" \
-d "Authorize Multisig Prover address for $CHAIN at Multisig contract" \
--msg "{
\"authorize_callers\": {
\"contracts\": {
\"$MULTISIG_PROVER\": \"$CHAIN\"
}
}
}"
```

8. Create reward pool for voting verifier
5. Create reward pool for voting verifier

#### Rewards

| Network | `epoch_duration` | `participation_threshold` | `rewards_per_epoch` |
| Network | `EPOCH_DURATION` | `PARTICIPATION_THRESHOLD` | `REWARDS_PER_EPOCH` |
| -------------------- | ---------------- | ------------------------- | ------------------- |
| **Devnet-amplifier** | `100` | `[\"7\", \"10\"]` | `100` |
| **Stagenet** | `600` | `[\"7\", \"10\"]` | `100` |
Expand All @@ -230,8 +153,8 @@ ts-node cosmwasm/submit-proposal.js execute \
\"create_pool\": {
\"params\": {
\"epoch_duration\": \"$EPOCH_DURATION\",
\"participation_threshold\": [participation threshold],
\"rewards_per_epoch\": \"[rewards per epoch]\"
\"participation_threshold\": \"$PARTICIPATION_THRESHOLD\",
\"rewards_per_epoch\": \"$REWARDS_PER_EPOCH\"
},
\"pool_id\": {
\"chain_name\": \"$CHAIN\",
Expand All @@ -241,7 +164,8 @@ ts-node cosmwasm/submit-proposal.js execute \
}"
```

9. Create reward pool for multisig

6. Create reward pool for multisig

```bash
ts-node cosmwasm/submit-proposal.js execute \
Expand All @@ -252,8 +176,8 @@ ts-node cosmwasm/submit-proposal.js execute \
\"create_pool\": {
\"params\": {
\"epoch_duration\": \"$EPOCH_DURATION\",
\"participation_threshold\": [participation threshold],
\"rewards_per_epoch\": \"[rewards per epoch]\"
\"participation_threshold\": \"$PARTICIPATION_THRESHOLD\",
\"rewards_per_epoch\": \"$REWARDS_PER_EPOCH\"
},
\"pool_id\": {
\"chain_name\": \"$CHAIN\",
Expand All @@ -263,7 +187,7 @@ ts-node cosmwasm/submit-proposal.js execute \
}"
```

10. Register ITS edge contract on ITS Hub
7. Register ITS edge contract on ITS Hub

Proceed with this step only if ITS deployment on $CHAIN is confirmed. Add the following to `contracts` in the `$CHAIN` config within `ENV.json`:

Expand Down Expand Up @@ -291,56 +215,30 @@ ts-node cosmwasm/submit-proposal.js \

- Please remove this temporary config after submitting the proposal and reset contracts to an empty object.

11. Add funds to reward pools from a wallet containing the reward funds `$REWARD_AMOUNT`
8. Add funds to reward pools from a wallet containing the reward funds `$REWARD_AMOUNT`

```bash
axelard tx wasm execute $REWARDS "{ \"add_rewards\": { \"pool_id\": { \"chain_name\": \"$CHAIN\", \"contract\": \"$MULTISIG\" } } }" --amount $REWARD_AMOUNT --from $WALLET

axelard tx wasm execute $REWARDS "{ \"add_rewards\": { \"pool_id\": { \"chain_name\": \"$CHAIN\", \"contract\": \"$VOTING_VERIFIER\" } } }" --amount $REWARD_AMOUNT --from $WALLET
```

12. Confirm proposals have passed
9. Confirm proposals have passed

- Check proposals on block explorer (i.e. https://axelarscan.io/proposals)
- "Register Gateway for `$CHAIN`"
- "Register Multisig Prover for `$CHAIN`"
- "Authorize Multisig Prover for `$CHAIN`"
- "Instantiate amplifier contracts"
- "Register chain deployment"
- "Create pool for `$CHAIN` in `$CHAIN` voting verifier"
- "Create pool for `$CHAIN` in axelar multisig"
- (optional) "Register `$CHAIN` on ITS Hub"

- Check Gateway registered at Router
```bash
axelard q wasm contract-state smart $ROUTER "{\"chain_info\": \"$CHAIN\"}" --output json | jq .
# You should see something like this:
{
"data": {
"name": \"$CHAIN\",
"gateway": {
"address": "axelar1jah3ac59xke2r266yjhh45tugzsvnlzsefyvx6jgp0msk6tp7vqqaktuz2"
},
"frozen_status": 0,
"msg_id_format": "hex_tx_hash_and_event_index"
}
}
```

- Check Multisig Prover authorized on Multisig
```bash
axelard q wasm contract-state smart $MULTISIG "{\"is_caller_authorized\": {\"contract_address\": \"$MULTISIG_PROVER\", \"chain_name\": \"$CHAIN\"}}" --output json | jq .
# Result should look like:
{
"data": true
}
```

Comment on lines -312 to -336
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I removed the registration and authorization checks since they are now part of the Coordinator contract responsibility. We should not test the implementation details of the contract during each release

- Check reward pool to confirm funding worked:

```bash
ts-node cosmwasm/query.js rewards -n $CHAIN
```

13. Update `ampd` with the `$CHAIN` chain configuration. Verifiers should use their own `$CHAIN` RPC node for the `http_url` in production.
10. Update `ampd` with the `$CHAIN` chain configuration. Verifiers should use their own `$CHAIN` RPC node for the `http_url` in production.

| Network | `http_url` |
| -------------------- | ----------------- |
Expand Down Expand Up @@ -370,13 +268,13 @@ cosmwasm_contract="$VOTING_VERIFIER"
type="EvmVerifierSetVerifier"
```

14. Update `ampd` with the `$CHAIN` chain configuration.
11. Update `ampd` with the `$CHAIN` chain configuration.

```bash
ampd register-chain-support "[service name]" $CHAIN
ampd register-chain-support "$SERVICE_NAME" $CHAIN
```

15. Create genesis verifier set
12. Create genesis verifier set

Note that this step can only be run once a sufficient number of verifiers have registered.

Expand Down