Skip to content

docs(sdk): fix and expand the Upgrades and Cosmovisor guides #331

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
evanorti wants to merge 3 commits into
base: main
Choose a base branch
from
Open

docs(sdk): fix and expand the Upgrades and Cosmovisor guides #331

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
0985a4d
cosmovisor updates
evanorti Jul 17, 2026
de57e36
update update guides
evanorti Jul 17, 2026
a566ab5
Apply suggestions from code review
evanorti Jul 17, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
97 changes: 62 additions & 35 deletions sdk/latest/guides/upgrades/cosmovisor.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,7 @@ It polls the `upgrade-info.json` file that is created by the x/upgrade module at
* [Chain Setup](#chain-setup)
* [Prepare Cosmovisor and Start the Chain](#prepare-cosmovisor-and-start-the-chain)
* [Update App](#update-app)
* [Pre-Upgrade Handling](#pre-upgrade-handling)

## Design

Expand All @@ -31,7 +32,9 @@ Cosmovisor is designed to be used as a wrapper for a `Cosmos SDK` app:
* it will manage an app by restarting and upgrading if needed;
* it is configured using environment variables, not positional arguments.

*Note: If new versions of the application are not set up to run in-place store migrations, migrations will need to be run manually before restarting `cosmovisor` with the new binary. For this reason, we recommend applications adopt in-place store migrations.*
<Note>
If new versions of the application are not set up to run in-place store migrations, migrations must be run manually before restarting `cosmovisor` with the new binary. For this reason, applications should adopt in-place store migrations.
</Note>

<Tip>
Only the latest version of cosmovisor is actively developed/maintained.
Expand All @@ -51,7 +54,7 @@ Release branches have the following format `release/cosmovisor/vA.B.x`, where A

### Installation

You can download Cosmovisor from the [GitHub releases](https://github.com/cosmos/cosmos-sdk/releases/tag/cosmovisor%2Fv1.5.0).
You can download Cosmovisor from the [GitHub releases](https://github.com/cosmos/cosmos-sdk/releases/tag/cosmovisor%2Fv1.7.1).

To install the latest version of `cosmovisor`, run the following command:

Expand All @@ -62,7 +65,7 @@ go install cosmossdk.io/tools/cosmovisor/cmd/cosmovisor@latest
To install a specific version, you can specify the version:

```shell
go install cosmossdk.io/tools/cosmovisor/cmd/cosmovisor@v1.5.0
go install cosmossdk.io/tools/cosmovisor/cmd/cosmovisor@v1.7.1
```

Run `cosmovisor version` to check the cosmovisor version.
Expand All @@ -85,6 +88,7 @@ The first argument passed to `cosmovisor` is the action for `cosmovisor` to take
* `add-upgrade` - Add an upgrade manually to `cosmovisor`. This command allow you to easily add the binary corresponding to an upgrade in cosmovisor.
* `add-batch-upgrade` - Add multiple upgrades at once.
* `show-upgrade-info` - Show the current upgrade info from the upgrade-info.json file.
* `prepare-upgrade` - Download and place the next scheduled upgrade's binary ahead of time, using upgrade info read from the chain over gRPC.

All arguments passed to `cosmovisor run` will be passed to the application binary (as a subprocess). `cosmovisor` will return `/dev/stdout` and `/dev/stderr` of the subprocess as its own. For this reason, `cosmovisor run` cannot accept any command-line arguments other than those available to the application binary.

Expand Down Expand Up @@ -172,7 +176,7 @@ The `cosmovisor init` command is specifically for initializing cosmovisor, and s

### Detecting Upgrades

`cosmovisor` is polling the `$DAEMON_HOME/data/upgrade-info.json` file for new upgrade instructions. The file is created by the x/upgrade module in `BeginBlocker` when an upgrade is detected and the blockchain reaches the upgrade height.
`cosmovisor` is polling the `$DAEMON_HOME/data/upgrade-info.json` file for new upgrade instructions. The file is created by the x/upgrade module in `PreBlocker` when an upgrade is detected and the blockchain reaches the upgrade height.
The following heuristic is applied to detect the upgrade:

* When starting, `cosmovisor` doesn't know much about currently running upgrade, except the binary which is `current/bin/`. It tries to read the `current/upgrade-info.json` file to get information about the current upgrade name.
Expand Down Expand Up @@ -295,53 +299,55 @@ INFO Downloading upgrade binary url=https://example.com/binary/v1.0.0?checksum=s
INFO Upgrade preparation complete name=v1.0.0 height=1000000
```

*Note: The current way of downloading manually and placing the binary at the right place would still work.*
<Note>
Downloading manually and placing the binary in the right location still works.
</Note>

## Example: SimApp Upgrade

The following instructions provide a demonstration of `cosmovisor` using the simulation application (`simapp`) shipped with the Cosmos SDK's source code. The following commands are to be run from within the `cosmos-sdk` repository.
The following instructions demonstrate `cosmovisor` using the simulation application (`simapp`) shipped with the Cosmos SDK's source code, upgrading a chain from `v0.53.7` to `v0.54.3`. This pair uses the in-repo `v053-to-v054` upgrade handler defined in `simapp/upgrades.go` on the `v0.54.x` line, so no custom code is required. Run these commands from within a clone of the `cosmos-sdk` repository.

### Chain Setup

Let's create a new chain using the `v0.47.4` version of simapp (the Cosmos SDK demo app):
Build the `v0.53.7` version of `simd` (the Cosmos SDK demo app):

```shell
git checkout v0.47.4
git checkout v0.53.7
make build
```

Clean `~/.simapp` (never do this in a production environment):
Initialize the node, overwriting any previous configuration (never do this in a production environment):

```shell
./build/simd tendermint unsafe-reset-all
./build/simd init test --chain-id test --overwrite
```

Set up app config:
Set up the client config:

```shell
./build/simd config chain-id test
./build/simd config keyring-backend test
./build/simd config broadcast-mode sync
./build/simd config set client chain-id test
./build/simd config set client keyring-backend test
./build/simd config set client broadcast-mode sync
```

Initialize the node and overwrite any previous genesis file (never do this in a production environment):
Clear any previous chain data (never do this in a production environment):

```shell
./build/simd init test --chain-id test --overwrite
./build/simd comet unsafe-reset-all
```

For the sake of this demonstration, amend `voting_period` in `genesis.json` to a reduced time of 20 seconds (`20s`):
For the sake of this demonstration, reduce the governance voting period to `20s`. You must also reduce `expedited_voting_period` because it has to stay strictly less than `voting_period`, otherwise `gentx` and node startup fail genesis validation:

```shell
cat <<< $(jq '.app_state.gov.params.voting_period = "20s"' $HOME/.simapp/config/genesis.json) > $HOME/.simapp/config/genesis.json
cat <<< $(jq '.app_state.gov.params.voting_period = "20s" | .app_state.gov.params.expedited_voting_period = "10s"' $HOME/.simapp/config/genesis.json) > $HOME/.simapp/config/genesis.json
```

Create a validator, and setup genesis transaction:
Create a validator and set up the genesis transaction:

```shell
./build/simd keys add validator
./build/simd keys add validator --keyring-backend test
./build/simd genesis add-genesis-account validator 1000000000stake --keyring-backend test
./build/simd genesis gentx validator 1000000stake --chain-id test
./build/simd genesis gentx validator 1000000stake --chain-id test --keyring-backend test
./build/simd genesis collect-gentxs
```

Expand All @@ -354,63 +360,84 @@ export DAEMON_NAME=simd
export DAEMON_HOME=$HOME/.simapp
```

Set the optional environment variable to trigger an automatic app restart:
Set the optional environment variable to trigger an automatic app restart after the upgrade:

```shell
export DAEMON_RESTART_AFTER_UPGRADE=true
```

Initialize cosmovisor with the current binary:
Initialize cosmovisor with the current binary. This creates `$DAEMON_HOME/cosmovisor/genesis/bin/simd` and the `current` symlink:

```shell
cosmovisor init ./build/simd
```

Now you can run cosmovisor with simapp v0.47.4:
Now run the chain through cosmovisor with simapp v0.53.7:

```shell
cosmovisor run start
```

### Update App

Update app to the latest version (e.g. v0.50.0).
Update the app to `v0.54.3`.

<Note>

Migration plans are defined using the `x/upgrade` module and described in [Upgrading Modules](/sdk/latest/guides/upgrades/upgrade). Migrations can perform any deterministic state change.

The migration plan to upgrade the simapp from v0.47 to v0.50 is defined in `simapp/upgrade.go`.
The upgrade name and handler for this example (`const UpgradeName = "v053-to-v054"`) are defined in `simapp/upgrades.go` on the `v0.54.x` branch.

</Note>

Build the new version `simd` binary:
In a second terminal, build the new version of `simd`:

```shell
git checkout v0.54.3
make build
```

Add the new `simd` binary and the upgrade name:
Register the new binary with cosmovisor under the upgrade name. This copies it to `$DAEMON_HOME/cosmovisor/upgrades/v053-to-v054/bin/simd`:

<Warning>

The migration name must match the one defined in the migration plan.
The upgrade name must match the one defined in the migration plan (`v053-to-v054`).

</Warning>

```shell
cosmovisor add-upgrade v047-to-v050 ./build/simd
cosmovisor add-upgrade v053-to-v054 ./build/simd
```

Open a new terminal window and submit an upgrade proposal along with a deposit and a vote (these commands must be run within 20 seconds of each other):
Submit the software-upgrade proposal, then vote on it. Include an initial `--deposit` that meets the minimum deposit so the proposal enters the voting period immediately; both commands must run within the 20-second voting period:

```shell
./build/simd tx upgrade software-upgrade v047-to-v050 --title upgrade --summary upgrade --upgrade-height 200 --upgrade-info "{}" --no-validate --from validator --yes
./build/simd tx gov deposit 1 10000000stake --from validator --yes
./build/simd tx gov vote 1 yes --from validator --yes
./build/simd tx upgrade software-upgrade v053-to-v054 --title upgrade --summary upgrade --upgrade-height 85 --upgrade-info "{}" --no-validate --deposit 10000000stake --from validator --keyring-backend test --chain-id test --yes
./build/simd tx gov vote 1 yes --from validator --keyring-backend test --chain-id test --yes
```

<Note>

Pick an `--upgrade-height` that the chain will reach *after* the proposal passes; adjust it if your setup takes longer. With the default block time this example passes well before height 85.

</Note>

At the upgrade height, the running `v0.53.7` binary halts, and cosmovisor switches to the `v0.54.3` binary, runs the migrations, and restarts the node automatically:

```text
ERR UPGRADE "v053-to-v054" NEEDED at height: 85: {} module=x/upgrade
INF pre-upgrade command does not exist. continuing the upgrade. module=cosmovisor
INF applying upgrade "v053-to-v054" at height: 85 module=x/upgrade
INF running migrations for module: auth module=baseapp
...
```

The upgrade will occur automatically at height 200. Note: you may need to change the upgrade height in the snippet above if your test play takes more time.
Confirm the upgrade was applied and the chain has continued past the upgrade height:

```shell
./build/simd query upgrade applied v053-to-v054
./build/simd status
```

## Pre-Upgrade Handling

Expand Down
Loading