[pallet-balances] burn_allow_death extrinsic

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

@@ -159,4 +159,12 @@ impl<T: frame_system::Config> pallet_balances::WeightInfo for WeightInfo<T> {
 			.saturating_add(Weight::from_parts(0, 1501))
 			.saturating_add(T::DbWeight::get().reads(1))
 	}
+	fn burn_allow_death() -> Weight {
+		// TODO
+		Weight::zero()
+	}
+	fn burn_keep_alive() -> Weight {
+		// TODO
+		Weight::zero()
+	}
 }

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

@@ -159,4 +159,12 @@ impl<T: frame_system::Config> pallet_balances::WeightInfo for WeightInfo<T> {
 			.saturating_add(Weight::from_parts(0, 1501))
 			.saturating_add(T::DbWeight::get().reads(1))
 	}
+	fn burn_allow_death() -> Weight {
+		// TODO
+		Weight::zero()
+	}
+	fn burn_keep_alive() -> Weight {
+		// TODO
+		Weight::zero()
+	}
 }

cumulus/parachains/runtimes/bridge-hubs/bridge-hub-rococo/src/weights/pallet_balances.rs

@@ -159,4 +159,12 @@ impl<T: frame_system::Config> pallet_balances::WeightInfo for WeightInfo<T> {
 			.saturating_add(Weight::from_parts(0, 1501))
 			.saturating_add(T::DbWeight::get().reads(1))
 	}
+	fn burn_allow_death() -> Weight {
+		// TODO
+		Weight::zero()
+	}
+	fn burn_keep_alive() -> Weight {
+		// TODO
+		Weight::zero()
+	}
 }

cumulus/parachains/runtimes/bridge-hubs/bridge-hub-westend/src/weights/pallet_balances.rs

@@ -159,4 +159,12 @@ impl<T: frame_system::Config> pallet_balances::WeightInfo for WeightInfo<T> {
 			.saturating_add(Weight::from_parts(0, 1501))
 			.saturating_add(T::DbWeight::get().reads(1))
 	}
+	fn burn_allow_death() -> Weight {
+		// TODO
+		Weight::zero()
+	}
+	fn burn_keep_alive() -> Weight {
+		// TODO
+		Weight::zero()
+	}
 }

cumulus/parachains/runtimes/collectives/collectives-westend/src/weights/pallet_balances.rs

@@ -159,4 +159,12 @@ impl<T: frame_system::Config> pallet_balances::WeightInfo for WeightInfo<T> {
 			.saturating_add(Weight::from_parts(0, 1501))
 			.saturating_add(T::DbWeight::get().reads(1))
 	}
+	fn burn_allow_death() -> Weight {
+		// TODO
+		Weight::zero()
+	}
+	fn burn_keep_alive() -> Weight {
+		// TODO
+		Weight::zero()
+	}
 }

cumulus/parachains/runtimes/coretime/coretime-rococo/src/weights/pallet_balances.rs

@@ -159,4 +159,12 @@ impl<T: frame_system::Config> pallet_balances::WeightInfo for WeightInfo<T> {
 			.saturating_add(Weight::from_parts(0, 1501))
 			.saturating_add(T::DbWeight::get().reads(1))
 	}
+	fn burn_allow_death() -> Weight {
+		// TODO
+		Weight::zero()
+	}
+	fn burn_keep_alive() -> Weight {
+		// TODO
+		Weight::zero()
+	}
 }

cumulus/parachains/runtimes/coretime/coretime-westend/src/weights/pallet_balances.rs

@@ -161,4 +161,12 @@ impl<T: frame_system::Config> pallet_balances::WeightInfo for WeightInfo<T> {
 			.saturating_add(Weight::from_parts(0, 1501))
 			.saturating_add(T::DbWeight::get().reads(1))
 	}
+	fn burn_allow_death() -> Weight {
+		// TODO
+		Weight::zero()
+	}
+	fn burn_keep_alive() -> Weight {
+		// TODO
+		Weight::zero()
+	}
 }

cumulus/parachains/runtimes/people/people-rococo/src/weights/pallet_balances.rs

@@ -155,4 +155,12 @@ impl<T: frame_system::Config> pallet_balances::WeightInfo for WeightInfo<T> {
 			.saturating_add(T::DbWeight::get().writes((1_u64).saturating_mul(u.into())))
 			.saturating_add(Weight::from_parts(0, 2603).saturating_mul(u.into()))
 	}
