frame_support/traits/tokens/fungible/

regular.rs

// This file is part of Substrate.

// Copyright (C) Parity Technologies (UK) Ltd.
// SPDX-License-Identifier: Apache-2.0

// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// 	http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

//! `Inspect` and `Mutate` traits for working with regular balances.
//!
//! See the [`crate::traits::fungible`] doc for more information about fungible traits.

use crate::{
	ensure,
	traits::{
		tokens::{
			misc::{
				Balance, DepositConsequence,
				Fortitude::{self, Force, Polite},
				Precision::{self, BestEffort, Exact},
				Preservation::{self, Expendable},
				Provenance::{self, Extant},
				WithdrawConsequence,
			},
			Imbalance as ImbalanceT,
		},
		SameOrOther, TryDrop,
	},
};
use core::marker::PhantomData;
use sp_arithmetic::traits::{CheckedAdd, CheckedSub, One, Zero};
use sp_runtime::{
	traits::{Bounded, Saturating},
	ArithmeticError, DispatchError, TokenError,
};

use super::{Credit, Debt, HandleImbalanceDrop, Imbalance};

/// Trait for providing balance-inspection access to a fungible asset.
pub trait Inspect<AccountId>: Sized {
	/// Scalar type for representing balance of an account.
	type Balance: Balance;

	/// The total amount of issuance in the system.
	fn total_issuance() -> Self::Balance;

	/// The total amount of issuance in the system excluding those which are controlled by the
	/// system.
	fn active_issuance() -> Self::Balance {
		Self::total_issuance()
	}

	/// The minimum balance any single account may have.
	fn minimum_balance() -> Self::Balance;

	/// Get the total amount of funds whose ultimate beneficial ownership can be determined as
	/// `who`.
	///
	/// This may include funds which are wholly inaccessible to `who`, either temporarily or even
	/// indefinitely.
	///
	/// For the amount of the balance which is currently free to be removed from the account without
	/// error, use [`Inspect::reducible_balance`].
	///
	/// For the amount of the balance which may eventually be free to be removed from the account,
	/// use `balance()`.
	fn total_balance(who: &AccountId) -> Self::Balance;

	/// Get the balance of `who` which does not include funds which are exclusively allocated to
	/// subsystems of the chain ("on hold" or "reserved").
	///
	/// In general this isn't especially useful outside of tests, and for practical purposes, you'll
	/// want to use [`Inspect::reducible_balance`].
	fn balance(who: &AccountId) -> Self::Balance;

	/// Get the maximum amount that `who` can withdraw/transfer successfully based on whether the
	/// account should be kept alive (`preservation`) or whether we are willing to force the
	/// reduction and potentially go below user-level restrictions on the minimum amount of the
	/// account.
	///
	/// Always less than or equal to [`Inspect::balance`].
	fn reducible_balance(
		who: &AccountId,
		preservation: Preservation,
		force: Fortitude,
	) -> Self::Balance;

	/// Returns `true` if the balance of `who` may be increased by `amount`.
	///
	/// - `who`: The account of which the balance should be increased by `amount`.
	/// - `amount`: How much should the balance be increased?
	/// - `provenance`: Will `amount` be minted to deposit it into `account` or is it already in the
	///   system?
	fn can_deposit(
		who: &AccountId,
		amount: Self::Balance,
		provenance: Provenance,
	) -> DepositConsequence;

	/// Returns `Success` if the balance of `who` may be decreased by `amount`, otherwise
	/// the consequence.
	fn can_withdraw(who: &AccountId, amount: Self::Balance) -> WithdrawConsequence<Self::Balance>;
}

/// Special dust type which can be type-safely converted into a [`Credit`].
#[must_use]
pub struct Dust<A, T: Inspect<A>>(pub T::Balance);

impl<A, T: Balanced<A>> Dust<A, T> {
	/// Convert `Dust` into an instance of `Credit`.
	pub fn into_credit(self) -> Credit<A, T> {
		Credit::<A, T>::new(self.0)
	}
}

