diff --git a/src/content/docs/resources/mainnet/upgrades/v147.mdx b/src/content/docs/resources/mainnet/upgrades/v147.mdx new file mode 100644 index 000000000..5ce152e55 --- /dev/null +++ b/src/content/docs/resources/mainnet/upgrades/v147.mdx @@ -0,0 +1,118 @@ +# Mainnet upgrade: v1.4.7 + +import { Callout } from "/src/components/callout"; + +Instructions for the mainnet upgrade to axelar-core `v1.4.7`. + +The release for the upgrade can be found [here](https://github.com/axelarnetwork/axelar-core/releases/tag/v1.4.7). + +Upgrade height: **30135800**. Proposal: **[#480](https://axelarscan.io/proposals/480)**. Upgrade time: **~14:00 UTC, 2026-06-16**. See [countdown](https://www.mintscan.io/axelar/block/30135800). + +## Binary Types + +The v1.4.7 release provides **two Linux binaries**: + +- **[Static](https://github.com/axelarnetwork/axelar-core/releases/download/v1.4.7/axelard-linux-amd64-v1.4.7-static) binary (`axelard-linux-amd64-v1.4.7-static`)** + - Contains a statically linked `libwasmvm` + - **Does not require** installing or configuring `libwasmvm` + +- **[Dynamically](https://github.com/axelarnetwork/axelar-core/releases/download/v1.4.7/axelard-linux-amd64-v1.4.7) linked binary (`axelard-linux-amd64-v1.4.7`)** + - Requires `libwasmvm` **v2.2.6** (bumped from v2.2.4 in v1.3.x; replace the library when upgrading a v1.3.x dynamic-binary node) + - Must have the library directory on `LD_LIBRARY_PATH` + + + `axelard` must be built with `go-1.25` for this release (same as v1.3.x). + + If using the **static** binary, no `wasmvm` setup is required. + + If using the **dynamic** binary, `libwasmvm` is bumped from `v2.2.4` (v1.3.x) to `v2.2.6` + ([libwasmvm.x86_64.so](https://github.com/CosmWasm/wasmvm/releases/tag/v2.2.6)) in this + upgrade. Replace the library on every node and keep it on `LD_LIBRARY_PATH` before starting + the new binary, otherwise it refuses to launch with a wasmvm version-mismatch error. + + +## About the v1.4 upgrade + +The `v1.4` upgrade is a consensus-breaking release for Axelar mainnet. Highlights: + +- **Removes the link-deposit protocol.** The legacy non-GMP token-transfer paths (linked deposit addresses, direct token transfers) that were deprecated in v1.3.1 are now fully removed. Pending link-deposit state is cleaned up in the upgrade handler. +- **Routes governance proposals targeting legacy EVM chains through the Amplifier GMP path** (axelarnet-gateway wasm contract → nexus → EVM module) instead of the old direct axelarnet route. The emitted `sourceChain` for these messages changes from `Axelarnet` to `axelar`. +- **Reduces `maxBitmapSize` in nexus maintainer state** (32,768 → 1,024) to lower per-validator memory pressure. +- **Dependency bumps:** CometBFT v0.38.23, CosmWasm `wasmd` v0.54.7, `libwasmvm` v2.2.4 → v2.2.6, Cosmos SDK v0.50.15, ibc-go v8.8.0. +- **Vald correctness:** reject votes on failed polls. +- **`v1.4.7` patch (on top of `v1.4.6`):** restores the `InterfaceRegistry` registrations for tss `UpdateParams` and `HeartBeat`. + +No CosmWasm contract migrations are required for this upgrade. No `config.toml` / `app.toml` changes are required relative to a node already running v1.3.x with the post-v1.3.0 settings (`iavl-cache-size = 0`, `iavl-disable-fastnode = true`, `timeout_commit = 1s`). + +For the full list of changes, see the [v1.4.7 changelog](https://github.com/axelarnetwork/axelar-core/blob/v1.4.7/CHANGELOG.md). + +## Upgrade Instructions + +1. If you're a validator or have delegated to one, please vote for the upgrade proposal via: + +```bash +axelard tx gov vote yes --from validator +``` + +2. Wait for the proposed upgrade block. Your node will panic at that block height with a log: `{"level":"error","module":"consensus","err":"UPGRADE \"v1.4\" NEEDED at height: ",`. + +Stop your node after chain halt: + +```bash +pkill -f 'axelard start' +# Validators also need to stop vald/tofnd +pkill -f 'vald-start' +pkill -f tofnd +``` + +3. Backup the state: + +```bash +cp -r ~/.axelar/.core/data ~/.axelar-dojo-1-upgrade-1.4.7/.core/data +``` + + + ⚠️ **Important:** If you backup the entire folder, `~/.axelar/.core`, that'll + also include your private keys (inside `config` and `keyring-file` + subfolders). That can be dangerous if anyone gets access to your backups. We + recommend backing up keys separately when you first create your node, and then + excluding them from any data backups. + + +4. Restart your `axelard` node with the new `v1.4.7` build. + +5. If you're a validator also restart `vald` with `v1.4.7` and `tofnd` with `v1.0.1` (unchanged from v1.3.x). + +### Example using join scripts (axelarate-community) + +```bash +# in axelarate-community repo +git checkout main +git pull +KEYRING_PASSWORD="pw-1" ./scripts/node.sh -n mainnet -a v1.4.7 +# For validators, restart vald/tofnd +KEYRING_PASSWORD="pw-1" TOFND_PASSWORD="pw-2" ./scripts/validator-tools-host.sh -n mainnet -a v1.4.7 -q v1.0.1 +``` + +## Ampd + +For verifiers, refer to the matching `ampd` release notes under [`axelar-contract-deployments/releases/ampd`](https://github.com/axelarnetwork/axelar-contract-deployments/tree/main/releases/ampd) for the version compatible with `axelard v1.4.7`. The `ampd` upgrade must be done **after** the `axelard` upgrade. + +## Rollback + +This is a state-machine-breaking upgrade. **There is no in-place rollback** to v1.3.x once your node has executed the `v1.4` upgrade handler. The link-deposit removal and parameter changes are persisted to state. If rollback is required, restore from the pre-upgrade snapshot you took in step 3. + +## Troubleshooting + +If you encounter a **hash error**, ensure you have `libwasmvm v2.2.6`: + +https://github.com/CosmWasm/wasmvm/releases/download/v2.2.6/libwasmvm.x86_64.so + +Before restarting your node: + +1. Make sure `LD_LIBRARY_PATH` includes the directory of `libwasmvm` (dynamic binary only). +2. Docker users do **not** need to modify anything. + +If you see the error `undefined symbol: migrate_with_info`, switch to the statically linked binary (`axelard-linux-amd64-v1.4.7-static`). + +If you see the error `app hash` mismatch after the upgrade, verify all replicas in your fleet were swapped to v1.4.7 before the upgrade height. Mixed binaries across replicas after the upgrade height will fork. diff --git a/src/content/docs/resources/testnet/upgrades/v147.mdx b/src/content/docs/resources/testnet/upgrades/v147.mdx new file mode 100644 index 000000000..adc4b08b5 --- /dev/null +++ b/src/content/docs/resources/testnet/upgrades/v147.mdx @@ -0,0 +1,118 @@ +# Testnet upgrade: v1.4.7 + +import { Callout } from "/src/components/callout"; + +Instructions for the testnet upgrade to axelar-core `v1.4.7`. + +The release for the upgrade can be found [here](https://github.com/axelarnetwork/axelar-core/releases/tag/v1.4.7). + +Upgrade height: **30546580**. Proposal: **[#578](https://testnet.axelarscan.io/proposals/578)**. Upgrade time: **~12:00 UTC, 2026-05-19**. See [countdown](https://www.mintscan.io/axelar-testnet/block/30546580). + +## Binary Types + +The v1.4.7 release provides **two Linux binaries**: + +- **[Static](https://github.com/axelarnetwork/axelar-core/releases/download/v1.4.7/axelard-linux-amd64-v1.4.7-static) binary (`axelard-linux-amd64-v1.4.7-static`)** + - Contains a statically linked `libwasmvm` + - **Does not require** installing or configuring `libwasmvm` + +- **[Dynamically](https://github.com/axelarnetwork/axelar-core/releases/download/v1.4.7/axelard-linux-amd64-v1.4.7) linked binary (`axelard-linux-amd64-v1.4.7`)** + - Requires `libwasmvm` **v2.2.6** (bumped from v2.2.4 in v1.3.x; replace the library when upgrading a v1.3.x dynamic-binary node) + - Must have the library directory on `LD_LIBRARY_PATH` + + + `axelard` must be built with `go-1.25` for this release (same as v1.3.x). + + If using the **static** binary, no `wasmvm` setup is required. + + If using the **dynamic** binary, `libwasmvm` is bumped from `v2.2.4` (v1.3.x) to `v2.2.6` + ([libwasmvm.x86_64.so](https://github.com/CosmWasm/wasmvm/releases/tag/v2.2.6)) in this + upgrade. Replace the library on every node and keep it on `LD_LIBRARY_PATH` before starting + the new binary, otherwise it refuses to launch with a wasmvm version-mismatch error. + + +## About the v1.4 upgrade + +The `v1.4` upgrade is a consensus-breaking release. Highlights: + +- **Removes the link-deposit protocol.** The legacy non-GMP token-transfer paths (linked deposit addresses, direct token transfers) that were deprecated in v1.3.1 are now fully removed. Pending link-deposit state is cleaned up in the upgrade handler. +- **Routes governance proposals targeting legacy EVM chains through the Amplifier GMP path** (axelarnet-gateway wasm contract → nexus → EVM module) instead of the old direct axelarnet route. The emitted `sourceChain` for these messages changes from `Axelarnet` to `axelar`. +- **Reduces `maxBitmapSize` in nexus maintainer state** (32,768 → 1,024) to lower per-validator memory pressure. +- **Dependency bumps:** CometBFT v0.38.23, CosmWasm `wasmd` v0.54.7, `libwasmvm` v2.2.4 → v2.2.6, Cosmos SDK v0.50.15, ibc-go v8.8.0. +- **Vald correctness:** reject votes on failed polls. +- **`v1.4.7` patch (on top of `v1.4.6`):** restores the `InterfaceRegistry` registrations for tss `UpdateParams` and `HeartBeat`. + +No CosmWasm contract migrations are required for this upgrade. No `config.toml` / `app.toml` changes are required relative to a node already running v1.3.x with the post-v1.3.0 settings (`iavl-cache-size = 0`, `iavl-disable-fastnode = true`, `timeout_commit = 1s`). + +For the full list of changes, see the [v1.4.7 changelog](https://github.com/axelarnetwork/axelar-core/blob/v1.4.7/CHANGELOG.md). + +## Upgrade Instructions + +1. If you're a validator or have delegated to one, please vote for the upgrade proposal via: + +```bash +axelard tx gov vote yes --from validator +``` + +2. Wait for the proposed upgrade block. Your node will panic at that block height with a log: `{"level":"error","module":"consensus","err":"UPGRADE \"v1.4\" NEEDED at height: ",`. + +Stop your node after chain halt: + +```bash +pkill -f 'axelard start' +# Validators also need to stop vald/tofnd +pkill -f 'vald-start' +pkill -f tofnd +``` + +3. Backup the state: + +```bash +cp -r ~/.axelar_testnet/.core/data ~/.axelar-lisbon-3-upgrade-1.4.7/.core/data +``` + + + ⚠️ **Important:** If you backup the entire folder, `~/.axelar_testnet/.core`, that'll + also include your private keys (inside `config` and `keyring-file` + subfolders). That can be dangerous if anyone gets access to your backups. We + recommend backing up keys separately when you first create your node, and then + excluding them from any data backups. + + +4. Restart your `axelard` node with the new `v1.4.7` build. + +5. If you're a validator also restart `vald` with `v1.4.7` and `tofnd` with `v1.0.1` (unchanged from v1.3.x). + +### Example using join scripts (axelarate-community) + +```bash +# in axelarate-community repo +git checkout main +git pull +KEYRING_PASSWORD="pw-1" ./scripts/node.sh -n testnet -a v1.4.7 +# For validators, restart vald/tofnd +KEYRING_PASSWORD="pw-1" TOFND_PASSWORD="pw-2" ./scripts/validator-tools-host.sh -n testnet -a v1.4.7 -q v1.0.1 +``` + +## Ampd + +For verifiers, refer to the matching `ampd` release notes under [`axelar-contract-deployments/releases/ampd`](https://github.com/axelarnetwork/axelar-contract-deployments/tree/main/releases/ampd) for the version compatible with `axelard v1.4.7`. The `ampd` upgrade must be done **after** the `axelard` upgrade. + +## Rollback + +This is a state-machine-breaking upgrade. **There is no in-place rollback** to v1.3.x once your node has executed the `v1.4` upgrade handler. The link-deposit removal and parameter changes are persisted to state. If rollback is required, restore from the pre-upgrade snapshot you took in step 3. + +## Troubleshooting + +If you encounter a **hash error**, ensure you have `libwasmvm v2.2.6`: + +https://github.com/CosmWasm/wasmvm/releases/download/v2.2.6/libwasmvm.x86_64.so + +Before restarting your node: + +1. Make sure `LD_LIBRARY_PATH` includes the directory of `libwasmvm` (dynamic binary only). +2. Docker users do **not** need to modify anything. + +If you see the error `undefined symbol: migrate_with_info`, switch to the statically linked binary (`axelard-linux-amd64-v1.4.7-static`). + +If you see the error `app hash` mismatch after the upgrade, verify all replicas in your fleet were swapped to v1.4.7 before the upgrade height. Mixed binaries across replicas after the upgrade height will fork. diff --git a/src/layouts/navigation.ts b/src/layouts/navigation.ts index 9c86ffebb..053c808b5 100644 --- a/src/layouts/navigation.ts +++ b/src/layouts/navigation.ts @@ -737,6 +737,10 @@ export const getNavigation = (section) => { { title: "Mainnet axelard", children: [ + { + title: "v1.4", + href: "/resources/mainnet/upgrades/v147/", + }, { title: "v1.3", href: "https://github.com/axelarnetwork/axelar-contract-deployments/blob/main/releases/axelard/2025-11-v1.3.2.md", @@ -814,6 +818,10 @@ export const getNavigation = (section) => { { title: "Testnet axelard", children: [ + { + title: "v1.4", + href: "/resources/testnet/upgrades/v147/", + }, { title: "v1.3.1", href: "/resources/testnet/upgrades/v131/",