# MultiversX Node upgrades

> Plan and execute MultiversX node upgrades safely: scheduling, compatibility considerations, and operational steps.

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](https://t.me/MultiversXValidators)
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](https://github.com/multiversx/mx-chain-mainnet-config), [mx-chain-testnet-config](https://github.com/multiversx/mx-chain-mainnet-config) and [mx-chain-devnet-config](https://github.com/multiversx/mx-chain-mainnet-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` |