/// A fungible token class where the balance can be set arbitrarily.
///
/// **WARNING**
/// Do not use this directly unless you want trouble, since it allows you to alter account balances
/// without keeping the issuance up to date. It has no safeguards against accidentally creating
/// token imbalances in your system leading to accidental inflation or deflation. It's really just
/// for the underlying datatype to implement so the user gets the much safer [`Balanced`] trait to
/// use.
pub trait Unbalanced<AccountId>: Inspect<AccountId> {
	/// Create some dust and handle it with [`Unbalanced::handle_dust`]. This is an unbalanced
	/// operation and it must only be used when an account is modified in a raw fashion, outside of
	/// the entire fungibles API. The `amount` is capped at [`Inspect::minimum_balance()`] - 1`.
	///
	/// This should not be reimplemented.
	fn handle_raw_dust(amount: Self::Balance) {
		Self::handle_dust(Dust(amount.min(Self::minimum_balance().saturating_sub(One::one()))))
	}

	/// Do something with the dust which has been destroyed from the system. [`Dust`] can be
	/// converted into a [`Credit`] with the [`Balanced`] trait impl.
	fn handle_dust(dust: Dust<AccountId, Self>);

	/// Forcefully set the balance of `who` to `amount`.
	///
	/// If this call executes successfully, you can `assert_eq!(Self::balance(), amount);`.
	///
	/// For implementations which include one or more balances on hold, then these are *not*
	/// included in the `amount`.
	///
	/// This function does its best to force the balance change through, but will not break system
	/// invariants such as any Existential Deposits needed or overflows/underflows.
	/// If this cannot be done for some reason (e.g. because the account cannot be created, deleted
	/// or would overflow) then an `Err` is returned.
	///
	/// If `Ok` is returned then its inner, then `Some` is the amount which was discarded as dust
	/// due to existential deposit requirements. The default implementation of
	/// [`Unbalanced::decrease_balance`] and [`Unbalanced::increase_balance`] converts this into an
	/// [`Imbalance`] and then passes it into [`Unbalanced::handle_dust`].
	fn write_balance(
		who: &AccountId,
		amount: Self::Balance,
	) -> Result<Option<Self::Balance>, DispatchError>;

	/// Set the total issuance to `amount`.
	fn set_total_issuance(amount: Self::Balance);

	/// Reduce the balance of `who` by `amount`.
	///
	/// If `precision` is [`Exact`] and it cannot be reduced by that amount for
	/// some reason, return `Err` and don't reduce it at all. If `precision` is [`BestEffort`], then
	/// reduce the balance of `who` by the most that is possible, up to `amount`.
	///
	/// In either case, if `Ok` is returned then the inner is the amount by which is was reduced.
	/// Minimum balance will be respected and thus the returned amount may be up to
	/// [`Inspect::minimum_balance()`] - 1` greater than `amount` in the case that the reduction
	/// caused the account to be deleted.
	///
	/// Any such excess must still be in the system when this returns — it must not have been
	/// disposed of through [`Unbalanced::handle_dust`]. Callers account for the returned amount,
	/// so an implementation that both reports the excess and traps it as dust makes them issue it
	/// a second time.
	fn decrease_balance(
		who: &AccountId,
		mut amount: Self::Balance,
		precision: Precision,
		preservation: Preservation,
		force: Fortitude,
	) -> Result<Self::Balance, DispatchError> {
		let old_balance = Self::balance(who);
		let reducible = Self::reducible_balance(who, preservation, force);
		match precision {
			BestEffort => amount = amount.min(reducible),
			Exact => ensure!(reducible >= amount, TokenError::FundsUnavailable),
		}

		let new_balance = old_balance.checked_sub(&amount).ok_or(TokenError::FundsUnavailable)?;
		if let Some(dust) = Self::write_balance(who, new_balance)? {
			Self::handle_dust(Dust(dust));
		}
		Ok(old_balance.saturating_sub(new_balance))
	}

	/// Increase the balance of `who` by `amount`.
	///
	/// If it cannot be increased by that amount for some reason, return `Err` and don't increase
	/// it at all. If Ok, return the imbalance.
	/// Minimum balance will be respected and an error will be returned if
	/// amount < [`Inspect::minimum_balance()`] when the account of `who` is zero.
	fn increase_balance(
		who: &AccountId,
		amount: Self::Balance,
		precision: Precision,
	) -> Result<Self::Balance, DispatchError> {
		let old_balance = Self::balance(who);
		let reserved = Self::total_balance(who).saturating_sub(old_balance);
		let new_balance = if let BestEffort = precision {
			let max_balance = Self::Balance::max_value().saturating_sub(reserved);
			old_balance.saturating_add(amount).min(max_balance)
		} else {
			old_balance.checked_add(&amount).ok_or(ArithmeticError::Overflow)?
		};
		new_balance.checked_add(&reserved).ok_or(ArithmeticError::Overflow)?;

		if new_balance < Self::minimum_balance() {
			// Attempt to increase from 0 to below minimum -> stays at zero.
			if let BestEffort = precision {
				Ok(Default::default())
			} else {
				Err(TokenError::BelowMinimum.into())
			}
		} else {
			if new_balance == old_balance {
				Ok(Default::default())
			} else {
				if let Some(dust) = Self::write_balance(who, new_balance)? {
					Self::handle_dust(Dust(dust));
				}
				Ok(new_balance.saturating_sub(old_balance))
			}
		}
	}

	/// Reduce the active issuance by some amount.
	fn deactivate(_: Self::Balance) {}

	/// Increase the active issuance by some amount, up to the outstanding amount reduced.
	fn reactivate(_: Self::Balance) {}
}

/// Trait for providing a basic fungible asset.
pub trait Mutate<AccountId>: Inspect<AccountId> + Unbalanced<AccountId>
where
	AccountId: Eq,
{
	/// Increase the balance of `who` by exactly `amount`, minting new tokens. If that isn't
	/// possible then an `Err` is returned and nothing is changed.
	fn mint_into(who: &AccountId, amount: Self::Balance) -> Result<Self::Balance, DispatchError> {
		Self::total_issuance().checked_add(&amount).ok_or(ArithmeticError::Overflow)?;
		let actual = Self::increase_balance(who, amount, Exact)?;
		Self::set_total_issuance(Self::total_issuance().saturating_add(actual));
		Self::done_mint_into(who, amount);
		Ok(actual)
	}

	/// Attempt to decrease the balance of `who`, burning the tokens.
	/// The actual amount burned is derived from the `amount`, `preservation`, `precision` and
	/// `force`, and might end up being more, less or equal to the `amount` specified.
	///
	/// If the burn isn't possible then an `Err` is returned and nothing is changed.
	/// If successful, the amount of tokens reduced is returned.
	fn burn_from(
		who: &AccountId,
		amount: Self::Balance,
		preservation: Preservation,
		precision: Precision,
		force: Fortitude,
	) -> Result<Self::Balance, DispatchError> {
		let actual = Self::reducible_balance(who, preservation, force).min(amount);
		ensure!(actual == amount || precision == BestEffort, TokenError::FundsUnavailable);
		Self::total_issuance().checked_sub(&actual).ok_or(ArithmeticError::Overflow)?;
		let actual = Self::decrease_balance(who, actual, BestEffort, preservation, force)?;
		Self::set_total_issuance(Self::total_issuance().saturating_sub(actual));
		Self::done_burn_from(who, actual);
		Ok(actual)
	}

	/// Attempt to decrease the `asset` balance of `who` by `amount`.
	///
	/// Equivalent to [`Mutate::burn_from`], except with an expectation that within the bounds of
	/// some universal issuance, the total assets `suspend`ed and `resume`d will be equivalent. The
	/// implementation may be configured such that the total assets suspended may never be less than
	/// the total assets resumed (which is the invariant for an issuing system), or the reverse
	/// (which the invariant in a non-issuing system).
	///
	/// Because of this expectation, any metadata associated with the asset is expected to survive
	/// the suspect-resume cycle.
	fn shelve(who: &AccountId, amount: Self::Balance) -> Result<Self::Balance, DispatchError> {
		let actual = Self::reducible_balance(who, Expendable, Polite).min(amount);
		ensure!(actual == amount, TokenError::FundsUnavailable);
		Self::total_issuance().checked_sub(&actual).ok_or(ArithmeticError::Overflow)?;
		let actual = Self::decrease_balance(who, actual, BestEffort, Expendable, Polite)?;
		Self::set_total_issuance(Self::total_issuance().saturating_sub(actual));
		Self::done_shelve(who, actual);
		Ok(actual)
	}

	/// Attempt to increase the `asset` balance of `who` by `amount`.
	///
	/// Equivalent to [`Mutate::mint_into`], except with an expectation that within the bounds of
	/// some universal issuance, the total assets `suspend`ed and `resume`d will be equivalent. The
	/// implementation may be configured such that the total assets suspended may never be less than
	/// the total assets resumed (which is the invariant for an issuing system), or the reverse
	/// (which the invariant in a non-issuing system).
	///
	/// Because of this expectation, any metadata associated with the asset is expected to survive
	/// the suspect-resume cycle.
	fn restore(who: &AccountId, amount: Self::Balance) -> Result<Self::Balance, DispatchError> {
		Self::total_issuance().checked_add(&amount).ok_or(ArithmeticError::Overflow)?;
		let actual = Self::increase_balance(who, amount, Exact)?;
		Self::set_total_issuance(Self::total_issuance().saturating_add(actual));
		Self::done_restore(who, amount);
		Ok(actual)
	}

	/// Transfer funds from one account into another.
	///
	/// Returns the amount credited to `dest`. With the default implementation this is `amount`
	/// unless [`Unbalanced::decrease_balance`] folded a sub-minimum remainder of `source` into
	/// its return, as `pallet-assets` does, in which case it exceeds `amount` by up to
	/// `minimum_balance() - 1` and that remainder is credited to `dest` as well. Adapters such as
	/// `ItemOf` and `UnionOf` forward that figure.
	///
	/// `source` may be debited by more than is returned, e.g. when a reaped remainder is passed to
	/// `handle_dust` as `pallet-balances` does.
	///
	/// A transfer where the source and destination account are identical, or where `amount` is
	/// zero, is treated as No-OP after checking the preconditions.
	fn transfer(
		source: &AccountId,
		dest: &AccountId,
		amount: Self::Balance,
		preservation: Preservation,
	) -> Result<Self::Balance, DispatchError> {
		let _extra = Self::can_withdraw(source, amount).into_result(preservation != Expendable)?;
		Self::can_deposit(dest, amount, Extant).into_result()?;
		if source == dest || amount.is_zero() {
			return Ok(amount);
		}

		let actual = Self::decrease_balance(source, amount, Exact, preservation, Polite)?;
		Self::increase_balance(dest, actual, Exact)?;
		Self::done_transfer(source, dest, actual);
		Ok(actual)
	}

	/// Simple infallible function to force an account to have a particular balance, good for use
	/// in tests and benchmarks but not recommended for production code owing to the lack of
	/// error reporting.
	///
	/// Returns the new balance.
	fn set_balance(who: &AccountId, amount: Self::Balance) -> Self::Balance {
		let b = Self::balance(who);
		if b > amount {
			Self::burn_from(who, b - amount, Expendable, BestEffort, Force)
				.map(|d| b.saturating_sub(d))
		} else {
			Self::mint_into(who, amount - b).map(|d| b.saturating_add(d))
		}
		.unwrap_or(b)
	}

	fn done_mint_into(_who: &AccountId, _amount: Self::Balance) {}
	fn done_burn_from(_who: &AccountId, _amount: Self::Balance) {}
	fn done_shelve(_who: &AccountId, _amount: Self::Balance) {}
	fn done_restore(_who: &AccountId, _amount: Self::Balance) {}
	fn done_transfer(_source: &AccountId, _dest: &AccountId, _amount: Self::Balance) {}
}

/// Simple handler for an imbalance drop which increases the total issuance of the system by the
/// imbalance amount. Used for leftover debt.
pub struct IncreaseIssuance<AccountId, U>(PhantomData<(AccountId, U)>);
impl<AccountId, U: Unbalanced<AccountId>> HandleImbalanceDrop<U::Balance>
	for IncreaseIssuance<AccountId, U>
{
	fn handle(amount: U::Balance) {
		U::set_total_issuance(U::total_issuance().saturating_add(amount))
	}
}

/// Simple handler for an imbalance drop which decreases the total issuance of the system by the
/// imbalance amount. Used for leftover credit.
pub struct DecreaseIssuance<AccountId, U>(PhantomData<(AccountId, U)>);
impl<AccountId, U: Unbalanced<AccountId>> HandleImbalanceDrop<U::Balance>
	for DecreaseIssuance<AccountId, U>
{
	fn handle(amount: U::Balance) {
		U::set_total_issuance(U::total_issuance().saturating_sub(amount))
	}
}

