Op Farms

.env.example

@@ -0,0 +1,12 @@
+export FOUNDRY_SCRIPT_DEPS=deployed
+export FOUNDRY_EXPORTS_OVERWRITE_LATEST=true
+export L1="sepolia"
+export L2="base_sepolia"
+export MAINNET_RPC_URL=
+export BASE_RPC_URL=
+export SEPOLIA_RPC_URL=
+export BASE_SEPOLIA_RPC_URL=
+export L1_PRIVATE_KEY="0x$(cat /path/to/pkey1)"
+export L2_PRIVATE_KEY="0x$(cat /path/to/pkey2)"
+export ETHERSCAN_KEY=
+export BASESCAN_KEY=

.github/workflows/test.yml

@@ -0,0 +1,37 @@
+name: test
+
+on: [push, pull_request]
+
+env:
+  FOUNDRY_PROFILE: ci
+
+jobs:
+  check:
+    strategy:
+      fail-fast: true
+
+    name: Foundry project
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - name: Install Foundry
+        uses: foundry-rs/foundry-toolchain@v1
+        with:
+          version: nightly
+
+      - name: Run Forge build
+        run: |
+          forge --version
+          forge build --sizes
+        id: build
+
+      - name: Run Forge tests
+        run: |
+          forge test -vvv
+        id: test
+        env:
+          MAINNET_RPC_URL: ${{ secrets.MAINNET_RPC_URL }}
+          BASE_RPC_URL: ${{ secrets.BASE_RPC_URL }}

.gitignore

@@ -0,0 +1,14 @@
+# Compiler files
+cache/
+out/
+
+# Ignores development broadcast logs
+!/broadcast
+/broadcast/*/31337/
+/broadcast/**/dry-run/
+
+# Docs
+docs/
+
+# Dotenv file
+.env

.gitmodules

@@ -0,0 +1,10 @@
+[submodule "lib/dss-test"]
+	path = lib/dss-test
+	url = https://github.com/makerdao/dss-test
+[submodule "lib/endgame-toolkit"]
+	path = lib/endgame-toolkit
+	url = https://github.com/makerdao/endgame-toolkit
+[submodule "lib/op-token-bridge"]
+	path = lib/op-token-bridge
+	url = https://github.com/makerdao/op-token-bridge
+	branch = dev

README.md

