The Session module allows validators to manage their session keys, provides a function for changing the session length, and handles session rotation.
- 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_lengthduring 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_keyfor use in the next session. It is stored in
NextKeyFor, a mapping between the caller's
AccountIDand the session key provided.
set_keyallows 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
NextKeyFormay 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
set_key. If it was then we call
set_authorityfrom the Consensus module 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
AuthorityStorageVecmapping, 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
NextSessionLengthwas 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
- 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
on_finalizemethod. It may be called by either an origin or internally from another runtime module at the end of each block.
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.
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.
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.
The Staking module uses the Session module to get the validator set.
use srml_session as session; let validators = <session::Module<T>>::validators();
Current index of the session.
Timestamp when current session started.
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).
Current length of the session.
The current set of validators.
Events for this module.
A session has changed.