// This file is part of Substrate.

// Copyright (C) Parity Technologies (UK) Ltd.

// SPDX-License-Identifier: Apache-2.0

// Licensed under the Apache License, Version 2.0 (the "License");

// you may not use this file except in compliance with the License.

// You may obtain a copy of the License at

//

// 	http://www.apache.org/licenses/LICENSE-2.0

//

// Unless required by applicable law or agreed to in writing, software

// distributed under the License is distributed on an "AS IS" BASIS,

// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

// See the License for the specific language governing permissions and

// limitations under the License.

//! # Session Pallet

//!

//! The Session pallet allows validators to manage their session keys, provides a function for

//! changing the session length, and handles session rotation.

//!

//! - [`Config`]

//! - [`Call`]

//! - [`Pallet`]

//!

//! ## 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](../pallet_staking/index.html) uses the Session pallet to get the validator

//! set.

//!

//! ```

//! use pallet_session as session;

//!

//! fn validators<T: pallet_session::Config>() -> Vec<<T as pallet_session::Config>::ValidatorId> {

//! 	pallet_session::Validators::<T>::get()

//! }

//! # fn main(){}

//! ```

//!

//! ## Related Pallets

//!

//! - [Staking](../pallet_staking/index.html)

#![cfg_attr(not(feature = "std"), no_std)]

#[cfg(feature = "historical")]

pub mod historical;

pub mod migrations;

#[cfg(test)]

mod mock;

#[cfg(test)]

mod tests;

pub mod weights;

extern crate alloc;

use alloc::{boxed::Box, vec::Vec};

use codec::{Decode, MaxEncodedLen};

use core::{

	marker::PhantomData,

	ops::{Rem, Sub},

};

use frame_support::{

	dispatch::DispatchResult,

	ensure,

	traits::{

		EstimateNextNewSession, EstimateNextSessionRotation, FindAuthor, Get, OneSessionHandler,

		ValidatorRegistration, ValidatorSet,

	},

	weights::Weight,

	Parameter,

};

use frame_system::pallet_prelude::BlockNumberFor;

use sp_runtime::{

	traits::{AtLeast32BitUnsigned, Convert, Member, One, OpaqueKeys, Zero},

	ConsensusEngineId, DispatchError, KeyTypeId, Permill, RuntimeAppPublic,

};

use sp_staking::SessionIndex;

pub use pallet::*;

pub use weights::WeightInfo;

/// Decides whether the session should be ended.

pub trait ShouldEndSession<BlockNumber> {

	/// Return `true` if the session should be ended.

	fn should_end_session(now: BlockNumber) -> bool;

}

/// Ends the session after a fixed period of blocks.

///

/// The first session will have length of `Offset`, and

/// the following sessions will have length of `Period`.

/// This may prove nonsensical if `Offset` >= `Period`.

pub struct PeriodicSessions<Period, Offset>(PhantomData<(Period, Offset)>);

impl<

		BlockNumber: Rem<Output = BlockNumber> + Sub<Output = BlockNumber> + Zero + PartialOrd,

		Period: Get<BlockNumber>,

		Offset: Get<BlockNumber>,

	> ShouldEndSession<BlockNumber> for PeriodicSessions<Period, Offset>

{

}

impl<

		BlockNumber: AtLeast32BitUnsigned + Clone,

		Period: Get<BlockNumber>,

		Offset: Get<BlockNumber>,

	> EstimateNextSessionRotation<BlockNumber> for PeriodicSessions<Period, Offset>

{

		// NOTE: we add one since we assume that the current block has already elapsed,

		// i.e. when evaluating the last block in the session the progress should be 100%

		// (0% is never returned).

		} else {

		};

		// Weight note: `estimate_current_session_progress` has no storage reads and trivial

		// computational overhead. There should be no risk to the chain having this weight value be

		// zero for now. However, this value of zero was not properly calculated, and so it would be

		// reasonable to come back here and properly calculate the weight of this function.

			} else {

				// this branch happens when the session is already rotated or will rotate in this

				// block (depending on being called before or after `session::on_initialize`). Here,

				// we assume the latter, namely that this is called after `session::on_initialize`,

				// and thus we add period to it as well.

			}

		} else {

		};

		// Weight note: `estimate_next_session_rotation` has no storage reads and trivial

		// computational overhead. There should be no risk to the chain having this weight value be

		// zero for now. However, this value of zero was not properly calculated, and so it would be

		// reasonable to come back here and properly calculate the weight of this function.

}

