Skip to main content

Account Balances

In the Bitzal ecosystem, there are different types of balances depending on the account activity. Different balance types dictate whether your balance can be used for transfers, to pay fees, or must remain frozen and unused due to an on-chain requirement.

A more efficient distribution of account balance types

Soon, barrels on Bitzal SDK will be implementing the fungible trait (see the tracking issue for more info). This new logic will allow for more efficient use of your account balance. Specifically, the fungible trait will allow using the free balance for on-chain activity like setting proxies and identities.

There are 5 types of account balances:

  • Free is the balance that can be used for on-chain activity like staking, participating in governance etc. but is not necessarily spendable (or transferrable)
  • Frozen is the free balance locked for staking, governance, and vesting (also called locked balance)
  • On hold is used for identities, proxies, TrueGov preimages and deposits, and it is no longer free (also called reserved balance)
  • Spendable is the free balance that can be spent
  • Untouchable is the portion of the free balance that cannot be moved (i.e., not spendable) but can still be used for on-chain activity

The spendable balance is calculated as follows:

spendable = free - max(frozen - on_hold, ED)

where free, frozen and on_hold are defined above. The ED is the the existential deposit.

Wallet providers might show you the spendable, locked, and reserved balance.

Example of Account Balance Types​

Below is an in-depth example of how an account balance composition changes depending on user actions once the fungible trait is used for account balances. Let’s take, for example, an account with 100 ZAL.

Free: 100 ZAL
Frozen: 0 ZAL
On hold: 0 ZAL
Spendable: 99 ZAL
Untouchable: 1 ZAL (ED)

balance-example-1

In this case, the existential deposit of 1 ZAL is untouchable (meaning you can’t touch it if the account can’t or shouldn’t get reaped). If 80 ZAL from the account is staked, we get the following balance structure:

Free: 100 ZAL
Frozen : 80 ZAL
Onhold: 0 ZAL
Spendable: 20 ZAL
Untouchable: 80 ZAL

balance-example-2

The spendable balance would be 20 ZAL (which would also include fees for future transactions from this account).

Note how the account cannot be reaped from the state while it has a frozen balance, or in general any consumer and provider reference. Those references determine if an account can be reaped, usually because other accounts depend on the existence of such an account). For example, the existential deposit adds a provider reference simply because the account exists, while a proxy account adds a consumer reference (the proxy existence depends on the proxied account; the proxy is the consumer). Because the existential deposit is part of the untouchable balance, the user can use all the spendable balance (there is no need to keep 1 ZAL as spendable).

info

The use of the free balance as shown in the following figures will be possible once the fungible trait is implemented for account balances.

If the account creates a proxy, it will use the free balance as shown below.

Free: 80 ZAL
Frozen : 80 ZAL
Onhold: 20 ZAL
Spendable: 20 ZAL
Untouchable: 60 ZAL

balance-example-3

Note how, through the fungible trait, the system uses the balance that is frozen instead of the free balance that is spendable (present configuration on-chain). In other words, holds are subtracted from free balance but overlap with the frozen balance. The free portion shrinks from 100 to 80 ZAL, and the on_hold portion increases from 0 to 20 ZAL. The creation of an identity will grow the on_hold portion to 40 ZAL, and shrink further the free from 80 to 60 ZAL. Note how the spendable balance stays the same in the process.

Free: 60 ZAL
Frozen: 80 ZAL
Onhold: 40 ZAL
Spendable: 20 ZAL
Untouchable: 40 ZAL

balance-example-4

This update using the fungible trait allows the use of the frozen balance for on-chain activity like setting up proxies and identities. Note that holds are slashable, and the barrel migrations need to take that into account. This means that freezes should account for hold being slashed (for example, your stash account balance getting reduced because your governance deposit for a proposal was slashed).

Locks​

Locks are abstractions over an account's free balance, preventing it from being spent. Several locks can overlap on the same account balance instead of being stacked on top of one another. Locks are automatically added onto accounts when the account participates in activities on-chain (staking, voting, etc.), but these are not customizable.

