## Module frame_pallet_coupling

Source
Expand description

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::pezkuwi_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::pezkuwi_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 pezkuwi-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 `pezkuwi-sdk` that needed to work with currencies could have been tightly coupled with [`pallet_balances`]. But, `pezkuwi-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://exchange.pezkuwichain.app/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”.