+	fn burn_allow_death() -> Weight {
+		// TODO
+		Weight::zero()
+	}
+	fn burn_keep_alive() -> Weight {
+		// TODO
+		Weight::zero()
+	}
 }

cumulus/parachains/runtimes/people/people-westend/src/weights/pallet_balances.rs

@@ -155,4 +155,12 @@ impl<T: frame_system::Config> pallet_balances::WeightInfo for WeightInfo<T> {
 			.saturating_add(T::DbWeight::get().writes((1_u64).saturating_mul(u.into())))
 			.saturating_add(Weight::from_parts(0, 2603).saturating_mul(u.into()))
 	}
+	fn burn_allow_death() -> Weight {
+		// TODO
+		Weight::zero()
+	}
+	fn burn_keep_alive() -> Weight {
+		// TODO
+		Weight::zero()
+	}
 }

polkadot/runtime/rococo/src/weights/pallet_balances_balances.rs

@@ -157,4 +157,12 @@ impl<T: frame_system::Config> pallet_balances::WeightInfo for WeightInfo<T> {
 		Weight::from_parts(5_617_000, 0)
 			.saturating_add(Weight::from_parts(0, 0))
 	}
+	fn burn_allow_death() -> Weight {
+		// TODO
+		Weight::zero()
+	}
+	fn burn_keep_alive() -> Weight {
+		// TODO
+		Weight::zero()
+	}
 }

polkadot/runtime/rococo/src/weights/pallet_balances_nis_counterpart_balances.rs

@@ -171,4 +171,12 @@ impl<T: frame_system::Config> pallet_balances::WeightInfo for WeightInfo<T> {
 		Weight::from_parts(5_628_000, 0)
 			.saturating_add(Weight::from_parts(0, 0))
 	}
+	fn burn_allow_death() -> Weight {
+		// TODO
+		Weight::zero()
+	}
+	fn burn_keep_alive() -> Weight {
+		// TODO
+		Weight::zero()
+	}
 }

polkadot/runtime/westend/src/weights/pallet_balances.rs

@@ -156,4 +156,12 @@ impl<T: frame_system::Config> pallet_balances::WeightInfo for WeightInfo<T> {
 		Weight::from_parts(5_457_000, 0)
 			.saturating_add(Weight::from_parts(0, 0))
 	}
+	fn burn_allow_death() -> Weight {
+		// TODO
+		Weight::zero()
+	}
+	fn burn_keep_alive() -> Weight {
+		// TODO
+		Weight::zero()
+	}
 }

polkadot/xcm/xcm-builder/src/fungible_adapter.rs

@@ -19,7 +19,11 @@
 use super::MintLocation;
 use frame_support::traits::{
 	tokens::{
-		fungible, Fortitude::Polite, Precision::Exact, Preservation::Preserve, Provenance::Minted,
+		fungible,
+		Fortitude::Polite,
+		Precision::Exact,
+		Preservation::{Expendable, Preserve},
+		Provenance::Minted,
 	},
 	Get,
 };
@@ -100,7 +104,7 @@ impl<
 	}
 
 	fn reduce_checked(checking_account: AccountId, amount: Fungible::Balance) {
-		let ok = Fungible::burn_from(&checking_account, amount, Exact, Polite).is_ok();
+		let ok = Fungible::burn_from(&checking_account, amount, Expendable, Exact, Polite).is_ok();
 		debug_assert!(ok, "`can_reduce_checked` must have returned `true` immediately prior; qed");
 	}
 }
@@ -210,7 +214,7 @@ impl<
 		let amount = Matcher::matches_fungible(what).ok_or(MatchError::AssetNotHandled)?;
 		let who = AccountIdConverter::convert_location(who)
 			.ok_or(MatchError::AccountIdConversionFailed)?;
-		Fungible::burn_from(&who, amount, Exact, Polite)
+		Fungible::burn_from(&who, amount, Expendable, Exact, Polite)
 			.map_err(|error| XcmError::FailedToTransactAsset(error.into()))?;
 		Ok(what.clone().into())
 	}

polkadot/xcm/xcm-builder/src/fungibles_adapter.rs

@@ -18,7 +18,11 @@
 
 use frame_support::traits::{
 	tokens::{
-		fungibles, Fortitude::Polite, Precision::Exact, Preservation::Preserve, Provenance::Minted,
+		fungibles,
+		Fortitude::Polite,
+		Precision::Exact,
+		Preservation::{Expendable, Preserve},
+		Provenance::Minted,
 	},
 	Contains, Get,
 };
