MultiversX Node upgrades

As opposed to a hard fork, which is a change in the protocol that is not backward compatible, MultiversX performs regular node upgrades, which are changes in the protocol that are backward compatible and bring new features, improvements and bugs fixes. Nodes operators must be aware of the upgrade process and the steps they need to take in order to avoid any downtime.

Introduction

Once a new node's binary is ready to be deployed on one of the networks (mainnet, testnet or devnet), nodes operators must perform the upgrade to the newest version. These releases are always announced on MultiversX Validators chat plus via other communication channels, depending on the case.

When to upgrade

Subscribe to email notifications for new releases from the official GitHub repositories that hold the chain configuration (mx-chain-mainnet-config, mx-chain-testnet-config and mx-chain-devnet-config. Also, make sure to join the Validators Telegram channel.

Setup monitoring and get alerts for new updates. As last resort, check the status of your validator software version using the relevant Explorer section https://explorer.multiversx.com/nodes - outdated versions will be marked with ⚠

Types of upgrades

Currently, we have the following types of upgrades:

A. - all nodes need to upgrade: upgrades that involve processing changes with an activation epoch (as explained below) and have to be performed by all nodes operators in order to keep the same view over the network and not cause service disruptions.

B. - optional upgrades: upgrades that, for example, simply add a new Rest API endpoint or improve the trie syncing timing are not critical from a processing point of view, and they are optional. If the nodes operators think the new feature will help them, they can proceed with the upgrade without losing the compatibility with the network.

C. - only validators need to upgrade: upgrades that, for example, include new features that only trigger validators (ratings changes, transactions selection improvements and so on). Observers (nodes that don't have a stake attached) don't need to perform the upgrade (but can upgrade nonetheless if desired).

Activation epochs

In order to make the upgrades as smooth as possible and to ensure that each node has the same view over the network at a given moment, MultiversX has a so called activation epoch mechanism that allows the node to implement both behaviors of the protocol - the old (current) one, and the new one, planned for activation at a specific epoch. This mechanisms ensures that, until the protocol change becomes active, nodes with an upgraded codebase / binary remain compatible with nodes that did not perform the upgrade, and consensus is held. Although this happens in 99.9% cases, this is not 100% guaranteed due to the unforeseen consequences when upgrading the code base in parallel with executing transactions generated by 3rd parties (MultiversX blockchain users)

Deterministic time / height for upgrades

As compared to other protocols that perform upgrades that start at a specific block height, releases for MultiversX nodes don't have a specific block height where the new updates become effective, but rather the first block in the activation epoch will make the nodes proceed with the updated versions of the components.

Since the height of the first block in an epoch cannot be known in advance (due to possible roll-backs), the network height where a feature becomes effective cannot be calculated.

However, the time when a new feature of a bugfix becomes effective can be calculated, as epochs have fixed lengths in rounds. Currently, MultiversX Mainnet has epochs of 14,400 rounds and a round is 6 sec. This results in a 24h epoch. However, there can be delays of a few rounds, due to rollbacks of the start of epoch metablocks.

Activation epoch example

For example, let's say that we want to introduce a feature so that smart contracts can receive a PayableBySC metadata that will allow them to receive EGLD or other tokens from other smart contracts.

Timeline example

• the MultiversX Mainnet is at epoch 590.

• currently, the node binary doesn't know about the PayableBySC metadata so if one wants to try it, an error like invalid metadata will be returned.

• at epoch 600, we release a new node binary that contains the PayableBySC metadata that will become active starting with epoch 613.

• all nodes operators perform the upgrade.

• when epoch 613 begins, the new feature activates and the new metadata is recognized and accepted.

• if one wants to issue a smart contract that is PayableBySC, it will work.

• nodes that didn't perform the upgrade will produce a different output of the transaction (as compared to the majority) and won't be able to keep up with the rest of the chain.

Backwards compatibility explained:
If one wants to process all the blocks since genesis (via full archive or via import-db) with the released binary it will behave this way:

• if for example, in epoch 455 there was a transaction that tried to set the PayableBySC metadata, it will process it as invalid metadata
• for transactions in epochs newer than 613 it will process the new metadata.

	Epoch < 613	Epoch >= 613
IsPayableBySC	invalid metadata	successful