diff --git a/substrate/bin/node-template/pallets/template/src/lib.rs b/substrate/bin/node-template/pallets/template/src/lib.rs
index edf7769bab7d3e852256b2d338c565b28117a600..4a2e53baa774ee5ca333602024d458aa078f9c10 100644
--- a/substrate/bin/node-template/pallets/template/src/lib.rs
+++ b/substrate/bin/node-template/pallets/template/src/lib.rs
@@ -1,105 +1,201 @@
+//! # Template Pallet
+//!
+//! A pallet with minimal functionality to help developers understand the essential components of
+//! writing a FRAME pallet. It is typically used in beginner tutorials or in Substrate template
+//! nodes as a starting point for creating a new pallet and **not meant to be used in production**.
+//!
+//! ## Overview
+//!
+//! This template pallet contains basic examples of:
+//! - declaring a storage item that stores a single `u32` value
+//! - declaring and using events
+//! - declaring and using errors
+//! - a dispatchable function that allows a user to set a new value to storage and emits an event
+//! upon success
+//! - another dispatchable function that causes a custom error to be thrown
+//!
+//! Each pallet section is annotated with an attribute using the `#[pallet::...]` procedural macro.
+//! This macro generates the necessary code for a pallet to be aggregated into a FRAME runtime.
+//!
+//! Learn more about FRAME macros [here](https://docs.substrate.io/reference/frame-macros/).
+//!
+//! ### Pallet Sections
+//!
+//! The pallet sections in this template are:
+//!
+//! - A **configuration trait** that defines the types and parameters which the pallet depends on
+//! (denoted by the `#[pallet::config]` attribute). See: [`Config`].
+//! - A **means to store pallet-specific data** (denoted by the `#[pallet::storage]` attribute).
+//! See: [`storage_types`].
+//! - A **declaration of the events** this pallet emits (denoted by the `#[pallet::event]`
+//! attribute). See: [`Event`].
+//! - A **declaration of the errors** that this pallet can throw (denoted by the `#[pallet::error]`
+//! attribute). See: [`Error`].
+//! - A **set of dispatchable functions** that define the pallet's functionality (denoted by the
+//! `#[pallet::call]` attribute). See: [`dispatchables`].
+//!
+//! Run `cargo doc --package pallet-template --open` to view this pallet's documentation.
+
+// We make sure this pallet uses `no_std` for compiling to Wasm.
#![cfg_attr(not(feature = "std"), no_std)]
-/// Edit this file to define custom logic or remove it if it is not needed.
-/// Learn more about FRAME and the core library of Substrate FRAME pallets:
-/// <https://docs.substrate.io/reference/frame-pallets/>
+// Re-export pallet items so that they can be accessed from the crate namespace.
pub use pallet::*;
+// FRAME pallets require their own "mock runtimes" to be able to run unit tests. This module
+// contains a mock runtime specific for testing this pallet's functionality.
#[cfg(test)]
mod mock;
+// This module contains the unit tests for this pallet.
+// Learn about pallet unit testing here: https://docs.substrate.io/test/unit-testing/
#[cfg(test)]
mod tests;
+// Every callable function or "dispatchable" a pallet exposes must have weight values that correctly
+// estimate a dispatchable's execution time. The benchmarking module is used to calculate weights
+// for each dispatchable and generates this pallet's weight.rs file. Learn more about benchmarking here: https://docs.substrate.io/test/benchmark/
#[cfg(feature = "runtime-benchmarks")]
mod benchmarking;
pub mod weights;
pub use weights::*;
+// All pallet logic is defined in its own module and must be annotated by the `pallet` attribute.
#[frame_support::pallet]
pub mod pallet {
+ // Import various useful types required by all FRAME pallets.
use super::*;
use frame_support::pallet_prelude::*;
use frame_system::pallet_prelude::*;
+ // The `Pallet` struct serves as a placeholder to implement traits, methods and dispatchables
+ // (`Call`s) in this pallet.
#[pallet::pallet]
pub struct Pallet<T>(_);
- /// Configure the pallet by specifying the parameters and types on which it depends.
+ /// The pallet's configuration trait.
+ ///
+ /// All our types and constants a pallet depends on must be declared here.
+ /// These types are defined generically and made concrete when the pallet is declared in the
+ /// `runtime/src/lib.rs` file of your chain.
#[pallet::config]
pub trait Config: frame_system::Config {
- /// Because this pallet emits events, it depends on the runtime's definition of an event.
+ /// The overarching runtime event type.
type RuntimeEvent: From<Event<Self>> + IsType<<Self as frame_system::Config>::RuntimeEvent>;
- /// Type representing the weight of this pallet
+ /// A type representing the weights required by the dispatchables of this pallet.
type WeightInfo: WeightInfo;
}
- // The pallet's runtime storage items.
- // https://docs.substrate.io/main-docs/build/runtime-storage/
+ /// A storage item for this pallet.
+ ///
+ /// In this template, we are declaring a storage item called `Something` that stores a single
+ /// `u32` value. Learn more about runtime storage here: <https://docs.substrate.io/build/runtime-storage/>
+ /// The [`getter`] macro generates a function to conveniently retrieve the value from storage.
#[pallet::storage]
#[pallet::getter(fn something)]
- // Learn more about declaring storage items:
- // https://docs.substrate.io/main-docs/build/runtime-storage/#declaring-storage-items
pub type Something<T> = StorageValue<_, u32>;
- // Pallets use events to inform users when important changes are made.
- // https://docs.substrate.io/main-docs/build/events-errors/
+ /// Events that functions in this pallet can emit.
+ ///
+ /// Events are a simple means of indicating to the outside world (such as dApps, chain explorers
+ /// or other users) that some notable update in the runtime has occurred. In a FRAME pallet, the
+ /// documentation for each event field and its parameters is added to a node's metadata so it
+ /// can be used by external interfaces or tools.
+ ///
+ /// The `generate_deposit` macro generates a function on `Pallet` called `deposit_event` which
+ /// will convert the event type of your pallet into `RuntimeEvent` (declared in the pallet's
+ /// [`Config`] trait) and deposit it using [`frame_system::Pallet::deposit_event`].
#[pallet::event]
#[pallet::generate_deposit(pub(super) fn deposit_event)]
pub enum Event<T: Config> {
- /// Event documentation should end with an array that provides descriptive names for event
- /// parameters. [something, who]
- SomethingStored { something: u32, who: T::AccountId },
+ /// A user has successfully set a new value.
+ SomethingStored {
+ /// The new value set.
+ something: u32,
+ /// The account who set the new value.
+ who: T::AccountId,
+ },
}
- // Errors inform users that something went wrong.
+ /// Errors that can be returned by this pallet.
+ ///
+ /// Errors tell users that something went wrong so it's important that their naming is
+ /// informative. Similar to events, error documentation is added to a node's metadata so it's
+ /// equally important that they have helpful documentation associated with them.
+ ///
+ /// This type of runtime error can be up to 4 bytes in size should you want to return additional
+ /// information.
#[pallet::error]
pub enum Error<T> {
- /// Error names should be descriptive.
+ /// The value retrieved was `None` as no value was previously set.
NoneValue,
- /// Errors should have helpful documentation associated with them.
+ /// There was an attempt to increment the value in storage over `u32::MAX`.
StorageOverflow,
}
- // Dispatchable functions allows users to interact with the pallet and invoke state changes.
- // These functions materialize as "extrinsics", which are often compared to transactions.
- // Dispatchable functions must be annotated with a weight and must return a DispatchResult.
+ /// The pallet's dispatchable functions ([`Call`]s).
+ ///
+ /// Dispatchable functions allows users to interact with the pallet and invoke state changes.
+ /// These functions materialize as "extrinsics", which are often compared to transactions.
+ /// They must always return a `DispatchResult` and be annotated with a weight and call index.
+ ///
+ /// The [`call_index`] macro is used to explicitly
+ /// define an index for calls in the [`Call`] enum. This is useful for pallets that may
+ /// introduce new dispatchables over time. If the order of a dispatchable changes, its index
+ /// will also change which will break backwards compatibility.
+ ///
+ /// The [`weight`] macro is used to assign a weight to each call.
#[pallet::call]
impl<T: Config> Pallet<T> {
- /// An example dispatchable that takes a singles value as a parameter, writes the value to
- /// storage and emits an event. This function must be dispatched by a signed extrinsic.
+ /// An example dispatchable that takes a single u32 value as a parameter, writes the value
+ /// to storage and emits an event.
+ ///
+ /// It checks that the _origin_ for this call is _Signed_ and returns a dispatch
+ /// error if it isn't. Learn more about origins here: <https://docs.substrate.io/build/origins/>
#[pallet::call_index(0)]
#[pallet::weight(T::WeightInfo::do_something())]
pub fn do_something(origin: OriginFor<T>, something: u32) -> DispatchResult {
// Check that the extrinsic was signed and get the signer.
- // This function will return an error if the extrinsic is not signed.
- // https://docs.substrate.io/main-docs/build/origins/
let who = ensure_signed(origin)?;
// Update storage.
- <Something<T>>::put(something);
+ Something::<T>::put(something);
// Emit an event.
Self::deposit_event(Event::SomethingStored { something, who });
- // Return a successful DispatchResultWithPostInfo
+
+ // Return a successful `DispatchResult`
Ok(())
}
/// An example dispatchable that may throw a custom error.
+ ///
+ /// It checks that the caller is a signed origin and reads the current value from the
+ /// `Something` storage item. If a current value exists, it is incremented by 1 and then
+ /// written back to storage.
+ ///
+ /// ## Errors
+ ///
+ /// The function will return an error under the following conditions:
+ ///
+ /// - If no value has been set ([`Error::NoneValue`])
+ /// - If incrementing the value in storage causes an arithmetic overflow
+ /// ([`Error::StorageOverflow`])
#[pallet::call_index(1)]
#[pallet::weight(T::WeightInfo::cause_error())]
pub fn cause_error(origin: OriginFor<T>) -> DispatchResult {
let _who = ensure_signed(origin)?;
// Read a value from storage.
- match <Something<T>>::get() {
+ match Pallet::<T>::something() {
// Return an error if the value has not been set.
None => Err(Error::<T>::NoneValue.into()),
Some(old) => {
- // Increment the value read from storage; will error in the event of overflow.
+ // Increment the value read from storage. This will cause an error in the event
+ // of overflow.
let new = old.checked_add(1).ok_or(Error::<T>::StorageOverflow)?;
// Update the value in storage with the incremented result.
- <Something<T>>::put(new);
+ Something::<T>::put(new);
Ok(())
},
}