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:
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:
total_grant_amount | Total amount of locked tokens |
|---|---|
unlocked_period_count | Number of predefined schedule time periods which have passed |
grant_type | Type of lock |
inhibit_unlocking | Integration flag determines if FIO Member has launched integration |
remaining_locked_amount | Remaining locked tokens |
timestamp | Date when locks set (Mainnet) |
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 feeds current and future tokens locked and divided into the following categories:
Mainnet locks: Type 1
Mainnet locks: Type 2
Mainnet locks: Type 3
Mainnet locks: Type 4
FIP-6 locks
Since it’s difficult to recreate circulating supply historical data, Grafana reports should only include future unlock amounts based on time periods only. For lock type 4, a average number of tokens unlocked in previous 30 day period should be used instead.