Crate pezpallet_balances 

Balances Pezpallet

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

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

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

Overview

The Balances pezpallet 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 pezpallet 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 pezpallet.

• 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 pezpallet in your custom pezpallet.

Examples from the FRAME

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

use pezframe_support::traits::Currency;

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

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

use pezframe_support::traits::{WithdrawReasons, LockableCurrency};
use pezsp_runtime::traits::Bounded;
pub trait Config: pezframe_system::Config {
    type Currency: LockableCurrency<Self::AccountId, Moment=pezframe_system::pezpallet_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 pezpallet 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 pezpallet 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 pezpallet::*;

Modules

migration

pezpallet

The pezpallet module in each FRAME pezpallet hosts the most important items needed to construct this pezpallet.

weights

Autogenerated weights for pezpallet_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.