pallet_balances

Branch/Release: release-polkadot-v1.10.0

Source Code

Purpose

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.

Config

  • Pallet-specific configs

    • RuntimeHoldReason — The overarching hold reason.

    • RuntimeFreezeReason — The overarching freeze reason.

    • Balance — The balance of an account

    • DustRemoval — Handler for the unbalanced reduction when removing a dust account.

    • ExistentialDeposit — The minimum amount required to keep an account open. MUST BE GREATER THAN ZERO!

    • AccountStore — The means of storing the balances of an account.

    • ReserveIdentifier —  The ID type for reserves. The use of reserves is deprecated in favor of holds. See https://github.com/paritytech/substrate/pull/12951/

    • FreezeIdentifier — The ID type for freezes.

    • MaxLocks — The maximum number of locks that should exist on an account.

    • MaxReserves — The maximum number of named reserves that can exist on an account. The use of reserves is deprecated in favor of holds. See https://github.com/paritytech/substrate/pull/12951/

    • MaxFreezes — The maximum number of individual freeze locks that can exist on an account at any time.

  • Common configs

    • RuntimeEvent — The overarching event type.

    • WeightInfo — Weight information for extrinsics in this pallet.

Events

  • Endowed(account, free_balance) — An account was created with some free balance.

  • DustLost(account, amount) — An account was removed whose balance was non-zero but below ExistentialDeposit, resulting in an outright loss.

  • Transfer(from, to, amount) — Transfer succeeded.

  • BalanceSet(who, free) — A balance was set by root.

  • Reserved(who, amount) — Some balance was reserved (moved from free to reserved).

  • Unreserved(who, amount) — Some balance was unreserved (moved from reserved to free).

  • ReserveRepatriated(from, to, amount, destination_status) — Some balance was moved from the reserve of the first account to the second account. The final argument indicates the destination balance type.

  • Deposit(who, amount) — Some amount was deposited (e.g. for transaction fees).

  • Withdraw(who, amount) — Some amount was withdrawn from the account (e.g. for transaction fees).

  • Slashed(who, amount) — Some amount was removed from the account (e.g. for misbehavior).

  • Minted(who, amount) — Some amount was minted into an account.

  • Burned(who, amount) — Some amount was burned from an account.

  • Suspended(who, amount) — Some amount was suspended from an account (it can be restored later).

  • Restored(who, amount) — Some amount was restored into an account.

  • Upgraded(who) — An account was upgraded.

  • Issued(amount) — Total issuance was increased by amount, creating a credit to be balanced.

  • Rescinded(amount) — Total issuance was decreased by amount, creating a debt to be balanced.

  • Locked(who, amount) — Some balance was locked.

  • Unlocked(who, amount) — Some balance was unlocked.

  • Frozen(who, amount) — Some balance was frozen.

  • Thawed(who, amount) — Some balance was thawed.

  • TotalIssuanceForced(old, new) — Total issuance was forcefully changed.

Errors

  • VestingBalance — Vesting balance too high to send value.

  • LiquidityRestrictions — Account liquidity restrictions prevent withdrawal.

  • InsufficientBalance — Balance too low to send value.

  • ExistentialDeposit — Value too low to create an account due to existential deposit.

  • Expendability — Transfer/payment would kill the account.

  • ExistingVestingSchedule — A vesting schedule already exists for this account.

  • DeadAccount — Beneficiary account must pre-exist.

  • TooManyReserves — Number of named reserves exceed MaxReserves.

  • TooManyHolds — Number of holds exceeds MaxHolds.

  • TooManyFreezes — Number of freezes exceeds MaxFreezes.

  • IssuanceDeactivated — The issuance cannot be modified since it is already deactivated.

  • DeltaZero — The delta cannot be zero.

Dispatchables

transfer_allow_death

pub fn transfer_allow_death(
    origin: OriginFor<T>,
    dest: AccountIdLookupOf<T>,
    #[pallet::compact] value: T::Balance,
) -> DispatchResult

Transfers the value from origin to dest.

allow_death means, that if the account balance drops below the ExistentialDeposit limit, it might be reaped/deleted.

