Simplifying & Clarifying `calculateCirculatingSupply` computation

[bedeho]

Background

Currently we are using calculateCirculatingSupply to compute this, and it is both complex, undocumented/explained, has redundancies and is possibly incorrect w.r.t. intended semantics. Lets fix, is needed for Subscan, Coingecko and CMC, among other things.

Proposal

Semantics

Amount of tokens across all accounts which, are not encumbered by vesting lock.

Note

• Scope: We therefore include tokens which are not transferrable, but are not locked in vesting, such as voting, nomination, validation, etc.
• Isonar Bug: Be aware that vesting locks can be much greater than actual account balances, because there is an edge case in the vesting pallet which allows vested self-transfer without verifying that vesting amount actually is funded.
• Single lock: Be aware that there is only a single vesting lock per account, even if there are multiple schedules.
• AccountData concepts: the total amount of tokens in an account is free + reserved, the locks only apply to the free portion, hence the total quantity of tokens that exist in an account, but which are locked by a vesting lock is X = min{vesting_lock_amount, free}, provided there is actually such a lock.

To compute circulating supply, just do total_supply - Sum(X) for all accounts where vesting lock exists.

Approach

We go for simplicity over speed or efficiency, having this fucntion be easily verifiable is very valuable.

Check Delta

Do computation and derive new circualting supply, compare this value to existing script, raise the alarm if there is a delta, we expect there to be one, but it may also not be the case. If there is, we want to pin point which exact accounts have a different contribution across the two schemes.

Documentation

Make the implementation very well documented, line by line, and also the function itself.