Balances Model

The idea or purpose of the “balances model” is to define a minimal set of balances that govern an asset. These balances should be chosen in a way so that the UI can show them in a generic way without doing any asset specific calculations. We also define some derivable balances, such that can be calculated in a generic way from the minimal set.

This minimal set should be applicable to all assets that we support and should allow calculating any other amount in the wallet that we need to show to the customer.

The model also defines which fields are returned by the asset.api.getBalances() function, which all assets must implement.

Definitions

Confirmed amount - on-chain consensus balance. It may be fetched from a coin node or calculated from transactions or utxos. The meaning of confirmed depends on a specific chain. For most chains we accept one confirmation as confirmed. Some chains such as Monero require more confirmations.

Unconfirmed amount - an amount derived from values of pending transactions.

Balances Model

Here is the information formatted as a markdown table with two columns:

Balances representation

{
    total, // total
    unconfirmedSent,
    unconfirmedReceived,
    spendable,
    unspendable,
    stakeable,
    walletReserve,
    networkReserve,
    staking,
    staked,
    unstaking,
    unstaked,
    rewards,
    frozen,
} = asset.api.getBalances({ accountState, txLog })

Deriveable amounts:

reserved = walletReserve + networkReserve

available = spendable - fee

unconfirmed = unconfirmedReceived + unconfirmedSent

Asset examples

Bitcoin

{
    balance, // from utxos, includes confirmed balance and unconfirmed received amounts
    unconfirmedSent, // from txLog + utxos
    unconfirmedReceived, // from txLog + utxos
    spendable: balance, // may also contain unconfirmed received utxos values
    unspendable, // utxos used by inscriptions or BRC20 transfers, unconfirmed utxos in some cases, ...
}

Elrond

We receive the on-chain balance using an RPC call. All received amounts are final, so we don’t have pending unconfirmed transactions. The spendable balance simply equals the on-chain balance.

{
  balance, // RPC
  unconfirmedSent, // unconfirmed sent txs from txLog
  spendable: balance,
}

EOS

We get many values from the network, including: totalBalance, liquidBalance, refundBalance

{
  balance: totalBalance,
  unconfirmedSent, // from txLog
  spendable: liquidBalance,
  walletReserve: staked || unstaking || unstaked ? RESERVE : ZERO,
  staked: totalBalance - liquidBalance - refundBalance,
  unstaking, // from txLog,
  unstaked: refundBalance,
}

Ethereum

We get several staking related amounts: unclaimedUndelegatedBalance, delegatedBalance, rewardsBalance, withdrawable.

{
    balance, // from txLog, includes confirmed balance and unconfirmed received amounts
    unconfirmedSent, // from txLog
    unconfirmedReceived, // from txLog
    spendable: balance,
    walletReserve,
    staking,
    staked: delegatedBalance,
    unstaking,
    unstaked: withdrawable,
    rewards: rewardsBalance,
}

Hedera

We fetch the on-chain balance once, when the monitor starts up for the first time. We also fetch all transactions and calculate an initialBalance as a difference between the on-chain balance and the txLog balance: initialBalance = onChainBalance - txLogBalance.

Received amounts are final, we don’t have unconfirmedReceived.

{
  balance, // from txLog, includes confirmed balance and unconfirmed received amounts
  unconfirmedSent, // unconfirmed sent txs from txLog
  spendable: balance,
}