# 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::Validators::<T>::get()
}
```

## Related Pallets

- [Staking](https://docs.rs/pallet-staking/latest/pallet_staking/)

License: Apache-2.0


## Release

Polkadot SDK stable2409