Ref docs frame currency

docs/sdk/src/reference_docs/frame_currency.rs

@@ -1,8 +1,51 @@
-//! FRAME Currency Abstractions and Traits
+//! # FRAME Currency Abstractions and Traits
 //!
-//! Notes:
+//! Currency related traits in FRAME provide standardized interfaces for implementing various
+//! currency functionalities. 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: <https://github.com/paritytech/polkadot-sdk/pull/1900#discussion_r1363783609>
+//! ## The Currency Trait
+//!
+//! The [`Currency`](../../../frame_support/traits/tokens/currency/index.html) trait was initially
+//! introduced in Substrate to manage the native token balances. This trait was later deprecated in
+//! favor of the [`fungible`](../../../frame_support/traits/tokens/fungible/index.html) traits in
+//! Substrate's PR [#12951](https://github.com/paritytech/substrate/pull/12951). 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`](../../../frame_support/traits/tokens/currency/index.html) 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`](../../../frame_support/traits/tokens/currency/index.html) 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`](../../../frame_support/traits/tokens/currency/index.html) trait.
+//! There one could find the relevant code examples for upgrading.
+//!
+//! ## Fungible Traits
+//!
+//! The [`fungible`](../../../frame_support/traits/tokens/fungible/index.html) 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].
+//!
+//! ## Pallet Balances
+//! 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`](../../../frame_support/traits/tokens/fungible/index.html)
+//! 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

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::{

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,

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.

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;

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,

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;