#
pezkuwi_sdk_docs/pezkuwi_sdk/
frame_runtime.rs

    1//! # FRAME
    2//!
    3//! ```no_compile
    4//!   ______   ______    ________   ___ __ __   ______
    5//!  /_____/\ /_____/\  /_______/\ /__//_//_/\ /_____/\
    6//!  \::::_\/_\:::_ \ \ \::: _  \ \\::\| \| \ \\::::_\/_
    7//!   \:\/___/\\:(_) ) )_\::(_)  \ \\:.      \ \\:\/___/\
    8//!    \:::._\/ \: __ `\ \\:: __  \ \\:.\-/\  \ \\::___\/_
    9//!     \:\ \    \ \ `\ \ \\:.\ \  \ \\. \  \  \ \\:\____/\
    10//!      \_\/     \_\/ \_\/ \__\/\__\/ \__\/ \__\/ \_____\/
    11//! ```
    12//!
    13//! > **F**ramework for **R**untime **A**ggregation of **M**odularized **E**ntities: Bizinikiwi's
    14//! > State Transition Function (Runtime) Framework.
    15//!
    16//! ## Introduction
    17//!
    18//! As described in [`crate::reference_docs::wasm_meta_protocol`], at a high-level Bizinikiwi-based
    19//! blockchains are composed of two parts:
    20//!
    21//! 1. A *runtime* which represents the state transition function (i.e. "Business Logic") of a
    22//! blockchain, and is encoded as a WASM blob.
    23//! 2. A node whose primary purpose is to execute the given runtime.
    24#![doc = simple_mermaid::mermaid!("../../../mermaid/bizinikiwi_simple.mmd")]
    25//!
    26//! *FRAME is the Bizinikiwi's framework of choice to build a runtime.*
    27//!
    28//! FRAME is composed of two major components, **pallets** and a **runtime**.
    29//!
    30//! ## Pallets
    31//!
    32//! A pezpallet is a unit of encapsulated logic. It has a clearly defined responsibility and can be
    33//! linked to other pallets. In order to be reusable, pallets shipped with FRAME strive to only care
    34//! about its own responsibilities and make as few assumptions about the general runtime as
    35//! possible. A pezpallet is analogous to a _module_ in the runtime.
    36//!
    37//! A pezpallet is defined as a `mod pezpallet` wrapped by the [`pezframe::pezpallet`] macro. Within
    38//! this macro, pezpallet components/parts can be defined. Most notable of these parts are:
    39//!
    40//! - [Config](pezframe::pezpallet_macros::config), allowing a pezpallet to make itself configurable
    41//!   and generic over types, values and such.
    42//! - [Storage](pezframe::pezpallet_macros::storage), allowing a pezpallet to define onchain storage.
    43//! - [Dispatchable function](pezframe::pezpallet_macros::call), allowing a pezpallet to define
    44//!   extrinsics that are callable by end users, from the outer world.
    45//! - [Events](pezframe::pezpallet_macros::event), allowing a pezpallet to emit events.
    46//! - [Errors](pezframe::pezpallet_macros::error), allowing a pezpallet to emit well-formed errors.
    47//!
    48//! Some of these pezpallet components resemble the building blocks of a smart contract. While both
    49//! models are programming state transition functions of blockchains, there are crucial differences
    50//! between the two. See [`crate::reference_docs::runtime_vs_smart_contract`] for more.
    51//!
    52//! Most of these components are defined using macros, the full list of which can be found in
    53//! [`pezframe::pezpallet_macros`].
    54//!
    55//! ### Example
    56//!
    57//! The following example showcases a minimal pezpallet.
    58#![doc = docify::embed!("src/pezkuwi_sdk/frame_runtime.rs", pezpallet)]
    59//!
    60//! ## Runtime
    61//!
    62//! A runtime is a collection of pallets that are amalgamated together. Each pezpallet typically has
    63//! some configurations (exposed as a `trait Config`) that needs to be *specified* in the runtime.
    64//! This is done with [`pezframe::runtime::prelude::construct_runtime`].
    65//!
    66//! A (real) runtime that actually wishes to compile to WASM needs to also implement a set of
    67//! runtime-apis. These implementation can be specified using the
    68//! [`pezframe::runtime::prelude::impl_runtime_apis`] macro.
    69//!
    70//! ### Example
    71//!
    72//! The following example shows a (test) runtime that is composing the pezpallet demonstrated above,
    73//! next to the [`pezframe::prelude::pezframe_system`] pezpallet, into a runtime.
    74#![doc = docify::embed!("src/pezkuwi_sdk/frame_runtime.rs", runtime)]
    75//!
    76//! ## More Examples
    77//!
    78//! You can find more FRAME examples that revolve around specific features at
    79//! [`pezpallet_examples`].
    80//!
    81//! ## Alternatives 🌈
    82//!
    83//! There is nothing in the Bizinikiwi's node side code-base that mandates the use of FRAME. While
    84//! FRAME makes it very simple to write Bizinikiwi-based runtimes, it is by no means intended to be
    85//! the only one. At the end of the day, any WASM blob that exposes the right set of runtime APIs is
    86//! a valid Runtime form the point of view of a Bizinikiwi client (see
    87//! [`crate::reference_docs::wasm_meta_protocol`]). Notable examples are:
    88//!
    89//! * writing a runtime in pure Rust, as done in [this template](https://github.com/JoshOrndorff/frameless-node-template).
    90//! * writing a runtime in AssemblyScript, as explored in [this project](https://github.com/LimeChain/subsembly).
    91
    92/// A FRAME based pezpallet. This `mod` is the entry point for everything else. All
    93/// `#[pezpallet::xxx]` macros must be defined in this `mod`. Although, frame also provides an
    94/// experimental feature to break these parts into different `mod`s. See [`pezpallet_examples`] for
    95/// more.
    96#[docify::export]
    97#[pezframe::pezpallet(dev_mode)]
    98pub mod pezpallet {
    99	use pezframe::prelude::*;
    100
    101	/// The configuration trait of a pezpallet. Mandatory. Allows a pezpallet to receive types at a
    102	/// later point from the runtime that wishes to contain it. It allows the pezpallet to be
    103	/// parameterized over both types and values.
    104	#[pezpallet::config]
    105	pub trait Config: pezframe_system::Config {
    106		/// A type that is not known now, but the runtime that will contain this pezpallet will
    107		/// know it later, therefore we define it here as an associated type.
    108		#[allow(deprecated)]
    109		type RuntimeEvent: IsType<<Self as pezframe_system::Config>::RuntimeEvent>
    110			+ From<Event<Self>>;
    111
    112		/// A parameterize-able value that we receive later via the `Get<_>` trait.
    113		type ValueParameter: Get<u32>;
    114
    115		/// Similar to [`Config::ValueParameter`], but using `const`. Both are functionally
    116		/// equal, but offer different tradeoffs.
    117		const ANOTHER_VALUE_PARAMETER: u32;
    118	}
    119
    120	/// A mandatory struct in each pezpallet. All functions callable by external users (aka.
    121	/// transactions) must be attached to this type (see [`pezframe::pezpallet_macros::call`]). For
    122	/// convenience, internal (private) functions can also be attached to this type.
    123	#[pezpallet::pezpallet]
    124	pub struct Pezpallet<T>(PhantomData<T>);
    125
    126	/// The events that this pezpallet can emit.
    127	#[pezpallet::event]
    128	pub enum Event<T: Config> {}
    129
    130	/// A storage item that this pezpallet contains. This will be part of the state root trie
    131	/// of the blockchain.
    132	#[pezpallet::storage]
    133	pub type Value<T> = StorageValue<Value = u32>;
    134
    135	/// All *dispatchable* call functions (aka. transactions) are attached to `Pezpallet` in a
    136	/// `impl` block.
    137	#[pezpallet::call]
    138	impl<T: Config> Pezpallet<T> {
    139		/// This will be callable by external users, and has two u32s as a parameter.
    140		pub fn some_dispatchable(
    141			_origin: OriginFor<T>,
    142			_param: u32,
    143			_other_para: u32,
    144		) -> DispatchResult {
    145			Ok(())
    146		}
    147	}
    148}
    149
    150/// A simple runtime that contains the above pezpallet and `pezframe_system`, the mandatory
    151/// pezpallet of all runtimes. This runtime is for testing, but it shares a lot of similarities with
    152/// a *real* runtime.
    153#[docify::export]
    154pub mod runtime {
    155	use super::pezpallet as pezpallet_example;
    156	use pezframe::{prelude::*, testing_prelude::*};
    157
    158	// The major macro that amalgamates pallets into `enum Runtime`
    159	construct_runtime!(
    160		pub enum Runtime {
    161			System: pezframe_system,
    162			Example: pezpallet_example,
    163		}
    164	);
    165
    166	// These `impl` blocks specify the parameters of each pezpallet's `trait Config`.
    167	#[derive_impl(pezframe_system::config_preludes::TestDefaultConfig)]
    168	impl pezframe_system::Config for Runtime {
    169		type Block = MockBlock<Self>;
    170	}
    171
    172	impl pezpallet_example::Config for Runtime {
    173		type RuntimeEvent = RuntimeEvent;
    174		type ValueParameter = ConstU32<42>;
    175		const ANOTHER_VALUE_PARAMETER: u32 = 42;
    176	}
    177}