Skip to main content

Balances

Calls​

forceTransfer​

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

Namespace​

api.tx.balances.forceTransfer

Type​

function forceTransfer(
  source: SeedPrimitivesSignatureAccountId20,
  dest: SeedPrimitivesSignatureAccountId20,
  value: Compact<u128>
)

forceUnreserve​

Unreserve some balance from a user by force.

Can only be called by ROOT.

Namespace​

api.tx.balances.forceUnreserve

Type​

function forceUnreserve(
  who: SeedPrimitivesSignatureAccountId20,
  amount: u128
)

setBalance​

Set the balances of a given account.

This will alter FreeBalance and ReservedBalance in storage. it will also alter the total issuance of the system (TotalIssuance) appropriately. If the new free or reserved balance is below the existential deposit, it will reset the account nonce (frame_system::AccountNonce).

The dispatch origin for this call is root.

Namespace​

api.tx.balances.setBalance

Type​

function setBalance(
  who: SeedPrimitivesSignatureAccountId20,
  new_free: Compact<u128>,
  new_reserved: Compact<u128>
)

transfer​

Transfer some liquid free balance to another account.

transfer will set the FreeBalance of the sender and receiver. If the sender's account is below the existential deposit as a result of the transfer, the account will be reaped.

The dispatch origin for this call must be Signed by the transactor.

Namespace​

api.tx.balances.transfer

Type​

function transfer(
  dest: SeedPrimitivesSignatureAccountId20,
  value: Compact<u128>
)

transferAll​

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. To ensure that this function results in a killed account, you might need to prepare the account by removing any reference counters, storage deposits, etc...

The dispatch origin of this call must be Signed.

  • dest: The recipient of the transfer.

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

Namespace​

api.tx.balances.transferAll

Type​

function transferAll(
  dest: SeedPrimitivesSignatureAccountId20,
  keep_alive: bool
)

transferKeepAlive​

Same as the transfer call, but with a check that the transfer will not kill the origin account.

99% of the time you want transfer instead.

Namespace​

api.tx.balances.transferKeepAlive

Type​

function transferKeepAlive(
  dest: SeedPrimitivesSignatureAccountId20,
  value: Compact<u128>
)

Storage​

account​

The Balances pallet example of storing the balance of an account.

Example​

nocompile impl pallet_balances::Config for Runtime { type AccountStore = StorageMapShim<Self::Account<Runtime>, frame_system::Provider<Runtime>, AccountId, Self::AccountData<Balance>> }

You can also store the balance of an account in the System pallet.

Example​

nocompile impl pallet_balances::Config for Runtime { type AccountStore = System }

But this comes with tradeoffs, storing account balances in the system pallet stores frame_system data alongside the account data contrary to storing account balances in the Balances pallet, which uses a StorageMap to store balances data only. NOTE: This is only used in the case that this pallet is used to store balances.

Namespace​

api.query.balances.account

Type​

function account(
  SeedPrimitivesSignatureAccountId20
): PalletBalancesAccountData

locks​

Any liquidity locks on some account balances. NOTE: Should only be accessed when setting, changing and freeing a lock.

Namespace​

api.query.balances.locks

Type​

function locks(
  SeedPrimitivesSignatureAccountId20
): Vec<PalletBalancesBalanceLock>

reserves​

Named reserves on some account balances.

Namespace​

api.query.balances.reserves

Type​

function reserves(
  SeedPrimitivesSignatureAccountId20
): Vec<PalletBalancesReserveData>

storageVersion​

Storage version of the pallet.

This is set to v2.0.0 for new networks.

Namespace​

api.query.balances.storageVersion

Type​

function storageVersion(

): PalletBalancesReleases

totalIssuance​

The total units issued in the system.

Namespace​

api.query.balances.totalIssuance

Type​

function totalIssuance(

): u128

Events​

BalanceSet​

A balance was set by root.

Namespace​

api.events.balances.BalanceSet

