Upgrades (cosmovisor)
Safrochain follows the standard Cosmos SDK upgrade pattern: an on-chain
MsgSoftwareUpgrade proposal targets a future block height, and every node
must run the new binary at exactly that height. The simplest way to do this
safely is cosmovisor, a thin process supervisor that watches for the
upgrade plan, halts safrochaind at the target height, swaps the binary
symlink, and restarts.
1 · Install cosmovisor
Linux / macOS
go install cosmossdk.io/tools/cosmovisor/cmd/cosmovisor@latest
cosmovisor version
If ~/go/bin is not in your $PATH:
echo 'export PATH=$PATH:$HOME/go/bin' >> ~/.bashrc
source ~/.bashrc
2 · Lay out the cosmovisor directory
~/.safrochain/cosmovisor/
current -> upgrades/<plan-name> # symlink, cosmovisor manages it
genesis/bin/safrochaind # the binary you launched the chain with
upgrades/<plan-name>/bin/safrochaind
Cosmovisor directories must match the on-chain upgrade plan name (the string passed to MsgSoftwareUpgrade), not necessarily the git tag. Example: aligning testnet to binary v0.2.2 uses plan name v29 → stage at cosmovisor/upgrades/v29/bin/safrochaind. See Testnet upgrade to v0.2.2.
Bootstrap with the binary you have today:
mkdir -p ~/.safrochain/cosmovisor/genesis/bin
cp "$(command -v safrochaind)" ~/.safrochain/cosmovisor/genesis/bin/
3 · Run cosmovisor under systemd
Create /etc/systemd/system/safrochaind.service:
[Unit]
Description=Safrochain (cosmovisor)
After=network-online.target
[Service]
User=safrochain
Environment="DAEMON_HOME=/home/safrochain/.safrochain"
Environment="DAEMON_NAME=safrochaind"
Environment="DAEMON_RESTART_AFTER_UPGRADE=true"
Environment="DAEMON_ALLOW_DOWNLOAD_BINARIES=false"
ExecStart=/home/safrochain/go/bin/cosmovisor run start
Restart=on-failure
RestartSec=5s
LimitNOFILE=1048576
[Install]
WantedBy=multi-user.target
sudo systemctl daemon-reload
sudo systemctl enable --now safrochaind
sudo journalctl -u safrochaind -f
4 · Stage a new release before the upgrade height
When the foundation announces a release tag (for example v0.3.0, see
Mainnet software upgrade to v0.3.0), stage it under the plan name directory.
Either build it from the tag (git checkout v0.3.0 && make build, then copy ./bin/safrochaind), or
download the statically linked release binary and verify it against the release SHA256SUMS:
RELEASE=v0.3.0 # release tag
PLAN=v0.3.0 # on-chain upgrade plan name (cosmovisor directory)
ARCH=amd64 # or arm64
BASE="https://github.com/Safrochain-Org/safrochain-node/releases/download/${RELEASE}"
cd /tmp
curl -fLO "${BASE}/safrochaind-${RELEASE}-linux-${ARCH}"
curl -fLO "${BASE}/SHA256SUMS"
sha256sum -c --ignore-missing SHA256SUMS # must print: ... OK
mkdir -p ~/.safrochain/cosmovisor/upgrades/${PLAN}/bin
install -m 0755 "safrochaind-${RELEASE}-linux-${ARCH}" ~/.safrochain/cosmovisor/upgrades/${PLAN}/bin/safrochaind
~/.safrochain/cosmovisor/upgrades/${PLAN}/bin/safrochaind version --long | grep -E '^version:|^cosmos_sdk_version:|^go:'
cosmovisor will pick up the new binary automatically when it sees the matching upgrade plan on chain.
5 · Watch the upgrade height
# the active proposal (height + name)
safrochaind query upgrade applied $RELEASE
safrochaind query upgrade plan
# tail logs through the upgrade
sudo journalctl -u safrochaind -f
At the upgrade height, cosmovisor will halt the running binary, switch
the current symlink, and restart. After restart, confirm:
safrochaind status \
| jq '.node_info.version, .sync_info.latest_block_height'
6 · If something goes wrong
If a validator does not come back within ~5 minutes:
sudo journalctl -u safrochaind -n 500 --no-pager
If cosmovisor flipped the symlink but the new binary panics, flip it back to the previous version manually and coordinate with other validators in the operator channel:
sudo systemctl stop safrochaind
cd ~/.safrochain/cosmovisor
ln -sfn upgrades/<previous-version> current
sudo systemctl start safrochaind
7 · Coordinated chain restart (no governance)
Used only in emergencies (state corruption, panic loop). The foundation will publish:
- a new
genesis.json(export-genesis from a healthy archive) + sha256 - a new chain id, if any
Each operator:
sudo systemctl stop safrochaind
# replace genesis
sudo cp genesis-...json ~/.safrochain/config/genesis.json
# wipe local state but keep node_key.json + priv_validator_key.json
safrochaind comet unsafe-reset-all --keep-addr-book
sudo systemctl start safrochaind
Watch peers reconnect and consensus form. Coordinate timing in the operator channel before doing this.