Params:

  • origin: OriginFor<T> — caller (and in this case, sender) account.

  • dest: AccountIdLookupOf<T> — recipient.

  • value: T::Balance — amount to transfer.

transfer_keep_alive

pub fn transfer_keep_alive(
    origin: OriginFor<T>,
    dest: AccountIdLookupOf<T>,
    #[pallet::compact] value: T::Balance,
) -> DispatchResult

Transfers the value from origin to dest.

keep_alive means, with a check that the transfer will not kill the origin account.
99% of the time you want transfer_allow_death instead.

Params:

  • origin: OriginFor<T> — caller (and in this case, sender) account.

  • dest: AccountIdLookupOf<T> — recipient.

  • value: T::Balance — amount to transfer.

force_transfer

pub fn force_transfer(
    origin: OriginFor<T>,
    source: AccountIdLookupOf<T>,
    dest: AccountIdLookupOf<T>,
    #[pallet::compact] value: T::Balance,
) -> DispatchResult

Exactly as transfer_allow_death, except the origin must be root and the source account may be specified.

Params:

  • origin: OriginFor<T> — caller (and in this case, root) account.

  • source: AccountIdLookupOf<T> — sender (forced by root).

  • dest: AccountIdLookupOf<T> — recipient.

  • value: T::Balance — amount to transfer.

transfer_all

pub fn transfer_all(
    origin: OriginFor<T>,
    dest: AccountIdLookupOf<T>,
    keep_alive: bool,
) -> DispatchResult

Transfer the entire transferable balance from the caller account.

This function only attempts to transfer transferable balances. This means that any locked, reserved, or existential deposits (when keep_alive is true), will not be transferred by this function.

Params:

  • origin: OriginFor<T> — caller (and in this case, sender) account.

  • dest: AccountIdLookupOf<T> — recipient.

  • keep_alive: bool — A boolean to determine if the transfer_all operation should send all of the transferable funds (including existential deposits) the account has, causing the sender account to be killed (false), or transfer everything transferable, except at least the existential deposit, which will guarantee to keep the sender account alive (true).

force_unreserve

pub fn force_unreserve(
    origin: OriginFor<T>,
    who: AccountIdLookupOf<T>,
    amount: T::Balance,
) -> DispatchResult

Unreserve some balance from a user by force. The caller (origin) must be root.

Params:

  • origin: OriginFor<T> — caller (and in this case, sender) account.

  • who: AccountIdLookupOf<T> — the account for which the balance is to be unreserved.

  • amount: T::Balance — the amount of balance to be unreserved.

upgrade_accounts

pub fn upgrade_accounts(
    origin: OriginFor<T>,
    who: Vec<T::AccountId>,
) -> DispatchResultWithPostInfo

Upgrade the specified account(s).

Params:

  • origin: OriginFor<T> — caller, must be Signed.

  • who: Vec<T::AccountId> — the account(s) to be upgraded.

This will waive the transaction fee if at least all but 10% of the accounts need to be upgraded.

force_set_balance

pub fn force_set_balance(
    origin: OriginFor<T>,
    who: AccountIdLookupOf<T>,
    #[pallet::compact] new_free: T::Balance,
) -> DispatchResult

Set the regular balance of a given account. The caller (origin) must be root.

Params:

  • origin: OriginFor<T> — caller, must be root.

  • who: AccountIdLookupOf<T> — the account for which the balance will be set.

  • new_free: T::Balance — the amount of free balance that will be set to the given account.

force_adjust_total_issuance

pub fn force_adjust_total_issuance(
    origin: OriginFor<T>,
	direction: AdjustmentDirection,
	#[pallet::compact] delta: T::Balance,
) -> DispatchResult

Adjust the total issuance in a saturating way.

Can only be called by root and always needs a positive delta.

Params:

  • origin: OriginFor<T> — caller, must be root.

  • direction: AdjustmentDirection — the direction of issuance change (increase or decrease).

  • delta: T::Balance — the amount of free balance that will be set to the given account.

← pallet_assets
pallet_message_queue →