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§
pub use weights::WeightInfo;
pub use pallet::*;
Modules§
- The
pallet
module in each FRAME pallet hosts the most important items needed to construct this pallet. - Autogenerated weights for
pallet_balances
Structs§
- All balance information for an account.
- 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.
- Opaque, move-only struct with private fields that serves as a token denoting that funds have been destroyed without any equal and opposite accounting.
- Opaque, move-only struct with private fields that serves as a token denoting that funds have been created without any equal and opposite accounting.
- Store named reserved balance.
Enums§
- Whether something should be interpreted as an increase or a decrease.
- Simplified reasons for withdrawing balance.