From d6927c2f3e7ae7e181d00ec572e41439eeedc09c Mon Sep 17 00:00:00 2001 From: Gautam Dhameja Date: Thu, 28 Mar 2019 15:09:44 +0100 Subject: [PATCH] Documentation for system module (#1999) * srml system docs * updated docs * fixed typo * addressed initial review comments * addressed review comments * addressed review comments * minor fixes in docs * Various corrections, punctuation. * updated docs * minor edit * fixed doc test * Update srml/system/src/lib.rs --- substrate/srml/system/src/lib.rs | 114 +++++++++++++++++++++++++++---- 1 file changed, 102 insertions(+), 12 deletions(-) diff --git a/substrate/srml/system/src/lib.rs b/substrate/srml/system/src/lib.rs index 62bdc5156a..cf4dedbca6 100644 --- a/substrate/srml/system/src/lib.rs +++ b/substrate/srml/system/src/lib.rs @@ -14,8 +14,59 @@ // You should have received a copy of the GNU General Public License // along with Substrate. If not, see . -//! System manager: Handles lowest level stuff like depositing logs, basic set up and take down of -//! temporary storage entries, access to old block hashes. +//! # System module +//! +//! The system module provides low-level access to core types and cross-cutting utilities. +//! It acts as the base layer for other SRML modules to interact with the Substrate framework components. +//! To use it in your module, you should ensure your module's trait implies the system [`Trait`]. +//! +//! ## Overview +//! +//! The system module defines the core data types used in a Substrate runtime. +//! It also provides several utility functions (see [`Module`]) for other runtime modules. +//! +//! In addition, it manages the storage items for extrinsics data, indexes, event record 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 +//! +//! All public functions are available as part of the [`Module`] type. +//! +//! ## Usage +//! +//! ### Prerequisites +//! +//! Import the system module and derive your module's configuration trait from the system trait. +//! +//! ### Example - Get random seed and extrinsic count for the current block +//! +//! ``` +//! use srml_support::{decl_module, dispatch::Result}; +//! use srml_system::{self as system, ensure_signed}; +//! +//! pub trait Trait: system::Trait {} +//! +//! decl_module! { +//! pub struct Module for enum Call where origin: T::Origin { +//! pub fn system_module_example(origin) -> Result { +//! let _sender = ensure_signed(origin)?; +//! let _random_seed = >::random_seed(); +//! let _extrinsic_count = >::extrinsic_count(); +//! Ok(()) +//! } +//! } +//! } +//! # fn main() { } +//! ``` #![cfg_attr(not(feature = "std"), no_std)] @@ -60,32 +111,64 @@ impl IsDeadAccount for () { } } -/// Compute the extrinsics root of a list of extrinsics. +/// Compute the trie root of a list of extrinsics. pub fn extrinsics_root(extrinsics: &[E]) -> H::Output { extrinsics_data_root::(extrinsics.iter().map(parity_codec::Encode::encode).collect()) } -/// Compute the extrinsics root of a list of extrinsics. +/// Compute the trie root of a list of extrinsics. pub fn extrinsics_data_root(xts: Vec>) -> H::Output { let xts = xts.iter().map(Vec::as_slice).collect::>(); H::enumerated_trie_root(&xts) } pub trait Trait: 'static + Eq + Clone { + /// The aggregated `Origin` type used by dispatchable calls. type Origin: Into>> + From>; - type Index: Parameter + Member + MaybeSerializeDebugButNotDeserialize + Default + MaybeDisplay + SimpleArithmetic + Copy; - type BlockNumber: Parameter + Member + MaybeSerializeDebug + MaybeDisplay + SimpleArithmetic + Default + Bounded + Copy + rstd::hash::Hash; - type Hash: Parameter + Member + MaybeSerializeDebug + MaybeDisplay + SimpleBitOps + Default + Copy + CheckEqual + rstd::hash::Hash + AsRef<[u8]> + AsMut<[u8]>; + + /// Account index (aka nonce) type. This stores the number of previous transactions associated with a sender + /// account. + type Index: + Parameter + Member + MaybeSerializeDebugButNotDeserialize + Default + MaybeDisplay + SimpleArithmetic + Copy; + + /// The block number type used by the runtime. + type BlockNumber: + Parameter + Member + MaybeSerializeDebug + MaybeDisplay + SimpleArithmetic + Default + Bounded + Copy + + rstd::hash::Hash; + + /// The output of the `Hashing` function. + type Hash: + Parameter + Member + MaybeSerializeDebug + MaybeDisplay + SimpleBitOps + Default + Copy + CheckEqual + + rstd::hash::Hash + AsRef<[u8]> + AsMut<[u8]>; + + /// The hashing system (algorithm) being used in the runtime (e.g. Blake2). type Hashing: Hash; - type Digest: Parameter + Member + MaybeSerializeDebugButNotDeserialize + Default + traits::Digest; + + /// Collection of (light-client-relevant) logs for a block to be included verbatim in the block header. + type Digest: + Parameter + Member + MaybeSerializeDebugButNotDeserialize + Default + traits::Digest; + + /// The user account identifier type for the runtime. type AccountId: Parameter + Member + MaybeSerializeDebug + 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, Digest = Self::Digest >; + + /// The aggregated event type of the runtime. type Event: Parameter + Member + From; + + /// A piece of information which can be part of the digest (as a digest item). type Log: From> + Into>; } @@ -191,7 +274,7 @@ impl From> for primitives::testing::DigestIte } // Create a Hash with 69 for each byte, -// only used to build genesis config +// only used to build genesis config. #[cfg(feature = "std")] fn hash69 + Default>() -> T { let mut h = T::default(); @@ -201,20 +284,27 @@ fn hash69 + Default>() -> T { decl_storage! { trait Store for Module as System { - + /// Extrinsics nonce for accounts. pub AccountNonce get(account_nonce): map T::AccountId => T::Index; - + /// Total extrinsics count for the current block. ExtrinsicCount: 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(block_hash) build(|_| vec![(T::BlockNumber::zero(), hash69())]): map T::BlockNumber => T::Hash; + /// Extrinsics data for the current block (maps extrinsic's index to its data). ExtrinsicData get(extrinsic_data): map u32 => Vec; + /// Random seed of the current block. RandomSeed get(random_seed) build(|_| T::Hash::default()): T::Hash; /// The current block number being processed. Set by `execute_block`. Number get(block_number) build(|_| T::BlockNumber::sa(1u64)): T::BlockNumber; + /// Hash of the previous block. ParentHash get(parent_hash) build(|_| hash69()): T::Hash; + /// Extrinsics root of the current block, also part of the block header. ExtrinsicsRoot get(extrinsics_root): T::Hash; + /// Digest of the current block, also part of the block header. Digest get(digest): T::Digest; - + /// Events deposited for the current block. Events get(events): Vec>; } add_extra_genesis {