75 lines
4.9 KiB
Markdown
75 lines
4.9 KiB
Markdown
# Pallet Parking
|
||
|
||
This is a pallet to icentivize network users to hold their tokens on-chain. The mechanism for this is named "Parking".
|
||
|
||
## Parking metaphor
|
||
|
||
Account holders can "park" their tokens in a single parking lot. Tokens take some time to get their parking slot. Then, for each week when tokens are parked, their amount grows according to total amount of parked tokens. Users can request unparking anytime, but they will only receive their tokens next Wednesday, when they are successfully unparked.
|
||
|
||
## Parking mechanics
|
||
|
||
### Parking
|
||
|
||
To park tokens, account should call "park" call and indicate amount to be parked. It is possible to reap account by doing so, but not recommended in general (there is small potential for replay attack if immortal transactions were used). These tokens go into parking lot pool and stay there, while parked amount is stored in separate parking ledger. There is minimal parked amount, it is highly recommended that it is set above ED.
|
||
|
||
### Rewards computation
|
||
|
||
On first block after Wednesday midnight, following procedure happens:
|
||
|
||
1. Total parked amount (and thus all individual parking amount) is increased with accordance to following annual Parking Reward Percentage (PRP) assuming 365.25 days in a year:
|
||
|
||
in case of 1 - 50k tokens in the parking pool 15% is the PRP
|
||
in case of 50k - 100k tokens in the parking pool 14.5% is the PRP
|
||
in case of 100k -150k tokens in the parking pool 14% is the PRP
|
||
in case of 150k - 200k tokens in the parking pool 13.5% is the PRP
|
||
in case of 200k - 250k tokens in the parking pool 13% is the PRP
|
||
in case of 250k - 300k tokens in the parking pool 12.5% is the PRP
|
||
in case of 300k - 400 tokens in the parking pool 12% is the PRP
|
||
in case of 400k - 500 tokens in the parking pool 11% is the PRP
|
||
in case of 500k - 600 tokens in the parking pool 10% is the PRP
|
||
in case of 600k - 700 tokens in the parking pool 9% is the PRP
|
||
in case of 700k - 800 tokens in the parking pool 8% is the PRP
|
||
in case of 800k - 900 tokens in the parking pool 7% is the PRP
|
||
in case of 900k - 1M tokens in the parking pool 6% is the PRP
|
||
|
||
There is no mechanics defined outside of these ranges.
|
||
|
||
2. All newly parked tokens are added to pool and from this moment are considered as parked.
|
||
|
||
3. Reward coefficient is stored for lazy reward computation.
|
||
|
||
### Lazy rewards computation
|
||
|
||
To avoid getting extremely large Wednesday block with many parked accounts, rewards are computed on demand. Using associativity of multiplication (`a(b+c) = a*b + a*c`), we can calculate only total pool size on reward event, but spread individual accounts computation in time (and even get the logic for that off-chain). Now rewards are computed in either of the following:
|
||
|
||
1. Parking events
|
||
2. Unparking events
|
||
3. 'apply_rewards' calls
|
||
|
||
Upon recalculation, updated balance of account is recorded. This could be used to estimate accumulated rewards on demand. This call could be sent from any account for any other account, is harmless and benefitial for the network.
|
||
|
||
Downside of this approach is that full log of past reward coefficients is stored. Although not particularly large, it is limited from above to keep things clean. Fortunately, automatic trimming is implemented for coefficients that are not needed anymore (no accounts with not calculated rewards remain before the unnecessary coefficient). Thus, occasionally some check should be performed to prevent the list of stored coefficients overgrowing.
|
||
|
||
These are possible solutions for this:
|
||
|
||
- Incentivize users to recalculate rewards when those are sufficiently old (silly solution but increases involvement) or make an off-chain robots do it on community funding;
|
||
- Implement automated "on idle" recalculation (requires some extra caching logic and thus should be implemented carefully);
|
||
- Keep growing cache size with upgrades, as needed
|
||
|
||
### Unparking
|
||
|
||
Account can request unparking (possibly partial) anytime by calling `unfreeze`. After this request, rewards are calculated and unparked tokens are delivered to user in frozen form if they were properly parked in the pool or unfrozen if they were not (unfrozen unparking taking precedence). Funds can be unfrozen after the Wednesday or are automatically unfrozed on next parking or unparking by the same account.
|
||
|
||
### Source of funds and management
|
||
|
||
Funds are coming from "benefactor" account that should be set by parking manager account (or Root) before the pallet could be used. Funds would be drawn from this account on every Wednesday to grow parking pool. There is no plan on what should happen if this account does not have enough free balance. Maximum amount that could be withdrawn in a week is approximately 1000 tokens. Please make sure benefitiary does not get drained.
|
||
|
||
Benefitiary account could be changed anytime, but could not be un-set.
|
||
|
||
## Usage
|
||
|
||
1. Parking manager or root sets benefitiary account by calling `set benefactor` at least once.
|
||
2. Users park, unpark, collect rewards, enjoy.
|
||
3. Remember to trim old coefficients when needed (or patch this pallet to do it automatically).
|
||
|