Skip to main content

Protocol Upgrades

The IOTA protocol, framework, and execution engine are frequently updated to introduce new features and bug fixes. These updates are released as part of regular software updates for validator operators. However, since all validators must agree on the results of each transaction execution, introducing changes to transaction execution presents a challenge.

  • How to ensure that all validators upgrade their software in a coordinated manner?

  • How to ensure that the transaction history remains consistent and replayable despite protocol changes?

IOTA addresses these challenges through a structured protocol upgrade process.

Protocol Upgrade Process​

Protocol Versioning​

Validators run the iota-node software, which supports multiple protocol versions, including future versions. The protocol version is determined by the ProtocolConfig struct. Validators that do not support the current protocol version cannot participate in consensus.

The protocol version to be executed in the next epoch is recorded on-chain in a special end-of-epoch transaction. This ensures that all validators switch to the new protocol version at the same time.

Upgrade Steps​

  1. Implementation: IOTA developers introduce a new protocol version by updating the ProtocolConfig struct with properties and values, which may include feature flags to control specific functionalities within the new version.

  2. Software Release: A new iota-node binary is released, and validators update their software. After restarting, validators continue to run the previous protocol version until the upgrade is activated.

  3. Upgrade Signaling: Upgraded validators signal their readiness to switch to the new protocol version. This is done through consensus among the validator committee.

  4. Consensus and Activation: If enough validators agree to switch, the new protocol version is recorded on-chain at the end of the current epoch. The next epoch then executes using the upgraded protocol version.

Full nodes follow a similar process but do not participate in voting. Instead, they synchronize with validators to ensure they execute transactions using the correct protocol version.

IOTA Move Framework Upgrades​

The IOTA Move Framework is a collection of system smart contracts built into the validator binary. These contracts provide essential functionalities, such as native functions for smart contracts.

The upgrade process for the IOTA Move Framework follows a similar structure to protocol upgrades:

  1. Framework Update in Software: IOTA developers introduce changes to the IOTA Move Framework within the validator binary.

  2. Software Release and Validator Updates: A new iota-node binary containing the updated framework is released. Validators update their software but continue using the existing framework until the upgrade is activated.

  3. Upgrade Signaling: If a validator detects that its built-in framework differs from the framework stored on-chain (object 0x2), it signals its intent to upgrade.

  4. Consensus and Activation: Once enough validators agree, the new framework version is written to object 0x2 at the end of the epoch. The next epoch then executes using the updated framework.