@@ -1 +1,98 @@
-# op-farms
+# Op Farms
+
+## Overview
+
+This repository implements a mechanism to distribute rewards vested in a [DssVest](https://github.com/makerdao/dss-vest) contract on L1 to users staking tokens in a [StakingRewards](https://github.com/makerdao/endgame-toolkit/blob/master/src/synthetix/StakingRewards.sol) farm on an OP stack L2. It uses the [Op Token Bridge](https://github.com/makerdao/op-token-bridge) to transfer the rewards from L1 to L2.
+
+## Contracts
+
+- `L1FarmProxy.sol` - Proxy to the farm on the L1 side. Receives the token reward (expected to come from a [`VestedRewardDistribution`](https://github.com/makerdao/endgame-toolkit/blob/master/src/VestedRewardsDistribution.sol) contract) and transfers it cross-chain to the `L2FarmProxy`. An instance of `L1FarmProxy` must be deployed for each supported pair of staking and rewards token.
+- `L2FarmProxy.sol` - Proxy to the farm on the L2 side. Receives the token reward (expected to be bridged from the `L1FarmProxy`) and forwards it to the [StakingRewards](https://github.com/makerdao/endgame-toolkit/blob/master/src/synthetix/StakingRewards.sol) farm where it gets distributed to stakers. An instance of `L2FarmProxy` must be deployed for each supported pair of staking and rewards token.
+
+### External dependencies
+
+- The L2 staking tokens and the L1 and L2 rewards tokens are not provided as part of this repository. It is assumed that only simple, regular ERC20 tokens will be used. In particular, the supported tokens are assumed to revert on failure (instead of returning false) and do not execute any hook on transfer.
+- [`DssVest`](https://github.com/makerdao/dss-vest) is used to vest the rewards token on L1.
+- [`VestedRewardDistribution`](https://github.com/makerdao/endgame-toolkit/blob/master/src/VestedRewardsDistribution.sol) is used to vest the rewards tokens from `DssVest`, transfer them to the `L1FarmProxy` and trigger the bridging of the tokens.
+- The [Op Token Bridge](https://github.com/makerdao/op-token-bridge) is used to bridge the tokens from L1 to L2. 
+- The [escrow contract](https://github.com/makerdao/op-token-bridge/blob/dev/src/Escrow.sol) is used by the Op Token Bridge to hold the bridged tokens on L1.
+- [`StakingRewards`](https://github.com/makerdao/endgame-toolkit/blob/master/src/synthetix/StakingRewards.sol) is used to distribute the bridged rewards to stakers on L2.
+- The [`L1GovernanceRelay`](https://github.com/makerdao/op-token-bridge/blob/dev/src/L1GovernanceRelay.sol) & [`L2GovernanceRelay`](https://github.com/makerdao/op-token-bridge/blob/dev/src/L2GovernanceRelay.sol) allow governance to exert admin control over the deployed L2 contracts.
+
+## Expected flow
+- Once the vested amount of rewards tokens exceeds `L1FarmProxy.rewardThreshold`, a keeper calls `VestedRewardDistribution.distribute()` to vest the rewards and have them bridged to L2.
+- Once the bridged amount of rewards tokens exceeds `L2FarmProxy.rewardThreshold`, anyone (e.g. a keeper or an L2 staker) can call `L2FarmProxy.forwardReward()` to distribute the rewards to the L2 farm.
+
+Note that `L1FarmProxy.rewardThreshold` should be sufficiently large to reduce the frequency of cross-chain transfers (thereby saving keepers gas). `L2FarmProxy.rewardThreshold` must also be sufficiently large to limit the reduction of the farm's rate of rewards distribution. Consider also choosing `L2FarmProxy.rewardThreshold <= L1FarmProxy.rewardThreshold` so that the bridged rewards can be promptly distributed to the farm. In the initialization library, these two variables are assigned the same value.
+
+Note that the L2 Farm's reward rate might not be perfectly constant, even if the `L1FarmProxy` and `L2FarmProxy` reward thresholds are set to the same value. With the cross-chain setup there are several ways that can lead to non-constant reward rates. Therefore the following should be taken into consideration:
+* The system configuration (durations and thresholds) should be chosen carefully to align the vesting rate with the farm's reward rate.
+* Keepers should monitor and call `VestedRewardsDistribution.distribute` on L1 and `L2FarmProxy.forwardReward` whenever their reward thresholds are reached.
+* L2 sequencer downtimes or other bridging delays can lead to delayed L2 distribution.
+* Failed reward token bridging transactions should be monitored and retried.
+
+## Deployment
+
+### Declare env variables
+
+Add the required env variables listed in `.env.example` to your `.env` file, and run `source .env`.
+
+Make sure to set the `L1` and `L2` env variables according to your desired deployment environment.
+
+Mainnet deployment:
+
+```
+L1=mainnet
+L2=base # in case of using Base as the L2
+```
+
+Testnet deployment:
+
+```
+L1=sepolia
+L2=base_sepolia # in case of using Base as the L2
+```
+
+### Deploy the farm L1 & L2 proxies
+
+The deployment assumes that the [op-token-bridge](https://github.com/makerdao/op-token-bridge) has already been deployed and was properly initialized.
+
+Fill in the addresses of the L2 staking token and L1 and L2 rewards tokens in `script/input/{chainId}/config.json` under the `"stakingToken"` and `"rewardsToken"` keys.
+
+Fill in the address of the mainnet DssVest contract in `script/input/1/config.json` under the `vest` key. It is assumed that the vesting contract was properly initialized. On testnet, a mock DssVest contract will automatically be deployed.
+
+Start by deploying the `L2FarmProxySpell` singleton.
+
+```
+forge script script/DeploySingletons.s.sol:DeploySingletons --slow --multi --broadcast --verify
+```
+
+Next, run the following command to deploy the L1 vested rewards distribution contract, the L2 farm and the L1 and L2 proxies:
+
+```
+forge script script/DeployProxy.s.sol:DeployProxy --slow --multi --broadcast --verify
+```
+
+### Initialize the farm L1 & L2 proxies
+
+On mainnet, the farm proxies should be initialized via the spell process.
+On testnet, the proxies initialization can be performed via the following command:
+
+```
+forge script script/Init.s.sol:Init --slow --multi --broadcast
+```
+
+### Run a test distribution
+
+Run the following command to distribute the vested funds to the L1 proxy.  
+We add a buffer to the gas estimation per Optimism's [recommendation](https://docs.optimism.io/builders/app-developers/bridging/messaging#for-l1-to-l2-transactions-1) for L1 => L2 transactions.
+
+```
+forge script script/Distribute.s.sol:Distribute --slow --multi --broadcast --gas-estimate-multiplier 120
+```
+
+Wait for the transaction to be relayed to L2, then run the following command to forward the bridged funds from the L2 proxy to the farm:
+
+```
+forge script script/Forward.s.sol:Forward --slow --multi --broadcast
+```

deploy/FarmProxyDeploy.sol

@@ -0,0 +1,50 @@
+// SPDX-FileCopyrightText: © 2024 Dai Foundation <www.daifoundation.org>
+// SPDX-License-Identifier: AGPL-3.0-or-later
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+pragma solidity >=0.8.0;
+
+import { ScriptTools } from "dss-test/ScriptTools.sol";
+
+import { L2FarmProxySpell } from "./L2FarmProxySpell.sol";
+import { L1FarmProxy } from "src/L1FarmProxy.sol";
+import { L2FarmProxy } from "src/L2FarmProxy.sol";
+
+library FarmProxyDeploy {
+    function deployL1Proxy(
+        address deployer,
+        address owner,
+        address rewardsToken,
+        address remoteToken,
+        address l2Proxy,
+        address l1Bridge
+    ) internal returns (address l1Proxy) {
+        l1Proxy = address(new L1FarmProxy(rewardsToken, remoteToken, l2Proxy, l1Bridge));
+        ScriptTools.switchOwner(l1Proxy, deployer, owner);
+    }
+
+    function deployL2Proxy(
+        address deployer,
+        address owner,
+        address farm
+    ) internal returns (address l2Proxy) {
+        l2Proxy = address(new L2FarmProxy(farm));
+        ScriptTools.switchOwner(l2Proxy, deployer, owner);
+    }
+
+    function deployL2ProxySpell() internal returns (address l2Spell) {
+        l2Spell = address(new L2FarmProxySpell());
+    }
+}

deploy/FarmProxyInit.sol

@@ -0,0 +1,131 @@
+// SPDX-FileCopyrightText: © 2024 Dai Foundation <www.daifoundation.org>
+// SPDX-License-Identifier: AGPL-3.0-or-later
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+pragma solidity >=0.8.0;
+
+import { DssInstance } from "dss-test/MCD.sol";
+import { L2FarmProxySpell } from "./L2FarmProxySpell.sol";
+
+interface DssVestLike {
+    function gem() external view returns (address);
+    function create(address _usr, uint256 _tot, uint256 _bgn, uint256 _tau, uint256 _eta, address _mgr) external returns (uint256 id);
+    function restrict(uint256 _id) external;
+}
+
+interface VestedRewardsDistributionLike {
+    function dssVest() external view returns (address);
+    function stakingRewards() external view returns (address);
+    function gem() external view returns (address);
+    function file(bytes32 what, uint256 data) external;
+}
+
+interface L1FarmProxyLike {
+    function rewardsToken() external view returns (address);
+    function remoteToken() external view returns (address);
+    function l2Proxy() external view returns (address);
+    function l1Bridge() external view returns (address);
+    function file(bytes32 what, uint256 data) external;
+}
+
+interface L1RelayLike {
+    function l2GovernanceRelay() external view returns (address);
+    function relay(address target, bytes calldata targetData, uint32 minGasLimit) external;
+}
+
+struct ProxiesConfig {
+    address vest;             // DssVest, assumed to have been fully init'ed for l1RewardsToken
+    uint256 vestTot;
+    uint256 vestBgn;
+    uint256 vestTau;
+    address vestedRewardsDistribution;
+    address l1RewardsToken;
+    address l2RewardsToken;
+    address l2StakingToken;
+    address l1Bridge;
+    uint32  minGasLimit;      // For filing in the L1 proxy
+    uint224 rewardThreshold;  // For the L1 and L2 proxies
+    address farm;             // The L2 farm
+    uint256 rewardsDuration;  // For the L2 farm
+    uint32  initMinGasLimit;  // For relaying of `init` L2 spell operation
+    bytes32 proxyChainlogKey; // Chainlog key for the L1 proxy
+    bytes32 distrChainlogKey; // Chainlog key for vestedRewardsDistribution
+}
+
+library FarmProxyInit {
+    function initProxies(
+        DssInstance memory   dss,
+        address              l1GovRelay,
+        address              l1Proxy_,
+        address              l2Proxy,
+        address              l2Spell,
+        ProxiesConfig memory cfg
+    ) internal {
+        L1FarmProxyLike l1Proxy = L1FarmProxyLike(l1Proxy_);
+        DssVestLike vest = DssVestLike(cfg.vest);
+        VestedRewardsDistributionLike distribution = VestedRewardsDistributionLike(cfg.vestedRewardsDistribution);
+
+        // sanity checks
+
+        require(vest.gem()                    == cfg.l1RewardsToken, "FarmProxyInit/vest-gem-mismatch");
+        require(distribution.gem()            == cfg.l1RewardsToken, "FarmProxyInit/distribution-gem-mismatch");
+        require(distribution.stakingRewards() == l1Proxy_,           "FarmProxyInit/distribution-farm-mismatch");
+        require(distribution.dssVest()        == cfg.vest,           "FarmProxyInit/distribution-vest-mismatch");
+        require(l1Proxy.rewardsToken()        == cfg.l1RewardsToken, "FarmProxyInit/rewardsToken-token-mismatch");
+        require(l1Proxy.l2Proxy()             == l2Proxy,            "FarmProxyInit/l2-proxy-mismatch");
+        require(l1Proxy.remoteToken()         == cfg.l2RewardsToken, "FarmProxyInit/remote-token-mismatch");
+        require(l1Proxy.l1Bridge()            == cfg.l1Bridge,       "FarmProxyInit/l1-bridge-mismatch");
+        require(cfg.minGasLimit               <= 500_000_000,        "FarmProxyInit/min-gas-limit-out-of-bounds");
+        require(cfg.initMinGasLimit           <= 500_000_000,        "FarmProxyInit/init-min-gas-limit-out-of-bounds");
+
+        // setup vest
+
+        uint256 vestId = vest.create({
+            _usr: cfg.vestedRewardsDistribution,
+            _tot: cfg.vestTot,
+            _bgn: cfg.vestBgn,
+            _tau: cfg.vestTau,
+            _eta: 0,
+            _mgr: address(0)
+        });
+        vest.restrict(vestId);
+        distribution.file("vestId", vestId);
+
+        // setup L1 proxy
+
+        l1Proxy.file("minGasLimit",     cfg.minGasLimit);
+        l1Proxy.file("rewardThreshold", cfg.rewardThreshold);
+
+        // setup L2 proxy
+
+        L1RelayLike(l1GovRelay).relay({
+            target:     l2Spell,
+            targetData: abi.encodeCall(L2FarmProxySpell.init, (
+                l2Proxy,
+                cfg.l2RewardsToken,
+                cfg.l2StakingToken,
+                cfg.farm,
+                cfg.rewardThreshold,
+                cfg.rewardsDuration
+            )),
+            minGasLimit: cfg.initMinGasLimit
+        });
+
+        // update chainlog
+
+        dss.chainlog.setAddress(cfg.proxyChainlogKey, l1Proxy_);
+        dss.chainlog.setAddress(cfg.distrChainlogKey, cfg.vestedRewardsDistribution);
+    }
+}