Display locked token balance breakdown on Account Detail page

[kcole16]

Overview

Related issue in Wallet: near/near-wallet#481

We display "locked" balance, which is the amount staked. We should also display the other types of locked balances:

• Vesting
  • Several community members (NEAR team, contributors) have tokens that vest over time, and will be unlocked linearly, block by block
• State stake (Minimum Balance)
  • There is a minimum required balance (NEP #40) for all accounts. This can only be transferred by deleting the account
• Staking
• Delegating

Story

As a user, I want to view both my active and locked (vesting, state staked, delegated, staked) token balances, so I can understand the quantity of tokens that are fully usable and transferrable.

Acceptance Criteria

• Total NEAR balance (available+locked) is visible
• Available NEAR balance is visible (total - locked)
• Locked NEAR balance is visible, and broken down into
  • Staked
  • Minimum Balance (storage_used * cost_per_byte)
  • Vesting
  • Delegating
• Difference between locked and available is explained
• Minimum balance is explained
• Mobile ok
• Tested

[frol]

[frol]

• Change "Locked" to "Staked Balance"
• Add "Lockup Balance" for a lockup contract

Add help messages to those briefly describing the balance type and link to a relevant documentation page

[icerove]

lockup contract: link to it | amount | lockup details |

what is link to it and lockup details you mentioned? @ilblackdragon

[kcole16]

@icerove Here is the line in the wallet which computes the lockup account name: https://github.com/near/near-wallet/blob/master/src/utils/wallet.js#L601

LOCKUP_ACCOUNT_ID_SUFFIX = lockup.near for mainnet

[icerove]

From this line, what I can know is that I can not reverse account ID from lockup ID. I do not know how to get lockup balance for now since I can not know which account is lockup, right? @kcole16 @ilblackdragon

[frol]

From this line, what I can know is that I can not reverse account ID from lockup ID

Lockup contract has get_owner_account_id view method: https://github.com/near/core-contracts/blob/215d4ed2edb563c47edd961555106b74275c4274/lockup/src/getters.rs#L9

I do not know how to get lockup balance for now since I can not know which account is lockup, right?

If a given account id ends with the LOCKUP_ACCOUNT_ID_SUFFIX (.lockup.near on mainnet), it is a lockup contract, otherwise, use the function to compute the lockup account id from the given account id and try calling the view methods on it. There are various methods on the lockup contract; Wallet displays it in the finest break down [get_owners_balance, get_liquid_owners_balance, get_locked_amount] (read the documentation comments on those); I believe we should just display the get_balance on Explorer side and link to https://wallet.near.org/profile/<account_id> for the breakdown.

[bowenwang1996]

otherwise, use the function to compute the lockup account id from the given account id and try calling the view methods on it.

This only works for a certain amount of lockups deployed on mainnet. In general there is not necessarily any relationship between the owner account id and the lockup account id.

[frol]

@bowenwang1996 If I read this correctly, this means that to implement it 100% correctly, we need to implement Indexer for lockup contracts drawing the relationships to their owners, right?

[bowenwang1996]

@bowenwang1996 If I read this correctly, this means that to implement it 100% correctly, we need to implement Indexer for lockup contracts drawing the relationships to their owners, right?

That is correct.

[kcole16]

Our implementation in the wallet is pretty naive, in that it just checks for a lockup for the currently selected account, and shows it if it exists.

A complete solution in Explorer should deal with the case of the lockup itself, and also further naming conventions (whichever those end up being). That being said, I think for this pass it is fine to have a one-way lookup. This will solve 100% of the questions we are currently receiving from users.

[frol]

Given Wallet has the same naive approach, I think we should at least implement it this way in Explorer for now. We are currently deploying the initial version of Indexer for Explorer on testnet, and I think this naive implementation can be implemented before we settle down on Indexer for Explorer on mainnet and Explorer frontend updated to the new data source (SQLite -> Postgres with some data structure changes)

[ilblackdragon]

As pointed out in the message - you can grab code that pulls all lockup details (finding account, getting internal state, showing vesting/lockup) from here https://github.com/near/account-lookup

[ilblackdragon]

#291 (comment)

To be clear, I don't think we need this - I think we should just show the state of the lockup on the account itself.
E.g. we just use code above to fetch the state from lockup and don't need to do anything the other way.

[ilblackdragon]

This only works for a certain amount of lockups deployed on mainnet. In general there is not necessarily any relationship between the owner account id and the lockup account id.

@bowenwang1996 you are wrong, all lockups respect this relationship.

[frol]

@icerove Let me give you the exact values:

Minimum Balance = cost_per_byte [RPC EXPERIMENTAL_genesis_config] multiplied by storage_used [RPC query(view_account)]

Staked Balance = locked [RPC query(view_account)]

Available Balance (a.k.a. Liquid Balance) = minimum of two(amount OR (amount [RPC query(view_account)] plus Staked Balance minus Minimum Balance))

Lockup Balance = make a view-call to the lockup contract method get_balance

Total Balance = amount plus Staked Balance plus Lockup Balance

Let's skip Vesting and Delegating balances for now (unless someone considers them to be crucial for Explorer).

[ilblackdragon]

Hm, I think liquid balance calculation is wrong - it's amount - min(staked balance, minimum balance)
e.g. https://wallet.near.org/profile/illia.near Available Balance here.
Also we should prob use the same terms across all this places.

[frol]

@ilblackdragon your liquid (immediately available) balance formula does not make sense to me 🤔

The liquid balance is something that you can spend immediately, but the amount provided by RPC includes the liquid balance for storage. The full balance for storage is (cost-per-byte * storage-used), but if you stake some tokens, those are accounted as ones that cover storage, and liquid balance for storage is max(0, balance for storage - staked).

The liquid balance is (amount - liquid balance for storage) = (amount - max(0, full balance for storage - staked)) = min(amount, amount + staked - full balance for storage)

Let me know if I miss something

[bowenwang1996]

@frol hmm I think the amount returned in rpc does not include staked balance (which is returned as locked). So the liquid balance should simply be amount - storage cost? Did I miss something here?

[bowenwang1996]

@bowenwang1996 you are wrong, all lockups respect this relationship.

Yes I was wrong. On mainnet all lockups respect this relationship, but I wanted to say that in general there is nothing enforcing such relationship. However it appears that we want to make this a standard (from my conversation with @ilblackdragon )

[frol]

hmm I think the amount returned in rpc does not include staked balance (which is returned as locked).

Correct

So the liquid balance should simply be amount - storage cost? Did I miss something here?

@bowenwang1996 Almost correct (please, refer to my comment above).

The liquid balance is amount - liquid storage cost

liquid storage cost is the storage cost that is not covered by the balance locked for stake

@evgenykuzyakov we need your final word here

[bowenwang1996]

liquid storage cost is the storage cost that is not covered by the balance locked for stake

Yeah I see what you meant now. That is correct

[ilblackdragon]

Can we make at least basic UI change for this?
E.g. change current "Locked" to "Staked". And add a section of "Locked" to query associate lockup contract if it is present.

As I mentioned, we have a lot of people confused with where are their tokens.

[icerove]

Minimum Balance = cost_per_byte [RPC EXPERIMENTAL_genesis_config] multiplied by storage_used [RPC query(view_account)]

I see many cost_per_byte here and they are different numbers, which one should I use for that? @frol

[frol]

@icerove it is "runtime_config"."storage_amount_per_byte", sorry for the confusion