Chain Upgrade

This guide outlines the steps required to upgrade your Sentinel Hub software. Follow these instructions carefully to ensure a smooth process.

Upgrade List

Upgrade #	Binary Version	Name	Block Height	Proposal #	Commit Hash
0 (Hard Fork)	v0.6.2	sentinelhub-2	901,801	/	4cd6b2b
1	v0.7.0	upgrade-1	1,272,000	3	600fd5f
2	v0.8.3	upgrade-2	2,586,000	5	fa7cd3c
3	v0.9.2	upgrade-3	5,125,000	9	d04a400
4	v0.10.1	upgrade-4	9,348,475	19	bbe6fab
5	v0.11.2	v11	12,310,005	30	54c28ae
6	v12.0.0	v12_0_0	23,997,755	64	eb3c5c4

Build the Binary

When the upgrade is available clone the Sentinel Hub repository, checkout at the new version and install it

git clone https://github.com/sentinel-official/sentinelhub.git "${HOME}/sentinelhub"
cd "${HOME}/sentinelhub"
git checkout <new_version>
make install

Automatic Upgrade: Cosmovisor

If you’re using or planning to use Cosmovisor (see the guide), the upgrade process will be mostly automatic. Once the new binary is built and placed in the correct directory, Cosmovisor will take care of the rest.

note

Upgrades can be either consensus-breaking or non-consensus-breaking. Follow the appropriate section below depending on the upgrade type.

Consensus Breaking (Chain Upgrade)

Create the upgrade directory inside Cosmovisor with the name of the version (for the last upgrade was v12_0_0 as you can see here under the section plan, tab name)

mkdir -p ~/.sentinelhub/cosmovisor/upgrades/<upgrade_name>/bin

Copy sentinelhub binary in it

cp ~/go/bin/sentinelhub ~/.sentinelhub/cosmovisor/upgrades/<upgrade_name>/bin

Check if the sentinelhub binary upgrade was copied and if it is the correct version:

~/.sentinelhub/cosmovisor/upgrades/<upgrade_name>/bin/sentinelhub version

Now that you have prepared and deployed the new binary, the remaining steps will be managed by Cosmovisor when the upgrade is scheduled to take place. Here's a breakdown of the process:

When the designated block height is reached, the blockchain temporarily halts its operations. Following this, an upgrade-info.json file is generated and put into the folder .sentinelhub/cosmovisor/upgrades/<upgrade_name>/.

The content of this file will be the following, based on the last hub upgrade:

.sentinelhub/cosmovisor/upgrades/<upgrade_name>/

{"name":"v12_0_0","time":"0001-01-01T00:00:00Z","height":23997755}

The Cosmovisor system identifies the existence of this file and triggers the required sequence of actions. These actions include pausing the node, inserting the relevant binary into the specified directory, and subsequently restarting the node.

This carefully orchestrated sequence guarantees a seamless transition and successful execution of the blockchain upgrade.

Non Consensus Breaking

For non-consensus upgrades, you only need to replace the running binary with the new one.

Stop cosmovisor

sudo systemctl stop cosmovisor.service

Copy the newly created Sentinel Hub binary into Cosmovisor

cp go/bin/sentinelhub .sentinelhub/cosmovisor/current/bin/

Verify that the cosmovisor version is current

cosmovisor version

Start cosmovisor

sudo systemctl start cosmovisor

Monitor the logs to confirm the successful execution of the process

journalctl -u cosmovisor.service -f --output=cat

Manual Upgrade

If you’re not using Cosmovisor, follow these manual steps once the blockchain halts at the upgrade block height.

Stop the node

Check the current block height to confirm it matches the upgrade height:

curl -fsLS http://127.0.0.1:26657/status | jq -r '.result.sync_info.latest_block_height'

Then stop the Sentinel Hub service:

sudo systemctl stop sentinelhub.service

Install the new version

Link the new binary:

# For Ubuntu installation
sudo ln -s "${GOBIN}/sentinelhub" /usr/bin/sentinelhub

# For manual installation
sudo ln -s "${GOBIN}/sentinelhub" /usr/local/bin/sentinelhub

Start the node

Verify the version:

sentinelhub version --long

Restart the service:

sudo systemctl start sentinelhub.service

In Case of Upgrade Failure

• Roll back to the previous version (e.g., if upgrade-6 fails, use version v0.11.2).

• Confirm the rollback version matches the upgrade table above.

• Restart the node using the --unsafe-skip-upgrades flag at the upgrade height:

sentinelhub start --unsafe-skip-upgrades <block_height>

This allows the node to continue syncing while minimizing downtime.