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-13 02:21:14 +00:00 · 2023-10-27 11:38:16 +02:00
parent 6ca5789db8
commit 43415ef58c
48 changed files with 2019 additions and 192 deletions
@@ -0,0 +1,347 @@
+// 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.
+
+//! > Made for [![polkadot]](https://polkadot.network)
+//!
+//! [polkadot]: https://img.shields.io/badge/polkadot-E6007A?style=for-the-badge&logo=polkadot&logoColor=white
+//!
+//! # FRAME
+//!
+//! ```no_compile
+//!   ______   ______    ________   ___ __ __   ______
+//!  /_____/\ /_____/\  /_______/\ /__//_//_/\ /_____/\
+//!  \::::_\/_\:::_ \ \ \::: _  \ \\::\| \| \ \\::::_\/_
+//!   \:\/___/\\:(_) ) )_\::(_)  \ \\:.      \ \\:\/___/\
+//!    \:::._\/ \: __ `\ \\:: __  \ \\:.\-/\  \ \\::___\/_
+//!     \:\ \    \ \ `\ \ \\:.\ \  \ \\. \  \  \ \\:\____/\
+//!      \_\/     \_\/ \_\/ \__\/\__\/ \__\/ \__\/ \_____\/
+//! ```
+//!
+//! > **F**ramework for **R**untime **A**ggregation of **M**odularized **E**ntities: Substrate's
+//! > State Transition Function (Runtime) Framework.
+//!
+//! ## Warning: Experimental
+//!
+//! This crate and all of its content is experimental, and should not yet be used in production.
+//!
+//! ## Getting Started
+//!
+//! TODO: link to `developer_hub::polkadot_sdk::frame`. The `developer_hub` hasn't been published
+//! yet, this can be updated once it is linkable.
+
+#![cfg_attr(not(feature = "std"), no_std)]
+#![cfg(feature = "experimental")]
+
+/// Exports the main pallet macro. This can wrap a `mod pallet` and will transform it into
+/// being a pallet, eg `#[frame::pallet] mod pallet { .. }`.
+///
+/// Note that this is not part of the prelude, in order to make it such that the common way to
+/// define a macro is `#[frame::pallet] mod pallet { .. }`, followed by `#[pallet::foo]`,
+/// `#[pallet::bar]` inside the mod.
+pub use frame_support::pallet;
+
+/// The logging library of the runtime. Can normally be the classic `log` crate.
+pub use log;
+
+/// The main prelude of FRAME.
+///
+/// This prelude should almost always be the first line of code in any pallet or runtime.
+///
+/// ```
+/// use frame::prelude::*;
+///
+/// // rest of your pallet..
+/// mod pallet {}
+/// ```
+pub mod prelude {
+	/// `frame_system`'s parent crate, which is mandatory in all pallets build with this crate.
+	///
+	/// Conveniently, the keyword `frame_system` is in scope as one uses `use
+	/// frame::prelude::*`
+	#[doc(inline)]
+	pub use frame_system;
+
+	/// Pallet prelude of `frame-support`.
+	///
+	/// Note: this needs to revised once `frame-support` evolves.
+	// `frame-support` will be break down https://github.com/paritytech/polkadot-sdk/issues/127 and its reexports will
+	// most likely change. These wildcard reexportings can be optimized once `frame-support` has
+	// changed.
+	#[doc(no_inline)]
+	pub use frame_support::pallet_prelude::*;
+
+	/// Pallet prelude of `frame-system`.
+	#[doc(no_inline)]
+	pub use frame_system::pallet_prelude::*;
+
+	/// All of the std alternative types.
+	#[doc(no_inline)]
+	pub use sp_std::prelude::*;
+
+	/// All FRAME-relevant derive macros.
+	#[doc(no_inline)]
+	pub use super::derive::*;
+}
+
+/// The main testing prelude of FRAME.
+///
+/// A test setup typically starts with:
+///
+/// ```
+/// use frame::testing_prelude::*;
+/// // rest of your test setup.
+/// ```
+#[cfg(feature = "std")]
+pub mod testing_prelude {
+	pub use super::prelude::*;
+	/// Testing includes building a runtime, so we bring in all preludes related to runtimes as
+	/// well.
+	pub use super::runtime::testing_prelude::*;
+
+	/// Other helper macros from `frame_support` that help with asserting in tests.
+	pub use frame_support::{
+		assert_err, assert_err_ignore_postinfo, assert_error_encoded_size, assert_noop, assert_ok,
+		assert_storage_noop, storage_alias,
+	};
+
+	pub use frame_system::{self, mocking::*};
+	pub use sp_io::TestExternalities as TestState;
+	pub use sp_std::if_std;
+}
+
+/// All of the types and tools needed to build FRAME-based runtimes.
+#[cfg(any(feature = "runtime", feature = "std"))]
+pub mod runtime {
+	/// The main prelude of `FRAME` for building runtimes.
+	///
+	/// A runtime typically starts with:
+	///
+	/// ```
+	/// use frame::{prelude::*, runtime::prelude::*};
+	/// ```
+	pub mod prelude {
+		/// All of the types related to the FRAME runtime executive.
+		pub use frame_executive::*;
+
+		/// Macro to amalgamate the runtime into `struct Runtime`.
+		pub use frame_support::construct_runtime;
+
+		/// Macro to easily derive the `Config` trait of various pallet for `Runtime`.
+		pub use frame_support::derive_impl;
+
+		/// Macros to easily impl traits such as `Get` for types.
+		// TODO: using linking in the Get in the line above triggers an ICE :/
+		pub use frame_support::{ord_parameter_types, parameter_types};
+
+		/// Const types that can easily be used in conjuncture with `Get`.
+		pub use frame_support::traits::{
+			ConstBool, ConstI128, ConstI16, ConstI32, ConstI64, ConstI8, ConstU128, ConstU16,
+			ConstU32, ConstU64, ConstU8,
+		};
+
+		/// Types to define your runtime version.
+		pub use sp_version::{create_runtime_str, runtime_version, RuntimeVersion};
+
+		#[cfg(feature = "std")]
+		pub use sp_version::NativeVersion;
+	}
+
+	/// Types and traits for runtimes that implement runtime APIs.
+	///
+	/// A testing runtime should not need this.
+	///
+	/// A non-testing runtime should have this enabled, as such:
+	///
+	/// ```
+	/// use frame::runtime::{prelude::*, apis::{*,}};
+	/// ```
+	// TODO: This is because of wildcard imports, and it should be not needed once we can avoid
+	// that. Imports like that are needed because we seem to need some unknown types in the macro
+	// expansion. See `sp_session::runtime_api::*;` as one example. All runtime api decls should be
+	// moved to file similarly.
+	#[allow(ambiguous_glob_reexports)]
+	pub mod apis {
+		// Types often used in the runtime APIs.
+		pub use sp_core::OpaqueMetadata;
+		pub use sp_inherents::{CheckInherentsResult, InherentData};
+		pub use sp_runtime::ApplyExtrinsicResult;
+
+		/// Macro to implement runtime APIs.
+		pub use sp_api::impl_runtime_apis;
+
+		pub use frame_system_rpc_runtime_api::*;
+		pub use sp_api::{self, *};
+		pub use sp_block_builder::*;
+		pub use sp_consensus_aura::*;
+		pub use sp_consensus_grandpa::*;
+		pub use sp_offchain::*;
+		pub use sp_session::runtime_api::*;
+		pub use sp_transaction_pool::runtime_api::*;
+	}
+
+	/// A set of opinionated types aliases commonly used in runtimes.
+	///
+	/// This is one set of opinionated types. They are compatible with one another, but are not
+	/// guaranteed to work if you start tweaking a portion.
+	///
+	/// Some note-worthy opinions in this prelude:
+	///
+	/// - `u32` block number.
+	/// - [`sp_runtime::MultiAddress`] and [`sp_runtime::MultiSignature`] are used as the account id
+	///   and signature types. This implies that this prelude can possibly used with an
+	///   "account-index" system (eg `pallet-indices`). And, in any case, it should be paired with
+	///   `AccountIdLookup` in [`frame_system::Config::Lookup`].
+	pub mod types_common {
+		use frame_system::Config as SysConfig;
+		use sp_runtime::{generic, traits, OpaqueExtrinsic};
+
+		/// A signature type compatible capably of handling multiple crypto-schemes.
+		pub type Signature = sp_runtime::MultiSignature;
+
+		/// The corresponding account-id type of [`Signature`].
+		pub type AccountId =
+			<<Signature as traits::Verify>::Signer as traits::IdentifyAccount>::AccountId;
+
+		/// The block-number type, which should be fed into [`frame_system::Config`].
+		pub type BlockNumber = u32;
+
+		/// TODO: Ideally we want the hashing type to be equal to SysConfig::Hashing?
+		type HeaderInner = generic::Header<BlockNumber, traits::BlakeTwo256>;
+
+		// NOTE: `AccountIndex` is provided for future compatibility, if you want to introduce
+		// something like `pallet-indices`.
+		type ExtrinsicInner<T, Extra, AccountIndex = ()> = generic::UncheckedExtrinsic<
+			sp_runtime::MultiAddress<AccountId, AccountIndex>,
+			<T as SysConfig>::RuntimeCall,
+			Signature,
+			Extra,
+		>;
+
+		/// The block type, which should be fed into [`frame_system::Config`].
+		///
+		/// Should be parameterized with `T: frame_system::Config` and a tuple of `SignedExtension`.
+		/// When in doubt, use [`SystemSignedExtensionsOf`].
+		// Note that this cannot be dependent on `T` for block-number because it would lead to a
+		// circular dependency (self-referential generics).
+		pub type BlockOf<T, Extra = ()> = generic::Block<HeaderInner, ExtrinsicInner<T, Extra>>;
+
+		/// The opaque block type. This is the same [`BlockOf`], but it has
+		/// [`sp_runtime::OpaqueExtrinsic`] as its final extrinsic type.
+		///
+		/// This should be provided to the client side as the extrinsic type.
+		pub type OpaqueBlock = generic::Block<HeaderInner, OpaqueExtrinsic>;
+
+		/// Default set of signed extensions exposed from the `frame_system`.
+		///
+		/// crucially, this does NOT contain any tx-payment extension.
+		pub type SystemSignedExtensionsOf<T> = (
+			frame_system::CheckNonZeroSender<T>,
+			frame_system::CheckSpecVersion<T>,
+			frame_system::CheckTxVersion<T>,
+			frame_system::CheckGenesis<T>,
+			frame_system::CheckEra<T>,
+			frame_system::CheckNonce<T>,
+			frame_system::CheckWeight<T>,
+		);
+	}
+
+	/// The main prelude of FRAME for building runtimes, and in the context of testing.
+	///
+	/// counter part of `runtime::prelude`.
+	#[cfg(feature = "std")]
+	pub mod testing_prelude {
+		pub use super::prelude::*;
+		pub use sp_core::storage::Storage;
+		pub use sp_runtime::BuildStorage;
+	}
+}
+
+/// All traits often used in FRAME pallets.
+///
+/// Note that types implementing these traits can also be found in this module.
+// TODO: `Hash` and `Bounded` are defined multiple times; should be fixed once these two crates are
+// cleaned up.
+#[allow(ambiguous_glob_reexports)]
+pub mod traits {
+	pub use frame_support::traits::*;
+	pub use sp_runtime::traits::*;
+}
+
+/// The arithmetic types used for safe math.
+pub mod arithmetic {
+	pub use sp_arithmetic::{traits::*, *};
+}
+
+/// Low level primitive types used in FRAME pallets.
+pub mod primitives {
+	pub use sp_core::{H160, H256, H512, U256, U512};
+	pub use sp_runtime::traits::{BlakeTwo256, Hash, Keccak256};
+}
+
+/// All derive macros used in frame.
+///
+/// This is already part of the [`prelude`].
+pub mod derive {
+	pub use frame_support::{
+		CloneNoBound, DebugNoBound, DefaultNoBound, EqNoBound, PartialEqNoBound,
+		RuntimeDebugNoBound,
+	};
+	pub use parity_scale_codec::{Decode, Encode};
+	pub use scale_info::TypeInfo;
+	pub use sp_runtime::RuntimeDebug;
+	pub use sp_std::fmt::Debug;
+}
+
+/// Access to all of the dependencies of this crate. In case the re-exports are not enough, this
+/// module can be used.
+///
+/// Any time one uses this module to access a dependency, you can have a moment to think about
+/// whether this item could have been placed in any of the other modules and preludes in this crate.
+/// In most cases, hopefully the answer is yes.
+pub mod deps {
+	// TODO: It would be great to somehow instruct RA to prefer *not* suggesting auto-imports from
+	// these. For example, we prefer `frame::derive::CloneNoBound` rather than
+	// `frame::deps::frame_support::CloneNoBound`.
+	pub use frame_support;
+	pub use frame_system;
+
+	pub use sp_arithmetic;
+	pub use sp_core;
+	pub use sp_io;
+	pub use sp_runtime;
+	pub use sp_std;
+
+	pub use parity_scale_codec as codec;
+	pub use scale_info;
+
+	#[cfg(feature = "runtime")]
+	pub use frame_executive;
+	#[cfg(feature = "runtime")]
+	pub use sp_api;
+	#[cfg(feature = "runtime")]
+	pub use sp_block_builder;
+	#[cfg(feature = "runtime")]
+	pub use sp_consensus_aura;
+	#[cfg(feature = "runtime")]
+	pub use sp_consensus_grandpa;
+	#[cfg(feature = "runtime")]
+	pub use sp_inherents;
+	#[cfg(feature = "runtime")]
+	pub use sp_offchain;
+	#[cfg(feature = "runtime")]
+	pub use sp_version;
+}