Branislav Kontur
bb8ddc46c1
I started this investigation/issue based on @liamaharon question [here](https://github.com/paritytech/polkadot-sdk/pull/1801#discussion_r1410452499). ## Problem The `pallet_balances` integrity test should correctly detect that the runtime has correct distinct `HoldReasons` variant count. I assume the same situation exists for RuntimeFreezeReason. It is not a critical problem, if we set `MaxHolds` with a sufficiently large value, everything should be ok. However, in this case, the integrity_test check becomes less useful. **Situation for "any" runtime:** - `HoldReason` enums from different pallets: ```rust /// from pallet_nis #[pallet::composite_enum] pub enum HoldReason { NftReceipt, } /// from pallet_preimage #[pallet::composite_enum] pub enum HoldReason { Preimage, } // from pallet_state-trie-migration #[pallet::composite_enum] pub enum HoldReason { SlashForContinueMigrate, SlashForMigrateCustomTop, SlashForMigrateCustomChild, } ``` - generated `RuntimeHoldReason` enum looks like: ```rust pub enum RuntimeHoldReason { #[codec(index = 32u8)] Preimage(pallet_preimage::HoldReason), #[codec(index = 38u8)] Nis(pallet_nis::HoldReason), #[codec(index = 42u8)] StateTrieMigration(pallet_state_trie_migration::HoldReason), } ``` - composite enum `RuntimeHoldReason` variant count is detected as `3` - we set `type MaxHolds = ConstU32<3>` - `pallet_balances::integrity_test` is ok with `3`(at least 3) However, the real problem can occur in a live runtime where some functionality might stop working. This is due to a total of 5 distinct hold reasons (for pallets with multi-instance support, it is even more), and not all of them can be used because of an incorrect `MaxHolds`, which is deemed acceptable according to the `integrity_test`: ``` // pseudo-code - if we try to call all of these: T::Currency::hold(&pallet_nis::HoldReason::NftReceipt.into(), &nft_owner, deposit)?; T::Currency::hold(&pallet_preimage::HoldReason::Preimage.into(), &nft_owner, deposit)?; T::Currency::hold(&pallet_state_trie_migration::HoldReason::SlashForContinueMigrate.into(), &nft_owner, deposit)?; // With `type MaxHolds = ConstU32<3>` these two will fail T::Currency::hold(&pallet_state_trie_migration::HoldReason::SlashForMigrateCustomTop.into(), &nft_owner, deposit)?; T::Currency::hold(&pallet_state_trie_migration::HoldReason::SlashForMigrateCustomChild.into(), &nft_owner, deposit)?; ``` ## Solutions A macro `#[pallet::*]` expansion is extended of `VariantCount` implementation for the `#[pallet::composite_enum]` enum type. This expansion generates the `VariantCount` implementation for pallets' `HoldReason`, `FreezeReason`, `LockId`, and `SlashReason`. Enum variants must be plain enum values without fields to ensure a deterministic count. The composite runtime enum, `RuntimeHoldReason` and `RuntimeFreezeReason`, now sets `VariantCount::VARIANT_COUNT` as the sum of pallets' enum `VariantCount::VARIANT_COUNT`: ```rust #[frame_support::pallet(dev_mode)] mod module_single_instance { #[pallet::composite_enum] pub enum HoldReason { ModuleSingleInstanceReason1, ModuleSingleInstanceReason2, } ... } #[frame_support::pallet(dev_mode)] mod module_multi_instance { #[pallet::composite_enum] pub enum HoldReason<I: 'static = ()> { ModuleMultiInstanceReason1, ModuleMultiInstanceReason2, ModuleMultiInstanceReason3, } ... } impl self::sp_api_hidden_includes_construct_runtime::hidden_include::traits::VariantCount for RuntimeHoldReason { const VARIANT_COUNT: u32 = 0 + module_single_instance::HoldReason::VARIANT_COUNT + module_multi_instance::HoldReason::<module_multi_instance::Instance1>::VARIANT_COUNT + module_multi_instance::HoldReason::<module_multi_instance::Instance2>::VARIANT_COUNT + module_multi_instance::HoldReason::<module_multi_instance::Instance3>::VARIANT_COUNT; } ``` In addition, `MaxHolds` is removed (as suggested [here](https://github.com/paritytech/polkadot-sdk/pull/2657#discussion_r1443324573)) from `pallet_balances`, and its `Holds` are now bounded to `RuntimeHoldReason::VARIANT_COUNT`. Therefore, there is no need to let the runtime specify `MaxHolds`. ## For reviewers Relevant changes can be found here: - `substrate/frame/support/procedural/src/lib.rs` - `substrate/frame/support/procedural/src/pallet/parse/composite.rs` - `substrate/frame/support/procedural/src/pallet/expand/composite.rs` - `substrate/frame/support/procedural/src/construct_runtime/expand/composite_helper.rs` - `substrate/frame/support/procedural/src/construct_runtime/expand/hold_reason.rs` - `substrate/frame/support/procedural/src/construct_runtime/expand/freeze_reason.rs` - `substrate/frame/support/src/traits/misc.rs` And the rest of the files is just about removed `MaxHolds` from `pallet_balances` ## Next steps Do the same for `MaxFreezes` https://github.com/paritytech/polkadot-sdk/issues/2997. --------- Co-authored-by: command-bot <> Co-authored-by: Bastian Köcher <git@kchr.de> Co-authored-by: Dónal Murray <donal.murray@parity.io> Co-authored-by: gupnik <nikhilgupta.iitk@gmail.com>
Phragmén Election Module
An election module based on sequential phragmen.
Term and Round
The election happens in rounds: every N blocks, all previous members are retired and a new set is elected (which may
or may not have an intersection with the previous set). Each round lasts for some number of blocks defined by
TermDuration storage item. The words term and round can be used interchangeably in this context.
TermDuration might change during a round. This can shorten or extend the length of the round. The next election
round's block number is never stored but rather always checked on the fly. Based on the current block number and
TermDuration, the condition BlockNumber % TermDuration == 0 being satisfied will always trigger a new election
round.
Voting
Voters can vote for any set of the candidates by providing a list of account ids. Invalid votes (voting for
non-candidates) are ignored during election. Yet, a voter might vote for a future candidate. Voters reserve a bond as
they vote. Each vote defines a value. This amount is locked from the account of the voter and indicates the weight of
the vote. Voters can update their votes at any time by calling vote() again. This keeps the bond untouched but can
optionally change the locked value. After a round, votes are kept and might still be valid for further rounds. A voter
is responsible for calling remove_voter once they are done to have their bond back and remove the lock.
Voters also report other voters as being defunct to earn their bond. A voter is defunct once all of the candidates that
they have voted for are neither a valid candidate anymore nor a member. Upon reporting, if the target voter is actually
defunct, the reporter will be rewarded by the voting bond of the target. The target will lose their bond and get
removed. If the target is not defunct, the reporter is slashed and removed. To prevent being reported, voters should
manually submit a remove_voter() as soon as they are in the defunct state.
Candidacy and Members
Candidates also reserve a bond as they submit candidacy. A candidate cannot take their candidacy back. A candidate can end up in one of the below situations:
- Winner: A winner is kept as a member. They must still have a bond in reserve and they are automatically counted as a candidate for the next election.
- Runner-up: Runners-up are the best candidates immediately after the winners. The number of runners_up to keep is
configurable. Runners-up are used, in order that they are elected, as replacements when a candidate is kicked by
[remove_member], or when an active member renounces their candidacy. Runners are automatically counted as a candidate for the next election. - Loser: Any of the candidate who are not a winner are left as losers. A loser might be an outgoing member or runner, meaning that they are an active member who failed to keep their spot. An outgoing will always lose their bond.
Renouncing candidacy
All candidates, elected or not, can renounce their candidacy. A call to [Module::renounce_candidacy] will always cause
the candidacy bond to be refunded.
Note that with the members being the default candidates for the next round and votes persisting in storage, the election
system is entirely stable given no further input. This means that if the system has a particular set of candidates C
and voters V that lead to a set of members M being elected, as long as V and C don't remove their candidacy and
votes, M will keep being re-elected at the end of each round.
Module Information
License: Apache-2.0