|
| 1 | +# Mainnet upgrade: v1.3 |
| 2 | + |
| 3 | +import { Callout } from "/src/components/callout"; |
| 4 | + |
| 5 | +Instructions for the `v1.3` mainnet upgrade to axelar-core `v1.3.2`. |
| 6 | + |
| 7 | +The release for the upgrade can be found [here](https://github.com/axelarnetwork/axelar-core/releases/tag/v1.3.2). |
| 8 | + |
| 9 | +Upgrade height `21163285` [countdown](https://www.mintscan.io/axelar/block/21163285) |
| 10 | + |
| 11 | +## Binary Types |
| 12 | + |
| 13 | +The v1.3.2 release provides **two Linux binaries**: |
| 14 | + |
| 15 | +- **[Static](https://github.com/axelarnetwork/axelar-core/releases/download/v1.3.2/axelard-linux-amd64-v1.3.2-static) binary (`axelard-linux-amd64-v1.3.2-static`)** |
| 16 | + - Contains a statically linked `libwasmvm` |
| 17 | + - **Does not require** installing or configuring `libwasmvm` |
| 18 | + |
| 19 | +- **[Dynamically](https://github.com/axelarnetwork/axelar-core/releases/download/v1.3.2/axelard-linux-amd64-v1.3.2) linked binary (`axelard-linux-amd64-v1.3.2`)** |
| 20 | + - Requires upgrading `libwasmvm` to **v2.2.4** |
| 21 | + - Must add the library directory to `LD_LIBRARY_PATH` |
| 22 | + |
| 23 | +<Callout type="warning" emoji="⚠️"> |
| 24 | + `axelard` must be built with `go-1.25` for this release. |
| 25 | + |
| 26 | + If using the **dynamically linked** binary, update `wasmvm` from `v1.5.8` to `v2.2.4` |
| 27 | + ([libwasmvm.x86_64.so](https://github.com/CosmWasm/wasmvm/releases/tag/v2.2.4)) |
| 28 | + and ensure the directory containing the library is added to `LD_LIBRARY_PATH`. |
| 29 | + |
| 30 | + If using the **static** binary (`*-static`), **no wasmvm installation is required**. |
| 31 | + |
| 32 | + If using the community node setup scripts, please update to the latest commit on `main` first. |
| 33 | + The dynamic `wasmvm` library will be auto-downloaded to `$AXELARD_HOME/lib`, |
| 34 | + but you'll still need to add it to `LD_LIBRARY_PATH` before running the script. |
| 35 | + |
| 36 | + For verifiers, prepare to update [ampd](#ampd). |
| 37 | +</Callout> |
| 38 | + |
| 39 | +## About the v1.3 upgrade |
| 40 | + |
| 41 | +The `v1.3` upgrade is required to support the Axelar Network's migration to [Cosmos SDK v0.50](https://cosmos-docs.mintlify.app/sdk/v0.50/build). This upgrade reduces block times from **5s → 1s** and brings the latest SDK security features. |
| 42 | + |
| 43 | +This is a consensus-breaking release for Axelar mainnet. |
| 44 | + |
| 45 | +## Upgrade Instructions |
| 46 | + |
| 47 | +1. If you're a validator or have delegated to one, please vote for the upgrade proposal via: |
| 48 | + |
| 49 | +```bash |
| 50 | +axelard tx gov vote 421 yes --from validator |
| 51 | +``` |
| 52 | + |
| 53 | +2. Wait for the proposed upgrade block, `21163285`. Your node will panic at that block height with a log: `{"level":"error","module":"consensus","err":"UPGRADE \"v1.3\" NEEDED at height: 21163285",`. |
| 54 | + |
| 55 | +Stop your node after chain halt: |
| 56 | + |
| 57 | +```bash |
| 58 | +pkill -f 'axelard start' |
| 59 | +# Validators also need to stop vald/tofnd |
| 60 | +pkill -f 'vald-start' |
| 61 | +pkill -f tofnd |
| 62 | +``` |
| 63 | + |
| 64 | +3. Backup the state: |
| 65 | + |
| 66 | +```bash |
| 67 | +cp -r ~/.axelar/.core/data ~/.axelar-dojo-1-upgrade-1.3.2/.core/data |
| 68 | +``` |
| 69 | + |
| 70 | +<Callout type="warning" emoji="⚠️"> |
| 71 | + ⚠️ **Important:** If you backup the entire folder, `~/.axelar/.core`, that'll |
| 72 | + also include your private keys (inside `config` and `keyring-file` |
| 73 | + subfolders). That can be dangerous if anyone gets access to your backups. We |
| 74 | + recommend backing up keys separately when you first create your node, and then |
| 75 | + excluding them from any data backups. |
| 76 | +</Callout> |
| 77 | + |
| 78 | +4. Update `app.toml`. Add the following parameters at the root level (required for optimal migration performance): |
| 79 | + |
| 80 | +```toml |
| 81 | +iavl-cache-size = 0 |
| 82 | +iavl-disable-fastnode = true |
| 83 | +``` |
| 84 | + |
| 85 | +5. Lower the `timeout_commit` config in `~/.axelar/config/config.toml` from `5s` to `1s`. |
| 86 | + |
| 87 | +6. Restart your `axelard` node with the new `v1.3.2` build as well as `ampd` with the new `v1.13.2` binaries. |
| 88 | + |
| 89 | +7. If you're a validator also restart `vald` with `v1.3.2` and `tofnd` with `v1.0.1`. |
| 90 | + |
| 91 | +### Migration expectations |
| 92 | + |
| 93 | +- **Archival nodes:** ~12.5 hours migration + catch-up time |
| 94 | +- **Validator / RPC nodes:** ~1 hour migration + catch-up time |
| 95 | + |
| 96 | +**Important:** Do not restart the node during migration, as any restart will cause the migration to begin again. Block production will resume once a quorum of validators by stake have completed the upgrade. |
| 97 | + |
| 98 | +### Example using join scripts (axelarate-community) |
| 99 | + |
| 100 | +```bash |
| 101 | +# in axelarate-community repo |
| 102 | +git checkout main |
| 103 | +git pull |
| 104 | +KEYRING_PASSWORD="pw-1" ./scripts/node.sh -n mainnet -a v1.3.2 |
| 105 | +# For validators, restart vald/tofnd |
| 106 | +KEYRING_PASSWORD="pw-1" TOFND_PASSWORD="pw-2" ./scripts/validator-tools-host.sh -n mainnet -a v1.3.2 -q v1.0.1 |
| 107 | +``` |
| 108 | + |
| 109 | +## Ampd |
| 110 | + |
| 111 | +For verifiers, a new `ampd` [upgrade](https://github.com/axelarnetwork/axelar-contract-deployments/blob/main/releases/ampd/2025-11-17-ampd-v1.13.2.md) is required to support `axelard v1.3.2`. The `ampd` upgrade must be done **after** the `axelard` upgrade. |
| 112 | + |
| 113 | +### Instructions |
| 114 | + |
| 115 | +Restart `ampd` with the new binary after deploying axelard `v1.3.2`. The relevant `ampd` release is available [here](https://github.com/axelarnetwork/axelar-amplifier/releases/tag/ampd-v1.13.2). |
| 116 | + |
| 117 | +## Troubleshooting |
| 118 | + |
| 119 | +If you encounter a **hash error**, ensure you have `libwasmvm` v2.2.4: |
| 120 | + |
| 121 | +https://github.com/CosmWasm/wasmvm/releases/download/v2.2.4/libwasmvm.x86_64.so |
| 122 | + |
| 123 | +Before restarting your node: |
| 124 | + |
| 125 | +1. Make sure `LD_LIBRARY_PATH` includes the directory of `libwasmvm` (dynamic binary only). |
| 126 | +2. Docker users do **not** need to modify anything. |
| 127 | + |
| 128 | +If you see the error `undefined symbol: migrate_with_info`, switch to using the statically linked binary (`axelard-linux-amd64-v1.3.2-static`). If you need to use a dynamically linked binary, make sure you have the correct `libwasmvm` version (`2.2.4`). |
| 129 | + |
| 130 | +If you see the message `migrating module auth from version 2 to version 3`, the upgrade has started and is progressing normally. |
| 131 | + |
| 132 | +If you see the error `ERR failed to get consensus params err="collections: not found: key 'no_key' of type ...`, no action is necessary. This is expected during preblock so the upgrade plan can be executed and the consensus params set for the first time in the new format. |
| 133 | + |
| 134 | +Required RAM is **64 GB**. If your process runs out of memory during the upgrade you will have to increase your system RAM to at least 64 GB and the upgrade will restart from the beginning (progress is lost). |
0 commit comments