@keep-network/tbtc-v2 0.1.1-dev.8 → 0.1.1-dev.82

package/contracts/vault/DonationVault.sol

@@ -0,0 +1,125 @@
+// SPDX-License-Identifier: MIT
+
+// ██████████████     ▐████▌     ██████████████
+// ██████████████     ▐████▌     ██████████████
+//               ▐████▌    ▐████▌
+//               ▐████▌    ▐████▌
+// ██████████████     ▐████▌     ██████████████
+// ██████████████     ▐████▌     ██████████████
+//               ▐████▌    ▐████▌
+//               ▐████▌    ▐████▌
+//               ▐████▌    ▐████▌
+//               ▐████▌    ▐████▌
+//               ▐████▌    ▐████▌
+//               ▐████▌    ▐████▌
+
+pragma solidity ^0.8.9;
+
+import "./IVault.sol";
+import "../bank/Bank.sol";
+
+/// @title BTC donation vault
+/// @notice Vault that allows making BTC donations to the system. Upon deposit,
+///         this vault does not increase depositors' balances and always
+///         decreases its own balance in the same transaction. The vault also
+///         allows making donations using existing Bank balances.
+///
+///         BEWARE: ALL BTC DEPOSITS TARGETING THIS VAULT ARE NOT REDEEMABLE
+///         AND THERE IS NO WAY TO RESTORE THE DONATED BALANCE.
+///         USE THIS VAULT ONLY WHEN YOU REALLY KNOW WHAT YOU ARE DOING!
+contract DonationVault is IVault {
+    Bank public bank;
+
+    event DonationReceived(address donor, uint256 donatedAmount);
+
+    modifier onlyBank() {
+        require(msg.sender == address(bank), "Caller is not the Bank");
+        _;
+    }
+
+    constructor(Bank _bank) {
+        require(
+            address(_bank) != address(0),
+            "Bank can not be the zero address"
+        );
+
+        bank = _bank;
+    }
+
+    /// @notice Transfers the given `amount` of the Bank balance from the
+    ///         caller to the Donation Vault and immediately decreases the
+    ///         vault's balance in the Bank by the transferred `amount`.
+    /// @param amount Amount of the Bank balance to donate.
+    /// @dev Requirements:
+    ///      - The caller's balance in the Bank must be greater than or equal
+    ///        to the `amount`,
+    ///      - Donation Vault must have an allowance for caller's balance in
+    ///        the Bank for at least `amount`.
+    function donate(uint256 amount) external {
+        address donor = msg.sender;
+
+        require(
+            bank.balanceOf(donor) >= amount,
+            "Amount exceeds balance in the bank"
+        );
+
+        emit DonationReceived(donor, amount);
+
+        bank.transferBalanceFrom(donor, address(this), amount);
+        bank.decreaseBalance(amount);
+    }
+
+    /// @notice Transfers the given `amount` of the Bank balance from the
+    ///         `owner` to the Donation Vault and immediately decreases the
+    ///         vault's balance in the Bank by the transferred `amount`.
+    /// @param owner Address of the Bank balance owner who approved their
+    ///        balance to be used by the vault.
+    /// @param amount The amount of the Bank balance approved by the owner
+    ///        to be used by the vault.
+    /// @dev Requirements:
+    ///      - Can only be called by the Bank via `approveBalanceAndCall`,
+    ///      - The `owner` balance in the Bank must be greater than or equal
+    ///        to the `amount`.
+    function receiveBalanceApproval(
+        address owner,
+        uint256 amount,
+        bytes memory
+    ) external override onlyBank {
+        require(
+            bank.balanceOf(owner) >= amount,
+            "Amount exceeds balance in the bank"
+        );
+
+        emit DonationReceived(owner, amount);
+
+        bank.transferBalanceFrom(owner, address(this), amount);
+        bank.decreaseBalance(amount);
+    }
+
+    /// @notice Ignores the deposited amounts and does not increase depositors'
+    ///         individual balances. The vault decreases its own tBTC balance
+    ///         in the Bank by the total deposited amount.
+    /// @param depositors Addresses of depositors whose deposits have been swept.
+    /// @param depositedAmounts Amounts deposited by individual depositors and
+    ///        swept.
+    /// @dev Requirements:
+    ///      - Can only be called by the Bank after the Bridge swept deposits
+    ///        and Bank increased balance for the vault,
+    ///      - The `depositors` array must not be empty,
+    ///      - The `depositors` array length must be equal to the
+    ///        `depositedAmounts` array length.
+    function receiveBalanceIncrease(
+        address[] calldata depositors,
+        uint256[] calldata depositedAmounts
+    ) external override onlyBank {
+        require(depositors.length != 0, "No depositors specified");
+
+        uint256 totalAmount = 0;
+        for (uint256 i = 0; i < depositors.length; i++) {
+            totalAmount += depositedAmounts[i];
+            emit DonationReceived(depositors[i], depositedAmounts[i]);
+        }
+
+        bank.decreaseBalance(totalAmount);
+    }
+}

