// Copyright 2017-2020 Parity Technologies (UK) Ltd.
// This file is part of Substrate.
// Substrate is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
// Substrate is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
// GNU General Public License for more details.
// You should have received a copy of the GNU General Public License
// along with Substrate. If not, see .
//! # System Module
//!
//! The System module provides low-level access to core types and cross-cutting utilities.
//! It acts as the base layer for other pallets to interact with the Substrate framework components.
//!
//! - [`system::Trait`](./trait.Trait.html)
//!
//! ## Overview
//!
//! The System module defines the core data types used in a Substrate runtime.
//! It also provides several utility functions (see [`Module`](./struct.Module.html)) for other FRAME pallets.
//!
//! In addition, it manages the storage items for extrinsics data, indexes, event records, and digest items,
//! among other things that support the execution of the current block.
//!
//! It also handles low-level tasks like depositing logs, basic set up and take down of
//! temporary storage entries, and access to previous block hashes.
//!
//! ## Interface
//!
//! ### Dispatchable Functions
//!
//! The System module does not implement any dispatchable functions.
//!
//! ### Public Functions
//!
//! See the [`Module`](./struct.Module.html) struct for details of publicly available functions.
//!
//! ### Signed Extensions
//!
//! The System module defines the following extensions:
//!
//! - [`CheckWeight`]: Checks the weight and length of the block and ensure that it does not
//! exceed the limits.
//! - [`CheckNonce`]: Checks the nonce of the transaction. Contains a single payload of type
//! `T::Index`.
//! - [`CheckEra`]: Checks the era of the transaction. Contains a single payload of type `Era`.
//! - [`CheckGenesis`]: Checks the provided genesis hash of the transaction. Must be a part of the
//! signed payload of the transaction.
//! - [`CheckVersion`]: Checks that the runtime version is the same as the one encoded in the
//! transaction.
//!
//! Lookup the runtime aggregator file (e.g. `node/runtime`) to see the full list of signed
//! extensions included in a chain.
//!
//! ## Usage
//!
//! ### Prerequisites
//!
//! Import the System module and derive your module's configuration trait from the system trait.
//!
//! ### Example - Get extrinsic count and parent hash for the current block
//!
//! ```
//! use frame_support::{decl_module, dispatch, weights::MINIMUM_WEIGHT};
//! use frame_system::{self as system, ensure_signed};
//!
//! pub trait Trait: system::Trait {}
//!
//! decl_module! {
//! pub struct Module for enum Call where origin: T::Origin {
//! #[weight = MINIMUM_WEIGHT]
//! pub fn system_module_example(origin) -> dispatch::DispatchResult {
//! let _sender = ensure_signed(origin)?;
//! let _extrinsic_count = >::extrinsic_count();
//! let _parent_hash = >::parent_hash();
//! Ok(())
//! }
//! }
//! }
//! # fn main() { }
//! ```
#![cfg_attr(not(feature = "std"), no_std)]
#[cfg(feature = "std")]
use serde::Serialize;
use sp_std::prelude::*;
#[cfg(any(feature = "std", test))]
use sp_std::map;
use sp_std::convert::Infallible;
use sp_std::marker::PhantomData;
use sp_std::fmt::Debug;
use sp_version::RuntimeVersion;
use sp_runtime::{
RuntimeDebug, Perbill, DispatchOutcome, DispatchError, DispatchResult,
generic::{self, Era},
transaction_validity::{
ValidTransaction, TransactionPriority, TransactionLongevity, TransactionValidityError,
InvalidTransaction, TransactionValidity,
},
traits::{
self, CheckEqual, AtLeast32Bit, Zero, SignedExtension, Lookup, LookupError,
SimpleBitOps, Hash, Member, MaybeDisplay, BadOrigin, SaturatedConversion,
MaybeSerialize, MaybeSerializeDeserialize, MaybeMallocSizeOf, StaticLookup, One, Bounded,
Dispatchable, DispatchInfoOf, PostDispatchInfoOf,
},
};
use sp_core::{ChangesTrieConfiguration, storage::well_known_keys};
use frame_support::{
decl_module, decl_event, decl_storage, decl_error, storage, Parameter, ensure, debug,
traits::{
Contains, Get, ModuleToIndex, OnNewAccount, OnKilledAccount, IsDeadAccount, Happened,
StoredMap, EnsureOrigin,
},
weights::{
Weight, MINIMUM_WEIGHT, RuntimeDbWeight, DispatchInfo, PostDispatchInfo, DispatchClass,
FunctionOf, Pays,
}
};
use codec::{Encode, Decode, FullCodec, EncodeLike};
#[cfg(any(feature = "std", test))]
use sp_io::TestExternalities;
pub mod offchain;
/// Compute the trie root of a list of extrinsics.
pub fn extrinsics_root(extrinsics: &[E]) -> H::Output {
extrinsics_data_root::(extrinsics.iter().map(codec::Encode::encode).collect())
}
/// Compute the trie root of a list of extrinsics.
pub fn extrinsics_data_root(xts: Vec>) -> H::Output {
H::ordered_trie_root(xts)
}
pub trait Trait: 'static + Eq + Clone {
/// The aggregated `Origin` type used by dispatchable calls.
type Origin:
Into, Self::Origin>>
+ From>
+ Clone;
/// The aggregated `Call` type.
type Call: Dispatchable + Debug;
/// Account index (aka nonce) type. This stores the number of previous transactions associated
/// with a sender account.
type Index:
Parameter + Member + MaybeSerialize + Debug + Default + MaybeDisplay + AtLeast32Bit
+ Copy;
/// The block number type used by the runtime.
type BlockNumber:
Parameter + Member + MaybeSerializeDeserialize + Debug + MaybeDisplay + AtLeast32Bit
+ Default + Bounded + Copy + sp_std::hash::Hash + sp_std::str::FromStr + MaybeMallocSizeOf;
/// The output of the `Hashing` function.
type Hash:
Parameter + Member + MaybeSerializeDeserialize + Debug + MaybeDisplay + SimpleBitOps + Ord
+ Default + Copy + CheckEqual + sp_std::hash::Hash + AsRef<[u8]> + AsMut<[u8]> + MaybeMallocSizeOf;
/// The hashing system (algorithm) being used in the runtime (e.g. Blake2).
type Hashing: Hash;
/// The user account identifier type for the runtime.
type AccountId: Parameter + Member + MaybeSerializeDeserialize + Debug + MaybeDisplay + Ord
+ Default;
/// Converting trait to take a source type and convert to `AccountId`.
///
/// Used to define the type and conversion mechanism for referencing accounts in transactions.
/// It's perfectly reasonable for this to be an identity conversion (with the source type being
/// `AccountId`), but other modules (e.g. Indices module) may provide more functional/efficient
/// alternatives.
type Lookup: StaticLookup;
/// The block header.
type Header: Parameter + traits::Header<
Number = Self::BlockNumber,
Hash = Self::Hash,
>;
/// The aggregated event type of the runtime.
type Event: Parameter + Member + From> + Debug;
/// Maximum number of block number to block hash mappings to keep (oldest pruned first).
type BlockHashCount: Get;
/// The maximum weight of a block.
type MaximumBlockWeight: Get;
/// The weight of runtime database operations the runtime can invoke.
type DbWeight: Get;
/// The maximum length of a block (in bytes).
type MaximumBlockLength: Get;
/// The portion of the block that is available to normal transaction. The rest can only be used
/// by operational transactions. This can be applied to any resource limit managed by the system
/// module, including weight and length.
type AvailableBlockRatio: Get;
/// Get the chain's current version.
type Version: Get;
/// Convert a module to its index in the runtime.
///
/// Expects the `ModuleToIndex` type that is being generated by `construct_runtime!` in the
/// runtime. For tests it is okay to use `()` as type (returns `0` for each input).
type ModuleToIndex: ModuleToIndex;
/// Data to be associated with an account (other than nonce/transaction counter, which this
/// module does regardless).
type AccountData: Member + FullCodec + Clone + Default;
/// Handler for when a new account has just been created.
type OnNewAccount: OnNewAccount;
/// A function that is invoked when an account has been determined to be dead.
///
/// All resources should be cleaned up associated with the given account.
type OnKilledAccount: OnKilledAccount;
}
pub type DigestOf = generic::Digest<::Hash>;
pub type DigestItemOf = generic::DigestItem<::Hash>;
pub type Key = Vec;
pub type KeyValue = (Vec, Vec);
/// A phase of a block's execution.
#[derive(Encode, Decode, RuntimeDebug)]
#[cfg_attr(feature = "std", derive(Serialize, PartialEq, Eq, Clone))]
pub enum Phase {
/// Applying an extrinsic.
ApplyExtrinsic(u32),
/// Finalizing the block.
Finalization,
/// Initializing the block.
Initialization,
}
impl Default for Phase {
fn default() -> Self {
Self::Initialization
}
}
/// Record of an event happening.
#[derive(Encode, Decode, RuntimeDebug)]
#[cfg_attr(feature = "std", derive(Serialize, PartialEq, Eq, Clone))]
pub struct EventRecord {
/// The phase of the block it happened in.
pub phase: Phase,
/// The event itself.
pub event: E,
/// The list of the topics this event has.
pub topics: Vec,
}
/// Origin for the System module.
#[derive(PartialEq, Eq, Clone, RuntimeDebug)]
pub enum RawOrigin {
/// The system itself ordained this dispatch to happen: this is the highest privilege level.
Root,
/// It is signed by some public key and we provide the `AccountId`.
Signed(AccountId),
/// It is signed by nobody, can be either:
/// * included and agreed upon by the validators anyway,
/// * or unsigned transaction validated by a module.
None,
}
impl From> for RawOrigin {
fn from(s: Option) -> RawOrigin {
match s {
Some(who) => RawOrigin::Signed(who),
None => RawOrigin::None,
}
}
}
/// Exposed trait-generic origin type.
pub type Origin = RawOrigin<::AccountId>;
// Create a Hash with 69 for each byte,
// only used to build genesis config.
#[cfg(feature = "std")]
fn hash69 + Default>() -> T {
let mut h = T::default();
h.as_mut().iter_mut().for_each(|byte| *byte = 69);
h
}
/// This type alias represents an index of an event.
///
/// We use `u32` here because this index is used as index for `Events`
/// which can't contain more than `u32::max_value()` items.
type EventIndex = u32;
/// Type used to encode the number of references an account has.
pub type RefCount = u8;
/// Information of an account.
#[derive(Clone, Eq, PartialEq, Default, RuntimeDebug, Encode, Decode)]
pub struct AccountInfo {
/// The number of transactions this account has sent.
pub nonce: Index,
/// The number of other modules that currently depend on this account's existence. The account
/// cannot be reaped until this is zero.
pub refcount: RefCount,
/// The additional data that belongs to this account. Used to store the balance(s) in a lot of
/// chains.
pub data: AccountData,
}
/// Stores the `spec_version` and `spec_name` of when the last runtime upgrade
/// happened.
#[derive(sp_runtime::RuntimeDebug, Encode, Decode)]
#[cfg_attr(feature = "std", derive(PartialEq))]
pub struct LastRuntimeUpgradeInfo {
pub spec_version: codec::Compact,
pub spec_name: sp_runtime::RuntimeString,
}
impl LastRuntimeUpgradeInfo {
/// Returns if the runtime was upgraded in comparison of `self` and `current`.
///
/// Checks if either the `spec_version` increased or the `spec_name` changed.
pub fn was_upgraded(&self, current: &sp_version::RuntimeVersion) -> bool {
current.spec_version > self.spec_version.0 || current.spec_name != self.spec_name
}
}
impl From for LastRuntimeUpgradeInfo {
fn from(version: sp_version::RuntimeVersion) -> Self {
Self {
spec_version: version.spec_version.into(),
spec_name: version.spec_name,
}
}
}
decl_storage! {
trait Store for Module as System {
/// The full account information for a particular account ID.
pub Account get(fn account):
map hasher(blake2_128_concat) T::AccountId => AccountInfo;
/// Total extrinsics count for the current block.
ExtrinsicCount: Option;
/// Total weight for all extrinsics put together, for the current block.
AllExtrinsicsWeight: Option;
/// Total length (in bytes) for all extrinsics put together, for the current block.
AllExtrinsicsLen: Option;
/// Map of block numbers to block hashes.
pub BlockHash get(fn block_hash) build(|_| vec![(T::BlockNumber::zero(), hash69())]):
map hasher(twox_64_concat) T::BlockNumber => T::Hash;
/// Extrinsics data for the current block (maps an extrinsic's index to its data).
ExtrinsicData get(fn extrinsic_data): map hasher(twox_64_concat) u32 => Vec;
/// The current block number being processed. Set by `execute_block`.
Number get(fn block_number): T::BlockNumber;
/// Hash of the previous block.
ParentHash get(fn parent_hash) build(|_| hash69()): T::Hash;
/// Extrinsics root of the current block, also part of the block header.
ExtrinsicsRoot get(fn extrinsics_root): T::Hash;
/// Digest of the current block, also part of the block header.
Digest get(fn digest): DigestOf;
/// Events deposited for the current block.
Events get(fn events): Vec>;
/// The number of events in the `Events` list.
EventCount get(fn event_count): EventIndex;
// TODO: https://github.com/paritytech/substrate/issues/2553
// Possibly, we can improve it by using something like:
// `Option<(BlockNumber, Vec)>`, however in this case we won't be able to use
// `EventTopics::append`.
/// Mapping between a topic (represented by T::Hash) and a vector of indexes
/// of events in the `>` list.
///
/// All topic vectors have deterministic storage locations depending on the topic. This
/// allows light-clients to leverage the changes trie storage tracking mechanism and
/// in case of changes fetch the list of events of interest.
///
/// The value has the type `(T::BlockNumber, EventIndex)` because if we used only just
/// the `EventIndex` then in case if the topic has the same contents on the next block
/// no notification will be triggered thus the event might be lost.
EventTopics get(fn event_topics): map hasher(blake2_128_concat) T::Hash => Vec<(T::BlockNumber, EventIndex)>;
/// Stores the `spec_version` and `spec_name` of when the last runtime upgrade happened.
pub LastRuntimeUpgrade build(|_| Some(LastRuntimeUpgradeInfo::from(T::Version::get()))): Option;
/// The execution phase of the block.
ExecutionPhase: Option;
}
add_extra_genesis {
config(changes_trie_config): Option;
#[serde(with = "sp_core::bytes")]
config(code): Vec;
build(|config: &GenesisConfig| {
use codec::Encode;
sp_io::storage::set(well_known_keys::CODE, &config.code);
sp_io::storage::set(well_known_keys::EXTRINSIC_INDEX, &0u32.encode());
if let Some(ref changes_trie_config) = config.changes_trie_config {
sp_io::storage::set(
well_known_keys::CHANGES_TRIE_CONFIG,
&changes_trie_config.encode(),
);
}
});
}
}
decl_event!(
/// Event for the System module.
pub enum Event where AccountId = ::AccountId {
/// An extrinsic completed successfully.
ExtrinsicSuccess(DispatchInfo),
/// An extrinsic failed.
ExtrinsicFailed(DispatchError, DispatchInfo),
/// `:code` was updated.
CodeUpdated,
/// A new account was created.
NewAccount(AccountId),
/// An account was reaped.
KilledAccount(AccountId),
}
);
decl_error! {
/// Error for the System module
pub enum Error for Module {
/// The name of specification does not match between the current runtime
/// and the new runtime.
InvalidSpecName,
/// The specification version is not allowed to decrease between the current runtime
/// and the new runtime.
SpecVersionNeedsToIncrease,
/// Failed to extract the runtime version from the new runtime.
///
/// Either calling `Core_version` or decoding `RuntimeVersion` failed.
FailedToExtractRuntimeVersion,
/// Suicide called when the account has non-default composite data.
NonDefaultComposite,
/// There is a non-zero reference count preventing the account from being purged.
NonZeroRefCount,
}
}
decl_module! {
pub struct Module for enum Call where origin: T::Origin {
type Error = Error;
/// The maximum weight of a block.
const MaximumBlockWeight: Weight = T::MaximumBlockWeight::get();
/// The maximum length of a block (in bytes).
const MaximumBlockLength: u32 = T::MaximumBlockLength::get();
/// A dispatch that will fill the block weight up to the given ratio.
// TODO: This should only be available for testing, rather than in general usage, but
// that's not possible at present (since it's within the decl_module macro).
#[weight = FunctionOf(
|(ratio,): (&Perbill,)| *ratio * T::MaximumBlockWeight::get(),
DispatchClass::Operational,
Pays::Yes,
)]
fn fill_block(origin, _ratio: Perbill) {
ensure_root(origin)?;
}
/// Make some on-chain remark.
///
/// #
/// - `O(1)`
/// #
#[weight = MINIMUM_WEIGHT]
fn remark(origin, _remark: Vec) {
ensure_signed(origin)?;
}
/// Set the number of pages in the WebAssembly environment's heap.
///
/// #
/// - `O(1)`
/// - 1 storage write.
/// #
#[weight = (MINIMUM_WEIGHT, DispatchClass::Operational)]
fn set_heap_pages(origin, pages: u64) {
ensure_root(origin)?;
storage::unhashed::put_raw(well_known_keys::HEAP_PAGES, &pages.encode());
}
/// Set the new runtime code.
///
/// #
/// - `O(C + S)` where `C` length of `code` and `S` complexity of `can_set_code`
/// - 1 storage write (codec `O(C)`).
/// - 1 call to `can_set_code`: `O(S)` (calls `sp_io::misc::runtime_version` which is expensive).
/// - 1 event.
/// #
#[weight = (200_000_000, DispatchClass::Operational)]
pub fn set_code(origin, code: Vec) {
Self::can_set_code(origin, &code)?;
storage::unhashed::put_raw(well_known_keys::CODE, &code);
Self::deposit_event(RawEvent::CodeUpdated);
}
/// Set the new runtime code without doing any checks of the given `code`.
///
/// #
/// - `O(C)` where `C` length of `code`
/// - 1 storage write (codec `O(C)`).
/// - 1 event.
/// #
#[weight = (200_000_000, DispatchClass::Operational)]
pub fn set_code_without_checks(origin, code: Vec) {
ensure_root(origin)?;
storage::unhashed::put_raw(well_known_keys::CODE, &code);
Self::deposit_event(RawEvent::CodeUpdated);
}
/// Set the new changes trie configuration.
///
/// #
/// - `O(D)` where `D` length of `Digest`
/// - 1 storage write or delete (codec `O(1)`).
/// - 1 call to `deposit_log`: `O(D)` (which depends on the length of `Digest`)
/// #
#[weight = (20_000_000, DispatchClass::Operational)]
pub fn set_changes_trie_config(origin, changes_trie_config: Option) {
ensure_root(origin)?;
match changes_trie_config.clone() {
Some(changes_trie_config) => storage::unhashed::put_raw(
well_known_keys::CHANGES_TRIE_CONFIG,
&changes_trie_config.encode(),
),
None => storage::unhashed::kill(well_known_keys::CHANGES_TRIE_CONFIG),
}
let log = generic::DigestItem::ChangesTrieSignal(
generic::ChangesTrieSignal::NewConfiguration(changes_trie_config),
);
Self::deposit_log(log.into());
}
/// Set some items of storage.
///
/// #
/// - `O(I)` where `I` length of `items`
/// - `I` storage writes (`O(1)`).
/// #
#[weight = (MINIMUM_WEIGHT, DispatchClass::Operational)]
fn set_storage(origin, items: Vec) {
ensure_root(origin)?;
for i in &items {
storage::unhashed::put_raw(&i.0, &i.1);
}
}
/// Kill some items from storage.
///
/// #
/// - `O(VK)` where `V` length of `keys` and `K` length of one key
/// - `V` storage deletions.
/// #
#[weight = (MINIMUM_WEIGHT, DispatchClass::Operational)]
fn kill_storage(origin, keys: Vec) {
ensure_root(origin)?;
for key in &keys {
storage::unhashed::kill(&key);
}
}
/// Kill all storage items with a key that starts with the given prefix.
///
/// #
/// - `O(P)` where `P` amount of keys with prefix `prefix`
/// - `P` storage deletions.
/// #
#[weight = (MINIMUM_WEIGHT, DispatchClass::Operational)]
fn kill_prefix(origin, prefix: Key) {
ensure_root(origin)?;
storage::unhashed::kill_prefix(&prefix);
}
/// Kill the sending account, assuming there are no references outstanding and the composite
/// data is equal to its default value.
///
/// #
/// - `O(K)` with `K` being complexity of `on_killed_account`
/// - 1 storage read and deletion.
/// - 1 call to `on_killed_account` callback with unknown complexity `K`
/// - 1 event.
/// #
#[weight = (25_000_000, DispatchClass::Operational)]
fn suicide(origin) {
let who = ensure_signed(origin)?;
let account = Account::::get(&who);
ensure!(account.refcount == 0, Error::::NonZeroRefCount);
ensure!(account.data == T::AccountData::default(), Error::::NonDefaultComposite);
Account::::remove(who);
}
}
}
pub struct EnsureRoot(sp_std::marker::PhantomData);
impl<
O: Into, O>> + From>,
AccountId,
> EnsureOrigin for EnsureRoot {
type Success = ();
fn try_origin(o: O) -> Result {
o.into().and_then(|o| match o {
RawOrigin::Root => Ok(()),
r => Err(O::from(r)),
})
}
#[cfg(feature = "runtime-benchmarks")]
fn successful_origin() -> O {
O::from(RawOrigin::Root)
}
}
pub struct EnsureSigned(sp_std::marker::PhantomData);
impl<
O: Into, O>> + From>,
AccountId: Default,
> EnsureOrigin for EnsureSigned {
type Success = AccountId;
fn try_origin(o: O) -> Result {
o.into().and_then(|o| match o {
RawOrigin::Signed(who) => Ok(who),
r => Err(O::from(r)),
})
}
#[cfg(feature = "runtime-benchmarks")]
fn successful_origin() -> O {
O::from(RawOrigin::Signed(Default::default()))
}
}
pub struct EnsureSignedBy(sp_std::marker::PhantomData<(Who, AccountId)>);
impl<
O: Into, O>> + From>,
Who: Contains,
AccountId: PartialEq + Clone + Ord + Default,
> EnsureOrigin for EnsureSignedBy {
type Success = AccountId;
fn try_origin(o: O) -> Result {
o.into().and_then(|o| match o {
RawOrigin::Signed(ref who) if Who::contains(who) => Ok(who.clone()),
r => Err(O::from(r)),
})
}
#[cfg(feature = "runtime-benchmarks")]
fn successful_origin() -> O {
let members = Who::sorted_members();
let first_member = match members.get(0) {
Some(account) => account.clone(),
None => Default::default(),
};
O::from(RawOrigin::Signed(first_member.clone()))
}
}
pub struct EnsureNone(sp_std::marker::PhantomData);
impl<
O: Into, O>> + From>,
AccountId,
> EnsureOrigin for EnsureNone {
type Success = ();
fn try_origin(o: O) -> Result {
o.into().and_then(|o| match o {
RawOrigin::None => Ok(()),
r => Err(O::from(r)),
})
}
#[cfg(feature = "runtime-benchmarks")]
fn successful_origin() -> O {
O::from(RawOrigin::None)
}
}
pub struct EnsureNever(sp_std::marker::PhantomData);
impl EnsureOrigin for EnsureNever {
type Success = T;
fn try_origin(o: O) -> Result {
Err(o)
}
#[cfg(feature = "runtime-benchmarks")]
fn successful_origin() -> O {
unimplemented!()
}
}
/// Ensure that the origin `o` represents a signed extrinsic (i.e. transaction).
/// Returns `Ok` with the account that signed the extrinsic or an `Err` otherwise.
pub fn ensure_signed(o: OuterOrigin) -> Result
where OuterOrigin: Into, OuterOrigin>>
{
match o.into() {
Ok(RawOrigin::Signed(t)) => Ok(t),
_ => Err(BadOrigin),
}
}
/// Ensure that the origin `o` represents the root. Returns `Ok` or an `Err` otherwise.
pub fn ensure_root(o: OuterOrigin) -> Result<(), BadOrigin>
where OuterOrigin: Into, OuterOrigin>>
{
match o.into() {
Ok(RawOrigin::Root) => Ok(()),
_ => Err(BadOrigin),
}
}
/// Ensure that the origin `o` represents an unsigned extrinsic. Returns `Ok` or an `Err` otherwise.
pub fn ensure_none(o: OuterOrigin) -> Result<(), BadOrigin>
where OuterOrigin: Into, OuterOrigin>>
{
match o.into() {
Ok(RawOrigin::None) => Ok(()),
_ => Err(BadOrigin),
}
}
/// A type of block initialization to perform.
pub enum InitKind {
/// Leave inspectable storage entries in state.
///
/// i.e. `Events` are not being reset.
/// Should only be used for off-chain calls,
/// regular block execution should clear those.
Inspection,
/// Reset also inspectable storage entries.
///
/// This should be used for regular block execution.
Full,
}
impl Default for InitKind {
fn default() -> Self {
InitKind::Full
}
}
/// Reference status; can be either referenced or unreferenced.
pub enum RefStatus {
Referenced,
Unreferenced,
}
impl Module {
/// Deposits an event into this block's event record.
pub fn deposit_event(event: impl Into) {
Self::deposit_event_indexed(&[], event.into());
}
/// Increment the reference counter on an account.
pub fn inc_ref(who: &T::AccountId) {
Account::::mutate(who, |a| a.refcount = a.refcount.saturating_add(1));
}
/// Decrement the reference counter on an account. This *MUST* only be done once for every time
/// you called `inc_ref` on `who`.
pub fn dec_ref(who: &T::AccountId) {
Account::::mutate(who, |a| a.refcount = a.refcount.saturating_sub(1));
}
/// The number of outstanding references for the account `who`.
pub fn refs(who: &T::AccountId) -> RefCount {
Account::::get(who).refcount
}
/// True if the account has no outstanding references.
pub fn allow_death(who: &T::AccountId) -> bool {
Account::::get(who).refcount == 0
}
/// Deposits an event into this block's event record adding this event
/// to the corresponding topic indexes.
///
/// This will update storage entries that correspond to the specified topics.
/// It is expected that light-clients could subscribe to this topics.
pub fn deposit_event_indexed(topics: &[T::Hash], event: T::Event) {
let block_number = Self::block_number();
// Don't populate events on genesis.
if block_number.is_zero() { return }
let phase = ExecutionPhase::get().unwrap_or_default();
let event = EventRecord {
phase,
event,
topics: topics.iter().cloned().collect::>(),
};
// Index of the to be added event.
let event_idx = {
let old_event_count = EventCount::get();
let new_event_count = match old_event_count.checked_add(1) {
// We've reached the maximum number of events at this block, just
// don't do anything and leave the event_count unaltered.
None => return,
Some(nc) => nc,
};
EventCount::put(new_event_count);
old_event_count
};
// Appending can only fail if `Events` can not be decoded or
// when we try to insert more than `u32::max_value()` events.
//
// We perform early return if we've reached the maximum capacity of the event list,
// so `Events` seems to be corrupted. Also, this has happened after the start of execution
// (since the event list is cleared at the block initialization).
if >::append([event].iter()).is_err() {
// The most sensible thing to do here is to just ignore this event and wait until the
// new block.
return;
}
for topic in topics {
// The same applies here.
if >::append(topic, &[(block_number, event_idx)]).is_err() {
return;
}
}
}
/// Gets the index of extrinsic that is currently executing.
pub fn extrinsic_index() -> Option {
storage::unhashed::get(well_known_keys::EXTRINSIC_INDEX)
}
/// Gets extrinsics count.
pub fn extrinsic_count() -> u32 {
ExtrinsicCount::get().unwrap_or_default()
}
/// Gets a total weight of all executed extrinsics.
pub fn all_extrinsics_weight() -> Weight {
AllExtrinsicsWeight::get().unwrap_or_default()
}
pub fn all_extrinsics_len() -> u32 {
AllExtrinsicsLen::get().unwrap_or_default()
}
/// Inform the system module of some additional weight that should be accounted for, in the
/// current block.
///
/// NOTE: use with extra care; this function is made public only be used for certain modules
/// that need it. A runtime that does not have dynamic calls should never need this and should
/// stick to static weights. A typical use case for this is inner calls or smart contract calls.
/// Furthermore, it only makes sense to use this when it is presumably _cheap_ to provide the
/// argument `weight`; In other words, if this function is to be used to account for some
/// unknown, user provided call's weight, it would only make sense to use it if you are sure you
/// can rapidly compute the weight of the inner call.
///
/// Even more dangerous is to note that this function does NOT take any action, if the new sum
/// of block weight is more than the block weight limit. This is what the _unchecked_.
///
/// Another potential use-case could be for the `on_initialize` and `on_finalize` hooks.
///
/// If no previous weight exists, the function initializes the weight to zero.
pub fn register_extra_weight_unchecked(weight: Weight) {
let current_weight = AllExtrinsicsWeight::get().unwrap_or_default();
let next_weight = current_weight.saturating_add(weight).min(T::MaximumBlockWeight::get());
AllExtrinsicsWeight::put(next_weight);
}
/// Start the execution of a particular block.
pub fn initialize(
number: &T::BlockNumber,
parent_hash: &T::Hash,
txs_root: &T::Hash,
digest: &DigestOf,
kind: InitKind,
) {
// populate environment
ExecutionPhase::put(Phase::Initialization);
storage::unhashed::put(well_known_keys::EXTRINSIC_INDEX, &0u32);
>::put(number);
>::put(digest);
>::put(parent_hash);
>::insert(*number - One::one(), parent_hash);
>::put(txs_root);
if let InitKind::Full = kind {
>::kill();
EventCount::kill();
>::remove_all();
}
}
/// Remove temporary "environment" entries in storage.
pub fn finalize() -> T::Header {
ExecutionPhase::kill();
ExtrinsicCount::kill();
AllExtrinsicsWeight::kill();
AllExtrinsicsLen::kill();
let number = >::take();
let parent_hash = >::take();
let mut digest = >::take();
let extrinsics_root = >::take();
// move block hash pruning window by one block
let block_hash_count = ::get();
if number > block_hash_count {
let to_remove = number - block_hash_count - One::one();
// keep genesis hash
if to_remove != Zero::zero() {
>::remove(to_remove);
}
}
let storage_root = T::Hash::decode(&mut &sp_io::storage::root()[..])
.expect("Node is configured to use the same hash; qed");
let storage_changes_root = sp_io::storage::changes_root(&parent_hash.encode());
// we can't compute changes trie root earlier && put it to the Digest
// because it will include all currently existing temporaries.
if let Some(storage_changes_root) = storage_changes_root {
let item = generic::DigestItem::ChangesTrieRoot(
T::Hash::decode(&mut &storage_changes_root[..])
.expect("Node is configured to use the same hash; qed")
);
digest.push(item);
}
// The following fields
//
// - >
// - >
// - >
//
// stay to be inspected by the client and will be cleared by `Self::initialize`.
::new(number, extrinsics_root, storage_root, parent_hash, digest)
}
/// Deposits a log and ensures it matches the block's log data.
///
/// #
/// - `O(D)` where `D` length of `Digest`
/// - 1 storage mutation (codec `O(D)`).
/// #
pub fn deposit_log(item: DigestItemOf) {
let mut l = >::get();
l.push(item);
>::put(l);
}
/// Get the basic externalities for this module, useful for tests.
#[cfg(any(feature = "std", test))]
pub fn externalities() -> TestExternalities {
TestExternalities::new(sp_core::storage::Storage {
top: map![
>::hashed_key_for(T::BlockNumber::zero()) => [69u8; 32].encode(),
>::hashed_key().to_vec() => T::BlockNumber::one().encode(),
>::hashed_key().to_vec() => [69u8; 32].encode()
],
children_default: map![],
})
}
/// Set the block number to something in particular. Can be used as an alternative to
/// `initialize` for tests that don't need to bother with the other environment entries.
#[cfg(any(feature = "std", feature = "runtime-benchmarks", test))]
pub fn set_block_number(n: T::BlockNumber) {
>::put(n);
}
/// Sets the index of extrinsic that is currently executing.
#[cfg(any(feature = "std", test))]
pub fn set_extrinsic_index(extrinsic_index: u32) {
storage::unhashed::put(well_known_keys::EXTRINSIC_INDEX, &extrinsic_index)
}
/// Set the parent hash number to something in particular. Can be used as an alternative to
/// `initialize` for tests that don't need to bother with the other environment entries.
#[cfg(any(feature = "std", test))]
pub fn set_parent_hash(n: T::Hash) {
>::put(n);
}
/// Set the current block weight. This should only be used in some integration tests.
#[cfg(any(feature = "std", test))]
pub fn set_block_limits(weight: Weight, len: usize) {
AllExtrinsicsWeight::put(weight);
AllExtrinsicsLen::put(len as u32);
}
/// Return the chain's current runtime version.
pub fn runtime_version() -> RuntimeVersion { T::Version::get() }
/// Retrieve the account transaction counter from storage.
pub fn account_nonce(who: impl EncodeLike) -> T::Index {
Account::::get(who).nonce
}
/// Increment a particular account's nonce by 1.
pub fn inc_account_nonce(who: impl EncodeLike) {
Account::::mutate(who, |a| a.nonce += T::Index::one());
}
/// Note what the extrinsic data of the current extrinsic index is. If this
/// is called, then ensure `derive_extrinsics` is also called before
/// block-building is completed.
///
/// NOTE: This function is called only when the block is being constructed locally.
/// `execute_block` doesn't note any extrinsics.
pub fn note_extrinsic(encoded_xt: Vec) {
ExtrinsicData::insert(Self::extrinsic_index().unwrap_or_default(), encoded_xt);
}
/// To be called immediately after an extrinsic has been applied.
pub fn note_applied_extrinsic(r: &DispatchOutcome, _encoded_len: u32, info: DispatchInfo) {
Self::deposit_event(
match r {
Ok(()) => RawEvent::ExtrinsicSuccess(info),
Err(err) => {
sp_runtime::print(err);
RawEvent::ExtrinsicFailed(err.clone(), info)
},
}
);
let next_extrinsic_index = Self::extrinsic_index().unwrap_or_default() + 1u32;
storage::unhashed::put(well_known_keys::EXTRINSIC_INDEX, &next_extrinsic_index);
ExecutionPhase::put(Phase::ApplyExtrinsic(next_extrinsic_index));
}
/// To be called immediately after `note_applied_extrinsic` of the last extrinsic of the block
/// has been called.
pub fn note_finished_extrinsics() {
let extrinsic_index: u32 = storage::unhashed::take(well_known_keys::EXTRINSIC_INDEX)
.unwrap_or_default();
ExtrinsicCount::put(extrinsic_index);
ExecutionPhase::put(Phase::Finalization);
}
/// To be called immediately after finishing the initialization of the block
/// (e.g., called `on_initialize` for all modules).
pub fn note_finished_initialize() {
ExecutionPhase::put(Phase::ApplyExtrinsic(0))
}
/// Remove all extrinsic data and save the extrinsics trie root.
pub fn derive_extrinsics() {
let extrinsics = (0..ExtrinsicCount::get().unwrap_or_default())
.map(ExtrinsicData::take).collect();
let xts_root = extrinsics_data_root::(extrinsics);
>::put(xts_root);
}
/// An account is being created.
pub fn on_created_account(who: T::AccountId) {
T::OnNewAccount::on_new_account(&who);
Self::deposit_event(RawEvent::NewAccount(who));
}
/// Do anything that needs to be done after an account has been killed.
fn on_killed_account(who: T::AccountId) {
T::OnKilledAccount::on_killed_account(&who);
Self::deposit_event(RawEvent::KilledAccount(who));
}
/// Remove an account from storage. This should only be done when its refs are zero or you'll
/// get storage leaks in other modules. Nonetheless we assume that the calling logic knows best.
///
/// This is a no-op if the account doesn't already exist. If it does then it will ensure
/// cleanups (those in `on_killed_account`) take place.
fn kill_account(who: &T::AccountId) {
if Account::::contains_key(who) {
let account = Account::::take(who);
if account.refcount > 0 {
debug::debug!(
target: "system",
"WARNING: Referenced account deleted. This is probably a bug."
);
}
Module::::on_killed_account(who.clone());
}
}
/// Determine whether or not it is possible to update the code.
///
/// This function has no side effects and is idempotent, but is fairly
/// heavy. It is automatically called by `set_code`; in most cases,
/// a direct call to `set_code` is preferable. It is useful to call
/// `can_set_code` when it is desirable to perform the appropriate
/// runtime checks without actually changing the code yet.
pub fn can_set_code(origin: T::Origin, code: &[u8]) -> Result<(), sp_runtime::DispatchError> {
ensure_root(origin)?;
let current_version = T::Version::get();
let new_version = sp_io::misc::runtime_version(&code)
.and_then(|v| RuntimeVersion::decode(&mut &v[..]).ok())
.ok_or_else(|| Error::::FailedToExtractRuntimeVersion)?;
if new_version.spec_name != current_version.spec_name {
Err(Error::::InvalidSpecName)?
}
if new_version.spec_version <= current_version.spec_version {
Err(Error::::SpecVersionNeedsToIncrease)?
}
Ok(())
}
}
/// Event handler which calls on_created_account when it happens.
pub struct CallOnCreatedAccount(PhantomData);
impl Happened for CallOnCreatedAccount {
fn happened(who: &T::AccountId) {
Module::::on_created_account(who.clone());
}
}
/// Event handler which calls kill_account when it happens.
pub struct CallKillAccount(PhantomData);
impl Happened for CallKillAccount {
fn happened(who: &T::AccountId) {
Module::::kill_account(who)
}
}
// Implement StoredMap for a simple single-item, kill-account-on-remove system. This works fine for
// storing a single item which is required to not be empty/default for the account to exist.
// Anything more complex will need more sophisticated logic.
impl StoredMap for Module {
fn get(k: &T::AccountId) -> T::AccountData {
Account::::get(k).data
}
fn is_explicit(k: &T::AccountId) -> bool {
Account::::contains_key(k)
}
fn insert(k: &T::AccountId, data: T::AccountData) {
let existed = Account::::contains_key(k);
Account::::mutate(k, |a| a.data = data);
if !existed {
Self::on_created_account(k.clone());
}
}
fn remove(k: &T::AccountId) {
Self::kill_account(k)
}
fn mutate(k: &T::AccountId, f: impl FnOnce(&mut T::AccountData) -> R) -> R {
let existed = Account::::contains_key(k);
let r = Account::::mutate(k, |a| f(&mut a.data));
if !existed {
Self::on_created_account(k.clone());
}
r
}
fn mutate_exists(k: &T::AccountId, f: impl FnOnce(&mut Option) -> R) -> R {
Self::try_mutate_exists(k, |x| -> Result { Ok(f(x)) }).expect("Infallible; qed")
}
fn try_mutate_exists(k: &T::AccountId, f: impl FnOnce(&mut Option) -> Result) -> Result {
Account::::try_mutate_exists(k, |maybe_value| {
let existed = maybe_value.is_some();
let (maybe_prefix, mut maybe_data) = split_inner(
maybe_value.take(),
|account| ((account.nonce, account.refcount), account.data)
);
f(&mut maybe_data).map(|result| {
*maybe_value = maybe_data.map(|data| {
let (nonce, refcount) = maybe_prefix.unwrap_or_default();
AccountInfo { nonce, refcount, data }
});
(existed, maybe_value.is_some(), result)
})
}).map(|(existed, exists, v)| {
if !existed && exists {
Self::on_created_account(k.clone());
} else if existed && !exists {
Self::on_killed_account(k.clone());
}
v
})
}
}
/// Split an `option` into two constituent options, as defined by a `splitter` function.
pub fn split_inner(option: Option, splitter: impl FnOnce(T) -> (R, S))
-> (Option, Option)
{
match option {
Some(inner) => {
let (r, s) = splitter(inner);
(Some(r), Some(s))
}
None => (None, None),
}
}
/// resource limit check.
#[derive(Encode, Decode, Clone, Eq, PartialEq)]
pub struct CheckWeight(PhantomData);
impl CheckWeight where
T::Call: Dispatchable
{
/// Get the quota ratio of each dispatch class type. This indicates that all operational
/// dispatches can use the full capacity of any resource, while user-triggered ones can consume
/// a portion.
fn get_dispatch_limit_ratio(class: DispatchClass) -> Perbill {
match class {
DispatchClass::Operational | DispatchClass::Mandatory
=> ::one(),
DispatchClass::Normal => T::AvailableBlockRatio::get(),
}
}
/// Checks if the current extrinsic can fit into the block with respect to block weight limits.
///
/// Upon successes, it returns the new block weight as a `Result`.
fn check_weight(
info: &DispatchInfoOf,
) -> Result {
let current_weight = Module::::all_extrinsics_weight();
let maximum_weight = T::MaximumBlockWeight::get();
let limit = Self::get_dispatch_limit_ratio(info.class) * maximum_weight;
let added_weight = info.weight.min(limit);
let next_weight = current_weight.saturating_add(added_weight);
if next_weight > limit && info.class != DispatchClass::Mandatory {
Err(InvalidTransaction::ExhaustsResources.into())
} else {
Ok(next_weight)
}
}
/// Checks if the current extrinsic can fit into the block with respect to block length limits.
///
/// Upon successes, it returns the new block length as a `Result`.
fn check_block_length(
info: &DispatchInfoOf,
len: usize,
) -> Result {
let current_len = Module::::all_extrinsics_len();
let maximum_len = T::MaximumBlockLength::get();
let limit = Self::get_dispatch_limit_ratio(info.class) * maximum_len;
let added_len = len as u32;
let next_len = current_len.saturating_add(added_len);
if next_len > limit {
Err(InvalidTransaction::ExhaustsResources.into())
} else {
Ok(next_len)
}
}
/// get the priority of an extrinsic denoted by `info`.
fn get_priority(info: &DispatchInfoOf) -> TransactionPriority {
match info.class {
DispatchClass::Normal => info.weight.into(),
DispatchClass::Operational => Bounded::max_value(),
// Mandatory extrinsics are only for inherents; never transactions.
DispatchClass::Mandatory => Bounded::min_value(),
}
}
/// Creates new `SignedExtension` to check weight of the extrinsic.
pub fn new() -> Self {
Self(PhantomData)
}
/// Do the pre-dispatch checks. This can be applied to both signed and unsigned.
///
/// It checks and notes the new weight and length.
fn do_pre_dispatch(
info: &DispatchInfoOf,
len: usize,
) -> Result<(), TransactionValidityError> {
let next_len = Self::check_block_length(info, len)?;
let next_weight = Self::check_weight(info)?;
AllExtrinsicsLen::put(next_len);
AllExtrinsicsWeight::put(next_weight);
Ok(())
}
/// Do the validate checks. This can be applied to both signed and unsigned.
///
/// It only checks that the block weight and length limit will not exceed.
fn do_validate(
info: &DispatchInfoOf,
len: usize,
) -> TransactionValidity {
// ignore the next weight and length. If they return `Ok`, then it is below the limit.
let _ = Self::check_block_length(info, len)?;
let _ = Self::check_weight(info)?;
Ok(ValidTransaction { priority: Self::get_priority(info), ..Default::default() })
}
}
impl SignedExtension for CheckWeight where
T::Call: Dispatchable
{
type AccountId = T::AccountId;
type Call = T::Call;
type AdditionalSigned = ();
type Pre = ();
const IDENTIFIER: &'static str = "CheckWeight";
fn additional_signed(&self) -> sp_std::result::Result<(), TransactionValidityError> { Ok(()) }
fn pre_dispatch(
self,
_who: &Self::AccountId,
_call: &Self::Call,
info: &DispatchInfoOf,
len: usize,
) -> Result<(), TransactionValidityError> {
if info.class == DispatchClass::Mandatory {
Err(InvalidTransaction::MandatoryDispatch)?
}
Self::do_pre_dispatch(info, len)
}
fn validate(
&self,
_who: &Self::AccountId,
_call: &Self::Call,
info: &DispatchInfoOf,
len: usize,
) -> TransactionValidity {
if info.class == DispatchClass::Mandatory {
Err(InvalidTransaction::MandatoryDispatch)?
}
Self::do_validate(info, len)
}
fn pre_dispatch_unsigned(
_call: &Self::Call,
info: &DispatchInfoOf,
len: usize,
) -> Result<(), TransactionValidityError> {
Self::do_pre_dispatch(info, len)
}
fn validate_unsigned(
_call: &Self::Call,
info: &DispatchInfoOf,
len: usize,
) -> TransactionValidity {
Self::do_validate(info, len)
}
fn post_dispatch(
_pre: Self::Pre,
info: &DispatchInfoOf,
post_info: &PostDispatchInfoOf,
_len: usize,
result: &DispatchResult,
) -> Result<(), TransactionValidityError> {
// Since mandatory dispatched do not get validated for being overweight, we are sensitive
// to them actually being useful. Block producers are thus not allowed to include mandatory
// extrinsics that result in error.
if info.class == DispatchClass::Mandatory && result.is_err() {
Err(InvalidTransaction::BadMandatory)?
}
let unspent = post_info.calc_unspent(info);
if unspent > 0 {
AllExtrinsicsWeight::mutate(|weight| {
*weight = weight.map(|w| w.saturating_sub(unspent));
})
}
Ok(())
}
}
impl Debug for CheckWeight {
#[cfg(feature = "std")]
fn fmt(&self, f: &mut sp_std::fmt::Formatter) -> sp_std::fmt::Result {
write!(f, "CheckWeight")
}
#[cfg(not(feature = "std"))]
fn fmt(&self, _: &mut sp_std::fmt::Formatter) -> sp_std::fmt::Result {
Ok(())
}
}
/// Nonce check and increment to give replay protection for transactions.
#[derive(Encode, Decode, Clone, Eq, PartialEq)]
pub struct CheckNonce(#[codec(compact)] T::Index);
impl CheckNonce {
/// utility constructor. Used only in client/factory code.
pub fn from(nonce: T::Index) -> Self {
Self(nonce)
}
}
impl Debug for CheckNonce {
#[cfg(feature = "std")]
fn fmt(&self, f: &mut sp_std::fmt::Formatter) -> sp_std::fmt::Result {
write!(f, "CheckNonce({})", self.0)
}
#[cfg(not(feature = "std"))]
fn fmt(&self, _: &mut sp_std::fmt::Formatter) -> sp_std::fmt::Result {
Ok(())
}
}
impl SignedExtension for CheckNonce where
T::Call: Dispatchable
{
type AccountId = T::AccountId;
type Call = T::Call;
type AdditionalSigned = ();
type Pre = ();
const IDENTIFIER: &'static str = "CheckNonce";
fn additional_signed(&self) -> sp_std::result::Result<(), TransactionValidityError> { Ok(()) }
fn pre_dispatch(
self,
who: &Self::AccountId,
_call: &Self::Call,
_info: &DispatchInfoOf,
_len: usize,
) -> Result<(), TransactionValidityError> {
let mut account = Account::::get(who);
if self.0 != account.nonce {
return Err(
if self.0 < account.nonce {
InvalidTransaction::Stale
} else {
InvalidTransaction::Future
}.into()
)
}
account.nonce += T::Index::one();
Account::::insert(who, account);
Ok(())
}
fn validate(
&self,
who: &Self::AccountId,
_call: &Self::Call,
info: &DispatchInfoOf,
_len: usize,
) -> TransactionValidity {
// check index
let account = Account::::get(who);
if self.0 < account.nonce {
return InvalidTransaction::Stale.into()
}
let provides = vec![Encode::encode(&(who, self.0))];
let requires = if account.nonce < self.0 {
vec![Encode::encode(&(who, self.0 - One::one()))]
} else {
vec![]
};
Ok(ValidTransaction {
priority: info.weight as TransactionPriority,
requires,
provides,
longevity: TransactionLongevity::max_value(),
propagate: true,
})
}
}
impl IsDeadAccount for Module {
fn is_dead_account(who: &T::AccountId) -> bool {
!Account::::contains_key(who)
}
}
/// Check for transaction mortality.
#[derive(Encode, Decode, Clone, Eq, PartialEq)]
pub struct CheckEra(Era, sp_std::marker::PhantomData);
impl CheckEra {
/// utility constructor. Used only in client/factory code.
pub fn from(era: Era) -> Self {
Self(era, sp_std::marker::PhantomData)
}
}
impl Debug for CheckEra {
#[cfg(feature = "std")]
fn fmt(&self, f: &mut sp_std::fmt::Formatter) -> sp_std::fmt::Result {
write!(f, "CheckEra({:?})", self.0)
}
#[cfg(not(feature = "std"))]
fn fmt(&self, _: &mut sp_std::fmt::Formatter) -> sp_std::fmt::Result {
Ok(())
}
}
impl SignedExtension for CheckEra {
type AccountId = T::AccountId;
type Call = T::Call;
type AdditionalSigned = T::Hash;
type Pre = ();
const IDENTIFIER: &'static str = "CheckEra";
fn validate(
&self,
_who: &Self::AccountId,
_call: &Self::Call,
_info: &DispatchInfoOf,
_len: usize,
) -> TransactionValidity {
let current_u64 = >::block_number().saturated_into::();
let valid_till = self.0.death(current_u64);
Ok(ValidTransaction {
longevity: valid_till.saturating_sub(current_u64),
..Default::default()
})
}
fn additional_signed(&self) -> Result {
let current_u64 =