Skip to content

Commit 813b7c7

Browse files
docs: add mainnet v1.3 upgrade page and repoint sidebar internally (#1450)
1 parent bf9267d commit 813b7c7

2 files changed

Lines changed: 135 additions & 1 deletion

File tree

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
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).

src/layouts/navigation.ts

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -743,7 +743,7 @@ export const getNavigation = (section) => {
743743
},
744744
{
745745
title: "v1.3",
746-
href: "https://github.com/axelarnetwork/axelar-contract-deployments/blob/main/releases/axelard/2025-11-v1.3.2.md",
746+
href: "/resources/mainnet/upgrades/v132/",
747747
},
748748
{
749749
title: "v1.2",

0 commit comments

Comments
 (0)