Cosmovisor

cosmovisor is a lightweight process manager for Cosmos SDK application binaries that automates the upgrade process. It monitors the governance module for on-chain upgrade proposals and seamlessly handles binary upgrades by:

• Downloading and preparing the new binary

• Stopping the current binary

• Switching to the upgraded binary

• Restarting the node with the new binary

Why Use Cosmovisor?

For validators, cosmovisor significantly reduces downtime during chain upgrades. Instead of manually handling upgrades, validators can pre-install new binaries, allowing cosmovisor to execute upgrades automatically when a proposal passes.

---

Configuration

More details about cosmovisor settings can be found in the official documentation.

---

Installation

1. Using Go Install

Install the latest version of cosmovisor with:

go install cosmossdk.io/tools/cosmovisor/cmd/cosmovisor@latest

2. Manual Build

Alternatively, build from source:

git clone https://github.com/cosmos/cosmos-sdk.git
cd cosmos-sdk
git checkout cosmovisor/vx.x.x
make cosmovisor

This builds cosmovisor in the /cosmovisor directory. To add it to your system’s PATH:

cp cosmovisor/cosmovisor ~/go/bin/cosmovisor

Verify the installation:

cosmovisor version

---

Directory Structure

.
├── current -> genesis or upgrades/<name>
├── genesis
│   └── bin
│       └── $DAEMON_NAME
└── upgrades
    └── <name>
        ├── bin
        │   └── $DAEMON_NAME
        └── upgrade-info.json

---

Manual Software Upgrade Using Cosmovisor

This tutorial assumes you have set up a validator node using this guide.

Upgrade Process Overview

1. Foundation Team Publishes a New Release

Example: v0.50.8 Release

2. Foundation Team Submits a Software Upgrade Proposal

Example: Proposal #310

• The most important detail is the block height at which the upgrade takes effect. In Proposal #310, the upgrade happens at block 53006170.

• You can track this block height and estimate when the upgrade will occur.

3. Validator's Steps: Prepare the Upgrade Binary

1. Create the upgrade binary folder:

   mkdir -p $HOME/.oraid/cosmovisor/upgrades/v0.50.8/bin

2. Build the new binary:

   cd orai
   git pull
   git checkout v0.50.8
   make build

3. Copy the binary to the upgrade folder:

   cp $(which oraid) $HOME/.oraid/cosmovisor/upgrades/v0.50.8/bin

4. Verify the new binary version:

   oraid version
   $HOME/.oraid/cosmovisor/upgrades/v0.50.8/bin/oraid version

If both commands return v0.50.8, the setup is correct, and you are now ready for the upgrade.

4. Automatic Upgrade at the Specified Block Height

Once the network reaches block 53006170, cosmovisor will automatically:

• Stop the current binary

• Switch to the new binary (upgrades/v0.50.8/bin)

• Restart the node

When 2/3 of validators approve the next block (53006170), the upgrade is considered successful.

---

Final Thoughts

With cosmovisor, software upgrades are seamless and reduce validator downtime. Make sure to follow this guide for every upgrade and ensure your node is prepared in advance.

🚀 Happy Validating!