feat: FRAME umbrella crate. (#1337)

### Original PR https://github.com/paritytech/substrate/pull/14137 This PR brings in the first version of the "_`frame` umbrella crate_". This crate is intended to serve two purposes: 1. documentation 2. easier development with frame. Ideally, we want most users to be able to build a frame-based pallet and runtime using just `frame` (plus `scale-codec` and `scale-info`). The crate is not finalized and is not yet intended for external use. Therefore, the version is set to `0.0.1-dev`, this PR is `silent`, and the entire crate is hidden behind the `experimental` flag. The main intention in merging it early on is to be able to iterate on it in the rest of [`developer-hub`](https://github.com/paritytech/polkadot-sdk-docs/) efforts. The public API of the `frame` crate is at the moment as follows: ``` pub mod frame pub use frame::log pub use frame::pallet pub mod frame::arithmetic pub use frame::arithmetic::<<sp_arithmetic::*>> pub use frame::arithmetic::<<sp_arithmetic::traits::*>> pub mod frame::deps pub use frame::deps::codec pub use frame::deps::frame_executive pub use frame::deps::frame_support pub use frame::deps::frame_system pub use frame::deps::scale_info pub use frame::deps::sp_api pub use frame::deps::sp_arithmetic pub use frame::deps::sp_block_builder pub use frame::deps::sp_consensus_aura pub use frame::deps::sp_consensus_grandpa pub use frame::deps::sp_core pub use frame::deps::sp_inherents pub use frame::deps::sp_io pub use frame::deps::sp_offchain pub use frame::deps::sp_runtime pub use frame::deps::sp_std pub use frame::deps::sp_version pub mod frame::derive pub use frame::derive::CloneNoBound pub use frame::derive::Debug pub use frame::derive::Debug pub use frame::derive::DebugNoBound pub use frame::derive::Decode pub use frame::derive::Decode pub use frame::derive::DefaultNoBound pub use frame::derive::Encode pub use frame::derive::Encode pub use frame::derive::EqNoBound pub use frame::derive::PartialEqNoBound pub use frame::derive::RuntimeDebug pub use frame::derive::RuntimeDebugNoBound pub use frame::derive::TypeInfo pub use frame::derive::TypeInfo pub mod frame::prelude pub use frame::prelude::<<frame_support::pallet_prelude::*>> pub use frame::prelude::<<frame_system::pallet_prelude::*>> pub use frame::prelude::<<sp_std::prelude::*>> pub use frame::prelude::CloneNoBound pub use frame::prelude::Debug pub use frame::prelude::Debug pub use frame::prelude::DebugNoBound pub use frame::prelude::Decode pub use frame::prelude::Decode pub use frame::prelude::DefaultNoBound pub use frame::prelude::Encode pub use frame::prelude::Encode pub use frame::prelude::EqNoBound pub use frame::prelude::PartialEqNoBound pub use frame::prelude::RuntimeDebug pub use frame::prelude::RuntimeDebugNoBound pub use frame::prelude::TypeInfo pub use frame::prelude::TypeInfo pub use frame::prelude::frame_system pub mod frame::primitives pub use frame::primitives::BlakeTwo256 pub use frame::primitives::H160 pub use frame::primitives::H256 pub use frame::primitives::H512 pub use frame::primitives::Hash pub use frame::primitives::Keccak256 pub use frame::primitives::U256 pub use frame::primitives::U512 pub mod frame::runtime pub mod frame::runtime::apis pub use frame::runtime::apis::<<frame_system_rpc_runtime_api::*>> pub use frame::runtime::apis::<<sp_api::*>> pub use frame::runtime::apis::<<sp_block_builder::*>> pub use frame::runtime::apis::<<sp_consensus_aura::*>> pub use frame::runtime::apis::<<sp_consensus_grandpa::*>> pub use frame::runtime::apis::<<sp_offchain::*>> pub use frame::runtime::apis::<<sp_session::runtime_api::*>> pub use frame::runtime::apis::<<sp_transaction_pool::runtime_api::*>> pub use frame::runtime::apis::ApplyExtrinsicResult pub use frame::runtime::apis::CheckInherentsResult pub use frame::runtime::apis::InherentData pub use frame::runtime::apis::OpaqueMetadata pub use frame::runtime::apis::impl_runtime_apis pub use frame::runtime::apis::sp_api pub mod frame::runtime::prelude pub use frame::runtime::prelude::<<frame_executive::*>> pub use frame::runtime::prelude::ConstBool pub use frame::runtime::prelude::ConstI128 pub use frame::runtime::prelude::ConstI16 pub use frame::runtime::prelude::ConstI32 pub use frame::runtime::prelude::ConstI64 pub use frame::runtime::prelude::ConstI8 pub use frame::runtime::prelude::ConstU128 pub use frame::runtime::prelude::ConstU16 pub use frame::runtime::prelude::ConstU32 pub use frame::runtime::prelude::ConstU64 pub use frame::runtime::prelude::ConstU8 pub use frame::runtime::prelude::NativeVersion pub use frame::runtime::prelude::RuntimeVersion pub use frame::runtime::prelude::construct_runtime pub use frame::runtime::prelude::create_runtime_str pub use frame::runtime::prelude::derive_impl pub use frame::runtime::prelude::frame_support pub use frame::runtime::prelude::ord_parameter_types pub use frame::runtime::prelude::parameter_types pub use frame::runtime::prelude::runtime_version pub mod frame::runtime::testing_prelude pub use frame::runtime::testing_prelude::BuildStorage pub use frame::runtime::testing_prelude::Storage pub mod frame::runtime::types_common pub type frame::runtime::types_common::AccountId = <<frame::runtime::types_common::Signature as sp_runtime::traits::Verify>::Signer as sp_runtime::traits::IdentifyAccount>::AccountId pub type frame::runtime::types_common::BlockNumber = u32 pub type frame::runtime::types_common::BlockOf<T, Extra> = sp_runtime::generic::block::Block<sp_runtime::generic::header::Header<frame::runtime::types_common::BlockNumber, sp_runtime::traits::BlakeTwo256>, sp_runtime::generic::unchecked_extrinsic::UncheckedExtrinsic<sp_runtime::multiaddress::MultiAddress<frame::runtime::types_common::AccountId, ()>, <T as frame_system::pallet::Config>::RuntimeCall, frame::runtime::types_common::Signature, Extra>> pub type frame::runtime::types_common::OpaqueBlock = sp_runtime::generic::block::Block<sp_runtime::generic::header::Header<frame::runtime::types_common::BlockNumber, sp_runtime::traits::BlakeTwo256>, sp_runtime::OpaqueExtrinsic> pub type frame::runtime::types_common::Signature = sp_runtime::MultiSignature pub type frame::runtime::types_common::SystemSignedExtensionsOf<T> = (frame_system::extensions::check_non_zero_sender::CheckNonZeroSender<T>, frame_system::extensions::check_spec_version::CheckSpecVersion<T>, frame_system::extensions::check_tx_version::CheckTxVersion<T>, frame_system::extensions::check_genesis::CheckGenesis<T>, frame_system::extensions::check_mortality::CheckMortality<T>, frame_system::extensions::check_nonce::CheckNonce<T>, frame_system::extensions::check_weight::CheckWeight<T>) pub mod frame::testing_prelude pub use frame::testing_prelude::<<frame_executive::*>> pub use frame::testing_prelude::<<frame_system::mocking::*>> pub use frame::testing_prelude::BuildStorage pub use frame::testing_prelude::ConstBool pub use frame::testing_prelude::ConstI128 pub use frame::testing_prelude::ConstI16 pub use frame::testing_prelude::ConstI32 pub use frame::testing_prelude::ConstI64 pub use frame::testing_prelude::ConstI8 pub use frame::testing_prelude::ConstU128 pub use frame::testing_prelude::ConstU16 pub use frame::testing_prelude::ConstU32 pub use frame::testing_prelude::ConstU64 pub use frame::testing_prelude::ConstU8 pub use frame::testing_prelude::NativeVersion pub use frame::testing_prelude::RuntimeVersion pub use frame::testing_prelude::Storage pub use frame::testing_prelude::TestState pub use frame::testing_prelude::assert_err pub use frame::testing_prelude::assert_err_ignore_postinfo pub use frame::testing_prelude::assert_error_encoded_size pub use frame::testing_prelude::assert_noop pub use frame::testing_prelude::assert_ok pub use frame::testing_prelude::assert_storage_noop pub use frame::testing_prelude::construct_runtime pub use frame::testing_prelude::create_runtime_str pub use frame::testing_prelude::derive_impl pub use frame::testing_prelude::frame_support pub use frame::testing_prelude::frame_system pub use frame::testing_prelude::if_std pub use frame::testing_prelude::ord_parameter_types pub use frame::testing_prelude::parameter_types pub use frame::testing_prelude::runtime_version pub use frame::testing_prelude::storage_alias pub mod frame::traits pub use frame::traits::<<frame_support::traits::*>> pub use frame::traits::<<sp_runtime::traits::*>> ``` --- The road to full stabilization is - [ ] https://github.com/paritytech/polkadot-sdk/issues/127 - [ ] have a more intentional version bump, as opposed to the current bi weekly force-major-bump - [ ] revise the internal API of `frame`, especially what goes into the `prelude`s. - [ ] migrate all internal pallets and runtime to use `frame` --------- Co-authored-by: kianenigma <kian@parity.io> Co-authored-by: Kian Paimani <5588131+kianenigma@users.noreply.github.com> Co-authored-by: Oliver Tale-Yazdi <oliver.tale-yazdi@parity.io> Co-authored-by: Francisco Aguirre <franciscoaguirreperez@gmail.com>
2026-06-14 16:51:03 +00:00 · 2023-10-27 11:38:16 +02:00
parent 6ca5789db8
commit 43415ef58c
48 changed files with 2019 additions and 192 deletions
@@ -15,21 +15,16 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.

+use crate::common::API_VERSION_ATTRIBUTE;
+use inflector::Inflector;
 use proc_macro2::{Span, TokenStream};
-
+use proc_macro_crate::{crate_name, FoundCrate};
+use quote::{format_ident, quote, ToTokens};
 use syn::{
 	parse_quote, spanned::Spanned, token::And, Attribute, Error, FnArg, GenericArgument, Ident,
 	ImplItem, ItemImpl, Pat, Path, PathArguments, Result, ReturnType, Signature, Type, TypePath,
 };

-use quote::{format_ident, quote};
-
-use proc_macro_crate::{crate_name, FoundCrate};
-
-use crate::common::API_VERSION_ATTRIBUTE;
-
-use inflector::Inflector;
-
 /// Generates the access to the `sc_client` crate.
 pub fn generate_crate_access() -> TokenStream {
 	match crate_name("sp-api") {
@@ -38,10 +33,15 @@ pub fn generate_crate_access() -> TokenStream {
 			let renamed_name = Ident::new(&renamed_name, Span::call_site());
 			quote!(#renamed_name)
 		},
-		Err(e) => {
-			let err = Error::new(Span::call_site(), e).to_compile_error();
-			quote!( #err )
-		},
+		Err(e) =>
+			if let Ok(FoundCrate::Name(name)) = crate_name(&"frame") {
+				let path = format!("{}::deps::{}", name, "sp_api");
+				let path = syn::parse_str::<syn::Path>(&path).expect("is a valid path; qed");
+				quote!( #path )
+			} else {
+				let err = Error::new(Span::call_site(), e).to_compile_error();
+				quote!( #err )
+			},
 	}
 }

@@ -261,8 +261,6 @@ pub fn versioned_trait_name(trait_ident: &Ident, version: u64) -> Ident {
 /// Extract the documentation from the provided attributes.
 #[cfg(feature = "frame-metadata")]
 pub fn get_doc_literals(attrs: &[syn::Attribute]) -> Vec<syn::Lit> {
-	use quote::ToTokens;
-
 	attrs
 		.iter()
 		.filter_map(|attr| {
@@ -942,8 +942,7 @@ pub trait Pair: CryptoType + Sized {
 	///   - the path may be followed by `///`, in which case everything after the `///` is treated
 	/// as a password.
 	/// - If `s` begins with a `/` character it is prefixed with the Substrate public `DEV_PHRASE`
-	///   and
-	/// interpreted as above.
+	///   and interpreted as above.
 	///
 	/// In this case they are interpreted as HDKD junctions; purely numeric items are interpreted as
 	/// integers, non-numeric items as strings. Junctions prefixed with `/` are interpreted as soft
@@ -35,6 +35,12 @@ pub enum Keyring {
 	Dave,
 	Eve,
 	Ferdie,
+	AliceStash,
+	BobStash,
+	CharlieStash,
+	DaveStash,
+	EveStash,
+	FerdieStash,
 	One,
 	Two,
 }
@@ -104,6 +110,12 @@ impl From<Keyring> for &'static str {
 			Keyring::Dave => "Dave",
 			Keyring::Eve => "Eve",
 			Keyring::Ferdie => "Ferdie",
+			Keyring::AliceStash => "Alice//stash",
+			Keyring::BobStash => "Bob//stash",
+			Keyring::CharlieStash => "Charlie//stash",
+			Keyring::DaveStash => "Dave//stash",
+			Keyring::EveStash => "Eve//stash",
+			Keyring::FerdieStash => "Ferdie//stash",
 			Keyring::One => "One",
 			Keyring::Two => "Two",
 		}
@@ -27,9 +27,8 @@ pub mod ed25519;
 #[cfg(feature = "bandersnatch-experimental")]
 pub mod bandersnatch;

-/// Convenience export: Sr25519's Keyring is exposed as `AccountKeyring`,
-/// since it tends to be used for accounts (although it may also be used
-/// by authorities).
+/// Convenience export: Sr25519's Keyring is exposed as `AccountKeyring`, since it tends to be
+/// used for accounts (although it may also be used by authorities).
 pub use sr25519::Keyring as AccountKeyring;

 #[cfg(feature = "bandersnatch-experimental")]
@@ -35,6 +35,12 @@ pub enum Keyring {
 	Dave,
 	Eve,
 	Ferdie,
+	AliceStash,
+	BobStash,
+	CharlieStash,
+	DaveStash,
+	EveStash,
+	FerdieStash,
 	One,
 	Two,
 }
@@ -114,6 +120,12 @@ impl From<Keyring> for &'static str {
 			Keyring::Dave => "Dave",
 			Keyring::Eve => "Eve",
 			Keyring::Ferdie => "Ferdie",
+			Keyring::AliceStash => "Alice//stash",
+			Keyring::BobStash => "Bob//stash",
+			Keyring::CharlieStash => "Charlie//stash",
+			Keyring::DaveStash => "Dave//stash",
+			Keyring::EveStash => "Eve//stash",
+			Keyring::FerdieStash => "Ferdie//stash",
 			Keyring::One => "One",
 			Keyring::Two => "Two",
 		}
@@ -134,16 +134,16 @@ impl<Address: TypeInfo, Call: TypeInfo, Signature: TypeInfo, Extra: SignedExtens
 	}
 }

-impl<Address, AccountId, Call, Signature, Extra, Lookup> Checkable<Lookup>
-	for UncheckedExtrinsic<Address, Call, Signature, Extra>
+impl<LookupSource, AccountId, Call, Signature, Extra, Lookup> Checkable<Lookup>
+	for UncheckedExtrinsic<LookupSource, Call, Signature, Extra>
 where
-	Address: Member + MaybeDisplay,
+	LookupSource: Member + MaybeDisplay,
 	Call: Encode + Member,
 	Signature: Member + traits::Verify,
 	<Signature as traits::Verify>::Signer: IdentifyAccount<AccountId = AccountId>,
 	Extra: SignedExtension<AccountId = AccountId>,
 	AccountId: Member + MaybeDisplay,
-	Lookup: traits::Lookup<Source = Address, Target = AccountId>,
+	Lookup: traits::Lookup<Source = LookupSource, Target = AccountId>,
 {
 	type Checked = CheckedExtrinsic<AccountId, Call, Extra>;

@@ -466,7 +466,7 @@ impl Verify for MultiSignature {
 }

 /// Signature verify that can work with any known signature types..
-#[derive(Eq, PartialEq, Clone, Default, Encode, Decode, RuntimeDebug)]
+#[derive(Eq, PartialEq, Clone, Default, Encode, Decode, RuntimeDebug, TypeInfo)]
 #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
 pub struct AnySignature(H512);

@@ -226,7 +226,7 @@ pub trait StaticLookup {
 }

 /// A lookup implementation returning the input value.
-#[derive(Default)]
+#[derive(Default, Clone, Copy, PartialEq, Eq)]
 pub struct IdentityLookup<T>(PhantomData<T>);
 impl<T: Codec + Clone + PartialEq + Debug + TypeInfo> StaticLookup for IdentityLookup<T> {
 	type Source = T;
@@ -1666,8 +1666,6 @@ impl<AccountId, Call: Dispatchable> SignedExtension for Tuple {
 	}
 }

-/// Only for bare bone testing when you don't care about signed extensions at all.
-#[cfg(feature = "std")]
 impl SignedExtension for () {
 	type AccountId = u64;
 	type AdditionalSigned = ();
@@ -26,28 +26,12 @@ use sp_api::ProvideRuntimeApi;
 #[cfg(feature = "std")]
 use sp_runtime::traits::Block as BlockT;

-use sp_core::{crypto::KeyTypeId, RuntimeDebug};
+use sp_core::RuntimeDebug;
 use sp_staking::SessionIndex;
 use sp_std::vec::Vec;

-sp_api::decl_runtime_apis! {
-	/// Session keys runtime api.
-	pub trait SessionKeys {
-		/// Generate a set of session keys with optionally using the given seed.
-		/// The keys should be stored within the keystore exposed via runtime
-		/// externalities.
-		///
-		/// The seed needs to be a valid `utf8` string.
-		///
-		/// Returns the concatenated SCALE encoded public keys.
-		fn generate_session_keys(seed: Option<Vec<u8>>) -> Vec<u8>;
-
-		/// Decode the given public session keys.
-		///
-		/// Returns the list of public raw public keys + key type.
-		fn decode_session_keys(encoded: Vec<u8>) -> Option<Vec<(Vec<u8>, KeyTypeId)>>;
-	}
-}
+pub mod runtime_api;
+pub use runtime_api::*;

 /// Number of validators in a given session.
 pub type ValidatorCount = u32;
@@ -0,0 +1,38 @@
+// 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.
+
+pub use sp_core::crypto::KeyTypeId;
+use sp_std::prelude::*;
+
+sp_api::decl_runtime_apis! {
+	/// Session keys runtime api.
+	pub trait SessionKeys {
+		/// Generate a set of session keys with optionally using the given seed.
+		/// The keys should be stored within the keystore exposed via runtime
+		/// externalities.
+		///
+		/// The seed needs to be a valid `utf8` string.
+		///
+		/// Returns the concatenated SCALE encoded public keys.
+		fn generate_session_keys(seed: Option<Vec<u8>>) -> Vec<u8>;
+
+		/// Decode the given public session keys.
+		///
+		/// Returns the list of public raw public keys + key type.
+		fn decode_session_keys(encoded: Vec<u8>) -> Option<Vec<(Vec<u8>, sp_core::crypto::KeyTypeId)>>;
+	}
+}
@@ -248,7 +248,25 @@ where
 	}
 }

+/// Implementor of [`WeightToFee`] such that it maps any unit of weight to a fixed fee.
+pub struct FixedFee<const F: u32, T>(sp_std::marker::PhantomData<T>);
+
+impl<const F: u32, T> WeightToFee for FixedFee<F, T>
+where
+	T: BaseArithmetic + From<u32> + Copy + Unsigned,
+{
+	type Balance = T;
+
+	fn weight_to_fee(_: &Weight) -> Self::Balance {
+		F.into()
+	}
+}
+
+/// An implementation of [`WeightToFee`] that collects no fee.
+pub type NoFee<T> = FixedFee<0, T>;
+
 /// Implementor of [`WeightToFee`] that uses a constant multiplier.
+///
 /// # Example
 ///
 /// ```