Staking - Integration calculations

The following is a typical UI for displaying Staking information:

Calculating unstaked and locked tokens (without General locks)

1. Retrieve balance, available, and staked amounts from get_fio_balance

Example:

{
	"balance": 100000000000,
	"available": 100000000000,
	"staked": 1000000000,
	"srps: 1000000000,
	"roe": 2.333333333
}

2. If balance - available = staked, then there are no unstaked and locked tokens.

3. Otherwise, call get_locks to retrieve locks

Example:

{
	"lock_amount": 2000000000000,
	"remaining_lock_amount": 1000000000000,
	"time_stamp": "2020-03-11T18:30:56",
	"payouts_performed": 2,
	"can_vote": 1,
	"unlock_periods": [
		{
			"duration": 86400,
			"amount": 1000000000000
		},
		{
			"duration": 172800,
			"amount": 500000000000
		},
		{
			"duration": 259200,
			"amount": 500000000000
		}
	]
}

It is important to note that get_locks returns the state of the lock table. The lock table ONLY updates upon a vote or transfer transaction. So, the lock table values, such as remaining_lock_amount may be inaccurate because they have not yet been accounted by the system. get_locks does NOT do anything to validate these values.

4. Since it is possible that one or more unstaking unlock_periods have passed (7 or more days has elapsed since unstaking, each period will need to be checked.

6. Starting with the first unlock_periods

a. time_stamp + duration = unlock_day (duration is in seconds)

b. If the calculated unlock_day <= current_day then this unstake period has passed and those tokens are unstaked and available to the user.

c. If the calculated unlock_day > current_day then this unstake period is in the future and it should be reported as “Unstaked and locked”

7. The sum of the amounts for all of the periods where unlock_day <= current_day should equal balance - available - staked

Calculating unstaked and locked tokens (with General locks)

if users transfer locked tokens to an account, and then also transfers other fio into this account, and then uses this account to stake and unstake, it becomes unclear how to use the information contained within get_fio_balance, and the locked tokens table to properly inform the user of the unstaking, and locked information as it relates to their account.

it is possible that staking can and will take place on the same day that an unlock from transfer lock tokens take place, in this case the system buckets both the unstake lock and the transfer locked tokens general lock into the same lock period. This makes it difficult to separate out the general lock amounts to identify what tokens are from the unstake lock for this account.

Possible solutions:

Add a “type” to the unlock_periods table
- pros – this would clarify the purpose of each lock,
- cons -- we must address mixed locks, or locks that have the same duration of different type, this requires re-design and modification to all the logic used in staking and general locks.
allow this state to exist, and when the math does not add up nicely (IE: balance - available - staked < the sum of all of the future lock amounts happening within the next 7 days) then you know that there is a general lock from transfer locked tokens present, and you can:
- issue a warning that says “One or more of the above unstaked and locked amounts is not relating to staking”
- Other?
  - dis-able the use of transfer locked tokens by users, this capability is not used, maintain these locks as SYSTEM locked tokens, figure out an approach to locking tokens for users when a need arises that we can design for.