FRAME

The Framework for Runtime Aggregation of Modularized Entities (FRAME) is a set of modules and support libraries that simplify runtime development. In Substrate, these modules are called Pallets, each hosting domain-specific logic to include in a chain's runtime.

FRAME also provides some helper modules to interact with important Substrate Primitives that provide the interface to the core client.

The following diagram shows the architectural overview of FRAME and its support libraries:

FRAME Architecture

Pallets

When building with FRAME, the Substrate runtime is composed of several smaller components called pallets. A pallet contains a set of types, storage items, and functions that define a set of features and functionality for a runtime.

FRAME Runtime

Tip

If you are just getting started with Substrate runtime development, we suggest you try our introductory tutorial for creating your first Substrate chain.

FRAME not only provides a library of commonly used Substrate pallets but also a framework to build custom domain-specific pallets, giving runtime engineers the flexibility to define their runtime's behaviour according to their target use case. The result is each pallet has its own discrete logic which can modify the features and functionality of your blockchain's state transition functions.

For example, the Balances pallet, which is included in FRAME, defines cryptocurrency capabilities for your blockchain. More specifically, it defines:

Storage items that keep track of the tokens a user owns.
Functions that users can call to transfer and manage those tokens.
APIs which allow other pallets to make use of those tokens and their capabilities.
Hooks which allow other pallets to trigger function calls when a user's balance changes.

Substrate runtime engineers can define custom logics for their blockchain by writing their own pallets and encapsulating their blockchains desired functionality by combining custom pallets with existing FRAME pallets or Substrate modules alike. The following documentation will show you how.

Skeleton of a pallet

A FRAME pallet is composed of 7 sections:

Imports and Dependencies
Declaration of the Pallet type
Runtime Configuration Trait
Runtime Storage
Runtime Events
Hooks
Extrinsics

An example is as follows:

// 1. Imports and Dependencies
pub use pallet::*;
#[frame_support::pallet]
pub mod pallet {
    use frame_support::pallet_prelude::*;
    use frame_system::pallet_prelude::*;

    // 2. Declaration of the Pallet type
    // This is a placeholder to implement traits and methods.
    #[pallet::pallet]
    #[pallet::generate_store(pub(super) trait Store)]
    pub struct Pallet<T>(PhantomData<T>);

    // 3. Runtime Configuration Trait
    // All types and constants go here.
    // Use #[pallet::constant] and #[pallet::extra_constants]
    // to pass in values to metadata.
    #[pallet::config]
    pub trait Config: frame_system::Config { ... }

    // 4. Runtime Storage
    // Use to declare storage items.
    #[pallet::storage]
    #[pallet::getter(fn something)]
    pub MyStorage<T: Config> = StorageValue<_, u32>;

    // 5. Runtime Events
    // Can stringify event types to metadata.
    #[pallet::event]
    #[pallet::generate_deposit(pub(super) fn deposit_event)]
    pub enum Event<T: Config> { ... }

    // 6. Hooks
    // Define some logic that should be executed
    // regularly in some context, for e.g. on_initialize.
    #[pallet::hooks]
    impl<T: Config> Hooks<BlockNumberFor<T>> for Pallet<T> { ... }

    // 7. Extrinsics
    // Functions that are callable from outside the runtime.
    #[pallet::call]
    impl<T:Config> Pallet<T> { ... }

}

Note

Pallets can be composed of as many sections as needed, giving runtime engineers a lot of flexibility on top of the basic skeletons depicted above. Refer to the Substrate Runtime Macros to learn more about adding functionality to a FRAME pallet.

System crate

The FRAME System crate frame_system provides low-level types, storage, and functions for your blockchain. All other pallets depend on the System crate as the basis of your Substrate runtime.

The System crate defines all the core types for the Substrate runtime, such as:

Origin
Block Number
Account Id
Hash
Header
Version
etc...

It also has a number of system-critical storage items, such as:

Account Nonce
Block Hash
Block Number
Events
etc...

Finally, it defines a number of low level functions which can access your blockchain storage, verify the origin of an extrinsic, and more.

Support crate

The FRAME Support Crate frame_support is a collection of Rust macros, types, traits, and modules that simplify the development of Substrate pallets.

The support macros expanded at compile time generate boilerplate code needed for the common structure of a pallet and save developers from writing them repeatedly.

Executive pallet

The FRAME Executive Pallet frame_executive acts as the orchestration layer for the runtime. It dispatches incoming extrinsic calls to the respective pallets in the runtime.

Runtime

The runtime library brings together all these components and pallets. It defines which pallets are included with your runtime and configures them to work together to compose your final runtime. When calls are made to your runtime, it uses the Executive pallet to dispatch those calls to the individual pallets.

Prebuilt pallets

