Implement Version Upgrade Mechanism #3096

paberr · 2024-11-18T21:26:59Z

What's in this pull request?

This PR implements the mechanism to carry out breaking changes (version upgrades) after launch.

It mostly follows the specification in the Albatross paper with one exception:
We will not only check for the proportion of stake supporting the upgrade, but also for the proportion of slots supporting the upgrade. This makes sure we don't propose an upgrade in an epoch where less than 2f+1 elected validators support the upgrade.

⚠️ All changes in this PR that affect the consensus pre-version upgrade are backwards compatible in that the current nodes enforce stricter rules. All consensus breaking changes would only ever be performed post-version upgrade (e.g., deactivating validators).

Mechanism Overview

The version upgrade mechanism introduces the following key changes, discussed in a bit more detail below:

Modified block validity (i.e., when upgrades are possible)
Tools for checking supporting stake/slots
Validators producing blocks with new version
New version upgrade inherent (deactivating unsupporting validators)
Moving validator selection in election blocks from before the accounts commit to after the accounts commit

Block validity

The version number is stored in every block. We allow version upgrades only in election blocks.
Instead of checking against a constant version from the Policy, block-level verification of the version is now split into two parts:

Block::verify_header: Making sure that the version is always below or equal to the maximum supported version Policy::max_supported_version(network_id). The maximum supported version depends on the network, so that we can roll out changes in the testnet first.
Block:: verify_immediate_successor and Block::verify_macro_successor: Making sure that the version number can only increase in election blocks and only in steps of one. For all other scenarios, the version needs to match the predecessor's version. We test this in both functions as these are called in different scenarios.

Helper functions

We only perform version upgrades when at least Policy:: UPGRADE_MIN_SUPPORT% of the active stake signals support for the upgrade and when at least Policy::TWO_F_PLUS_ONE slots of the currently elected validators signals support.
We add helper functions to determine the supporting stake and slots.

The get_supporting_stake function is computationally expensive in that it iterates over all validators in the staking contract. This number is bounded by the validator deposit and we only call the function when proposing an election block and not being on the maximum version already.

Currently, the support for a version is signalled by encoding the supported version in the first two bytes of the validator's signal data (in big-endian). This can still be changed later and be implemented version-specific in the Policy::supports_upgrade function.

We also add a function to deactivate unsupportive stake, which is discussed in the section about the new inherent.

Producing an upgrade

Validators who updated their client and have a maximum supported version higher than the current blockchain's version (determined from the head block) will determine support for this upgrade whenever they are the ones to produce a macro proposal. Only when the conditions (supporting_stake >= Policy:: UPGRADE_MIN_SUPPORT * active stake && supporting_slots > Policy::TWO_F_PLUS_ONE) are met, the proposal will contain the increased version number. If the proposal is accepted, the upgrade is successfully active from this block on (including this election block).

There is no explicit check for validators to only vote for a block if they support the upgrade. If they updated their client and have a new maximum supported version, the proposal will be deemed valid and voted for. Validators not supporting the upgrade won't update their clients and will reject the proposal due to an invalid version.

Version upgrade inherent

The mechanism adds a new inherent VersionUpgrade that also has the new version. It has the side effect of deactivating all validators that did not explicitly signal support for the new version with immediate effect. This also means that these unsupporting validators should not be selected for the next epoch (thus preventing possible stalls).

Full nodes will apply this side-effect through trie-diffs. The inherent is not stored in the history and thus does not require any special handling.

Switching validator selection and accounts commit

In the current model, we first select the validators for the next epoch (based on the current staking contract) and then apply the accounts changes of an election block. The only accounts changes possible in an election block right now are: reward distribution and preparing the bitsets in the staking contract for the next epoch.

Since none of these have an effect on the validator selection, we switch the order of these two. This is required so that unsupporting validators are deactivated before the validator selection.

Tests

This PR includes unit tests in the following crates:

validator: Testing that the validator will propose an election block with a new version if the conditions are met.
block: Testing the new validity rules.
staking_contract: Testing correct computation of stake/slot support and correct handling of inherent.
blockchain: Testing that the blockchain correctly emits the new inherent.

Pull request checklist

All tests pass. The project builds and runs.
I have resolved any merge conflicts.
I have resolved all clippy and rustfmt warnings.

hrxi

I wonder if we should somehow support the case of someone not wanting an upgrade. In that case, they should probably not signal support for it — however, this means that they'll get deactivated on a version upgrade. This puts them in a bad spot. Could we maybe add a "I have technical support for this upgrade but I don't like it" flag that allows a validator to vote against an upgrade while not getting deactivated if it does get activated?

primitives/src/policy.rs

validator/src/tendermint.rs

primitives/src/policy.rs

