Attribute Macro frame_support_procedural::pallet

source · 
#[pallet]
Expand description

The pallet struct placeholder #[pallet::pallet] is mandatory and allows you to specify pallet information.

The struct must be defined as follows:

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

I.e. a regular struct definition named Pallet, with generic T and no where clause.

Macro expansion:

The macro adds this attribute to the struct definition:

ⓘ
#[derive(
	frame_support::CloneNoBound,
	frame_support::EqNoBound,
	frame_support::PartialEqNoBound,
	frame_support::RuntimeDebugNoBound,
)]

and replaces the type _ with PhantomData<T>. It also implements on the pallet:

  • GetStorageVersion
  • OnGenesis: contains some logic to write the pallet version into storage.
  • PalletErrorTypeInfo: provides the type information for the pallet error, if defined.

It declares type Module type alias for Pallet, used by construct_runtime.

It implements PalletInfoAccess on Pallet to ease access to pallet information given by frame_support::traits::PalletInfo. (The implementation uses the associated type frame_system::Config::PalletInfo).

It implements StorageInfoTrait on Pallet which give information about all storages.

If the attribute generate_store is set then the macro creates the trait Store and implements it on Pallet.

If the attribute set_storage_max_encoded_len is set then the macro calls StorageInfoTrait for each storage in the implementation of StorageInfoTrait for the pallet. Otherwise it implements StorageInfoTrait for the pallet using the PartialStorageInfoTrait implementation of storages.

Dev Mode (#[pallet(dev_mode)])

Specifying the argument dev_mode will allow you to enable dev mode for a pallet. The aim of dev mode is to loosen some of the restrictions and requirements placed on production pallets for easy tinkering and development. Dev mode pallets should not be used in production. Enabling dev mode has the following effects:

  • Weights no longer need to be specified on every #[pallet::call] declaration. By default, dev mode pallets will assume a weight of zero (0) if a weight is not specified. This is equivalent to specifying #[weight(0)] on all calls that do not specify a weight.
  • Call indices no longer need to be specified on every #[pallet::call] declaration. By default, dev mode pallets will assume a call index based on the order of the call.
  • All storages are marked as unbounded, meaning you do not need to implement MaxEncodedLen on storage types. This is equivalent to specifying #[pallet::unbounded] on all storage type definitions.
  • Storage hashers no longer need to be specified and can be replaced by _. In dev mode, these will be replaced by Blake2_128Concat. In case of explicit key-binding, Hasher can simply be ignored when in dev_mode.

Note that the dev_mode argument can only be supplied to the #[pallet] or #[frame_support::pallet] attribute macro that encloses your pallet module. This argument cannot be specified anywhere else, including but not limited to the #[pallet::pallet] attribute macro.

WARNING:
You should not deploy or use dev mode pallets in production. Doing so can break your chain
and therefore should never be done. Once you are done tinkering, you should remove the
'dev_mode' argument from your #[pallet] declaration and fix any compile errors before
attempting to use your pallet in a production scenario.

See frame_support::pallet docs for more info.

Runtime Metadata Documentation

The documentation added to this pallet is included in the runtime metadata.

The documentation can be defined in the following ways:

ⓘ
#[pallet::pallet]
/// Documentation for pallet 1
#[doc = "Documentation for pallet 2"]
#[doc = include_str!("../README.md")]
#[pallet_doc("../doc1.md")]
#[pallet_doc("../doc2.md")]
pub mod pallet {}

The runtime metadata for this pallet contains the following

  • “ Documentation for pallet 1“ (captured from ///)
  • “Documentation for pallet 2” (captured from #[doc])
  • content of ../README.md (captured from #[doc] with include_str!)
  • content of “../doc1.md” (captured from pallet_doc)
  • content of “../doc2.md” (captured from pallet_doc)

doc attribute

The value of the doc attribute is included in the runtime metadata, as well as expanded on the pallet module. The previous example is expanded to:

ⓘ
/// Documentation for pallet 1
/// Documentation for pallet 2
/// Content of README.md
pub mod pallet {}

If you want to specify the file from which the documentation is loaded, you can use the include_str macro. However, if you only want the documentation to be included in the runtime metadata, use the pallet_doc attribute.

pallet_doc attribute

Unlike the doc attribute, the documentation provided to the pallet_doc attribute is not inserted on the module.

The pallet_doc attribute can only be provided with one argument, which is the file path that holds the documentation to be added to the metadata.

This approach is beneficial when you use the include_str macro at the beginning of the file and want that documentation to extend to the runtime metadata, without reiterating the documentation on the pallet module itself.