Skip to main content

Overview

Learn how to manage complete and validator node chain upgrades. Three sorts of updates are available:

  • Planned or Unplanned: Chain upgrades can be planned at a given height through an upgrade proposal plan or happen unexpectedly.
  • Breaking or Non-breaking: Backwards compatibility may be impacted by upgrades that break State Machines or APIs. In order to fix this, the genesis file or application state would need to be migratedin advance of the upgrade.
  • Data Reset Upgrades: Some upgrades require a complete data reset to clear the state. This occasionally happens when there is a rollback or hard fork.

Additionally, validators can select the upgrade management method that best suits their preferences:

  • Automatic or Manual Upgrades: Validator can either manually carry out the update or run the cosmovisor process to do it out automatically.

Planned Upgrades​

Planned upgrades are scheduled upgrades that are coordinated and employ the logic of the upgrade module. Because it takes care of the state migration for the new release automatically, this makes it easier to upgrade Humans.ai to a new (breaking) software version.

Governance Proposal​

An update can be coordinated via a governance proposal, or 'software-proposal', at a specific height or time.

tip

Software updates are no exception to the rule that all governance initiatives must wait until the voting session is over before being implemented. When submitting a software upgrade proposal, take this time into account.

If the proposal passes, the upgrade Plan, which uses a specific upgrade logic to migrate the state, is scheduled to occur at the specified upgrade height and is stored to the blockchain state. The Plan.Height in a new proposal can be updated to either postpone or speed up the upgrade.

Hard Forks​

Hard fork upgrades are a unique kind of scheduled upgrade. As opposed to Governance Proposals, hard forks do not necessitate waiting through the entire voting session. They are therefore perfect for coordinating security flaws and patches.

The application's BeginBlock (i.e., before the transactions for the block are completed) is where the upgrade (fork) block height is set. The blockchain will then automatically schedule an upgrade Plan for that height and start the upgrading procedure once it reaches that height. The block activities (BeginBlock, transaction processing, and state Commit) carry on as usual after the upgrade.

tip

A patch version with the BeginBlock upgrade scheduling logic must first be produced in order to carry out an upgrade hard fork. The nodes of those validators will automatically cease and upgrade the binary after +2/3 of them have upgraded to the new patch version.

Unplanned Upgrades​

Unplanned upgrades occur when every validator must gracefully halt and shut down each of their nodes at precisely the same time in the upgrading process. To do this, run the humansd start command with the --halt-height flag set.

Before restarting their nodes, validators will need to move the state and genesis if there are breaking changes during an unplanned update (see below).

tip

The primary issue with unplanned upgrades is that the blockchain data needs to be reset and the genesis state exported. Those who must employ archival nodes to serve queries for the pre-upgrade heights include infrastructure providers, tools, and clients like block explorers and clients.

Breaking and Non-Breaking Upgrades​

According to the semantic versioning(Semver) of the corresponding software release version (i.e. vX.Y.Z), upgrades can be classified as breaking or non-breaking:

  • Major version (X): backward incompatible API and state machine breaking changes.
  • Minor version (Y): new backward compatible features. These can be also be state machine breaking.
  • Patch version (Z): backwards compatible bug fixes, small refactors and improvements.

Major Versions​

If the new version you are upgrading to contains breaking changes, you must:

  1. Migrate genesis JSON
  2. Migrate application state
  3. Restart node
tip

To avoid double signing or pausing the chain during consensus, this must be done.

The humansd export command can be used to export the genesis file locally or to retrieve it from a trusted source.

Minor Versions​

If the new version you are upgrading to contains breaking changes, you must:

  1. Migrate the state (if applicable)
  2. Restart node

Patch Versions​

A patch can be updated by:

  1. Stop Node
  2. Download new release binary manually
  3. Restart node

Data Reset Upgrades​

When performing Data Reset upgrades, node operators must completely wipe the blockchain clean and restart their nodes using the same validator keys.

Automatic or Manual Upgrades​

We strongly advise full nodes and validator operators to upgrade their software whenever a new version is released.

Your node can be upgraded either way:

  • Automatically updating the software version and restart the node once the upgrade occurs;
  • Download the new binary and perform a manual upgrade.