:source-highlighter: highlight.js
:highlightjs-languages: rust
:github-icon: pass:[<svg class="icon"><use href="#github-icon"/></svg>]

= pallet_balances

Branch/Release: `release-polkadot-v1.10.0`

== Source Code link:https://github.com/paritytech/polkadot-sdk/blob/release-polkadot-v1.10.0/substrate/frame/balances/src/lib.rs[{github-icon},role=heading-link]

== 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 xref:glossary.adoc#lock[locks].

== Config

* Pallet-specific configs
** `RuntimeHoldReason` -- The overarching xref:glossary.adoc#hold[hold] reason.
** `RuntimeFreezeReason` -- The overarching xref:glossary.adoc#freeze[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 xref:glossary.adoc#reserve[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` -- xref:glossary.adoc#weight[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

[.contract-item]
[[transfer_allow_death]]
==== `[.contract-item-name]#++transfer_allow_death++#`
[source,rust]
----
pub fn transfer_allow_death(
    origin: OriginFor<T>,
    dest: AccountIdLookupOf<T>,
    #[pallet::compact] value: T::Balance,
) -> DispatchResult
----
Transfers the `value` from `origin` to `dest`.

NOTE: `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.

[.contract-item]
[[transfer_keep_alive]]
==== `[.contract-item-name]#++transfer_keep_alive++#`
[source,rust]
----
pub fn transfer_keep_alive(
    origin: OriginFor<T>,
    dest: AccountIdLookupOf<T>,
    #[pallet::compact] value: T::Balance,
) -> DispatchResult
----
Transfers the `value` from `origin` to `dest`.

NOTE: `keep_alive` means, with a check that the transfer will not kill the origin account.

TIP: 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.

[.contract-item]
[[force_transfer]]
==== `[.contract-item-name]#++force_transfer++#`
[source,rust]
----
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.

[.contract-item]
[[transfer_all]]
==== `[.contract-item-name]#++transfer_all++#`
[source,rust]
----
pub fn transfer_all(
    origin: OriginFor<T>,
    dest: AccountIdLookupOf<T>,
    keep_alive: bool,
) -> DispatchResult
----
Transfer the entire transferable balance from the caller account.

NOTE: 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).

[.contract-item]
[[force_unreserve]]
==== `[.contract-item-name]#++force_unreserve++#`
[source,rust]
----
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.

[.contract-item]
[[upgrade_accounts]]
==== `[.contract-item-name]#++upgrade_accounts++#`
[source,rust]
----
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.

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

[.contract-item]
[[force_set_balance]]
==== `[.contract-item-name]#++force_set_balance++#`
[source,rust]
----
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.

[.contract-item]
[[force_adjust_total_issuance]]
==== `[.contract-item-name]#++force_adjust_total_issuance++#`
[source,rust]
----
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.
