Skip to main content

Perform a chain upgrade

In this guide, we will go through upgrading your node during network upgrades, chain halt upgrades and hard forks. Depending on if you are using Cosmovisor or not, there are key differences. Please note that the use of cosmovisor is recommended.

Using cosmovisor vs. not using cosmovisor​

  • Using Cosmovisor: Cosmovisor is an upgrade manager for Cosmos SDK-based blockchains. It lets you automatically switch to the new binary when the specified block height for the upgrade is reached. Additionally, you can enable cosmovisor to download the upgrade automatically. In any case, for hard forks, you will still need to replace the genesis file manually.

  • Not Using Cosmovisor: If you are not using Cosmovisor, you are responsible for manually managing the upgrade process. This involves downloading, verifying, and extracting the new binary, and restarting the node once the specified block height is reached. Similarly to when using cosmovisor, for hard forks you will need to replace the genesis file manually.

info

It is highly recommended to use Cosmovisor, as it is considered the standard best practice to run nodes.

In either case, make sure to monitor the upgrade details on Discord or look at upcoming upgrade proposals via the block explorer. It is recommended to be aware about the exact block height for the upgrade, so that action can be taken in case specific steps are required.

Network Upgrades​

With cosmovisor (auto-download enabled)​

If you enable Cosmovisor to automatically perform binary downloads, only the following steps are required:

  • Monitor the upgrade details on Discord or stay updated about upcoming upgrade proposals via the block explorer. It is recommended to be aware about the exact block height for the upgrade, so that action can be taken in case specific steps are required.

  • Cosmovisor will automatically switch to the new binary when the specified block height is reached.

Please make sure to always be aware of upcoming upgrades even if you enabled the automatic download, so you can make sure you are aware of any risks.

With cosmovisor (auto-download disabled)​

If you are using cosmovisor with the automatic download disabled, you will need to download the binary manually. In this scenario, the steps would be:

  • Monitor the upgrade details on Discord or stay updated about upcoming upgrade proposals via the block explorer. It is recommended to be aware about the exact block height for the upgrade, so that action can be taken in case specific steps are required.

Within the cosmovisor upgrades directory, go to the folder relative to the specific binary version you are looking to download, for example:

cd "${HOME}"/.terp/cosmovisor/upgrades/2.0.0/bin

Download the latest release, in this case:

wget - https://github.com/terpnetworkterp-core/releases/download/terpd_v2.0.0_linux_amd64

You can then verify the download by looking at its sha256 hash using the sha256sum command:

sha256sum terpd_linux_amd64

You can then download the sha256 checksum file relative to the release file:

wget terpsh256.txt https://github.com/terpnewtork/terp-core/releases/download/v2.0.0/terpd_v2.0.0_checksums.txt

and ensure that both sha256 hashes are identical. If they match, the downloaded file matches the actual release file.

Once the upgrade block height is reached, cosmovisor will automatically stop the old binary and start the latest one.

Hard forks​

The process for hard forks is similar to the one for Network upgrades but includes additional steps for replacing the genesis file.

When using cosmovisor, the process slightly differs depending on if you enabled or disabled the auto-download feature.

Cosmovisor with auto-download enabled​

If you have allowed the auto-download feature, you would just need to replace the genesis file.

Cosmovisor with auto-download disbled​

If you have disabled the auto-download feature, then you would need to:

Replace the genesis file​

First, download the new genesis file to your local machine. The genesis file for each respective network can be found on the networks page.

For example, you can download the genesis with:

curl -Ls https://raw.githubusercontent.com/terpnetwork/mainnet/main/morocco-1/genesis.json > $HOME/.terp/config/genesis.json

Before replacing the current genesis file, it's good practice to create a backup. Navigate to the directory containing the genesis file (usually located in the config folder) and create a backup:

cd ~/.terp/config
cp genesis.json genesis.json.backup

Replace the current genesis file with the new one you downloaded earlier. Assuming you have downloaded the new genesis file as new-genesis.json, you can replace the existing file using the following command:

cp /path/to/new-genesis.json ~/.terp/config/genesis.json

Make sure to replace /path/to/new-genesis.json with the actual path to the new genesis file.

You will now need to reset your node's data to start with the new genesis file. You can do this using the following command:

terpd tendermint unsafe-reset-all

If you have already updated the binary (either manually or through Cosmovisor), you can now restart your node to complete the process:

sudo systemctl restart terpd

Keep in mind that the process of replacing the genesis file is the same whether you are using Cosmovisor or not. Cosmovisor only helps automate the binary upgrade, while replacing the genesis file remains a manual process.

Chain Halt Upgrades​

Chain halt upgrades are a specific type of upgrade process triggered by the discovery of a critical protocol bug that necessitates an urgent chain upgrade. Unlike regular upgrades, these don't wait for a governance proposal due to the immediate need for a fix.

The workflow for a chain halt upgrade involves the following steps:

  • Validators and node operators shut the node down.
  • Download a new terpd binary and replace the old one on the node.
  • Restart the node.

Shutting down the node​

The first step in a chain halt upgrade is for all validators and node operators to stop their node's operation. This is an essential step to prevent any further spread the consequences of the issue across the network.

If you are running terpd as a service, you can launch: 

sudo systemctl stop terpd

Download the Binary​

Similarly to network upgrades, within the cosmovisor upgrades directory, you can go to the folder relative to the specific binary version you are looking to download, for example:

cd "${HOME}"/.terp/cosmovisor/upgrades/v2.0.0/bin

And download the new terp-core binary from the release page.

For example:

wget https://github.com/terpnetwork/terp-core/releases/download/v2.0.0/terpd_v2.0.0_linux_amd64

You can now verify the download by generating the sha256 hash for the downloaded file:

sha256sum terpd_linux_amd64

You can then download the sha256 checksum file relative to the release file:

wget terpsha256.txt https://github.com/terpnetwork/terp-core/releases/download/v2.0.0/terpd_v2.0.0__checksums.txt

You can compare that the sha256 hash strings match, ensuring that the downloaded file matches the actual release file.

Restart the Node​


sudo systemctl start terpd