/// A fungible token class where any creation and deletion of tokens is semi-explicit and where the
/// total supply is maintained automatically.
///
/// This is auto-implemented when a token class has [`Unbalanced`] implemented.
pub trait Balanced<AccountId>: Inspect<AccountId> + Unbalanced<AccountId> {
	/// The type for managing what happens when an instance of `Debt` is dropped without being used.
	type OnDropDebt: HandleImbalanceDrop<Self::Balance>;
	/// The type for managing what happens when an instance of `Credit` is dropped without being
	/// used.
	type OnDropCredit: HandleImbalanceDrop<Self::Balance>;

	/// Reduce the total issuance by `amount` and return the according imbalance. The imbalance will
	/// typically be used to reduce an account by the same amount with e.g. [`Balanced::settle`].
	///
	/// This is infallible, but doesn't guarantee that the entire `amount` is burnt, for example
	/// in the case of underflow.
	fn rescind(amount: Self::Balance) -> Debt<AccountId, Self> {
		let old = Self::total_issuance();
		let new = old.saturating_sub(amount);
		Self::set_total_issuance(new);
		let delta = old - new;
		Self::done_rescind(delta);
		Imbalance::<Self::Balance, Self::OnDropDebt, Self::OnDropCredit>::new(delta)
	}

	/// Increase the total issuance by `amount` and return the according imbalance. The imbalance
	/// will typically be used to increase an account by the same amount with e.g.
	/// [`Balanced::resolve`].
	///
	/// This is infallible, but doesn't guarantee that the entire `amount` is issued, for example
	/// in the case of overflow.
	fn issue(amount: Self::Balance) -> Credit<AccountId, Self> {
		let old = Self::total_issuance();
		let new = old.saturating_add(amount);
		Self::set_total_issuance(new);
		let delta = new - old;
		Self::done_issue(delta);
		Imbalance::<Self::Balance, Self::OnDropCredit, Self::OnDropDebt>::new(delta)
	}

	/// Produce a pair of imbalances that cancel each other out exactly.
	///
	/// This is just the same as burning and issuing the same amount and has no effect on the
	/// total issuance.
	///
	/// This could fail when we cannot issue and redeem the entire `amount`, for example in the
	/// case where the amount would cause overflow or underflow in [`Balanced::issue`] or
	/// [`Balanced::rescind`].
	fn pair(
		amount: Self::Balance,
	) -> Result<(Debt<AccountId, Self>, Credit<AccountId, Self>), DispatchError> {
		let issued = Self::issue(amount);
		let rescinded = Self::rescind(amount);
		// Need to check amount in case by some edge case both issued and rescinded are below
		// `amount` by the exact same value
		if issued.peek() != rescinded.peek() || issued.peek() != amount {
			// Issued and rescinded will be dropped automatically
			Err("Failed to issue and rescind equal amounts".into())
		} else {
			Ok((rescinded, issued))
		}
	}

	/// Mints `value` into the account of `who`, creating it as needed.
	///
	/// If `precision` is `BestEffort` and `value` in full could not be minted (e.g. due to
	/// overflow), then the maximum is minted, up to `value`. If `precision` is [`Exact`], then
	/// exactly `value` must be minted into the account of `who` or the operation will fail with an
	/// `Err` and nothing will change.
	///
	/// If the operation is successful, this will return `Ok` with a [`Debt`] of the total value
	/// added to the account.
	fn deposit(
		who: &AccountId,
		value: Self::Balance,
		precision: Precision,
	) -> Result<Debt<AccountId, Self>, DispatchError> {
		let increase = Self::increase_balance(who, value, precision)?;
		Self::done_deposit(who, increase);
		Ok(Imbalance::<Self::Balance, Self::OnDropDebt, Self::OnDropCredit>::new(increase))
	}

	/// Removes `value` balance from `who` account if possible.
	///
	/// If `precision` is [`BestEffort`] and `value` in full could not be removed (e.g. due to
	/// underflow), then the maximum is removed, up to `value`. If `precision` is [`Exact`], then
	/// exactly `value` must be removed from the account of `who` or the operation will fail with an
	/// `Err` and nothing will change.
	///
	/// If the removal is needed but not possible, then it returns `Err` and nothing is changed.
	/// If the account needed to be deleted, then slightly more than `value` may be removed from the
	/// account owning since up to (but not including) minimum balance may also need to be removed.
	///
	/// If the operation is successful, this will return `Ok` with a [`Credit`] of the total value
	/// removed from the account.
	fn withdraw(
		who: &AccountId,
		value: Self::Balance,
		precision: Precision,
		preservation: Preservation,
		force: Fortitude,
	) -> Result<Credit<AccountId, Self>, DispatchError> {
		let decrease = Self::decrease_balance(who, value, precision, preservation, force)?;
		Self::done_withdraw(who, decrease);
		Ok(Imbalance::<Self::Balance, Self::OnDropCredit, Self::OnDropDebt>::new(decrease))
	}

	/// The balance of `who` is increased in order to counter `credit`. If the whole of `credit`
	/// cannot be countered, then nothing is changed and the original `credit` is returned in an
	/// `Err`.
	///
	/// Please note: If `credit.peek()` is less than [`Inspect::minimum_balance()`], then `who` must
	/// already exist for this to succeed.
	fn resolve(
		who: &AccountId,
		credit: Credit<AccountId, Self>,
	) -> Result<(), Credit<AccountId, Self>> {
		let v = credit.peek();
		let debt = match Self::deposit(who, v, Exact) {
			Err(_) => return Err(credit),
			Ok(d) => d,
		};
		let result = credit.offset(debt).try_drop();
		debug_assert!(result.is_ok(), "ok deposit return must be equal to credit value; qed");
		Ok(())
	}

	/// The balance of `who` is decreased in order to counter `debt`. If the whole of `debt`
	/// cannot be countered, then nothing is changed and the original `debt` is returned in an
	/// `Err`.
	fn settle(
		who: &AccountId,
		debt: Debt<AccountId, Self>,
		preservation: Preservation,
	) -> Result<Credit<AccountId, Self>, Debt<AccountId, Self>> {
		let amount = debt.peek();
		let credit = match Self::withdraw(who, amount, Exact, preservation, Polite) {
			Err(_) => return Err(debt),
			Ok(c) => c,
		};

		match credit.offset(debt) {
			SameOrOther::None => Ok(Credit::<AccountId, Self>::zero()),
			SameOrOther::Same(dust) => Ok(dust),
			SameOrOther::Other(rest) => {
				debug_assert!(false, "ok withdraw return must be at least debt value; qed");
				Err(rest)
			},
		}
	}

	fn done_rescind(_amount: Self::Balance) {}
	fn done_issue(_amount: Self::Balance) {}
	fn done_deposit(_who: &AccountId, _amount: Self::Balance) {}
	fn done_withdraw(_who: &AccountId, _amount: Self::Balance) {}
}

/// Dummy implementation of [`Inspect`]
#[cfg(feature = "std")]
impl<AccountId> Inspect<AccountId> for () {
	type Balance = u32;
	fn total_issuance() -> Self::Balance {
		0
	}
	fn minimum_balance() -> Self::Balance {
		0
	}
	fn total_balance(_: &AccountId) -> Self::Balance {
		0
	}
	fn balance(_: &AccountId) -> Self::Balance {
		0
	}
	fn reducible_balance(_: &AccountId, _: Preservation, _: Fortitude) -> Self::Balance {
		0
	}
	fn can_deposit(_: &AccountId, _: Self::Balance, _: Provenance) -> DepositConsequence {
		DepositConsequence::Success
	}
	fn can_withdraw(_: &AccountId, _: Self::Balance) -> WithdrawConsequence<Self::Balance> {
		WithdrawConsequence::Success
	}
}

/// Dummy implementation of [`Unbalanced`]
#[cfg(feature = "std")]
impl<AccountId> Unbalanced<AccountId> for () {
	fn handle_dust(_: Dust<AccountId, Self>) {}
	fn write_balance(
		_: &AccountId,
		_: Self::Balance,
	) -> Result<Option<Self::Balance>, DispatchError> {
		Ok(None)
	}
	fn set_total_issuance(_: Self::Balance) {}
}

