Account Balance

Overview

Account balance indicates whether it can be used to transfer, to pay fees, or remain frozen and not used due to an on-chain requirement.

Description

4 types of account balances:

free: this is the only balance that matters in terms of most operations on tokens. It alone is used to determine the balance when in the contract execution environment.

Reserved: this balance is a 'reserve' balance that other subsystems use in order to set aside tokens that are still 'owned' by the account holder, but which are suspendable. Transactions made in Governance need a bond and it is called reserved balance. Here are some cases of transactions:

  • Submit proposal in Democracy

  • Submit proposal in Council

  • Submit proposal in Treasury

  • Add bounty

misc_frozen: the amount of 'free balance' may not drop below when withdrawing for anything except transaction fee payment.

fee_frozen: the amount that 'free balance' may not drop below when withdrawing specifically for transaction fee payment.

Note that misc_frozen doesn't combine with fee_frozen to be deducted from the free balance.

The usable balance of the account: is the amount that is a free balance minus any funds that are considered frozen (either misc_frozen or fee_frozen) and depends on the reason for which the funds are to be used.

  • If the funds are to be used for transfers then the usable amount is the "free" amount minus any misc_frozen funds.

  • However, if the funds are to be used to pay transaction fees then the usable amount would be the "free" funds minus any funds that are fee_frozen.

For example

  • Free balance= 100 - transaction fee= 99.99

  • Usable balance= 50,99

  • Misc_frozen= 40

  • Fee_frozen= 40

→ Usable balance to pay fee= 100- 40=60.

Tx fee= 0,01 → New free balance=100 - 0,01= 99,99.

→ Usable balance to transfer= 99,99-40=50,99

The total balance of the account: is considered to be the sum of free and reserved funds in the account. Reserved funds are held due to on-chain requirements and can usually be freed by making some on-chain action. For example, the "Identity" pallet reserves funds while an on-chain identity is registered, but by clearing the identity you can unreserve the funds and make them free again.

Note that during the bonding period, you can bond more by using the usable balance= old usable balance + unbonded amount

For example:

  • Stash account A:

    • Free = 100 - transaction fee= 99.99

    • Usable balance=79,99

    • Bonded=10

    • Locked =20

    • Unbonded=10

→ During unbonding period, usable balance to bond more= 79,99+10=89,99

Example

Example 1

Assume that we have 2 accounts A (Initial balance = 100), and account B (Initial balance = 200). We initially bond 50 GLCH to create a paired account: Stash account A - Controller account B. So we have the following results:

Stash account A:

+ Free = 100 - 0.0001= 99,9999. (0.0001: fee transaction for bonding)

+ Reserved = 0

+ Misc_Frozen = locked= bonded= 50

+ Fee_Frozen =50

Controller account B:

+ Free = 200

+ Reserved = 0

+ Misc_Frozen = 0

+ Fee_Frozen =0

Then unbond 10 GLCH. When the unbonded amount hasn’t been withdrawn, we have the following result

Stash account A:

+ Free = 99,9999.

+ Usable= 49,9999

+ Reserved = 0

+ Misc_Frozen = locked= 50

+ Fee_Frozen = 50

Controller Account B

+ Free = 200 - 0,0001= 199,9999

+ Reserved = 0

+ Misc_Frozen = 0

+ Fee_Frozen =0

When we submit candidacy to become Council, an amount of 100 micro GLCH (approximately equal to 0,0001 GLCH) is deducted from Stash account A to pay for the candidacy bond.

Then there are changes in balances as below:

Stash account A: (when the unbonding period hasn’t run out)

+ Free = 100 - 0.0001= 99,9999.

+ Reserved = 0,0001 GLCH

+ Misc_Frozen = locked= 50

+ Fee_Frozen = 50

After the unbonding period (currently 1 day), the unbonded amount is available for withdrawal, then we have the results as below:

Stash account A

+ Free = 99,9999.

+ Reserved = 0,0001

+ Misc_Frozen = locked=bonded= 40

+ Fee_Frozen = 40

Last updated