Crate pallet_balances

source ·
Expand description

§Balances Pallet

The Balances pallet provides functionality for handling accounts and balances for a single token.

It makes heavy use of concepts such as Holds and Freezes from the [frame_support::traits::fungible] traits, therefore you should read and understand those docs as a prerequisite to understanding this pallet.

Also see the frame_tokens reference docs for higher level information regarding the place of this palet in FRAME.

§Overview

The Balances pallet provides functions for:

  • Getting and setting free balances.
  • Retrieving total, reserved and unreserved balances.
  • Repatriating a reserved balance to a beneficiary account that exists.
  • Transferring a balance between accounts (when not reserved).
  • Slashing an account balance.
  • Account creation and removal.
  • Managing total issuance.
  • Setting and managing locks.

§Terminology

  • Reaping an account: The act of removing an account by resetting its nonce. Happens after its total balance has become less than the Existential Deposit.

§Implementations

The Balances pallet provides implementations for the following [fungible] traits. If these traits provide the functionality that you need, then you should avoid tight coupling with the Balances pallet.

  • [fungible::Inspect]
  • [fungible::Mutate]
  • [fungible::Unbalanced]
  • [fungible::Balanced]
  • [fungible::BalancedHold]
  • [fungible::InspectHold]
  • [fungible::MutateHold]
  • [fungible::InspectFreeze]
  • [fungible::MutateFreeze]
  • [fungible::Imbalance]

It also implements the following [Currency] related traits, however they are deprecated and will eventually be removed.

  • [Currency]: Functions for dealing with a fungible assets system.
  • [ReservableCurrency]
  • NamedReservableCurrency: Functions for dealing with assets that can be reserved from an account.
  • LockableCurrency: Functions for dealing with accounts that allow liquidity restrictions.
  • Imbalance: Functions for handling imbalances between total issuance in the system and account balances. Must be used when a function creates new funds (e.g. a reward) or destroys some funds (e.g. a system fee).

§Usage

The following examples show how to use the Balances pallet in your custom pallet.

§Examples from the FRAME

The Contract pallet uses the Currency trait to handle gas payment, and its types inherit from Currency:

use frame_support::traits::Currency;

pub type BalanceOf<T> = <<T as Config>::Currency as Currency<<T as frame_system::Config>::AccountId>>::Balance;
pub type NegativeImbalanceOf<T> = <<T as Config>::Currency as Currency<<T as frame_system::Config>::AccountId>>::NegativeImbalance;

The Staking pallet uses the LockableCurrency trait to lock a stash account’s funds:

use frame_support::traits::{WithdrawReasons, LockableCurrency};
use sp_runtime::traits::Bounded;
pub trait Config: frame_system::Config {
    type Currency: LockableCurrency<Self::AccountId, Moment=frame_system::pallet_prelude::BlockNumberFor<Self>>;
}

fn update_ledger<T: Config>(
    controller: &T::AccountId,
    ledger: &StakingLedger<T>
) {
    T::Currency::set_lock(
        STAKING_ID,
        &ledger.stash,
        ledger.total,
        WithdrawReasons::all()
    );
    // <Ledger<T>>::insert(controller, ledger); // Commented out as we don't have access to Staking's storage here.
}

§Genesis config

The Balances pallet depends on the GenesisConfig.

§Assumptions

  • Total issued balanced of all accounts should be less than Config::Balance::max_value().
  • Existential Deposit is set to a value greater than zero.

Note, you may find the Balances pallet still functions with an ED of zero when the insecure_zero_ed cargo feature is enabled. However this is not a configuration which is generally supported, nor will it be.

Re-exports§

Modules§

  • benchmarking 🔒
    Balances pallet benchmarking.
  • impl_currency 🔒
    Implementations for the Currency family of traits.
  • impl_fungible 🔒
    Implementation of fungible traits for Balances pallet.
  • migration
  • pallet
    The pallet module in each FRAME pallet hosts the most important items needed to construct this pallet.
  • types 🔒
    Types used in the pallet.
  • weights
    Autogenerated weights for pallet_balances

Structs§

  • AccountData
    All balance information for an account.
  • BalanceLock
    A single lock on a balance. There can be many of these on an account and they “overlap”, so the same balance is frozen by multiple locks.
  • DustCleaner
  • ExtraFlags
  • IdAmount
    An identifier and balance.
  • NegativeImbalance
    Opaque, move-only struct with private fields that serves as a token denoting that funds have been destroyed without any equal and opposite accounting.
  • PositiveImbalance
    Opaque, move-only struct with private fields that serves as a token denoting that funds have been created without any equal and opposite accounting.
  • ReserveData
    Store named reserved balance.

Enums§

  • AdjustmentDirection
    Whether something should be interpreted as an increase or a decrease.
  • Reasons
    Simplified reasons for withdrawing balance.

Constants§

Type Aliases§