validator/src/tendermint.rs

blockchain/tests/inherents.rs

blockchain/src/blockchain/inherents.rs

blockchain/src/blockchain/slots.rs

primitives/Cargo.toml

primitives/block/src/block.rs

nibhar

Left some comments mostly for clarity. Functionally this looks good to me.

blockchain/src/blockchain/history_sync.rs

blockchain/src/blockchain/inherents.rs

blockchain/src/blockchain/history_sync.rs

blockchain/src/blockchain/slots.rs

nibhar · 2025-02-15T17:23:57Z

blockchain/src/blockchain/verify.rs

@@ -143,6 +143,22 @@ impl Blockchain {
        if let Block::Macro(macro_block) = block {
            // If we don't have the staking contract, there is nothing we can check.
            if let Some(staking_contract) = self.get_staking_contract_if_complete(Some(txn)) {
+                // Verify validators.
+                let validators = match macro_block.is_election() {
+                    true => Some(self.next_validators(&macro_block.header.seed, Some(txn))),


See other comment about the staking contract requirement.

I don't think the two are equivalent.
next_validators will fetch the staking contract again, which means that inherents have already been applied.

This should be especially important in the upgrade: Some validators just got deactivated.

blockchain/tests/push.rs

light-blockchain/tests/push.rs

primitives/account/src/account/staking_contract/mod.rs

rpc-interface/src/types.rs

validator/src/tendermint.rs

Add function for supporting slots

Produce upgraded blocks after gathering enough support

Implement upgrade test Add block tests Add accounts tree tests and fix block number Test creation of inherent

paberr · 2025-04-05T07:55:27Z

I implemented all suggested changes except the one about next_validator assuming the staking contract is there (this is the same behavior as previously, and I am unsure if passing in the staking contract is semantically equivalent here).

In particular, I moved the max_supported_version into the NetworkInfo similar to the genesis block number.
That successfully removed the network dependency from the policy again.

paberr added the enhancement New feature or request label Nov 18, 2024

paberr self-assigned this Nov 18, 2024

paberr requested a review from hrxi November 18, 2024 21:42

paberr force-pushed the pb/upgrade branch 3 times, most recently from cad6edb to 42076ca Compare November 19, 2024 01:59

paberr requested review from styppo and nibhar November 19, 2024 02:10

hrxi reviewed Feb 13, 2025

View reviewed changes

jsdanielh reviewed Feb 14, 2025

View reviewed changes

blockchain/src/blockchain/inherents.rs Outdated Show resolved Hide resolved

blockchain/src/blockchain/slots.rs Outdated Show resolved Hide resolved

primitives/Cargo.toml Outdated Show resolved Hide resolved

primitives/block/src/block.rs Outdated Show resolved Hide resolved

nibhar reviewed Mar 10, 2025

View reviewed changes

paberr force-pushed the pb/upgrade branch 2 times, most recently from 4f06efc to af5cd81 Compare March 28, 2025 14:48

paberr added 5 commits April 5, 2025 08:22

Add helper functions for upgrades

06993b0

Add function for supporting slots

Allow version upgrades in election blocks

884f16b

Make validator selection dependent on accounts

eb5aa8b

Remove unsupporting validators after upgrade

46f34cc

Produce upgraded blocks after gathering enough support

Make max supported version dependent on network

5be6610

Implement upgrade test Add block tests Add accounts tree tests and fix block number Test creation of inherent

paberr force-pushed the pb/upgrade branch from af5cd81 to 7a3ad0e Compare April 5, 2025 07:41

Implement feedback

e018a9d

paberr force-pushed the pb/upgrade branch from 7a3ad0e to e018a9d Compare April 5, 2025 07:51

paberr requested review from jsdanielh, hrxi and nibhar April 5, 2025 07:53

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Implement Version Upgrade Mechanism #3096

Implement Version Upgrade Mechanism #3096

paberr commented Nov 18, 2024

hrxi left a comment

nibhar left a comment

nibhar Feb 15, 2025

paberr Apr 5, 2025

paberr commented Apr 5, 2025

Implement Version Upgrade Mechanism #3096

Are you sure you want to change the base?

Implement Version Upgrade Mechanism #3096

Conversation

paberr commented Nov 18, 2024

What's in this pull request?

Mechanism Overview

Block validity

Helper functions

Producing an upgrade

Version upgrade inherent

Switching validator selection and accounts commit

Tests

Pull request checklist

hrxi left a comment

Choose a reason for hiding this comment

nibhar left a comment

Choose a reason for hiding this comment

nibhar Feb 15, 2025

Choose a reason for hiding this comment

paberr Apr 5, 2025

Choose a reason for hiding this comment

paberr commented Apr 5, 2025