diff --git a/docs/sdk/src/reference_docs/frame_currency.rs b/docs/sdk/src/reference_docs/frame_currency.rs index 6987d51aec82..d62c234c3fee 100644 --- a/docs/sdk/src/reference_docs/frame_currency.rs +++ b/docs/sdk/src/reference_docs/frame_currency.rs @@ -1,8 +1,55 @@ -//! FRAME Currency Abstractions and Traits +//! # FRAME Currency Abstractions and Traits //! -//! Notes: +//! Currency related traits in FRAME provide standardized interfaces for implementing various +//! currency functionalities. The fundamental reason to have these traits is to allow pallets to +//! utilize a token without relying on the implementation detail. Or else we could have a perfectly +//! fine runtime without these traits. +//! These traits enable developers to create, transfer, and manage different forms of digital assets +//! within the blockchain environment, ensuring that the economic aspects of the chain are robust +//! and adaptable to different use cases. + //! -//! - History, `Currency` trait. -//! - `Hold` and `Freeze` with diagram. -//! - `HoldReason` and `FreezeReason` -//! - This footgun: +//! ## The Currency Trait +//! +//! The [`Currency`][4] trait was initially introduced in Substrate to manage the native token +//! balances. This trait was later deprecated in favor of the [`fungible`][3] traits in Substrate's +//! PR [#12951](https://github.com/paritytech/substrate/pull/12951), the main reason for this is +//! that the deprecated trait is only sensible in a system that has just one currency type. This +//! shift is part of a broader initiative to enhance token management capabilities within the +//! framework. This deprecation is aimed at providing improved safety and more flexibility for +//! managing assets, beyond the capabilities of the original [`Currency`][4] trait. This transition +//! enables more diverse economic models in Substrate. For more details, you can view the discussion +//! on the [Tokens Horizon issue](https://github.com/paritytech/polkadot-sdk/issues/327). The +//! [`Currency`][4] trait is still available in Substrate, but it is recommended to use the +//! **fungible** traits instead. The [deprecation PR](https://github.com/paritytech/substrate/pull/12951) +//! has a dedicated section on upgrading from **Currency** to **fungible**. Besides, this +//! [issue](https://github.com/paritytech/polkadot-sdk/issues/226) lists the pallets that have been +//! upgraded to the **fungible** traits, and the ones that are still using the [`Currency`][4] +//! trait. There one could find the relevant code examples for upgrading. +//! +//! ## Fungible Traits +//! +//! The [`fungible`][3] traits are designed for managing currency types, providing a streamlined +//! approach for single-asset operations. Fungible is currently preferred over currency as the +//! latter is deprecated. +//! +//! #### Holds and Freezes +//! +//! Learn more about this two concepts in +//! [`frame_support::traits::tokens::fungible::hold`][1] and +//! [`frame_support::traits::tokens::fungible::freeze`][2]. +//! +//! ## Balances Pallet +//! The [`pallet_balances`](../../../pallet_balances/index.html) is a key component in FRAME. It +//! is designed for managing native token balances. It plays a crucial role in tracking and +//! manipulating the balance of accounts, providing functionalities essential for a wide range of +//! financial operations. The key functions of +//! [`pallet_balances`](../../../pallet_balances/index.html) include transferring tokens between +//! accounts, checking account balances, and adjusting balances for staking or fees. This pallet +//! implements the [`fungible`][3] traits, aligning with the standardized approach for asset +//! management in Substrate. +//! +//! [1]: ../../../frame_support/traits/tokens/fungible/hold/index.html +//! [2]: ../../../frame_support/traits/tokens/fungible/freeze/index.html +//! [3]: ../../../frame_support/traits/tokens/fungible/index.html +//! [4]: ../../../frame_support/traits/tokens/currency/index.html diff --git a/substrate/frame/support/src/traits/tokens/fungible/freeze.rs b/substrate/frame/support/src/traits/tokens/fungible/freeze.rs index 8b542ee4c606..ed59611abfa2 100644 --- a/substrate/frame/support/src/traits/tokens/fungible/freeze.rs +++ b/substrate/frame/support/src/traits/tokens/fungible/freeze.rs @@ -15,7 +15,26 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! # Freeze +//! //! The traits for putting freezes within a single fungible token class. +//! +//! Freezes can overlap with [Holds](crate::traits::fungible::hold). Since Holds are designed to be +//! infallibly slashed, this means that any logic using a `Freeze` must handle the possibility of +//! the frozen amount being reduced, potentially to zero. A permissionless function should be +//! provided in order to allow bookkeeping to be updated in this instance. E.g. some balance is +//! frozen when it is used for voting, one could use held balance for voting, but nothing prevents +//! this frozen balance from being reduced if the overlapping hold is slashed. +//! +//! ``` +//! |__total__________________________________| +//! |__on_hold__|_____________free____________| +//! |__________frozen___________| +//! |__on_hold__|__ed__| +//! ``` +//! +//! Freezes require a `Reason`, which is configurable and is expected to be an enum aggregated +//! across all pallet instances of the runtime. use scale_info::TypeInfo; use sp_arithmetic::{ diff --git a/substrate/frame/support/src/traits/tokens/fungible/hold.rs b/substrate/frame/support/src/traits/tokens/fungible/hold.rs index 6da652d2998d..e5157c25094d 100644 --- a/substrate/frame/support/src/traits/tokens/fungible/hold.rs +++ b/substrate/frame/support/src/traits/tokens/fungible/hold.rs @@ -15,7 +15,18 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! # Holds +//! //! The traits for putting holds within a single fungible token class. +//! +//! Holds are explicitly designed to be infallibly slashed. They do not contribute to the ED but +//! do require a provider reference, removing any possibility of account reference counting from +//! being problematic for a slash. They are also always named, ensuring different holds do not +//! accidentally slash each other's balances. E.g. some balance is held when it is put to staking, +//! it does not contribute to the ED, but it is slashed when the staker misbehaves. +//! +//! Holds require a `Reason`, which is configurable and is expected to be an enum aggregated across +//! all pallet instances of the runtime. use crate::{ ensure, diff --git a/substrate/frame/support/src/traits/tokens/fungible/mod.rs b/substrate/frame/support/src/traits/tokens/fungible/mod.rs index ba4a2e5e21a2..24e3f9b29184 100644 --- a/substrate/frame/support/src/traits/tokens/fungible/mod.rs +++ b/substrate/frame/support/src/traits/tokens/fungible/mod.rs @@ -15,7 +15,13 @@ // See the License for the specific language governing permissions and // limitations under the License. -//! The traits for dealing with a single fungible token class and any associated types. +//! # Fungible Traits +//! +//! **The traits for dealing with a single fungible token class and any associated types.** +//! +//! This trait includes key methods for asset management, like transfer, balance check, and minting. +//! It's particularly useful in scenarios involving a single currency type, simplifying the +//! implementation and management process. //! //! ### User-implememted traits //! - `Inspect`: Regular balance inspector functions. diff --git a/substrate/frame/support/src/traits/tokens/fungibles/freeze.rs b/substrate/frame/support/src/traits/tokens/fungibles/freeze.rs index b07d20d6c41c..4f20263aacc4 100644 --- a/substrate/frame/support/src/traits/tokens/fungibles/freeze.rs +++ b/substrate/frame/support/src/traits/tokens/fungibles/freeze.rs @@ -15,7 +15,11 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! # Freeze +//! //! The traits for putting freezes within a single fungible token class. +//! +//! Refer to [`frame_support::traits::tokens::fungible::freeze`] for more info. use crate::{ensure, traits::tokens::Fortitude}; use scale_info::TypeInfo; diff --git a/substrate/frame/support/src/traits/tokens/fungibles/hold.rs b/substrate/frame/support/src/traits/tokens/fungibles/hold.rs index 1efd1594213c..02258ca3b6f5 100644 --- a/substrate/frame/support/src/traits/tokens/fungibles/hold.rs +++ b/substrate/frame/support/src/traits/tokens/fungibles/hold.rs @@ -15,7 +15,11 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! # Hold +//! //! The traits for putting holds within a single fungible token class. +//! +//! Refer to [`frame_support::traits::tokens::fungible::hold`] for more info. use crate::{ ensure, diff --git a/substrate/frame/support/src/traits/tokens/fungibles/mod.rs b/substrate/frame/support/src/traits/tokens/fungibles/mod.rs index 1db0706ba4fd..31b89ef8d5e8 100644 --- a/substrate/frame/support/src/traits/tokens/fungibles/mod.rs +++ b/substrate/frame/support/src/traits/tokens/fungibles/mod.rs @@ -15,7 +15,14 @@ // See the License for the specific language governing permissions and // limitations under the License. -//! The traits for sets of fungible tokens and any associated types. +//! # Fungibles Traits +//! +//! **The traits for sets of fungible tokens and any associated types.** +//! +//! Offers a comprehensive solution for managing multiple asset types within a single system. +//! It's more complex than the [`fungible`](crate::traits::tokens::fungible) trait, suited for +//! environments where diverse asset types coexist and interact. This trait is essential in +//! multi-currency contexts, providing the necessary tools for intricate asset management. pub mod approvals; mod enumerable;