From 8c94c41046672dcbdcf4d94c10d6b1631e2b55fa Mon Sep 17 00:00:00 2001 From: Juan Girini Date: Fri, 8 Dec 2023 16:04:31 +0100 Subject: [PATCH 1/7] initial currency outline --- docs/sdk/src/reference_docs/frame_currency.rs | 69 +++++++++++++++++++ 1 file changed, 69 insertions(+) diff --git a/docs/sdk/src/reference_docs/frame_currency.rs b/docs/sdk/src/reference_docs/frame_currency.rs index ba181373062f..a4bc5c12e098 100644 --- a/docs/sdk/src/reference_docs/frame_currency.rs +++ b/docs/sdk/src/reference_docs/frame_currency.rs @@ -6,3 +6,72 @@ //! - `Hold` and `Freeze` with diagram. //! - `HoldReason` and `FreezeReason` //! - This footgun: https://github.com/paritytech/polkadot-sdk/pull/1900#discussion_r1363783609 +//! +//! +//! +//! This document provides an in-depth guide for Substrate developers on the implementation and +//! functionalities of currency management in FRAME-based runtimes. It focuses on the transition +//! from the `Currency` trait to the `fungible` traits, and the utilization of +//! pallet_balances and pallet_assets. +//! +//! 1. Overview of FRAME-based Runtimes +//! - Brief introduction to FRAME +//! - Importance of currency management in blockchain development +//! - Overview of currency traits in Substrate +//! 2. **The `Currency` Trait** +//! +//! The `Currency` trait was initially introduced in Substrate to manage the native token +//! balances. This trait was later deprecated in favor of the `fungible` 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` 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` 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` trait. There one could find the relevant code examples for +//! upgrading. +//! +//! 3. The fungible and fungibles Traits +//! - Definition and distinction between fungible and fungibles +//! - fungible: For managing single currency types +//! - fungibles: For handling multiple types of currencies or assets +//! 3.1 fungible Trait +//! - Detailed explanation of the trait +//! - Key methods and their functionalities +//! - Use cases and implementation examples +//! 3.2 fungibles Trait +//! - Comprehensive overview +//! - Comparison with the fungible trait +//! - Implementation in multi-currency contexts +//! 4. Pallet Balances (pallet_balances) +//! - Introduction to pallet_balances +//! - Role in managing native token balances +//! - Key functions and their uses +//! - Integration with the fungible trait +//! - Example code snippets and use cases +//! 5. Pallet Assets (pallet_assets) +//! - Purpose and functionalities of pallet_assets +//! - Handling multiple asset types +//! - Interaction with fungibles trait +//! - Configuration and customization options +//! - Practical examples and code snippets +//! 6. Migration Strategies +//! - Guidance for migrating from Currency to fungible and fungibles +//! - Best practices and common pitfalls +//! - Case studies or examples of successful migrations +//! 7. Advanced Topics +//! - Cross-chain asset management +//! - Interaction with other FRAME pallets +//! - Security considerations and best practices +//! 8. Conclusion +//! - Recap of key points +//! - Future developments in currency management in Substrate +//! - Additional resources and community support +//! - References +//! - Official Substrate documentation +//! - Relevant GitHub repositories and code examples +//! - Community discussions and tutorials From c94350a7c62b1c110e1fee71a61713e3307addb7 Mon Sep 17 00:00:00 2001 From: Juan Girini Date: Mon, 11 Dec 2023 18:40:55 +0100 Subject: [PATCH 2/7] intial frame currency --- docs/sdk/src/reference_docs/frame_currency.rs | 172 ++++++++++-------- 1 file changed, 97 insertions(+), 75 deletions(-) diff --git a/docs/sdk/src/reference_docs/frame_currency.rs b/docs/sdk/src/reference_docs/frame_currency.rs index a4bc5c12e098..54f8e977c8fe 100644 --- a/docs/sdk/src/reference_docs/frame_currency.rs +++ b/docs/sdk/src/reference_docs/frame_currency.rs @@ -1,77 +1,99 @@ //! FRAME Currency Abstractions and Traits //! -//! Notes: -//! -//! - History, `Currency` trait. -//! - `Hold` and `Freeze` with diagram. -//! - `HoldReason` and `FreezeReason` -//! - This footgun: https://github.com/paritytech/polkadot-sdk/pull/1900#discussion_r1363783609 -//! -//! -//! -//! This document provides an in-depth guide for Substrate developers on the implementation and -//! functionalities of currency management in FRAME-based runtimes. It focuses on the transition -//! from the `Currency` trait to the `fungible` traits, and the utilization of -//! pallet_balances and pallet_assets. -//! -//! 1. Overview of FRAME-based Runtimes -//! - Brief introduction to FRAME -//! - Importance of currency management in blockchain development -//! - Overview of currency traits in Substrate -//! 2. **The `Currency` Trait** -//! -//! The `Currency` trait was initially introduced in Substrate to manage the native token -//! balances. This trait was later deprecated in favor of the `fungible` 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` 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` 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` trait. There one could find the relevant code examples for -//! upgrading. -//! -//! 3. The fungible and fungibles Traits -//! - Definition and distinction between fungible and fungibles -//! - fungible: For managing single currency types -//! - fungibles: For handling multiple types of currencies or assets -//! 3.1 fungible Trait -//! - Detailed explanation of the trait -//! - Key methods and their functionalities -//! - Use cases and implementation examples -//! 3.2 fungibles Trait -//! - Comprehensive overview -//! - Comparison with the fungible trait -//! - Implementation in multi-currency contexts -//! 4. Pallet Balances (pallet_balances) -//! - Introduction to pallet_balances -//! - Role in managing native token balances -//! - Key functions and their uses -//! - Integration with the fungible trait -//! - Example code snippets and use cases -//! 5. Pallet Assets (pallet_assets) -//! - Purpose and functionalities of pallet_assets -//! - Handling multiple asset types -//! - Interaction with fungibles trait -//! - Configuration and customization options -//! - Practical examples and code snippets -//! 6. Migration Strategies -//! - Guidance for migrating from Currency to fungible and fungibles -//! - Best practices and common pitfalls -//! - Case studies or examples of successful migrations -//! 7. Advanced Topics -//! - Cross-chain asset management -//! - Interaction with other FRAME pallets -//! - Security considerations and best practices -//! 8. Conclusion -//! - Recap of key points -//! - Future developments in currency management in Substrate -//! - Additional resources and community support -//! - References -//! - Official Substrate documentation -//! - Relevant GitHub repositories and code examples -//! - Community discussions and tutorials +//! TODO: +//! +//! - [x] History, `Currency` trait. +//! - [ ] `Hold` and `Freeze` with diagram. +//! - [x] `HoldReason` and `FreezeReason` +//! - [ ] This footgun: https://github.com/paritytech/polkadot-sdk/pull/1900#discussion_r1363783609 +//! +//! +//! +//! 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. +//! +//! ## 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) and +//! [`fungibles`](../../../frame_support/traits/tokens/fungibles/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 and Fungibles Traits +//! +//! The [`fungible`](../../../frame_support/traits/tokens/fungible/index.html) trait is designed for +//! managing single currency types, providing a streamlined approach for single-asset operations. +//! The [`fungibles`](../../../frame_support/traits/tokens/fungibles/index.html) trait, in contrast, +//! allows for handling multiple types of currencies or assets, offering greater flexibility in +//! multi-asset environments. +//! +//! #### Fungible Trait: +//! +//! 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. +//! +//! #### Fungibles Trait: +//! +//! Offers a comprehensive solution for managing multiple asset types within a single system. +//! It's more complex than the +//! [`fungible`](../../../frame_support/traits/tokens/fungible/index.html) 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. +//! +//! #### Holds and Freezes +//! +//! *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. +//! +//! *Freezes* can overlap with *Holds*. 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. +//! +//! Both *Holds* and *Freezes* require an identifier, `HoldReason` and `FreezeReason` respectively, +//! which is configurable and is expected to be an enum aggregated across all pallet instances of +//! the runtime. +//! +//! To understand this with an example +//! +//! ## Common Pallets +//! +//! #### 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 +//! integrates with the [`fungible`](../../../frame_support/traits/tokens/fungible/index.html) +//! trait, aligning with the standardized approach for asset management in Substrate. +//! +//! #### Pallet Assets +//! The [`pallet_assets`](../../../pallet_assets/index.html) is designed to manage +//! multiple asset types within a blockchain. It provides functionalities for asset creation, +//! management, and destruction. This pallet allows for the handling of a diverse range of assets, +//! facilitating complex economic models and token systems. Its interaction with the +//! [`fungibles`](../../../frame_support/traits/tokens/fungibles/index.html) trait enables seamless +//! integration with multi-asset systems. From 14f11bb5439e544aceba04e967c85fd400e16aeb Mon Sep 17 00:00:00 2001 From: Juan Girini Date: Thu, 14 Dec 2023 18:20:55 +0100 Subject: [PATCH 3/7] reorganize fungibles docs --- docs/sdk/src/reference_docs/frame_currency.rs | 37 +++---------------- .../src/traits/tokens/fungible/freeze.rs | 19 ++++++++++ .../src/traits/tokens/fungible/hold.rs | 11 ++++++ .../support/src/traits/tokens/fungible/mod.rs | 8 +++- .../src/traits/tokens/fungibles/freeze.rs | 4 ++ .../src/traits/tokens/fungibles/hold.rs | 4 ++ .../src/traits/tokens/fungibles/mod.rs | 9 ++++- 7 files changed, 58 insertions(+), 34 deletions(-) diff --git a/docs/sdk/src/reference_docs/frame_currency.rs b/docs/sdk/src/reference_docs/frame_currency.rs index 54f8e977c8fe..c5b91828447a 100644 --- a/docs/sdk/src/reference_docs/frame_currency.rs +++ b/docs/sdk/src/reference_docs/frame_currency.rs @@ -43,40 +43,13 @@ //! allows for handling multiple types of currencies or assets, offering greater flexibility in //! multi-asset environments. //! -//! #### Fungible Trait: -//! -//! 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. -//! -//! #### Fungibles Trait: -//! -//! Offers a comprehensive solution for managing multiple asset types within a single system. -//! It's more complex than the -//! [`fungible`](../../../frame_support/traits/tokens/fungible/index.html) 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. -//! //! #### Holds and Freezes //! -//! *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. -//! -//! *Freezes* can overlap with *Holds*. 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. -//! -//! Both *Holds* and *Freezes* require an identifier, `HoldReason` and `FreezeReason` respectively, -//! which is configurable and is expected to be an enum aggregated across all pallet instances of -//! the runtime. -//! -//! To understand this with an example +//! Learn more about this two concepts in +//! [frame_support::traits::tokens::fungible::hold](../../../frame_support/traits/tokens/fungible/ +//! hold/index.html) and +//! [frame_support::traits::tokens::fungible::freeze](../../../frame_support/traits/tokens/fungible/ +//! freeze/index.html). //! //! ## Common Pallets //! 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 61b75fd6563c..859f2898e525 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 4fd6ef43a15f..e5c941b83a7e 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; From 9a940420a6bcde5f4ffbeeabcd48a32fd1802465 Mon Sep 17 00:00:00 2001 From: Juan Girini Date: Fri, 15 Dec 2023 16:47:00 +0100 Subject: [PATCH 4/7] remove fungibles and assets --- docs/sdk/src/reference_docs/frame_currency.rs | 50 ++++++------------- 1 file changed, 14 insertions(+), 36 deletions(-) diff --git a/docs/sdk/src/reference_docs/frame_currency.rs b/docs/sdk/src/reference_docs/frame_currency.rs index c5b91828447a..77bb74acfc59 100644 --- a/docs/sdk/src/reference_docs/frame_currency.rs +++ b/docs/sdk/src/reference_docs/frame_currency.rs @@ -1,29 +1,19 @@ -//! FRAME Currency Abstractions and Traits -//! -//! TODO: -//! -//! - [x] History, `Currency` trait. -//! - [ ] `Hold` and `Freeze` with diagram. -//! - [x] `HoldReason` and `FreezeReason` -//! - [ ] This footgun: https://github.com/paritytech/polkadot-sdk/pull/1900#discussion_r1363783609 -//! -//! +//! # FRAME Currency Abstractions and Traits //! //! 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. //! -//! ## The `Currency` Trait +//! ## 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) and -//! [`fungibles`](../../../frame_support/traits/tokens/fungibles/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 +//! 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 @@ -35,13 +25,11 @@ //! still using the [`Currency`](../../../frame_support/traits/tokens/currency/index.html) trait. //! There one could find the relevant code examples for upgrading. //! -//! ## Fungible and Fungibles Traits +//! ## Fungible Traits //! -//! The [`fungible`](../../../frame_support/traits/tokens/fungible/index.html) trait is designed for -//! managing single currency types, providing a streamlined approach for single-asset operations. -//! The [`fungibles`](../../../frame_support/traits/tokens/fungibles/index.html) trait, in contrast, -//! allows for handling multiple types of currencies or assets, offering greater flexibility in -//! multi-asset environments. +//! 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 //! @@ -51,22 +39,12 @@ //! [frame_support::traits::tokens::fungible::freeze](../../../frame_support/traits/tokens/fungible/ //! freeze/index.html). //! -//! ## Common Pallets -//! -//! #### Pallet Balances +//! ## 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 -//! integrates with the [`fungible`](../../../frame_support/traits/tokens/fungible/index.html) -//! trait, aligning with the standardized approach for asset management in Substrate. -//! -//! #### Pallet Assets -//! The [`pallet_assets`](../../../pallet_assets/index.html) is designed to manage -//! multiple asset types within a blockchain. It provides functionalities for asset creation, -//! management, and destruction. This pallet allows for the handling of a diverse range of assets, -//! facilitating complex economic models and token systems. Its interaction with the -//! [`fungibles`](../../../frame_support/traits/tokens/fungibles/index.html) trait enables seamless -//! integration with multi-asset systems. +//! implements the [`fungible`](../../../frame_support/traits/tokens/fungible/index.html) +//! traits, aligning with the standardized approach for asset management in Substrate. From 6babc75d8097c2f03e63805253994d5faa325a45 Mon Sep 17 00:00:00 2001 From: Juan Girini Date: Mon, 8 Jan 2024 07:09:52 -0300 Subject: [PATCH 5/7] fix rustdocs links --- docs/sdk/src/reference_docs/frame_currency.rs | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/sdk/src/reference_docs/frame_currency.rs b/docs/sdk/src/reference_docs/frame_currency.rs index 77bb74acfc59..0b978784f5a8 100644 --- a/docs/sdk/src/reference_docs/frame_currency.rs +++ b/docs/sdk/src/reference_docs/frame_currency.rs @@ -34,10 +34,8 @@ //! #### Holds and Freezes //! //! Learn more about this two concepts in -//! [frame_support::traits::tokens::fungible::hold](../../../frame_support/traits/tokens/fungible/ -//! hold/index.html) and -//! [frame_support::traits::tokens::fungible::freeze](../../../frame_support/traits/tokens/fungible/ -//! freeze/index.html). +//! [frame_support::traits::tokens::fungible::hold](../../../frame_support/traits/tokens/fungible/hold/index.html) +//! and [frame_support::traits::tokens::fungible::freeze](../../../frame_support/traits/tokens/fungible/freeze/index.html). //! //! ## Pallet Balances //! The [`pallet_balances`](../../../pallet_balances/index.html) is a key component in FRAME. It From 933a8e26441d70273c7f231ce87b046b17f5ce3d Mon Sep 17 00:00:00 2001 From: Juan Girini Date: Mon, 8 Jan 2024 07:29:42 -0300 Subject: [PATCH 6/7] fix rustdocs links --- docs/sdk/src/reference_docs/frame_currency.rs | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/sdk/src/reference_docs/frame_currency.rs b/docs/sdk/src/reference_docs/frame_currency.rs index 0b978784f5a8..8b6e21ccca2c 100644 --- a/docs/sdk/src/reference_docs/frame_currency.rs +++ b/docs/sdk/src/reference_docs/frame_currency.rs @@ -34,8 +34,8 @@ //! #### Holds and Freezes //! //! Learn more about this two concepts in -//! [frame_support::traits::tokens::fungible::hold](../../../frame_support/traits/tokens/fungible/hold/index.html) -//! and [frame_support::traits::tokens::fungible::freeze](../../../frame_support/traits/tokens/fungible/freeze/index.html). +//! [`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 @@ -46,3 +46,6 @@ //! 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 From 80ff2cec9a1e0f8c8cd97efcc45de01d39f50d44 Mon Sep 17 00:00:00 2001 From: Juan Girini Date: Tue, 9 Jan 2024 11:11:38 -0300 Subject: [PATCH 7/7] review improvements --- docs/sdk/src/reference_docs/frame_currency.rs | 52 ++++++++++--------- 1 file changed, 28 insertions(+), 24 deletions(-) diff --git a/docs/sdk/src/reference_docs/frame_currency.rs b/docs/sdk/src/reference_docs/frame_currency.rs index 8b6e21ccca2c..d62c234c3fee 100644 --- a/docs/sdk/src/reference_docs/frame_currency.rs +++ b/docs/sdk/src/reference_docs/frame_currency.rs @@ -1,35 +1,37 @@ //! # FRAME Currency Abstractions and Traits //! //! 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. +//! 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. + //! //! ## 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 +//! 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`](../../../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. +//! [`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`](../../../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. +//! 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 //! @@ -37,15 +39,17 @@ //! [`frame_support::traits::tokens::fungible::hold`][1] and //! [`frame_support::traits::tokens::fungible::freeze`][2]. //! -//! ## Pallet Balances +//! ## 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`](../../../frame_support/traits/tokens/fungible/index.html) -//! traits, aligning with the standardized approach for asset management in Substrate. +//! 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