Base Token Bridge

.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 ETH_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=

README.md

@@ -0,0 +1,97 @@
+# MakerDAO OP Token Bridge
+
+## Overview
+
+The OP Token Bridge is a [custom bridge](https://docs.optimism.io/builders/app-developers/bridging/custom-bridge) to an OP Stack L2 that allows users to deposit a supported token to the L2 and withdraw it back to Ethereum. It operates similarly to the previously deployed [Optimism Dai Bridge](https:/makerdao/optimism-dai-bridge) and relies on the same security model but allows MakerDAO governance to update the set of tokens supported by the bridge.
+
+## Contracts
+
+- `L1TokenBridge.sol` - L1 side of the bridge. Transfers the deposited tokens into an escrow contract. Transfer them back to the user upon receiving a withdrawal message from the `L2TokenBridge`.
+- `L2TokenBridge.sol` - L2 side of the bridge. Mints new L2 tokens after receiving a deposit message from `L1TokenBridge`. Burns L2 tokens when withdrawing them to L1.
+- `Escrow.sol` - Escrow contract that holds the bridged tokens on L1.
+- `L1GovernanceRelay.sol` - L1 side of the governance relay, which allows governance to exert admin control over the deployed L2 contracts.
+- `L2GovernanceRelay.sol` - L2 side of the governance relay.
+
+### External dependencies
+
+- The L2 implementations of the bridged tokens are not provided as part of this repository and are assumed to exist in external repositories. It is assumed that only simple, regular ERC20 tokens will be used with this bridge. In particular, the supported tokens are assumed to revert on failure (instead of returning false) and do not execute any hook on transfer.
+
+## User flows
+
+### L1 to L2 deposits
+
+To deposit a given amount of a supported token to the L2, Alice calls `bridgeERC20[To]()` on the `L1TokenBridge`. This call locks Alice's tokens into the `Escrow` contract and calls the [L1CrossDomainMessenger](https:/ethereum-optimism/optimism/blob/9001eef4784dc2950d0bdcda29752cb2939bae2b/packages/contracts-bedrock/src/L1/L1CrossDomainMessenger.sol) which instructs the sequencer to asynchroneously relay a cross-chain message on L2. This will involve a call to `finalizeBridgeERC20()` on `L2TokenBridge`, which mints an equivalent amount of L2 tokens for Alice.
+
+### L2 to L1 withdrawals
+
+To withdraw her tokens back to L1, Alice calls `bridgeERC20[To]()` on the `L2TokenBridge`. This call burns Alice's tokens and calls the [L2CrossDomainMessenger](https:/ethereum-optimism/optimism/blob/9001eef4784dc2950d0bdcda29752cb2939bae2b/packages/contracts-bedrock/src/L2/L2CrossDomainMessenger.sol), which will eventually (after the ~7 days security period) allow the permissionless finalization of the withdrawal on L1. This will involve a call to `finalizeBridgeERC20()` on the `L1TokenBridge`, which releases an equivalent amount of L1 tokens from the `Escrow` to Alice.
+
+## Upgrades
+
+### Upgrade to a new bridge (and deprecate this bridge)
+
+1. Deploy the new token bridge and connect it to the same escrow as the one used by this bridge. The old and new bridges can operate in parallel.
+2. Optionally, deprecate the old bridge by closing it. This involves calling `close()` on both the `L1TokenBridge` and `L2TokenBridge` so that no new outbound message can be sent to the other side of the bridge. After all cross-chain messages are done processing (can take ~1 week), the bridge is effectively closed and governance can consider revoking the approval to transfer funds from the escrow on L1 and the token minting rights on L2.
+
+### Upgrade a single token to a new bridge
+
+To migrate a single token to a new bridge, follow the steps below:
+
+1. Deploy the new token bridge and connect it to the same escrow as the one used by this bridge.
+2. Unregister the token on both `L1TokenBridge` and `L2TokenBridge`, so that no new outbound message can be sent to the other side of the bridge for that token.
+
+## 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. To deploy the bridge on Base, use the following values:
+
+Mainnet deployment:
+
+```
+L1=mainnet
+L2=base
+```
+
+Testnet deployment:
+
+```
+L1=sepolia
+L2=base_sepolia
+```
+
+### Deploy the bridge
+
+Fill in the required variables into your domain config in `script/input/{chainId}/config.json` by using `base` or `base_sepolia` as an example. Deploy the L1 and L2 tokens (not included in this repo) that must be supported by the bridge then fill in the addresses of these tokens in `script/input/{chainId}/config.json` as two arrays of address strings under the `tokens` key for both the L1 and L2 domains. On testnet, if the `tokens` key is missing for a domain, mock tokens will automatically be deployed for that domain.
+
+The following command deploys the L1 and L2 sides of the bridge:
+
+```
+forge script script/Deploy.s.sol:Deploy --slow --multi --broadcast --verify
+```
+
+### Initialize the bridge
+
+On mainnet, the bridge should be initialized via the spell process. Importantly, the spell caster should add at least 20% gas on top of the estimated gas limit to account for the possibility of a sudden spike in the amount of gas burned to pay for the L1 to L2 message. On testnet, the bridge initialization can be performed via the following command:
+
+```
+forge script script/Init.s.sol:Init --slow --multi --broadcast
+```
+
+### Test the deployment
+
+Make sure the L1 deployer account holds at least 10^18 units of the first token listed under `"l1Tokens"` in `script/output/{chainId}/deployed-latest.json`. To perform a test deposit of that token, use the following command:
+
+```
+forge script script/Deposit.s.sol:Deposit --slow --multi --broadcast
+```
+
+To subsequently perform a test withdrawal, use the following command:
+
+```
+forge script script/Withdraw.s.sol:Withdraw --slow --multi --broadcast
+```
+
+The message can be relayed manually to L1 using the [Superchain Relayer](https://superchainrelayer.xyz/).

deploy/L1TokenBridgeInstance.sol

@@ -0,0 +1,23 @@
+// 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;
+
+struct L1TokenBridgeInstance {
+ address govRelay;
+ address escrow;
+ address bridge;
+}

deploy/L2TokenBridgeInstance.sol

@@ -0,0 +1,23 @@
+// 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;
+
+struct L2TokenBridgeInstance {
+ address govRelay;
+ address bridge;
+ address spell;
+}

deploy/L2TokenBridgeSpell.sol

@@ -0,0 +1,79 @@
+// 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;
+
+interface L2GovRelayLike {
+ function l1GovernanceRelay() external view returns (address);
+ function messenger() external view returns (address);
+}
+
+interface L2TokenBridgeLike {
+ function isOpen() external view returns (uint256);
+ function otherBridge() external view returns (address);
+ function messenger() external view returns (address);
+ function rely(address) external;
+ function deny(address) external;
+ function close() external;
+ function registerToken(address, address) external;
+}
+
+interface AuthLike {
+ function rely(address usr) external;
+}
+
+// A reusable L2 spell to be used by the L2GovernanceRelay to exert admin control over L2TokenBridge
+contract L2TokenBridgeSpell {
+ L2TokenBridgeLike public immutable l2Bridge;
+
+ constructor(address l2Bridge_) {
+ l2Bridge = L2TokenBridgeLike(l2Bridge_);
+ }
+
+ function rely(address usr) external { l2Bridge.rely(usr); }
+ function deny(address usr) external { l2Bridge.deny(usr); }
+ function close() external { l2Bridge.close(); }
+
+ function registerTokens(address[] memory l1Tokens, address[] memory l2Tokens) public { 
+ for (uint256 i; i < l2Tokens.length;) {
+ l2Bridge.registerToken(l1Tokens[i], l2Tokens[i]);
+ AuthLike(l2Tokens[i]).rely(address(l2Bridge));
+ unchecked { ++i; }
+ }
+ }
+
+ function init(
+ address l2GovRelay_,
+ address l2Bridge_,
+ address l1GovRelay,
+ address l1Bridge,
+ address l2Messenger,
+ address[] calldata l1Tokens,
+ address[] calldata l2Tokens
+ ) external {
+ L2GovRelayLike l2GovRelay = L2GovRelayLike(l2GovRelay_);
+
+ // sanity checks
+ require(address(l2Bridge) == l2Bridge_, "L2TokenBridgeSpell/l2-gateway-mismatch");
+ require(l2Bridge.isOpen() == 1, "L2TokenBridgeSpell/not-open");
+ require(l2Bridge.otherBridge() == l1Bridge, "L2TokenBridgeSpell/other-bridge-mismatch");
+ require(l2Bridge.messenger() == l2Messenger, "L2TokenBridgeSpell/l2-bridge-messenger-mismatch");
+ require(l2GovRelay.l1GovernanceRelay() == l1GovRelay, "L2TokenBridgeSpell/l1-gov-relay-mismatch");
+ require(l2GovRelay.messenger() == l2Messenger, "L2TokenBridgeSpell/l2-gov-relay-messenger-mismatch");
+
+ registerTokens(l1Tokens, l2Tokens);
+ }
+}

deploy/TokenBridgeDeploy.sol

@@ -0,0 +1,57 @@
+// 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 { L1TokenBridgeInstance } from "./L1TokenBridgeInstance.sol";
+import { L2TokenBridgeInstance } from "./L2TokenBridgeInstance.sol";
+import { L2TokenBridgeSpell } from "./L2TokenBridgeSpell.sol";
+import { L1GovernanceRelay } from "src/L1GovernanceRelay.sol";
+import { L2GovernanceRelay } from "src/L2GovernanceRelay.sol";
+import { Escrow } from "src/Escrow.sol";
+import { L1TokenBridge } from "src/L1TokenBridge.sol";
+import { L2TokenBridge } from "src/L2TokenBridge.sol";
+
+library TokenBridgeDeploy {
+ function deployL1(
+ address deployer,
+ address owner,
+ address l2GovRelay,
+ address l2Bridge,
+ address l1Messenger
+ ) internal returns (L1TokenBridgeInstance memory l1BridgeInstance) {
+ l1BridgeInstance.govRelay = address(new L1GovernanceRelay(l2GovRelay, l1Messenger));
+ l1BridgeInstance.escrow = address(new Escrow());
+ l1BridgeInstance.bridge = address(new L1TokenBridge(l2Bridge, l1BridgeInstance.escrow, l1Messenger));
+ ScriptTools.switchOwner(l1BridgeInstance.govRelay, deployer, owner);
+ ScriptTools.switchOwner(l1BridgeInstance.escrow, deployer, owner);
+ ScriptTools.switchOwner(l1BridgeInstance.bridge, deployer, owner);
+ }
+
+ function deployL2(
+ address deployer,
+ address l1GovRelay,
+ address l1Bridge,
+ address l2Messenger
+ ) internal returns (L2TokenBridgeInstance memory l2BridgeInstance) {
+ l2BridgeInstance.govRelay = address(new L2GovernanceRelay(l1GovRelay, l2Messenger));
+ l2BridgeInstance.bridge = address(new L2TokenBridge(l1Bridge, l2Messenger));
+ l2BridgeInstance.spell = address(new L2TokenBridgeSpell(l2BridgeInstance.bridge));
+ ScriptTools.switchOwner(l2BridgeInstance.bridge, deployer, l2BridgeInstance.govRelay);
+ }
+}