Coordinated protocol updates

Introduction

As of release 1.2.0 the Radix node software introduces a coordinated protocol update mechanism.

This page contains an overview of how it works and how to use it from the node runner’s point of view.

What is a protocol update?

The node software consists of a set of protocol versions (historically, these were inaccurately called fork configurations). Each protocol version defines a set of rules for the Radix Engine. At any given time the node uses a single protocol version and runs its corresponding engine ruleset.

Up to version 1.2.0, the Radix Olympia mainnet defines two protocol versions:

  • the genesis protocol version ran for the first epoch - and included configuration to make the first epoch very long, as an initial network bootstrapping configuration

  • the olympia v1 protocol version started at epoch 2 - and was the main olympia configuration

Two nodes using different protocol versions will process transactions using different sets of rules and may not agree as to the output ledger state. As a result, the network could split - with two or more groups of nodes not agreeing on whether transactions are valid, or what state should result.

A coordinated protocol updating process is required so that the nodes of a network can transition to a new set of rules together, without affecting network liveness.

Coordinated protocol updating overview

Before release 1.2.0 the Radix engine could only update its protocol version at fixed, predefined epochs. That’s how the genesis and olympia v1 protocol versions were configured.

While this mechanism was good enough for bootstrapping, it is not the most reliable for introducing changes on a living network. Introducing a protocol update with a misjudged fixed epoch could potentially cause a liveness break if not enough validators have managed to upgrade their software on time.

To make the transition as smooth as possible, as of release 1.2.0, the Radix node software implements the coordinated protocol updating mechanism, which allows the network to automatically switch to a newer configuration whenever the validators are ready.

Coordinated protocol updating works by allowing the validators to signal their readiness to run the given protocol version and only enact it when sufficient number of validators (by their stake) have signalled their readiness.

When a new software version is released with a new ruleset for the Radix engine, the corresponding protocol version is contained in a candidate protocol update. An upgraded node still runs the old set of rules and the switchover to the new candidate protocol version is not scheduled at any specific epoch. The switchover happens when a sufficient number of validators have signalled readiness. When the protocol update occurs, any node running the upgraded version with the candidate protocol update will transition to the new set of rules automatically.

In order for the protocol update to actually occur, validators must first signal their readiness to switchover. This requires both running the upgraded software version, and explicitly signalling on ledger that the validator is ready. When enough validators (configurable, but no less than 2/3+1 of the total stake) signal their readiness and remain ready for a configurable number of consecutive epochs, the network switches over to the new protocol version. If a validator is running the new version, the validator will transition to the new ruleset if the protocol update occurs, regardless of whether it has signalled readiness. That said, a validator is strongly encouraged to signal readiness, so that the network will actually perform the update.

After this protocol update point, nodes not running the upgraded version may stop being able to ingest the ledger. Shortly after the protocol update, a new node version will be published which fixes the exact epoch of the protocol update into the node software as a fixed epoch protocol update.

I am a validator, how do I signal my readiness after upgrading?

First, make sure you’re running the latest Radix node software version (the newest version is available on the Github Releases page). You’ll only be able to vote for a candidate protocol update if it’s included in your binary.

Already running the latest version? Good. The recommended way to signal your readiness is to use the radixnode CLI.

Using the radixnode CLI

The signal-protocol-update-readiness command (historically, before CLI 1.3.2, this was signal-candidate-fork-readiness) will guide you through signalling your readiness. Just answer Yes when asked whether you want to signal.

radixnode api core signal-protocol-update-readiness

The CLI is smart enough to know whether you need to signal or not. You won’t be bothered if there’s no candidate protocol update to signal for or if your readiness has already been recorded.

Note that in order to signal your readiness you need your /key API enabled. Make sure you’ve got either the api.sign.enable property in your .config file or $RADIXDLT_SIGN_ENABLE env variable set to true.

Using the Core API

Internally, the readiness signalling mechanism is implemented in terms of "votes" for the candidate protocol update. Each reported readiness is stored on ledger as a candidate protocol update vote.

Use the Core API /key/vote endpoint to submit a vote transaction. The Core API will automatically inject the candidate protocol update vote information for whatever is the newest candidate protocol version included in the software.

Below is an example POST /key/vote request payload

{
  "network_identifier": {
    "network": "mainnet"
  }
}

I am a validator, how do I know whether I need to signal readiness for a protocol update?

As usual, the recommended way is to use the radixnode CLI. The radixnode api core signal-protocol-update-readiness command (historically, before CLI 1.3.2, this was signal-candidate-fork-readiness) will tell you whether you need to signal your readiness for the protocol update.

Alternatively, there’s a fork_vote_status field in the /system/health API response. The return value of VOTE_REQUIRED indicates that a new candidate protocol update present in the software for which the readiness hasen’t yet been signalled. If this is the value you’re receiving - signal your readiness!

Otherwise, if the response is NO_ACTION_NEEDED you’re all good! There isn’t any new unsignalled candidate protocol update included in your software.

I have signalled readiness but I want to rollback my node, what do I do?

If your rolled back node no longer contains a candidate protocol update for which you have signalled readiness, the signal needs to be retracted.

You can also use the radixnode CLI for this. Use the radixnode api core retract-protocol-update-readiness command to retract any readiness signal of yours.

Alternatively, the Core API /key/withdraw-vote endpoint can be used to retract a readiness signal without using the CLI.

Below is an example POST /key/withdraw-vote request payload

{
  "network_identifier": {
    "network": "mainnet"
  }
}

Note that in order to retract your readiness signal you need your /key API enabled. Make sure you’ve got either the api.sign.enable property in your .config file or $RADIXDLT_SIGN_ENABLE env variable set to true.