Using Cosmovisor in Story Protocol: a Guide

Story Protocol emphasizes the importance of using Cosmovisor for the Odyssey testnet. The smooth operation of Story Protocol is vital for the many ecosystem projects that actively run campaigns, mint badges, and customize Story Protocol’s PILs for their specific needs. A fast and seamless upgrade minimizes downtime and reduces the likelihood of errors.

The recent upgrade to Story v0.13.0 was an example of outstanding coordination between all involved validators, being completed in under two minutes. The credit goes, first and foremost, to the clear guidance from the Story core team and the widespread adoption of Cosmovisor by the node operators.

Our previous overviews provide more information about Story Protocol and its PIL. This material, however, focuses on using Cosmovisor for blockchain upgrades on the protocol and explains its importance for maintaining the safe and resilient operation of nodes.

How Cosmovisor Enhances Node Upgrades

Since integrating into the Cosmos SDK toolkit, Cosmovisor has made things easier for developers by automating most of the manual work and monitoring previously required during node upgrades. This simple and reliable binary switcher ensures that nodes update seamlessly at the specified height, significantly reducing delays and missed upgrades.

Synchronized upgrades across all nodes are critical for any blockchain’s performance. Faster upgrades mean better overall network health and stability. With Cosmovisor, developers can pre-configure the upgrade process by providing the necessary data as soon as it’s available from official sources.

Here’s how Cosmovisor works:

1. Reads upgrade-info.json: Generated by the x/upgrade module at the designated height.
2. Downloads the new binary: Automatically fetches and switches to the latest binary.
3. Restarts the node: Ensures nodes are operational post-upgrade.

Although Cosmovisor automates downloading and installing new binaries, node operators are ultimately responsible for ensuring they use reliable ones. Even with Cosmovisor, operators should carefully review upgrade proposals and independently verify the integrity of new binaries.

Cosmovisor for Story Protocol: Setup Guide

Given the utmost importance of timely upgrades, Everstake’s DevOps team is happy to share our best practices for using Cosmovisor, including its installation, migration, and upgrade configuration.

Install Cosmovisor

Use the following commands to install Cosmovisor:

wget https://github.com/cosmos/cosmos-sdk/releases/download/cosmovisor%2Fv1.5.0/cosmovisor-v1.5.0-linux-amd64.tar.gz 

tar -xvf cosmovisor-v1.5.0-linux-amd64.tar.gz

mv cosmovisor /usr/local/bin

Migrate Cosmovisor

Migrate using these steps:

export DAEMON_NODE='story'
export DAEMON_HOME='$HOME/.story' # path to current node home

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

# stop the node and place current binary to cosmovisor folder
systemctl stop storyd
mv $(which story) $DAEMON_HOME/cosmovisor/genesis/bin/story
# to be able to use binary via cli
ln -s $DAEMON_HOME/cosmovisor/current/bin/story /usr/local/bin/story


# edit /etc/systemd/system/storyd.service file and change next lines: 
ExecStart=/usr/local/go/bin/story run --home ... --engine-jw-file ...
# to
ExecStart=/usr/local/bin/cosmovisor run run \
	--home ... \ # NODE HOME
	--engine-jwt-file # PATH TO GETH JWTSECRET

# Add these lines above ExecStart, as configuration fo cosmovisor 
Environment="DAEMON_NAME=story"
Environment="DAEMON_HOME=$HOME/.story" 
# ^ path to node home
Environment="DAEMON_ALLOW_DOWNLOAD_BINARIES=false"
Environment="DAEMON_RESTART_AFTER_UPGRADE=true"
Environment="DAEMON_DATA_BACKUP_DIR=$HOME/.story/backup"
# ^ path to backup directory. It will be empty once you skipping backups. But required for cosmovisor
Environment="UNSAFE_SKIP_BACKUP=true"


# after these changes, run the updated service 
systemctl daemon-reload
systemctl start storyd && journalctl -u storyd -f 

Prepare for the upgrade

Schedule the upgrade manually:

# add upgrade

cosmovisor add-upgrade v0.13.0  $HOME/.story/cosmovisor/upgrades/v0.13.0/bin/story --force --upgrade-height 8580000

# example of output, if configured correct

12:32PM INF Using $HOME/.story/cosmovisor/upgrades/v0.13.0/bin/story for v0.13.0 upgrade module=cosmovisor

12:32PM INF Upgrade binary located at/home/story/.story/cosmovisor/upgrades/v0.13.0/bin/story module=cosmovisor

12:32PM INF /home/story/.story/data/upgrade-info.json created, v0.13.0 upgrade binary will switch at height 8580000 module=cosmovisor

# verify upgrade-info.json is created and is not empty

cat /home/story/.story/data/upgrade-info.json

Conclusion

Ensuring all nodes are properly and timely upgraded is one of the main responsibilities of any validator on any blockchain, no matter the size. 

With extensive experience supporting numerous Cosmos SDK-based blockchains, Everstake has successfully utilized Cosmovisor across various blockchain networks, including testnet and mainnet environments, and recommends using it for all Cosmos-based networks.