package/contracts/vault/IVault.sol

@@ -13,25 +13,31 @@
 //               ▐████▌    ▐████▌
 //               ▐████▌    ▐████▌
 
-pragma solidity 0.8.4;
+pragma solidity ^0.8.9;
+
+import "../bank/IReceiveBalanceApproval.sol";
 
 /// @title Bank Vault interface
 /// @notice `IVault` is an interface for a smart contract consuming Bank
-///         balances allowing the smart contract to receive Bank balances right
-///         after sweeping the deposit by the Bridge. This method allows the
-///         depositor to route their deposit revealed to the Bridge to the
-///         particular smart contract in the same transaction the deposit is
-///         revealed. This way, the depositor does not have to execute
-///         additional transaction after the deposit gets swept by the Bridge.
-interface IVault {
+///         balances of other contracts or externally owned accounts (EOA).
+interface IVault is IReceiveBalanceApproval {
     /// @notice Called by the Bank in `increaseBalanceAndCall` function after
-    ///         increasing the balance in the Bank for the vault.
-    /// @param depositors Addresses of depositors whose deposits have been swept
+    ///         increasing the balance in the Bank for the vault. It happens in
+    ///         the same transaction in which deposits were swept by the Bridge.
+    ///         This allows the depositor to route their deposit revealed to the
+    ///         Bridge to the particular smart contract (vault) in the same
+    ///         transaction in which the deposit is revealed. This way, the
+    ///         depositor does not have to execute additional transaction after
+    ///         the deposit gets swept by the Bridge to approve and transfer
+    ///         their balance to the vault.
+    /// @param depositors Addresses of depositors whose deposits have been swept.
     /// @param depositedAmounts Amounts deposited by individual depositors and
-    ///        swept
+    ///        swept.
     /// @dev The implementation must ensure this function can only be called
-    ///      by the Bank.
-    function onBalanceIncreased(
+    ///      by the Bank. The Bank guarantees that the vault's balance was
+    ///      increased by the sum of all deposited amounts before this function
+    ///      is called, in the same transaction.
+    function receiveBalanceIncrease(
         address[] calldata depositors,
         uint256[] calldata depositedAmounts
     ) external;

package/contracts/vault/TBTCVault.sol

@@ -13,7 +13,9 @@
 //               ▐████▌    ▐████▌
 //               ▐████▌    ▐████▌
 
-pragma solidity 0.8.4;
+pragma solidity ^0.8.9;
+
+import "@keep-network/random-beacon/contracts/Governable.sol";
 
 import "./IVault.sol";
 import "../bank/Bank.sol";
@@ -23,17 +25,17 @@ import "../token/TBTC.sol";
 /// @notice TBTC is a fully Bitcoin-backed ERC-20 token pegged to the price of
 ///         Bitcoin. It facilitates Bitcoin holders to act on the Ethereum
 ///         blockchain and access the decentralized finance (DeFi) ecosystem.
-///         TBTC Vault mints and redeems TBTC based on Bitcoin balances in the
+///         TBTC Vault mints and unmints TBTC based on Bitcoin balances in the
 ///         Bank.
 /// @dev TBTC Vault is the owner of TBTC token contract and is the only contract
 ///      minting the token.
-contract TBTCVault is IVault {
+contract TBTCVault is IVault, Governable {
     Bank public bank;
     TBTC public tbtcToken;
 
     event Minted(address indexed to, uint256 amount);
 
-    event Redeemed(address indexed from, uint256 amount);
+    event Unminted(address indexed from, uint256 amount);
 
     modifier onlyBank() {
         require(msg.sender == address(bank), "Caller is not the Bank");
@@ -53,13 +55,43 @@ contract TBTCVault is IVault {
 
         bank = _bank;
         tbtcToken = _tbtcToken;
+
+        _transferGovernance(msg.sender);
+    }
+
+    /// @notice Allows the governance of the TBTCVault to recover any ERC20
+    ///         token sent mistakenly to the TBTC token contract address.
+    /// @param token Address of the recovered ERC20 token contract.
+    /// @param recipient Address the recovered token should be sent to.
+    /// @param amount Recovered amount.
+    function recoverERC20(
+        IERC20 token,
+        address recipient,
+        uint256 amount
+    ) external onlyGovernance {
+        tbtcToken.recoverERC20(token, recipient, amount);
+    }
+
+    /// @notice Allows the governance of the TBTCVault to recover any ERC721
+    ///         token sent mistakenly to the TBTC token contract address.
+    /// @param token Address of the recovered ERC721 token contract.
+    /// @param recipient Address the recovered token should be sent to.
+    /// @param tokenId Identifier of the recovered token.
+    /// @param data Additional data.
+    function recoverERC721(
+        IERC721 token,
+        address recipient,
+        uint256 tokenId,
+        bytes calldata data
+    ) external onlyGovernance {
+        tbtcToken.recoverERC721(token, recipient, tokenId, data);
     }
 
     /// @notice Transfers the given `amount` of the Bank balance from caller
     ///         to TBTC Vault, and mints `amount` of TBTC to the caller.
     /// @dev TBTC Vault must have an allowance for caller's balance in the Bank
     ///      for at least `amount`.
-    /// @param amount Amount of TBTC to mint
+    /// @param amount Amount of TBTC to mint.
     function mint(uint256 amount) external {
         address minter = msg.sender;
         require(
@@ -70,13 +102,31 @@ contract TBTCVault is IVault {
         bank.transferBalanceFrom(minter, address(this), amount);
     }
 
+    /// @notice Transfers the given `amount` of the Bank balance from the caller
+    ///         to TBTC Vault and mints `amount` of TBTC to the caller.
+    /// @dev Can only be called by the Bank via `approveBalanceAndCall`.
+    /// @param owner The owner who approved their Bank balance.
+    /// @param amount Amount of TBTC to mint.
+    function receiveBalanceApproval(
+        address owner,
+        uint256 amount,
+        bytes memory
+    ) external override onlyBank {
+        require(
+            bank.balanceOf(owner) >= amount,
+            "Amount exceeds balance in the bank"
+        );
+        _mint(owner, amount);
+        bank.transferBalanceFrom(owner, address(this), amount);
+    }
+
     /// @notice Mints the same amount of TBTC as the deposited amount for each
     ///         depositor in the array. Can only be called by the Bank after the
     ///         Bridge swept deposits and Bank increased balance for the
     ///         vault.
     /// @dev Fails if `depositors` array is empty. Expects the length of
     ///      `depositors` and `depositedAmounts` is the same.
-    function onBalanceIncreased(
+    function receiveBalanceIncrease(
         address[] calldata depositors,
         uint256[] calldata depositedAmounts
     ) external override onlyBank {
@@ -90,19 +140,19 @@ contract TBTCVault is IVault {
     ///         `amount` back to the caller's balance in the Bank.
     /// @dev Caller must have at least `amount` of TBTC approved to
     ///       TBTC Vault.
-    /// @param amount Amount of TBTC to redeem
-    function redeem(uint256 amount) external {
-        _redeem(msg.sender, amount);
+    /// @param amount Amount of TBTC to unmint.
+    function unmint(uint256 amount) external {
+        _unmint(msg.sender, amount);
     }
 
     /// @notice Burns `amount` of TBTC from the caller's account and transfers
     ///         `amount` back to the caller's balance in the Bank.
-    /// @dev This function is doing the same as `redeem` but it allows to
-    ///      execute redemption without an additional approval transaction.
+    /// @dev This function is doing the same as `unmint` but it allows to
+    ///      execute unminting without an additional approval transaction.
     ///      The function can be called only via `approveAndCall` of TBTC token.
-    /// @param from TBTC token holder executing redemption
-    /// @param amount Amount of TBTC to redeem
-    /// @param token TBTC token address
+    /// @param from TBTC token holder executing unminting.
+    /// @param amount Amount of TBTC to unmint.
+    /// @param token TBTC token address.
     function receiveApproval(
         address from,
         uint256 amount,
@@ -111,7 +161,7 @@ contract TBTCVault is IVault {
     ) external {
         require(token == address(tbtcToken), "Token is not TBTC");
         require(msg.sender == token, "Only TBTC caller allowed");
-        _redeem(from, amount);
+        _unmint(from, amount);
     }
 
     // slither-disable-next-line calls-loop
@@ -120,9 +170,9 @@ contract TBTCVault is IVault {
         tbtcToken.mint(minter, amount);
     }
 
-    function _redeem(address redeemer, uint256 amount) internal {
-        emit Redeemed(redeemer, amount);
-        tbtcToken.burnFrom(redeemer, amount);
-        bank.transferBalance(redeemer, amount);
+    function _unmint(address unminter, uint256 amount) internal {
+        emit Unminted(unminter, amount);
+        tbtcToken.burnFrom(unminter, amount);
+        bank.transferBalance(unminter, amount);
     }
 }

package/deploy/00_resolve_relay.ts

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

package/deploy/04_deploy_bank.ts

@@ -0,0 +1,27 @@
+import { HardhatRuntimeEnvironment } from "hardhat/types"
+import { DeployFunction } from "hardhat-deploy/types"
+
+const func: DeployFunction = async function (hre: HardhatRuntimeEnvironment) {
+  const { deployments, getNamedAccounts } = hre
+  const { deploy } = deployments
+  const { deployer } = await getNamedAccounts()
+
+  const Bank = await deploy("Bank", {
+    contract:
+      deployments.getNetworkName() === "hardhat" ? "BankStub" : undefined,
+    from: deployer,
+    args: [],
+    log: true,
+  })
+
+  if (hre.network.tags.tenderly) {
+    await hre.tenderly.verify({
+      name: "Bank",
+      address: Bank.address,
+    })
+  }
+}
+
+export default func
+
+func.tags = ["Bank"]

package/deploy/05_deploy_bridge.ts

@@ -0,0 +1,80 @@
+import { HardhatRuntimeEnvironment } from "hardhat/types"
+import { DeployFunction } from "hardhat-deploy/types"
+
+const func: DeployFunction = async function (hre: HardhatRuntimeEnvironment) {
+  const { ethers, helpers, deployments, getNamedAccounts } = hre
+  const { deploy } = deployments
+  const { deployer, treasury } = await getNamedAccounts()
+
+  const Bank = await deployments.get("Bank")
+  const Relay = await deployments.get("Relay")
+
+  // TODO: Test for mainnet deployment that when `WalletRegistry` is provided
+  // in `external/mainnet/` directory it gets resolved correctly, and the deployment
+  // script from `@keep-network/ecdsa` is not invoked once again.
+  const WalletRegistry = await deployments.get("WalletRegistry")
+
+  // For local tests use `1`.
+  const txProofDifficultyFactor =
+    deployments.getNetworkName() === "hardhat" ? 1 : 6
+
+  const Deposit = await deploy("Deposit", { from: deployer, log: true })
+  const DepositSweep = await deploy("DepositSweep", {
+    from: deployer,
+    log: true,
+  })
+  const Redemption = await deploy("Redemption", { from: deployer, log: true })
+  const Wallets = await deploy("Wallets", {
+    contract: "contracts/bridge/Wallets.sol:Wallets",
+    from: deployer,
+    log: true,
+  })
+  const Fraud = await deploy("Fraud", { from: deployer, log: true })
+  const MovingFunds = await deploy("MovingFunds", {
+    from: deployer,
+    log: true,
+  })
+
+  const bridge = await helpers.upgrades.deployProxy("Bridge", {
+    contractName:
+      deployments.getNetworkName() === "hardhat" ? "BridgeStub" : undefined,
+    initializerArgs: [
+      Bank.address,
+      Relay.address,
+      treasury,
+      WalletRegistry.address,
+      txProofDifficultyFactor,
+    ],
+    factoryOpts: {
+      signer: await ethers.getSigner(deployer),
+      libraries: {
+        Deposit: Deposit.address,
+        DepositSweep: DepositSweep.address,
+        Redemption: Redemption.address,
+        Wallets: Wallets.address,
+        Fraud: Fraud.address,
+        MovingFunds: MovingFunds.address,
+      },
+    },
+    proxyOpts: {
+      kind: "transparent",
+      // Allow external libraries linking. We need to ensure manually that the
+      // external  libraries we link are upgrade safe, as the OpenZeppelin plugin
+      // doesn't perform such a validation yet.
+      // See: https://docs.openzeppelin.com/upgrades-plugins/1.x/faq#why-cant-i-use-external-libraries
+      unsafeAllow: ["external-library-linking"],
+    },
+  })
+
+  if (hre.network.tags.tenderly) {
+    await hre.tenderly.verify({
+      name: "Bridge",
+      address: bridge.address,
+    })
+  }
+}
+
+export default func
+
+func.tags = ["Bridge"]
+func.dependencies = ["Bank", "Relay", "Treasury", "WalletRegistry"]

package/deploy/06_deploy_tbtc_vault.ts

@@ -0,0 +1,30 @@
+import { HardhatRuntimeEnvironment } from "hardhat/types"
+import { DeployFunction } from "hardhat-deploy/types"
+
+const func: DeployFunction = async function (hre: HardhatRuntimeEnvironment) {
+  const { deployments, getNamedAccounts } = hre
+  const { deploy } = deployments
+  const { deployer } = await getNamedAccounts()
+
+  const Bank = await deployments.get("Bank")
+  const TBTC = await deployments.get("TBTC")
+
+  const TBTCVault = await deploy("TBTCVault", {
+    contract: "TBTCVault",
+    from: deployer,
+    args: [Bank.address, TBTC.address],
+    log: true,
+  })
+
+  if (hre.network.tags.tenderly) {
+    await hre.tenderly.verify({
+      name: "TBTCVault",
+      address: TBTCVault.address,
+    })
+  }
+}
+
+export default func
+
+func.tags = ["TBTCVault"]
+func.dependencies = ["Bank", "TBTC"]

package/deploy/07_bank_update_bridge.ts

@@ -0,0 +1,19 @@
+import { HardhatRuntimeEnvironment } from "hardhat/types"
+import { DeployFunction } from "hardhat-deploy/types"
+
+const func: DeployFunction = async function (hre: HardhatRuntimeEnvironment) {
+  const { getNamedAccounts, deployments } = hre
+  const { execute, log } = deployments
+  const { deployer } = await getNamedAccounts()
+
+  const Bridge = await deployments.get("Bridge")
+
+  log("updating Bridge in Bank")
+
+  await execute("Bank", { from: deployer }, "updateBridge", Bridge.address)
+}
+
+export default func
+
+func.tags = ["BankUpdateBridge"]
+func.dependencies = ["Bank", "Bridge"]

package/deploy/08_transfer_ownership.ts

@@ -0,0 +1,15 @@
+import { HardhatRuntimeEnvironment } from "hardhat/types"
+import { DeployFunction } from "hardhat-deploy/types"
+
+const func: DeployFunction = async function (hre: HardhatRuntimeEnvironment) {
+  const { getNamedAccounts, helpers } = hre
+  const { deployer, governance } = await getNamedAccounts()
+
+  await helpers.ownable.transferOwnership("Bank", governance, deployer)
+}
+
+export default func
+
+func.tags = ["TransferOwnership"]
+func.dependencies = ["Bank"]
+func.runAtTheEnd = true

package/deploy/09_transfer_governance.ts

@@ -0,0 +1,20 @@
+import { HardhatRuntimeEnvironment } from "hardhat/types"
+import { DeployFunction } from "hardhat-deploy/types"
+
+const func: DeployFunction = async function (hre: HardhatRuntimeEnvironment) {
+  const { getNamedAccounts, deployments } = hre
+  const { deployer, governance } = await getNamedAccounts()
+
+  await deployments.execute(
+    "Bridge",
+    { from: deployer },
+    "transferGovernance",
+    governance
+  )
+}
+
+export default func
+
+func.tags = ["TransferGovernance"]
+func.dependencies = ["Bridge"]
+func.runAtTheEnd = true

package/deploy/10_transfer_proxy_admin_ownership.ts

@@ -0,0 +1,30 @@
+import type { HardhatRuntimeEnvironment } from "hardhat/types"
+import type { DeployFunction } from "hardhat-deploy/types"
+
+const func: DeployFunction = async (hre: HardhatRuntimeEnvironment) => {
+  const { helpers, upgrades, deployments } = hre
+  const { esdm, deployer } = await helpers.signers.getNamedSigners()
+  const { log } = deployments
+
+  // TODO: Once a DAO is established we want to switch to ProxyAdminWithDeputy and
+  // use the DAO as the proxy admin owner and ESDM as the deputy. Until then we
+  // use ESDM as the owner of ProxyAdmin contract.
+  const newProxyAdminOwner = esdm.address
+
+  const proxyAdmin = await upgrades.admin.getInstance()
+
+  const currentOwner = await proxyAdmin.owner()
+
+  // The `@openzeppelin/hardhat-upgrades` plugin deploys a single ProxyAdmin
+  // per network. We don't want to transfer the ownership if the owner is already
+  // set to the desired address.
+  if (!helpers.address.equal(currentOwner, newProxyAdminOwner)) {
+    log(`transferring ownership of ProxyAdmin to ${newProxyAdminOwner}`)
+    await proxyAdmin.connect(deployer).transferOwnership(newProxyAdminOwner)
+  }
+}
+
+export default func
+
+func.tags = ["TransferProxyAdminOwnership"]
+func.dependencies = ["Bridge"]

package/deploy/11_deploy_proxy_admin_with_deputy.ts

@@ -0,0 +1,33 @@
+import type { HardhatRuntimeEnvironment } from "hardhat/types"
+import type { DeployFunction } from "hardhat-deploy/types"
+
+const func: DeployFunction = async (hre: HardhatRuntimeEnvironment) => {
+  const { ethers, getNamedAccounts, upgrades, deployments } = hre
+  const { deployer, dao, esdm } = await getNamedAccounts()
+
+  const BridgeProxyAdminWithDeputy = await deployments.deploy(
+    "BridgeProxyAdminWithDeputy",
+    {
+      contract: "ProxyAdminWithDeputy",
+      from: deployer,
+      args: [dao, esdm],
+      log: true,
+    }
+  )
+
+  const Bridge = await deployments.get("Bridge")
+
+  const proxyAdmin = await upgrades.admin.getInstance()
+
+  await proxyAdmin
+    .connect(await ethers.getSigner(esdm))
+    .changeProxyAdmin(Bridge.address, BridgeProxyAdminWithDeputy.address)
+}
+
+export default func
+
+func.tags = ["BridgeProxyAdminWithDeputy"]
+func.dependencies = ["Bridge"]
+
+// TODO: For now we skip this script as DAO is not yet established.
+func.skip = async () => true