Use macros in a custom pallet

⚠️ Update Notice:

Please read Substrate to Polkadot SDK page first.

This tutorial illustrates how to create a custom pallet for a Substrate runtime using macros that are part of the FRAME development environment.

For this tutorial, you'll build a simple proof-of-existence application. Proof-of-existence is an approach to validating the authenticity and ownership of a digital object by storing information about the object on the blockchain. Because the blockchain associates a timestamp and account with the object, the blockchain record can be used to "prove" that a particular object existed at a specific date and time. It can also verify who the owner of a record was at that date and time.

Digital objects and hashes

Instead of storing an entire file on the blockchain, it can be much more efficient to simply store a cryptographic hash of that file. This is also known as a "digital fingerprint". The hash enables the blockchain to store files of arbitrary size efficiently by using a small and unique hash value. Because any change to a file would result in a different hash, users can prove the validity of a file by computing the hash and comparing that hash with the hash stored on chain.

Digital objects and account signatures

Blockchains use public key cryptography to map digital identities to accounts that have private keys. The blockchain records the account you use to store the hash for a digital object as part of the transaction. Because the account information is stored as part of the transaction, the controller of the private key for that account can later prove ownership as the person who initially uploaded the file.

How much time do you need to complete this tutorial?

This tutorial requires compiling Rust code and takes approximately one to two hours to complete.

Before you begin

Before you begin, verify the following:

You have configured your environment for Substrate development by installing Rust and the Rust toolchain.
You have cloned the Substrate node template, which will be used as the starting point for this tutorial.

Tutorial objectives

By completing this tutorial, you will accomplish the following objectives:

Learn the basic structure of a custom pallet.
See examples of how Rust macros simplify the code you need to write.
Start a blockchain node that contains a custom pallet.
Interact with a front-end that exposes the proof-of-existence pallet.

Application design

The proof-of-existence application exposes two callable functions:

create_claim() allows a user to claim the existence of a file by uploading a hash.
revoke_claim() allows the current owner of a claim to revoke ownership.

Build a custom pallet

The Substrate node template has a FRAME-based runtime. As you learned in Runtime development, FRAME is a library of code that allows you to build a Substrate runtime by composing modules called pallets. You can think of the pallets as specialized logical units that define what your blockchain can do. Substrate provides you with a number of pre-built pallets for use in FRAME-based runtimes.

This tutorial demonstrates how to create your own FRAME pallet to be included in your custom blockchain.

Set up scaffolding for your pallet

This tutorial demonstrates how to create a custom pallet from scratch. Therefore, the first step is to remove some files and content from the files in the node template directory.

Open a terminal shell and navigate to the root directory for the node template.
Change to the pallets/template/src directory by running the following command:
```
cd pallets/template/src
```
Remove the following files:
```
benchmarking.rs
mock.rs
tests.rs
```
Open the lib.rs file in a text editor.

This file contains code that you can use as a template for a new pallet. You won't be using the template code in this tutorial. However, you can review the template code to see what it provides before you delete it.

Delete all of the lines in the lib.rs file, and replace it with the skeleton of a custom pallet:

// All pallets must be configured for `no_std`.
#![cfg_attr(not(feature = "std"), no_std)]

// Re-export pallet items so that they can be accessed from the crate namespace.
pub use pallet::*;

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

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

 #[pallet::config]  // <-- Step 2. code block will replace this.
 #[pallet::event]   // <-- Step 3. code block will replace this.
 #[pallet::error]   // <-- Step 4. code block will replace this.
 #[pallet::storage] // <-- Step 5. code block will replace this.
 #[pallet::call]    // <-- Step 6. code block will replace this.
}

pub mod weights {
  // Placeholder struct for the pallet weights
  pub struct SubstrateWeight<T>(core::marker::PhantomData<T>);
}

You now have a framework that includes placeholders for events, errors, storage, and callable functions.

NOTE: Pallet weights are outside the scope of this tutorial. If you want to learn more about weights, you can read our documentation here.

Save your changes.

Configure the pallet to emit events

Every pallet has a Rust "trait" called Config. You use this trait to expose configurable options and connect your pallet to other parts of the runtime. For this tutorial, we need to configure out pallet to emit events.

To define the Config trait for the proof-of-existence pallet:

Open the pallets/template/src/lib.rs file in a text editor.