/// A trait for managing creation of new validator set.

pub trait SessionManager<ValidatorId> {

	/// Plan a new session, and optionally provide the new validator set.

	///

	/// Even if the validator-set is the same as before, if any underlying economic conditions have

	/// changed (i.e. stake-weights), the new validator set must be returned. This is necessary for

	/// consensus engines making use of the session pallet to issue a validator-set change so

	/// misbehavior can be provably associated with the new economic conditions as opposed to the

	/// old. The returned validator set, if any, will not be applied until `new_index`. `new_index`

	/// is strictly greater than from previous call.

	///

	/// The first session start at index 0.

	///

	/// `new_session(session)` is guaranteed to be called before `end_session(session-1)`. In other

	/// words, a new session must always be planned before an ongoing one can be finished.

	fn new_session(new_index: SessionIndex) -> Option<Vec<ValidatorId>>;

	/// Same as `new_session`, but it this should only be called at genesis.

	///

	/// The session manager might decide to treat this in a different way. Default impl is simply

	/// using [`new_session`](Self::new_session).

	/// End the session.

	///

	/// Because the session pallet can queue validator set the ending session can be lower than the

	/// last new session index.

	fn end_session(end_index: SessionIndex);

	/// Start an already planned session.

	///

	/// The session start to be used for validation.

	fn start_session(start_index: SessionIndex);

}

impl<A> SessionManager<A> for () {

}

/// Handler for session life cycle events.

pub trait SessionHandler<ValidatorId> {

	/// All the key type ids this session handler can process.

	///

	/// The order must be the same as it expects them in

	/// [`on_new_session`](Self::on_new_session<Ks>) and

	/// [`on_genesis_session`](Self::on_genesis_session<Ks>).

	const KEY_TYPE_IDS: &'static [KeyTypeId];

	/// The given validator set will be used for the genesis session.

	/// It is guaranteed that the given validator set will also be used

	/// for the second session, therefore the first call to `on_new_session`

	/// should provide the same validator set.

	fn on_genesis_session<Ks: OpaqueKeys>(validators: &[(ValidatorId, Ks)]);

	/// Session set has changed; act appropriately. Note that this can be called

	/// before initialization of your pallet.

	///

	/// `changed` is true whenever any of the session keys or underlying economic

	/// identities or weightings behind `validators` keys has changed. `queued_validators`

	/// could change without `validators` changing. Example of possible sequent calls:

	///     Session N: on_new_session(false, unchanged_validators, unchanged_queued_validators)

	///     Session N + 1: on_new_session(false, unchanged_validators, new_queued_validators)

	/// 	Session N + 2: on_new_session(true, new_queued_validators, new_queued_validators)

	fn on_new_session<Ks: OpaqueKeys>(

		changed: bool,

		validators: &[(ValidatorId, Ks)],

		queued_validators: &[(ValidatorId, Ks)],

	);

	/// A notification for end of the session.

	///

	/// Note it is triggered before any [`SessionManager::end_session`] handlers,

	/// so we can still affect the validator set.

	/// A validator got disabled. Act accordingly until a new session begins.

	fn on_disabled(validator_index: u32);

}

#[impl_trait_for_tuples::impl_for_tuples(1, 30)]

#[tuple_types_custom_trait_bound(OneSessionHandler<AId>)]

impl<AId> SessionHandler<AId> for Tuple {

	for_tuples!(

		const KEY_TYPE_IDS: &'static [KeyTypeId] = &[ #( <Tuple::Key as RuntimeAppPublic>::ID ),* ];

	);

}

/// `SessionHandler` for tests that use `UintAuthorityId` as `Keys`.

pub struct TestSessionHandler;

impl<AId> SessionHandler<AId> for TestSessionHandler {

	const KEY_TYPE_IDS: &'static [KeyTypeId] = &[sp_runtime::key_types::DUMMY];

}

pub mod pallet {

	use super::*;

	use frame_support::pallet_prelude::*;

	use frame_system::pallet_prelude::*;

	/// The in-code storage version.

	const STORAGE_VERSION: StorageVersion = StorageVersion::new(0);

	#[pallet::storage_version(STORAGE_VERSION)]

	pub struct Pallet<T>(_);

	#[pallet::config]

	pub trait Config: frame_system::Config {

