Crate polkadot_sdk_frame

FRAME

  ______   ______    ________   ___ __ __   ______
 /_____/\ /_____/\  /_______/\ /__//_//_/\ /_____/\
 \::::_\/_\:::_ \ \ \::: _  \ \\::\| \| \ \\::::_\/_
  \:\/___/\\:(_) ) )_\::(_)  \ \\:.      \ \\:\/___/\
   \:::._\/ \: __ `\ \\:: __  \ \\:.\-/\  \ \\::___\/_
    \:\ \    \ \ `\ \ \\:.\ \  \ \\. \  \  \ \\:\____/\
     \_\/     \_\/ \_\/ \__\/\__\/ \__\/ \__\/ \_____\/

Framework for Runtime Aggregation of Modularized Entities: Substrate’s State Transition Function (Runtime) Framework.

Usage

This crate is organized into 3 stages:

1. preludes: prelude, testing_prelude and runtime::prelude, benchmarking, weights_prelude, try_runtime.
2. domain-specific modules: traits, hashing, arithmetic and derive.
3. Accessing frame/substrate dependencies directly: deps.

The main intended use of this crate is for it to be used with the former, preludes:

use polkadot_sdk_frame as frame;
#[frame::pallet]
pub mod pallet {
	use frame::prelude::*;
	// ^^ using the prelude!

	#[pallet::config]
	pub trait Config: frame_system::Config {}

	#[pallet::pallet]
	pub struct Pallet<T>(_);
}

#[cfg(test)]
pub mod tests {
	use frame::testing_prelude::*;
}

#[cfg(feature = "runtime-benchmarks")]
pub mod benchmarking {
	use frame::benchmarking::prelude::*;
}

pub mod runtime {
	use frame::runtime::prelude::*;
}

If not in preludes, one can look into the domain-specific modules. Finally, if an import is still not feasible, one can look into deps.

This crate also uses a runtime feature to include all of the types and tools needed to build FRAME-based runtimes. So, if you want to build a runtime with this, import it as

polkadot-sdk-frame = { version = "foo", features = ["runtime"] }

If you just want to build a pallet instead, import it as

polkadot-sdk-frame = { version = "foo" }

Notice that the preludes overlap since they have imports in common. More in detail:

• testing_prelude brings in frame prelude and runtime::prelude;
• runtime::prelude brings in frame prelude;
• benchmarking brings in frame prelude.

Naming

Please note that this crate can only be imported as polkadot-sdk-frame or frame. This is due to compatibility matters with frame-support.

A typical pallet’s Cargo.toml using this crate looks like:

[dependencies]
codec = { features = ["max-encoded-len"], workspace = true }
scale-info = { features = ["derive"], workspace = true }
frame = { workspace = true, features = ["experimental", "runtime"] }

[features]
default = ["std"]
std = [
	"codec/std",
	"scale-info/std",
	"frame/std",
]
runtime-benchmarks = [
	"frame/runtime-benchmarks",
]
try-runtime = [
	"frame/try-runtime",
]

Documentation

See polkadot_sdk::frame.

WARNING: Experimental

This crate and all of its content is experimental, and should not yet be used in production.

Maintenance Note

Notes for the maintainers of this crate, describing how the re-exports and preludes should work.

• Preludes should be extensive. The goal of this pallet is to be ONLY used with the preludes. The domain-specific modules are just a backup, aiming to keep things organized. Don’t hesitate in adding more items to the main prelude.
• The only non-module, non-prelude items exported from the top level crate is the pallet macro, such that we can have the #[frame::pallet] mod pallet { .. } syntax working.
• In most cases, you might want to create a domain-specific module, but also add it to the preludes, such as hashing.
• The only items that should NOT be in preludes are those that have been placed in frame-support/sp-runtime, but in truth are related to just one pallet.
• The currency related traits are kept out of the preludes to encourage a deliberate choice of one over the other.
• runtime::apis should expose all common runtime APIs that all FRAME-based runtimes need.

Re-exports

• pub use frame_support::pallet;
• pub use frame_support::pallet_macros::import_section;
• pub use frame_support::pallet_macros::pallet_section;
• pub use log;

Modules

• arithmetic
  The arithmetic types used for safe math.
• benchmarking
  Prelude to be included in the benchmarking.rs of a pallet.
• deps
  Access to all of the dependencies of this crate. In case the prelude re-exports are not enough, this module can be used.
• derive
  All derive macros used in frame.
• hashing
• pallet_macros
  Macros used within the main pallet macro.
• prelude
  The main prelude of FRAME.
• runtime
  All of the types and tools needed to build FRAME-based runtimes.
• testing_prelude
  The main testing prelude of FRAME.
• traits
  All traits often used in FRAME pallets.
• try_runtime
• weights_prelude
  Prelude to be included in the weight.rs of each pallet.

Attribute Macros

• storage_alias

  ---