Merge pull request #258 from mnaamani/council-election-refactor

Docs for set_election_parameters

node/src/chain_spec.rs

@@ -18,9 +18,9 @@ use node_runtime::{
     versioned_store::InputValidationLengthConstraint as VsInputValidation, ActorsConfig,
     AuthorityDiscoveryConfig, BabeConfig, Balance, BalancesConfig, ContentWorkingGroupConfig,
     CouncilConfig, CouncilElectionConfig, DataObjectStorageRegistryConfig,
-    DataObjectTypeRegistryConfig, GrandpaConfig, ImOnlineConfig, IndicesConfig, MembersConfig,
-    Perbill, ProposalsConfig, SessionConfig, SessionKeys, Signature, StakerStatus, StakingConfig,
-    SudoConfig, SystemConfig, VersionedStoreConfig, DAYS, WASM_BINARY,
+    DataObjectTypeRegistryConfig, ElectionParameters, GrandpaConfig, ImOnlineConfig, IndicesConfig,
+    MembersConfig, Perbill, ProposalsConfig, SessionConfig, SessionKeys, Signature, StakerStatus,
+    StakingConfig, SudoConfig, SystemConfig, VersionedStoreConfig, DAYS, WASM_BINARY,
 };
 pub use node_runtime::{AccountId, GenesisConfig};
 use primitives::{sr25519, Pair, Public};