Replace the #[pallet::config] line with the following code block:

/// Configure the pallet by specifying the parameters and types on which it depends.
#[pallet::config]
pub trait Config: frame_system::Config {
 /// Because this pallet emits events, it depends on the runtime's definition of an event.
 type RuntimeEvent: From<Event<Self>> + IsType<<Self as frame_system::Config>::RuntimeEvent>;
  /// Pallets use weights to measure the complexity of the callable functions.
  /// Configuring weights is outside the scope of this tutorial, so we will leave it empty for now.
  type WeightInfo;
}

Save your changes.

Implement pallet events

Now that you've configured the pallet to emit events, you are ready to define those events. Based on the application design, we want the proof-of-existence pallet to emit an event under the following conditions:

When a new claim is added to the blockchain.
When a claim is revoked.

Each event can include an AccountId to identify who triggered the event and a Hash, representing the proof-of-existence claim that is being stored or removed.

To implement the pallet events:

Open the pallets/template/src/lib.rs file in a text editor.

Replace the #[pallet::event] line with the following code block:

// Pallets use events to inform users when important changes are made.
// Event documentation should end with an array that provides descriptive names for parameters.
#[pallet::event]
#[pallet::generate_deposit(pub(super) fn deposit_event)]
pub enum Event<T: Config> {
 /// Event emitted when a claim has been created.
 ClaimCreated { who: T::AccountId, claim: T::Hash },
 /// Event emitted when a claim is revoked by the owner.
 ClaimRevoked { who: T::AccountId, claim: T::Hash },
}

Save your changes.

Include pallet errors

The events you defined indicate when calls to the pallet have completed successfully. Errors indicate that a call has failed, and why it has failed. For this tutorial, you define the following error conditions:

An attempt to make a claim when a claim already exists.
An attempt to revoke a claim that doesn't exist.
An attempt to revoke a claim that is owned by another account.

To implement the errors for the proof-of-existence pallet:

Open the pallets/template/src/lib.rs file in a text editor.

Replace the #[pallet::error] line with the following code block:

#[pallet::error]
pub enum Error<T> {
 /// The claim already exists.
 AlreadyClaimed,
 /// The claim does not exist, so it cannot be revoked.
 NoSuchClaim,
 /// The claim is owned by another account, so caller can't revoke it.
 NotClaimOwner,
}

Save your changes.

Implement a storage map for stored items

To add a new claim to the blockchain, the proof-of-existence pallet requires a storage mechanism. To address this requirement, you can create a key-value map, where each claim points to the owner and the block number when the claim was made. To create this key-value map, you can use the FRAME StorageMap.

To implement storage for the proof-of-existence pallet:

Open the pallets/template/src/lib.rs file in a text editor.

Replace the #[pallet::storage] line with the following code block:

#[pallet::storage]
pub(super) type Claims<T: Config> = StorageMap<_, Blake2_128Concat, T::Hash, (T::AccountId, BlockNumberFor<T>)>;

Save your changes.

Implement callable functions

The proof-of-existence pallet exposes two callable functions to users:

create_claim() allows a user to claim the existence of a file with a hash.
revoke_claim() allows the owner of a claim to revoke the claim.

These functions use the StorageMap to implement the following logic:

If a claim is already in storage, then it already has an owner and cannot be claimed again.
If a claim doesn't exist in storage, then it is available to be claimed and written to storage.

To implement this logic in the proof-of-existence pallet:

Open the pallets/template/src/lib.rs file in a text editor.

Replace the #[pallet::call] line with the following code block. You might try to implement the revoke_claim function yourself. Just copy the function signature and not the content. The Claims::<T>::get and Claims::<T>::remove should be used to get or remove a claim.

// Dispatchable functions allow 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.
#[pallet::call]
impl<T: Config> Pallet<T> {
 #[pallet::weight(Weight::default())]
 #[pallet::call_index(0)]
 pub fn create_claim(origin: OriginFor<T>, claim: T::Hash) -> DispatchResult {
   // Check that the extrinsic was signed and get the signer.
   // This function will return an error if the extrinsic is not signed.
   let sender = ensure_signed(origin)?;

   // Verify that the specified claim has not already been stored.
   ensure!(!Claims::<T>::contains_key(&claim), Error::<T>::AlreadyClaimed);

   // Get the block number from the FRAME System pallet.
   let current_block = <frame_system::Pallet<T>>::block_number();

   // Store the claim with the sender and block number.
   Claims::<T>::insert(&claim, (&sender, current_block));

   // Emit an event that the claim was created.
   Self::deposit_event(Event::ClaimCreated { who: sender, claim });

   Ok(())
 }

