Module polkadot_sdk_docs::reference_docs::frame_pallet_coupling

Learn about the different ways through which multiple frame pallets can be combined to work together.

FRAME Pallet Coupling

This reference document explains how FRAME pallets can be combined to interact together.

It is suggested to re-read crate::polkadot_sdk::frame_runtime, notably the information around frame::pallet_macros::config. Recall that:

Configuration trait of a pallet: It allows a pallet to receive types at a later point from the runtime that wishes to contain it. It allows the pallet to be parameterized over both types and values.

Context, Background

FRAME pallets, as per described in crate::polkadot_sdk::frame_runtime are:

A pallet is a unit of encapsulated logic. It has a clearly defined responsibility and can be linked to other pallets.

That is to say:

• encapsulated: Ideally, a FRAME pallet contains encapsulated logic which has clear boundaries. It is generally a bad idea to build a single monolithic pallet that does multiple things, such as handling currencies, identities and staking all at the same time.
• linked to other pallets: But, adhering extensively to the above also hinders the ability to write useful applications. Pallets often need to work with each other, communicate and use each other’s functionalities.

The broad principle that allows pallets to be linked together is the same way through which a pallet uses its Config trait to receive types and values from the runtime that contains it.

There are generally two ways to achieve this:

1. Tight coupling pallets.
2. Loose coupling pallets.

To explain the difference between the two, consider two pallets, A and B. In both cases, A wants to use some functionality exposed by B.

When tightly coupling pallets, A can only exist in a runtime if B is also present in the same runtime. That is, A is expressing that can only work if B is present.

This translates to the following Rust code:

trait Pallet_B_Config {}
trait Pallet_A_Config: Pallet_B_Config {}

Contrary, when pallets are loosely coupled, A expresses that some functionality, expressed via a trait F, needs to be fulfilled. This trait is then implemented by B, and the two pallets are linked together at the runtime level. This means that A only relies on the implementation of F, which may be B, or another implementation of F.

This translates to the following Rust code:

trait F {}
trait Pallet_A_Config {
   type F: F;
}
// Pallet_B will implement and fulfill `F`.

Example

Consider the following example, in which pallet-foo needs another pallet to provide the block author to it, and pallet-author which has access to this information.

#[frame::pallet]
pub mod pallet_foo {
	use super::*;

	#[pallet::config]
	pub trait Config: frame_system::Config {}

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

	impl<T: Config> Pallet<T> {
		fn do_stuff_with_author() {
			// needs block author here
		}
	}
}

#[frame::pallet]
pub mod pallet_author {
	use super::*;

	#[pallet::config]
	pub trait Config: frame_system::Config {}

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

	impl<T: Config> Pallet<T> {
		pub fn author() -> T::AccountId {
			todo!("somehow has access to the block author and can return it here")
		}
	}
}

Tight Coupling Pallets

To tightly couple pallet-foo and pallet-author, we use Rust’s supertrait system. When a pallet makes its own trait Config be bounded by another pallet’s trait Config, it is expressing two things:

1. That it can only exist in a runtime if the other pallet is also present.
2. That it can use the other pallet’s functionality.

pallet-foo’s Config would then look like:

#[pallet::config]
pub trait Config: frame_system::Config + pallet_author::Config {}

And pallet-foo can use the method exposed by pallet_author::Pallet directly:

impl<T: Config> Pallet<T> {
	// anywhere in `pallet-foo`, we can call into `pallet-author` directly, namely because
	// `T: pallet_author::Config`
	fn do_stuff_with_author() {
		let _ = pallet_author::Pallet::<T>::author();
	}
}

Loosely Coupling Pallets

If pallet-foo wants to not rely on pallet-author directly, it can leverage its Config’s associated types. First, we need a trait to express the functionality that pallet-foo wants to obtain:

pub trait AuthorProvider<AccountId> {
	fn author() -> AccountId;
}

We sometimes refer to such traits that help two pallets interact as “glue traits”.

Next, pallet-foo states that it needs this trait to be provided to it, at the runtime level, via an associated type:

#[pallet::config]
pub trait Config: frame_system::Config {
	/// This pallet relies on the existence of something that implements [`AuthorProvider`],
	/// which may or may not be `pallet-author`.
	type AuthorProvider: AuthorProvider<Self::AccountId>;
}

Then, pallet-foo can use this trait to obtain the block author, without knowing where it comes from:

impl<T: Config> Pallet<T> {
	fn do_stuff_with_author() {
		let _ = T::AuthorProvider::author();
	}
}

Then, if pallet-author implements this glue-trait:

impl<T: pallet_author::Config> AuthorProvider<T::AccountId> for pallet_author::Pallet<T> {
	fn author() -> T::AccountId {
		pallet_author::Pallet::<T>::author()
	}
}

And upon the creation of the runtime, the two pallets are linked together as such:

impl pallet_foo_loose::Config for Runtime {
	type AuthorProvider = pallet_author::Pallet<Runtime>;
	// which is also equivalent to
	// type AuthorProvider = PalletAuthor;
}

Crucially, when using loose coupling, we gain the flexibility of providing different implementations of AuthorProvider, such that different users of a pallet-foo can use different ones, without any code change being needed. For example, in the code snippets of this module, you can find OtherAuthorProvider, which is an alternative implementation of AuthorProvider.

impl<AccountId> AuthorProvider<AccountId> for OtherAuthorProvider {
	fn author() -> AccountId {
		todo!("somehow get the block author here")
	}
}

A common pattern in polkadot-sdk is to provide an implementation of such glu traits for the unit type as a “default/test behavior”.

impl<AccountId> AuthorProvider<AccountId> for () {
	fn author() -> AccountId {
		todo!("somehow get the block author here")
	}
}

Frame System

With the above information in context, we can conclude that frame_system is a special pallet that is tightly coupled with every other pallet. This is because it provides the fundamental system functionality that every pallet needs, such as some types like frame::prelude::frame_system::Config::AccountId, frame::prelude::frame_system::Config::Hash, and some functionality such as block number, etc.

Recap

To recap, consider the following rules of thumb:

• In all cases, try and break down big pallets apart with clear boundaries of responsibility. In general, it is easier to argue about multiple pallet if they only communicate together via a known trait, rather than having access to all of each others public items, such as storage and dispatchables.
• If a group of pallets is meant to work together, but is not foreseen to be generalized, or used by others, consider tightly coupling pallets, if it simplifies the development.
• If a pallet needs a functionality provided by another pallet, but multiple implementations can be foreseen, consider loosely coupling pallets.

For example, all pallets in polkadot-sdk that needed to work with currencies could have been tightly coupled with pallet_balances. But, polkadot-sdk also provides pallet_assets (and more implementations by the community), therefore all pallets use traits to loosely couple with balances or assets pallet. More on this in crate::reference_docs::frame_tokens.

Further References

• https://www.youtube.com/watch?v=0eNGZpNkJk4
• https://substrate.stackexchange.com/questions/922/pallet-loose-couplingtight-coupling-and-missing-traits

Modules

• pallet_author
  The pallet module in each FRAME pallet hosts the most important items needed to construct this pallet.
• pallet_foo
  The pallet module in each FRAME pallet hosts the most important items needed to construct this pallet.
• pallet_foo_loose
  The pallet module in each FRAME pallet hosts the most important items needed to construct this pallet.
• pallet_foo_tight
  The pallet module in each FRAME pallet hosts the most important items needed to construct this pallet.
• runtime

Structs

• OtherAuthorProvider

Traits

• AuthorProvider
  Abstraction over “something that can provide the block author”.