Introduction

The objective of this project is to develop functionality to properly determine the number of tokens that are locked at any given time in order to properly determine FIO token circulating supply.

Today this calculation is based on the following:

• Tokens defined in lockedtokens → total_grant_amount summed and considered unlocked when one of predefined time period passes.

• Tokens locked for BP rewards in:

  • bpbucketpool

  • bprewards

This calculation does not properly consider:

• Today

  • Locked tokens overstated (est. 4,300,000 as of 09/22/2020): it assumes tokens of lock type 2 unlock based on predefined time period, but in reality they also have to have the unlock inhibit flag flipped to be unlocked and many of them do not have the flag flipped yet.

  • Locked tokens understated (est. <50,000 as of 09/22/2020): it does not properly consider tokens spent on fees, which is allowed even if tokens are locked. This primarily impacts tokens of lock type 4 which are seen as permanently locked, even though almost 500,000 have entered circulating supply and then been re-locked in BP rewards and are released every day.

• After October 21st, 2020

  • Locked tokens overstated: tokens of lock type 2 and for which unlock inhibit flag has not been flipped will not be considered 100% locked as they should. They will continue to unlock based on predefined time period.

• After launch of FIP-6

  • Locked tokens understated: tokens locked using the new functionality will not be considered locked.

Mainnet locks background

Some tokens have been locked at Mainnet as described in Mainnet locks

The lockedtokens table stores:

It is worth noting that the remaining_locked_amount is only updated when the account is subject to an action impacting token balance such as:

• Transferring tokens

• Voting

• Proxying

• Receiving tokens

Therefore in its current state, sum of remaining_locked_amount is not a good way to calculate locked tokens, because if a predefined time period passes, the amount will not be automatically updated. That’s why time is used in existing calculations.

Solutions Considered

On-chain

An enhancement to the FIO Protocol could be be made to create a new maintenance call, which would recalculate locked tokens for every account in locked token table for both Mainnet locks and FIP-6 locks.

Pros:

• Locked token balance could be obtained on-chain by simply summing remaining_locked_amount for both Mainnet locks and FIP-6 locks.

Cons:

• This may involve a lot of calls to process, especially since FIP-6 does not put a limit on number of accounts that can have locks or how many time periods they can have.

• Processing would not be instantaneous and therefore locked token numbers would potentially be inaccurate before all processing is complete.

SELECTED: Off-chain

Custom logic could be built on existing Graphana stats service or similar which would properly report locked tokens:

• BP locks

  • Would work as is

• Mainnet tokens locked

  • Would look at tokens in lockedtokens and properly evaluate:

    • Tokens would automatically be considered unlocked based on predefined time period

    • Type 2 unlock inhibit flag would be considered

    • Balance inflow/ouflow would be considered such as when fees are paid out of lock balance (Type 4)

• FIP-6 token locks

  • Would look at tokens in lockedtokens and properly evaluate:

    • Tokens currently locked based on lock schedule and time passed from lock start

• Future unlock chart

Pros:

• Can be built without modifications to off-chain code

• Can be more rich, e.g. charts

• Can be built on top of on-chain solution

Cons:

• Data on-chain may not be accurate to outside observer who does not understand the details behind how table values are computed.

Solution Specification

Circulating Supply Service

Existing Circulating Service needs to be modified to accurately compute locked tokens:

• Tokens locked via Mainnet locks

  • Inspect each account in lockedtokens table and apply the same logic used by chain

• Tokens locked via FIP-6 functionality

  • Inspect each account general_locks_table and apply the same logic used by chain

Grafana import

A data feed to Grafana should be generated which would enable the creation of a stacked graph, similar to this, which shows circulating supply over time in the following categories:

• Mainnet locks: Type 1

• Mainnet locks: Type 2

• Mainnet locks: Type 3

• Mainnet locks: Type 4

• FIP-6 locks

• Tokens locked in BP reward buckets

• The following are assumed permanently locked in the future:

  • BP reserves

  • User bounties

  • Address Giveaways

Initiative link

https://fioprotocol.atlassian.net/browse/WP-92