change(prdoc): apply suggestions and clarify changes in balance model

paritytech · Nov 3, 2024 · 608b688 · 608b688
1 parent 7d84bee
commit 608b688
Showing 1 changed file with 16 additions and 3 deletions.
diff --git a/prdoc/pr_4530.prdoc b/prdoc/pr_4530.prdoc
@@ -5,9 +5,22 @@ doc:
     description: |
         This change creates the `pallet-assets-holder` pallet, as well as changes `pallet-assets`
         to support querying held balances via a new trait: `BalanceOnHold`.
+
+        ## Changes in Balance Model
 
-        It also adjusts the balance model implementation for fungible
-        sets (see [sdk docs](https://paritytech.github.io/polkadot-sdk/master/frame_support/traits/tokens/fungible/index.html#visualising-balance-components-together-)).
+        The change also adjusts the balance model implementation for fungible sets. This aligns the
+        calculation of the _spendable_ balance (that can be reduced either via withdrawals, like
+        paying for fees, or transfer to other accounts) to behave like it works with native tokens.
+
+        As a consequence, when this change is introduced, adding freezes (a.k.a. locks) or balances
+        on hold (a.k.a. reserves) to an asset account will constraint the amount of balance for such
+        account that can be withdrawn or transferred, and will affect the ability for these accounts
+        to be destroyed.
+
+        See [sdk docs](https://paritytech.github.io/polkadot-sdk/master/frame_support/traits/tokens/fungible/index.html#visualising-balance-components-together-)
+        to understand how to calculate the spendable balance of an asset account on the client side.
+
+        ## Implementation of `InspectHold` and `MutateHold`
 
         The `pallet-assets-holder` implements `hold` traits for `pallet-assets`, by extending this
         pallet and implementing the `BalanceOnHold` trait so the held balance can be queried by
@@ -23,7 +36,7 @@ doc:
         ## Enable `pallet-assets-holder`
 
         Define an instance of `pallet-assets-holder` (we'll call it `AssetsHolder`) and use
-        `AssetsHolder` as the value for `Holder`, when intend to use holding capabilities are
+        `AssetsHolder` as the type for `Holder`, when intend to use holding capabilities are
         wanted in the runtime implementation.
 
 crates: