[Assets] Implement pallet-assets-holder

Cargo.toml

@@ -315,6 +315,7 @@ members = [
 	"substrate/frame/asset-rate",
 	"substrate/frame/assets",
 	"substrate/frame/assets-freezer",
+	"substrate/frame/assets-holder",
 	"substrate/frame/atomic-swap",
 	"substrate/frame/aura",
 	"substrate/frame/authority-discovery",
@@ -887,6 +888,7 @@ pallet-asset-rate = { path = "substrate/frame/asset-rate", default-features = fa
 pallet-asset-tx-payment = { path = "substrate/frame/transaction-payment/asset-tx-payment", default-features = false }
 pallet-assets = { path = "substrate/frame/assets", default-features = false }
 pallet-assets-freezer = { path = "substrate/frame/assets-freezer", default-features = false }
+pallet-assets-holder = { path = "substrate/frame/assets-holder", default-features = false }
 pallet-atomic-swap = { default-features = false, path = "substrate/frame/atomic-swap" }
 pallet-aura = { path = "substrate/frame/aura", default-features = false }
 pallet-authority-discovery = { path = "substrate/frame/authority-discovery", default-features = false }

cumulus/parachains/runtimes/assets/asset-hub-rococo/src/lib.rs

@@ -265,6 +265,7 @@ impl pallet_assets::Config<TrustBackedAssetsInstance> for Runtime {
 	type MetadataDepositPerByte = MetadataDepositPerByte;
 	type ApprovalDeposit = ApprovalDeposit;
 	type StringLimit = AssetsStringLimit;
+	type Holder = ();
 	type Freezer = AssetsFreezer;
 	type Extra = ();
 	type WeightInfo = weights::pallet_assets_local::WeightInfo<Runtime>;
@@ -310,6 +311,7 @@ impl pallet_assets::Config<PoolAssetsInstance> for Runtime {
 	type MetadataDepositPerByte = ConstU128<0>;
 	type ApprovalDeposit = ApprovalDeposit;
 	type StringLimit = ConstU32<50>;
+	type Holder = ();
 	type Freezer = PoolAssetsFreezer;
 	type Extra = ();
 	type WeightInfo = weights::pallet_assets_pool::WeightInfo<Runtime>;
@@ -434,6 +436,7 @@ impl pallet_assets::Config<ForeignAssetsInstance> for Runtime {
 	type MetadataDepositPerByte = ForeignAssetsMetadataDepositPerByte;
 	type ApprovalDeposit = ForeignAssetsApprovalDeposit;
 	type StringLimit = ForeignAssetsAssetsStringLimit;
+	type Holder = ();
 	type Freezer = ForeignAssetsFreezer;
 	type Extra = ();
 	type WeightInfo = weights::pallet_assets_foreign::WeightInfo<Runtime>;

cumulus/parachains/runtimes/assets/asset-hub-westend/src/lib.rs

@@ -265,6 +265,7 @@ impl pallet_assets::Config<TrustBackedAssetsInstance> for Runtime {
 	type MetadataDepositPerByte = MetadataDepositPerByte;
 	type ApprovalDeposit = ApprovalDeposit;
 	type StringLimit = AssetsStringLimit;
+	type Holder = ();
 	type Freezer = AssetsFreezer;
 	type Extra = ();
 	type WeightInfo = weights::pallet_assets_local::WeightInfo<Runtime>;
@@ -309,6 +310,7 @@ impl pallet_assets::Config<PoolAssetsInstance> for Runtime {
 	type MetadataDepositPerByte = ConstU128<0>;
 	type ApprovalDeposit = ConstU128<0>;
 	type StringLimit = ConstU32<50>;
+	type Holder = ();
 	type Freezer = PoolAssetsFreezer;
 	type Extra = ();
 	type WeightInfo = weights::pallet_assets_pool::WeightInfo<Runtime>;
@@ -433,6 +435,7 @@ impl pallet_assets::Config<ForeignAssetsInstance> for Runtime {
 	type MetadataDepositPerByte = ForeignAssetsMetadataDepositPerByte;
 	type ApprovalDeposit = ForeignAssetsApprovalDeposit;
 	type StringLimit = ForeignAssetsAssetsStringLimit;
+	type Holder = ();
 	type Freezer = ForeignAssetsFreezer;
 	type Extra = ();
 	type WeightInfo = weights::pallet_assets_foreign::WeightInfo<Runtime>;

cumulus/parachains/runtimes/testing/penpal/src/lib.rs

@@ -466,6 +466,7 @@ impl pallet_assets::Config<TrustBackedAssetsInstance> for Runtime {
 	type MetadataDepositPerByte = MetadataDepositPerByte;
 	type ApprovalDeposit = ApprovalDeposit;
 	type StringLimit = AssetsStringLimit;
+	type Holder = ();
 	type Freezer = ();
 	type Extra = ();
 	type WeightInfo = pallet_assets::weights::SubstrateWeight<Runtime>;
@@ -501,6 +502,7 @@ impl pallet_assets::Config<ForeignAssetsInstance> for Runtime {
 	type MetadataDepositPerByte = ForeignAssetsMetadataDepositPerByte;
 	type ApprovalDeposit = ForeignAssetsApprovalDeposit;
 	type StringLimit = ForeignAssetsAssetsStringLimit;
+	type Holder = ();
 	type Freezer = ();
 	type Extra = ();
 	type WeightInfo = pallet_assets::weights::SubstrateWeight<Runtime>;
@@ -540,6 +542,7 @@ impl pallet_assets::Config<PoolAssetsInstance> for Runtime {
 	type MetadataDepositPerByte = ConstU128<0>;
 	type ApprovalDeposit = ConstU128<0>;
 	type StringLimit = ConstU32<50>;
+	type Holder = ();
 	type Freezer = ();
 	type Extra = ();
 	type WeightInfo = pallet_assets::weights::SubstrateWeight<Runtime>;

cumulus/parachains/runtimes/testing/rococo-parachain/src/lib.rs

@@ -592,6 +592,7 @@ impl pallet_assets::Config for Runtime {
 	type MetadataDepositPerByte = MetadataDepositPerByte;
 	type ApprovalDeposit = ApprovalDeposit;
 	type StringLimit = AssetsStringLimit;
+	type Holder = ();
 	type Freezer = ();
 	type Extra = ();
 	type WeightInfo = pallet_assets::weights::SubstrateWeight<Runtime>;

polkadot/xcm/pallet-xcm/src/mock.rs

@@ -299,6 +299,7 @@ impl pallet_assets::Config for Test {
 	type MetadataDepositPerByte = ConstU128<1>;
 	type ApprovalDeposit = ConstU128<1>;
 	type StringLimit = ConstU32<50>;
+	type Holder = ();
 	type Freezer = ();
 	type WeightInfo = ();
 	type CallbackHandle = ();

polkadot/xcm/xcm-builder/src/asset_exchange/single_asset_adapter/mock.rs

@@ -82,6 +82,7 @@ impl pallet_assets::Config<TrustBackedAssetsInstance> for Runtime {
 	type CreateOrigin = AsEnsureOriginWithArg<frame_system::EnsureSigned<AccountId>>;
 	type ForceOrigin = frame_system::EnsureRoot<AccountId>;
 	type Freezer = ();
+	type Holder = ();
 	type CallbackHandle = ();
 }
 
@@ -97,6 +98,7 @@ impl pallet_assets::Config<PoolAssetsInstance> for Runtime {
 	type CreateOrigin = AsEnsureOriginWithArg<frame_system::EnsureSigned<AccountId>>;
 	type ForceOrigin = frame_system::EnsureRoot<AccountId>;
 	type Freezer = ();
+	type Holder = ();
 	type CallbackHandle = ();
 }
 

polkadot/xcm/xcm-builder/src/tests/pay/mock.rs

@@ -111,6 +111,7 @@ impl pallet_assets::Config for Test {
 	type AssetAccountDeposit = AssetAccountDeposit;
 	type ApprovalDeposit = ApprovalDeposit;
 	type StringLimit = AssetsStringLimit;
+	type Holder = ();
 	type Freezer = ();
 	type Extra = ();
 	type WeightInfo = ();

polkadot/xcm/xcm-runtime-apis/tests/mock.rs

@@ -96,6 +96,7 @@ impl pallet_assets::Config for TestRuntime {
 	type Currency = Balances;
 	type CreateOrigin = AsEnsureOriginWithArg<frame_system::EnsureSigned<AccountId>>;
 	type ForceOrigin = frame_system::EnsureRoot<AccountId>;
+	type Holder = ();
 	type Freezer = ();
 	type AssetDeposit = ConstU128<1>;
 	type AssetAccountDeposit = ConstU128<10>;

prdoc/pr_4530.prdoc

@@ -0,0 +1,107 @@
+title: "Implement `pallet-assets-holder`"
+
+doc:
+  - audience: Runtime Dev
+    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
+
+        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.
+
+        ### Example
+
+        Before the changes in the balance model, an asset account balance could look like something like this:
+
+        ```
+        |____________balance____________|
+               |__frozen__|
+        |__ed__|
+        |___untouchable___|__spendable__|
+        ```
+
+        In the previous model, you could spend funds up to `ed + frozen` where `ed` is the minimum balance for an asset
+        class, and `frozen` is the frozen amount (if any `freezes` are in place).
+
+        Now, the model looks like this:
+
+        ```
+        |__total__________________________________|
+        |__on_hold__|_____________free____________|
+        |__________frozen___________|
+        |__on_hold__|__ed__|
+                    |__untouchable__|__spendable__|
+        ```
+
+        There's now a balance `on_hold` and a `free` balance. The balance `on_hold` is managed by a `Holder` (typically
+        `pallet-assets-holder`) and `free` is the balance that remains in `pallet-assets`. The `frozen` amount can be
+        subsumed into the balance `on_hold`, and now you can spend funds up to `max(frozen, ed)`, so if for an account,
+        `frozen` is less or equal than `on_hold + ed`, you'd be able to spend your `free` balance up to `ed`. If for
+        the account, `frozen` is more than `on_hold + ed`, the remaining amount after subtracting `frozen` to
+        `on_hold + ed` is the amount you cannot spend from your `free` balance.
+
+        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
+        `pallet-assets` to calculate the reducible (a.k.a. spendable) balance.
+
+        These changes imply adding a configuration type in `pallet-assets` for `Holder`
+
+        ## Default implementation of `Holder`
+
+        Use `()` as the default value, when no holding capabilities are wanted in the runtime
+        implementation.
+
+        ## Enable `pallet-assets-holder`
+
+        Define an instance of `pallet-assets-holder` (we'll call it `AssetsHolder`) and use
+        `AssetsHolder` as the type for `Holder`, when intend to use holding capabilities are
+        wanted in the runtime implementation.
+
+crates:
+  - name: asset-hub-rococo-runtime
+    bump: minor
+  - name: asset-hub-westend-runtime
+    bump: minor
+  - name: pallet-asset-tx-payment
+    bump: patch
+  - name: pallet-asset-conversion-ops
+    bump: patch
+  - name: pallet-asset-conversion-tx-payment
+    bump: patch
+  - name: pallet-assets
+    bump: major
+  - name: pallet-assets-holder
+    bump: major
+  - name: pallet-assets-freezer
+    bump: patch
+  - name: pallet-contracts-mock-network
+    bump: patch
+  - name: pallet-nft-fractionalization
+    bump: patch
+  - name: pallet-revive-mock-network
+    bump: patch
+  - name: pallet-xcm
+    bump: patch
+  - name: penpal-runtime
+    bump: patch
+  - name: rococo-parachain-runtime
+    bump: patch
+  - name: polkadot-sdk
+    bump: minor
+  - name: staging-xcm-builder
+    bump: patch
+  - name: xcm-runtime-apis
+    bump: patch

substrate/bin/node/runtime/src/lib.rs

@@ -1732,6 +1732,7 @@ impl pallet_assets::Config<Instance1> for Runtime {
 	type MetadataDepositPerByte = MetadataDepositPerByte;
 	type ApprovalDeposit = ApprovalDeposit;
 	type StringLimit = StringLimit;
+	type Holder = ();
 	type Freezer = ();
 	type Extra = ();
 	type CallbackHandle = ();
@@ -1759,6 +1760,7 @@ impl pallet_assets::Config<Instance2> for Runtime {
 	type MetadataDepositPerByte = MetadataDepositPerByte;
 	type ApprovalDeposit = ApprovalDeposit;
 	type StringLimit = StringLimit;
+	type Holder = ();
 	type Freezer = ();
 	type Extra = ();
 	type WeightInfo = pallet_assets::weights::SubstrateWeight<Runtime>;

substrate/frame/asset-conversion/ops/src/mock.rs

@@ -67,6 +67,7 @@ impl pallet_assets::Config<Instance1> for Test {
 	type Currency = Balances;
 	type CreateOrigin = AsEnsureOriginWithArg<EnsureSigned<Self::AccountId>>;
 	type ForceOrigin = frame_system::EnsureRoot<Self::AccountId>;
+	type Holder = ();
 	type Freezer = ();
 }
 
@@ -76,6 +77,7 @@ impl pallet_assets::Config<Instance2> for Test {
 	type CreateOrigin =
 		AsEnsureOriginWithArg<EnsureSignedBy<AssetConversionOrigin, Self::AccountId>>;
 	type ForceOrigin = frame_system::EnsureRoot<Self::AccountId>;
+	type Holder = ();
 	type Freezer = ();
 }
 

substrate/frame/asset-conversion/src/mock.rs

@@ -83,6 +83,7 @@ impl pallet_assets::Config<Instance1> for Test {
 	type MetadataDepositPerByte = ConstU128<1>;
 	type ApprovalDeposit = ConstU128<1>;
 	type StringLimit = ConstU32<50>;
+	type Holder = ();
 	type Freezer = ();
 	type Extra = ();
 	type WeightInfo = ();
@@ -108,6 +109,7 @@ impl pallet_assets::Config<Instance2> for Test {
 	type MetadataDepositPerByte = ConstU128<0>;
 	type ApprovalDeposit = ConstU128<0>;
 	type StringLimit = ConstU32<50>;
+	type Holder = ();
 	type Freezer = ();
 	type Extra = ();
 	type WeightInfo = ();

substrate/frame/assets-freezer/src/impls.rs

@@ -23,6 +23,7 @@ use frame_support::traits::{
 };
 use pallet_assets::FrozenBalance;
 use sp_runtime::traits::Zero;
+use storage::StorageDoubleMap;
 
 // Implements [`FrozenBalance`] from [`pallet-assets`], so it can understand how much of an
 // account balance is frozen, and is able to signal to this pallet when to clear the state of an
@@ -35,9 +36,22 @@ impl<T: Config<I>, I: 'static> FrozenBalance<T::AssetId, T::AccountId, T::Balanc
 	}
 
 	fn died(asset: T::AssetId, who: &T::AccountId) {
+		defensive_assert!(
+			Freezes::<T, I>::get(asset.clone(), who).is_empty(),
+			"The list of Freezes should be empty before allowing an account to die"
+		);
+		defensive_assert!(
+			FrozenBalances::<T, I>::get(asset.clone(), who).is_none(),
+			"There should not be a frozen balance before allowing to die"
+		);
+
 		FrozenBalances::<T, I>::remove(asset.clone(), who);
 		Freezes::<T, I>::remove(asset, who);
 	}
+
+	fn contains_freezes(asset: T::AssetId) -> bool {
+		Freezes::<T, I>::contains_prefix(asset)
+	}
 }
 
 // Implement [`fungibles::Inspect`](frame_support::traits::fungibles::Inspect) as it is bound by

substrate/frame/assets-freezer/src/mock.rs

@@ -106,6 +106,7 @@ impl pallet_assets::Config for Test {
 	type RemoveItemsLimit = ConstU32<10>;
 	type CallbackHandle = ();
 	type Currency = Balances;
+	type Holder = ();
 	type Freezer = AssetsFreezer;
 	type RuntimeEvent = RuntimeEvent;
 	type WeightInfo = ();