referrerpolicy=no-referrer-when-downgrade

pallet_balances/
lib.rs

1// This file is part of Substrate.
2
3// Copyright (C) Parity Technologies (UK) Ltd.
4// SPDX-License-Identifier: Apache-2.0
5
6// Licensed under the Apache License, Version 2.0 (the "License");
7// you may not use this file except in compliance with the License.
8// You may obtain a copy of the License at
9//
10// 	http://www.apache.org/licenses/LICENSE-2.0
11//
12// Unless required by applicable law or agreed to in writing, software
13// distributed under the License is distributed on an "AS IS" BASIS,
14// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15// See the License for the specific language governing permissions and
16// limitations under the License.
17
18//! # Balances Pallet
19//!
20//! The Balances pallet provides functionality for handling accounts and balances for a single
21//! token.
22//!
23//! It makes heavy use of concepts such as Holds and Freezes from the
24//! [`frame_support::traits::fungible`] traits, therefore you should read and understand those docs
25//! as a prerequisite to understanding this pallet.
26//!
27//! Also see the [`frame_tokens`] reference docs for higher level information regarding the
28//! place of this palet in FRAME.
29//!
30//! ## Overview
31//!
32//! The Balances pallet provides functions for:
33//!
34//! - Getting and setting free balances.
35//! - Retrieving total, reserved and unreserved balances.
36//! - Repatriating a reserved balance to a beneficiary account that exists.
37//! - Transferring a balance between accounts (when not reserved).
38//! - Slashing an account balance.
39//! - Account creation and removal.
40//! - Managing total issuance.
41//! - Setting and managing locks.
42//!
43//! ### Terminology
44//!
45//! - **Reaping an account:** The act of removing an account by resetting its nonce. Happens after
46//!   its total balance has become less than the Existential Deposit.
47//!
48//! ### Implementations
49//!
50//! The Balances pallet provides implementations for the following [`fungible`] traits. If these
51//! traits provide the functionality that you need, then you should avoid tight coupling with the
52//! Balances pallet.
53//!
54//! - [`fungible::Inspect`]
55//! - [`fungible::Mutate`]
56//! - [`fungible::Unbalanced`]
57//! - [`fungible::Balanced`]
58//! - [`fungible::BalancedHold`]
59//! - [`fungible::InspectHold`]
60//! - [`fungible::MutateHold`]
61//! - [`fungible::InspectFreeze`]
62//! - [`fungible::MutateFreeze`]
63//! - [`fungible::Imbalance`]
64//!
65//! It also implements the following [`Currency`] related traits, however they are deprecated and
66//! will eventually be removed.
67//!
68//! - [`Currency`]: Functions for dealing with a fungible assets system.
69//! - [`ReservableCurrency`]
70//! - [`NamedReservableCurrency`](frame_support::traits::NamedReservableCurrency):
71//! Functions for dealing with assets that can be reserved from an account.
72//! - [`LockableCurrency`](frame_support::traits::LockableCurrency): Functions for
73//! dealing with accounts that allow liquidity restrictions.
74//! - [`Imbalance`](frame_support::traits::Imbalance): Functions for handling
75//! imbalances between total issuance in the system and account balances. Must be used when a
76//! function creates new funds (e.g. a reward) or destroys some funds (e.g. a system fee).
77//!
78//! ## Usage
79//!
80//! The following examples show how to use the Balances pallet in your custom pallet.
81//!
82//! ### Examples from the FRAME
83//!
84//! The Contract pallet uses the `Currency` trait to handle gas payment, and its types inherit from
85//! `Currency`:
86//!
87//! ```
88//! use frame_support::traits::Currency;
89//! # pub trait Config: frame_system::Config {
90//! #   type Currency: Currency<Self::AccountId>;
91//! # }
92//!
93//! pub type BalanceOf<T> = <<T as Config>::Currency as Currency<<T as frame_system::Config>::AccountId>>::Balance;
94//! pub type NegativeImbalanceOf<T> = <<T as Config>::Currency as Currency<<T as frame_system::Config>::AccountId>>::NegativeImbalance;
95//!
96//! # fn main() {}
97//! ```
98//!
99//! The Staking pallet uses the `LockableCurrency` trait to lock a stash account's funds:
100//!
101//! ```
102//! use frame_support::traits::{WithdrawReasons, LockableCurrency};
103//! use sp_runtime::traits::Bounded;
104//! pub trait Config: frame_system::Config {
105//!     type Currency: LockableCurrency<Self::AccountId, Moment=frame_system::pallet_prelude::BlockNumberFor<Self>>;
106//! }
107//! # struct StakingLedger<T: Config> {
108//! #   stash: <T as frame_system::Config>::AccountId,
109//! #   total: <<T as Config>::Currency as frame_support::traits::Currency<<T as frame_system::Config>::AccountId>>::Balance,
110//! #   phantom: std::marker::PhantomData<T>,
111//! # }
112//! # const STAKING_ID: [u8; 8] = *b"staking ";
113//!
114//! fn update_ledger<T: Config>(
115//!     controller: &T::AccountId,
116//!     ledger: &StakingLedger<T>
117//! ) {
118//!     T::Currency::set_lock(
119//!         STAKING_ID,
120//!         &ledger.stash,
121//!         ledger.total,
122//!         WithdrawReasons::all()
123//!     );
124//!     // <Ledger<T>>::insert(controller, ledger); // Commented out as we don't have access to Staking's storage here.
125//! }
126//! # fn main() {}
127//! ```
128//!
129//! ## Genesis config
130//!
131//! The Balances pallet depends on the [`GenesisConfig`].
132//!
133//! ## Assumptions
134//!
135//! * Total issued balanced of all accounts should be less than `Config::Balance::max_value()`.
136//! * Existential Deposit is set to a value greater than zero.
137//!
138//! Note, you may find the Balances pallet still functions with an ED of zero when the
139//! `insecure_zero_ed` cargo feature is enabled. However this is not a configuration which is
140//! generally supported, nor will it be.
141//!
142//! [`frame_tokens`]: ../polkadot_sdk_docs/reference_docs/frame_tokens/index.html
143
144#![cfg_attr(not(feature = "std"), no_std)]
145mod benchmarking;
146mod impl_currency;
147mod impl_fungible;
148pub mod migration;
149mod tests;
150mod types;
151pub mod weights;
152
153extern crate alloc;
154
155use alloc::{
156	format,
157	string::{String, ToString},
158	vec::Vec,
159};
160use codec::{Codec, MaxEncodedLen};
161use core::{cmp, fmt::Debug, mem, result};
162use frame_support::{
163	ensure,
164	pallet_prelude::DispatchResult,
165	traits::{
166		tokens::{
167			fungible, BalanceStatus as Status, DepositConsequence,
168			Fortitude::{self, Force, Polite},
169			IdAmount,
170			Preservation::{Expendable, Preserve, Protect},
171			WithdrawConsequence,
172		},
173		Currency, Defensive, Get, OnUnbalanced, ReservableCurrency, StoredMap,
174	},
175	BoundedSlice, WeakBoundedVec,
176};
177use frame_system as system;
178pub use impl_currency::{NegativeImbalance, PositiveImbalance};
179use scale_info::TypeInfo;
180use sp_core::{sr25519::Pair as SrPair, Pair};
181use sp_runtime::{
182	traits::{
183		AtLeast32BitUnsigned, CheckedAdd, CheckedSub, MaybeSerializeDeserialize, Saturating,
184		StaticLookup, Zero,
185	},
186	ArithmeticError, DispatchError, FixedPointOperand, Perbill, RuntimeDebug, TokenError,
187};
188
189pub use types::{
190	AccountData, AdjustmentDirection, BalanceLock, DustCleaner, ExtraFlags, Reasons, ReserveData,
191};
192pub use weights::WeightInfo;
193
194pub use pallet::*;
195
196const LOG_TARGET: &str = "runtime::balances";
197
198// Default derivation(hard) for development accounts.
199const DEFAULT_ADDRESS_URI: &str = "//Sender//{}";
200
201type AccountIdLookupOf<T> = <<T as frame_system::Config>::Lookup as StaticLookup>::Source;
202
203#[frame_support::pallet]
204pub mod pallet {
205	use super::*;
206	use codec::HasCompact;
207	use frame_support::{
208		pallet_prelude::*,
209		traits::{fungible::Credit, tokens::Precision, VariantCount, VariantCountOf},
210	};
211	use frame_system::pallet_prelude::*;
212
213	pub type CreditOf<T, I> = Credit<<T as frame_system::Config>::AccountId, Pallet<T, I>>;
214
215	/// Default implementations of [`DefaultConfig`], which can be used to implement [`Config`].
216	pub mod config_preludes {
217		use super::*;
218		use frame_support::derive_impl;
219
220		pub struct TestDefaultConfig;
221
222		#[derive_impl(frame_system::config_preludes::TestDefaultConfig, no_aggregated_types)]
223		impl frame_system::DefaultConfig for TestDefaultConfig {}
224
225		#[frame_support::register_default_impl(TestDefaultConfig)]
226		impl DefaultConfig for TestDefaultConfig {
227			#[inject_runtime_type]
228			type RuntimeEvent = ();
229			#[inject_runtime_type]
230			type RuntimeHoldReason = ();
231			#[inject_runtime_type]
232			type RuntimeFreezeReason = ();
233
234			type Balance = u64;
235			type ExistentialDeposit = ConstUint<1>;
236
237			type ReserveIdentifier = ();
238			type FreezeIdentifier = Self::RuntimeFreezeReason;
239
240			type DustRemoval = ();
241
242			type MaxLocks = ConstU32<100>;
243			type MaxReserves = ConstU32<100>;
244			type MaxFreezes = VariantCountOf<Self::RuntimeFreezeReason>;
245
246			type WeightInfo = ();
247			type DoneSlashHandler = ();
248		}
249	}
250
251	#[pallet::config(with_default)]
252	pub trait Config<I: 'static = ()>: frame_system::Config {
253		/// The overarching event type.
254		#[pallet::no_default_bounds]
255		#[allow(deprecated)]
256		type RuntimeEvent: From<Event<Self, I>>
257			+ IsType<<Self as frame_system::Config>::RuntimeEvent>;
258
259		/// The overarching hold reason.
260		#[pallet::no_default_bounds]
261		type RuntimeHoldReason: Parameter + Member + MaxEncodedLen + Copy + VariantCount;
262
263		/// The overarching freeze reason.
264		#[pallet::no_default_bounds]
265		type RuntimeFreezeReason: VariantCount;
266
267		/// Weight information for extrinsics in this pallet.
268		type WeightInfo: WeightInfo;
269
270		/// The balance of an account.
271		type Balance: Parameter
272			+ Member
273			+ AtLeast32BitUnsigned
274			+ Codec
275			+ HasCompact<Type: DecodeWithMemTracking>
276			+ Default
277			+ Copy
278			+ MaybeSerializeDeserialize
279			+ Debug
280			+ MaxEncodedLen
281			+ TypeInfo
282			+ FixedPointOperand;
283
284		/// Handler for the unbalanced reduction when removing a dust account.
285		#[pallet::no_default_bounds]
286		type DustRemoval: OnUnbalanced<CreditOf<Self, I>>;
287
288		/// The minimum amount required to keep an account open. MUST BE GREATER THAN ZERO!
289		///
290		/// If you *really* need it to be zero, you can enable the feature `insecure_zero_ed` for
291		/// this pallet. However, you do so at your own risk: this will open up a major DoS vector.
292		/// In case you have multiple sources of provider references, you may also get unexpected
293		/// behaviour if you set this to zero.
294		///
295		/// Bottom line: Do yourself a favour and make it at least one!
296		#[pallet::constant]
297		#[pallet::no_default_bounds]
298		type ExistentialDeposit: Get<Self::Balance>;
299
300		/// The means of storing the balances of an account.
301		#[pallet::no_default]
302		type AccountStore: StoredMap<Self::AccountId, AccountData<Self::Balance>>;
303
304		/// The ID type for reserves.
305		///
306		/// Use of reserves is deprecated in favour of holds. See `https://github.com/paritytech/substrate/pull/12951/`
307		type ReserveIdentifier: Parameter + Member + MaxEncodedLen + Ord + Copy;
308
309		/// The ID type for freezes.
310		type FreezeIdentifier: Parameter + Member + MaxEncodedLen + Copy;
311
312		/// The maximum number of locks that should exist on an account.
313		/// Not strictly enforced, but used for weight estimation.
314		///
315		/// Use of locks is deprecated in favour of freezes. See `https://github.com/paritytech/substrate/pull/12951/`
316		#[pallet::constant]
317		type MaxLocks: Get<u32>;
318
319		/// The maximum number of named reserves that can exist on an account.
320		///
321		/// Use of reserves is deprecated in favour of holds. See `https://github.com/paritytech/substrate/pull/12951/`
322		#[pallet::constant]
323		type MaxReserves: Get<u32>;
324
325		/// The maximum number of individual freeze locks that can exist on an account at any time.
326		#[pallet::constant]
327		type MaxFreezes: Get<u32>;
328
329		/// Allows callbacks to other pallets so they can update their bookkeeping when a slash
330		/// occurs.
331		type DoneSlashHandler: fungible::hold::DoneSlash<
332			Self::RuntimeHoldReason,
333			Self::AccountId,
334			Self::Balance,
335		>;
336	}
337
338	/// The in-code storage version.
339	const STORAGE_VERSION: frame_support::traits::StorageVersion =
340		frame_support::traits::StorageVersion::new(1);
341
342	#[pallet::pallet]
343	#[pallet::storage_version(STORAGE_VERSION)]
344	pub struct Pallet<T, I = ()>(PhantomData<(T, I)>);
345
346	#[pallet::event]
347	#[pallet::generate_deposit(pub(super) fn deposit_event)]
348	pub enum Event<T: Config<I>, I: 'static = ()> {
349		/// An account was created with some free balance.
350		Endowed { account: T::AccountId, free_balance: T::Balance },
351		/// An account was removed whose balance was non-zero but below ExistentialDeposit,
352		/// resulting in an outright loss.
353		DustLost { account: T::AccountId, amount: T::Balance },
354		/// Transfer succeeded.
355		Transfer { from: T::AccountId, to: T::AccountId, amount: T::Balance },
356		/// A balance was set by root.
357		BalanceSet { who: T::AccountId, free: T::Balance },
358		/// Some balance was reserved (moved from free to reserved).
359		Reserved { who: T::AccountId, amount: T::Balance },
360		/// Some balance was unreserved (moved from reserved to free).
361		Unreserved { who: T::AccountId, amount: T::Balance },
362		/// Some balance was moved from the reserve of the first account to the second account.
363		/// Final argument indicates the destination balance type.
364		ReserveRepatriated {
365			from: T::AccountId,
366			to: T::AccountId,
367			amount: T::Balance,
368			destination_status: Status,
369		},
370		/// Some amount was deposited (e.g. for transaction fees).
371		Deposit { who: T::AccountId, amount: T::Balance },
372		/// Some amount was withdrawn from the account (e.g. for transaction fees).
373		Withdraw { who: T::AccountId, amount: T::Balance },
374		/// Some amount was removed from the account (e.g. for misbehavior).
375		Slashed { who: T::AccountId, amount: T::Balance },
376		/// Some amount was minted into an account.
377		Minted { who: T::AccountId, amount: T::Balance },
378		/// Some credit was balanced and added to the TotalIssuance.
379		MintedCredit { amount: T::Balance },
380		/// Some amount was burned from an account.
381		Burned { who: T::AccountId, amount: T::Balance },
382		/// Some debt has been dropped from the Total Issuance.
383		BurnedDebt { amount: T::Balance },
384		/// Some amount was suspended from an account (it can be restored later).
385		Suspended { who: T::AccountId, amount: T::Balance },
386		/// Some amount was restored into an account.
387		Restored { who: T::AccountId, amount: T::Balance },
388		/// An account was upgraded.
389		Upgraded { who: T::AccountId },
390		/// Total issuance was increased by `amount`, creating a credit to be balanced.
391		Issued { amount: T::Balance },
392		/// Total issuance was decreased by `amount`, creating a debt to be balanced.
393		Rescinded { amount: T::Balance },
394		/// Some balance was locked.
395		Locked { who: T::AccountId, amount: T::Balance },
396		/// Some balance was unlocked.
397		Unlocked { who: T::AccountId, amount: T::Balance },
398		/// Some balance was frozen.
399		Frozen { who: T::AccountId, amount: T::Balance },
400		/// Some balance was thawed.
401		Thawed { who: T::AccountId, amount: T::Balance },
402		/// The `TotalIssuance` was forcefully changed.
403		TotalIssuanceForced { old: T::Balance, new: T::Balance },
404		/// Some balance was placed on hold.
405		Held { reason: T::RuntimeHoldReason, who: T::AccountId, amount: T::Balance },
406		/// Held balance was burned from an account.
407		BurnedHeld { reason: T::RuntimeHoldReason, who: T::AccountId, amount: T::Balance },
408		/// A transfer of `amount` on hold from `source` to `dest` was initiated.
409		TransferOnHold {
410			reason: T::RuntimeHoldReason,
411			source: T::AccountId,
412			dest: T::AccountId,
413			amount: T::Balance,
414		},
415		/// The `transferred` balance is placed on hold at the `dest` account.
416		TransferAndHold {
417			reason: T::RuntimeHoldReason,
418			source: T::AccountId,
419			dest: T::AccountId,
420			transferred: T::Balance,
421		},
422		/// Some balance was released from hold.
423		Released { reason: T::RuntimeHoldReason, who: T::AccountId, amount: T::Balance },
424		/// An unexpected/defensive event was triggered.
425		Unexpected(UnexpectedKind),
426	}
427
428	/// Defensive/unexpected errors/events.
429	///
430	/// In case of observation in explorers, report it as an issue in polkadot-sdk.
431	#[derive(Clone, Encode, Decode, DecodeWithMemTracking, PartialEq, TypeInfo, RuntimeDebug)]
432	pub enum UnexpectedKind {
433		/// Balance was altered/dusted during an operation that should have NOT done so.
434		BalanceUpdated,
435		/// Mutating the account failed unexpectedly. This might lead to storage items in
436		/// `Balances` and the underlying account in `System` to be out of sync.
437		FailedToMutateAccount,
438	}
439
440	#[pallet::error]
441	pub enum Error<T, I = ()> {
442		/// Vesting balance too high to send value.
443		VestingBalance,
444		/// Account liquidity restrictions prevent withdrawal.
445		LiquidityRestrictions,
446		/// Balance too low to send value.
447		InsufficientBalance,
448		/// Value too low to create account due to existential deposit.
449		ExistentialDeposit,
450		/// Transfer/payment would kill account.
451		Expendability,
452		/// A vesting schedule already exists for this account.
453		ExistingVestingSchedule,
454		/// Beneficiary account must pre-exist.
455		DeadAccount,
456		/// Number of named reserves exceed `MaxReserves`.
457		TooManyReserves,
458		/// Number of holds exceed `VariantCountOf<T::RuntimeHoldReason>`.
459		TooManyHolds,
460		/// Number of freezes exceed `MaxFreezes`.
461		TooManyFreezes,
462		/// The issuance cannot be modified since it is already deactivated.
463		IssuanceDeactivated,
464		/// The delta cannot be zero.
465		DeltaZero,
466	}
467
468	/// The total units issued in the system.
469	#[pallet::storage]
470	#[pallet::whitelist_storage]
471	pub type TotalIssuance<T: Config<I>, I: 'static = ()> = StorageValue<_, T::Balance, ValueQuery>;
472
473	/// The total units of outstanding deactivated balance in the system.
474	#[pallet::storage]
475	#[pallet::whitelist_storage]
476	pub type InactiveIssuance<T: Config<I>, I: 'static = ()> =
477		StorageValue<_, T::Balance, ValueQuery>;
478
479	/// The Balances pallet example of storing the balance of an account.
480	///
481	/// # Example
482	///
483	/// ```nocompile
484	///  impl pallet_balances::Config for Runtime {
485	///    type AccountStore = StorageMapShim<Self::Account<Runtime>, frame_system::Provider<Runtime>, AccountId, Self::AccountData<Balance>>
486	///  }
487	/// ```
488	///
489	/// You can also store the balance of an account in the `System` pallet.
490	///
491	/// # Example
492	///
493	/// ```nocompile
494	///  impl pallet_balances::Config for Runtime {
495	///   type AccountStore = System
496	///  }
497	/// ```
498	///
499	/// But this comes with tradeoffs, storing account balances in the system pallet stores
500	/// `frame_system` data alongside the account data contrary to storing account balances in the
501	/// `Balances` pallet, which uses a `StorageMap` to store balances data only.
502	/// NOTE: This is only used in the case that this pallet is used to store balances.
503	#[pallet::storage]
504	pub type Account<T: Config<I>, I: 'static = ()> =
505		StorageMap<_, Blake2_128Concat, T::AccountId, AccountData<T::Balance>, ValueQuery>;
506
507	/// Any liquidity locks on some account balances.
508	/// NOTE: Should only be accessed when setting, changing and freeing a lock.
509	///
510	/// Use of locks is deprecated in favour of freezes. See `https://github.com/paritytech/substrate/pull/12951/`
511	#[pallet::storage]
512	pub type Locks<T: Config<I>, I: 'static = ()> = StorageMap<
513		_,
514		Blake2_128Concat,
515		T::AccountId,
516		WeakBoundedVec<BalanceLock<T::Balance>, T::MaxLocks>,
517		ValueQuery,
518	>;
519
520	/// Named reserves on some account balances.
521	///
522	/// Use of reserves is deprecated in favour of holds. See `https://github.com/paritytech/substrate/pull/12951/`
523	#[pallet::storage]
524	pub type Reserves<T: Config<I>, I: 'static = ()> = StorageMap<
525		_,
526		Blake2_128Concat,
527		T::AccountId,
528		BoundedVec<ReserveData<T::ReserveIdentifier, T::Balance>, T::MaxReserves>,
529		ValueQuery,
530	>;
531
532	/// Holds on account balances.
533	#[pallet::storage]
534	pub type Holds<T: Config<I>, I: 'static = ()> = StorageMap<
535		_,
536		Blake2_128Concat,
537		T::AccountId,
538		BoundedVec<
539			IdAmount<T::RuntimeHoldReason, T::Balance>,
540			VariantCountOf<T::RuntimeHoldReason>,
541		>,
542		ValueQuery,
543	>;
544
545	/// Freeze locks on account balances.
546	#[pallet::storage]
547	pub type Freezes<T: Config<I>, I: 'static = ()> = StorageMap<
548		_,
549		Blake2_128Concat,
550		T::AccountId,
551		BoundedVec<IdAmount<T::FreezeIdentifier, T::Balance>, T::MaxFreezes>,
552		ValueQuery,
553	>;
554
555	#[pallet::genesis_config]
556	pub struct GenesisConfig<T: Config<I>, I: 'static = ()> {
557		pub balances: Vec<(T::AccountId, T::Balance)>,
558		/// Derived development accounts(Optional):
559		/// - `u32`: The number of development accounts to generate.
560		/// - `T::Balance`: The initial balance assigned to each development account.
561		/// - `String`: An optional derivation(hard) string template.
562		/// - Must include `{}` as a placeholder for account indices.
563		/// - Defaults to `"//Sender//{}`" if `None`.
564		pub dev_accounts: Option<(u32, T::Balance, Option<String>)>,
565	}
566
567	impl<T: Config<I>, I: 'static> Default for GenesisConfig<T, I> {
568		fn default() -> Self {
569			Self { balances: Default::default(), dev_accounts: None }
570		}
571	}
572
573	#[pallet::genesis_build]
574	impl<T: Config<I>, I: 'static> BuildGenesisConfig for GenesisConfig<T, I> {
575		fn build(&self) {
576			let total = self.balances.iter().fold(Zero::zero(), |acc: T::Balance, &(_, n)| acc + n);
577
578			<TotalIssuance<T, I>>::put(total);
579
580			for (_, balance) in &self.balances {
581				assert!(
582					*balance >= <T as Config<I>>::ExistentialDeposit::get(),
583					"the balance of any account should always be at least the existential deposit.",
584				)
585			}
586
587			// ensure no duplicates exist.
588			let endowed_accounts = self
589				.balances
590				.iter()
591				.map(|(x, _)| x)
592				.cloned()
593				.collect::<alloc::collections::btree_set::BTreeSet<_>>();
594
595			assert!(
596				endowed_accounts.len() == self.balances.len(),
597				"duplicate balances in genesis."
598			);
599
600			// Generate additional dev accounts.
601			if let Some((num_accounts, balance, ref derivation)) = self.dev_accounts {
602				// Using the provided derivation string or default to `"//Sender//{}`".
603				Pallet::<T, I>::derive_dev_account(
604					num_accounts,
605					balance,
606					derivation.as_deref().unwrap_or(DEFAULT_ADDRESS_URI),
607				);
608			}
609			for &(ref who, free) in self.balances.iter() {
610				frame_system::Pallet::<T>::inc_providers(who);
611				assert!(T::AccountStore::insert(who, AccountData { free, ..Default::default() })
612					.is_ok());
613			}
614		}
615	}
616
617	#[pallet::hooks]
618	impl<T: Config<I>, I: 'static> Hooks<BlockNumberFor<T>> for Pallet<T, I> {
619		fn integrity_test() {
620			#[cfg(not(feature = "insecure_zero_ed"))]
621			assert!(
622				!<T as Config<I>>::ExistentialDeposit::get().is_zero(),
623				"The existential deposit must be greater than zero!"
624			);
625
626			assert!(
627				T::MaxFreezes::get() >= <T::RuntimeFreezeReason as VariantCount>::VARIANT_COUNT,
628				"MaxFreezes should be greater than or equal to the number of freeze reasons: {} < {}",
629				T::MaxFreezes::get(), <T::RuntimeFreezeReason as VariantCount>::VARIANT_COUNT,
630			);
631		}
632
633		#[cfg(feature = "try-runtime")]
634		fn try_state(n: BlockNumberFor<T>) -> Result<(), sp_runtime::TryRuntimeError> {
635			Self::do_try_state(n)
636		}
637	}
638
639	#[pallet::call(weight(<T as Config<I>>::WeightInfo))]
640	impl<T: Config<I>, I: 'static> Pallet<T, I> {
641		/// Transfer some liquid free balance to another account.
642		///
643		/// `transfer_allow_death` will set the `FreeBalance` of the sender and receiver.
644		/// If the sender's account is below the existential deposit as a result
645		/// of the transfer, the account will be reaped.
646		///
647		/// The dispatch origin for this call must be `Signed` by the transactor.
648		#[pallet::call_index(0)]
649		pub fn transfer_allow_death(
650			origin: OriginFor<T>,
651			dest: AccountIdLookupOf<T>,
652			#[pallet::compact] value: T::Balance,
653		) -> DispatchResult {
654			let source = ensure_signed(origin)?;
655			let dest = T::Lookup::lookup(dest)?;
656			<Self as fungible::Mutate<_>>::transfer(&source, &dest, value, Expendable)?;
657			Ok(())
658		}
659
660		/// Exactly as `transfer_allow_death`, except the origin must be root and the source account
661		/// may be specified.
662		#[pallet::call_index(2)]
663		pub fn force_transfer(
664			origin: OriginFor<T>,
665			source: AccountIdLookupOf<T>,
666			dest: AccountIdLookupOf<T>,
667			#[pallet::compact] value: T::Balance,
668		) -> DispatchResult {
669			ensure_root(origin)?;
670			let source = T::Lookup::lookup(source)?;
671			let dest = T::Lookup::lookup(dest)?;
672			<Self as fungible::Mutate<_>>::transfer(&source, &dest, value, Expendable)?;
673			Ok(())
674		}
675
676		/// Same as the [`transfer_allow_death`] call, but with a check that the transfer will not
677		/// kill the origin account.
678		///
679		/// 99% of the time you want [`transfer_allow_death`] instead.
680		///
681		/// [`transfer_allow_death`]: struct.Pallet.html#method.transfer
682		#[pallet::call_index(3)]
683		pub fn transfer_keep_alive(
684			origin: OriginFor<T>,
685			dest: AccountIdLookupOf<T>,
686			#[pallet::compact] value: T::Balance,
687		) -> DispatchResult {
688			let source = ensure_signed(origin)?;
689			let dest = T::Lookup::lookup(dest)?;
690			<Self as fungible::Mutate<_>>::transfer(&source, &dest, value, Preserve)?;
691			Ok(())
692		}
693
694		/// Transfer the entire transferable balance from the caller account.
695		///
696		/// NOTE: This function only attempts to transfer _transferable_ balances. This means that
697		/// any locked, reserved, or existential deposits (when `keep_alive` is `true`), will not be
698		/// transferred by this function. To ensure that this function results in a killed account,
699		/// you might need to prepare the account by removing any reference counters, storage
700		/// deposits, etc...
701		///
702		/// The dispatch origin of this call must be Signed.
703		///
704		/// - `dest`: The recipient of the transfer.
705		/// - `keep_alive`: A boolean to determine if the `transfer_all` operation should send all
706		///   of the funds the account has, causing the sender account to be killed (false), or
707		///   transfer everything except at least the existential deposit, which will guarantee to
708		///   keep the sender account alive (true).
709		#[pallet::call_index(4)]
710		pub fn transfer_all(
711			origin: OriginFor<T>,
712			dest: AccountIdLookupOf<T>,
713			keep_alive: bool,
714		) -> DispatchResult {
715			let transactor = ensure_signed(origin)?;
716			let keep_alive = if keep_alive { Preserve } else { Expendable };
717			let reducible_balance = <Self as fungible::Inspect<_>>::reducible_balance(
718				&transactor,
719				keep_alive,
720				Fortitude::Polite,
721			);
722			let dest = T::Lookup::lookup(dest)?;
723			<Self as fungible::Mutate<_>>::transfer(
724				&transactor,
725				&dest,
726				reducible_balance,
727				keep_alive,
728			)?;
729			Ok(())
730		}
731
732		/// Unreserve some balance from a user by force.
733		///
734		/// Can only be called by ROOT.
735		#[pallet::call_index(5)]
736		pub fn force_unreserve(
737			origin: OriginFor<T>,
738			who: AccountIdLookupOf<T>,
739			amount: T::Balance,
740		) -> DispatchResult {
741			ensure_root(origin)?;
742			let who = T::Lookup::lookup(who)?;
743			let _leftover = <Self as ReservableCurrency<_>>::unreserve(&who, amount);
744			Ok(())
745		}
746
747		/// Upgrade a specified account.
748		///
749		/// - `origin`: Must be `Signed`.
750		/// - `who`: The account to be upgraded.
751		///
752		/// This will waive the transaction fee if at least all but 10% of the accounts needed to
753		/// be upgraded. (We let some not have to be upgraded just in order to allow for the
754		/// possibility of churn).
755		#[pallet::call_index(6)]
756		#[pallet::weight(T::WeightInfo::upgrade_accounts(who.len() as u32))]
757		pub fn upgrade_accounts(
758			origin: OriginFor<T>,
759			who: Vec<T::AccountId>,
760		) -> DispatchResultWithPostInfo {
761			ensure_signed(origin)?;
762			if who.is_empty() {
763				return Ok(Pays::Yes.into())
764			}
765			let mut upgrade_count = 0;
766			for i in &who {
767				let upgraded = Self::ensure_upgraded(i);
768				if upgraded {
769					upgrade_count.saturating_inc();
770				}
771			}
772			let proportion_upgraded = Perbill::from_rational(upgrade_count, who.len() as u32);
773			if proportion_upgraded >= Perbill::from_percent(90) {
774				Ok(Pays::No.into())
775			} else {
776				Ok(Pays::Yes.into())
777			}
778		}
779
780		/// Set the regular balance of a given account.
781		///
782		/// The dispatch origin for this call is `root`.
783		#[pallet::call_index(8)]
784		#[pallet::weight(
785			T::WeightInfo::force_set_balance_creating() // Creates a new account.
786				.max(T::WeightInfo::force_set_balance_killing()) // Kills an existing account.
787		)]
788		pub fn force_set_balance(
789			origin: OriginFor<T>,
790			who: AccountIdLookupOf<T>,
791			#[pallet::compact] new_free: T::Balance,
792		) -> DispatchResult {
793			ensure_root(origin)?;
794			let who = T::Lookup::lookup(who)?;
795			let existential_deposit = Self::ed();
796
797			let wipeout = new_free < existential_deposit;
798			let new_free = if wipeout { Zero::zero() } else { new_free };
799
800			// First we try to modify the account's balance to the forced balance.
801			let old_free = Self::mutate_account_handling_dust(&who, false, |account| {
802				let old_free = account.free;
803				account.free = new_free;
804				old_free
805			})?;
806
807			// This will adjust the total issuance, which was not done by the `mutate_account`
808			// above.
809			if new_free > old_free {
810				mem::drop(PositiveImbalance::<T, I>::new(new_free - old_free));
811			} else if new_free < old_free {
812				mem::drop(NegativeImbalance::<T, I>::new(old_free - new_free));
813			}
814
815			Self::deposit_event(Event::BalanceSet { who, free: new_free });
816			Ok(())
817		}
818
819		/// Adjust the total issuance in a saturating way.
820		///
821		/// Can only be called by root and always needs a positive `delta`.
822		///
823		/// # Example
824		#[doc = docify::embed!("./src/tests/dispatchable_tests.rs", force_adjust_total_issuance_example)]
825		#[pallet::call_index(9)]
826		#[pallet::weight(T::WeightInfo::force_adjust_total_issuance())]
827		pub fn force_adjust_total_issuance(
828			origin: OriginFor<T>,
829			direction: AdjustmentDirection,
830			#[pallet::compact] delta: T::Balance,
831		) -> DispatchResult {
832			ensure_root(origin)?;
833
834			ensure!(delta > Zero::zero(), Error::<T, I>::DeltaZero);
835
836			let old = TotalIssuance::<T, I>::get();
837			let new = match direction {
838				AdjustmentDirection::Increase => old.saturating_add(delta),
839				AdjustmentDirection::Decrease => old.saturating_sub(delta),
840			};
841
842			ensure!(InactiveIssuance::<T, I>::get() <= new, Error::<T, I>::IssuanceDeactivated);
843			TotalIssuance::<T, I>::set(new);
844
845			Self::deposit_event(Event::<T, I>::TotalIssuanceForced { old, new });
846
847			Ok(())
848		}
849
850		/// Burn the specified liquid free balance from the origin account.
851		///
852		/// If the origin's account ends up below the existential deposit as a result
853		/// of the burn and `keep_alive` is false, the account will be reaped.
854		///
855		/// Unlike sending funds to a _burn_ address, which merely makes the funds inaccessible,
856		/// this `burn` operation will reduce total issuance by the amount _burned_.
857		#[pallet::call_index(10)]
858		#[pallet::weight(if *keep_alive {T::WeightInfo::burn_allow_death() } else {T::WeightInfo::burn_keep_alive()})]
859		pub fn burn(
860			origin: OriginFor<T>,
861			#[pallet::compact] value: T::Balance,
862			keep_alive: bool,
863		) -> DispatchResult {
864			let source = ensure_signed(origin)?;
865			let preservation = if keep_alive { Preserve } else { Expendable };
866			<Self as fungible::Mutate<_>>::burn_from(
867				&source,
868				value,
869				preservation,
870				Precision::Exact,
871				Polite,
872			)?;
873			Ok(())
874		}
875	}
876
877	impl<T: Config<I>, I: 'static> Pallet<T, I> {
878		/// Public function to get the total issuance.
879		pub fn total_issuance() -> T::Balance {
880			TotalIssuance::<T, I>::get()
881		}
882
883		/// Public function to get the inactive issuance.
884		pub fn inactive_issuance() -> T::Balance {
885			InactiveIssuance::<T, I>::get()
886		}
887
888		/// Public function to access the Locks storage.
889		pub fn locks(who: &T::AccountId) -> WeakBoundedVec<BalanceLock<T::Balance>, T::MaxLocks> {
890			Locks::<T, I>::get(who)
891		}
892
893		/// Public function to access the reserves storage.
894		pub fn reserves(
895			who: &T::AccountId,
896		) -> BoundedVec<ReserveData<T::ReserveIdentifier, T::Balance>, T::MaxReserves> {
897			Reserves::<T, I>::get(who)
898		}
899
900		fn ed() -> T::Balance {
901			T::ExistentialDeposit::get()
902		}
903		/// Ensure the account `who` is using the new logic.
904		///
905		/// Returns `true` if the account did get upgraded, `false` if it didn't need upgrading.
906		pub fn ensure_upgraded(who: &T::AccountId) -> bool {
907			let mut a = T::AccountStore::get(who);
908			if a.flags.is_new_logic() {
909				return false
910			}
911			a.flags.set_new_logic();
912			if !a.reserved.is_zero() && a.frozen.is_zero() {
913				if system::Pallet::<T>::providers(who) == 0 {
914					// Gah!! We have no provider refs :(
915					// This shouldn't practically happen, but we need a failsafe anyway: let's give
916					// them enough for an ED.
917					log::warn!(
918						target: LOG_TARGET,
919						"account with a non-zero reserve balance has no provider refs, account_id: '{:?}'.",
920						who
921					);
922					a.free = a.free.max(Self::ed());
923					system::Pallet::<T>::inc_providers(who);
924				}
925				let _ = system::Pallet::<T>::inc_consumers_without_limit(who).defensive();
926			}
927			// Should never fail - we're only setting a bit.
928			let _ = T::AccountStore::try_mutate_exists(who, |account| -> DispatchResult {
929				*account = Some(a);
930				Ok(())
931			});
932			Self::deposit_event(Event::Upgraded { who: who.clone() });
933			return true
934		}
935
936		/// Get the free balance of an account.
937		pub fn free_balance(who: impl core::borrow::Borrow<T::AccountId>) -> T::Balance {
938			Self::account(who.borrow()).free
939		}
940
941		/// Get the balance of an account that can be used for transfers, reservations, or any other
942		/// non-locking, non-transaction-fee activity. Will be at most `free_balance`.
943		pub fn usable_balance(who: impl core::borrow::Borrow<T::AccountId>) -> T::Balance {
944			<Self as fungible::Inspect<_>>::reducible_balance(who.borrow(), Expendable, Polite)
945		}
946
947		/// Get the balance of an account that can be used for paying transaction fees (not tipping,
948		/// or any other kind of fees, though). Will be at most `free_balance`.
949		///
950		/// This requires that the account stays alive.
951		pub fn usable_balance_for_fees(who: impl core::borrow::Borrow<T::AccountId>) -> T::Balance {
952			<Self as fungible::Inspect<_>>::reducible_balance(who.borrow(), Protect, Polite)
953		}
954
955		/// Get the reserved balance of an account.
956		pub fn reserved_balance(who: impl core::borrow::Borrow<T::AccountId>) -> T::Balance {
957			Self::account(who.borrow()).reserved
958		}
959
960		/// Get both the free and reserved balances of an account.
961		pub(crate) fn account(who: &T::AccountId) -> AccountData<T::Balance> {
962			T::AccountStore::get(who)
963		}
964
965		/// Mutate an account to some new value, or delete it entirely with `None`. Will enforce
966		/// `ExistentialDeposit` law, annulling the account as needed.
967		///
968		/// It returns the result from the closure. Any dust is handled through the low-level
969		/// `fungible::Unbalanced` trap-door for legacy dust management.
970		///
971		/// NOTE: Doesn't do any preparatory work for creating a new account, so should only be used
972		/// when it is known that the account already exists.
973		///
974		/// NOTE: LOW-LEVEL: This will not attempt to maintain total issuance. It is expected that
975		/// the caller will do this.
976		pub(crate) fn mutate_account_handling_dust<R>(
977			who: &T::AccountId,
978			force_consumer_bump: bool,
979			f: impl FnOnce(&mut AccountData<T::Balance>) -> R,
980		) -> Result<R, DispatchError> {
981			let (r, maybe_dust) = Self::mutate_account(who, force_consumer_bump, f)?;
982			if let Some(dust) = maybe_dust {
983				<Self as fungible::Unbalanced<_>>::handle_raw_dust(dust);
984			}
985			Ok(r)
986		}
987
988		/// Mutate an account to some new value, or delete it entirely with `None`. Will enforce
989		/// `ExistentialDeposit` law, annulling the account as needed.
990		///
991		/// It returns the result from the closure. Any dust is handled through the low-level
992		/// `fungible::Unbalanced` trap-door for legacy dust management.
993		///
994		/// NOTE: Doesn't do any preparatory work for creating a new account, so should only be used
995		/// when it is known that the account already exists.
996		///
997		/// NOTE: LOW-LEVEL: This will not attempt to maintain total issuance. It is expected that
998		/// the caller will do this.
999		pub(crate) fn try_mutate_account_handling_dust<R, E: From<DispatchError>>(
1000			who: &T::AccountId,
1001			force_consumer_bump: bool,
1002			f: impl FnOnce(&mut AccountData<T::Balance>, bool) -> Result<R, E>,
1003		) -> Result<R, E> {
1004			let (r, maybe_dust) = Self::try_mutate_account(who, force_consumer_bump, f)?;
1005			if let Some(dust) = maybe_dust {
1006				<Self as fungible::Unbalanced<_>>::handle_raw_dust(dust);
1007			}
1008			Ok(r)
1009		}
1010
1011		/// Mutate an account to some new value, or delete it entirely with `None`. Will enforce
1012		/// `ExistentialDeposit` law, annulling the account as needed.
1013		///
1014		/// It returns both the result from the closure, and an optional amount of dust
1015		/// which should be handled once it is known that all nested mutates that could affect
1016		/// storage items what the dust handler touches have completed.
1017		///
1018		/// NOTE: Doesn't do any preparatory work for creating a new account, so should only be used
1019		/// when it is known that the account already exists.
1020		///
1021		/// NOTE: LOW-LEVEL: This will not attempt to maintain total issuance. It is expected that
1022		/// the caller will do this.
1023		///
1024		/// NOTE: LOW-LEVEL: `force_consumer_bump` is mainly there to accomodate for locks, which
1025		/// have no ability in their API to return an error, and therefore better force increment
1026		/// the consumer, or else the system will be inconsistent. See `consumer_limits_tests`.
1027		pub(crate) fn mutate_account<R>(
1028			who: &T::AccountId,
1029			force_consumer_bump: bool,
1030			f: impl FnOnce(&mut AccountData<T::Balance>) -> R,
1031		) -> Result<(R, Option<T::Balance>), DispatchError> {
1032			Self::try_mutate_account(who, force_consumer_bump, |a, _| -> Result<R, DispatchError> {
1033				Ok(f(a))
1034			})
1035		}
1036
1037		/// Returns `true` when `who` has some providers or `insecure_zero_ed` feature is disabled.
1038		/// Returns `false` otherwise.
1039		#[cfg(not(feature = "insecure_zero_ed"))]
1040		fn have_providers_or_no_zero_ed(_: &T::AccountId) -> bool {
1041			true
1042		}
1043
1044		/// Returns `true` when `who` has some providers or `insecure_zero_ed` feature is disabled.
1045		/// Returns `false` otherwise.
1046		#[cfg(feature = "insecure_zero_ed")]
1047		fn have_providers_or_no_zero_ed(who: &T::AccountId) -> bool {
1048			frame_system::Pallet::<T>::providers(who) > 0
1049		}
1050
1051		/// Mutate an account to some new value, or delete it entirely with `None`. Will enforce
1052		/// `ExistentialDeposit` law, annulling the account as needed. This will do nothing if the
1053		/// result of `f` is an `Err`.
1054		///
1055		/// It returns both the result from the closure, and an optional amount of dust
1056		/// which should be handled once it is known that all nested mutates that could affect
1057		/// storage items what the dust handler touches have completed.
1058		///
1059		/// NOTE: Doesn't do any preparatory work for creating a new account, so should only be used
1060		/// when it is known that the account already exists.
1061		///
1062		/// NOTE: LOW-LEVEL: This will not attempt to maintain total issuance. It is expected that
1063		/// the caller will do this.
1064		pub(crate) fn try_mutate_account<R, E: From<DispatchError>>(
1065			who: &T::AccountId,
1066			force_consumer_bump: bool,
1067			f: impl FnOnce(&mut AccountData<T::Balance>, bool) -> Result<R, E>,
1068		) -> Result<(R, Option<T::Balance>), E> {
1069			Self::ensure_upgraded(who);
1070			let result = T::AccountStore::try_mutate_exists(who, |maybe_account| {
1071				let is_new = maybe_account.is_none();
1072				let mut account = maybe_account.take().unwrap_or_default();
1073				let did_provide =
1074					account.free >= Self::ed() && Self::have_providers_or_no_zero_ed(who);
1075				let did_consume =
1076					!is_new && (!account.reserved.is_zero() || !account.frozen.is_zero());
1077
1078				let result = f(&mut account, is_new)?;
1079
1080				let does_provide = account.free >= Self::ed();
1081				let does_consume = !account.reserved.is_zero() || !account.frozen.is_zero();
1082
1083				if !did_provide && does_provide {
1084					frame_system::Pallet::<T>::inc_providers(who);
1085				}
1086				if did_consume && !does_consume {
1087					frame_system::Pallet::<T>::dec_consumers(who);
1088				}
1089				if !did_consume && does_consume {
1090					if force_consumer_bump {
1091						// If we are forcing a consumer bump, we do it without limit.
1092						frame_system::Pallet::<T>::inc_consumers_without_limit(who)?;
1093					} else {
1094						frame_system::Pallet::<T>::inc_consumers(who)?;
1095					}
1096				}
1097				if does_consume && frame_system::Pallet::<T>::consumers(who) == 0 {
1098					// NOTE: This is a failsafe and should not happen for normal accounts. A normal
1099					// account should have gotten a consumer ref in `!did_consume && does_consume`
1100					// at some point.
1101					log::error!(target: LOG_TARGET, "Defensively bumping a consumer ref.");
1102					frame_system::Pallet::<T>::inc_consumers(who)?;
1103				}
1104				if did_provide && !does_provide {
1105					// This could reap the account so must go last.
1106					frame_system::Pallet::<T>::dec_providers(who).inspect_err(|_| {
1107						// best-effort revert consumer change.
1108						if did_consume && !does_consume {
1109							let _ = frame_system::Pallet::<T>::inc_consumers(who).defensive();
1110						}
1111						if !did_consume && does_consume {
1112							let _ = frame_system::Pallet::<T>::dec_consumers(who);
1113						}
1114					})?;
1115				}
1116
1117				let maybe_endowed = if is_new { Some(account.free) } else { None };
1118
1119				// Handle any steps needed after mutating an account.
1120				//
1121				// This includes DustRemoval unbalancing, in the case than the `new` account's total
1122				// balance is non-zero but below ED.
1123				//
1124				// Updates `maybe_account` to `Some` iff the account has sufficient balance.
1125				// Evaluates `maybe_dust`, which is `Some` containing the dust to be dropped, iff
1126				// some dust should be dropped.
1127				//
1128				// We should never be dropping if reserved is non-zero. Reserved being non-zero
1129				// should imply that we have a consumer ref, so this is economically safe.
1130				let ed = Self::ed();
1131				let maybe_dust = if account.free < ed && account.reserved.is_zero() {
1132					if account.free.is_zero() {
1133						None
1134					} else {
1135						Some(account.free)
1136					}
1137				} else {
1138					assert!(
1139						account.free.is_zero() || account.free >= ed || !account.reserved.is_zero()
1140					);
1141					*maybe_account = Some(account);
1142					None
1143				};
1144				Ok((maybe_endowed, maybe_dust, result))
1145			});
1146			result.map(|(maybe_endowed, maybe_dust, result)| {
1147				if let Some(endowed) = maybe_endowed {
1148					Self::deposit_event(Event::Endowed {
1149						account: who.clone(),
1150						free_balance: endowed,
1151					});
1152				}
1153				if let Some(amount) = maybe_dust {
1154					Pallet::<T, I>::deposit_event(Event::DustLost { account: who.clone(), amount });
1155				}
1156				(result, maybe_dust)
1157			})
1158		}
1159
1160		/// Update the account entry for `who`, given the locks.
1161		pub(crate) fn update_locks(who: &T::AccountId, locks: &[BalanceLock<T::Balance>]) {
1162			let bounded_locks = WeakBoundedVec::<_, T::MaxLocks>::force_from(
1163				locks.to_vec(),
1164				Some("Balances Update Locks"),
1165			);
1166
1167			if locks.len() as u32 > T::MaxLocks::get() {
1168				log::warn!(
1169					target: LOG_TARGET,
1170					"Warning: A user has more currency locks than expected. \
1171					A runtime configuration adjustment may be needed."
1172				);
1173			}
1174			let freezes = Freezes::<T, I>::get(who);
1175			let mut prev_frozen = Zero::zero();
1176			let mut after_frozen = Zero::zero();
1177			// We do not alter ED, so the account will not get dusted. Yet, consumer limit might be
1178			// full, therefore we pass `true` into `mutate_account` to make sure this cannot fail
1179			let res = Self::mutate_account(who, true, |b| {
1180				prev_frozen = b.frozen;
1181				b.frozen = Zero::zero();
1182				for l in locks.iter() {
1183					b.frozen = b.frozen.max(l.amount);
1184				}
1185				for l in freezes.iter() {
1186					b.frozen = b.frozen.max(l.amount);
1187				}
1188				after_frozen = b.frozen;
1189			});
1190			match res {
1191				Ok((_, None)) => {
1192					// expected -- all good.
1193				},
1194				Ok((_, Some(_dust))) => {
1195					Self::deposit_event(Event::Unexpected(UnexpectedKind::BalanceUpdated));
1196					defensive!("caused unexpected dusting/balance update.");
1197				},
1198				_ => {
1199					Self::deposit_event(Event::Unexpected(UnexpectedKind::FailedToMutateAccount));
1200					defensive!("errored in mutate_account");
1201				},
1202			}
1203
1204			match locks.is_empty() {
1205				true => Locks::<T, I>::remove(who),
1206				false => Locks::<T, I>::insert(who, bounded_locks),
1207			}
1208
1209			if prev_frozen > after_frozen {
1210				let amount = prev_frozen.saturating_sub(after_frozen);
1211				Self::deposit_event(Event::Unlocked { who: who.clone(), amount });
1212			} else if after_frozen > prev_frozen {
1213				let amount = after_frozen.saturating_sub(prev_frozen);
1214				Self::deposit_event(Event::Locked { who: who.clone(), amount });
1215			}
1216		}
1217
1218		/// Update the account entry for `who`, given the locks.
1219		pub(crate) fn update_freezes(
1220			who: &T::AccountId,
1221			freezes: BoundedSlice<IdAmount<T::FreezeIdentifier, T::Balance>, T::MaxFreezes>,
1222		) -> DispatchResult {
1223			let mut prev_frozen = Zero::zero();
1224			let mut after_frozen = Zero::zero();
1225			let (_, maybe_dust) = Self::mutate_account(who, false, |b| {
1226				prev_frozen = b.frozen;
1227				b.frozen = Zero::zero();
1228				for l in Locks::<T, I>::get(who).iter() {
1229					b.frozen = b.frozen.max(l.amount);
1230				}
1231				for l in freezes.iter() {
1232					b.frozen = b.frozen.max(l.amount);
1233				}
1234				after_frozen = b.frozen;
1235			})?;
1236			if maybe_dust.is_some() {
1237				Self::deposit_event(Event::Unexpected(UnexpectedKind::BalanceUpdated));
1238				defensive!("caused unexpected dusting/balance update.");
1239			}
1240			if freezes.is_empty() {
1241				Freezes::<T, I>::remove(who);
1242			} else {
1243				Freezes::<T, I>::insert(who, freezes);
1244			}
1245			if prev_frozen > after_frozen {
1246				let amount = prev_frozen.saturating_sub(after_frozen);
1247				Self::deposit_event(Event::Thawed { who: who.clone(), amount });
1248			} else if after_frozen > prev_frozen {
1249				let amount = after_frozen.saturating_sub(prev_frozen);
1250				Self::deposit_event(Event::Frozen { who: who.clone(), amount });
1251			}
1252			Ok(())
1253		}
1254
1255		/// Move the reserved balance of one account into the balance of another, according to
1256		/// `status`. This will respect freezes/locks only if `fortitude` is `Polite`.
1257		///
1258		/// Is a no-op if the value to be moved is zero.
1259		///
1260		/// NOTE: returns actual amount of transferred value in `Ok` case.
1261		pub(crate) fn do_transfer_reserved(
1262			slashed: &T::AccountId,
1263			beneficiary: &T::AccountId,
1264			value: T::Balance,
1265			precision: Precision,
1266			fortitude: Fortitude,
1267			status: Status,
1268		) -> Result<T::Balance, DispatchError> {
1269			if value.is_zero() {
1270				return Ok(Zero::zero())
1271			}
1272
1273			let max = <Self as fungible::InspectHold<_>>::reducible_total_balance_on_hold(
1274				slashed, fortitude,
1275			);
1276			let actual = match precision {
1277				Precision::BestEffort => value.min(max),
1278				Precision::Exact => value,
1279			};
1280			ensure!(actual <= max, TokenError::FundsUnavailable);
1281			if slashed == beneficiary {
1282				return match status {
1283					Status::Free => Ok(actual.saturating_sub(Self::unreserve(slashed, actual))),
1284					Status::Reserved => Ok(actual),
1285				}
1286			}
1287
1288			let ((_, maybe_dust_1), maybe_dust_2) = Self::try_mutate_account(
1289				beneficiary,
1290				false,
1291				|to_account, is_new| -> Result<((), Option<T::Balance>), DispatchError> {
1292					ensure!(!is_new, Error::<T, I>::DeadAccount);
1293					Self::try_mutate_account(slashed, false, |from_account, _| -> DispatchResult {
1294						match status {
1295							Status::Free =>
1296								to_account.free = to_account
1297									.free
1298									.checked_add(&actual)
1299									.ok_or(ArithmeticError::Overflow)?,
1300							Status::Reserved =>
1301								to_account.reserved = to_account
1302									.reserved
1303									.checked_add(&actual)
1304									.ok_or(ArithmeticError::Overflow)?,
1305						}
1306						from_account.reserved.saturating_reduce(actual);
1307						Ok(())
1308					})
1309				},
1310			)?;
1311
1312			if let Some(dust) = maybe_dust_1 {
1313				<Self as fungible::Unbalanced<_>>::handle_raw_dust(dust);
1314			}
1315			if let Some(dust) = maybe_dust_2 {
1316				<Self as fungible::Unbalanced<_>>::handle_raw_dust(dust);
1317			}
1318
1319			Self::deposit_event(Event::ReserveRepatriated {
1320				from: slashed.clone(),
1321				to: beneficiary.clone(),
1322				amount: actual,
1323				destination_status: status,
1324			});
1325			Ok(actual)
1326		}
1327
1328		/// Generate dev account from derivation(hard) string.
1329		pub fn derive_dev_account(num_accounts: u32, balance: T::Balance, derivation: &str) {
1330			// Ensure that the number of accounts is not zero.
1331			assert!(num_accounts > 0, "num_accounts must be greater than zero");
1332
1333			assert!(
1334				balance >= <T as Config<I>>::ExistentialDeposit::get(),
1335				"the balance of any account should always be at least the existential deposit.",
1336			);
1337
1338			assert!(
1339				derivation.contains("{}"),
1340				"Invalid derivation, expected `{{}}` as part of the derivation"
1341			);
1342
1343			for index in 0..num_accounts {
1344				// Replace "{}" in the derivation string with the index.
1345				let derivation_string = derivation.replace("{}", &index.to_string());
1346
1347				// Generate the key pair from the derivation string using sr25519.
1348				let pair: SrPair = Pair::from_string(&derivation_string, None)
1349					.expect(&format!("Failed to parse derivation string: {derivation_string}"));
1350
1351				// Convert the public key to AccountId.
1352				let who = T::AccountId::decode(&mut &pair.public().encode()[..])
1353					.expect(&format!("Failed to decode public key from pair: {:?}", pair.public()));
1354
1355				// Set the balance for the generated account.
1356				Self::mutate_account_handling_dust(&who, false, |account| {
1357					account.free = balance;
1358				})
1359				.expect(&format!("Failed to add account to keystore: {:?}", who));
1360			}
1361		}
1362	}
1363
1364	#[cfg(any(test, feature = "try-runtime"))]
1365	impl<T: Config<I>, I: 'static> Pallet<T, I> {
1366		pub(crate) fn do_try_state(
1367			_n: BlockNumberFor<T>,
1368		) -> Result<(), sp_runtime::TryRuntimeError> {
1369			Self::hold_and_freeze_count()?;
1370			Self::account_frozen_greater_than_locks()?;
1371			Self::account_frozen_greater_than_freezes()?;
1372			Ok(())
1373		}
1374
1375		fn hold_and_freeze_count() -> Result<(), sp_runtime::TryRuntimeError> {
1376			Holds::<T, I>::iter_keys().try_for_each(|k| {
1377				if Holds::<T, I>::decode_len(k).unwrap_or(0) >
1378					T::RuntimeHoldReason::VARIANT_COUNT as usize
1379				{
1380					Err("Found `Hold` with too many elements")
1381				} else {
1382					Ok(())
1383				}
1384			})?;
1385
1386			Freezes::<T, I>::iter_keys().try_for_each(|k| {
1387				if Freezes::<T, I>::decode_len(k).unwrap_or(0) > T::MaxFreezes::get() as usize {
1388					Err("Found `Freeze` with too many elements")
1389				} else {
1390					Ok(())
1391				}
1392			})?;
1393
1394			Ok(())
1395		}
1396
1397		fn account_frozen_greater_than_locks() -> Result<(), sp_runtime::TryRuntimeError> {
1398			Locks::<T, I>::iter().try_for_each(|(who, locks)| {
1399				let max_locks = locks.iter().map(|l| l.amount).max().unwrap_or_default();
1400				let frozen = T::AccountStore::get(&who).frozen;
1401				if max_locks > frozen {
1402					log::warn!(
1403						target: crate::LOG_TARGET,
1404						"Maximum lock of {:?} ({:?}) is greater than the frozen balance {:?}",
1405						who,
1406						max_locks,
1407						frozen
1408					);
1409					Err("bad locks".into())
1410				} else {
1411					Ok(())
1412				}
1413			})
1414		}
1415
1416		fn account_frozen_greater_than_freezes() -> Result<(), sp_runtime::TryRuntimeError> {
1417			Freezes::<T, I>::iter().try_for_each(|(who, freezes)| {
1418				let max_locks = freezes.iter().map(|l| l.amount).max().unwrap_or_default();
1419				let frozen = T::AccountStore::get(&who).frozen;
1420				if max_locks > frozen {
1421					log::warn!(
1422						target: crate::LOG_TARGET,
1423						"Maximum freeze of {:?} ({:?}) is greater than the frozen balance {:?}",
1424						who,
1425						max_locks,
1426						frozen
1427					);
1428					Err("bad freezes".into())
1429				} else {
1430					Ok(())
1431				}
1432			})
1433		}
1434	}
1435}