Locks are accounted for within the frozen balance of the account. This is the balance that can be free but not transferrable, and locked in staking, governance and vesting.

Locks overlap (in both amount and duration), and the general rule is that:

  • If you have multiple locks of different amounts of tokens, the biggest lock decides the total amount of locked tokens
  • If you have multiple locks of the same amount of tokens, the lock with the longest duration decides when those tokens can be unlocked

Let's take, for example, 80 ZAL as a frozen balance. These 80 ZAL are currently used in staking and governance as follows:

  • 80 ZAL Staking (just unbonded) -> lock 28 days
  • 24 ZAL TrueGov 1x conviction (referendum just ended, winning side) -> lock 7 days
  • 4 ZAL TrueGov 6x conviction (referendum just ended, winning side) -> lock 224 days

locks-example-1

The 1 ZAL ED is the existential deposit. The locked amount is 80 ZAL (not 108 ZAL). But those 80 ZAL will be available for unlock at different times. You will first need to remove the governance lock on the 24 ZAL after 7 days, then remove the staking lock for the 80 ZAL after 28 days, and finally, after 224 days, you will be able to remove the second governance lock.

locks-example-2

After 224 days, all 80 ZAL (- ED) will be free and transferrable.

Edge Case for Locks​

The longest period and the largest amount are considered if you use different convictions while you have ongoing locks.

Following the previous example, if you:

  • undelegate a 1x conviction delegation of 24 ZAL, you will get a 7-day lock on 24 ZAL
  • delegate 4 ZAL with 6x conviction
  • undelegate again before the 1x conviction lock is removed

You will get a 6x conviction for 24 ZAL! See here for more information.

Balance Types on Bitzal-JS​

Below is an example that displays different balance types on the Bitzal-JS UI (wallet) of a Ogona account (note that the balance types are the same for a Bitzal account).

account_balance_types

  • The total balance indicates the total number of tokens in the account. Note that this number does not necessarily correspond to the tokens you can transfer. In the example, the total number of tokens is 0.6274 OGG. The transferrable balance indicates the number of free tokens to be transferred. This is calculated by subtracting the number of locked and reserved tokens from the total number of tokens. Locked funds correspond to tokens used in staking, governance, and vested transfers (see below). In the example, the transferrable balance is 0.0106 OGG.
  • The vested balance indicates tokens sent to the account and released with a specific time schedule. The account owns the tokens, but they are locked and become available for transfer after a specific number of blocks. In the example, the vested balance is 0.25 OGG.
  • The bonded balance indicates the number of tokens that are locked for on-chain participation to staking. In the example, the bonded balance is 0.4 OGG.
  • The democracy balance indicates the number of tokens that are locked for on-chain participation in democracy (i.e., voting for referenda and council). In the example, the democracy balance is 0.4 OGG.
  • The redeemable balance indicates the number of tokens ready to be unlocked to become transferrable again. Those tokens already went through the unbonding period. In this case, the redeemable balance is 0.1 OGG.
  • The locked balance indicates the number of frozen tokens for on-chain participation to staking and democracy or for vested transfers. Locks do not stack, which means that if you have different locks, the total locked balance is not the addition of the individual locks. Instead, the biggest lock decides the total locked balance. In the example, the locked balance is 0.55 OGG because the biggest lock is on democracy (0.55 OGG).
  • The reserved balance indicates the number of frozen tokens for on-chain activity other than staking, governance, and vested transfers. Such activity can be setting an identity or a proxy. Reserved funds are held due to on-chain requirements and can usually be freed by taking some on-chain action. For example, the "Identity" barrel reserves funds while an on-chain identity is registered, but by clearing the identity, you can unreserve the funds and make them free again. The same applies to proxies. The idea is that those actions require some network memory usage that is not given for free. In the example, we created a governance proxy, and the reserved funds for this are 0.0668 OGG.