Some pallets will be sufficiently general-purpose to be reused in many blockchains. Anyone is free to write and share useful pallets. There is a collection of popular pallets provided with Substrate. Let's explore them.

Assets

The Assets pallet is a simple, secure module for dealing with fungible assets.

Atomic Swap

A module for atomically sending funds from an origin to a target. A proof is used to allow the target to approve (claim) the swap. If the swap is not claimed within a specified duration of time, the sender may cancel it.

Aura

The Aura pallet extends Aura consensus by managing offline reporting.

Authority Discovery

The Authority Discovery pallet is used by core/authority-discovery to retrieve the current set of authorities, learn its own authority ID, as well as to sign and verify messages to and from other authorities.

Authorship

The Authorship pallet tracks the current author of the block and recent uncles.

BABE

The BABE pallet extends BABE consensus by collecting on-chain randomness from VRF outputs and managing epoch transitions.

Balances

The Balances pallet provides functionality for handling accounts and balances.

Benchmark

A pallet that contains common runtime patterns in an isolated manner. This pallet is not meant to be used in a production blockchain, just for benchmarking and testing purposes.

Collective

The Collective pallet allows a set of account IDs to make their collective feelings known through dispatched calls from specialized origins.

Contracts

The Contracts pallet provides functionality for the runtime to deploy and execute WebAssembly smart-contracts.

Democracy

The Democracy pallet provides a democratic system that handles administration of general stakeholder voting.

Elections Phragmén

The Phragmén Elections pallet is an election module based on sequential Phragmén.

Elections

WARNING: NOT ACTIVELY MAINTAINED The Elections pallet is an election module for stake-weighted membership selection of a collective.

Example Offchain Worker

The Offchain Worker Example: A simple pallet demonstrating concepts, APIs and structures common to most offchain workers.

Example

The Example pallet is a simple example of a pallet demonstrating concepts, APIs, and structures common to most pallets.

GRANDPA

The GRANDPA pallet extends GRANDPA consensus by managing the GRANDPA authority set ready for the native code.

Identity

A federated naming system, allowing for multiple registrars to be added from a specified origin. Registrars can set a fee to provide identity-verification service. Anyone can put forth a proposed identity for a fixed deposit and ask for review by any number of registrars (paying each of their fees). Registrar judgements are given as an enum, allowing for sophisticated, multi-tier opinions.

I'm Online

The I'm Online pallet allows validators to gossip a heartbeat transaction with each new session to signal that the node is online.

Indices

The Indices pallet allocates indices for newly created accounts. An index is a short form of an address.

Membership

The Membership pallet allows control of membership of a set of AccountIds, useful for managing membership of a collective.

Multisig

A module for doing multi-signature dispatches.

Nicks

Nicks is a trivial module for keeping track of account names on-chain. It makes no effort to create a name hierarchy, be a DNS replacement, or provide reverse lookups.

Offences

The Offences pallet tracks reported offences.

Proxy

A module allowing accounts to give permission to other accounts to dispatch types of calls from their signed origin.

Randomness Collective Flip

The Randomness Collective Flip pallet provides a random function that can be used in tests and generates low-influence random values based on the block hashes from the previous 81 blocks. This pallet is not intended for use in production.

Recovery

The Recovery pallet is an M-of-N social recovery tool for users to gain access to their accounts if the private key or other authentication mechanism is lost. Through this pallet, a user is able to make calls on-behalf-of another account which they have recovered. The recovery process is protected by trusted "friends" whom the original account owner chooses. A threshold (M) out of N friends are needed to give another account access to the recoverable account.

Scheduler

This module exposes capabilities for scheduling dispatches to occur at a specified block number or at a specified period. These scheduled dispatches may be named or anonymous and may be canceled.

Scored Pool

The Scored Pool pallet maintains a scored membership pool where the highest scoring entities are made members.

Session

The Session pallet allows validators to manage their session keys, provides a function for changing the session length, and handles session rotation.

Society

The Society module is an economic game which incentivizes users to participate and maintain a membership society.

Staking

The Staking pallet is used to manage funds at stake by network maintainers.

Sudo

The Sudo pallet allows for a single account (called the "sudo key") to execute dispatchable functions that require a Root origin or designate a new account to replace them as the sudo key.

Timestamp

The Timestamp pallet provides functionality to get and set the on-chain time.

Transaction Payment

The Transaction Payment pallet provides the basic logic to compute pre-dispatch transaction fees.

Treasury

The Treasury pallet provides a "pot" of funds that can be managed by stakeholders in the system and a structure for making spending proposals from this pot.

Utility

A stateless module with helpers for dispatch management.

Vesting

A simple module providing a means of placing a linear curve on an account's locked balance. This module ensures that there is a lock in place preventing the balance to drop below the unvested amount for any reason other than transaction fee payment.