@@ -176,7 +180,8 @@ impl<
 	}
 	fn reduce_checked(asset_id: Assets::AssetId, amount: Assets::Balance) {
 		let checking_account = CheckingAccount::get();
-		let ok = Assets::burn_from(asset_id, &checking_account, amount, Exact, Polite).is_ok();
+		let ok = Assets::burn_from(asset_id, &checking_account, amount, Expendable, Exact, Polite)
+			.is_ok();
 		debug_assert!(ok, "`can_reduce_checked` must have returned `true` immediately prior; qed");
 	}
 }
@@ -295,7 +300,7 @@ impl<
 		let (asset_id, amount) = Matcher::matches_fungibles(what)?;
 		let who = AccountIdConverter::convert_location(who)
 			.ok_or(MatchError::AccountIdConversionFailed)?;
-		Assets::burn_from(asset_id, &who, amount, Exact, Polite)
+		Assets::burn_from(asset_id, &who, amount, Expendable, Exact, Polite)
 			.map_err(|e| XcmError::FailedToTransactAsset(e.into()))?;
 		Ok(what.clone().into())
 	}

prdoc/pr_3964.prdoc

@@ -0,0 +1,16 @@
+title: Burn extrinsic call and `fn burn_from` `Preservation` argument 
+
+doc:
+  - audience: Runtime Dev
+    description: |
+      pallet-balances extrinsic calls has been expanded with `burn` call.
+      An argument flag is allowed to specify whether the account should be kept alive or not.
+      This in turn required a change to the fungible's `pub trait Mutate` `burn_from` function which now
+      also accepts `Preservation` as an argument.
+      In order to keep the behavior same as before, developers should simply specify `Preservation::Expandable`.
+
+crates:
+  - name: frame-support
+    bump: major
+  - name: pallet-balances
+    bump: minor

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

@@ -582,7 +582,14 @@ pub mod pallet {
 			);
 
 			// burn the provided lp token amount that includes the fee
-			T::PoolAssets::burn_from(pool.lp_token.clone(), &sender, lp_token_burn, Exact, Polite)?;
+			T::PoolAssets::burn_from(
+				pool.lp_token.clone(),
+				&sender,
+				lp_token_burn,
+				Expendable,
+				Exact,
+				Polite,
+			)?;
 
 			T::Assets::transfer(*asset1, &pool_account, &withdraw_to, amount1, Expendable)?;
 			T::Assets::transfer(*asset2, &pool_account, &withdraw_to, amount2, Expendable)?;

substrate/frame/balances/src/benchmarking.rs

@@ -297,6 +297,44 @@ mod benchmarks {
 		assert_eq!(Balances::<T, I>::total_issuance(), ti + delta);
 	}
 
