Module polkadot_sdk_frame::traits::tokens::fungible

The traits for dealing with a single fungible token class and any associated types.

Also see the frame_tokens reference docs for more information about the place of fungible traits in Substrate.

Available Traits

• Inspect: Regular balance inspector functions.
• Unbalanced: Low-level balance mutating functions. Does not guarantee proper book-keeping and so should not be called into directly from application code. Other traits depend on this and provide default implementations based on it.
• UnbalancedHold: Low-level balance mutating functions for balances placed on hold. Does not guarantee proper book-keeping and so should not be called into directly from application code. Other traits depend on this and provide default implementations based on it.
• Mutate: Regular balance mutator functions. Pre-implemented using Unbalanced, though the done_* functions should likely be reimplemented in case you want to do something following the operation such as emit events.
• InspectHold: Inspector functions for balances on hold.
• MutateHold: Mutator functions for balances on hold. Mostly pre-implemented using UnbalancedHold.
• InspectFreeze: Inspector functions for frozen balance.
• MutateFreeze: Mutator functions for frozen balance.
• Balanced: One-sided mutator functions for regular balances, which return imbalance objects which guarantee eventual book-keeping. May be useful for some sophisticated operations where funds must be removed from an account before it is known precisely what should be done with them.

Terminology

• Total Issuance: The total number of units in existence in a system.

• Total Balance: The sum of an account’s free and held balances.

• Free Balance: A portion of an account’s total balance that is not held. Note this is distinct from the Spendable Balance, which represents how much Balance the user can actually transfer.

• Held Balance: Held balance still belongs to the account holder, but is suspended. It can be slashed, but only after all the free balance has been slashed.

  Multiple holds stack rather than overlay. This means that if an account has 3 holds for 100 units, the account can spend its funds for any reason down to 300 units, at which point the holds will start to come into play.

• Frozen Balance: A freeze on a specified amount of an account’s balance. Tokens that are frozen cannot be transferred.

  Multiple freezes always operate over the same funds, so they “overlay” rather than “stack”. This means that if an account has 3 freezes for 100 units, the account can spend its funds for any reason down to 100 units, at which point the freezes will start to come into play.

  It’s important to note that the frozen balance can exceed the total balance of the account. This is useful, eg, in cases where you want to prevent a user from transferring any fund. In such a case, setting the frozen balance to Balance::MAX would serve that purpose effectively.

• Minimum Balance (a.k.a. Existential Deposit, a.k.a. ED): The minimum balance required to create or keep an account open. This is to prevent “dust accounts” from filling storage. When the free plus the held balance (i.e. the total balance) falls below this, then the account is said to be dead. It loses its functionality as well as any prior history and all information on it is removed from the chain’s state. No account should ever have a total balance that is strictly between 0 and the existential deposit (exclusive). If this ever happens, it indicates either a bug in the implementation of this trait or an erroneous raw mutation of storage.

• Untouchable Balance: The part of a user’s free balance they cannot spend, due to ED or Freeze(s).

• Spendable Balance: The part of a user’s free balance they can actually transfer, after accounting for Holds and Freezes.

• Imbalance: A condition when some funds were credited or debited without equal and opposite accounting (i.e. a difference between total issuance and account balances). Functions that result in an imbalance will return an object of the imbalance::Credit or imbalance::Debt traits that can be managed within your runtime logic.

  If an imbalance is simply dropped, it should automatically maintain any book-keeping such as total issuance.

Visualising Balance Components Together 💫

|__total__________________________________|
|__on_hold__|_____________free____________|
|__________frozen___________|
|__on_hold__|__ed__|
            |__untouchable__|__spendable__|

Holds and Freezes

Both holds and freezes are used to prevent an account from using some of its balance.

The primary distinction between the two are that:

• Holds are cumulative (do not overlap) and are distinct from the free balance
• Freezes are not cumulative, and can overlap with each other or with holds

|__total_____________________________|
|__hold_a__|__hold_b__|_____free_____|
|__on_hold____________|     // <- the sum of all holds
|__freeze_a_______________|
|__freeze_b____|
|__freeze_c________|
|__frozen_________________| // <- the max of all freezes

