Developers
Validators
Software Upgrades

Software Upgrades

How to upgrade the Allora software version during hard forks.

The Allora network relies on multiple different pieces of software to do different tasks. For example the allora-chain repository handles the blockchain software that runs the chain, while the offchain-node repository performs off-chain tasks. Each piece of software may need to be upgraded separately.

Allora-Chain Upgrades

The allora-chain software is a cosmos-sdk based blockchain that runs the Allora network. New software releases are published on the Allora Chain Github (opens in a new tab) page and are tagged with a version number. Upgrading to non-breaking versions is as simple as downloading the pre-built binaries or compiling the software from source and running the new version.

Upgrading to a Breaking Version

For breaking versions such as hard forks, or software upgrades requiring changes to the underlying state machine of the allora-chain, the upgrade process is more involved. These upgrades require using the gov and upgrade cosmos-sdk modules to first propose and vote on a software upgrade, and then to execute the upgrade at a specific block height.

For Allora Chain Developers

For writing an upgrade the steps are roughly the following:

  1. In the app/ folder (opens in a new tab), create a new folder for your upgrade.
  2. In that folder create a file that contains an UpgradeName, and a function CreateUpgradeHandler which returns a "cosmossdk.io/x/upgrade/types".UpgradeHandler.Optionally include a UpgradeInfo that is a json string telling the client software where to download the upgrade binary version e.g.
const UpgradeInfo = `'{"binaries":{"linux/amd64":"https://github.com/allora-network/allora-chain/releases/download/v9.9.9/allorad_amd64.tar.gz"}}'`
  1. Wire up the new upgrade handler to the chain by editing the setupUpgradeHandlers function in app/upgrades.go (opens in a new tab). You can see a reference for how to do this in the upgrade integration test here (opens in a new tab)
  2. If you're upgrading standard cosmos-sdk module versions you may have to tweak the module.VersionMap that the CreateUpgradeHandler returns/processes.
  3. If you're upgrading one of the Allora forked/created modules, you'll need to bump the ConsensusVersion for the module.
  4. In the module, have the module.Configurator do a cfg.RegisterMigration with the module name, the previous consensus version that is being upgraded from, and the function to run to do the migration as a parameter.
  5. Write a function that process the kv store or does whatever other migrations are necessary. Examples here (opens in a new tab) and here (opens in a new tab).
  6. Merge the PR, tag it appropriately and post it to the releases page.
  7. Create a Software Upgrade Proposal for validators to vote on. You can see a reference where this is done in the proposeUpgrade (opens in a new tab) function in the integration tests.
  8. Convince all the validators to vote yes on the Software Upgrade Proposal, and run cosmovisor so that the upgrade will actually go through at the proposed block.

For Allora Chain Validator Operators

For those running the chain software, you will have to have to perform an upgrade as follows:

  1. Make sure you're running the allorad software with Cosmovisor (opens in a new tab)) managing the process, DAEMON_NAME=allorad and DAEMON_HOME=/path/to/allorad/data/folder. Hopefully you've already run cosmovisor init /path/to/allorad-binary and have the /allorad/data/folder/cosmovisor set.
  2. At some point the blockchain developers will provide you with a binary to put in that /allorad/data/folder/cosmovisor folder to upgrade to. This may be optional if the UpgradeInfo is set correctly by the developers, but if you're the paranoid type you can always download the binary yourself ahead of the upgrade and put it in the right folder by hand.
  3. When the developers put up the upgrade proposal to governance, be helpful and vote to make it pass. You can do this via the CLI with allorad tx gov vote $proposal_id yes --from $validator or an example of doing this programmatically can be found in the integration test voteOnProposal (opens in a new tab) function.
  4. At the block height of the upgrade, the old software will panic - cosmovisor will catch the panic and restart the process using the new binary for the upgrade instead. Monitor your logs appropriately to see the restart.

Further References

This is probably the most helpful document to understand the full workflow of a cosmos-sdk chain upgrade: Medium Blog Post Cosmos Dev Series: Cosmos Blockchain Upgrade (opens in a new tab)

Cosmos SDK Upgrade Module: Documentation (opens in a new tab)

Cosmovisor Process Manager Software Documentation (opens in a new tab)

Cosmos SDK Gov Module: Documentation (opens in a new tab)

Validator Operationsallorad