Skip to content

Customize Your Runtime

Introduction

A blockchain runtime is more than just a fixed set of rules—it's a dynamic foundation that you can shape to match your specific needs. With Polkadot SDK's FRAME (Framework for Runtime Aggregation of Modularized Entities), customizing your runtime is straightforward and modular. Instead of building everything from scratch, you combine pre-built pallets with your own custom logic to create a runtime suited to your blockchain's purpose.

This overview explains how runtime customization works, introduces the building blocks you'll use, and guides you through the key patterns for extending your runtime.

Understanding Your Runtime

The runtime is the core logic of your blockchain—it processes transactions, manages state, and enforces the rules that govern your network. When a transaction arrives at your blockchain, the frame_executive pallet receives it and routes it to the appropriate pallet for execution.

Think of your runtime as a collection of specialized modules, each handling a different aspect of your blockchain. Need token balances? Use the Balances pallet. Want governance? Add the Governance pallet. Need something custom? Create your own pallet. By mixing and matching these modules, you build a runtime that's efficient, secure, and tailored to your use case.

Runtime Architecture

The following diagram shows how FRAME components work together to form your runtime:

The main components are:

  • frame_executive: Routes all incoming transactions to the correct pallet for execution.
  • Pallets: Domain-specific modules that implement your blockchain's features and business logic.
  • frame_system: Provides core runtime primitives and storage.
  • frame_support: Utilities and macros that simplify pallet development.

Building Blocks: Pallets

Pallets are the fundamental units of runtime customization. Each pallet encapsulates specific functionality and can be independently developed, tested, and integrated.

A pallet can implement virtually any blockchain feature you need:

  • Expose new transactions that users can submit.
  • Store data on-chain.
  • Enforce business rules and validation logic.
  • Emit events to notify users of state changes.
  • Handle errors gracefully.

Pre-Built Pallets vs. Custom Pallets

FRAME provides a comprehensive library of pre-built pallets for common blockchain features, including consensus, staking, balances, governance, and more. These pallets are battle-tested, optimized, and ready to use.

However, you're not limited to pre-built functionality. When pre-built pallets don't meet your needs, you can create custom pallets with entirely custom logic. The real power of FRAME is the flexibility to use pre-built modules for standard features while building your own for unique requirements.

Pallet Structure

FRAME uses Rust macros extensively, allowing you to focus on your pallet's logic while the framework handles boilerplate and integration code.

A typical pallet looks like this:

pub use pallet::*;

#[frame_support::pallet]
pub mod pallet {
  use frame_support::pallet_prelude::*;
  use frame_system::pallet_prelude::*;

  #[pallet::pallet]
  #[pallet::generate_store(pub(super) trait Store)]
  pub struct Pallet<T>(_);

  #[pallet::config]  // snip
  #[pallet::event]   // snip
  #[pallet::error]   // snip
  #[pallet::storage] // snip
  #[pallet::call]    // snip
}

Every pallet can implement these core macros:

  • #[frame_support::pallet]: Marks your module as a FRAME pallet.
  • #[pallet::pallet]: Designates the struct that holds pallet metadata.
  • #[pallet::config]: Defines configuration and associated types.
  • #[pallet::event]: Defines events emitted by your pallet.
  • #[pallet::error]: Defines error types your pallet can return.
  • #[pallet::storage]: Defines on-chain storage items.
  • #[pallet::call]: Defines dispatchable functions (transactions).

For a comprehensive reference, see the pallet_macros documentation.

How Runtime Customization Works

Customizing your runtime typically follows these patterns:

Adding Pre-Built Pallets: Select pallets from the FRAME library and integrate them into your runtime configuration. This is the fastest way to add functionality.

Creating Custom Pallets: Write custom pallets for features that don't exist in the pre-built library. Custom pallets follow the same structure as pre-built ones and integrate seamlessly.

Combining Multiple Pallets: Layer multiple pallets together to create complex behaviors. Pallets can call each other and share storage when needed.

Configuring Pallet Parameters: Most pallets are configurable—you can adjust their behavior through configuration traits without modifying their code.

The following diagram illustrates how pallets combine to form a complete runtime:

Starting Templates

The easiest way to begin customizing your runtime is with a starter template. These templates provide a pre-configured foundation so you can focus on customization rather than setup.

  • Polkadot SDK Parachain Template: The recommended choice for most developers, it includes pre-configured pallets for common features (balances, block production, governance), a complete runtime setup, and built-in parachain consensus support. This template offers the best balance of features and learning opportunities.

  • Polkadot SDK Minimal Template: Provides a bare-bones runtime with only essential components. Choose this if you want maximum flexibility and prefer building from a clean slate.

  • Polkadot SDK Solochain Template: Designed for building standalone blockchains with moderate features, simple consensus, and several core pallets. Use this if you want a sovereign blockchain independent of a relay chain.

  • OpenZeppelin Runtime Templates: Provides security-focused configurations following industry best practices. The generic-template includes curated pallet selections and production-ready defaults—ideal if security is your top priority.

Key Customization Scenarios

This section covers the most common customization patterns you'll encounter:

Last update: October 20, 2025
| Created: September 30, 2025