Type​

type BalanceSet = {
  who: SeedPrimitivesSignatureAccountId20,
  free: u128,
  reserved: u128
}

Deposit​

Some amount was deposited (e.g. for transaction fees).

Namespace​

api.events.balances.Deposit

Type​

type Deposit = {
  who: SeedPrimitivesSignatureAccountId20,
  amount: u128
}

DustLost​

An account was removed whose balance was non-zero but below ExistentialDeposit, resulting in an outright loss.

Namespace​

api.events.balances.DustLost

Type​

type DustLost = {
  account: SeedPrimitivesSignatureAccountId20,
  amount: u128
}

Endowed​

An account was created with some free balance.

Namespace​

api.events.balances.Endowed

Type​

type Endowed = {
  account: SeedPrimitivesSignatureAccountId20,
  free_balance: u128
}

Reserved​

Some balance was reserved (moved from free to reserved).

Namespace​

api.events.balances.Reserved

Type​

type Reserved = {
  who: SeedPrimitivesSignatureAccountId20,
  amount: u128
}

ReserveRepatriated​

Some balance was moved from the reserve of the first account to the second account. Final argument indicates the destination balance type.

Namespace​

api.events.balances.ReserveRepatriated

Type​

type ReserveRepatriated = {
  from: SeedPrimitivesSignatureAccountId20,
  to: SeedPrimitivesSignatureAccountId20,
  amount: u128,
  destination_status: FrameSupportTokensMiscBalanceStatus
}

Slashed​

Some amount was removed from the account (e.g. for misbehavior).

Namespace​

api.events.balances.Slashed

Type​

type Slashed = {
  who: SeedPrimitivesSignatureAccountId20,
  amount: u128
}

Transfer​

Transfer succeeded.

Namespace​

api.events.balances.Transfer

Type​

type Transfer = {
  from: SeedPrimitivesSignatureAccountId20,
  to: SeedPrimitivesSignatureAccountId20,
  amount: u128
}

Unreserved​

Some balance was unreserved (moved from reserved to free).

Namespace​

api.events.balances.Unreserved

Type​

type Unreserved = {
  who: SeedPrimitivesSignatureAccountId20,
  amount: u128
}

Withdraw​

Some amount was withdrawn from the account (e.g. for transaction fees).

Namespace​

api.events.balances.Withdraw

Type​

type Withdraw = {
  who: SeedPrimitivesSignatureAccountId20,
  amount: u128
}

Errors​

DeadAccount​

Beneficiary account must pre-exist

Namespace​

api.errors.balances.DeadAccount

ExistentialDeposit​

Value too low to create account due to existential deposit

Namespace​

api.errors.balances.ExistentialDeposit

ExistingVestingSchedule​

A vesting schedule already exists for this account

Namespace​

api.errors.balances.ExistingVestingSchedule

InsufficientBalance​

Balance too low to send value

Namespace​

api.errors.balances.InsufficientBalance

KeepAlive​

Transfer/payment would kill account

Namespace​

api.errors.balances.KeepAlive

LiquidityRestrictions​

Account liquidity restrictions prevent withdrawal

Namespace​

api.errors.balances.LiquidityRestrictions

TooManyReserves​

Number of named reserves exceed MaxReserves

Namespace​

api.errors.balances.TooManyReserves

VestingBalance​

Vesting balance too high to send value

Namespace​

api.errors.balances.VestingBalance

Constants​

existentialDeposit​

The minimum amount required to keep an account open.

Namespace​

api.consts.balances.existentialDeposit

Type​

type existentialDeposit = u128

maxLocks​

The maximum number of locks that should exist on an account. Not strictly enforced, but used for weight estimation.

Namespace​

api.consts.balances.maxLocks

Type​

type maxLocks = u32

maxReserves​

The maximum number of named reserves that can exist on an account.

Namespace​

api.consts.balances.maxReserves

Type​

type maxReserves = u32