Node Upgrades ​

Network upgrades are occasionally required in order to add new features to the chain, make security fixes, etc.

There are two ways to perform a network upgrade:

• Cosmovisor (⚠️ work-in-progress)
• Manual Upgrade

Running Cosmovisor ​

Instead of manually performing challenging operational tasks late at night, it's preferable to automate them, and that's precisely what Cosmovisor aims to accomplish. Cosmovisor enables you to obtain binaries in advance for chain upgrades, which allows you to perform chain upgrades with minimal or no downtime. The process of installing Cosmovisor is fairly simple, but it requires specific environmental variables and the proper arrangement of folders.

1) Install Cosmovisor ​

Firstly, go install cosmovisor

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

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

Confirm the installation was successful:

which cosmovisor

which cosmovisor

2) Add Environment Variables to Your Shell ​

In the .profile file, usually located at ~/.profile, add:

export DAEMON_NAME=berad
export DAEMON_HOME=$HOME/.berad

export DAEMON_NAME=berad
export DAEMON_HOME=$HOME/.berad

Then enable these variables by sourcing the profile:

source ~/.profile

source ~/.profile

Setup Filesystem ​

Cosmovisor expects a certain folder structure

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

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

Don't worry about current - that is simply a symlink used by Cosmovisor. The other folders will need setting up, but this is easy:

mkdir -p $DAEMON_HOME/cosmovisor/genesis/bin && mkdir -p $DAEMON_HOME/cosmovisor/upgrades

mkdir -p $DAEMON_HOME/cosmovisor/genesis/bin && mkdir -p $DAEMON_HOME/cosmovisor/upgrades

Setup Genesis Binary ​

Cosmovisor needs to know which binary to use at genesis. We put this in $DAEMON_HOME/cosmovisor/genesis/bin.

First, find the location of the binary you want to use:

which berad

which berad

Then use the path returned to copy it to the directory Cosmovisor expects. Let's assume the previous command returned /home/your-user/go/bin/berad:

cp $HOME/go/bin/berad $DAEMON_HOME/cosmovisor/genesis/bin

cp $HOME/go/bin/berad $DAEMON_HOME/cosmovisor/genesis/bin

3) Initialize Cosmovisor ​

To create the directories and copy the binary, run this command:

cosmovisor init $HOME/go/bin/berad

cosmovisor init $HOME/go/bin/berad

4) Setup Service ​

Commands sent to Cosmovisor are sent to the underlying binary. For example, cosmovisor version is the same as typing berad version.

Nevertheless, just as we would manage berad using a process manager, we would like to make sure Cosmovisor is automatically restarted if something happens, for example an error or reboot.

First, create the service file:

sudo nano /etc/systemd/system/berad.service

sudo nano /etc/systemd/system/berad.service

Change the contents of the below to match your setup - cosmovisor is likely at ~/go/bin/cosmovisor regardless of which installation path you took above, but it's worth checking.

[Unit]
Description=Berachain Daemon (cosmovisor)
After=network-online.target

[Service]
User=<your-user>
ExecStart=/home/<your-user>/go/bin/cosmovisor run start
Restart=always
RestartSec=3
LimitNOFILE=4096
Environment="DAEMON_NAME=berad"
Environment="DAEMON_HOME=/home/<your-user>/.berad"
Environment="DAEMON_ALLOW_DOWNLOAD_BINARIES=false"
Environment="DAEMON_RESTART_AFTER_UPGRADE=true"
Environment="DAEMON_LOG_BUFFER_SIZE=512"

[Install]
WantedBy=multi-user.target

[Unit]
Description=Berachain Daemon (cosmovisor)
After=network-online.target

[Service]
User=<your-user>
ExecStart=/home/<your-user>/go/bin/cosmovisor run start
Restart=always
RestartSec=3
LimitNOFILE=4096
Environment="DAEMON_NAME=berad"
Environment="DAEMON_HOME=/home/<your-user>/.berad"
Environment="DAEMON_ALLOW_DOWNLOAD_BINARIES=false"
Environment="DAEMON_RESTART_AFTER_UPGRADE=true"
Environment="DAEMON_LOG_BUFFER_SIZE=512"

[Install]
WantedBy=multi-user.target

5) Start Cosmovisor ​

Enable and start the service:

sudo -S systemctl daemon-reload
sudo -S systemctl enable berad
# check config one last time before starting!
sudo systemctl start berad

sudo -S systemctl daemon-reload
sudo -S systemctl enable berad
# check config one last time before starting!
sudo systemctl start berad

Ensure that it is up and running:

sudo systemctl status berad
journalctl -fu berad # if monitoring required

sudo systemctl status berad
journalctl -fu berad # if monitoring required

Performing a Manual Upgrade ​

You can always perform the upgrade yourself instead of using Cosmovisor. Here's a walkthrough of how to do it manually:

1) Backup Existing Data ​

Before any upgrade, you should back up all your data. This includes your .berad folder, which contains your blockchain data and keys.

2) Download the New Version ​

Go to the official Berachain repository. Download the latest release binary or build the application from source.

3) Verify the New Version ​

Check the corresponding hash of the binary to ensure it is authentic.

4) Stop the Running Node ​

Stop your running blockchain node. Depending on your configuration, this will either involve a terminal Exit command like Ctrl-C or if you're running the node as a service something like systemctl stop berad.

5) Install the New Version ​

Replace the old binary (e.g., berad) with the new one. Make sure the new binary is executable and located somewhere in your PATH.

6) Run Migration (If Necessary) ​

If the new version includes state-breaking changes, a migration script will be provided. Run this script to upgrade your Berachain data to the new format.

7) Start the Node ​

Start your node again.

berad start

berad start

8) Verify the Upgrade ​

Check your node's logs to verify that the upgrade was successful and the node is producing or syncing new blocks.