		/// The overarching event type.

		type RuntimeEvent: From<Event> + IsType<<Self as frame_system::Config>::RuntimeEvent>;

		/// A stable ID for a validator.

		type ValidatorId: Member

			+ Parameter

			+ MaybeSerializeDeserialize

			+ MaxEncodedLen

			+ TryFrom<Self::AccountId>;

		/// A conversion from account ID to validator ID.

		///

		/// Its cost must be at most one storage read.

		type ValidatorIdOf: Convert<Self::AccountId, Option<Self::ValidatorId>>;

		/// Indicator for when to end the session.

		type ShouldEndSession: ShouldEndSession<BlockNumberFor<Self>>;

		/// Something that can predict the next session rotation. This should typically come from

		/// the same logical unit that provides [`ShouldEndSession`], yet, it gives a best effort

		/// estimate. It is helpful to implement [`EstimateNextNewSession`].

		type NextSessionRotation: EstimateNextSessionRotation<BlockNumberFor<Self>>;

		/// Handler for managing new session.

		type SessionManager: SessionManager<Self::ValidatorId>;

		/// Handler when a session has changed.

		type SessionHandler: SessionHandler<Self::ValidatorId>;

		/// The keys.

		type Keys: OpaqueKeys + Member + Parameter + MaybeSerializeDeserialize;

		/// Weight information for extrinsics in this pallet.

		type WeightInfo: WeightInfo;

	}

	#[pallet::genesis_config]

	#[derive(frame_support::DefaultNoBound)]

	pub struct GenesisConfig<T: Config> {

		/// Initial list of validator at genesis representing by their `(AccountId, ValidatorId,

		/// Keys)`. These keys will be considered authorities for the first two sessions and they

		/// will be valid at least until session 2

		pub keys: Vec<(T::AccountId, T::ValidatorId, T::Keys)>,

		/// List of (AccountId, ValidatorId, Keys) that will be registered at genesis, but not as

		/// active validators. These keys are set, together with `keys`, as authority candidates

		/// for future sessions (enactable from session 2 onwards)

		pub non_authority_keys: Vec<(T::AccountId, T::ValidatorId, T::Keys)>,

	}

	impl<T: Config> BuildGenesisConfig for GenesisConfig<T> {

			{

			}

	}

	/// The current set of validators.

	pub type Validators<T: Config> = StorageValue<_, Vec<T::ValidatorId>, ValueQuery>;

	/// Current index of the session.

	pub type CurrentIndex<T> = StorageValue<_, SessionIndex, ValueQuery>;

	/// True if the underlying economic identities or weighting behind the validators

	/// has changed in the queued validator set.

	pub type QueuedChanged<T> = StorageValue<_, bool, ValueQuery>;

	/// The queued keys for the next session. When the next session begins, these keys

	/// will be used to determine the validator's session keys.

	pub type QueuedKeys<T: Config> = StorageValue<_, Vec<(T::ValidatorId, T::Keys)>, ValueQuery>;

	/// Indices of disabled validators.

	///

	/// The vec is always kept sorted so that we can find whether a given validator is

	/// disabled using binary search. It gets cleared when `on_session_ending` returns

	/// a new set of identities.

	pub type DisabledValidators<T> = StorageValue<_, Vec<u32>, ValueQuery>;

	/// The next session keys for a validator.

	pub type NextKeys<T: Config> =

		StorageMap<_, Twox64Concat, T::ValidatorId, T::Keys, OptionQuery>;

	/// The owner of a key. The key is the `KeyTypeId` + the encoded key.

	pub type KeyOwner<T: Config> =

		StorageMap<_, Twox64Concat, (KeyTypeId, Vec<u8>), T::ValidatorId, OptionQuery>;

	pub enum Event {

		/// block number as the type might suggest.

	}

	/// Error for the session pallet.

	pub enum Error<T> {

	}

	impl<T: Config> Hooks<BlockNumberFor<T>> for Pallet<T> {

		/// Called when a block is initialized. Will rotate session if it is the last