/// Dummy implementation of [`Mutate`]
#[cfg(feature = "std")]
impl<AccountId: Eq> Mutate<AccountId> for () {}

#[cfg(test)]
mod tests {
	use super::*;
	use core::cell::RefCell;

	thread_local! {
		static BALANCES: RefCell<[u64; 2]> = const { RefCell::new([0, 0]) };
	}

	const MIN_BALANCE: u64 = 10;

	/// A fungible whose `decrease_balance` sweeps a sub-`minimum_balance` remainder into the
	/// figure it returns, as `Unbalanced::decrease_balance` permits and `pallet-assets` does.
	/// The excess stays in the system rather than going to `handle_dust`, so a caller that
	/// credits the return value moves it rather than issuing it afresh.
	struct SweepingFungible;

	impl Inspect<usize> for SweepingFungible {
		type Balance = u64;
		fn total_issuance() -> u64 {
			BALANCES.with(|b| b.borrow().iter().sum())
		}
		fn minimum_balance() -> u64 {
			MIN_BALANCE
		}
		fn total_balance(who: &usize) -> u64 {
			Self::balance(who)
		}
		fn balance(who: &usize) -> u64 {
			BALANCES.with(|b| b.borrow()[*who])
		}
		fn reducible_balance(who: &usize, _: Preservation, _: Fortitude) -> u64 {
			Self::balance(who)
		}
		fn can_deposit(_: &usize, _: u64, _: Provenance) -> DepositConsequence {
			DepositConsequence::Success
		}
		fn can_withdraw(_: &usize, _: u64) -> WithdrawConsequence<u64> {
			WithdrawConsequence::Success
		}
	}

	impl Unbalanced<usize> for SweepingFungible {
		fn handle_dust(_: Dust<usize, Self>) {
			unreachable!("the sweep is reported through `decrease_balance`, not trapped");
		}
		fn write_balance(_: &usize, _: u64) -> Result<Option<u64>, DispatchError> {
			unimplemented!("`decrease_balance` and `increase_balance` are provided");
		}
		fn set_total_issuance(_: u64) {}
		fn decrease_balance(
			who: &usize,
			amount: u64,
			_: Precision,
			_: Preservation,
			_: Fortitude,
		) -> Result<u64, DispatchError> {
			BALANCES.with(|b| {
				let mut b = b.borrow_mut();
				let remainder = b[*who].checked_sub(amount).ok_or(TokenError::FundsUnavailable)?;
				let actual =
					if !remainder.is_zero() && remainder < MIN_BALANCE { b[*who] } else { amount };
				b[*who] -= actual;
				Ok(actual)
			})
		}
		fn increase_balance(who: &usize, amount: u64, _: Precision) -> Result<u64, DispatchError> {
			BALANCES.with(|b| b.borrow_mut()[*who] += amount);
			Ok(amount)
		}
	}

	impl Mutate<usize> for SweepingFungible {}

	/// `transfer` must credit the destination with what `decrease_balance` actually took, not
	/// with what it was asked for. Crediting `amount` would debit the source 100 while
	/// crediting 95, destroying the difference.
	#[test]
	fn transfer_credits_the_amount_actually_debited() {
		BALANCES.with(|b| *b.borrow_mut() = [100, 0]);

		assert_eq!(
			<SweepingFungible as Mutate<usize>>::transfer(&0, &1, 95, Preservation::Expendable),
			Ok(100),
		);

		assert_eq!(<SweepingFungible as Inspect<usize>>::balance(&0), 0);
		assert_eq!(<SweepingFungible as Inspect<usize>>::balance(&1), 100);
	}

	/// A transfer that leaves a legal remainder is untouched by the above.
	#[test]
	fn transfer_without_a_sweep_moves_exactly_the_amount() {
		BALANCES.with(|b| *b.borrow_mut() = [100, 0]);

		assert_eq!(
			<SweepingFungible as Mutate<usize>>::transfer(&0, &1, 90, Preservation::Expendable),
			Ok(90),
		);

		assert_eq!(<SweepingFungible as Inspect<usize>>::balance(&0), 10);
		assert_eq!(<SweepingFungible as Inspect<usize>>::balance(&1), 90);
	}
}