Validators & Full-Nodes
Upgrades
Performing Upgrades

Performing Upgrades

Managing Upgrades

Validators can choose how to run a validator and manage software upgrades according to their preferred option:

  1. Using Cosmovisor
  2. Manual

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" --bridge-daemon-eth-rpc-endpoint="<eth rpc endpoint>"

🦾 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" --bridge-daemon-eth-rpc-endpoint="<eth rpc endpoint>"

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" --bridge-daemon-eth-rpc-endpoint="<eth rpc endpoint>"

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" --bridge-daemon-eth-rpc-endpoint="<eth rpc endpoint>"

🦾 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" --bridge-daemon-eth-rpc-endpoint="<eth rpc endpoint>"
Types of UpgradesCosmovisor