@keep-network/tbtc-v2 0.1.1-dev.22 → 0.1.1-dev.25

package/contracts/bridge/Wallets.sol

@@ -0,0 +1,520 @@
+// SPDX-License-Identifier: MIT
+
+// ██████████████     ▐████▌     ██████████████
+// ██████████████     ▐████▌     ██████████████
+//               ▐████▌    ▐████▌
+//               ▐████▌    ▐████▌
+// ██████████████     ▐████▌     ██████████████
+// ██████████████     ▐████▌     ██████████████
+//               ▐████▌    ▐████▌
+//               ▐████▌    ▐████▌
+//               ▐████▌    ▐████▌
+//               ▐████▌    ▐████▌
+//               ▐████▌    ▐████▌
+//               ▐████▌    ▐████▌
+
+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 "./BitcoinTx.sol";
+import "./EcdsaLib.sol";
+
+/// @title Wallet library
+/// @notice Library responsible for handling integration between Bridge
+///         contract and ECDSA wallets.
+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.
+        Unknown,
+        /// @dev The wallet can sweep deposits and accept redemption requests.
+        Live,
+        /// @dev The wallet was deemed unhealthy and is expected to move their
+        ///      outstanding funds to another wallet. The wallet can still
+        ///      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.
+        Closed,
+        /// @dev The wallet committed a fraud that was reported. The wallet is
+        ///      blocked and can not perform any actions in the Bridge.
+        ///      Off-chain coordination with the wallet operators is needed to
+        ///      recover funds.
+        Terminated
+    }
+
+    /// @notice Holds information about a wallet.
+    struct Wallet {
+        // Identifier of a ECDSA Wallet registered in the ECDSA Wallet Registry.
+        bytes32 ecdsaWalletID;
+        // Latest wallet's main UTXO hash computed as
+        // keccak256(txHash | txOutputIndex | txOutputValue). The `tx` prefix
+        // refers to the transaction which created that main UTXO. The `txHash`
+        // is `bytes32` (ordered as in Bitcoin internally), `txOutputIndex`
+        // an `uint32`, and `txOutputValue` an `uint64` value.
+        bytes32 mainUtxoHash;
+        // The total redeemable value of pending redemption requests targeting
+        // that wallet.
+        uint64 pendingRedemptionsValue;
+        // UNIX timestamp the wallet was created at.
+        uint32 createdAt;
+        // UNIX timestamp indicating the moment the wallet was requested to
+        // move their funds.
+        uint32 moveFundsRequestedAt;
+        // Current state of the wallet.
+        WalletState state;
+    }
+
+    event WalletCreationPeriodUpdated(uint32 newCreationPeriod);
+
+    event WalletBtcBalanceRangeUpdated(
+        uint64 newMinBtcBalance,
+        uint64 newMaxBtcBalance
+    );
+
+    event WalletMaxAgeUpdated(uint32 newMaxAge);
+
+    event NewWalletRequested();
+
+    event NewWalletRegistered(
+        bytes32 indexed ecdsaWalletID,
+        bytes20 indexed walletPubKeyHash
+    );
+
+    event WalletMovingFunds(
+        bytes32 indexed ecdsaWalletID,
+        bytes20 indexed walletPubKeyHash
+    );
+
+    event WalletClosed(
+        bytes32 indexed ecdsaWalletID,
+        bytes20 indexed walletPubKeyHash
+    );
+
+    event WalletTerminated(
+        bytes32 indexed ecdsaWalletID,
+        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
+    ///         using `registerNewWallet` function.
+    /// @param activeWalletMainUtxo Data of the active wallet's main UTXO, as
+    ///        currently known on the Ethereum chain.
+    /// @dev Requirements:
+    ///      - `activeWalletMainUtxo` components must point to the recent main
+    ///        UTXO of the given active wallet, as currently known on the
+    ///        Ethereum chain. If there is no active wallet at the moment, or
+    ///        the active wallet has no main UTXO, this parameter can be
+    ///        empty as it is ignored.
+    ///      - Wallet creation must not be in progress
+    ///      - If the active wallet is set, one of the following
+    ///        conditions must be true:
+    ///        - The active wallet BTC balance is above the minimum threshold
+    ///          and the active wallet is old enough, i.e. the creation period
+    ///           was elapsed since its creation time
+    ///        - The active wallet BTC balance is above the maximum threshold
+    function requestNewWallet(
+        Data storage self,
+        BitcoinTx.UTXO calldata activeWalletMainUtxo
+    ) external {
+        require(
+            self.registry.getWalletCreationState() == EcdsaDkg.State.IDLE,
+            "Wallet creation already in progress"
+        );
+
+        bytes20 activeWalletPubKeyHash = self.activeWalletPubKeyHash;
+
+        // If the active wallet is set, fetch this wallet's details from
+        // storage to perform conditions check. The `registerNewWallet`
+        // function guarantees an active wallet is always one of the
+        // registered ones.
+        if (activeWalletPubKeyHash != bytes20(0)) {
+            uint64 activeWalletBtcBalance = getWalletBtcBalance(
+                self,
+                activeWalletPubKeyHash,
+                activeWalletMainUtxo
+            );
+            uint32 activeWalletCreatedAt = self
+                .registeredWallets[activeWalletPubKeyHash]
+                .createdAt;
+            /* solhint-disable-next-line not-rely-on-time */
+            bool activeWalletOldEnough = block.timestamp >=
+                activeWalletCreatedAt + self.creationPeriod;
+
+            require(
+                (activeWalletOldEnough &&
+                    activeWalletBtcBalance >= self.minBtcBalance) ||
+                    activeWalletBtcBalance >= self.maxBtcBalance,
+                "Wallet creation conditions are not met"
+            );
+        }
+
+        emit NewWalletRequested();
+
+        self.registry.requestNewWallet();
+    }
+
+    /// @notice Gets BTC balance for given the wallet.
+    /// @param walletPubKeyHash 20-byte public key hash of the wallet
+    /// @param walletMainUtxo Data of the wallet's main UTXO, as currently
+    ///        known on the Ethereum chain.
+    /// @return walletBtcBalance Current BTC balance for the given wallet.
+    /// @dev Requirements:
+    ///      - `walletMainUtxo` components must point to the recent main UTXO
+    ///        of the given wallet, as currently known on the Ethereum chain.
+    ///        If the wallet has no main UTXO, this parameter can be empty as it
+    ///        is ignored.
+    function getWalletBtcBalance(
+        Data storage self,
+        bytes20 walletPubKeyHash,
+        BitcoinTx.UTXO calldata walletMainUtxo
+    ) internal view returns (uint64 walletBtcBalance) {
+        bytes32 walletMainUtxoHash = self
+            .registeredWallets[walletPubKeyHash]
+            .mainUtxoHash;
+
+        // If the wallet has a main UTXO hash set, cross-check it with the
+        // provided plain-text parameter and get the transaction output value
+        // as BTC balance. Otherwise, the BTC balance is just zero.
+        if (walletMainUtxoHash != bytes32(0)) {
+            require(
+                keccak256(
+                    abi.encodePacked(
+                        walletMainUtxo.txHash,
+                        walletMainUtxo.txOutputIndex,
+                        walletMainUtxo.txOutputValue
+                    )
+                ) == walletMainUtxoHash,
+                "Invalid wallet main UTXO data"
+            );
+
+            walletBtcBalance = walletMainUtxo.txOutputValue;
+        }
+
+        return walletBtcBalance;
+    }
+
+    /// @notice Registers a new wallet. This function should be called
+    ///         after the wallet creation process initiated using
+    ///         `requestNewWallet` completes and brings the outcomes.
+    /// @param ecdsaWalletID Wallet's unique identifier.
+    /// @param publicKeyX Wallet's public key's X coordinate.
+    /// @param publicKeyY Wallet's public key's Y coordinate.
+    /// @dev Requirements:
+    ///      - 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,
+        bytes32 ecdsaWalletID,
+        bytes32 publicKeyX,
+        bytes32 publicKeyY
+    ) external {
+        require(
+            msg.sender == address(self.registry),
+            "Caller is not the ECDSA Wallet Registry"
+        );
+
+        // Compress wallet's public key and calculate Bitcoin's hash160 of it.
+        bytes20 walletPubKeyHash = bytes20(
+            EcdsaLib.compressPublicKey(publicKeyX, publicKeyY).hash160()
+        );
+
+        Wallet storage wallet = self.registeredWallets[walletPubKeyHash];
+        require(
+            wallet.state == WalletState.Unknown,
+            "ECDSA wallet has been already registered"
+        );
+        wallet.ecdsaWalletID = ecdsaWalletID;
+        wallet.state = WalletState.Live;
+        /* solhint-disable-next-line not-rely-on-time */
+        wallet.createdAt = uint32(block.timestamp);
+
+        // Set the freshly created wallet as the new active wallet.
+        self.activeWalletPubKeyHash = walletPubKeyHash;
+
+        emit NewWalletRegistered(ecdsaWalletID, walletPubKeyHash);
+    }
+
+    /// @notice Handles a notification about a wallet heartbeat failure and
+    ///         triggers the wallet moving funds process.
+    /// @param publicKeyX Wallet's public key's X coordinate.
+    /// @param publicKeyY Wallet's public key's Y coordinate.
+    /// @dev Requirements:
+    ///      - The only caller authorized to call this function is `registry`
+    ///      - Wallet must be in Live state
+    function notifyWalletHeartbeatFailed(
+        Data storage self,
+        bytes32 publicKeyX,
+        bytes32 publicKeyY
+    ) external {
+        require(
+            msg.sender == address(self.registry),
+            "Caller is not the ECDSA Wallet Registry"
+        );
+
+        // Compress wallet's public key and calculate Bitcoin's hash160 of it.
+        bytes20 walletPubKeyHash = bytes20(
+            EcdsaLib.compressPublicKey(publicKeyX, publicKeyY).hash160()
+        );
+
+        require(
+            self.registeredWallets[walletPubKeyHash].state == WalletState.Live,
+            "ECDSA wallet must be in Live state"
+        );
+
+        moveFunds(self, walletPubKeyHash);
+    }
+
+    /// @notice Handles a notification about a wallet redemption timeout
+    ///         and requests slashing of the wallet operators. Triggers the
+    ///         wallet moving funds process only if the wallet is still in the
+    ///         Live state. That means multiple action timeouts can be reported
+    ///         for the same wallet but only the first report requests the
+    ///         wallet to move their funds.
+    /// @param walletPubKeyHash 20-byte public key hash of the wallet
+    /// @dev Requirements:
+    ///      - Wallet must be in Live or MovingFunds state
+    function notifyRedemptionTimedOut(
+        Data storage self,
+        bytes20 walletPubKeyHash
+    ) external {
+        WalletState walletState = self
+            .registeredWallets[walletPubKeyHash]
+            .state;
+
+        require(
+            walletState == WalletState.Live ||
+                walletState == WalletState.MovingFunds,
+            "ECDSA wallet must be in Live or MovingFunds state"
+        );
+
+        if (walletState == WalletState.Live) {
+            moveFunds(self, walletPubKeyHash);
+        }
+
+        // TODO: Perform slashing of wallet operators.
+    }
+
+    /// @notice Notifies that the wallet is either old enough or has too few
+    ///         satoshis left and qualifies to be closed.
+    /// @param walletPubKeyHash 20-byte public key hash of the wallet
+    /// @param walletMainUtxo Data of the wallet's main UTXO, as currently
+    ///        known on the Ethereum chain.
+    /// @dev Requirements:
+    ///      - Wallet must not be set as the current active wallet
+    ///      - Wallet must exceed the wallet maximum age OR the wallet BTC
+    ///        balance must be lesser than the minimum threshold. If the latter
+    ///        case is true, the `walletMainUtxo` components must point to the
+    ///        recent main UTXO of the given wallet, as currently known on the
+    ///        Ethereum chain. If the wallet has no main UTXO, this parameter
+    ///        can be empty as it is ignored since the wallet balance is
+    ///        assumed to be zero.
+    ///      - Wallet must be in Live state
+    function notifyCloseableWallet(
+        Data storage self,
+        bytes20 walletPubKeyHash,
+        BitcoinTx.UTXO calldata walletMainUtxo
+    ) external {
+        require(
+            self.activeWalletPubKeyHash != walletPubKeyHash,
+            "Active wallet cannot be considered closeable"
+        );
+
+        Wallet storage wallet = self.registeredWallets[walletPubKeyHash];
+        require(
+            wallet.state == WalletState.Live,
+            "ECDSA wallet must be in Live state"
+        );
+
+        /* solhint-disable-next-line not-rely-on-time */
+        bool walletOldEnough = block.timestamp >=
+            wallet.createdAt + self.maxAge;
+
+        require(
+            walletOldEnough ||
+                getWalletBtcBalance(self, walletPubKeyHash, walletMainUtxo) <
+                self.minBtcBalance,
+            "Wallet needs to be old enough or have too few satoshis"
+        );
+
+        moveFunds(self, walletPubKeyHash);
+    }
+
+    /// @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 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 {
+        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.
+            wallet.state = WalletState.Closed;
+
+            emit WalletClosed(wallet.ecdsaWalletID, walletPubKeyHash);
+
+            self.registry.closeWallet(wallet.ecdsaWalletID);
+        } else {
+            // Otherwise, initialize the moving funds process.
+            wallet.state = WalletState.MovingFunds;
+            /* solhint-disable-next-line not-rely-on-time */
+            wallet.moveFundsRequestedAt = uint32(block.timestamp);
+
+            emit WalletMovingFunds(wallet.ecdsaWalletID, walletPubKeyHash);
+        }
+
+        if (self.activeWalletPubKeyHash == walletPubKeyHash) {
+            // If the move funds request refers to the current active wallet,
+            // unset the active wallet and make the wallet creation process
+            // possible in order to get a new healthy active wallet.
+            delete self.activeWalletPubKeyHash;
+        }
+    }
+
+    // TODO: Implement functions that will be called upon moving funds process
+    //       end. Remember the moving funds process ends up with a successful
+    //       proof or a timeout.
+
+    /// @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.
+    /// @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 {
+        // TODO: Perform slashing of wallet operators and add unit tests for that.
+
+        terminateWallet(self, walletPubKeyHash);
+    }
+
+    /// @notice Terminates the given wallet and notifies the ECDSA registry
+    ///         about this fact. If the wallet termination 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:
+    ///      - Wallet must be in Live or MovingFunds state
+    function terminateWallet(Data storage self, bytes20 walletPubKeyHash)
+        internal
+    {
+        Wallet storage wallet = self.registeredWallets[walletPubKeyHash];
+        require(
+            wallet.state == WalletState.Live ||
+                wallet.state == WalletState.MovingFunds,
+            "ECDSA wallet must be in Live or MovingFunds state"
+        );
+
+        wallet.state = WalletState.Terminated;
+
+        emit WalletTerminated(wallet.ecdsaWalletID, walletPubKeyHash);
+
+        if (self.activeWalletPubKeyHash == walletPubKeyHash) {
+            // If termination refers to the current active wallet,
+            // unset the active wallet and make the wallet creation process
+            // possible in order to get a new healthy active wallet.
+            delete self.activeWalletPubKeyHash;
+        }
+
+        self.registry.closeWallet(walletPubKeyHash);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@keep-network/tbtc-v2",
-  "version": "0.1.1-dev.22+main.c25835616ce50ecd68c4421262fb4462cb716d0e",
+  "version": "0.1.1-dev.25+main.a623e0eefa3dbc09c7ace06db035b970d49c1861",
   "license": "MIT",
   "files": [
     "artifacts/",
@@ -27,39 +27,42 @@
   },
   "dependencies": {
     "@keep-network/bitcoin-spv-sol": "3.3.0-solc-0.8",
+    "@keep-network/ecdsa": "2.0.0-dev.4",
     "@keep-network/tbtc": ">1.1.2-dev <1.1.2-pre",
     "@openzeppelin/contracts": "^4.1.0",
     "@tenderly/hardhat-tenderly": "^1.0.12",
     "@thesis/solidity-contracts": "github:thesis/solidity-contracts#4985bcf"
   },
   "devDependencies": {
-    "@keep-network/hardhat-helpers": "0.4.1-pre.1",
-    "@keep-network/hardhat-local-networks-config": "^0.1.0-pre.0",
-    "@nomiclabs/hardhat-ethers": "^2.0.2",
+    "@defi-wonderland/smock": "^2.0.7",
+    "@keep-network/hardhat-helpers": "^0.4.1-pre.2",
+    "@keep-network/hardhat-local-networks-config": "^0.1.0-pre.4",
+    "@nomiclabs/hardhat-ethers": "npm:hardhat-deploy-ethers",
     "@nomiclabs/hardhat-etherscan": "^2.1.4",
-    "@nomiclabs/hardhat-waffle": "^2.0.1",
+    "@nomiclabs/hardhat-waffle": "^2.0.2",
     "@thesis-co/eslint-config": "github:thesis/eslint-config",
-    "@typechain/ethers-v5": "^7.2.0",
-    "@typechain/hardhat": "^2.3.1",
-    "@types/chai": "^4.2.22",
-    "@types/mocha": "^9.0.0",
-    "@types/node": "^16.10.5",
+    "@typechain/ethers-v5": "^8.0.5",
+    "@typechain/hardhat": "^4.0.0",
+    "@types/chai": "^4.3.0",
+    "@types/mocha": "^9.1.0",
+    "@types/node": "^17.0.10",
     "chai": "^4.3.4",
     "eslint": "^7.32.0",
     "ethereum-waffle": "^3.4.0",
-    "ethers": "^5.4.7",
-    "hardhat": "^2.6.4",
+    "ethers": "^5.5.3",
+    "hardhat": "^2.8.3",
     "hardhat-contract-sizer": "^2.5.0",
-    "hardhat-deploy": "^0.8.11",
-    "hardhat-gas-reporter": "^1.0.4",
+    "hardhat-dependency-compiler": "^1.1.2",
+    "hardhat-deploy": "^0.9.27",
+    "hardhat-gas-reporter": "^1.0.6",
     "prettier": "^2.5.1",
     "prettier-plugin-sh": "^0.8.1",
     "prettier-plugin-solidity": "^1.0.0-beta.19",
     "solhint": "^3.3.7",
     "solhint-config-keep": "github:keep-network/solhint-config-keep",
-    "ts-node": "^10.2.1",
-    "typechain": "^5.2.0",
-    "typescript": "^4.4.3"
+    "ts-node": "^10.4.0",
+    "typechain": "^6.1.0",
+    "typescript": "^4.5.4"
   },
   "engines": {
     "node": ">= 14.0.0"