> For the complete documentation index, see [llms.txt](https://service.block-pro.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://service.block-pro.net/mainnet/nolus/upgrade.md).

# 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.

{% hint style="warning" %}
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.
{% endhint %}

### Check the service

Confirm its executable and home before changing anything.

```bash
systemctl cat nolusd
```

### Check the upgrade plan

Read any scheduled on-chain upgrade.

```bash
nolusd query upgrade plan -o json
```

### Prepare the new binary

Use the binary download/build steps in [Installation](/mainnet/nolus/installation.md), 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.

```bash
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.

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

### Build into a staging directory

GOBIN keeps the service executable unchanged.

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

### Stage the result

Use a predictable path for the replacement.

```bash
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.

```bash
chmod 0755 "$HOME/nolusd.next"
```

### Check the staged version

Resolve missing libraries or a wrong release before downtime.

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

### Stop at the correct time

Stop the one active signer before switching binaries.

```bash
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.

```bash
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.

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

### Replace the binary

Install the staged executable.

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

### Start

Start the node with the upgraded binary.

```bash
sudo systemctl start nolusd
```

### Inspect logs

Check for migration errors and advancing heights.

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

### Confirm sync

Check height and catching\_up after the node recovers.

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

[Release history](https://github.com/nolus-protocol/nolus-core/tags).