From e51fac8db7e04ca31d58a99cbacc148fedf30d20 Mon Sep 17 00:00:00 2001 From: Joshy Orndorff Date: Thu, 9 Jan 2020 09:31:24 -0500 Subject: [PATCH 1/8] Simply remove references to frame_consensus --- frame/aura/src/lib.rs | 2 -- frame/session/src/lib.rs | 1 - frame/sudo/src/lib.rs | 1 - 3 files changed, 4 deletions(-) diff --git a/frame/aura/src/lib.rs b/frame/aura/src/lib.rs index 1a711f314abcd..e2aafde9efe6e 100644 --- a/frame/aura/src/lib.rs +++ b/frame/aura/src/lib.rs @@ -33,8 +33,6 @@ //! //! - [Timestamp](../pallet_timestamp/index.html): The Timestamp module is used in Aura to track //! consensus rounds (via `slots`). -//! - [Consensus](../frame_consensus/index.html): The Consensus module does not relate directly to Aura, -//! but serves to manage offline reporting by implementing `ProvideInherent` in a similar way. //! //! ## References //! diff --git a/frame/session/src/lib.rs b/frame/session/src/lib.rs index 2c5668f6fa9f2..b4fd69041ad6e 100644 --- a/frame/session/src/lib.rs +++ b/frame/session/src/lib.rs @@ -113,7 +113,6 @@ //! //! ## Related Modules //! -//! - [Consensus](../frame_consensus/index.html) //! - [Staking](../pallet_staking/index.html) //! - [Timestamp](../pallet_timestamp/index.html) diff --git a/frame/sudo/src/lib.rs b/frame/sudo/src/lib.rs index e49596b4bdb9b..ea436e2629b49 100644 --- a/frame/sudo/src/lib.rs +++ b/frame/sudo/src/lib.rs @@ -77,7 +77,6 @@ //! //! ## Related Modules //! -//! * [Consensus](../frame_consensus/index.html) //! * [Democracy](../pallet_democracy/index.html) //! //! [`Call`]: ./enum.Call.html From 9dc7b83c7e5edf6190e802fbf8621410dbbf88aa Mon Sep 17 00:00:00 2001 From: Joshy Orndorff Date: Fri, 10 Jan 2020 14:55:12 -0500 Subject: [PATCH 2/8] More thorough re-write --- frame/session/src/lib.rs | 76 ++++++++++++++++------------------------ 1 file changed, 30 insertions(+), 46 deletions(-) diff --git a/frame/session/src/lib.rs b/frame/session/src/lib.rs index b4fd69041ad6e..534c1eda73114 100644 --- a/frame/session/src/lib.rs +++ b/frame/session/src/lib.rs @@ -30,83 +30,68 @@ //! //! - **Session:** A session is a period of time that has a constant set of validators. Validators can only join //! or exit the validator set at a session change. It is measured in block numbers. The block where a session is -//! ended is determined by the `ShouldSessionEnd` trait. When the session is ending, a new validator set +//! ended is determined by the `ShouldEndSession` trait. When the session is ending, a new validator set //! can be chosen by `OnSessionEnding` implementations. //! - **Session key:** A session key is actually several keys kept together that provide the various signing //! functions required by network authorities/validators in pursuit of their duties. //! - **Validator ID:** Every account has an associated validator ID. For some simple staking systems, this //! may just be the same as the account ID. For staking systems using a stash/controller model, //! the validator ID would be the stash account ID of the controller. -//! - **Session key configuration process:** A session key is set using `set_key` for use in the -//! next session. It is stored in `NextKeyFor`, a mapping between the caller's `ValidatorId` and the session -//! keys provided. `set_key` allows users to set their session key prior to being selected as validator. +//! - **Session key configuration process:** Session keys are set using `set_keys` for use not in +//! the next session, but the session after next. They are stored in `NextKeys`, a mapping between +//! the caller's `ValidatorId` and the session keys provided. `set_keys` allows users to set their +//! session key prior to being selected as validator. //! It is a public call since it uses `ensure_signed`, which checks that the origin is a signed account. -//! As such, the account ID of the origin stored in in `NextKeyFor` may not necessarily be associated with +//! As such, the account ID of the origin stored in `NextKeys` may not necessarily be associated with //! a block author or a validator. The session keys of accounts are removed once their account balance is zero. -//! - **Validator set session key configuration process:** Each session we iterate through the current -//! set of validator account IDs to check if a session key was created for it in the previous session -//! using `set_key`. If it was then we call `set_authority` from the [Consensus module](../frame_consensus/index.html) -//! and pass it a set of session keys (each associated with an account ID) as the session keys for the new -//! validator set. Lastly, if the session key of the current authority does not match any session keys stored under -//! its validator index in the `AuthorityStorageVec` mapping, then we update the mapping with its session -//! key and update the saved list of original authorities if necessary -//! (see https://github.com/paritytech/substrate/issues/1290). Note: Authorities are stored in the Consensus module. -//! They are represented by a validator account ID index from the Session module and allocated with a session -//! key for the length of the session. -//! - **Session length change process:** At the start of the next session we allocate a session index and record the -//! timestamp when the session started. If a `NextSessionLength` was recorded in the previous session, we record -//! it as the new session length. Additionally, if the new session length differs from the length of the -//! next session then we record a `LastLengthChange`. +//! - **Session length:** This pallet does not assume anything about the length of each session. +//! Rather, it relies on an implementation of `ShouldEndSession` to dictate a new session's start. +//! This pallet provides the `PeriodicSessions` struct for simple periodic sessions. //! - **Session rotation configuration:** Configure as either a 'normal' (rewardable session where rewards are //! applied) or 'exceptional' (slashable) session rotation. -//! - **Session rotation process:** The session is changed at the end of the final block of the current session -//! using the `on_finalize` method. It may be called by either an origin or internally from another runtime -//! module at the end of each block. +//! - **Session rotation process:** At the beginning of each block, the `on_initialize` function +//! queries the provided implementation of `ShouldEndSession`. If the session is to end the newly +//! activated validator IDs and session keys are taken from storage and passed to the +//! `SessionHandler`. The validator set supplied by `OnSessionEnding` and the corresponding session +//! keys, which may have been registered via `set_keys` during the previous session, are written ////! to storage where they will wait one session before being passed to the `SessionHandler` +//! themselves. //! //! ### Goals //! -//! The Session module in Substrate is designed to make the following possible: +//! The Session pallet is designed to make the following possible: //! -//! - Set session keys of the validator set for the next session. -//! - Set the length of a session. +//! - Set session keys of the validator set for upcoming sessions. +//! - Control the length of sessions. //! - Configure and switch between either normal or exceptional session rotations. //! //! ## Interface //! //! ### Dispatchable Functions //! -//! - `set_key` - Set a validator's session key for the next session. -//! - `set_length` - Set a new session length to be applied upon the next session change. -//! - `force_new_session` - Force a new session that should be considered either a normal (rewardable) -//! or exceptional rotation. -//! - `on_finalize` - Called when a block is finalized. Will rotate session if it is the last -//! block of the current session. +//! - `set_keys` - Set a validator's session keys for upcoming sessions. +//! - `on_initialize` - Called when a block is initialized. Will rotate session if it is the first +//! block of the new session. //! //! ### Public Functions //! -//! - `validator_count` - Get the current number of validators. -//! - `last_length_change` - Get the block number when the session length last changed. -//! - `apply_force_new_session` - Force a new session. Can be called by other runtime modules. -//! - `set_validators` - Set the current set of validators. Can only be called by the Staking module. -//! - `check_rotate_session` - Rotate the session and apply rewards if necessary. Called after the Staking -//! module updates the authorities to the new validator set. -//! - `rotate_session` - Change to the next session. Register the new authority set. Update session keys. -//! Enact session length change if applicable. -//! - `ideal_session_duration` - Get the time of an ideal session. -//! - `blocks_remaining` - Get the number of blocks remaining in the current session, -//! excluding the current block. +//! - `rotate_session` - Change to the next session. Register the new authority set. Queue changes +//! for next session rotation. +//! - `disable_index` - Disable a validator by index. +//! - `disable` - Disable a validator by Validator ID //! //! ## Usage //! //! ### Example from the SRML //! -//! The [Staking module](../pallet_staking/index.html) uses the Session module to get the validator set. +//! The [Staking pallet](../pallet_staking/index.html) uses the Session pallet to get the validator set. //! //! ``` //! use pallet_session as session; //! # fn not_executed() { //! -//! let validators = >::validators(); +//! fn validators() -> Vec<::AccountId> { +//! >::validators() +//!} //! # } //! # fn main(){} //! ``` @@ -114,7 +99,6 @@ //! ## Related Modules //! //! - [Staking](../pallet_staking/index.html) -//! - [Timestamp](../pallet_timestamp/index.html) #![cfg_attr(not(feature = "std"), no_std)] @@ -485,7 +469,7 @@ decl_module! { fn deposit_event() = default; - /// Sets the session key(s) of the function caller to `key`. + /// Sets the session key(s) of the function caller to `keys`. /// Allows an account to set its session key prior to becoming a validator. /// This doesn't take effect until the next session. /// From 78020190cb26c2df13722dbe4c87bcbac2ef3fe0 Mon Sep 17 00:00:00 2001 From: Joshy Orndorff Date: Mon, 13 Jan 2020 10:09:51 -0500 Subject: [PATCH 3/8] Update frame/session/src/lib.rs Co-Authored-By: thiolliere --- frame/session/src/lib.rs | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/frame/session/src/lib.rs b/frame/session/src/lib.rs index 534c1eda73114..e0c8d5917a71e 100644 --- a/frame/session/src/lib.rs +++ b/frame/session/src/lib.rs @@ -53,7 +53,8 @@ //! queries the provided implementation of `ShouldEndSession`. If the session is to end the newly //! activated validator IDs and session keys are taken from storage and passed to the //! `SessionHandler`. The validator set supplied by `OnSessionEnding` and the corresponding session -//! keys, which may have been registered via `set_keys` during the previous session, are written ////! to storage where they will wait one session before being passed to the `SessionHandler` +//! keys, which may have been registered via `set_keys` during the previous session, are written +//! to storage where they will wait one session before being passed to the `SessionHandler` //! themselves. //! //! ### Goals From 173464f56a7ed5a3f281bf94775e697b7d28bebb Mon Sep 17 00:00:00 2001 From: Joshy Orndorff Date: Mon, 13 Jan 2020 12:33:16 -0500 Subject: [PATCH 4/8] on_initialize is not dispatchable --- frame/session/src/lib.rs | 2 -- 1 file changed, 2 deletions(-) diff --git a/frame/session/src/lib.rs b/frame/session/src/lib.rs index 534c1eda73114..ef21db20b7356 100644 --- a/frame/session/src/lib.rs +++ b/frame/session/src/lib.rs @@ -69,8 +69,6 @@ //! ### Dispatchable Functions //! //! - `set_keys` - Set a validator's session keys for upcoming sessions. -//! - `on_initialize` - Called when a block is initialized. Will rotate session if it is the first -//! block of the new session. //! //! ### Public Functions //! From a9730d067d0c0bf24fcdc463e6b3e94fb880c673 Mon Sep 17 00:00:00 2001 From: Joshy Orndorff Date: Wed, 22 Jan 2020 17:42:16 -0500 Subject: [PATCH 5/8] Attempt to fix test. --- frame/session/src/lib.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/frame/session/src/lib.rs b/frame/session/src/lib.rs index 9cada9a028147..3510263279ebd 100644 --- a/frame/session/src/lib.rs +++ b/frame/session/src/lib.rs @@ -89,7 +89,7 @@ //! # fn not_executed() { //! //! fn validators() -> Vec<::AccountId> { -//! >::validators() +//! ::validators() //!} //! # } //! # fn main(){} From 6a19cf6aebe7f802c31b186901b2acb48bc5a117 Mon Sep 17 00:00:00 2001 From: Joshy Orndorff Date: Wed, 22 Jan 2020 17:55:48 -0500 Subject: [PATCH 6/8] Actually fix test. --- frame/session/src/lib.rs | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/frame/session/src/lib.rs b/frame/session/src/lib.rs index 3510263279ebd..3950e2dcc514b 100644 --- a/frame/session/src/lib.rs +++ b/frame/session/src/lib.rs @@ -86,12 +86,10 @@ //! //! ``` //! use pallet_session as session; -//! # fn not_executed() { //! -//! fn validators() -> Vec<::AccountId> { -//! ::validators() -//!} -//! # } +//! fn validators() -> Vec<::AccountId> { +//! >::validators() +//! } //! # fn main(){} //! ``` //! From 9a12d7ca68ae6d1c4f7de371f8863fcd6342b8fa Mon Sep 17 00:00:00 2001 From: Joshy Orndorff Date: Fri, 24 Jan 2020 13:22:50 -0500 Subject: [PATCH 7/8] Actually ran passing test. --- frame/session/src/lib.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/frame/session/src/lib.rs b/frame/session/src/lib.rs index 3950e2dcc514b..353c9c4648053 100644 --- a/frame/session/src/lib.rs +++ b/frame/session/src/lib.rs @@ -87,7 +87,7 @@ //! ``` //! use pallet_session as session; //! -//! fn validators() -> Vec<::AccountId> { +//! fn validators() -> Vec<::ValidatorId> { //! >::validators() //! } //! # fn main(){} From 7eb9e8a2bc78ca73eacb0be6c835e211d9cfe081 Mon Sep 17 00:00:00 2001 From: Joshy Orndorff Date: Mon, 27 Jan 2020 10:36:30 -0500 Subject: [PATCH 8/8] Update frame/session/src/lib.rs Co-Authored-By: thiolliere --- frame/session/src/lib.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/frame/session/src/lib.rs b/frame/session/src/lib.rs index 353c9c4648053..600a325cb0127 100644 --- a/frame/session/src/lib.rs +++ b/frame/session/src/lib.rs @@ -52,7 +52,7 @@ //! - **Session rotation process:** At the beginning of each block, the `on_initialize` function //! queries the provided implementation of `ShouldEndSession`. If the session is to end the newly //! activated validator IDs and session keys are taken from storage and passed to the -//! `SessionHandler`. The validator set supplied by `OnSessionEnding` and the corresponding session +//! `SessionHandler`. The validator set supplied by `SessionManager::new_session` and the corresponding session //! keys, which may have been registered via `set_keys` during the previous session, are written //! to storage where they will wait one session before being passed to the `SessionHandler` //! themselves.