Performing upgrades
Running a validator and managing upgrades
Validators can choose how to run a validator and manage software upgrades according to their preferred option:
- Using
cosmovisor
- Manual
cosmovisor
is a small process manager for Cosmos SDK application binaries that monitors the governance module for incoming chain upgrade proposals. If it sees a proposal that gets approved, cosmovisor
can automatically download the new binary, stop the current binary, switch from the old binary to the new one, and finally restart the node with the new binary.
We recommend validators to use cosmovisor
to run their nodes. This will make low-downtime upgrades smoother, as validators don’t have to manually upgrade binaries during the upgrade. Instead, they can pre-install new binaries, and cosmovisor
will automatically update them based on the on-chain software upgrade proposals.
Installation instructions
See here for installation instructions.
Voting for Upgrade Proposals
Upgrades
Releases for the dYdX chain will use semantic versioning (opens in a new tab). See here for details.
⚒️ Cosmovisor Users
Upgrading to a new Major/Minor Version (e.g. v0.1.0)
- Download the binary (opens in a new tab) for the new release, rename the binary to
dydxprotocold
.
mv dydxprotocold.<version>-<platform> dydxprotocold
- Make sure that the new binary is executable.
chmod 755 dydxprotocold
- Create a new directory
$DAEMON_HOME/cosmovisor/upgrades/<name>/bin
where<name>
is the URI-encoded name of the upgrade as specified in the Software Upgrade Plan.
mkdir -p $DAEMON_HOME/cosmovisor/upgrades/<name>/bin
- Place the new binary under
$DAEMON_HOME/cosmovisor/upgrades/<name>/bin
before the upgrade height.
mv <path_to_major_version> $DAEMON_HOME/cosmovisor/upgrades/<name>/bin
💡 IMPORTANT: Do this before the upgrade height, so that cosmovisor
can make the switch.
That’s it! The old binary will stop itself at the upgrade height, and cosmovisor
will switch to the new binary automatically. For a Plan
with name v0.1.0
, your cosmovisor/
directory should look like this:
cosmovisor/
├── current/ # either genesis or upgrades/<name>
├── genesis
│ └── bin
│ └── dydxprotocold
└── upgrades
└── v0.1.0
├── bin
└── dydxprotocold
Upgrading to a Patch Version (e.g. v0.0.2)
- Download the binary (opens in a new tab) for the new patch release, rename the binary to
dydxprotocold
.
mv dydxprotocold.<version>-<platform> dydxprotocold
- Make sure that the new binary is executable.
chmod 755 dydxprotocold
- Replace the binary under
$DAEMON_HOME/cosmovisor/current/bin
with the new binary.
mv <path_to_patch_version> $DAEMON_HOME/cosmovisor/current/bin
- Stop the current binary (e.g. Ctrl+C)
- Restart
cosmovisor
cosmovisor run start --p2p.seeds="[seed_node_id]@[seed_node_ip_addr]:26656"
🦾 Manual Users
Upgrading to a Major/Minor Version (e.g. v0.1.0)
- Download the binary (opens in a new tab) for the new release.
- Ideally also before the upgrade height to minimize downtime
- Make sure that the new binary is executable.
chmod 755 dydxprotocold
- Wait for the old binary to stop at the upgrade height (this should happen automatically).
- Restart the application using the new binary from step 1.
./dydxprotocold start --p2p.seeds="[seed_node_id]@[seed_node_ip_addr]:26656"
Upgrading to a Patch Version (e.g. v0.0.2)
- Download the binary (opens in a new tab) for the new release.
- Make sure that the new binary is executable.
chmod 755 dydxprotocold
- Stop the current binary (e.g. Ctrl+C)
- Restart the application using the new binary from step 1.
./dydxprotocold start --p2p.seeds="[seed_node_id]@[seed_node_ip_addr]:26656"
Rollback
In the case of an unsuccessful chain upgrade, an incorrect AppHash
might get persisted by Tendermint. To move forward, validators will need to rollback to the previous state so that upon restart, Tendermint can replay the last block to get the correct AppHash
. Please note: validators should never rollback further than the last invalid block. In extreme edge cases, transactions could be reverted / re-applied for the last black and cause issues.
⚒️ Cosmovisor Users
Cosmovisor backs up the data
directory before attempting an upgrade. To restore to a previous version:
- Stop the node (e.g. Ctrl+C)
- Then, copy the contents of your backup data directory back to
~/.dydxprotocol
rm -rf ~/.dydxprotocol/data
mv ~/.dydxprotocol/data-backup-YYYY-MM-DD ~/.dydxprotocol/data
- Restart your node.
cosmovisor run start --p2p.seeds="[seed_node_id]@[seed_node_ip_addr]:26656"
🦾 Manual Users
If you don’t have a data backup:
- Stop the node (e.g. Ctrl+C)
- Rollback the application and Tendermint state by one block height.
./dydxprotocold rollback
- Restart your node.
./dydxprotocold start --p2p.seeds="[seed_node_id]@[seed_node_ip_addr]:26656"