feat: keeper reward for reservoir drip through token issuance

Author: pcarranzav

contracts/l2/reservoir/L2Reservoir.sol

@@ -15,7 +15,7 @@ import "./L2ReservoirStorage.sol";
  * It receives tokens for rewards from L1, and provides functions to compute accumulated and new
  * total rewards at a particular block number.
  */
-contract L2Reservoir is L2ReservoirV1Storage, Reservoir, IL2Reservoir {
+contract L2Reservoir is L2ReservoirV2Storage, Reservoir, IL2Reservoir {
     using SafeMath for uint256;
 
     event DripReceived(uint256 _normalizedTokenSupply);
@@ -80,14 +80,20 @@ contract L2Reservoir is L2ReservoirV1Storage, Reservoir, IL2Reservoir {
      * updates the normalizedTokenSupplyCache and issuanceRate,
      * and snapshots the accumulated rewards. If issuanceRate changes,
      * it also triggers a snapshot of rewards per signal on the RewardsManager.
+     * A keeper reward will be sent to the keeper that dripped on L1, and part of it
+     * to whoever redeemed the current retryable ticket (tx.origin)
      * @param _normalizedTokenSupply Snapshot of total GRT supply multiplied by L2 rewards fraction
      * @param _issuanceRate Rewards issuance rate, using fixed point at 1e18, and including a +1
      * @param _nonce Incrementing nonce to ensure messages are received in order
+     * @param _keeperReward Keeper reward to distribute between keeper that called drip and keeper that redeemed  the retryable tx
+     * @param _l1Keeper Address of the keeper that called drip in L1
      */
     function receiveDrip(
         uint256 _normalizedTokenSupply,
         uint256 _issuanceRate,
-        uint256 _nonce
+        uint256 _nonce,
+        uint256 _keeperReward,
+        address _l1Keeper
     ) external override onlyL2Gateway {
         require(_nonce == nextDripNonce, "INVALID_NONCE");
         nextDripNonce = nextDripNonce.add(1);
@@ -100,6 +106,11 @@ contract L2Reservoir is L2ReservoirV1Storage, Reservoir, IL2Reservoir {
             snapshotAccumulatedRewards();
         }
         normalizedTokenSupplyCache = _normalizedTokenSupply;
+        uint256 _l2KeeperReward = _keeperReward.mul(l2KeeperRewardFraction).div(TOKEN_DECIMALS);
+        IGraphToken grt = graphToken();
+        // solhint-disable-next-line avoid-tx-origin
+        grt.transfer(tx.origin, _l2KeeperReward);
+        grt.transfer(_l1Keeper, _keeperReward.sub(_l2KeeperReward));
         emit DripReceived(normalizedTokenSupplyCache);
     }
 

contracts/l2/reservoir/L2ReservoirStorage.sol

@@ -11,3 +11,8 @@ contract L2ReservoirV1Storage {
     // Expected nonce value for the next drip hook
     uint256 public nextDripNonce;
 }
+
+contract L2ReservoirV2Storage is L2ReservoirV1Storage {
+    // Fraction of the keeper reward to send to the retryable tx redeemer in L2 (fixed point 1e18)
+    uint256 public l2KeeperRewardFraction;
+}

contracts/reservoir/IReservoir.sol

@@ -49,10 +49,14 @@ interface IL2Reservoir is IReservoir {
      * @param _normalizedTokenSupply Snapshot of total GRT supply multiplied by L2 rewards fraction
      * @param _issuanceRate Rewards issuance rate, using fixed point at 1e18, and including a +1
      * @param _nonce Incrementing nonce to ensure messages are received in order
+     * @param _keeperReward Keeper reward to distribute between keeper that called drip and keeper that redeemed  the retryable tx
+     * @param _l1Keeper Address of the keeper that called drip in L1
      */
     function receiveDrip(
         uint256 _normalizedTokenSupply,
         uint256 _issuanceRate,
-        uint256 _nonce
+        uint256 _nonce,
+        uint256 _keeperReward,
+        address _l1Keeper
     ) external;
 }

contracts/reservoir/L1Reservoir.sol

@@ -17,7 +17,7 @@ import "./L1ReservoirStorage.sol";
  * It provides a function to periodically drip rewards, and functions to compute accumulated and new
  * total rewards at a particular block number.
  */
-contract L1Reservoir is L1ReservoirV1Storage, Reservoir {
+contract L1Reservoir is L1ReservoirV2Storage, Reservoir {
     using SafeMath for uint256;
 
     // Emitted when the initial supply snapshot is taken after contract deployment
@@ -38,6 +38,10 @@ contract L1Reservoir is L1ReservoirV1Storage, Reservoir {
     event RewardsDripped(uint256 _totalMinted, uint256 _sentToL2, uint256 _nextDeadline);
     // Emitted when the address for the L2Reservoir is updated
     event L2ReservoirAddressUpdated(address _l2ReservoirAddress);
+    // Emitted when drip reward per block is updated
+    event DripRewardPerBlockUpdated(uint256 _dripRewardPerBlock);
+    // Emitted when minDripInterval is updated
+    event MinDripIntervalUpdated(uint256 _minDripInterval);
 
     /**
      * @dev Initialize this contract.
@@ -90,6 +94,26 @@ contract L1Reservoir is L1ReservoirV1Storage, Reservoir {
         emit L2RewardsFractionStaged(_l2RewardsFraction);
     }
 
+    /**
+     * @dev Sets the drip reward per block
+     * This is the reward in GRT provided to the keeper that calls drip()
+     * @param _dripRewardPerBlock GRT accrued for each block after the threshold
+     */
+    function setDripRewardPerBlock(uint256 _dripRewardPerBlock) external onlyGovernor {
+        dripRewardPerBlock = _dripRewardPerBlock;
+        emit DripRewardPerBlockUpdated(_dripRewardPerBlock);
+    }
+
+    /**
+     * @dev Sets the minimum drip interval
+     * This is the minimum number of blocks between two successful drips
+     * @param _minDripInterval Minimum number of blocks since last drip for drip to be allowed
+     */
+    function setMinDripInterval(uint256 _minDripInterval) external onlyGovernor {
+        minDripInterval = _minDripInterval;
+        emit MinDripIntervalUpdated(_minDripInterval);
+    }
+
     /**
      * @dev Sets the L2 Reservoir address
      * This is the address on L2 to which we send tokens for rewards.
@@ -128,16 +152,23 @@ contract L1Reservoir is L1ReservoirV1Storage, Reservoir {
      * @param l2MaxGas Max gas for the L2 retryable ticket, only needed if L2RewardsFraction is > 0
      * @param l2GasPriceBid Gas price for the L2 retryable ticket, only needed if L2RewardsFraction is > 0
      * @param l2MaxSubmissionCost Max submission price for the L2 retryable ticket, only needed if L2RewardsFraction is > 0
+     * @param keeperRewardBeneficiary Address to which to credit keeper reward (will be redeemed in L2 if l2RewardsFraction is nonzero)
      */
     function drip(
         uint256 l2MaxGas,
         uint256 l2GasPriceBid,
-        uint256 l2MaxSubmissionCost
+        uint256 l2MaxSubmissionCost,
+        address keeperRewardBeneficiary
     ) external payable notPaused {
+        require(block.number > lastRewardsUpdateBlock + minDripInterval, "WAIT_FOR_MIN_INTERVAL");
+
         uint256 mintedRewardsTotal = getNewGlobalRewards(rewardsMintedUntilBlock);
         uint256 mintedRewardsActual = getNewGlobalRewards(block.number);
         // eps = (signed int) mintedRewardsTotal - mintedRewardsActual
 
+        uint256 keeperReward = dripRewardPerBlock.mul(
+            block.number.sub(lastRewardsUpdateBlock).sub(minDripInterval)
+        );
         if (nextIssuanceRate != issuanceRate) {
             rewardsManager().updateAccRewardsPerSignal();
             snapshotAccumulatedRewards(mintedRewardsActual); // This updates lastRewardsUpdateBlock
@@ -150,13 +181,15 @@ contract L1Reservoir is L1ReservoirV1Storage, Reservoir {
         rewardsMintedUntilBlock = block.number.add(dripInterval);
         // n = deltaR(t1, t0)
         uint256 newRewardsToDistribute = getNewGlobalRewards(rewardsMintedUntilBlock);
-        // N = n - eps
-        uint256 tokensToMint = newRewardsToDistribute.add(mintedRewardsActual).sub(
-            mintedRewardsTotal
-        );
+        // N = n - eps ( + reward)
+        uint256 tokensToMint = newRewardsToDistribute
+            .add(mintedRewardsActual)
+            .add(keeperReward)
+            .sub(mintedRewardsTotal);
 
+        IGraphToken grt = graphToken();
         if (tokensToMint > 0) {
-            graphToken().mint(address(this), tokensToMint);
+            grt.mint(address(this), tokensToMint);
         }
 
         uint256 tokensToSendToL2 = 0;
@@ -187,20 +220,26 @@ contract L1Reservoir is L1ReservoirV1Storage, Reservoir {
                 tokensToSendToL2,
                 l2MaxGas,
                 l2GasPriceBid,
-                l2MaxSubmissionCost
+                l2MaxSubmissionCost,
+                keeperReward,
+                keeperRewardBeneficiary
             );
         } else if (l2RewardsFraction > 0) {
             tokensToSendToL2 = tokensToMint.mul(l2RewardsFraction).div(TOKEN_DECIMALS);
             _sendNewTokensAndStateToL2(
                 tokensToSendToL2,
                 l2MaxGas,
                 l2GasPriceBid,
-                l2MaxSubmissionCost
+                l2MaxSubmissionCost,
+                keeperReward,
+                keeperRewardBeneficiary
             );
         } else {
             // Avoid locking funds in this contract if we don't need to
             // send a message to L2.
             require(msg.value == 0, "No eth value needed");
+            // If we don't send rewards to L2, pay the keeper reward in L1
+            grt.transfer(keeperRewardBeneficiary, keeperReward);
         }
         emit RewardsDripped(tokensToMint, tokensToSendToL2, rewardsMintedUntilBlock);
     }
@@ -234,14 +273,18 @@ contract L1Reservoir is L1ReservoirV1Storage, Reservoir {
         uint256 nTokens,
         uint256 maxGas,
         uint256 gasPriceBid,
-        uint256 maxSubmissionCost
+        uint256 maxSubmissionCost,
+        uint256 keeperReward,
+        address keeper
     ) internal {
         uint256 normalizedSupply = l2RewardsFraction.mul(tokenSupplyCache).div(TOKEN_DECIMALS);
         bytes memory extraData = abi.encodeWithSelector(
             IL2Reservoir.receiveDrip.selector,
             normalizedSupply,
             issuanceRate,
-            nextDripNonce
+            nextDripNonce,
+            keeperReward,
+            keeper
         );
         nextDripNonce = nextDripNonce.add(1);
         bytes memory data = abi.encode(maxSubmissionCost, extraData);

contracts/reservoir/L1ReservoirStorage.sol

@@ -23,3 +23,10 @@ contract L1ReservoirV1Storage {
     // Auto-incrementing nonce that will be used when sending rewards to L2, to ensure ordering
     uint256 public nextDripNonce;
 }
+
+contract L1ReservoirV2Storage is L1ReservoirV1Storage {
+    // Minimum number of blocks since last drip for a new drip to be allowed
+    uint256 public minDripInterval;
+    // Drip reward in GRT for each block since lastRewardsUpdateBlock + dripRewardThreshold
+    uint256 public dripRewardPerBlock;
+}

test/l2/l2Reservoir.test.ts

@@ -160,7 +160,13 @@ describe('L2Reservoir', () => {
     it('rejects the call when not called by the gateway', async function () {
       const tx = l2Reservoir
         .connect(governor.signer)
-        .receiveDrip(dripNormalizedSupply, dripIssuanceRate, toBN('0'))
+        .receiveDrip(
+          dripNormalizedSupply,
+          dripIssuanceRate,
+          toBN('0'),
+          toBN('0'),
+          testAccount1.address,
+        )
       await expect(tx).revertedWith('ONLY_GATEWAY')
     })
     it('rejects the call when received out of order', async function () {
@@ -169,6 +175,8 @@ describe('L2Reservoir', () => {
         dripNormalizedSupply,
         dripIssuanceRate,
         toBN('0'),
+        toBN('0'),
+        testAccount1.address,
       )
       const tx = await validGatewayFinalizeTransfer(receiveDripTx.data)
       dripBlock = await latestBlock()
@@ -181,6 +189,8 @@ describe('L2Reservoir', () => {
         dripNormalizedSupply.add(1),
         dripIssuanceRate.add(1),
         toBN('2'),
+        toBN('0'),
+        testAccount1.address,
       )
       const tx2 = gatewayFinalizeTransfer(receiveDripTx.data)
       dripBlock = await latestBlock()
@@ -192,6 +202,8 @@ describe('L2Reservoir', () => {
         dripNormalizedSupply,
         dripIssuanceRate,
         toBN('0'),
+        toBN('0'),
+        testAccount1.address,
       )
       const tx = await validGatewayFinalizeTransfer(receiveDripTx.data)
       dripBlock = await latestBlock()
@@ -205,6 +217,8 @@ describe('L2Reservoir', () => {
         dripNormalizedSupply,
         dripIssuanceRate,
         toBN('0'),
+        toBN('0'),
+        testAccount1.address,
       )
       let tx = await validGatewayFinalizeTransfer(receiveDripTx.data)
       dripBlock = await latestBlock()
@@ -216,6 +230,8 @@ describe('L2Reservoir', () => {
         dripNormalizedSupply.add(1),
         dripIssuanceRate.add(1),
         toBN('1'),
+        toBN('0'),
+        testAccount1.address,
       )
       tx = await gatewayFinalizeTransfer(receiveDripTx.data)
       dripBlock = await latestBlock()
@@ -232,6 +248,8 @@ describe('L2Reservoir', () => {
         dripNormalizedSupply,
         dripIssuanceRate,
         toBN('0'),
+        toBN('0'),
+        testAccount1.address,
       )
       let tx = await validGatewayFinalizeTransfer(receiveDripTx.data)
       dripBlock = await latestBlock()
@@ -243,6 +261,8 @@ describe('L2Reservoir', () => {
         dripNormalizedSupply.add(1),
         dripIssuanceRate,
         toBN('1'),
+        toBN('0'),
+        testAccount1.address,
       )
       tx = await gatewayFinalizeTransfer(receiveDripTx.data)
       dripBlock = await latestBlock()
@@ -259,6 +279,8 @@ describe('L2Reservoir', () => {
         dripNormalizedSupply,
         dripIssuanceRate,
         toBN('0'),
+        toBN('0'),
+        testAccount1.address,
       )
       let tx = await validGatewayFinalizeTransfer(receiveDripTx.data)
       dripBlock = await latestBlock()
@@ -271,6 +293,8 @@ describe('L2Reservoir', () => {
         dripNormalizedSupply.add(1),
         dripIssuanceRate,
         toBN('2'),
+        toBN('0'),
+        testAccount1.address,
       )
       tx = await gatewayFinalizeTransfer(receiveDripTx.data)
       dripBlock = await latestBlock()
@@ -291,6 +315,8 @@ describe('L2Reservoir', () => {
         dripNormalizedSupply,
         ISSUANCE_RATE_PER_BLOCK,
         toBN('0'),
+        toBN('0'),
+        testAccount1.address,
       )
       await validGatewayFinalizeTransfer(receiveDripTx.data)
       dripBlock = await latestBlock()