Skip to main content

How to Upgrade Your ZIGChain Node

TL;DR: A ZIGChain node upgrade uses a vote, a halt, or a patch. Use manual steps or Cosmovisor, then run the checks in Verification Steps.

Overview​

A ZIGChain node upgrade replaces your zigchaind binary when the network adopts a new release. This guide helps operators and validators pick the right path. Each path differs in whether state breaks, how the network coordinates, and whether every node must stop at one block height.

See Cosmovisor How-To Guide for Cosmovisor setup and prepare-upgrade. See Set Up a ZIGChain Node for first-time install and services. You need a running node and the new build from the ZIGChain Networks Repository.

Use the ZIGChain Node Upgrade Types Overview table to choose your ZIGChain node upgrade path. After you swap binaries, follow Verification Steps to confirm sync, version, and logs.

Key Concepts​

  • Governance upgrade: State-breaking upgrade approved by an on-chain software upgrade proposal. Every node stops at the same upgrade height in the proposal.
  • Blockchain halt upgrade: Non-governance, state-breaking upgrade that stops the chain at a coordinated block height. Validators act without waiting for a governance vote.
  • Patch upgrade: Non-state-breaking update that nodes can apply on their own schedule. The chain does not require a coordinated halt for these releases.
  • Upgrade height: Block height where the node stops and must run the new binary. Governance uses one height; halt upgrades publish separate manual and Cosmovisor values.
  • Manual halt height: halt-height in app.toml for operators who upgrade the binary by hand during a halt upgrade announcement.
  • Cosmovisor upgrade height: Height passed to cosmovisor add-upgrade, typically one block below the manual halt height for halt upgrades.
  • prepare-upgrade: Cosmovisor command that downloads and stages the binary after a governance proposal passes, using the on-chain upgrade plan.

ZIGChain Node Upgrade Types Overview​

Use this table to pick the right ZIGChain node upgrade path before you change binaries or Cosmovisor settings. Each row shows whether state breaks, how the network coordinates, and when teams use that path.

Upgrade TypeState-BreakingCoordinationWhen Used
GovernanceYesGovernance proposalRegular planned upgrades
Non-Governance - Blockchain HaltYesCoordinated at specific heightCritical/emergency situations
Non-Governance - PatchNoAsynchronousBug fixes, security patches, performance improvements
Security Upgrades

Critical security upgrades will be coordinated through non-governance approaches to protect the chain before public disclosure. Validators should be prepared to respond to urgent communications from the ZIGChain team for coordinated halts or emergency patches. For security-related upgrades, binaries may be shared privately with validators before public release.

Governance Upgrades​

A governance ZIGChain node upgrade is a state-breaking change approved by an on-chain software upgrade proposal. Every node stops at the upgrade height in the proposal and must run the new binary. Manual operators and Cosmovisor use that same height — unlike halt upgrades, which publish separate manual and Cosmovisor heights.

Manual Binary Upgrade​

Follow these steps for a manual ZIGChain node upgrade when Cosmovisor is not managing the process.

  1. Build or download the binary for the release you are upgrading to from the ZIGChain Networks Repository.

  2. Wait for the node to stop at the upgrade height. The log will display something like this:

ERR UPGRADE "v1.3.0" NEEDED at height: 5432100: upgrade to v1.3.0 and applying upgrade "v1.3.0" at height:5432100
  1. Stop the node service if it remains active:
sudo systemctl stop zigchaind.service
  1. Replace the binary with the new release:
sudo cp /path/to/new/zigchaind $(which zigchaind)
sudo chmod +x $(which zigchaind)
  1. Restart the node service:
sudo systemctl start zigchaind.service

Cosmovisor Upgrade​

Cosmovisor automates this ZIGChain node upgrade type after the proposal passes. See the Cosmovisor How-To Guide for setup and the prepare-upgrade command.

You do not need to run cosmovisor add-upgrade manually for a governance upgrade. After the proposal passes, use prepare-upgrade only. Cosmovisor reads the on-chain plan, including upgrade height, and knows when to stop and when to restart with the new build.

Summary:

  1. After the governance proposal passes, run cosmovisor prepare-upgrade to download and validate the new binary.
  2. Verify the binary was prepared correctly:
ls -la $HOME/.zigchain/cosmovisor/upgrades/
$HOME/.zigchain/cosmovisor/upgrades/<UPGRADE_NAME>/bin/zigchaind version
  1. At the upgrade height from the proposal, Cosmovisor automatically switches to the new binary and restarts the node.

