From 2bef24c5192174672b49b015f307006385e03dd9 Mon Sep 17 00:00:00 2001 From: sydhds Date: Mon, 27 Jan 2025 10:59:11 +0100 Subject: [PATCH] Update versioning doc with vote system description + tests --- massa-versioning/src/lib.rs | 22 ++++++++++++++++------ 1 file changed, 16 insertions(+), 6 deletions(-) diff --git a/massa-versioning/src/lib.rs b/massa-versioning/src/lib.rs index 60af9a824d4..226328c5a4d 100644 --- a/massa-versioning/src/lib.rs +++ b/massa-versioning/src/lib.rs @@ -7,15 +7,19 @@ //! MIPState -> Deployment state of a MIPInfo //! MIPStore -> A map of MIPInfo -> MipState //! +//! Check massa-versioning/src/mips.rs file for a list of already defined MIPInfo. //! //! # Notes on MipInfo versions //! //! There is 2 different 'versions': //! * version == Network version -> This is the network version to announce and thus is stored in block header -//! * component_version -> This is the version for the associated component and is used in VersioningFactory (e.g KeyPair, Address, VM) +//! * component_version -> This is the version for the associated component (stored in a MIPInfo) and is used in VersioningFactory (e.g. KeyPair, Address, VM) //! //! # Notes on MipInfo timings and stats //! +//! MipStore stats is in fact a voting system. Node runners can agree on a new version (a new list of MIPInfo) by +//! updating their node software. If a majority of node runners do not update, the new version will be rejected. +//! //! So in the execution module and after a block become final, we update the MipStore stats (in a blocking way). //! By updating the stats, we mean sending: (Slot timestamp, Option<(current: u32, announced: Option)>). //! Using the slot timestamp, ensure that the trigger (and the trigger timeout) is a consensus by all nodes @@ -29,7 +33,7 @@ //! so we need to make sure that everyone has seen as final the slot that triggered the locked-in state, //! and the worst-case delay required for a slot to become final is the definition of a cycle. //! -//! The activation delay counts how long we wait to activate after the vote threshold was reached +//! The activation delay counts how long we wait to activate after the vote threshold was reached, //! and we entered into locked-in state. During that delay, and after it, the number of blocks considered //! for the vote is not relevant. The only reason why we should consider a sufficient number of votes //! is to get a reasonable p-value on the vote itself: @@ -43,15 +47,15 @@ //! * A state machine (stores the current state of deployment for a MipInfo) //! * A history (stores a list of `Advance` message that 'really' updated the state machine) //! -//! A auto generated graph of the state machine can be found here: +//! An auto generated graph of the state machine can be found here: //! * dot -Tpng ./target/machine/componentstate.dot > ./target/machine/componentstate.png //! * xdg-open ./target/machine/componentstate.png //! //! History is there in order to: //! * Query the state at any time, so you can query MipStore and ask the best version at any time //! * Used a lot when merging 2 MipStore: -//! * By replaying the history of the states of the received MipStore (bootstrap), we can safely updates in the bootstrap process -//! * + When we init MipStore (at startup), this ensures that we have a time ranges & versions consistent list of MipInfo +//! * By replaying the history of the states of the received MipStore (bootstrap), we can safely update in the bootstrap process +//! * + When we initialize a MipStore (at startup), this ensures that we have a time ranges & versions consistent list of MipInfo //! * For instance, this can avoid to have 2 MipInfo with the same name //! //! # Versioning Factory @@ -59,7 +63,7 @@ //! A Factory trait is there to ease the development of factory for Versioned component (e.g. address, block) //! //! All factories should query MIPStore in order to create a component with correct version; default implementation -//! are provided by the trait to avoid re writing these query functions. +//! are provided by the trait to avoid re-writing these query functions. //! //! Unit tests in versioning_factory.rs shows a basic but realistic implementation of a AddressFactory (impl the Factory trait) //! @@ -71,6 +75,12 @@ //! //! By writing only 'Active' MIP in state_cf column, we ensure that the final state hash remains the same between //! the versioning transition (e.g. User 1 has upgraded to network version 1 while User 2 has not yet upgraded) +//! +//! # Tests +//! +//! The massa-versioning module has a bunch of unit test in versioning.rs. Note that functional test, +//! can be found in https://github.com/massalabs/massa-functional-tests/blob/main/tests_versioning.py. +//! Note that those tests might not be up to date with the latest module code. pub mod address_factory; pub mod grpc_mapping;