Crate pallet_balances

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

• pub use weights::WeightInfo;
• pub use pallet::*;

Modules

• migration
• pallet
  The pallet module in each FRAME pallet hosts the most important items needed to construct this 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
• 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.