@keep-network/tbtc-v2 0.1.1-dev.41 → 0.1.1-dev.44

package/contracts/bridge/Wallets.sol

@@ -16,11 +16,12 @@
 pragma solidity ^0.8.9;
 
 import {BTCUtils} from "@keep-network/bitcoin-spv-sol/contracts/BTCUtils.sol";
-import {IWalletRegistry as EcdsaWalletRegistry} from "@keep-network/ecdsa/contracts/api/IWalletRegistry.sol";
 import {EcdsaDkg} from "@keep-network/ecdsa/contracts/libraries/EcdsaDkg.sol";
+import {Math} from "@openzeppelin/contracts/utils/math/Math.sol";
 
 import "./BitcoinTx.sol";
 import "./EcdsaLib.sol";
+import "./BridgeState.sol";
 
 /// @title Wallet library
 /// @notice Library responsible for handling integration between Bridge
@@ -28,32 +29,6 @@ import "./EcdsaLib.sol";
 library Wallets {
     using BTCUtils for bytes;
 
-    /// @notice Struct that groups the state managed by the library.
-    struct Data {
-        // ECDSA Wallet Registry contract handle.
-        EcdsaWalletRegistry registry;
-        // Determines how frequently a new wallet creation can be requested.
-        // Value in seconds.
-        uint32 creationPeriod;
-        // The minimum BTC threshold in satoshi that is used to decide about
-        // wallet creation or closing.
-        uint64 minBtcBalance;
-        // The maximum BTC threshold in satoshi that is used to decide about
-        // wallet creation.
-        uint64 maxBtcBalance;
-        // The maximum age of a wallet in seconds, after which the wallet
-        // moving funds process can be requested.
-        uint32 maxAge;
-        // 20-byte wallet public key hash being reference to the currently
-        // active wallet. Can be unset to the zero value under certain
-        // circumstances.
-        bytes20 activeWalletPubKeyHash;
-        // Maps the 20-byte wallet public key hash (computed using Bitcoin
-        // HASH160 over the compressed ECDSA public key) to the basic wallet
-        // information like state and pending redemptions value.
-        mapping(bytes20 => Wallet) registeredWallets;
-    }
-
     /// @notice Represents wallet state:
     enum WalletState {
         /// @dev The wallet is unknown to the Bridge.
@@ -65,8 +40,15 @@ library Wallets {
         ///      fulfill their pending redemption requests although new
         ///      redemption requests and new deposit reveals are not accepted.
         MovingFunds,
-        /// @dev The wallet moved or redeemed all their funds and cannot
-        ///      perform any action.
+        /// @dev The wallet moved or redeemed all their funds and is in the
+        ///      closing period where they can be subject of fraud challenges
+        ///      and must defend against them. This state is needed to protect
+        ///      against deposit frauds on deposits revealed but not swept.
+        ///      The closing period must be greater that the deposit refund
+        ///      time plus some time margin.
+        Closing,
+        /// @dev The wallet finalized the closing period successfully and
+        ///      cannot perform any action in the Bridge.
         Closed,
         /// @dev The wallet committed a fraud that was reported. The wallet is
         ///      blocked and can not perform any actions in the Bridge.
@@ -93,6 +75,9 @@ library Wallets {
         // UNIX timestamp indicating the moment the wallet was requested to
         // move their funds.
         uint32 movingFundsRequestedAt;
+        // UNIX timestamp indicating the moment the wallet's closing period
+        // started.
+        uint32 closingStartedAt;
         // Current state of the wallet.
         WalletState state;
         // Moving funds target wallet commitment submitted by the wallet. It
@@ -101,15 +86,6 @@ library Wallets {
         bytes32 movingFundsTargetWalletsCommitmentHash;
     }
 
-    event WalletCreationPeriodUpdated(uint32 newCreationPeriod);
-
-    event WalletBtcBalanceRangeUpdated(
-        uint64 newMinBtcBalance,
-        uint64 newMaxBtcBalance
-    );
-
-    event WalletMaxAgeUpdated(uint32 newMaxAge);
-
     event NewWalletRequested();
 
     event NewWalletRegistered(
@@ -122,6 +98,11 @@ library Wallets {
         bytes20 indexed walletPubKeyHash
     );
 
+    event WalletClosing(
+        bytes32 indexed ecdsaWalletID,
+        bytes20 indexed walletPubKeyHash
+    );
+
     event WalletClosed(
         bytes32 indexed ecdsaWalletID,
         bytes20 indexed walletPubKeyHash
@@ -132,64 +113,6 @@ library Wallets {
         bytes20 indexed walletPubKeyHash
     );
 
-    /// @notice Initializes state invariants.
-    /// @param registry ECDSA Wallet Registry reference
-    /// @dev Requirements:
-    ///      - ECDSA Wallet Registry address must not be initialized
-    function init(Data storage self, address registry) external {
-        require(
-            registry != address(0),
-            "ECDSA Wallet Registry address cannot be zero"
-        );
-        require(
-            address(self.registry) == address(0),
-            "ECDSA Wallet Registry address already set"
-        );
-
-        self.registry = EcdsaWalletRegistry(registry);
-    }
-
-    /// @notice Sets the wallet creation period.
-    /// @param creationPeriod New value of the wallet creation period
-    function setCreationPeriod(Data storage self, uint32 creationPeriod)
-        external
-    {
-        self.creationPeriod = creationPeriod;
-
-        emit WalletCreationPeriodUpdated(creationPeriod);
-    }
-
-    /// @notice Sets the minimum and maximum BTC balance parameters.
-    /// @param minBtcBalance New value of the minimum BTC balance
-    /// @param maxBtcBalance New value of the maximum BTC balance
-    /// @dev Requirements:
-    ///      - Minimum BTC balance must be greater than zero
-    ///      - Maximum BTC balance must be greater than minimum BTC balance
-    function setBtcBalanceRange(
-        Data storage self,
-        uint64 minBtcBalance,
-        uint64 maxBtcBalance
-    ) external {
-        require(minBtcBalance > 0, "Minimum must be greater than zero");
-        require(
-            maxBtcBalance > minBtcBalance,
-            "Maximum must be greater than the minimum"
-        );
-
-        self.minBtcBalance = minBtcBalance;
-        self.maxBtcBalance = maxBtcBalance;
-
-        emit WalletBtcBalanceRangeUpdated(minBtcBalance, maxBtcBalance);
-    }
-
-    /// @notice Sets the wallet maximum age.
-    /// @param maxAge New value of the wallet maximum age
-    function setMaxAge(Data storage self, uint32 maxAge) external {
-        self.maxAge = maxAge;
-
-        emit WalletMaxAgeUpdated(maxAge);
-    }
-
     /// @notice Requests creation of a new wallet. This function just
     ///         forms a request and the creation process is performed
     ///         asynchronously. Outcome of that process should be delivered
@@ -210,11 +133,12 @@ library Wallets {
     ///           was elapsed since its creation time
     ///        - The active wallet BTC balance is above the maximum threshold
     function requestNewWallet(
-        Data storage self,
+        BridgeState.Storage storage self,
         BitcoinTx.UTXO calldata activeWalletMainUtxo
     ) external {
         require(
-            self.registry.getWalletCreationState() == EcdsaDkg.State.IDLE,
+            self.ecdsaWalletRegistry.getWalletCreationState() ==
+                EcdsaDkg.State.IDLE,
             "Wallet creation already in progress"
         );
 
@@ -235,19 +159,19 @@ library Wallets {
                 .createdAt;
             /* solhint-disable-next-line not-rely-on-time */
             bool activeWalletOldEnough = block.timestamp >=
-                activeWalletCreatedAt + self.creationPeriod;
+                activeWalletCreatedAt + self.walletCreationPeriod;
 
             require(
                 (activeWalletOldEnough &&
-                    activeWalletBtcBalance >= self.minBtcBalance) ||
-                    activeWalletBtcBalance >= self.maxBtcBalance,
+                    activeWalletBtcBalance >= self.walletMinBtcBalance) ||
+                    activeWalletBtcBalance >= self.walletMaxBtcBalance,
                 "Wallet creation conditions are not met"
             );
         }
 
         emit NewWalletRequested();
 
-        self.registry.requestNewWallet();
+        self.ecdsaWalletRegistry.requestNewWallet();
     }
 
     /// @notice Gets BTC balance for given the wallet.
@@ -261,7 +185,7 @@ library Wallets {
     ///        If the wallet has no main UTXO, this parameter can be empty as it
     ///        is ignored.
     function getWalletBtcBalance(
-        Data storage self,
+        BridgeState.Storage storage self,
         bytes20 walletPubKeyHash,
         BitcoinTx.UTXO calldata walletMainUtxo
     ) internal view returns (uint64 walletBtcBalance) {
@@ -300,13 +224,13 @@ library Wallets {
     ///      - The only caller authorized to call this function is `registry`
     ///      - Given wallet data must not belong to an already registered wallet
     function registerNewWallet(
-        Data storage self,
+        BridgeState.Storage storage self,
         bytes32 ecdsaWalletID,
         bytes32 publicKeyX,
         bytes32 publicKeyY
     ) external {
         require(
-            msg.sender == address(self.registry),
+            msg.sender == address(self.ecdsaWalletRegistry),
             "Caller is not the ECDSA Wallet Registry"
         );
 
@@ -328,6 +252,8 @@ library Wallets {
         // Set the freshly created wallet as the new active wallet.
         self.activeWalletPubKeyHash = walletPubKeyHash;
 
+        self.liveWalletsCount++;
+
         emit NewWalletRegistered(ecdsaWalletID, walletPubKeyHash);
     }
 
@@ -339,12 +265,12 @@ library Wallets {
     ///      - The only caller authorized to call this function is `registry`
     ///      - Wallet must be in Live state
     function notifyWalletHeartbeatFailed(
-        Data storage self,
+        BridgeState.Storage storage self,
         bytes32 publicKeyX,
         bytes32 publicKeyY
     ) external {
         require(
-            msg.sender == address(self.registry),
+            msg.sender == address(self.ecdsaWalletRegistry),
             "Caller is not the ECDSA Wallet Registry"
         );
 
@@ -370,10 +296,10 @@ library Wallets {
     /// @param walletPubKeyHash 20-byte public key hash of the wallet
     /// @dev Requirements:
     ///      - The wallet must be in the `Live` or `MovingFunds` state
-    function notifyRedemptionTimedOut(
-        Data storage self,
+    function notifyWalletTimedOutRedemption(
+        BridgeState.Storage storage self,
         bytes20 walletPubKeyHash
-    ) external {
+    ) internal {
         WalletState walletState = self
             .registeredWallets[walletPubKeyHash]
             .state;
@@ -408,7 +334,7 @@ library Wallets {
     ///        assumed to be zero.
     ///      - Wallet must be in Live state
     function notifyCloseableWallet(
-        Data storage self,
+        BridgeState.Storage storage self,
         bytes20 walletPubKeyHash,
         BitcoinTx.UTXO calldata walletMainUtxo
     ) external {
@@ -425,12 +351,12 @@ library Wallets {
 
         /* solhint-disable-next-line not-rely-on-time */
         bool walletOldEnough = block.timestamp >=
-            wallet.createdAt + self.maxAge;
+            wallet.createdAt + self.walletMaxAge;
 
         require(
             walletOldEnough ||
                 getWalletBtcBalance(self, walletPubKeyHash, walletMainUtxo) <
-                self.minBtcBalance,
+                self.walletMinBtcBalance,
             "Wallet needs to be old enough or have too few satoshis"
         );
 
@@ -438,21 +364,23 @@ library Wallets {
     }
 
     /// @notice Requests a wallet to move their funds. If the wallet balance
-    ///         is zero, the wallet is closed immediately and the ECDSA
-    ///         registry is notified about this fact. If the move funds
-    ///         request refers to the current active wallet, such a wallet
+    ///         is zero, the wallet closing begins immediately. If the move
+    ///         funds request refers to the current active wallet, such a wallet
     ///         is no longer considered active and the active wallet slot
     ///         is unset allowing to trigger a new wallet creation immediately.
     /// @param walletPubKeyHash 20-byte public key hash of the wallet
     /// @dev Requirements:
     ///      - The caller must make sure that the wallet is in the Live state
-    function moveFunds(Data storage self, bytes20 walletPubKeyHash) internal {
+    function moveFunds(
+        BridgeState.Storage storage self,
+        bytes20 walletPubKeyHash
+    ) internal {
         Wallet storage wallet = self.registeredWallets[walletPubKeyHash];
 
         if (wallet.mainUtxoHash == bytes32(0)) {
             // If the wallet has no main UTXO, that means its BTC balance
-            // is zero and it should be closed immediately.
-            closeWallet(self, walletPubKeyHash);
+            // is zero and the wallet closing should begin immediately.
+            beginWalletClosing(self, walletPubKeyHash);
         } else {
             // Otherwise, initialize the moving funds process.
             wallet.state = WalletState.MovingFunds;
@@ -468,45 +396,49 @@ library Wallets {
             // possible in order to get a new healthy active wallet.
             delete self.activeWalletPubKeyHash;
         }
+
+        self.liveWalletsCount--;
     }
 
-    /// @notice Closes the given wallet and notifies the ECDSA registry
-    ///         about this fact.
+    /// @notice Begins the closing period of the given wallet.
     /// @param walletPubKeyHash 20-byte public key hash of the wallet
     /// @dev Requirements:
     ///      - The caller must make sure that the wallet is in the
-    ///        Live or MovingFunds state.
-    function closeWallet(Data storage self, bytes20 walletPubKeyHash) internal {
+    ///        MovingFunds state
+    function beginWalletClosing(
+        BridgeState.Storage storage self,
+        bytes20 walletPubKeyHash
+    ) internal {
         Wallet storage wallet = self.registeredWallets[walletPubKeyHash];
+        // Initialize the closing period.
+        wallet.state = WalletState.Closing;
+        /* solhint-disable-next-line not-rely-on-time */
+        wallet.closingStartedAt = uint32(block.timestamp);
 
-        wallet.state = WalletState.Closed;
-
-        emit WalletClosed(wallet.ecdsaWalletID, walletPubKeyHash);
-
-        self.registry.closeWallet(wallet.ecdsaWalletID);
+        emit WalletClosing(wallet.ecdsaWalletID, walletPubKeyHash);
     }
 
-    /// @notice Reports about a fraud committed by the given wallet. This
-    ///         function performs slashing and wallet termination in reaction
-    ///         to a proven fraud and it should only be called when the fraud
-    ///         was confirmed.
+    /// @notice Finalizes the closing period of the given wallet and notifies
+    ///         the ECDSA registry about this fact.
     /// @param walletPubKeyHash 20-byte public key hash of the wallet
     /// @dev Requirements:
-    ///      - Wallet must be in Live or MovingFunds state
-    function notifyFraud(Data storage self, bytes20 walletPubKeyHash) external {
-        WalletState walletState = self
-            .registeredWallets[walletPubKeyHash]
-            .state;
+    ///      - The caller must make sure that the wallet is in the Closing state
+    ///
+    /// TODO: Make this function callable from the Bridge contract if
+    ///       `block.timestamp > wallet.closingStartedAt + self.walletClosingPeriod`.
+    ///
+    // slither-disable-next-line dead-code
+    function finalizeWalletClosing(
+        BridgeState.Storage storage self,
+        bytes20 walletPubKeyHash
+    ) internal {
+        Wallet storage wallet = self.registeredWallets[walletPubKeyHash];
 
-        require(
-            walletState == WalletState.Live ||
-                walletState == WalletState.MovingFunds,
-            "ECDSA wallet must be in Live or MovingFunds state"
-        );
+        wallet.state = WalletState.Closed;
 
-        terminateWallet(self, walletPubKeyHash);
+        emit WalletClosed(wallet.ecdsaWalletID, walletPubKeyHash);
 
-        // TODO: Perform slashing of wallet operators and add unit tests for that.
+        self.ecdsaWalletRegistry.closeWallet(wallet.ecdsaWalletID);
     }
 
     /// @notice Terminates the given wallet and notifies the ECDSA registry
@@ -517,12 +449,17 @@ library Wallets {
     /// @param walletPubKeyHash 20-byte public key hash of the wallet
     /// @dev Requirements:
     ///      - The caller must make sure that the wallet is in the
-    ///        Live or MovingFunds state.
-    function terminateWallet(Data storage self, bytes20 walletPubKeyHash)
-        internal
-    {
+    ///        Live or MovingFunds or Closing state.
+    function terminateWallet(
+        BridgeState.Storage storage self,
+        bytes20 walletPubKeyHash
+    ) internal {
         Wallet storage wallet = self.registeredWallets[walletPubKeyHash];
 
+        if (wallet.state == WalletState.Live) {
+            self.liveWalletsCount--;
+        }
+
         wallet.state = WalletState.Terminated;
 
         emit WalletTerminated(wallet.ecdsaWalletID, walletPubKeyHash);
@@ -534,7 +471,7 @@ library Wallets {
             delete self.activeWalletPubKeyHash;
         }
 
-        self.registry.closeWallet(wallet.ecdsaWalletID);
+        self.ecdsaWalletRegistry.closeWallet(wallet.ecdsaWalletID);
     }
 
     /// @notice Notifies that the wallet completed the moving funds process
@@ -553,11 +490,11 @@ library Wallets {
     ///        wallet.
     ///      - The actual target wallets used in the moving funds transaction
     ///        must be exactly the same as the target wallets commitment.
-    function notifyFundsMoved(
-        Data storage self,
+    function notifyWalletFundsMoved(
+        BridgeState.Storage storage self,
         bytes20 walletPubKeyHash,
         bytes32 targetWalletsHash
-    ) external {
+    ) internal {
         Wallet storage wallet = self.registeredWallets[walletPubKeyHash];
         // Check that the wallet is in the MovingFunds state but don't check
         // if the moving funds timeout is exceeded. That should give a
@@ -586,6 +523,6 @@ library Wallets {
         // If funds were moved, the wallet has no longer a main UTXO.
         delete wallet.mainUtxoHash;
 
-        closeWallet(self, walletPubKeyHash);
+        beginWalletClosing(self, walletPubKeyHash);
     }
 }

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,25 @@
+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", {
+    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,60 @@
+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, 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")
+
+  const txProofDifficultyFactor = 6
+
+  const Deposit = await deploy("Deposit", { from: deployer, log: true })
+  const Sweep = await deploy("Sweep", { from: deployer, log: true })
+  const Redemption = await deploy("Redemption", { from: deployer, log: true })
+  const Wallets = await deploy("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 deploy("Bridge", {
+    from: deployer,
+    args: [
+      Bank.address,
+      Relay.address,
+      treasury,
+      WalletRegistry.address,
+      txProofDifficultyFactor,
+    ],
+    libraries: {
+      Deposit: Deposit.address,
+      Sweep: Sweep.address,
+      Redemption: Redemption.address,
+      Wallets: Wallets.address,
+      Fraud: Fraud.address,
+      MovingFunds: MovingFunds.address,
+    },
+    log: true,
+  })
+
+  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_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/07_transfer_ownership.ts

@@ -0,0 +1,17 @@
+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)
+
+  await helpers.ownable.transferOwnership("Bridge", governance, deployer)
+}
+
+export default func
+
+func.tags = ["TransferOwnership"]
+func.dependencies = ["Bank", "Bridge"]
+func.runAtTheEnd = true