Protocol upgrades

A chain is its genesis plus its rules. The genesis never changes. The rules can change at a fixed height, and balances, stakes, addresses, history and the chain ID carry on: more capacity, another block rate or cut interval, new transaction kinds, a new signature scheme. Mainnet starts with one rule set.

Rule sets

Each rule set has a protocol version and a parameter hash. Every cut names the rule set of its height, and every node checks it against its own schedule: the genesis rule set followed by the upgrades its release knows, each with an activation height.

• Upgrades of public networks ship inside a node release. Nothing a peer sends can change the rules a node applies.
• The protocol version rises with every upgrade, and the network, the chain ID and the genesis stay as they are.
• An upgrade can take effect at any height. Epochs and emission intervals keep their days: the day in progress ends where it was going to, and the new day length counts from there.
• The difficulty carries over into the new rules, and transactions signed before the upgrade stay valid after it.

Before an upgrade

A release that schedules an upgrade is announced well before its height.

1. Install the release on every node before the activation height.
2. Check next_upgrade in GET /v1/node/status: it shows the height, protocol version and parameter hash of the next change the node's release knows.
3. Validators that have not updated by the height cannot sign its cuts. When fewer than two thirds of the stake run the release, the chain waits at that height until enough validators update.

A node that missed an upgrade

A node whose release does not know an upgrade follows the chain up to the height before it. When the committee certifies the first cut under the new rules, the node:

• stops following and never blames its peers for it;
• stops voting, if it is a validator;
• logs that the network follows rules its release does not know;
• reports the height and protocol version as update_required in GET /v1/node/status.

Installing the release lets it continue. Only a certificate from the committee the node computed itself can stop it this way.

Peers also tell each other which rules they know. When a peer runs a release with rules this one does not have, the node logs a warning once and reports the peer's claim as update_announced. The claim changes nothing else. A peer with a different history of rules for the same chain is refused.

For developers

• protocol_version and params_hash in GET /v1/node/status, the transaction manifest and the fee quote describe the rules of the next cut.
• Wallets and SDK users need no change for an upgrade unless it introduces new transaction kinds.
• Changes to consensus rules start as an improvement proposal.

The full specification is protocol/traidag-upgrades-v1.md in the node repository.