How should we calculate circulating supply?

[telezhnaya]

Circulating supply is total supply minus locked tokens.
Not all tokens on the lockup contract accounts are actually locked: some of them could be withdrawn by the owner, and that is the main difficulty here.

My task here is to:

• Read previous attempts of solving this task (see below)
• Understand, how should we calculate the amount of locked tokens for account X
• Check numbers on a historical data (October 2020 - March 2021)
• Try to talk with our finance team if my numbers will have big difference
• Then, go to this issue and write yet another solution for that

Previous attempts

• Rust solution
• JS solution

Useful materials

• Docs and source code of lockup contract
• Probably I need to read this file in contract
• Tool that could answer what amount is locked for account - I don't want to use it, no guarantee that it gives correct result
• Sources of this tool
• Numbers from our financial team - no-one can answer me, how exactly it was calculated

[telezhnaya]

• I used Rust solution as a start, because it was based on lockup contract realisation (sounds trusted enough)
• I changed @khorolets solution a little, just to collect all available data. Collected data is here (and the code is also there, no rocket science, only dumping to csv)
• I analysed numbers for all accounts: numbers are completely different compared to data from financial team (*)
• I decided to analyse numbers for accounts with public vesting schedule (it's more than a half of all accounts): that also wasn't a good idea, @frol said to try to ignore this field. See reasons and explanation below (1)
• I got rid of vesting schedule in lockup contract's realisation of get_locked_amount and again collected all available data, it is here
• Vesting schedule actually does not change almost anything compare to version in the early beginning (*) (~100 NEAR difference, it's not a difference in our scale)
• See some graphs here. I used numbers with ignoring vesting schedule, but again, it makes no sense, the graph for all data with vesting schedule looks the same. It's interesting that the lines become to move more similarly, but we need more data to prove this theory. For the April, diff is still 70KK NEAR, it's too much.
• There is a theory from @khorolets that we need to subtract some foundation accounts from circulating supply. From this ticket, we know that foundation owned 244KK NEAR in the end of March, so probably it will affect our numbers much more than we want to. UPD: since we have data from financial team, it's better stop guessing and just analyse the data

(1) We have unlocking logic, and vesting logic, and it's not the same process. Let's look at the example. We have an employee X, she started working at Near in 2017 and finished at 2019 (she was working exactly 2 years, and that's OK that she started before the company was created, don't blame her). Her vesting logic started with her starting day as an employee, but her unlocking logic will start only when transfers are enabled (14th of October 2020). There will be standard one year cliff and then one more year of linear unlock. (We assume that she had standard 4-year vesting schedule with 1-year cliff included, and her process is taking 2 years because she decided to leave the company). In vesting_schedule field we have employee information. As we can see, it does not affect actual unlocking of tokens, so it looks like we should ignore this data.

[telezhnaya]

Thoughts about data from finance team

• The smooth jump in October 2021 should be not smooth, but sharp. It is the moment when the cliff finished for many lockups in the system.
• According to their data, all lockups started in October 2020 (after transfers was enabled): I do not believe in it since significant number of lockups were created after that date

[telezhnaya]

Let's look at the moment when transfers enabled, 14th of October.

Data from finance team:

amount	cliff	whole_lockup (in days)
140000000	365	1460
50000000	0	0
106390580	0	30
33635810	0	182
59937800	0	365
248398783	0	730
75734000	0	1095
285903000	0	1825
999999973 total

The doc looks like all the tokens was put on the lockups and then they should be partially unlock, but for sure that's not true. Have plans to investigate final numbers further.

Real data:

amount	cliff	whole_lockup	explanation
117455000	365	1460	should be +23KK
20000	365	365	???
1250000	365	639	???
24785308	0	0	should be +25KK
50	0	1	Looks like test
100	0	10	Looks like test
167000	0	182	should be +33KK
57114814	0	365	should be +3KK
34939389	0	730	should be +213KK
7556319	0	1095	should be +68KK
0	0	1825	???, should be +285KK

It's hard to guess, which money should not have been locked, but I also have a plan to investigate it more

[telezhnaya]

The best result I've reached so far:

Looks amazing, but the numbers are not so good, actually.

month	finance data	data from code	diff
10/14/2020	157503033	235057243	78M
11/14/2020	189443528	204127204	15M
12/14/2020	221413208	227306254	6M
1/14/2021	253434736	254035392	0.6M
2/14/2021	285584565	277981655	-8M
3/14/2021	317530390	299634810	-18M
4/14/2021	349452304	325405443	-24M

But, I guess we can explain this difference.

[telezhnaya]

How did I get these numbers:

1. I took the old version of code from lockup contract implementation (the one that was used to launch these contracts). From there, I took the function that gives the locked amount of tokens (it takes block height and account id as the parameters).
2. For each 14th of month, I collected total supply, block height and all existing lockup contracts. The contract could be finished but it still appears in the data, that's not a problem, locked amount would be zero in this case, so it does not affect anything.
3. I collected data about locked amount for each account and each month.
4. For each month, I used the formula

circulating = total_supply - sum(locked_amount for each account) - amount_of_lockup.near - amount_of_contributors.near

We discussed also foundation.near, decided not to subtract it from circulating supply.
contributors.near could be calculated partially. It contains the tokens that should go to the lockups but they are waiting for it. So, we can imitate that they are gradually unlocking. Instead of that, I decided not to overcomplicate the formulas and just sum it up with locked amount.

@frol we are waiting for the approve from Yessin. After that, if everything is fine, should I rewrite the solution to JavaScript?
We could be more or less confident in the final solution (I mean Rust vs JavaScript version) since we have the numbers and we can compare the results.