Skip to main content

Protocol Upgrades

The IOTA protocol, framework, and execution engine are frequently updated to include new features and bug fixes. This new functionality is released as part of our regular software updates to validator operators. However, the IOTA protocol requires all validators to agree on the results of executing each transaction.

This creates a challenge: How to release code that changes transaction execution, given that it's impossible to ensure all operators upgrade their software simultaneously? Additionally, how to ensure that all IOTA transaction history can be replayed even after functionality has changed?

To address this, IOTA uses a process called protocol upgrades.

Protocol Upgrade Process​

The protocol upgrade process includes the following steps:

  1. An IOTA developer codes the new feature but restricts access to it using a "feature flag"—a boolean config variable that is initially set to false.
  2. The value of the feature flag is retrieved from a struct called ProtocolConfig.
  3. The developer creates a new version of the ProtocolConfig struct where the new feature flag is set to true.
  4. A new release of the IOTA validator software is built and released to validator and full node operators.
  5. When the validator process starts, it continues to use the previous version of ProtocolConfig (with the flag set to false). This ensures all validators behave identically, regardless of whether they have the new software or not.
  6. As validators are upgraded, they signal to the rest of the validator committee that they are prepared to switch to the new version of the configuration (with the flag enabled).
  7. If enough validators vote to switch to the new protocol version, the new version takes effect at the beginning of the next epoch.
  8. The new feature then comes into effect.

Full nodes follow a similar process but do not participate in voting. Instead, they follow the actions that validators recorded.

When validators switch to a new protocol version, they do so by recording the new version number in the special end-of-epoch transaction. Full nodes execute this transaction as they replay the chain history, allowing them to switch to the new protocol version at the right time.

Framework Upgrades​

Not all new IOTA functionality comes from changes to the validator code. There are also changes to the IOTA framework. For example, IOTA developers periodically add new native functions to the framework to expose new functionality to smart contracts. The process for framework updates is similar to protocol upgrades.

Instead of using feature flags, IOTA objects coordinate framework changes. The IOTA framework is a special object with ID 0x2. The Move source code for the framework is built into the validator binary.

If the validator notices that its built-in framework differs from the framework in object 0x2, it signals to the other validators that it would like to upgrade the framework to a new version. If enough validators agree to perform the upgrade, the new framework object is written at the end of the current epoch. Transactions executed in the new epoch then use the new version of the framework.

Quizzes​

Question 1/4

What is the main challenge addressed by IOTA’s protocol upgrade process?