Non-Governance - Blockchain Halts​

A halt-style ZIGChain node upgrade coordinates a stop at one block height without a governance vote. Teams use this path for critical security issues, consensus failures, and other state-breaking emergencies.

The sections below cover halt height values, manual steps with halt-height, and Cosmovisor registration for this ZIGChain node upgrade path. Read the official announcement before you change config or binaries.

note

Stop your node at the announced height, replace the binary, then start it again. Monitor logs as the halt height approaches.

Halt Upgrade Height Values​

Every halt ZIGChain node upgrade announcement includes two heights — one for manual upgrades and one for Cosmovisor. Use the value that matches your setup:

MechanismSettingUse from announcement
Manual (app.toml)halt-heightManual halt height (upgrade block height)
Cosmovisor--upgrade-heightCosmovisor upgrade height (upgrade block height minus one)

When using cosmovisor add-upgrade for a halt upgrade, set --upgrade-height to the upgrade block height minus one. Halt announcements publish both values so you do not need to calculate them.

Do not swap them, and do not use the same number for both settings.

Example (values from a halt announcement):

halt-height = 8370001
cosmovisor add-upgrade v5 /path/to/zigchaind --upgrade-height 8370000

Halt Manual Binary Upgrade​

These steps cover a manual halt ZIGChain node upgrade using halt-height in app.toml. Work through each step in order. Do not start the node again until you reset halt-height to 0.

  1. Build or download the binary for the release you are upgrading to.

  2. Update app.toml to set the halt height. Open the configuration file:

vim ~/.zigchain/config/app.toml

Find the halt-height variable and set it to the manual halt height from the announcement (see Halt Upgrade Height Values):

halt-height = 24666001
  1. Restart the node to apply the configuration:
sudo systemctl restart zigchaind.service
  1. Wait for the halt height. The log will display something like this:
ERR CONSENSUS FAILURE!!! err="failed to apply block; error halt per configuration height 24666001 time 0"
  1. Stop the node service:
sudo systemctl stop zigchaind.service
  1. Replace the binary with the new release:
sudo cp /path/to/new/zigchaind $(which zigchaind)
sudo chmod +x $(which zigchaind)
  1. Reset halt-height back to 0 in app.toml:
halt-height = 0
  1. Start the node service:
sudo systemctl start zigchaind.service
  1. Monitor the logs to ensure the node starts correctly and resumes consensus:
sudo journalctl -u zigchaind.service -f -o cat
tail -f /var/log/zigchaind/main.log

Halt Cosmovisor Upgrade​

warning

There are reported issues with using Cosmovisor for non-governance upgrades: the instructions below may result in unexpected behaviour, such as an immediate upgrade or failure to stop at the specified height.

If you use Cosmovisor for a halt ZIGChain node upgrade, register it with add-upgrade and the Cosmovisor upgrade height from the announcement (not the manual halt height).

  1. Download or build the new binary and place it in a temporary location.

  2. Register the upgrade using cosmovisor add-upgrade:

cosmovisor add-upgrade <UPGRADE_NAME> /path/to/new/zigchaind --upgrade-height <COSMOVISOR_UPGRADE_HEIGHT>

Use the Cosmovisor upgrade height from the announcement, not the manual halt height (see Halt Upgrade Height Values).

For example:

cosmovisor add-upgrade v3 /tmp/zigchaind-v3/zigchaind --upgrade-height 24666000
note

The <UPGRADE_NAME> will be provided by the ZIGChain team. Upgrade names cannot be reused, so ensure you use the exact name specified in the upgrade announcement.

  1. Verify the upgrade was registered:
ls -la $HOME/.zigchain/cosmovisor/upgrades/
$HOME/.zigchain/cosmovisor/upgrades/<UPGRADE_NAME>/bin/zigchaind version

  1. At the specified halt height, Cosmovisor will automatically switch to the new binary and restart the node.

  2. Monitor the logs to ensure the upgrade proceeds correctly:

sudo journalctl -u zigchaind-cosmovisor.service -f -o cat

Non-Governance - Patch​

A patch ZIGChain node upgrade does not break state, so nodes can roll forward on their own schedule. Patches cover bug fixes, performance work, and security fixes that do not need state migration.

Recommendation: For this ZIGChain node upgrade type, upgrade one or two nodes first, monitor for stability, then upgrade the rest.

