Story Node Upgrade Guide

This guide provides instructions for upgrading your node to Story v0.14.0.

Upgrading Your Node

The upgrade process outlined in this guide includes automated and manual approaches to ensure that your node is correctly updated and continues functioning as expected in the upgraded network. The automated upgrade section will cover Cosmovisor, a tool that streamlines the upgrade process by automating various tasks and minimizing node downtime. The manual upgrade section will guide you through the steps to upgrade your node manually, including monitoring the node, stopping and restarting the client, and verifying the upgrade status.

Automated Upgrade Procedure with Cosmovisor

To simplify the process of upgrading your consensus client, especially during hard forks, it is recommended to use Cosmovisor. This tool automates the upgrade of client binaries, allowing the node to transition smoothly without requiring manual stops and restarts.

Please note that the installed Cosmovisor version must be at least v1.7.0. Please follow this guide if you need help setting up or configuring Cosmovisor.

1.Prepare the Story Client Environment
To upgrade to Story v0.14.0, the existing story client must first be running version v0.13.0.

To download the v0.13.0 binaries directly, run the following:

• Linux x86_64

wget https://github.com/piplabs/story/releases/download/v0.13.0/story-linux-amd64

• Linux ARMv8

wget https://github.com/piplabs/story/releases/download/v0.13.0/story-linux-arm64

• Mac x86_64

wget https://github.com/piplabs/story/releases/download/v0.13.0/story-darwin-amd64

• Mac 64-bit ARM

wget https://github.com/piplabs/story/releases/download/v0.13.0/story-darwin-arm64

2. Setup and Configure Cosmovisor

You can skip this step if cosmovisor is already running; in that case, proceed directly to step 5.

As mentioned above, Cosmovisor must be installed to at least version v1.7.0 to upgrade Story.

You can verify that Cosmovisor was successfully installed by checking its current version:

cosmovisor version

Expected sample output:

% cosmovisor version
cosmovisor version: v1.7.0

Once done, define the necessary environment variables needed to configure Cosmovisor:

export DAEMON_HOME=${STORY_DATA_ROOT}
export DAEMON_NAME=story
export DAEMON_DATA_BACKUP_DIR=~/story_backup_folder # Specify your backup directory

STORY_DATA_ROOT refers to the data root folder used by the story client — by default, it is assigned the following values, which you should use unless overriding with your folder:

• Mac OS X: ~/Library/Story/story
• Linux: ~/.story/story

For DAEMON_NAME, ensure it is the same as the name of the story client binary, which should be story.

The DAEMON_DATA_BACKUP_DIR can be set to any custom data backup directory.

3. Initialize Cosmovisor:

You can skip this step if cosmovisor is already running; in that case, proceed directly to step 5.

Once Cosmovisor is already setup and configured, initialize it with:

cosmovisor init ${STORY_CLIENT}

Example command:

cosmovisor init /usr/local/bin/story

Verify that Cosmovisor was successfully installed by checking its current version:

cosmovisor version

Expected sample output:

% cosmovisor version
cosmovisor version: v1.7.0

4. Run Story as a Managed Process

You can skip this step if cosmovisor is already running; in that case, proceed directly to step 5.

Start story under Cosmovisor’s management by running the following command (note that the first run is to start Cosmovisor, and the second is the story run command):

cosmovisor run run

To verify that the Story client is running correctly is running correctly, follow our documentation for more information about this step.

5. Schedule the Client Upgrade

Start by downloading Story v0.14.0 binaries into a local folder:

• Linux x86_64

wget https://github.com/piplabs/story/releases/download/v0.14.0/story-linux-amd64

• Linux ARMv8

wget https://github.com/piplabs/story/releases/download/v0.14.0/story-linux-arm64

• Mac x86_64

wget https://github.com/piplabs/story/releases/download/v0.14.0/story-darwin-amd64

• Mac 64-bit ARM

wget https://github.com/piplabs/story/releases/download/v0.14.0/story-darwin-arm64

To schedule an upgrade to a new client version at a specific block height, cosmovisor should already be running. Once confirmed, open a separate terminal and run:

cosmovisor add-upgrade ${CLIENT_VERSION} ${NEW_STORY_CLIENT} --force --upgrade-height ${UPGRADE_HEIGHT}

Then run the following command to check if the upgrade was successfully scheduled:

cat ${PATH_TO_STORY_DATA}/upgrade-info.json

Example commands:

Schedule the upgrade:

cosmovisor add-upgrade v0.14.0 story-linux-amd64/story --force --upgrade-height 1349000

Verify whether it was successfully scheduled:

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

Afterward, the console should display the following output:

{"name":"v0.14.0","time":"0001-01-01T00:00:00Z","height":1349000}

If the output is not as expected, delete the upgrade-info.json file, rerun the cosmovisor add-upgrade command, and verify the result again.

If successfully scheduled, cosmovisor will automatically replace the current consensus client with the new binary at the specified upgrade height.

To confirm that the replacement was successful, running the cosmovisor version command should display the path corresponding to the upgraded version, as shown in the following example:

% cosmovisor version
cosmovisor version: v1.7.0
11:27PM INF running app args=["version"] module=cosmovisor path=/home/ec2-user/story/cosmovisor/upgrades/v0.14.0/bin/story
Version       v0.13.0-stable
Git Commit    9603826
Git Timestamp 2024-12-18T15:43:11Z

Manual Upgrade Procedure for Story Client

1. Wait for the Node to Reach the Upgrade Block Height. Monitor the node until it reaches the predetermined upgrade block height. The story client should automatically panic at this point, signaling that the node has reached the upgrade height.
2. Stop the Existing Story Client. Once the node reaches the upgrade block height and the story client panics, stop the existing story client to prepare for the upgrade. This can be done by terminating the process running the client.
3. Start the New Story Client. Replace the old story client with the new version. Then, start the new story client to initiate the upgrade process. To verify that the Story client is running correctly, follow our Public Testnet Guide for more information about this step.
4. Verify Node Status Post-Upgrade. Check the status of the new story client to ensure it either continues to function correctly or enters a waiting state. The network requires upgrading at least two-thirds of the voting power before resuming normal operations. Verify that the node correctly joins the upgraded network and reaches consensus. You can read our documentation for more information about this step.

Unjailing

If a node becomes jailed, run the following command on the validator:

./story validator unjail --validator-pubkey={validator_public_key} --rpc https://odyssey.storyrpc.io/ --chain-id 1516

Replace the validator_public_key value with the validator’s actual public key, and verify that the address has a balance of at least 1 IP.