Skip to content

Commit

Permalink
deprecate pages related to pallet coupling
Browse files Browse the repository at this point in the history
  • Loading branch information
kianenigma authored Mar 1, 2024
1 parent 426da55 commit c19679d
Show file tree
Hide file tree
Showing 3 changed files with 49 additions and 22 deletions.
9 changes: 9 additions & 0 deletions content/md/en/docs/build/pallet-coupling.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,15 @@ keywords:
- pallet design
---

<div class="warning">
<p>
<strong>⚠️ WARNING:</strong> This page contains potentially outdated information. Reading it might still be useful, yet we suggest taking it with a grain of salt.
</p>
<p>
Please refer to the <a href="https://paritytech.github.io/polkadot-sdk/master/polkadot_sdk_docs/reference_docs/frame_pallet_coupling/index.html">`polkadot-sdk-docs` crate</a> for the most up-to-date documentation on this topic.
</p>
</div>

The term **coupling** is often used to describe the degree to which two software modules depend on each other.
For example, in object-oriented programming tight coupling and loose coupling are used to describe the relationship between objects classes:

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,15 @@ description:
keywords:
---

<div class="warning">
<p>
<strong>⚠️ WARNING:</strong> This page contains potentially outdated information. Reading it might still be useful, yet we suggest taking it with a grain of salt.
</p>
<p>
Please refer to the <a href="https://paritytech.github.io/polkadot-sdk/master/polkadot_sdk_docs/reference_docs/frame_pallet_coupling/index.html">`polkadot-sdk-docs` crate</a> for the most up-to-date documentation on this topic.
</p>
</div>

This guide demonstrates how to reuse a function or type from one pallet in another pallet using a technique called **loose coupling**.

Loose coupling enables you to reuse part of the logic defined in an external pallet inside your current pallet.
Expand All @@ -27,28 +36,28 @@ In this example, you are reusing `Currency` trait information from the `frame-su
To configure your workspace manifest:

1. Open a terminal shell on your computer and navigate to the root directory for your project.

2. Open the manifest `Cargo.toml` file in a text editor.

3. Add the you are loosely coupling with to the dependencies.

For example:

```text
[dependencies]
frame-support = { default-features = false, git = "https://github.com/paritytech/substrate.git", branch = "polkadot-v1.0.0"}
```

Note that you should use the same branch and version information for all of the pallets to ensure that the imported pallets are compatible with each other.
Using pallets from different branches can result in compiler errors.
This example illustrates adding the `frame-support` pallet to the `Cargo.toml` file if the other pallets use `branch = "polkadot-v1.0.0"`.

Because the build process compiles both a standard binary and the WebAssembly target, you must also include `frame-support/std` in the features for your pallet.

1. Add `frame-support/std` to the `std` features for your pallet.

For example:

```text
[features]
default = ["std"]
Expand All @@ -66,11 +75,11 @@ In this example, you want to use the [`Currency`](https://paritytech.github.io/s
To import a trait from another pallet:

1. Open a terminal shell on your computer and navigate to the root directory for your project.

2. Open the `src/lib.rs` file for your current pallet in a text editor.

3. Import the `Currency` trait by adding the following line:

```rust
use frame_support::traits::Currency;
```
Expand All @@ -84,13 +93,13 @@ The next step is to create a type that is bound by the type you want to expose i
To update the configuration trait for your pallet:

1. Open a terminal shell on your computer and navigate to the root directory for your project.

2. Open the `src/lib.rs` file for your current pallet in a text editor.

3. Create a type to use in your pallet that is bound by the type you want to access in the external pallet:

For example:

```rust
pub trait Config: frame_system::Config {
// --snip--
Expand All @@ -101,14 +110,14 @@ To update the configuration trait for your pallet:
```

5. Use a method that the trait of your loosely-coupled pallet provides with the type you've created to access the method.

For example:

```rust
// Use the getter from `my-pallet`
let total_balance = T::LocalCurrency::total_issuance();
```

In this example, [`total_issuance`](https://paritytech.github.io/substrate/master/frame_support/traits/tokens/currency/trait.Currency.html#tymethod.total_issuance) is a method that the `Currency` trait exposes from the `frame_support` pallet.

1. Save your changes and close the `src/lib.rs` file for your project.
Expand All @@ -120,19 +129,19 @@ After you have completed the updates in your project, you are ready to implement
To update the runtime configuration for your pallet:

1. Open a terminal shell on your computer and navigate to the root directory for the node template.

2. Open the `runtime/src/lib.rs` file in a text editor.

1. Add the runtime configuration for your pallet to specify the `LocalCurrency` type to use the implementation defined for the `Balances` pallet.

```rust
impl my_pallet::Config for Runtime {
type LocalCurrency = Balances;
}
```

1. Check the `Balances` definition inside `construct_runtime!` macro.

```rust
construct_runtime! (
pub enum Runtime where
Expand All @@ -146,13 +155,13 @@ To update the runtime configuration for your pallet:
```

In this example, your pallet can inherit the implementation of the `Currency` trait from the [`pallet_balances`](https://paritytech.github.io/substrate/master/pallet_balances/index.html#implementations-1) pallet and access methods from the loosely-coupled `frame-support` pallet.
By default, the `construct_runtime!` macro includes all pallet attributes for all pallets listed in the macro definition.

By default, the `construct_runtime!` macro includes all pallet attributes for all pallets listed in the macro definition.

## Examples

- [`EnsureOrigin`](https://paritytech.github.io/substrate/master/frame_support/traits/trait.EnsureOrigin.html) trait in the [Democracy pallet](https://github.com/paritytech/polkadot-sdk/blob/master/substrate/frame/democracy/src/lib.rs#L298-L335)
- [Weighting methods](https://github.com/paritytech/polkadot-sdk/blob/master/substrate/frame/identity/src/weights.rs#L46-L64) in the [Identity pallet](https://github.com/paritytech/polkadot-sdk/blob/master/substrate/frame/identity/src/lib.rs#L149-L151).
- [Weighting methods](https://github.com/paritytech/polkadot-sdk/blob/master/substrate/frame/identity/src/weights.rs#L46-L64) in the [Identity pallet](https://github.com/paritytech/polkadot-sdk/blob/master/substrate/frame/identity/src/lib.rs#L149-L151).
-[`KeyOwnerProofSystem`](https://paritytech.github.io/substrate/master/frame_support/traits/trait.KeyOwnerProofSystem.html) in [Grandpa pallet](https://github.com/paritytech/polkadot-sdk/blob/master/substrate/frame/grandpa/src/lib.rs#L106).

## Resources
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,15 @@ description:
keywords:
---

<div class="warning">
<p>
<strong>⚠️ WARNING:</strong> This page contains potentially outdated information. Reading it might still be useful, yet we suggest taking it with a grain of salt.
</p>
<p>
Please refer to the <a href="https://paritytech.github.io/polkadot-sdk/master/polkadot_sdk_docs/reference_docs/frame_pallet_coupling/index.html">`polkadot-sdk-docs` crate</a> for the most up-to-date documentation on this topic.
</p>
</div>

Tight coupling two pallets is a technique to write pallets that re-use types and methods from an existing pallet.

It is useful for breaking up some runtime logic into separate pallets that need access to common type and methods.
Expand Down

0 comments on commit c19679d

Please sign in to comment.