Validators
Upgrades
Performing Upgrades

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:

  1. Using cosmovisor
  2. 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

See Governance -> Voting

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)

  1. Download the binary (opens in a new tab) for the new release, rename the binary to dydxprotocold.
mv dydxprotocold.<version>-<platform> dydxprotocold
  1. Make sure that the new binary is executable.
chmod 755 dydxprotocold
  1. 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
  1. 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)

  1. Download the binary (opens in a new tab) for the new patch release, rename the binary to dydxprotocold.
mv dydxprotocold.<version>-<platform> dydxprotocold
  1. Make sure that the new binary is executable.
chmod 755 dydxprotocold
  1. Replace the binary under $DAEMON_HOME/cosmovisor/current/bin with the new binary.
mv <path_to_patch_version> $DAEMON_HOME/cosmovisor/current/bin
  1. Stop the current binary (e.g. Ctrl+C)
  2. 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)

  1. Download the binary (opens in a new tab) for the new release.
    1. Ideally also before the upgrade height to minimize downtime
  2. Make sure that the new binary is executable.
chmod 755 dydxprotocold
  1. Wait for the old binary to stop at the upgrade height (this should happen automatically).
  2. 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)

  1. Download the binary (opens in a new tab) for the new release.
  2. Make sure that the new binary is executable.
chmod 755 dydxprotocold
  1. Stop the current binary (e.g. Ctrl+C)
  2. 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:

  1. Stop the node (e.g. Ctrl+C)
  2. 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
  1. 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:

  1. Stop the node (e.g. Ctrl+C)
  2. Rollback the application and Tendermint state by one block height.
./dydxprotocold rollback
  1. Restart your node.
./dydxprotocold start --p2p.seeds="[seed_node_id]@[seed_node_ip_addr]:26656"
Types of UpgradesNetwork Constants