mirror of
https://github.com/pezkuwichain/pezkuwi-subxt.git
synced 2026-04-25 22:17:58 +00:00
Chevdor
a30092ab42
* Add markdown linting - add linter default rules - adapt rules to current code - fix the code for linting to pass - add CI check fix #1243 * Fix markdown for Substrate * Fix tooling install * Fix workflow * Add documentation * Remove trailing spaces * Update .github/.markdownlint.yaml Co-authored-by: Oliver Tale-Yazdi <oliver.tale-yazdi@parity.io> * Fix mangled markdown/lists * Fix captalization issues on known words
82 lines
3.9 KiB
Markdown
82 lines
3.9 KiB
Markdown
# Session Pallet
|
|
|
|
The Session module allows validators to manage their session keys, provides a function for changing the session length,
|
|
and handles session rotation.
|
|
|
|
- [`session::Trait`](https://docs.rs/pallet-session/latest/pallet_session/trait.Config.html)
|
|
- [`Call`](https://docs.rs/pallet-session/latest/pallet_session/enum.Call.html)
|
|
- [`Pallet`](https://docs.rs/pallet-session/latest/pallet_session/struct.Pallet.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. The block where a session is 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:** 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 `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.
|
|
- **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:** 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 `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.
|
|
|
|
### Goals
|
|
|
|
The Session pallet is designed to make the following possible:
|
|
|
|
- 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_keys` - Set a validator's session keys for upcoming sessions.
|
|
|
|
### Public Functions
|
|
|
|
- `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 FRAME
|
|
|
|
The [Staking pallet](https://docs.rs/pallet-staking/latest/pallet_staking/) uses the Session pallet to get the validator
|
|
set.
|
|
|
|
```rust
|
|
use pallet_session as session;
|
|
|
|
fn validators<T: pallet_session::Config>() -> Vec<<T as pallet_session::Config>::ValidatorId> {
|
|
<pallet_session::Pallet<T>>::validators()
|
|
}
|
|
```
|
|
|
|
## Related Pallets
|
|
|
|
- [Staking](https://docs.rs/pallet-staking/latest/pallet_staking/)
|
|
|
|
License: Apache-2.0
|