Upgrade

Upgrade Nolus safely and confirm the node resumes syncing.

Mainnet · pirin-1

This procedure uses the direct nolusd.service created by our installation guide. If your service uses Cosmovisor, stage the binary under the exact on-chain upgrade plan name instead of replacing its symlink.

For a scheduled chain upgrade, prepare the binary in advance and switch only at the announced height. For a compatible patch, follow the project’s release instructions. Do not skip database migrations or start an old binary against upgraded state.

Check the service

Confirm its executable and home before changing anything.

systemctl cat nolusd

Check the upgrade plan

Read any scheduled on-chain upgrade.

nolusd query upgrade plan -o json

Prepare the new binary

Use the binary download/build steps in Installation, but stage the result as $HOME/nolusd.next and do not install it over the running executable yet. Select the release announced for pirin-1.

Create an upgrade checkout

Use a new directory and the intended release tag.

git clone --branch v0.8.4 --depth 1 https://github.com/nolus-protocol/nolus-core.git "$HOME/nolus-upgrade-v0.8.4"

Open the checkout

Build from the release source.

cd "$HOME/nolus-upgrade-v0.8.4"

Build into a staging directory

GOBIN keeps the service executable unchanged.

GOTOOLCHAIN=auto GOBIN="$HOME/nolus-upgrade-bin" make install

Stage the result

Use a predictable path for the replacement.

cp "$HOME/nolus-upgrade-bin/nolusd" "$HOME/nolusd.next"

If the release changes WasmVM, install its matching runtime library using the module lookup in Installation and run sudo ldconfig before starting the new binary.

Make executable

Allow checking the staged binary.

chmod 0755 "$HOME/nolusd.next"

Check the staged version

Resolve missing libraries or a wrong release before downtime.

"$HOME/nolusd.next" version --long

Stop at the correct time

Stop the one active signer before switching binaries.

sudo systemctl stop nolusd

Back up configuration and signing state

Keep the signing state from this stopped node. Store a full stopped database backup as well if the release requires one.

tar -czf "$HOME/nolus-mainnet-upgrade-$(date +%Y%m%d-%H%M%S).tar.gz" -C "$HOME/.nolus" config data/priv_validator_state.json

Keep the previous binary

Retain a copy for diagnostics; database migrations may prevent a simple binary rollback.

cp /usr/local/bin/nolusd "$HOME/nolusd.previous"

Replace the binary

Install the staged executable.

sudo install -m 0755 "$HOME/nolusd.next" /usr/local/bin/nolusd

Start

Start the node with the upgraded binary.

sudo systemctl start nolusd

Inspect logs

Check for migration errors and advancing heights.

sudo journalctl -u nolusd -n 100 -f -o cat

Confirm sync

Check height and catching_up after the node recovers.

curl -fsS http://127.0.0.1:26657/status | jq '.result.sync_info'

Release history.