# LIP-55 InflationManager
## Abstract
This proposal aims to seperate the current `Minter` contract into two separate contracts.
- The `InflationManager`, responsible for handling all inflation related logic
- The `Minter` acts as the owner of the `LivepeerToken` and is the only entity allowed to mint tokens. It also holds minted LPT and ETH from fees awaiting to be distributed.
## Motivation
Currently whenever inflation related logic has to change the entire `Minter` contract needs to be replaced, this involves migrating user funds to the new contract making it a very sensitive operation.
Seperation of concerns between funds management and inflation management allows for upgrades to the inflation logic and parameters without having to migrate user funds to a new contract.
The `Minter` contract itself would have to change very infrequently, on top of already being immutable, resulting in increased safety of user funds during protocol upgrades.
## Specification
### InflationManager
The `InflationManager` is a new contract responsible for inflation management, logic which is now part of the `Minter` contract.
#### State
| Parameter | Type | Description |
| -------- | -------- | -------- |
| inflation | `uint256 ` | Per round inflation rate |
| inflationChange | `uint256` | Change in inflation rate per round until the target bonding rate is achieved |
| targetBondingRate | `uint256` | Target bonding rate as a percentage of total bonded tokens / total token supply |
| currentMintableTokens | `uint256` | Total mintable reward tokens for the current reward period |
| currentMintedTokens | `uint256` | Track how many tokens are already minted in the current round |
| nextMintableTokens | `uint256` | Total mintable reward tokens for the next reward period |
#### API
##### inflation
```solidity
function inflation() external view returns (uint256);
```
Get the current inflation rate. This is a percentage scaled by factor `1 000 000 000`.
##### inflationChange
```solidity
function inflationChange() external view returns (uint256);
```
Get the current inflation change. This is a percentage scaled by factor `1 000 000 000`.
##### setInflationChange
```solidity
function setInflationChange(uint256 _inflationChange) external onlyControllerOwner;
```
Set the current inflation change. This is a percentage scaled by factor `1 000 000 000`.
Only callable by the `owner` of `Controller`.
##### targetBondingRate
```solidity
function targetBondingRate() external view returns (uint256);
```
Get the current target bonding rate. This is a percentage scaled by factor `1 000 000 000`.
i.e. `50% = 0.5 * 1 000 000 000 = 500 000 000`
##### setTargetBondingRate
```solidity
function setTargetBondingRate(uint256 _targetBondingRate) external onlyControllerOwner;
```
Set the current target bonding rate. This is a percentage scaled by factor `1 000 000 000`.
Only callable by the `owner` of `Controller`.
#### currentMintableTokens
```solidity
function currentMintableTokens() uint256 external
```
Returns the amount of total mintable tokens for the current active reward period.
##### setCurrentRewardTokens
```solidity
function setRewardTokensForRound(uint256 _round, uint245 _amount) external onlyRoundsManager
```
Sets the amount of reward tokens that are mintable for the current reward period.
Only callable by the `RoundsManager`.
The amount of tokens that is mintable for a round is calculated as follows:
$r = {totalSupply}\times inflation$
```solidity
uint256 rewardTokens = MathUtils.percOf(
livepeerToken().totalSupply(),
inflation
);
```
##### currentMintedTokens
```solidity
function currentMintedTokens() public view returns (uint256);
```
Returns the current total amount of tokens already minted in the current round.
Called by `BondingManager` to see if the amount of total rewards for the round doesn't exceed the minimum set forth during round initialization.
```solidity
uint256 currentMintedtokens = currentMintedTokens.add(rewardAmount);
require(
currentMintedTokens <= rewardTokensForPeriod,
"minted tokens cannot exceed mintable tokens"
);
```
`currentMintableTokens` and `currentMintedTokens` will be reset when a new round starts.
##### setCurrentMintedTokens
```solidity
setCurrentMintedTokens(uint256 _amount) internal
```
Sets the tokens minted so far in the current eligible reward period. Resets when a new reward period starts.
Can only be called by the `BondingManager` and `RoundsManager`.
If `_amount` is 0, reset `mintedInRewardPeriod` and `tokensForRewardPeriod`, as this indicates a new reward period starts.
#### nextMintableTokens
```solidity
function nextMintableTokens() uint256 public
```
Returns the amount of totable mintable tokens for the next reward period. This value is updated each round with the amount of inflationary LPT until all rounds for the reward period are accounted for.
##### setNextMintableTokens
```solidity
function setRewardTokensForRound(uint256 _round, uint245 _amount) external onlyRoundsManager
```
Sets the amount of reward tokens that are mintable for the next reward period.
Only callable by the `RoundsManager`.
The amount of tokens that is mintable for a round is calculated as follows:
$r = {totalSupply}\times inflation$
```solidity
uint256 rewardTokens = MathUtils.percOf(
livepeerToken().totalSupply(),
inflation
);
```
### Minter
The `Minter` will hold inflationairy LPT that has been minted by `reward` calls and will be the only entity that can `mint` Livepeer Tokens.
The `Minter` will also hold any ETH from winning ticket redemptions until withdrawal.
#### API
##### migrateToNewMinter
Migrates the current `Minter` to a new deployment. Internally transfers all balances to the new contract.
Only callable by the `owner` of `Controller`
```solidity
function migrateToNewMinter(IMinter _newMinter) external onlyControllerOwner whenSystemPaused;
```
##### trustedTransferTokens
```solidity
function trustedTransferTokens(address _to, uint256 _amount) external onlyBondingManager whenSystemNotPaused;
```
Transfers `_amount` Livepeer Token from the `Minter` to the recipient `_to`.
Only callable by the `BondingManager` when the system is not paused.
##### trustedBurnTokens
```solidity
function trustedTransferTokens(address _to, uint256 _amount) external onlyBondingManager whenSystemNotPaused;
```
Burns `_amount` Livepeer Token.
Only callable by the `BondingManager` when the system is not paused.
##### trustedWithdrawEth
```solidity
function trustedWithdrawETH(address payable _to, uint256 _amount) external onlyBondingManagerOrJobsManager whenSystemNotPaused;
```
Transfers `_amount` ETH from the `Minter` to the recipient `_to`.
Only callable by the `BondingManager` or `TicketBroker` when the system is not paused.
##### depositETH
```solidity
function depositETH() external payable onlyMinterOrJobsManager returns (bool)
```
##### createReward
```solidity
function createReward(uint256 _rewardTokens) external onlyBondingManager whenSystemNotPaused
```
Mints `_rewardTokens` where `_rewardTokens` is the total amount of mintable tokens for a transcoder for a given `rewardPeriod`, a `rewardPeriod` can consist of multiple rounds.
Calculating the number of `_rewardTokens` is now a responsability of the `BondingManager` instead.
# LIP-56 Reward Period
## Abstract
This proposal introduces a reward period which can reduce the frequency of reward calls (reward distribution transactions) and the overall costs incurred by orchestrators that are responsible for calling reward.
## Motivation
Gas prices on Ethereum have been fairly high due to increased demand for blockspace. In recent months the transaction cost of calling reward daily in order to receive inflationary LPT rewards often exceeds or is only marginally lower than the value received for many Orchestrators on the network.
To reduce the cost burden we could change the reward algorithm to require less frequent reward calls in tradeoff for a slightly higher single transaction cost.
E.g. Let's say a reward call under current conditions (per round basis) costs $100. Introducing a reward period would increase the cost to $150 for the call, but the frequency of calls reduces by 7x.
This still results in a cost saving of several magnitudes, in this example a 4.6x reduction:
`$100 * 7 / $150 = 4.6`
## Specification
Rewards are minted for each `rewardPeriod` rather than each round. Transcoders can call reward to claim their earnings for a `rewardPeriod N` during the entirety of `rewardPeriod N + 1`.
The new frequency at which `reward` needs to be called will be equal to `rewardPeriodlength`. A delegator and its delegates needs to be staked for the entirety of a `rewardPeriod` to be eligible for its rewards.
Delegators are free to add or remove stake during a reward period, the amount at the end of the reward period will count. A delegator can never be eligible to receive rewards from multiple delegates for the same reward period.
In more detail **the rules** are as follows:
- If a delegator was previously unstaked and staked during a reward period it will only be eligible for rewards starting from the next reward period.
- If a delegator completely unstakes during a reward period it will forgo all of its earned rewards during the reward period.
- If a delegator unstakes a portion of its stake during a reward period, its lowest amount will count for that reward period.
- If a delegator adds stake during a reward period, only its initial stake will count for that reward period.
- If a delegator switches delegate's during a reward period it will forgo it's rewards for the current reward period.
In order to achieve this, **a few core principles** are introduced in this specification:
- `totalStake` for a `delegate` at the end of a reward period counts for the reward distribution calculations.
- Checkpointing is done using the `endRound` of a reward period
- Time progression for fees is on a different scale than rewards.
- There are three distinguishable epochs we need to track
- Current reward period for which reward can be called and the amount of mintable tokens is locked
- Next reward period for which we are still counting mintable tokens on a per-round basis
- Next future reward period for which we need to checkpoint `totalStake` for transcoders on their earningsPools
### BondingManager
#### State
Following state variables are added to the **global state**.
| Parameter | Type | Description |
| -------- | -------- | -------- |
| currentRewardPeriodTotalActiveStake | `private uint256` | Total bonded stake for the current reward period
| nextRewardPeriodTotalActiveStake | `private uint256` | Total bonded stake for the next reward period |
*NOTE: Consider making variables private if they are not required for any 3rd party API*
Following state is added to the **`Delegator`** type
| Parameter | Type | Description |
| -------- | -------- | -------- |
| nextClaimRewardsStart | `uint256` | Start round for calculating cumulative rewards for the next claim earnings call |
#### API
##### currentRewardPeriodTotalActiveStake
```solidity
function currentRewardPeriodTotalActiveStake() public returns (uint256)
```
Returns the total active stake to be used in the rewards calculation for the current eligible reward period. Will be set to `nextRewardPeriodTotalActiveStake` by the `RoundsManager` when a new reward period starts.
##### nextRewardPeriodTotalActiveStake
```solidity
function nextRewardPeriodTotalActiveStake() public returns (uint256)
```
Returns the total active stake to be used in the rewards calculation for the next reward period.
##### setCurrentRewardPeriodTotalActiveStake
```solidity
function setCurrentRewardPeriodTotalActiveStake() external onlyRoundsManager
```
Sets the `currentRewardPeriodTotalActiveStake` equal to `nextRewardPeriodTotalActiveStake`.
Only callable by the `RoundsManager`
##### bondWithHint (implementation change)
- If a delegator stakes from unstaked
Set `delegator.startRewardPeriod` to `nextRewardPeriodStart`.
To avoid a division by zero error in case the new delegate doesn't call reward for the current reward period we should also set the cumulative reward factor from the `earningsPool` for `previousRewardPeriodStart` on the `earningsPool` for `nextRewardPeriodStart`.
- If a delegator adds stake
Claim earnings - What happens when earnings are claimed before reward call ?
Add the stake amount to `earningsPool.totalStake` for `nextRewardPeriodStart`, if this value is zero (no staking activity since `currentRewardPeriodStart`) start from `earningsPool.totalStake` for `currentRewardPeriodStart`.
- If a delegator switches delegate it will only earn rewards for the new delegate starting in the next reward period. This is required to prevent a scenario whereby a delegate could otherwise earn rewards from two delegates for a single reward period.
Imagine the following scenario:
1. delegator is staked to delegate_A
2. delegate_A calls reward for reward period with endround `N` in round `N+1`
3. in the same round delegator switches stake to delegate_B who hasn't called reward for reward period with endround `N` yet
- Earnings are claimed
- Stake is switched to delegate_B
- delegator adopts CRF for delegate_B for the delegators `lastClaimRound` which hasn't been updated yet for reward period with endround `N`
4. delegate_B calls reward
- CRF for reward period with end round `N` increases to account for additional rewards
5. delegator waits for new round to start since it can't claim earnings for the same round twice
6. delegator claims earnings in round `N+2`.
For both earnings calculations a cumulative reward factor for the reward period with end round `N` was used.
To solve this we introduce a new state variable on the `Delegator` type, `startRewardPeriod`, which indicates the starting `earningsPoolForRound` to use when a delegator claims earnings.
If a delegator switches delegates it will claim its rewards up until the `previousRewardPeriodStart` round. To prevent a delegator to claim for this period twice we can set `delegator.startRewardPeriod` to `nextRewardPeriodStart`.
Add the stake amount to `earningsPool.totalStake` for `nextRewardPeriodStart`, if this value is zero (no staking activity since `currentRewardPeriodStart`) start from `earningsPool.totalStake` for `currentRewardPeriodStart`.
To avoid a division by zero error in case the new delegate doesn't call reward for the current reward period we should also set the cumulative reward factor from the `earningsPool` for `previousRewardPeriodStart` on the `earningsPool` for `nextRewardPeriodStart`
##### UnbondWithHint
Subtract the unstake amount `earningsPool.totalStake` for `nextRewardPeriodStart`, if this value is zero (no staking activity since `currentRewardPeriodStart`) start from `earningsPool.totalStake` for `currentRewardPeriodStart`.
##### rebondFromUnbonded
Since a delegator can rebond to a different delegate from a completely unbonded state (while still in the unbonding period) the same exploit exists here as was described in `bondWithHint` but the same solution applies.
##### reward (implementation change)
1. Check that caller didn't already claim rewards for the eligible `rewardPeriod`
Reward period eligble for reward:
```
{
previousRewardPeriodStart
..
nextRewardPeriodStart - 1
}
```
```solidity
require(
transcoder.lastRewardRound < roundsmanager().previousRewardPeriodStart(),
"Already called reward for the current reward period"
);
```
2. Check if caller is/was an active transcoder during the eligible `rewardPeriod`, revert if this is not the case.
```solidity
require(
transcoder.activationRound <= roundsManager().previousRewardPeriodStart() && transcoder.deactivationRound >= roundsManager().currentRewardPeriodStart(),
"transcoder inactive during reward period"
);`
```
3. Calculate the amount of rewards to be minted for `{startRound..endRound}`
$r = {currentMintableTokens}\times \frac{totalStake_{delegate}}{currentRewardPeriodTotalActiveStake}$
where `totalPenaltyFromUnstake` is the total amount of rewards that need to be discounted from the reward calculation due to unstaking activity happening for the `delegate`.
5. Mint `rewardTokens` and update the minted tokens for the current eligible reward period
```solidity
uint256 currentMintedtokens = inflationManager().mintedInRewardPeriod() + rewardAmount;
require(
currentMintedTokens <= inflationManager().tokensForRewardPeriod(),
"minted tokens cannot exceed mintable tokens"
);
minter().createReward(rewardTokens);
inflationManager().setMintedInRewardPeriod(currentMintedTokens);
```
6. call `updateTranscoderWithRewards`
```solidity
updateTranscoderWithRewards(
msg.sender,
rewardTokens,
currentRound,
_newPosPrev,
_newPosNext
);
```
### RoundsManager
#### State
Following state variables are added to the `RoundsManager`
| Parameter | Type | Description |
| -------- | -------- | -------- |
| rewardPeriodLength | `uint256` | The number of rounds in a reward period, the initial value is 7|
| previousRewardPeriodStart | `uint256` | The end round of the previous reward period |
| currentRewardPeriodStart | `uint256` | The end round of the current reward period |
| nextRewardPeriodStart | `uint256` | The end round of the next reward period |
#### API
##### setRewardPeriodlength (new)
```solidity
function setRewardPeriodlength(uint256 _rewardPeriodLength) external onlyControllerOwner
```
Set the number of rounds in a reward period. The changes goes into effect starting from the reward period after the next one.
`_rewardPeriodLength` has to be greater or equal than `1` round.
Only callable by the `owner` of `Controller`.
##### initializeRound (implementation change)
The function signature will remain the same but some of the logic external contract calls that are part of this function will change
- If the current reward period ends
- set `previousRewardPeriodEnd` to `currentRewardPeriodEnd`
- set `currentRewardPeriodEnd` to `nextRewardPeriodEnd`
- set `nextRewardPeriodEnd` to `currentRound + rewardPeriodLength`
- set `InflationManager.currentMintableTokens` to `InflationManager.nextMintableTokens`
- reset `nextMintableTokens` on the `InflationManager` by calling `InflationManager.setNextMintableTokens(0)`
- Set `BondingManager.currentRewardPeriodTotalStake` to `BondingManager.nextRewardPeriodTotalStake`
- Set `BondingManager.nextRewardPeriodTotalStake` to the current `BondingManager.totalActiveStake`
- calculate amount of `rewardTokens` for this round, add it to `InflationManager.nextMintableTokens()` and set the result using `InflationManager.setNextMintableTokens(totalRewardTokens)`
### Go-Livepeer
In `go-livepeer` the `rewardService` needs to be updated to not call reward every round, but every reward period instead.
## Specification Rationale
- An initial value of 7 is selected for rewardPeriodLength because it roughtly corresponds to a week which seems to be a a unit of time that is easy to reason about while also providing a sizeable reduction in the effective per round transaction cost for calling reward.
- While this specification is slightly more stateful than the current implemented solution, it will still result in a significant gas cost reduction.
- Transcoders that were active during the current `rewardPeriod` but are not active during the last round of said period (due to being moved outside of the active transcoder set) should still be eligible to claim their rewards.
- Rewards should be calculated accurately for all potential stake updates a transcoder received during a `rewardPeriod`. This requires recursively calculating the network ownership and relative owed rewards for each round during the `rewardPeriod`. A transcoder should not be able to game reward calculation by increasing its stake for the last round of a reward period.
- Transcoders are given the window `rewardPeriodLength`to claim their rewards from the previous `rewardPeriod`. This offers greater flexibility for transcoders. Transcoders who call reward should be wary that this affects rewards calculation for the subsequent period however, as rewards only count towards active stake once `reward()` has been called.
- The minter is now stateless and only responsible for holding and transferring funds. The current structure would require less frequent upgrades for this contract, which puts user funds at 'ease'.
Remove discounter - unfair distirbution of risk is acceptable
delegationCooldown - prevent ability to claim double reward for a single period
is there an alternative to delegationCooldown ?
Set lastRewardRound on a new O to `roundsManager`.currentRewardPeriodEnd() so tha
Google Drive
Gist
Clipboard
Sign in with Wallet