@@ -235,14 +235,16 @@ pub fn testnet_genesis(
         }),
         election: Some(CouncilElectionConfig {
             auto_start: true,
-            announcing_period: 3 * DAYS,
-            voting_period: 1 * DAYS,
-            revealing_period: 1 * DAYS,
-            council_size: 12,
-            candidacy_limit: 25,
-            min_council_stake: 10 * DOLLARS,
-            new_term_duration: 14 * DAYS,
-            min_voting_stake: 1 * DOLLARS,
+            election_parameters: ElectionParameters {
+                announcing_period: 3 * DAYS,
+                voting_period: 1 * DAYS,
+                revealing_period: 1 * DAYS,
+                council_size: 12,
+                candidacy_limit: 25,
+                min_council_stake: 10 * DOLLARS,
+                new_term_duration: 14 * DAYS,
+                min_voting_stake: 1 * DOLLARS,
+            },
         }),
         proposals: Some(ProposalsConfig {
             approval_quorum: 66,

runtime-modules/governance/src/election.rs

@@ -1,3 +1,26 @@
+//! Council Elections Manager
+//!
+//! # Election Parameters:
+//! We don't currently handle zero periods, zero council term, zero council size and candidacy
+//! limit in any special way. The behaviour in such cases:
+//!
+//! - Setting any period to 0 will mean the election getting stuck in that stage, until force changing
+//! the state.
+//!
+//! - Council Size of 0 - no limit to size of council, all applicants that move beyond
+//! announcing stage would become council members, so effectively the candidacy limit will
+//! be the size of the council, voting and revealing have no impact on final results.
+//!
+//! - If candidacy limit is zero and council size > 0, council_size number of applicants will reach the voting stage.
+//! and become council members, voting will have no impact on final results.
+//!
+//! - If both candidacy limit and council size are zero then all applicant become council members
+//! since no filtering occurs at end of announcing stage.
+//!
+//! We only guard against these edge cases in the [`set_election_parameters`] call.
+//!
+//! [`set_election_parameters`]: struct.Module.html#method.set_election_parameters
+
 use rstd::prelude::*;
 use srml_support::traits::{Currency, ReservableCurrency};
 use srml_support::{decl_event, decl_module, decl_storage, dispatch::Result, ensure};
@@ -113,27 +136,21 @@ decl_storage! {
         // Should we replace all the individual values with a single ElectionParameters type?
         // Having them individually makes it more flexible to add and remove new parameters in future
         // without dealing with migration issues.
-
-        // We don't currently handle zero periods, zero council term, zero council size and candidacy
-        // limit in any special way. The behaviour in such cases:
-        // Setting any period to 0 will mean the election getting stuck in that stage, until force changing
-        // the state.
-        // Council Size of 0 - no limit to size of council, all applicants that move beyond
-        // announcing stage would become council members, so effectively the candidacy limit will
-        // be the size of the council, voting and revealing have no impact on final results.
-        // If candidacy limit is zero and council size > 0, council_size number of applicants will reach the voting stage.
-        // and become council members, voting will have no impact on final results.
-        // If both candidacy limit and council size are zero then all applicant become council members
-        // since no filtering occurs at end of announcing stage.
-        // We only guard against these edge cases in the set_election_parameters() call.
-        AnnouncingPeriod get(announcing_period) config(): T::BlockNumber = T::BlockNumber::from(100);
-        VotingPeriod get(voting_period) config(): T::BlockNumber = T::BlockNumber::from(100);
-        RevealingPeriod get(revealing_period) config(): T::BlockNumber = T::BlockNumber::from(100);
-        CouncilSize get(council_size) config(): u32 = 10;
-        CandidacyLimit get (candidacy_limit) config(): u32 = 20;
-        MinCouncilStake get(min_council_stake) config(): BalanceOf<T> = BalanceOf::<T>::from(100);
-        NewTermDuration get(new_term_duration) config(): T::BlockNumber = T::BlockNumber::from(1000);
-        MinVotingStake get(min_voting_stake) config(): BalanceOf<T> = BalanceOf::<T>::from(10);
+        AnnouncingPeriod get(announcing_period): T::BlockNumber;
+        VotingPeriod get(voting_period): T::BlockNumber;
+        RevealingPeriod get(revealing_period): T::BlockNumber;
+        CouncilSize get(council_size): u32;
+        CandidacyLimit get (candidacy_limit): u32;
+        MinCouncilStake get(min_council_stake): BalanceOf<T>;
+        NewTermDuration get(new_term_duration): T::BlockNumber;
+        MinVotingStake get(min_voting_stake): BalanceOf<T>;
+    }
+    add_extra_genesis {
+        config(election_parameters): ElectionParameters<BalanceOf<T>, T::BlockNumber>;
+        build(|config: &GenesisConfig<T>| {
+            config.election_parameters.ensure_valid().expect("Invalid Election Parameters");
+            Module::<T>::set_verified_election_parameters(config.election_parameters);
+        });
     }
 }
 
@@ -731,6 +748,17 @@ impl<T: Trait> Module<T> {
 
         Ok(())
     }
+
+    fn set_verified_election_parameters(params: ElectionParameters<BalanceOf<T>, T::BlockNumber>) {
+        <AnnouncingPeriod<T>>::put(params.announcing_period);
+        <VotingPeriod<T>>::put(params.voting_period);
+        <RevealingPeriod<T>>::put(params.revealing_period);
+        <MinCouncilStake<T>>::put(params.min_council_stake);
+        <NewTermDuration<T>>::put(params.new_term_duration);
+        CouncilSize::put(params.council_size);
+        CandidacyLimit::put(params.candidacy_limit);
+        <MinVotingStake<T>>::put(params.min_voting_stake);
+    }
 }
 
 decl_module! {
@@ -821,19 +849,16 @@ decl_module! {
             <Stage<T>>::put(ElectionStage::Voting(ends_at));
         }
 
-        fn set_election_parameters(origin, params: ElectionParameters<BalanceOf<T>, T::BlockNumber>) {
+        /// Sets new election parameters. Some combination of parameters that are not desirable, so
+        /// the parameters are checked for validity.
+        /// The call will fail if an election is in progress. If a council is not being elected for some
+        /// reaon after multiple rounds, force_stop_election() can be called to stop elections and followed by
+        /// set_election_parameters().
+        pub fn set_election_parameters(origin, params: ElectionParameters<BalanceOf<T>, T::BlockNumber>) {
             ensure_root(origin)?;
             ensure!(!Self::is_election_running(), MSG_CANNOT_CHANGE_PARAMS_DURING_ELECTION);
             params.ensure_valid()?;
-
-            <AnnouncingPeriod<T>>::put(params.announcing_period);
-            <VotingPeriod<T>>::put(params.voting_period);
-            <RevealingPeriod<T>>::put(params.revealing_period);
-            <MinCouncilStake<T>>::put(params.min_council_stake);
-            <NewTermDuration<T>>::put(params.new_term_duration);
-            CouncilSize::put(params.council_size);
-            CandidacyLimit::put(params.candidacy_limit);
-            <MinVotingStake<T>>::put(params.min_voting_stake);
+            Self::set_verified_election_parameters(params);
         }
 
         fn force_stop_election(origin) {

runtime-modules/governance/src/election_params.rs

@@ -1,4 +1,6 @@
 use codec::{Decode, Encode};
+#[cfg(feature = "std")]
+use serde::{Deserialize, Serialize};
 use sr_primitives::traits::Zero;
 use srml_support::{dispatch::Result, ensure};
 
@@ -8,6 +10,7 @@ pub static MSG_CANDIDACY_LIMIT_WAS_LOWER_THAN_COUNCIL_SIZE: &str =
     "CandidacyWasLessThanCouncilSize";
 
 /// Combined Election parameters, as argument for set_election_parameters
+#[cfg_attr(feature = "std", derive(Serialize, Deserialize))]
 #[derive(Clone, Copy, Encode, Decode, Default, PartialEq, Debug)]
 pub struct ElectionParameters<Balance, BlockNumber> {
     pub announcing_period: BlockNumber,

runtime/src/lib.rs

@@ -396,6 +396,7 @@ impl finality_tracker::Trait for Runtime {
 }
 
 pub use forum;
+pub use governance::election_params::ElectionParameters;
 use governance::{council, election, proposals};
 use membership::members;
 use storage::{data_directory, data_object_storage_registry, data_object_type_registry};