mirror of
https://github.com/pezkuwichain/pezkuwi-subxt.git
synced 2026-04-26 16:57:58 +00:00
Documentation for the Session Module (#2283)
* WIP * fix: Redo session module docs incorporating approach used by Joe in democracy * remove unncessary quotes * docs: Add example from srml to session module docs * replace asterix with dash * session start * make example compile * index html updates * Update lib.rs
This commit is contained in:
Luke Schoen
@@ -14,8 +14,104 @@
|
||||
// You should have received a copy of the GNU General Public License
|
||||
// along with Substrate. If not, see <http://www.gnu.org/licenses/>.
|
||||
|
||||
//! Session manager: is told the validators and allows them to manage their session keys for the
|
||||
//! consensus module.
|
||||
//! # Session Module
|
||||
//!
|
||||
//! The Session module allows validators to manage their session keys, provides a function for changing
|
||||
//! the session length, and handles session rotation.
|
||||
//!
|
||||
//! - [`session::Trait`](./trait.Trait.html)
|
||||
//! - [`Call`](./enum.Call.html)
|
||||
//! - [`Module`](./struct.Module.html)
|
||||
//!
|
||||
//! ## Overview
|
||||
//!
|
||||
//! ### Terminology
|
||||
//! <!-- Original author of paragraph: @gavofyork -->
|
||||
//!
|
||||
//! - **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 and set with `set_length`
|
||||
//! during a session for use in subsequent sessions.
|
||||
//! - **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.
|
||||
//! - **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 `AccountID` and the session
|
||||
//! key provided. `set_key` allows users to set their session key prior to becoming a 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
|
||||
//! 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](../srml_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 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.
|
||||
//!
|
||||
//! ### Goals
|
||||
//!
|
||||
//! The Session module in Substrate is designed to make the following possible:
|
||||
//!
|
||||
//! - Set session keys of the validator set for the next session.
|
||||
//! - Set the length of a session.
|
||||
//! - 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.
|
||||
//!
|
||||
//! ### 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.
|
||||
//!
|
||||
//! ## Usage
|
||||
//!
|
||||
//! ### Example from the SRML
|
||||
//!
|
||||
//! The [Staking module](../srml_staking/index.html) uses the Session module to get the validator set.
|
||||
//!
|
||||
//! ```
|
||||
//! use srml_session as session;
|
||||
//! # fn not_executed<T: session::Trait>() {
|
||||
//!
|
||||
//! let validators = <session::Module<T>>::validators();
|
||||
//! # }
|
||||
//! # fn main(){}
|
||||
//! ```
|
||||
//!
|
||||
//! ## Related Modules
|
||||
//!
|
||||
//! - [Consensus](../srml_consensus/index.html)
|
||||
//! - [Staking](../srml_staking/index.html)
|
||||
//! - [Timestamp](../srml_timestamp/index.html)
|
||||
|
||||
#![cfg_attr(not(feature = "std"), no_std)]
|
||||
|
||||
@@ -51,8 +147,13 @@ macro_rules! impl_session_change {
|
||||
for_each_tuple!(impl_session_change);
|
||||
|
||||
pub trait Trait: timestamp::Trait + consensus::Trait {
|
||||
/// Create a session key from an account key.
|
||||
type ConvertAccountIdToSessionKey: Convert<Self::AccountId, Option<Self::SessionKey>>;
|
||||
|
||||
/// Handler when a session changes.
|
||||
type OnSessionChange: OnSessionChange<Self::Moment>;
|
||||
|
||||
/// The overarching event type.
|
||||
type Event: From<Event<Self>> + Into<<Self as system::Trait>::Event>;
|
||||
}
|
||||
|
||||
@@ -60,8 +161,8 @@ decl_module! {
|
||||
pub struct Module<T: Trait> for enum Call where origin: T::Origin {
|
||||
fn deposit_event<T>() = default;
|
||||
|
||||
/// Sets the session key of `_validator` to `_key`. This doesn't take effect until the next
|
||||
/// session.
|
||||
/// Sets the session key of a validator (function caller) to `key`.
|
||||
/// This doesn't take effect until the next session.
|
||||
fn set_key(origin, key: T::SessionKey) {
|
||||
let who = ensure_signed(origin)?;
|
||||
// set new value for next session
|
||||
@@ -78,6 +179,8 @@ decl_module! {
|
||||
Self::apply_force_new_session(apply_rewards)
|
||||
}
|
||||
|
||||
/// Called when a block is finalized. Will rotate session if it is the last
|
||||
/// block of the current session.
|
||||
fn on_finalize(n: T::BlockNumber) {
|
||||
Self::check_rotate_session(n);
|
||||
}
|
||||
@@ -103,8 +206,9 @@ decl_storage! {
|
||||
/// Timestamp when current session started.
|
||||
pub CurrentStart get(current_start) build(|_| T::Moment::zero()): T::Moment;
|
||||
|
||||
/// New session is being forced if this entry exists; in which case, the boolean value is whether
|
||||
/// the new session should be considered a normal rotation (rewardable) or exceptional (slashable).
|
||||
/// New session is being forced if this entry exists; in which case, the boolean value is true if
|
||||
/// the new session should be considered a normal rotation (rewardable) and false if the new session
|
||||
/// should be considered exceptional (slashable).
|
||||
pub ForcingNewSession get(forcing_new_session): Option<bool>;
|
||||
/// Block at which the session length last changed.
|
||||
LastLengthChange: Option<T::BlockNumber>;
|
||||
@@ -198,7 +302,7 @@ impl<T: Trait> Module<T> {
|
||||
};
|
||||
}
|
||||
|
||||
/// Get the time that should have elapsed over a session if everything was working perfectly.
|
||||
/// Get the time that should elapse over a session if everything is working perfectly.
|
||||
pub fn ideal_session_duration() -> T::Moment {
|
||||
let block_period: T::Moment = <timestamp::Module<T>>::minimum_period();
|
||||
let session_length: T::BlockNumber = Self::length();
|
||||
|
||||
Reference in New Issue
Block a user