Module developer_hub::polkadot_sdk::frame_runtime

source ·
Expand description

Learn about FRAME, the framework used to build Substrate runtimes.

FRAME

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

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

Introduction

As described in crate::reference_docs::wasm_meta_protocol, at a high-level substrate-based blockchains are composed of two parts:

  1. A runtime which represents the state transition function (i.e. “Business Logic”) of a blockchain, and is encoded as a Wasm blob.
  2. A client whose primary purpose is to execute the given runtime.
graph TB
subgraph Substrate
	direction LR
	subgraph Client
	end
	subgraph Runtime
	end
end

FRAME is the Substrate’s framework of choice to build a runtime.

FRAME is composed of two major components, pallets and a runtime.

Pallets

A pallet is a unit of encapsulated logic. It has a clearly defined responsibility and can be linked to other pallets. Each pallet should try to only care about its own responsibilities and make as few assumptions about the general runtime as possible. A pallet is analogous to a module in the runtime.

A pallet is defined as a mod pallet wrapped by the [frame::pallet] macro. Within this macro, pallet components/parts can be defined. Most notable of these parts are:

  • Config, allowing a pallet to make itself configurable and generic over types, values and such.
  • Storage, allowing a pallet to define onchain storage.
  • Dispatchable function aka. Extrinsics, allowing a pallet to define extrinsics that are callable by end users, from the outer world.
  • Events, allowing a pallet to emit events.
  • Errors, allowing a pallet to emit well-formed errors.

Most of these components are defined using macros, the full list of which can be found in frame::pallet_macros.

Example

The following examples showcases a minimal pallet.

ⓘ
#[frame::pallet(dev_mode)]
pub mod pallet {
	use super::*;

	#[pallet::config]
	pub trait Config: frame_system::Config {
		type RuntimeEvent: IsType<<Self as frame_system::Config>::RuntimeEvent>
			+ From<Event<Self>>;
	}

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

	#[pallet::event]
	pub enum Event<T: Config> {}

	#[pallet::storage]
	pub type Value<T> = StorageValue<Value = u32>;

	#[pallet::call]
	impl<T: Config> Pallet<T> {
		pub fn some_dispatchable(_origin: OriginFor<T>) -> DispatchResult {
			Ok(())
		}
	}
}

A runtime is a collection of pallets that are amalgamated together. Each pallet typically has some configurations (exposed as a trait Config) that needs to be specified in the runtime. This is done with [frame::runtime::prelude::construct_runtime].

A (real) runtime that actually wishes to compile to WASM needs to also implement a set of runtime-apis. These implementation can be specified using the [frame::runtime::prelude::impl_runtime_apis] macro.

Example

The following example shows a (test) runtime that is composing the pallet demonstrated above, next to the [frame::prelude::frame_system] pallet, into a runtime.

ⓘ
pub mod runtime {
	use super::pallet as pallet_example;
	use frame::{prelude::*, testing_prelude::*};

	construct_runtime!(
		pub struct Runtime {
			System: frame_system,
			Example: pallet_example,
		}
	);

	#[derive_impl(frame_system::config_preludes::TestDefaultConfig as frame_system::DefaultConfig)]
	impl frame_system::Config for Runtime {
		type Block = MockBlock<Self>;
	}

	impl pallet_example::Config for Runtime {
		type RuntimeEvent = RuntimeEvent;
	}
}

More Examples

You can find more FRAME examples that revolve around specific features at [pallet_examples].

Alternatives 🌈

There is nothing in the Substrate’s client side code-base that mandates the use of FRAME. While FRAME makes it very simple to write Substrate-based runtimes, it is by no means intended to be the only one. At the end of the day, any WASM blob that exposes the right set of runtime APIs is a valid Runtime form the point of view of a Substrate cliemt (see crate::reference_docs::wasm_meta_protocol). Notable examples are: