wip fungible docs

docs/sdk/Cargo.toml

@@ -65,6 +65,8 @@ pallet-aura = { path = "../../substrate/frame/aura", default-features = false }
 # Pallets and FRAME internals
 pallet-timestamp = { path = "../../substrate/frame/timestamp" }
 pallet-balances = { path = "../../substrate/frame/balances" }
+pallet-assets = { path = "../../substrate/frame/assets" }
+pallet-preimage = { path = "../../substrate/frame/preimage" }
 pallet-transaction-payment = { path = "../../substrate/frame/transaction-payment" }
 pallet-utility = { path = "../../substrate/frame/utility" }
 pallet-multisig = { path = "../../substrate/frame/multisig" }

docs/sdk/src/reference_docs/frame_runtime_upgrades_and_migrations.rs

@@ -131,7 +131,6 @@
 //!
 //! TODO: Link to multi block migration example/s once PR is merged (<https://github.com/paritytech/polkadot-sdk/pull/2119>).
 //!
-//! [`GetStorageVersion`]: frame_support::traits::GetStorageVersion
 //! [`OnRuntimeUpgrade`]: frame_support::traits::OnRuntimeUpgrade
 //! [`StorageVersion`]: frame_support::traits::StorageVersion
 //! [`set_code`]: frame_system::Call::set_code

docs/sdk/src/reference_docs/mod.rs

@@ -32,6 +32,9 @@ pub mod glossary;
 /// Learn about the WASM meta-protocol of all Substrate-based chains.
 pub mod wasm_meta_protocol;
 
+/// Learn about the token-related logic in Substrate and how to use it.
+pub mod tokens_in_substrate;
+
 /// Learn about the differences between smart contracts and a FRAME-based runtime. They are both
 /// "code stored onchain", but how do they differ?
 pub mod runtime_vs_smart_contract;

docs/sdk/src/reference_docs/tokens_in_substrate.rs

@@ -34,11 +34,12 @@
 //! trait implementations.
 //!
 //! *Traits* define common interfaces that types of token should implement. For example, the
-//! [`fungible::Inspect`] trait specifies that implementations of this trait must contain methods
-//! for accessing the total issuance of the token, the balance of individual accounts, etc.
+//! [`frame_support::traits::fungible::Inspect`] trait specifies that implementations of this trait
+//! must contain methods for accessing the total issuance of the token, the balance of individual
+//! accounts, etc.
 //!
 //! *Trait implementations* are concrete implementations of these traits. For example, one of the
-//! many traits [`pallet_balances`] implements is [`fungible::Inspect`].
+//! many traits [`pallet_balances`] implements is [`frame_support::traits::fungible::Inspect`].
 //!
 //! The distinction between traits and trait implementations is helpful because it allows pallets
 //! and other logic to be generic over their dependencies, avoiding cumbersome and unwieldy tight
@@ -82,9 +83,15 @@
 //!
 //! ## Non-Fungible Tokens in Substrate
 //!
-//! The [`pallet_uniques`] is recommended to use for all NFT use cases in Substrate.
+//! [`pallet_uniques`] is recommended to use for all NFT use cases in Substrate.
 //! See the crate documentation for more info about this pallet.
 //!
-//! The [`pallet_nfts`] is deprecatd and should not be used.
+//! [`pallet_nfts`] is deprecated and should not be used.
 //!
-//! akkk
+//! # What Next?
+//!
+//! - If you are interested in implementing a single fungible token, continue reading the
+//!   [`frame_support::traits::fungible`] and [`pallet_balances`] docs.
+//! - If you are interested in implementing a set of fungible tokens, continue reading the
+//!   [`frame_support::traits::fungibles`] trait and [`pallet_assets`] docs.
+//! - If you are interested in implementing an NFT, continue reading the [`pallet_uniques`] docs.

substrate/frame/balances/src/lib.rs

@@ -157,6 +157,8 @@
 //!
 //! Note, you may find the Balances pallet still functions with an ED of zero in some circumstances,
 //! however this is not a configuration which is generally supported, nor will it be.
+//!
+//! [`tokens_in_substrate`]: ../polkadot_sdk_docs/reference_docs/tokens_in_substrate/index.html
 
 #![cfg_attr(not(feature = "std"), no_std)]
 mod benchmarking;

substrate/frame/support/src/traits/tokens/fungible/mod.rs

@@ -41,9 +41,75 @@
 //!   funds must be removed from an account before it is known precisely what should be done with
 //!   them.
 //!
-//! # Holds vs. Freezes
+//! ## Terminology
 //!
-//! TODO: Differentiate between the two.
+//! ### Total Balance
+//!
+//! The sum of an accounts free and held balances.
+//!
+//! ### Free Balance
+//!
+//! A portion of an accounts total balance that is not held.
+//!
+//! ### Held Balance
+//!
+//! A portion of a users total balance that is not free.
+//!
+//! Multiple holds stack rather than overlay. This means that if an account has
+//! 3 locks for 100 units, the account can spend it's funds for any reason down to 300 units, at
+//! which point the holds will start to come into play.
+//!
+//! Multiple holds are stack on top of another (cumulative) rather than overlay another.
+//!
+//! ### Frozen Balance
+//!
+//! An minimum amount a user should not be allowed to withdraw below.
+//!
+//! Multiple freezes overlay rather than stack on top of another. This means that if an account has
+//! 3 locks for 100 units, the account can spend it's funds for any reason down to 100 units, at
+//! which point the freezes will start to come into play.
+//!
+//! ### Minimum Balance (a.k.a. Existential Deposit, a.k.a. ED)
+//!
+//! The minimum amount of balance that an account must have to exist.
+//!
+//! ### Untouchable Balance
+//!
+//! The part of a users free balance they cannot spend, due to ED or Freeze/s.
+//!
+//! ### Spendable Balance
+//!
+//! The part of a users free balance they can spend.
+//!
+//! ## Visualising Balance Components Together 💫
+//!
+//! ```ignore
+//! |__total__________________________________|
+//! |__on_hold__|_____________free____________|
+//! |__________frozen___________|
+//! |__on_hold__|__ed__|
+//!             |__untouchable__|__spendable__|
+//! ```
+//!
+//! ## Holds vs. Freezes
+//!
+//! Both holds and freezes are used to prevent an account from using some of its balance.
+//!
+//! The primary distinction between the two are that:
+//! - Holds are cumulative (do not overlap) and are distinct from the free balance
+//! - Freezes are not cumulative, and can overlap with each other or with holds
+//!
+//! ```ignore
+//! |__total_____________________________|
+//! |__hold_a__|__hold_b__|_____free_____|
+//! |__on_hold____________|     // <- the sum of all holds
+//! |__freeze_a_______________|
+//! |__freeze_b____|
+//! |__freeze_c________|
+//! |__frozen_________________| // <- the max of all freezes
+//! ```
+//!
+//! [`tokens_in_substrate`]: ../../../../polkadot_sdk_docs/reference_docs/tokens_in_substrate/index.html
 
 pub mod conformance_tests;
 pub mod freeze;