Adding Base module for canonical TBTC (#673)

Part of #542

This PR is a continuation of tBTC expansion to L2s - BASE chain. Code
was largely copied from the existing cross-chain/* modules with some
naming modifications, addresses and chain ids. It creates a new
cross-chain/base module to bring tBTC to BASE with the help of Wormhole.
Here's a diagram to illustrate the flow
```
+----------------------------+         +-------------------------------------------------------------------+
|          Ethereum          |         |                                Base                               |
|                            |         |                                                                   |
|  +----------------------+  |         |  +----------------------+  +---------------------+  +----------+  |
|  | Wormhole TokenBridge |--|---------|--| Wormhole TokenBridge |--| BaseWormholeGateway |--| BaseTBTC |  |
|  +----------------------+  |         |  +----------------------+  +---------------------+  +----------+  |
|                            |         |                                                                   |
+----------------------------+         +-------------------------------------------------------------------+
```

- `Wormhole TokenBridge` on Ethereum - holds all `TBTC` bridged to BASE.
This is an external contract created by the Wormhole team.
- `Wormhole TokenBridge` on BASE - mints Wormhole wrapped `TBTC` ie.
`wormholeTBTC`. This is an external contract created by the Wormhole
team.
- `BaseWormholeGateway` on BASE - acts as a vending machine that wraps
and unwraps `wormholeTBTC` to the canonical `tBTC` token on BASE. This
is an upgradable Gateway behind OZ transparent proxy. The Threshold team
creates it.
- `BaseTBTC` canonical `tBTC` token on BASE. It is upgradable behind OZ
transparent proxy. The Threshold team creates it.
All the ownership of Threshold-created contracts is transferred to the
Threshold governance including a proxy admin ownership.

A couple of things to pay closer attention at:
- addresses under the `external/` dir
- gateway address to a wormhole chain id: `30`
- gateway addresses to other wormhole chains id: `23 - Arbitrum`, `24 -
Optimism`, `5 - Polygon`
- Goerli BASE and Mainnet BASE chain ids: `84531` and `8453`

## Deploy on BASE testnet / mainnet

Create a `.envrc` file and include the following:

```
export L2_CHAIN_API_URL=<API_URL> // e.g. "https://goerli.base.org"
export L2_ACCOUNTS_PRIVATE_KEYS=<0xOWNER_PRIV_KEY>
export BASESCAN_API_KEY=<API_KEY> // needs to be created on [basescan](https://basescan.org/)
```

```sh
  yarn deploy --network <network>
```

where `network` can be:
- `baseGeorli` // testnet
- `base` // mainnet

## Useful links:

https://docs.base.org/network-information/
https://docs.wormhole.com/wormhole/supported-environments/evm#base

TODO:
- [ ] Register TBTC on BASE using Portal on
[Testnet](https://testnet.portal-bridge-ui.pages.dev/18c38dbb6a/#/register)
and [Mainnet](https://www.portalbridge.com/#/register). After that
replace the address in `BaseWormholeTBTC.json` under `external/base`
~and `external/goerliBase`~ with a newly registered token.

cross-chain/base/.eslintignore

@@ -0,0 +1,8 @@
+artifacts/
+build/
+cache/
+deployments/
+export/
+hardhat-dependency-compiler/
+typechain/
+export.json

cross-chain/base/.eslintrc

@@ -0,0 +1,18 @@
+{
+ "root": true,
+ "extends": ["@thesis-co"],
+ "parserOptions": {
+ "ecmaVersion": 2017,
+ "sourceType": "module"
+ },
+ "env": {
+ "es6": true,
+ "mocha": true
+ },
+ "rules": {
+ "new-cap": "off",
+ "import/no-extraneous-dependencies": "off",
+ "@typescript-eslint/no-use-before-define": "off",
+ "no-plusplus": ["error", { "allowForLoopAfterthoughts": true }]
+ }
+}

cross-chain/base/.gitignore

@@ -0,0 +1,15 @@
+# Hardhat
+/artifacts/
+/build/
+/cache/
+/export/
+/external/npm
+/typechain/
+/export.json
+/deployments/*
+!/deployments/mainnet/
+!/deployments/base/
+!/deployments/baseGoerli/
+
+# OZ
+/.openzeppelin/unknown-*.json

cross-chain/base/.mocharc.json

@@ -0,0 +1,3 @@
+{
+ "require": "ts-node/register/files"
+}

cross-chain/base/.prettierignore

@@ -0,0 +1,9 @@
+.openzeppelin/
+artifacts/
+build/
+cache/
+deployments/
+export/
+hardhat-dependency-compiler/
+typechain/
+export.json

cross-chain/base/.prettierrc.js

@@ -0,0 +1,11 @@
+module.exports = {
+ ...require("@thesis-co/prettier-config"),
+ overrides: [
+ {
+ files: "*.sol",
+ options: {
+ tabWidth: 4,
+ },
+ },
+ ],
+}

cross-chain/base/.solhint.json

@@ -0,0 +1,7 @@
+{
+ "extends": "keep",
+ "plugins": [],
+ "rules": {
+ "func-visibility": ["error", { "ignoreConstructors": true }]
+ }
+}

cross-chain/base/.solhintignore

@@ -0,0 +1,2 @@
+hardhat-dependency-compiler/
+node_modules/

cross-chain/base/.tsconfig-eslint.json

@@ -0,0 +1 @@
+node_modules/@thesis-co/eslint-config/.tsconfig-eslint.json

cross-chain/base/README.adoc

@@ -0,0 +1,59 @@
+:toc: macro
+
+= Threshold cross-chain - Base
+
+This package brings Bitcoin to Ethereum L2 Base. For more details please
+see link:https://github.com/keep-network/tbtc-v2/blob/main/docs/rfc/rfc-8.adoc[RFC 8: Cross-chain Tokenized Threshold BTC]
+
+== How it works?
+
+```
++----------------------------+ +-------------------------------------------------------------------+
+| Ethereum | | Base |
+| | | |
+| +----------------------+ | | +----------------------+ +---------------------+ +----------+ |
+| | Wormhole TokenBridge |--|---------|--| Wormhole TokenBridge |--| BaseWormholeGateway |--| BaseTBTC | |
+| +----------------------+ | | +----------------------+ +---------------------+ +----------+ |
+| | | |
++----------------------------+ +-------------------------------------------------------------------+
+```
+
+- `BaseTBTC` canonical tBTC token on Base with a minting authority
+delegated to `BaseWormholeGateway`.
+- `BaseWormholeGateway` is a smart contract wrapping and unwrapping 
+Wormhole-specific tBTC representation into the canonical `BaseTBTC` token.
+
+=== Updating Wormhole Gateway mapping
+
+The deployment scripts are responsible for managing updates of the tBTC gateway
+addresses across various chains. These addresses are stored in the `external/`
+directory for a specific network.
+It is important to note that these addresses should remain constant for the 
+mainnet network. However, there may be instances where a new version of a 
+cross-chain module is deployed to the testing network, which would require a 
+manual update of the corresponding address.
+
+=== Deploy contracts
+
+To deploy all contracts on the given network, please run:
+```
+yarn deploy --network <network>
+```
+
+Supported networks:
+- `hardhat` - for local development
+- `baseGoerli` - L2 testing network
+- `base` - L2 mainnet
+
+Currently, this module does not deploy any contracts on L1. All the existing 
+Wormhole contract addresses that are used in this module are stored under 
+`external/<network>` dir.
+
+If contracts haven't been built yet or changes occurred, `deploy` task will build
+the contracts before running the deployment script. This command produces
+an `export.json` file containing contract deployment info. Note that for the
+chains other than `hardhat` the following environment variables are needed:
+
+- `L2_CHAIN_API_URL` - URL to access blockchain services, e.g. `https://goerli.base.org`
+- `L2_ACCOUNTS_PRIVATE_KEYS` - Private keys for the deployer and council `<0xOwnerPrivKey,0xCouncilPrivKey>`
+- `BASESCAN_API_KEY` - Base Etherscan API key

cross-chain/base/contracts/test/BaseTBTCUpgraded.sol

@@ -0,0 +1,18 @@
+// SPDX-License-Identifier: GPL-3.0-only
+
+pragma solidity ^0.8.17;
+
+import "@keep-network/tbtc-v2/contracts/l2/L2TBTC.sol";
+
+/// @notice Canonical tBTC Token on Base - upgraded version.
+/// @dev This contract is intended solely for testing purposes. As it currently
+/// stands in the implementation of L2TBTC.sol, there are no reserved
+/// storage gap slots available, thereby limiting the upgradability to a
+/// child contract only.
+contract BaseTBTCUpgraded is L2TBTC {
+ string public newVar;
+
+ function initializeV2(string memory _newVar) public {
+ newVar = _newVar;
+ }
+}

cross-chain/base/contracts/test/BaseWormholeGatewayUpgraded.sol

@@ -0,0 +1,18 @@
+// SPDX-License-Identifier: GPL-3.0-only
+
+pragma solidity ^0.8.17;
+
+import "@keep-network/tbtc-v2/contracts/l2/L2WormholeGateway.sol";
+
+/// @notice Wormhole gateway for L2 Base - upgraded version.
+/// @dev This contract is intended solely for testing purposes. As it currently
+/// stands in the implementation of L2WormholeGateway.sol, there are no
+/// reserved storage gap slots available, thereby limiting the upgradability
+/// to a child contract only.
+contract BaseWormholeGatewayUpgraded is L2WormholeGateway {
+ string public newVar;
+
+ function initializeV2(string memory _newVar) public {
+ newVar = _newVar;
+ }
+}

cross-chain/base/deploy_l2/00_resolve_arbitrum_wormhole_gateway.ts

@@ -0,0 +1,28 @@
+import type { HardhatRuntimeEnvironment } from "hardhat/types"
+import type { DeployFunction } from "hardhat-deploy/types"
+
+const func: DeployFunction = async function (hre: HardhatRuntimeEnvironment) {
+ const { helpers, deployments } = hre
+ const { log } = deployments
+
+ const ArbitrumWormholeGateway = await deployments.getOrNull(
+ "ArbitrumWormholeGateway"
+ )
+
+ if (
+ ArbitrumWormholeGateway &&
+ helpers.address.isValid(ArbitrumWormholeGateway.address)
+ ) {
+ log(
+ `using existing ArbitrumWormholeGateway at ${ArbitrumWormholeGateway.address}`
+ )
+ } else if (hre.network.name === "hardhat") {
+ log("using fake ArbitrumWormholeGateway for hardhat network")
+ } else {
+ throw new Error("deployed ArbitrumWormholeGateway contract not found")
+ }
+}
+
+export default func
+
+func.tags = ["ArbitrumWormholeGateway"]

cross-chain/base/deploy_l2/00_resolve_base_token_bridge.ts

@@ -0,0 +1,21 @@
+import type { HardhatRuntimeEnvironment } from "hardhat/types"
+import type { DeployFunction } from "hardhat-deploy/types"
+
+const func: DeployFunction = async function (hre: HardhatRuntimeEnvironment) {
+ const { helpers, deployments } = hre
+ const { log } = deployments
+
+ const BaseTokenBridge = await deployments.getOrNull("BaseTokenBridge")
+
+ if (BaseTokenBridge && helpers.address.isValid(BaseTokenBridge.address)) {
+ log(`using existing Base TokenBridge at ${BaseTokenBridge.address}`)
+ } else if (hre.network.name === "hardhat") {
+ log("using fake Base TokenBridge for hardhat network")
+ } else {
+ throw new Error("deployed Base TokenBridge contract not found")
+ }
+}
+
+export default func
+
+func.tags = ["BaseTokenBridge"]

cross-chain/base/deploy_l2/00_resolve_base_wormhole_tbtc.ts

@@ -0,0 +1,21 @@
+import type { HardhatRuntimeEnvironment } from "hardhat/types"
+import type { DeployFunction } from "hardhat-deploy/types"
+
+const func: DeployFunction = async function (hre: HardhatRuntimeEnvironment) {
+ const { helpers, deployments } = hre
+ const { log } = deployments
+
+ const BaseWormholeTBTC = await deployments.getOrNull("BaseWormholeTBTC")
+
+ if (BaseWormholeTBTC && helpers.address.isValid(BaseWormholeTBTC.address)) {
+ log(`using existing Base WormholeTBTC at ${BaseWormholeTBTC.address}`)
+ } else if (hre.network.name === "hardhat") {
+ log("using fake Base WormholeTBTC for hardhat network")
+ } else {
+ throw new Error("deployed Base WormholeTBTC contract not found")
+ }
+}
+
+export default func
+
+func.tags = ["BaseWormholeTBTC"]

cross-chain/base/deploy_l2/00_resolve_optimism_wormhole_gateway.ts

@@ -0,0 +1,28 @@
+import type { HardhatRuntimeEnvironment } from "hardhat/types"
+import type { DeployFunction } from "hardhat-deploy/types"
+
+const func: DeployFunction = async function (hre: HardhatRuntimeEnvironment) {
+ const { helpers, deployments } = hre
+ const { log } = deployments
+
+ const OptimismWormholeGateway = await deployments.getOrNull(
+ "OptimismWormholeGateway"
+ )
+
+ if (
+ OptimismWormholeGateway &&
+ helpers.address.isValid(OptimismWormholeGateway.address)
+ ) {
+ log(
+ `using existing OptimismWormholeGateway at ${OptimismWormholeGateway.address}`
+ )
+ } else if (hre.network.name === "hardhat") {
+ log("using fake OptimismWormholeGateway for hardhat network")
+ } else {
+ throw new Error("deployed OptimismWormholeGateway contract not found")
+ }
+}
+
+export default func
+
+func.tags = ["OptimismWormholeGateway"]

cross-chain/base/deploy_l2/00_resolve_polygon_wormhole_gateway.ts

@@ -0,0 +1,28 @@
+import type { HardhatRuntimeEnvironment } from "hardhat/types"
+import type { DeployFunction } from "hardhat-deploy/types"
+
+const func: DeployFunction = async function (hre: HardhatRuntimeEnvironment) {
+ const { helpers, deployments } = hre
+ const { log } = deployments
+
+ const PolygonWormholeGateway = await deployments.getOrNull(
+ "PolygonWormholeGateway"
+ )
+
+ if (
+ PolygonWormholeGateway &&
+ helpers.address.isValid(PolygonWormholeGateway.address)
+ ) {
+ log(
+ `using existing PolygonWormholeGateway at ${PolygonWormholeGateway.address}`
+ )
+ } else if (hre.network.name === "hardhat") {
+ log("using fake PolygonWormholeGateway for hardhat network")
+ } else {
+ throw new Error("deployed PolygonWormholeGateway contract not found")
+ }
+}
+
+export default func
+
+func.tags = ["PolygonWormholeGateway"]

cross-chain/base/deploy_l2/01_deploy_base_tbtc_token.ts

@@ -0,0 +1,36 @@
+import type { HardhatRuntimeEnvironment } from "hardhat/types"
+import type { DeployFunction } from "hardhat-deploy/types"
+
+const func: DeployFunction = async function (hre: HardhatRuntimeEnvironment) {
+ const { ethers, getNamedAccounts, helpers } = hre
+ const { deployer } = await getNamedAccounts()
+
+ const [, proxyDeployment] = await helpers.upgrades.deployProxy("BaseTBTC", {
+ contractName: "@keep-network/tbtc-v2/contracts/l2/L2TBTC.sol:L2TBTC",
+ initializerArgs: ["Base tBTC v2", "tBTC"],
+ factoryOpts: { signer: await ethers.getSigner(deployer) },
+ proxyOpts: {
+ kind: "transparent",
+ },
+ })
+
+ // TODO: Investigate the possibility of adding Tenderly verification for
+ // L2 and upgradable proxy.
+
+ // Contracts can be verified on L2 Base Etherscan in a similar way as we
+ // do it on L1 Etherscan
+ if (hre.network.tags.basescan) {
+ // We use `verify` instead of `verify:verify` as the `verify` task is defined
+ // in "@openzeppelin/hardhat-upgrades" to verify the proxy’s implementation
+ // contract, the proxy itself and any proxy-related contracts, as well as
+ // link the proxy to the implementation contract’s ABI on (Ether)scan.
+ await hre.run("verify", {
+ address: proxyDeployment.address,
+ constructorArgsParams: proxyDeployment.args,
+ })
+ }
+}
+
+export default func
+
+func.tags = ["BaseTBTC"]