L2: drip rewards from L1, introducing Reservoirs

cli/commands/migrate.ts

@@ -36,6 +36,7 @@ let allContracts = [
   'AllocationExchange',
   'L1GraphTokenGateway',
   'BridgeEscrow',
+  'L1Reservoir',
 ]
 
 const l2Contracts = [
@@ -55,6 +56,7 @@ const l2Contracts = [
   'DisputeManager',
   'AllocationExchange',
   'L2GraphTokenGateway',
+  'L2Reservoir',
 ]
 
 export const migrate = async (

cli/contracts.ts

@@ -26,6 +26,8 @@ import { L1GraphTokenGateway } from '../build/types/L1GraphTokenGateway'
 import { L2GraphToken } from '../build/types/L2GraphToken'
 import { L2GraphTokenGateway } from '../build/types/L2GraphTokenGateway'
 import { BridgeEscrow } from '../build/types/BridgeEscrow'
+import { L1Reservoir } from '../build/types/L1Reservoir'
+import { L2Reservoir } from '../build/types/L2Reservoir'
 
 export interface NetworkContracts {
   EpochManager: EpochManager
@@ -49,6 +51,8 @@ export interface NetworkContracts {
   BridgeEscrow: BridgeEscrow
   L2GraphToken: L2GraphToken
   L2GraphTokenGateway: L2GraphTokenGateway
+  L1Reservoir: L1Reservoir
+  L2Reservoir: L2Reservoir
 }
 
 export const loadAddressBookContract = (

config/graph.arbitrum-goerli.yml

@@ -33,6 +33,9 @@ contracts:
       - fn: "setContractProxy"
         id: "0xd362cac9cb75c10d67bcc0b7eeb0b1ef48bb5420b556c092d4fd7f758816fcf0" # keccak256('GraphTokenGateway')
         contractAddress: "${{L2GraphTokenGateway.address}}"
+      - fn: "setContractProxy"
+        id: "0x96ba401694892957e25e29c7a1e4171ae9945b5ee36339de79b199a530436e9e" # keccak256('Reservoir')
+        contractAddress: "${{L2Reservoir.address}}"
       - fn: "setPauseGuardian"
         pauseGuardian: *pauseGuardian
       - fn: "transferOwnership"
@@ -149,3 +152,10 @@ contracts:
       - fn: "syncAllContracts"
       - fn: "setPauseGuardian"
         pauseGuardian: *pauseGuardian
+  L2Reservoir:
+    proxy: true
+    init:
+      controller: "${{Controller.address}}"
+    calls:
+      - fn: "approveRewardsManager"
+      - fn: "syncAllContracts"

config/graph.arbitrum-localhost.yml

@@ -33,6 +33,9 @@ contracts:
       - fn: "setContractProxy"
         id: "0xd362cac9cb75c10d67bcc0b7eeb0b1ef48bb5420b556c092d4fd7f758816fcf0" # keccak256('GraphTokenGateway')
         contractAddress: "${{L2GraphTokenGateway.address}}"
+      - fn: "setContractProxy"
+        id: "0x96ba401694892957e25e29c7a1e4171ae9945b5ee36339de79b199a530436e9e" # keccak256('Reservoir')
+        contractAddress: "${{L2Reservoir.address}}"
       - fn: "setPauseGuardian"
         pauseGuardian: *pauseGuardian
       - fn: "transferOwnership"
@@ -149,3 +152,10 @@ contracts:
       - fn: "syncAllContracts"
       - fn: "setPauseGuardian"
         pauseGuardian: *pauseGuardian
+  L2Reservoir:
+    proxy: true
+    init:
+      controller: "${{Controller.address}}"
+    calls:
+      - fn: "approveRewardsManager"
+      - fn: "syncAllContracts"

config/graph.arbitrum-one.yml

@@ -33,6 +33,9 @@ contracts:
       - fn: "setContractProxy"
         id: "0xd362cac9cb75c10d67bcc0b7eeb0b1ef48bb5420b556c092d4fd7f758816fcf0" # keccak256('GraphTokenGateway')
         contractAddress: "${{L2GraphTokenGateway.address}}"
+      - fn: "setContractProxy"
+        id: "0x96ba401694892957e25e29c7a1e4171ae9945b5ee36339de79b199a530436e9e" # keccak256('Reservoir')
+        contractAddress: "${{L2Reservoir.address}}"
       - fn: "setPauseGuardian"
         pauseGuardian: *pauseGuardian
       - fn: "transferOwnership"
@@ -149,3 +152,10 @@ contracts:
       - fn: "syncAllContracts"
       - fn: "setPauseGuardian"
         pauseGuardian: *pauseGuardian
+  L2Reservoir:
+    proxy: true
+    init:
+      controller: "${{Controller.address}}"
+    calls:
+      - fn: "approveRewardsManager"
+      - fn: "syncAllContracts"

config/graph.goerli.yml

@@ -33,6 +33,9 @@ contracts:
       - fn: "setContractProxy"
         id: "0xd362cac9cb75c10d67bcc0b7eeb0b1ef48bb5420b556c092d4fd7f758816fcf0" # keccak256('GraphTokenGateway')
         contractAddress: "${{L1GraphTokenGateway.address}}"
+      - fn: "setContractProxy"
+        id: "0x96ba401694892957e25e29c7a1e4171ae9945b5ee36339de79b199a530436e9e" # keccak256('Reservoir')
+        contractAddress: "${{L1Reservoir.address}}"
       - fn: "setPauseGuardian"
         pauseGuardian: *pauseGuardian
       - fn: "transferOwnership"
@@ -57,7 +60,7 @@ contracts:
       initialSupply: "10000000000000000000000000000" # in wei
     calls:
       - fn: "addMinter"
-        minter: "${{RewardsManager.address}}"
+        minter: "${{L1Reservoir.address}}"
       - fn: "renounceMinter"
       - fn: "transferOwnership"
         owner: *governor
@@ -131,8 +134,6 @@ contracts:
     init:
       controller: "${{Controller.address}}"
     calls:
-      - fn: "setIssuanceRate"
-        issuanceRate: "1000000012184945188" # per block increase of total supply, blocks in a year = 365*60*60*24/13
       - fn: "setSubgraphAvailabilityOracle"
         subgraphAvailabilityOracle: *availabilityOracle
       - fn: "syncAllContracts"
@@ -158,3 +159,13 @@ contracts:
       controller: "${{Controller.address}}"
     calls:
       - fn: "syncAllContracts"
+  L1Reservoir:
+    proxy: true
+    init:
+      controller: "${{Controller.address}}"
+      dripInterval: 50400
+    calls:
+      - fn: "approveRewardsManager"
+      - fn: "initialSnapshot"
+        pendingRewards: "0"
+      - fn: "syncAllContracts"

config/graph.localhost.yml

@@ -33,6 +33,9 @@ contracts:
       - fn: "setContractProxy"
         id: "0xd362cac9cb75c10d67bcc0b7eeb0b1ef48bb5420b556c092d4fd7f758816fcf0" # keccak256('GraphTokenGateway')
         contractAddress: "${{L1GraphTokenGateway.address}}"
+      - fn: "setContractProxy"
+        id: "0x96ba401694892957e25e29c7a1e4171ae9945b5ee36339de79b199a530436e9e" # keccak256('Reservoir')
+        contractAddress: "${{L1Reservoir.address}}"
       - fn: "setPauseGuardian"
         pauseGuardian: *pauseGuardian
       - fn: "transferOwnership"
@@ -57,7 +60,7 @@ contracts:
       initialSupply: "10000000000000000000000000000" # in wei
     calls:
       - fn: "addMinter"
-        minter: "${{RewardsManager.address}}"
+        minter: "${{L1Reservoir.address}}"
       - fn: "renounceMinter"
       - fn: "transferOwnership"
         owner: *governor
@@ -131,8 +134,6 @@ contracts:
     init:
       controller: "${{Controller.address}}"
     calls:
-      - fn: "setIssuanceRate"
-        issuanceRate: "1000000012184945188" # per block increase of total supply, blocks in a year = 365*60*60*24/13
       - fn: "setSubgraphAvailabilityOracle"
         subgraphAvailabilityOracle: *availabilityOracle
       - fn: "syncAllContracts"
@@ -158,3 +159,13 @@ contracts:
       controller: "${{Controller.address}}"
     calls:
       - fn: "syncAllContracts"
+  L1Reservoir:
+    proxy: true
+    init:
+      controller: "${{Controller.address}}"
+      dripInterval: 50400
+    calls:
+      - fn: "approveRewardsManager"
+      - fn: "initialSnapshot"
+        pendingRewards: "0"
+      - fn: "syncAllContracts"

config/graph.mainnet.yml

@@ -33,6 +33,9 @@ contracts:
       - fn: "setContractProxy"
         id: "0xd362cac9cb75c10d67bcc0b7eeb0b1ef48bb5420b556c092d4fd7f758816fcf0" # keccak256('GraphTokenGateway')
         contractAddress: "${{L1GraphTokenGateway.address}}"
+      - fn: "setContractProxy"
+        id: "0x96ba401694892957e25e29c7a1e4171ae9945b5ee36339de79b199a530436e9e" # keccak256('Reservoir')
+        contractAddress: "${{L1Reservoir.address}}"
       - fn: "setPauseGuardian"
         pauseGuardian: *pauseGuardian
       - fn: "transferOwnership"
@@ -57,7 +60,7 @@ contracts:
       initialSupply: "10000000000000000000000000000" # in wei
     calls:
       - fn: "addMinter"
-        minter: "${{RewardsManager.address}}"
+        minter: "${{L1Reservoir.address}}"
       - fn: "renounceMinter"
       - fn: "transferOwnership"
         owner: *governor
@@ -131,8 +134,6 @@ contracts:
     init:
       controller: "${{Controller.address}}"
     calls:
-      - fn: "setIssuanceRate"
-        issuanceRate: "1000000012184945188" # per block increase of total supply, blocks in a year = 365*60*60*24/13
       - fn: "setSubgraphAvailabilityOracle"
         subgraphAvailabilityOracle: *availabilityOracle
       - fn: "syncAllContracts"
@@ -158,3 +159,13 @@ contracts:
       controller: "${{Controller.address}}"
     calls:
       - fn: "syncAllContracts"
+  L1Reservoir:
+    proxy: true
+    init:
+      controller: "${{Controller.address}}"
+      dripInterval: 50400
+    calls:
+      - fn: "approveRewardsManager"
+      - fn: "initialSnapshot"
+        pendingRewards: "0"
+      - fn: "syncAllContracts"

contracts/governance/Managed.sol

@@ -10,6 +10,7 @@ import "../rewards/IRewardsManager.sol";
 import "../staking/IStaking.sol";
 import "../token/IGraphToken.sol";
 import "../arbitrum/ITokenGateway.sol";
+import "../reservoir/IReservoir.sol";
 
 /**
  * @title Graph Managed contract
@@ -154,6 +155,14 @@ contract Managed {
         return ITokenGateway(_resolveContract(keccak256("GraphTokenGateway")));
     }
 
+    /**
+     * @dev Return Reservoir (L1 or L2) interface.
+     * @return Reservoir contract registered with Controller
+     */
+    function reservoir() internal view returns (IReservoir) {
+        return IReservoir(_resolveContract(keccak256("Reservoir")));
+    }
+
     /**
      * @dev Resolve a contract address from the cache or the Controller if not found.
      * @return Address of the contract
@@ -192,5 +201,6 @@ contract Managed {
         _syncContract("Staking");
         _syncContract("GraphToken");
         _syncContract("GraphTokenGateway");
+        _syncContract("Reservoir");
     }
 }

contracts/l2/reservoir/IL2Reservoir.sol

@@ -0,0 +1,40 @@
+// SPDX-License-Identifier: GPL-2.0-or-later
+
+pragma solidity ^0.7.6;
+
+import { IReservoir } from "../../reservoir/IReservoir.sol";
+
+/**
+ * @title Interface for the L2 Rewards Reservoir
+ * @dev This exposes a specific function for the L2Reservoir that is called
+ * as a callhook from L1 to L2, so that state can be updated when dripped rewards
+ * are bridged between layers.
+ */
+interface IL2Reservoir is IReservoir {
+    /**
+     * @dev Receive dripped tokens from L1.
+     * This function can only be called by the gateway, as it is
+     * meant to be a callhook when receiving tokens from L1. It
+     * updates the issuanceBase and issuanceRate,
+     * and snapshots the accumulated rewards. If issuanceRate changes,
+     * it also triggers a snapshot of rewards per signal on the RewardsManager.
+     * Note that the transaction might revert if it's received out-of-order,
+     * because it checks an incrementing nonce. If that is the case, the retryable ticket can be redeemed
+     * again once the ticket for previous drip has been redeemed.
+     * A keeper reward will be sent to the keeper that dripped on L1, and part of it
+     * to whoever redeemed the current retryable ticket (as reported by ArbRetryableTx.getCurrentRedeemer) if
+     * the ticket is not auto-redeemed.
+     * @param _issuanceBase Base value for token issuance (approximation for token supply times 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 _issuanceBase,
+        uint256 _issuanceRate,
+        uint256 _nonce,
+        uint256 _keeperReward,
+        address _l1Keeper
+    ) external;
+}