Manual Binary Upgrade​

Follow these steps for a manual patch ZIGChain node upgrade without a coordinated halt. You do not need to change halt-height.

  1. Stop the node service:
sudo systemctl stop zigchaind.service
  1. Replace the binary with the new release:
sudo cp /path/to/new/zigchaind $(which zigchaind)
sudo chmod +x $(which zigchaind)
  1. Start the node service:
sudo systemctl start zigchaind.service

Cosmovisor Upgrade​

warning

There are reported issues with using Cosmovisor for non-governance upgrades: the instructions below may result in unexpected behaviour, such as an immediate upgrade or failure to stop at the specified height.

If you use Cosmovisor for a patch ZIGChain node upgrade, register it with add-upgrade (no coordinated halt height required).

  1. Download or build the new binary and place it in a temporary location.

  2. Register the upgrade using cosmovisor add-upgrade:

cosmovisor add-upgrade <UPGRADE_NAME> /path/to/new/zigchaind --upgrade-height <HEIGHT>

For example:

cosmovisor add-upgrade v3.0.1-patch /tmp/zigchaind-v3.0.1/zigchaind --upgrade-height 24680000
note

The <UPGRADE_NAME> will be provided by the ZIGChain team. Upgrade names cannot be reused, so ensure you use the exact name specified in the upgrade announcement.

  1. Verify the upgrade was registered:
ls -la $HOME/.zigchain/cosmovisor/upgrades/
$HOME/.zigchain/cosmovisor/upgrades/<UPGRADE_NAME>/bin/zigchaind version

  1. Cosmovisor will automatically switch to the new binary.

  2. Monitor the logs to ensure the node is running correctly:

sudo journalctl -u zigchaind-cosmovisor.service -f -o cat

Verification Steps​

After any ZIGChain node upgrade, confirm sync, version, and logs before you declare the node healthy. The commands below work for manual and Cosmovisor-managed nodes on Linux and Mac.

To check node status, query the local RPC sync info:

curl -s localhost:26657/status | jq '.result.sync_info'

To verify the new version, compare the system binary and the Cosmovisor current link:

zigchaind version --long
$HOME/.zigchain/cosmovisor/current/bin/zigchaind version --long

To check logs for errors, use the service journal on Linux or the main log file on Mac:

sudo journalctl -u zigchaind.service -f -o cat
sudo journalctl -u zigchaind-cosmovisor.service -f -o cat

A successful ZIGChain node upgrade should show synced state, the expected binary version, clean consensus logs, and a rising block height. The numbered checks below confirm each signal.

  1. Node is synced: The catching_up field should be false. Check with:
curl -s localhost:26657/status | jq '.result.sync_info.catching_up'

Expected output: false

  1. Correct version: Verify the new version is running:
zigchaind version
$HOME/.zigchain/cosmovisor/current/bin/zigchaind version

  1. No consensus errors: Logs should show normal block production without ERR messages related to consensus.

  2. Blocks being produced: The latest_block_height should be increasing:

curl -s localhost:26657/status | jq '.result.sync_info.latest_block_height'

Common Questions​

Do I run cosmovisor add-upgrade for a governance upgrade​

No. After the governance proposal passes, run cosmovisor prepare-upgrade only. Cosmovisor reads the on-chain software upgrade plan, including upgrade height, and switches binaries at that height without a manual add-upgrade step. You do not register a separate upgrade name for a standard governance release.

Why halt announcements list two different heights​

Manual operators set halt-height in app.toml to the manual halt height from the announcement. Cosmovisor uses --upgrade-height set to the Cosmovisor upgrade height, which is the upgrade block height minus one. Do not swap these values or reuse one number for both settings. The team publishes both numbers so you do not need to derive them.

Is Cosmovisor safe for non-governance halt or patch upgrades​

There are reported issues with Cosmovisor on non-governance upgrades, including immediate upgrades or failure to stop at the announced height. Read the warnings in the halt and patch sections before you rely on Cosmovisor for those paths. Many operators prefer manual binary steps for halt and patch events until their setup is proven.

What to check right after any ZIGChain node upgrade​

Confirm sync status, binary version, and clean logs. The Verification Steps section lists RPC checks, version commands, and log commands for Linux and Mac. Run those checks before you re-enable monitoring alerts or delegate signing again.

Use these resources when you plan or verify a ZIGChain node upgrade.