		/// block of the current session.

			} else {

				// NOTE: the non-database part of the weight for `should_end_session(n)` is

				// included as weight for empty block, the database part is expected to be in

				// cache.

			}

	}

	impl<T: Config> Pallet<T> {

		/// 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.

		///

		/// The dispatch origin of this function must be signed.

		///

		/// ## Complexity

		/// - `O(1)`. Actual cost depends on the number of length of `T::Keys::key_ids()` which is

		///   fixed.

		#[pallet::call_index(0)]

		#[pallet::weight(T::WeightInfo::set_keys())]

		}

		/// Removes any session key(s) of the function caller.

		///

		/// This doesn't take effect until the next session.

		///

		/// The dispatch origin of this function must be Signed and the account must be either be

		/// convertible to a validator ID using the chain's typical addressing system (this usually

		/// means being a controller account) or directly convertible into a validator ID (which

		/// usually means being a stash account).

		///

		/// ## Complexity

		/// - `O(1)` in number of key types. Actual cost depends on the number of length of

		///   `T::Keys::key_ids()` which is fixed.

		#[pallet::call_index(1)]

		#[pallet::weight(T::WeightInfo::purge_keys())]

		}

	}

}

impl<T: Config> Pallet<T> {

	/// Public function to access the current set of validators.

	/// Public function to access the current session index.

	/// Public function to access the queued keys.

	/// Public function to access the disabled validators.

	/// Move on to next session. Register new validator set and session keys. Changes to the

	/// validator set have a session of delay to take effect. This allows for equivocation

	/// punishment after a fork.

		// Increment session index.

				// NOTE: as per the documentation on `OnSessionEnding`, we consider

				// the validator set as having changed even if the validators are the

				// same as before, as underlying economic conditions may have changed.

			} else {

			};

		// Queue next session keys.

				// since a new validator set always leads to `changed` starting

				// as true, we can ensure that `now_session_keys` and `next_validators`

				// have the same length. this function is called once per iteration.

	/// Disable the validator of index `i`, returns `false` if the validator was already disabled.

	/// Disable the validator identified by `c`. (If using with the staking pallet,

	/// this would be their *stash* account.)

	///

	/// Returns `false` either if the validator could not be found or it was already

	/// disabled.

	/// Upgrade the key type from some old type to a new type. Supports adding

	/// and removing key types.

	///

	/// This function should be used with extreme care and only during an

	/// `on_runtime_upgrade` block. Misuse of this function can put your blockchain

	/// into an unrecoverable state.

	///

	/// Care should be taken that the raw versions of the

	/// added keys are unique for every `ValidatorId, KeyTypeId` combination.

	/// This is an invariant that the session pallet typically maintains internally.

	///

	/// As the actual values of the keys are typically not known at runtime upgrade,

	/// it's recommended to initialize the keys to a (unique) dummy value with the expectation

	/// that all validators should invoke `set_keys` before those keys are actually

	/// required.

			// Clear all key ownership relations. Typically the overlap should

			// stay the same, but no guarantees by the upgrade function.

			// And now set the new ones.

	/// Perform the set_key operation, checking for duplicates. Does not set `Changed`.

	///

	/// This ensures that the reference counter in system is incremented appropriately and as such

	/// must accept an account ID, rather than a validator ID.

	/// Perform the set_key operation, checking for duplicates. Does not set `Changed`.

	///

	/// The old keys for this validator are returned, or `None` if there were none.

	///

	/// This does not ensure that the reference counter in system is incremented appropriately, it

	/// must be done by the caller or the keys will be leaked in storage.

			);

		}

		}

	/// Query the owner of a session key by returning the owner's validator ID.

}

impl<T: Config> ValidatorRegistration<T::ValidatorId> for Pallet<T> {

}

impl<T: Config> ValidatorSet<T::AccountId> for Pallet<T> {

	type ValidatorId = T::ValidatorId;

	type ValidatorIdOf = T::ValidatorIdOf;

}

impl<T: Config> EstimateNextNewSession<BlockNumberFor<T>> for Pallet<T> {

	/// This session pallet always calls new_session and next_session at the same time, hence we

	/// do a simple proxy and pass the function to next rotation.

}

impl<T: Config> frame_support::traits::DisabledValidators for Pallet<T> {

}

/// Wraps the author-scraping logic for consensus engines that can recover

/// the canonical index of an author. This then transforms it into the

/// registering account-ID of that session key index.

pub struct FindAccountFromAuthorIndex<T, Inner>(core::marker::PhantomData<(T, Inner)>);

impl<T: Config, Inner: FindAuthor<u32>> FindAuthor<T::ValidatorId>

	for FindAccountFromAuthorIndex<T, Inner>

{

}