 #[pallet::weight(Weight::default())]
 #[pallet::call_index(1)]
 pub fn revoke_claim(origin: OriginFor<T>, claim: T::Hash) -> DispatchResult {
   // Check that the extrinsic was signed and get the signer.
   // This function will return an error if the extrinsic is not signed.
   let sender = ensure_signed(origin)?;

   // Get owner of the claim, if none return an error.
   let (owner, _) = Claims::<T>::get(&claim).ok_or(Error::<T>::NoSuchClaim)?;

   // Verify that sender of the current call is the claim owner.
   ensure!(sender == owner, Error::<T>::NotClaimOwner);

   // Remove claim from storage.
   Claims::<T>::remove(&claim);

   // Emit an event that the claim was erased.
   Self::deposit_event(Event::ClaimRevoked { who: sender, claim });
   Ok(())
 }
}

Save your changes and close the file.
Check that your pallet compiles by running the following command:
```
cargo check -p pallet-template
```
The -p flag tells cargo to only check the pallet-template that you have been modifying and saving you some compile time.

You can refer to the node template solution if you get stuck.

Build the runtime with your new pallet

After you've copied all of the parts of the proof-of-existence pallet into the pallets/template/lib.rsfile, you are ready to compile and start the node.

To compile and start the updated Substrate node:

Open a terminal shell.
Change to the root directory for the node template.
Compile the node template by running the following command:
```
cargo build --release
```
Start the node in development mode by running the following command:
```
./target/release/node-template --dev
```
The --dev option starts the node using the predefined development chain specification. Using the --dev option ensures that you have a clean working state any time you stop and restart the node.
Verify the node produces blocks.

Interact with your blockchain

Now that you have a new blockchain running with the custom proof-of-existence pallet, we can interact with the chain to make sure all the functionality works as expected!

To do this, we will use Polkadot JS Apps, which is a developer tool that can connect to and interact with any Substrate based blockchain.

By default, your blockchain should be running on ws://127.0.0.1:9944, so to connect to it we can use this link:

https://polkadot.js.org/apps/?rpc=ws%3A%2F%2F127.0.0.1%3A9944#/

If your Substrate blockchain is running and Polkadot JS Apps is connected, you should see your block number increase in the top left corner:

Submit a claim

To test the proof-of-existence pallet using the front-end:

Navigate to the "Developer > Extrinsics" tab.
Adjust the extrinsics page to select "ALICE" as the account, and "templateModule > createClaim" as the extrinsic.
Then you can toggle "hash a file", which will allow you to select a file to hash and claim on the blockchain.
Click "Submit Transaction" in the bottom right corner, then on the pop up click "Sign and Submit".
If everything was successful, you should see a green extrinsic success notification!

Read a claim

The final step of this tutorial is to check what claims have been stored on your blockchain.

Navigate to the "Developer > Chain State" tab.
Adjust the state query to "templateModule > claims".
Toggle off the "include option" on the hash input to leave the input empty.

This will allow us to see all the claims, rather than just one at a time.
Press the "+" button to execute the query.

Now you can see that the claim is stored in the blockchain with the data about the owners address and the block number when the claim was made!

Next steps

In this tutorial, you learned the basics of how to create a new custom pallet, including:

How to add events, errors, storage, and callable functions to a custom pallet.
How to integrate the custom pallet into the runtime.
How to compile and start a node that includes your custom pallet.
How you can use the Polkadot JS Apps developer tool to interact with your custom blockchain.

This tutorial covered the basics without diving too deeply into the code. However, there's much more you can do as you work toward building your own fully-customized blockchain. Custom pallets enable you to expose the features you want your blockchain to support.

To complete your understanding of the proof-of-existence chain try:

Claiming the same file again with "ALICE" or even the "BOB" account.
- You should get an error!
Claiming other files with the "ALICE" and/or "BOB" accounts.
Revoking the claims with the appropriate claim owner account.
Looking at the final list of claims from reading storage.

To learn more about what's possible by creating custom pallets, explore the FRAME documentation and the how-to guides.