Holds are designed to be infallibly slashed, meaning that any logic using a Freeze must handle the possibility of the frozen amount being reduced, potentially to zero. A permissionless function should be provided in order to allow bookkeeping to be updated in this instance. E.g. some balance is frozen when it is used for voting, one could use held balance for voting, but nothing prevents this frozen balance from being reduced if the overlapping hold is slashed.

Every Hold and Freeze is accompanied by a unique Reason, making it clear for each instance what the originating pallet and purpose is. These reasons are amalgomated into a single enum RuntimeHoldReason and RuntimeFreezeReason respectively, when the runtime is compiled.

Note that Hold and Freeze reasons should remain in your runtime for as long as storage could exist in your runtime with those reasons, otherwise your runtime state could become undecodable.

Should I use a Hold or Freeze?

If you require a balance to be infaillibly slashed, then you should use Holds.

If you require setting a minimum account balance amount, then you should use a Freezes. Note Freezes do not carry the same guarantees as Holds. Although the account cannot voluntarily reduce their balance below the largest freeze, if Holds on the account are slashed then the balance could drop below the freeze amount.

Sets of Tokens

For managing sets of tokens, see the fungibles trait which is a wrapper around this trait but supporting multiple asset instances.

Modules

• conformance_tests
• freeze
  The traits for putting freezes within a single fungible token class.
• hold
  The traits for putting holds within a single fungible token class.

Structs

• DecreaseIssuance
  Simple handler for an imbalance drop which decreases the total issuance of the system by the imbalance amount. Used for leftover credit.
• Dust
  Special dust type which can be type-safely converted into a Credit.
• FreezeConsideration
  Consideration method using a fungible balance frozen as the cost exacted for the footprint.
• HoldConsideration
  Consideration method using a fungible balance frozen as the cost exacted for the footprint.
• Imbalance
  An imbalance in the system, representing a divergence of recorded token supply from the sum of the balances of all accounts. This is must_use in order to ensure it gets handled (placing into an account, settling from an account or altering the supply).
• IncreaseIssuance
  Simple handler for an imbalance drop which increases the total issuance of the system by the imbalance amount. Used for leftover debt.
• ItemOf
  Convert a fungibles trait implementation into a fungible trait implementation by identifying a single item.
• LoneFreezeConsideration
  Basic consideration method using a fungible balance frozen as the cost exacted for the footprint.
• LoneHoldConsideration
  Basic consideration method using a fungible balance placed on hold as the cost exacted for the footprint.
• NativeFromLeft
  Criterion for UnionOf where a set for NativeOrWithId::Native asset located from the left and for NativeOrWithId::WithId from the right.
• UnionOf
  Type to combine some fungible::* and fungibles::* implementations into one union fungibles::* implementation.

Enums

• NativeOrWithId
  The NativeOrWithId enum classifies an asset as either Native to the current chain or as an asset with a specific ID.

Traits

• Balanced
  A fungible token class where any creation and deletion of tokens is semi-explicit and where the total supply is maintained automatically.
• BalancedHold
  Trait for slashing a fungible asset which can be place on hold.
• HandleImbalanceDrop
  Handler for when an imbalance gets dropped. This could handle either a credit (negative) or debt (positive) imbalance.
• Inspect
  Trait for providing balance-inspection access to a fungible asset.
• InspectFreeze
  Trait for inspecting a fungible asset which can be frozen. Freezing is essentially setting a minimum balance bellow which the total balance (inclusive of any funds placed on hold) may not be normally allowed to drop. Generally, freezers will provide an “update” function such that if the total balance does drop below the limit, then the freezer can update their housekeeping accordingly.
• InspectHold
  Trait for inspecting a fungible asset whose accounts support partitioning and slashing.
• Mutate
  Trait for providing a basic fungible asset.
• MutateFreeze
  Trait for introducing, altering and removing freezes for an account for its funds never go below a set minimum.
• MutateHold
  Trait for mutating a fungible asset which can be placed on hold.
• Unbalanced
  A fungible token class where the balance can be set arbitrarily.
• UnbalancedHold
  A fungible, holdable token class where the balance on hold can be set arbitrarily.

Type Aliases

• Credit
  Imbalance implying that the total_issuance value is greater than the sum of all account balances.
• Debt
  Imbalance implying that the total_issuance value is less than the sum of all account balances.