+	// Benchmark `burn` extrinsic with the worst possible condition - burn kills the account.
+	#[benchmark]
+	fn burn_allow_death() {
+		let existential_deposit = T::ExistentialDeposit::get();
+		let caller = whitelisted_caller();
+
+		// Give some multiple of the existential deposit
+		let balance = existential_deposit.saturating_mul(ED_MULTIPLIER.into());
+		let _ = <Balances<T, I> as Currency<_>>::make_free_balance_be(&caller, balance);
+
+		// Burn enough to kill the account.
+		let burn_amount = balance - existential_deposit + 1u32.into();
+
+		#[extrinsic_call]
+		burn(RawOrigin::Signed(caller.clone()), burn_amount, false);
+
+		assert_eq!(Balances::<T, I>::free_balance(&caller), Zero::zero());
+	}
+
+	// Benchmark `burn` extrinsic with the case where account is kept alive.
+	#[benchmark]
+	fn burn_keep_alive() {
+		let existential_deposit = T::ExistentialDeposit::get();
+		let caller = whitelisted_caller();
+
+		// Give some multiple of the existential deposit
+		let balance = existential_deposit.saturating_mul(ED_MULTIPLIER.into());
+		let _ = <Balances<T, I> as Currency<_>>::make_free_balance_be(&caller, balance);
+
+		// Burn minimum possible amount which should not kill the account.
+		let burn_amount = 1u32.into();
+
+		#[extrinsic_call]
+		burn(RawOrigin::Signed(caller.clone()), burn_amount, true);
+
+		assert_eq!(Balances::<T, I>::free_balance(&caller), balance - burn_amount);
+	}
+
 	impl_benchmark_test_suite! {
 		Balances,
 		crate::tests::ExtBuilder::default().build(),

substrate/frame/balances/src/lib.rs

@@ -681,7 +681,7 @@ pub mod pallet {
 		) -> DispatchResultWithPostInfo {
 			ensure_signed(origin)?;
 			if who.is_empty() {
-				return Ok(Pays::Yes.into())
+				return Ok(Pays::Yes.into());
 			}
 			let mut upgrade_count = 0;
 			for i in &who {
@@ -767,6 +767,29 @@ pub mod pallet {
 
 			Ok(())
 		}
+
+		/// Burn the specified liquid free balance from the origin account.
+		///
+		/// If the origin's account ends up below the existential deposit as a result
+		/// of the burn and `keep_alive` is false, the account will be reaped.
+		#[pallet::call_index(10)]
+		#[pallet::weight(if *keep_alive {T::WeightInfo::burn_allow_death() } else {T::WeightInfo::burn_keep_alive()})]
+		pub fn burn(
+			origin: OriginFor<T>,
+			#[pallet::compact] value: T::Balance,
+			keep_alive: bool,
+		) -> DispatchResult {
+			let source = ensure_signed(origin)?;
+			let preservation = if keep_alive { Preserve } else { Expendable };
+			<Self as fungible::Mutate<_>>::burn_from(
+				&source,
+				value,
+				preservation,
+				Precision::Exact,
+				Polite,
+			)?;
+			Ok(())
+		}
 	}
 
 	impl<T: Config<I>, I: 'static> Pallet<T, I> {

substrate/frame/balances/src/tests/currency_tests.rs

@@ -701,7 +701,7 @@ fn account_removal_on_free_too_low() {
 fn burn_must_work() {
 	ExtBuilder::default().monied(true).build_and_execute_with(|| {
 		let init_total_issuance = Balances::total_issuance();
-		let imbalance = Balances::burn(10);
+		let imbalance = <Balances as Currency<_>>::burn(10);
 		assert_eq!(Balances::total_issuance(), init_total_issuance - 10);
 		drop(imbalance);
 		assert_eq!(Balances::total_issuance(), init_total_issuance);

substrate/frame/balances/src/tests/dispatchable_tests.rs

@@ -335,3 +335,47 @@ fn force_adjust_total_issuance_rejects_more_than_inactive() {
 		assert_eq!(Balances::active_issuance(), 10);
 	});
 }
+
+#[test]
+fn burn_works() {
+	ExtBuilder::default().build().execute_with(|| {
+		// Prepare account with initial balance
+		let (account, init_balance) = (1, 37);
+		assert_ok!(Balances::force_set_balance(RuntimeOrigin::root(), account, init_balance));
+		let init_issuance = Balances::total_issuance();
+		let (keep_alive, allow_death) = (true, false);
+
+		// 1. Cannot burn more than what's available
+		assert_noop!(
+			Balances::burn(Some(account).into(), init_balance + 1, allow_death),
+			TokenError::FundsUnavailable,
+		);
+
+		// 2. Burn some funds, without reaping the account
+		let burn_amount_1 = 1;
+		assert_ok!(Balances::burn(Some(account).into(), burn_amount_1, allow_death));
+		System::assert_last_event(RuntimeEvent::Balances(Event::Burned {
+			who: account,
+			amount: burn_amount_1,
+		}));
+		assert_eq!(Balances::total_issuance(), init_issuance - burn_amount_1);
+		assert_eq!(Balances::total_balance(&account), init_balance - burn_amount_1);
+
+		// 3. Cannot burn funds below existential deposit if `keep_alive` is `true`
+		let burn_amount_2 =
+			init_balance - burn_amount_1 - <Test as Config>::ExistentialDeposit::get() + 1;
+		assert_noop!(
+			Balances::burn(Some(account).into(), init_balance + 1, keep_alive),
+			TokenError::FundsUnavailable,
+		);
+
+		// 4. Burn some more funds, this time reaping the account
+		assert_ok!(Balances::burn(Some(account).into(), burn_amount_2, allow_death));
+		System::assert_last_event(RuntimeEvent::Balances(Event::Burned {
+			who: account,
+			amount: burn_amount_2,
+		}));
+		assert_eq!(Balances::total_issuance(), init_issuance - burn_amount_1 - burn_amount_2);
+		assert!(Balances::total_balance(&account).is_zero());
+	});
+}