# Upgrade Guide v2.0

This document provides an overview of the upgrade process and guidelines for node operators upgrading from Regen Ledger v1.0 to v2.0.

The upgrade on Regen Mainnet will be preceded by an upgrade on Redwood Testnet to give node operators an opportunity to go through the upgrade process on a live network before going through the same process on Regen Mainnet.

Note: Redwood Testnet uses the same configuration as Regen Mainnet aside from the voting period; the voting period for Redwood Testnet is 86400s (1 day) whereas the voting period for Regen Mainnet is 1209600s (14 days). The upgrade will be rigorously tested on temporary test networks before being performed on Redwood Testnet and Regen Mainnet.

# Upgrade Details

# Regen Ledger v2.0

# Regen Mainnet

# Redwood Testnet

  • Upgrade Height: 548703

# Upgrade Overview

Regen Ledger v2.0 introduces breaking changes. In order to upgrade a live network to a new version of software that introduces breaking changes, there must be an agreed upon block height at which blocks are no longer produced with the old version of the software and only with the new.

The expected version and the upgrade height are defined within a software upgrade (opens new window) proposal. If the proposal passes, the chain will halt at the proposed upgrade height. At this point, node operators will need to stop running the current binary and start running the upgrade binary.

We recommend node operators use Cosmovisor (opens new window), which is a process manager for running a blockchain's application binary. When the chain halts at the proposed upgrade height, Cosmovisor will automatically stop the current binary and start the upgrade binary. Node operators can prepare the upgrade binary ahead of time and then relax at the time of the upgrade.

# In-Place Store Migrations

The upgrade to Regen Ledger v2.0 leverages a new feature introduced in Cosmos SDK v0.43 called "In-Place Store Migrations" (opens new window). This new feature prevents the need for node operators to restart the chain using an updated genesis file. Regen Ledger includes a registerUpgradeHandlers() (opens new window) method that registers handlers for performing an upgrade's necessary state migrations in-place.

# Upgrade Guidelines

# Update Go

The latest version of Go (1.17) is required. For more information, see Go (opens new window).

# Option 1: Using Cosmovisor

Cosmovisor v1.0 with the auto-download option disabled is required. Node operators must prepare the upgrade binary in advance.

WARNING

The auto-download option is not supported in Cosmovisor v1.0 when upgrading from Regen Ledger 1.0 (because it uses Cosmos SDK v0.42). Cosmovisor v0.1 supports the auto-download option but it will not work with the proposal due to an issue with unwanted whitespace in the upgrade-info field. Enabling the auto-download option will result in an error and a failed restart at the time of the upgrade.

# Cosmovisor Not Installed

The following instructions assume regen is already installed but cosmovisor is not.

Install Cosmovisor:

go install github.com/cosmos/cosmos-sdk/cosmovisor/cmd/cosmovisor@v1.0

Check to ensure the install was successful:

cosmovisor version

Note: The above command should print out information about cosmovisor and multiple configuration errors. This is expected using the latest version of cosmovisor (v1.0.0) and can be ignored for the purpose of checking the install was successful.

Create the directory for the genesis binary (v1.0.0) and copy the regen binary (assuming that the regen binary is already installed and stored in the $GOBIN directory):

mkdir -p $HOME/.regen/cosmovisor/genesis/bin
cp $GOBIN/regen $HOME/.regen/cosmovisor/genesis/bin

Either download the upgrade binary (v2.0.0) or build it from source:

cd regen-ledger
git fetch --all
git checkout v2.0.0
make build

Create the directory for the upgrade binary (v2.0.0) and copy the regen binary (assuming that the regen binary was built from source and stored in the build directory):

mkdir -p $HOME/.regen/cosmovisor/upgrades/v2.0-upgrade/bin
cp $HOME/regen-ledger/build/regen $HOME/.regen/cosmovisor/upgrades/v2.0-upgrade/bin

Create cosmovisor systemd service file:

echo "[Unit]
Description=Cosmovisor daemon
After=network-online.target
[Service]
Environment="DAEMON_NAME=regen"
Environment="DAEMON_HOME=${HOME}/.regen"
Environment="DAEMON_RESTART_AFTER_UPGRADE=true"
Environment="DAEMON_ALLOW_DOWNLOAD_BINARIES=false"
User=${USER}
ExecStart=${GOBIN}/cosmovisor start
Restart=always
RestartSec=3
LimitNOFILE=4096
[Install]
WantedBy=multi-user.target
" >cosmovisor.service

Move the file to the systemd directory:

sudo mv cosmovisor.service /lib/systemd/system/cosmovisor.service

If you have not already done so, stop the current process running regen.

Reload systemctl and start cosmovisor:

sudo systemctl daemon-reload
sudo systemctl start cosmovisor

Check the status of the cosmovisor service:

sudo systemctl status cosmovisor

At the proposed block height, cosmovisor will automatically stop the current binary (v1.0.0), set the upgrade binary as the new current binary (v2.0.0), and then restart the node.

# Cosmovisor Already Installed

The following instructions assume cosmovisor is already installed.

Make sure Cosmovisor is up-to-date:

go install github.com/cosmos/cosmos-sdk/cosmovisor/cmd/cosmovisor@v1.0

Check to ensure the install was successful:

cosmovisor version

Note: The above command should print out information about cosmovisor and multiple configuration errors. This is expected using the latest version of cosmovisor (v1.0.0) and can be ignored for the purpose of checking the install was successful.

Update cosmovisor systemd service file and make sure the environment variables are set to the appropriate values (assuming that cosmovisor has been set up as a systemd service):

echo "[Unit]
Description=Cosmovisor daemon
After=network-online.target
[Service]
Environment="DAEMON_NAME=regen"
Environment="DAEMON_HOME=${HOME}/.regen"
Environment="DAEMON_RESTART_AFTER_UPGRADE=true"
Environment="DAEMON_ALLOW_DOWNLOAD_BINARIES=false"
User=${USER}
ExecStart=${GOBIN}/cosmovisor start
Restart=always
RestartSec=3
LimitNOFILE=4096
[Install]
WantedBy=multi-user.target
" >cosmovisor.service

Restart cosmovisor to ensure the environment variables have been updated:

sudo systemctl stop cosmovisor
sudo systemctl daemon-reload
sudo systemctl start cosmovisor

Either download the upgrade binary (v2.0.0) or build it from source:

cd regen-ledger
git fetch --all
git checkout v2.0.0
make build

Create the folder for the upgrade binary (v2.0.0) and copy the regen binary (assuming that the regen binary was built from source and stored in the build directory):

mkdir -p $HOME/.regen/cosmovisor/upgrades/v2.0-upgrade/bin
cp $HOME/regen-ledger/build/regen $HOME/.regen/cosmovisor/upgrades/v2.0-upgrade/bin

At the proposed block height, cosmovisor will automatically stop the current binary (v1.0.0), set the upgrade binary as the new current binary (v2.0.0), and then restart the node.

# Option 2: Without Cosmovisor

Using Cosmovisor to perform the upgrade is not required. Node operators also have the option to manually update the regen binary at the time of the upgrade.

When the chain halts at the proposed upgrade height, stop the current process running regen.

Either download the upgrade binary (v2.0.0) or build it from source:

cd regen-ledger
git fetch --all
git checkout v2.0.0
make install

Ensure the regen binary has been updated:

regen version

Restart the process running regen.