diff --git a/substrate/core/sr-primitives/src/generic/digest.rs b/substrate/core/sr-primitives/src/generic/digest.rs index 1b54f42134..8b3b7163e6 100644 --- a/substrate/core/sr-primitives/src/generic/digest.rs +++ b/substrate/core/sr-primitives/src/generic/digest.rs @@ -23,9 +23,11 @@ use traits::{self, Member, DigestItem as DigestItemT, MaybeHash}; use substrate_primitives::hash::H512 as Signature; +/// Generic header digest. #[derive(PartialEq, Eq, Clone, Encode, Decode)] #[cfg_attr(feature = "std", derive(Debug, Serialize))] pub struct Digest { + /// A list of logs in the digest. pub logs: Vec, } @@ -175,6 +177,7 @@ impl Decode for DigestItem } impl<'a, Hash: Codec + Member, AuthorityId: Codec + Member> DigestItemRef<'a, Hash, AuthorityId> { + /// Cast this digest item into `AuthoritiesChange`. pub fn as_authorities_change(&self) -> Option<&'a [AuthorityId]> { match *self { DigestItemRef::AuthoritiesChange(ref authorities) => Some(authorities), @@ -182,6 +185,7 @@ impl<'a, Hash: Codec + Member, AuthorityId: Codec + Member> DigestItemRef<'a, Ha } } + /// Cast this digest item into `ChangesTrieRoot`. pub fn as_changes_trie_root(&self) -> Option<&'a Hash> { match *self { DigestItemRef::ChangesTrieRoot(ref changes_trie_root) => Some(changes_trie_root), diff --git a/substrate/core/sr-primitives/src/lib.rs b/substrate/core/sr-primitives/src/lib.rs index c0480591cb..22504ba928 100644 --- a/substrate/core/sr-primitives/src/lib.rs +++ b/substrate/core/sr-primitives/src/lib.rs @@ -17,6 +17,8 @@ //! System manager: Handles all of the top-level stuff; executing block/transaction, setting code //! and depositing logs. +#![warn(missing_docs)] + #![cfg_attr(not(feature = "std"), no_std)] #[cfg(feature = "std")] @@ -60,6 +62,7 @@ pub mod traits; pub mod generic; pub mod transaction_validity; +/// Justification type. pub type Justification = Vec; use traits::{Verify, Lazy}; @@ -96,11 +99,15 @@ pub type ChildrenStorageMap = HashMap, StorageMap>; /// Complex storage builder stuff. #[cfg(feature = "std")] pub trait BuildStorage { + /// Hash given slice. + /// + /// Default to xx128 hashing. fn hash(data: &[u8]) -> [u8; 16] { let r = runtime_io::twox_128(data); trace!(target: "build_storage", "{} <= {}", substrate_primitives::hexdisplay::HexDisplay::from(&r), ascii_format(data)); r } + /// Build the storage out of this builder. fn build_storage(self) -> Result<(StorageMap, ChildrenStorageMap), String>; } @@ -118,15 +125,19 @@ pub struct Permill(u32); // TODO: impl Mul for N where N: As impl Permill { + /// Multiplication. pub fn times + ::rstd::ops::Mul + ::rstd::ops::Div>(self, b: N) -> N { // TODO: handle overflows b * >::sa(self.0 as u64) / >::sa(1000000) } + /// Wraps the argument into `Permill` type. pub fn from_millionths(x: u32) -> Permill { Permill(x) } + /// Converts percents into `Permill`. pub fn from_percent(x: u32) -> Permill { Permill(x * 10_000) } + /// Converts a fraction into `Permill`. #[cfg(feature = "std")] pub fn from_fraction(x: f64) -> Permill { Permill((x * 1_000_000.0) as u32) } } diff --git a/substrate/core/sr-primitives/src/testing.rs b/substrate/core/sr-primitives/src/testing.rs index f552600de9..30d04618f9 100644 --- a/substrate/core/sr-primitives/src/testing.rs +++ b/substrate/core/sr-primitives/src/testing.rs @@ -25,6 +25,7 @@ use generic::DigestItem as GenDigestItem; pub use substrate_primitives::{H256, Ed25519AuthorityId}; use substrate_primitives::U256; +/// Authority Id #[derive(Default, PartialEq, Eq, Clone, Decode, Encode, Debug)] #[cfg_attr(feature = "std", derive(Serialize, Deserialize))] pub struct UintAuthorityId(pub u64); @@ -35,17 +36,20 @@ impl Into for UintAuthorityId { } } +/// Converter between u64 and the AuthorityId wrapper type. pub struct ConvertUintAuthorityId; impl Convert for ConvertUintAuthorityId { fn convert(a: u64) -> UintAuthorityId { UintAuthorityId(a) } } - +/// Digest item pub type DigestItem = GenDigestItem; +/// Header Digest #[derive(Default, PartialEq, Eq, Clone, Serialize, Debug, Encode, Decode)] pub struct Digest { + /// Generated logs pub logs: Vec, } @@ -66,14 +70,20 @@ impl traits::Digest for Digest { } } +/// Block Header #[derive(PartialEq, Eq, Clone, Serialize, Debug, Encode, Decode)] #[serde(rename_all = "camelCase")] #[serde(deny_unknown_fields)] pub struct Header { + /// Parent hash pub parent_hash: H256, + /// Block Number pub number: u64, + /// Post-execution state trie root pub state_root: H256, + /// Merkle root of block's extrinsics pub extrinsics_root: H256, + /// Digest items pub digest: Digest, } @@ -123,6 +133,7 @@ impl<'a> Deserialize<'a> for Header { } } +/// An opaque extrinsic wrapper type. #[derive(PartialEq, Eq, Clone, Debug, Encode, Decode)] pub struct ExtrinsicWrapper(Xt); @@ -153,9 +164,12 @@ impl Deref for ExtrinsicWrapper { } } +/// Testing block #[derive(PartialEq, Eq, Clone, Serialize, Debug, Encode, Decode)] pub struct Block { + /// Block header pub header: Header, + /// List of extrinsics pub extrinsics: Vec, } @@ -185,6 +199,7 @@ impl<'a, Xt> Deserialize<'a> for Block where Block: Decode { } } +/// Test transaction #[derive(PartialEq, Eq, Clone, Encode, Decode)] pub struct TestXt(pub Option, pub u64, pub Call); diff --git a/substrate/core/sr-primitives/src/traits.rs b/substrate/core/sr-primitives/src/traits.rs index 623d04a938..e6e74460b3 100644 --- a/substrate/core/sr-primitives/src/traits.rs +++ b/substrate/core/sr-primitives/src/traits.rs @@ -36,6 +36,9 @@ use rstd::ops::{ /// A lazy value. pub trait Lazy { + /// Get a reference to the underlying value. + /// + /// This will compute the value if the function is invoked for the first time. fn get(&mut self) -> &T; } @@ -53,7 +56,9 @@ pub trait Verify { /// Some sort of check on the origin is performed by this object. pub trait EnsureOrigin { + /// A return type. type Success; + /// Perform the origin check. fn ensure_origin(o: OuterOrigin) -> result::Result; } @@ -79,6 +84,7 @@ pub trait StaticLookup { fn lookup(s: Self::Source) -> result::Result; } +/// A lookup implementation returning the input value. #[derive(Default)] pub struct IdentityLookup(PhantomData); impl StaticLookup for IdentityLookup { @@ -162,6 +168,7 @@ macro_rules! impl_numerics { impl_numerics!(u8, u16, u32, u64, u128, usize, i8, i16, i32, i64, i128, isize); +/// A structure that performs identity conversion. pub struct Identity; impl Convert for Identity { fn convert(a: T) -> T { a } @@ -170,13 +177,7 @@ impl Convert for () { fn convert(_: T) -> () { () } } -pub trait RefInto { - fn ref_into(&self) -> &T; -} -impl RefInto for T { - fn ref_into(&self) -> &T { &self } -} - +/// A meta trait for arithmetic. pub trait SimpleArithmetic: Zero + One + IntegerSquareRoot + As + Add + AddAssign + @@ -227,6 +228,7 @@ impl Clear for T { fn clear() -> Self { Default::default() } } +/// A meta trait for all bit ops. pub trait SimpleBitOps: Sized + Clear + rstd::ops::BitOr + @@ -348,6 +350,7 @@ impl Hash for BlakeTwo256 { /// Something that can be checked for equality and printed out to a debug channel if bad. pub trait CheckEqual { + /// Perform the equality check. fn check_equal(&self, other: &Self); } @@ -388,76 +391,79 @@ impl CheckEqual for I where I: DigestItem { } } +/// A type that implements Serialize and Debug when in std environment. #[cfg(feature = "std")] pub trait MaybeSerializeDebugButNotDeserialize: Serialize + Debug {} #[cfg(feature = "std")] impl MaybeSerializeDebugButNotDeserialize for T {} +/// A type that implements Serialize and Debug when in std environment. #[cfg(not(feature = "std"))] pub trait MaybeSerializeDebugButNotDeserialize {} #[cfg(not(feature = "std"))] impl MaybeSerializeDebugButNotDeserialize for T {} +/// A type that implements Serialize when in std environment. #[cfg(feature = "std")] pub trait MaybeSerialize: Serialize {} #[cfg(feature = "std")] impl MaybeSerialize for T {} +/// A type that implements Serialize when in std environment. #[cfg(not(feature = "std"))] pub trait MaybeSerialize {} #[cfg(not(feature = "std"))] impl MaybeSerialize for T {} +/// A type that implements Serialize, DeserializeOwned and Debug when in std environment. #[cfg(feature = "std")] pub trait MaybeSerializeDebug: Serialize + DeserializeOwned + Debug {} #[cfg(feature = "std")] impl MaybeSerializeDebug for T {} +/// A type that implements Serialize, DeserializeOwned and Debug when in std environment. #[cfg(not(feature = "std"))] pub trait MaybeSerializeDebug {} #[cfg(not(feature = "std"))] impl MaybeSerializeDebug for T {} +/// A type that implements Debug when in std environment. #[cfg(feature = "std")] pub trait MaybeDebug: Debug {} #[cfg(feature = "std")] impl MaybeDebug for T {} +/// A type that implements Debug when in std environment. #[cfg(not(feature = "std"))] pub trait MaybeDebug {} #[cfg(not(feature = "std"))] impl MaybeDebug for T {} +/// A type that implements Display when in std environment. #[cfg(feature = "std")] pub trait MaybeDisplay: Display {} #[cfg(feature = "std")] impl MaybeDisplay for T {} +/// A type that implements Display when in std environment. #[cfg(not(feature = "std"))] pub trait MaybeDisplay {} #[cfg(not(feature = "std"))] impl MaybeDisplay for T {} +/// A type that implements Hash when in std environment. #[cfg(feature = "std")] pub trait MaybeHash: ::rstd::hash::Hash {} #[cfg(feature = "std")] impl MaybeHash for T {} +/// A type that implements Hash when in std environment. #[cfg(not(feature = "std"))] pub trait MaybeHash {} #[cfg(not(feature = "std"))] impl MaybeHash for T {} -#[cfg(feature = "std")] -pub trait MaybeDecode: ::codec::Decode {} -#[cfg(feature = "std")] -impl MaybeDecode for T {} - -#[cfg(not(feature = "std"))] -pub trait MaybeDecode {} -#[cfg(not(feature = "std"))] -impl MaybeDecode for T {} - +/// A type that can be used in runtime structures. pub trait Member: Send + Sync + Sized + MaybeDebug + Eq + PartialEq + Clone + 'static {} impl Member for T {} @@ -467,11 +473,16 @@ impl Mem /// /// You can also create a `new` one from those fields. pub trait Header: Clone + Send + Sync + Codec + Eq + MaybeSerializeDebugButNotDeserialize + 'static { + /// Header number. type Number: Member + MaybeSerializeDebug + ::rstd::hash::Hash + Copy + MaybeDisplay + SimpleArithmetic + Codec; + /// Header hash type type Hash: Member + MaybeSerializeDebug + ::rstd::hash::Hash + Copy + MaybeDisplay + Default + SimpleBitOps + Codec + AsRef<[u8]> + AsMut<[u8]>; + /// Hashing algorithm type Hashing: Hash; + /// Digest type type Digest: Digest + Codec; + /// Creates new header. fn new( number: Self::Number, extrinsics_root: Self::Hash, @@ -480,23 +491,34 @@ pub trait Header: Clone + Send + Sync + Codec + Eq + MaybeSerializeDebugButNotDe digest: Self::Digest ) -> Self; + /// Returns a reference to the header number. fn number(&self) -> &Self::Number; + /// Sets the header number. fn set_number(&mut self, Self::Number); + /// Returns a reference to the extrinsics root. fn extrinsics_root(&self) -> &Self::Hash; + /// Sets the extrinsic root. fn set_extrinsics_root(&mut self, Self::Hash); + /// Returns a reference to the state root. fn state_root(&self) -> &Self::Hash; + /// Sets the state root. fn set_state_root(&mut self, Self::Hash); + /// Returns a reference to the parent hash. fn parent_hash(&self) -> &Self::Hash; + /// Sets the parent hash. fn set_parent_hash(&mut self, Self::Hash); + /// Returns a reference to the digest. fn digest(&self) -> &Self::Digest; /// Get a mutable reference to the digest. fn digest_mut(&mut self) -> &mut Self::Digest; + /// Sets the digest. fn set_digest(&mut self, Self::Digest); + /// Returns the hash of the header. fn hash(&self) -> Self::Hash { ::hash_of(self) } @@ -507,14 +529,22 @@ pub trait Header: Clone + Send + Sync + Codec + Eq + MaybeSerializeDebugButNotDe /// /// You can get an iterator over each of the `extrinsics` and retrieve the `header`. pub trait Block: Clone + Send + Sync + Codec + Eq + MaybeSerializeDebugButNotDeserialize + 'static { + /// Type of extrinsics. type Extrinsic: Member + Codec + Extrinsic + MaybeSerialize; + /// Header type. type Header: Header; + /// Block hash type. type Hash: Member + MaybeSerializeDebug + ::rstd::hash::Hash + Copy + MaybeDisplay + Default + SimpleBitOps + Codec + AsRef<[u8]> + AsMut<[u8]>; + /// Returns a reference to the header. fn header(&self) -> &Self::Header; + /// Returns a reference to the list of extrinsics. fn extrinsics(&self) -> &[Self::Extrinsic]; + /// Split the block into header and list of extrinsics. fn deconstruct(self) -> (Self::Header, Vec); + /// Creates new block from header and extrinsics. fn new(header: Self::Header, extrinsics: Vec) -> Self; + /// Returns the hash of the block. fn hash(&self) -> Self::Hash { <::Hashing as Hash>::hash_of(self.header()) } @@ -571,24 +601,32 @@ impl Checkable for T { } /// An "executable" piece of information, used by the standard Substrate Executive in order to -/// enact a piece of extrinsic information by marshalling and dispatching to a named functioon +/// enact a piece of extrinsic information by marshalling and dispatching to a named function /// call. /// /// Also provides information on to whom this information is attributable and an index that allows /// each piece of attributable information to be disambiguated. pub trait Applyable: Sized + Send + Sync { + /// Id of the account that is responsible for this piece of information (sender). type AccountId: Member + MaybeDisplay; + /// Index allowing to disambiguate other `Applyable`s from the same `AccountId`. type Index: Member + MaybeDisplay + SimpleArithmetic; + /// Function call. type Call: Member; + /// Returns a reference to the index if any. fn index(&self) -> Option<&Self::Index>; + /// Returns a reference to the sender if any. fn sender(&self) -> Option<&Self::AccountId>; + /// Deconstructs into function call and sender. fn deconstruct(self) -> (Self::Call, Option); } /// Something that acts like a `Digest` - it can have `Log`s `push`ed onto it and these `Log`s are /// each `Codec`. pub trait Digest: Member + MaybeSerializeDebugButNotDeserialize + Default { + /// Hash of the items. type Hash: Member; + /// Digest item type. type Item: DigestItem; /// Get reference to all digest items. @@ -611,7 +649,9 @@ pub trait Digest: Member + MaybeSerializeDebugButNotDeserialize + Default { /// /// If the runtime does not supports some 'system' items, use `()` as a stub. pub trait DigestItem: Codec + Member + MaybeSerializeDebugButNotDeserialize { + /// `ChangesTrieRoot` payload. type Hash: Member; + /// `AuthorityChange` payload. type AuthorityId: Member + MaybeHash + codec::Encode + codec::Decode; /// Returns Some if the entry is the `AuthoritiesChange` entry. diff --git a/substrate/core/sr-primitives/src/transaction_validity.rs b/substrate/core/sr-primitives/src/transaction_validity.rs index 3e185fea99..4d675a575b 100644 --- a/substrate/core/sr-primitives/src/transaction_validity.rs +++ b/substrate/core/sr-primitives/src/transaction_validity.rs @@ -32,12 +32,33 @@ pub type TransactionTag = Vec; #[derive(Clone, PartialEq, Eq, Encode, Decode)] #[cfg_attr(feature = "std", derive(Debug))] pub enum TransactionValidity { + /// Transaction is invalid. Details are described by the error code. Invalid, + /// Transaction is valid. Valid { + /// Priority of the transaction. + /// + /// Priority determines the ordering of two transactions that have all + /// their dependencies (required tags) satisfied. priority: TransactionPriority, + /// Transaction dependencies + /// + /// A non-empty list signifies that some other transactions which provide + /// given tags are required to be included before that one. requires: Vec, + /// Provided tags + /// + /// A list of tags this transaction provides. Successfuly importing the transaction + /// will enable other transactions that depend on (require) those tags to be included as well. + /// Provided and requried tags allow Substrate to build a dependency graph of transactions + /// and import them in the right (linear) order. provides: Vec, - longevity: TransactionLongevity + /// Transaction longevity + /// + /// Longevity describes minimum number of blocks the validity is correct. + /// After this period transaction should be removed from the pool or revalidated. + longevity: TransactionLongevity, }, + /// Transaction validity can't be determined. Unknown, }