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

package/contracts/bridge/MovingFunds.sol

@@ -20,20 +20,174 @@ import {BytesLib} from "@keep-network/bitcoin-spv-sol/contracts/BytesLib.sol";
 
 import "./BitcoinTx.sol";
 import "./BridgeState.sol";
-import "./Redeem.sol";
+import "./Redemption.sol";
+import "./Wallets.sol";
 
+/// @title Moving Bridge wallet funds
+/// @notice The library handles the logic for moving Bitcoin between Bridge
+///         wallets.
+/// @dev A wallet that failed a heartbeat, did not process requested redemption
+///      on time, or qualifies to be closed, begins the procedure of moving
+///      funds to other wallets in the Bridge. The wallet needs to commit to
+///      which other Live wallets it is moving the funds to and then, provide an
+///      SPV proof of moving funds to the previously committed wallets.
 library MovingFunds {
     using BridgeState for BridgeState.Storage;
-    using Wallets for Wallets.Data;
+    using Wallets for BridgeState.Storage;
+    using BitcoinTx for BridgeState.Storage;
 
     using BTCUtils for bytes;
     using BytesLib for bytes;
 
+    event MovingFundsCommitmentSubmitted(
+        bytes20 walletPubKeyHash,
+        bytes20[] targetWallets,
+        address submitter
+    );
+
     event MovingFundsCompleted(
         bytes20 walletPubKeyHash,
         bytes32 movingFundsTxHash
     );
 
+    event MovingFundsTimedOut(bytes20 walletPubKeyHash);
+
+    /// @notice Submits the moving funds target wallets commitment.
+    ///         Once all requirements are met, that function registers the
+    ///         target wallets commitment and opens the way for moving funds
+    ///         proof submission.
+    /// @param walletPubKeyHash 20-byte public key hash of the source wallet
+    /// @param walletMainUtxo Data of the source wallet's main UTXO, as
+    ///        currently known on the Ethereum chain
+    /// @param walletMembersIDs Identifiers of the source wallet signing group
+    ///        members
+    /// @param walletMemberIndex Position of the caller in the source wallet
+    ///        signing group members list
+    /// @param targetWallets List of 20-byte public key hashes of the target
+    ///        wallets that the source wallet commits to move the funds to
+    /// @dev Requirements:
+    ///      - The source wallet must be in the MovingFunds state
+    ///      - The source wallet must not have pending redemption requests
+    ///      - The source wallet must not have submitted its commitment already
+    ///      - The expression `keccak256(abi.encode(walletMembersIDs))` must
+    ///        be exactly the same as the hash stored under `membersIdsHash`
+    ///        for the given source wallet in the ECDSA registry. Those IDs are
+    ///        not directly stored in the contract for gas efficiency purposes
+    ///        but they can be read from appropriate `DkgResultSubmitted`
+    ///        and `DkgResultApproved` events.
+    ///      - The `walletMemberIndex` must be in range [1, walletMembersIDs.length]
+    ///      - The caller must be the member of the source wallet signing group
+    ///        at the position indicated by `walletMemberIndex` parameter
+    ///      - The `walletMainUtxo` components must point to the recent main
+    ///        UTXO of the source wallet, as currently known on the Ethereum
+    ///        chain.
+    ///      - Source wallet BTC balance must be greater than zero
+    ///      - At least one Live wallet must exist in the system
+    ///      - Submitted target wallets count must match the expected count
+    ///        `N = min(liveWalletsCount, ceil(walletBtcBalance / walletMaxBtcTransfer))`
+    ///        where `N > 0`
+    ///      - Each target wallet must be not equal to the source wallet
+    ///      - Each target wallet must follow the expected order i.e. all
+    ///        target wallets 20-byte public key hashes represented as numbers
+    ///        must form a strictly increasing sequence without duplicates.
+    ///      - Each target wallet must be in Live state
+    function submitMovingFundsCommitment(
+        BridgeState.Storage storage self,
+        bytes20 walletPubKeyHash,
+        BitcoinTx.UTXO calldata walletMainUtxo,
+        uint32[] calldata walletMembersIDs,
+        uint256 walletMemberIndex,
+        bytes20[] calldata targetWallets
+    ) external {
+        Wallets.Wallet storage wallet = self.registeredWallets[
+            walletPubKeyHash
+        ];
+
+        require(
+            wallet.state == Wallets.WalletState.MovingFunds,
+            "Source wallet must be in MovingFunds state"
+        );
+
+        require(
+            wallet.pendingRedemptionsValue == 0,
+            "Source wallet must handle all pending redemptions first"
+        );
+
+        require(
+            wallet.movingFundsTargetWalletsCommitmentHash == bytes32(0),
+            "Target wallets commitment already submitted"
+        );
+
+        require(
+            self.ecdsaWalletRegistry.isWalletMember(
+                wallet.ecdsaWalletID,
+                walletMembersIDs,
+                msg.sender,
+                walletMemberIndex
+            ),
+            "Caller is not a member of the source wallet"
+        );
+
+        uint64 walletBtcBalance = self.getWalletBtcBalance(
+            walletPubKeyHash,
+            walletMainUtxo
+        );
+
+        require(walletBtcBalance > 0, "Wallet BTC balance is zero");
+
+        uint256 expectedTargetWalletsCount = Math.min(
+            self.liveWalletsCount,
+            Math.ceilDiv(walletBtcBalance, self.walletMaxBtcTransfer)
+        );
+
+        // This requirement fails only when `liveWalletsCount` is zero. In
+        // that case, the system cannot accept the commitment and must provide
+        // new wallets first.
+        //
+        // TODO: Expose separate function to reset the moving funds timeout
+        //       if no Live wallets exist in the system.
+        require(expectedTargetWalletsCount > 0, "No target wallets available");
+
+        require(
+            targetWallets.length == expectedTargetWalletsCount,
+            "Submitted target wallets count is other than expected"
+        );
+
+        uint160 lastProcessedTargetWallet = 0;
+
+        for (uint256 i = 0; i < targetWallets.length; i++) {
+            bytes20 targetWallet = targetWallets[i];
+
+            require(
+                targetWallet != walletPubKeyHash,
+                "Submitted target wallet cannot be equal to the source wallet"
+            );
+
+            require(
+                uint160(targetWallet) > lastProcessedTargetWallet,
+                "Submitted target wallet breaks the expected order"
+            );
+
+            require(
+                self.registeredWallets[targetWallet].state ==
+                    Wallets.WalletState.Live,
+                "Submitted target wallet must be in Live state"
+            );
+
+            lastProcessedTargetWallet = uint160(targetWallet);
+        }
+
+        wallet.movingFundsTargetWalletsCommitmentHash = keccak256(
+            abi.encodePacked(targetWallets)
+        );
+
+        emit MovingFundsCommitmentSubmitted(
+            walletPubKeyHash,
+            targetWallets,
+            msg.sender
+        );
+    }
+
     /// @notice Used by the wallet to prove the BTC moving funds transaction
     ///         and to make the necessary state changes. Moving funds is only
     ///         accepted if it satisfies SPV proof.
@@ -81,7 +235,6 @@ library MovingFunds {
     ///        to `movingFundsTxMaxTotalFee` governable parameter.
     function submitMovingFundsProof(
         BridgeState.Storage storage self,
-        Wallets.Data storage wallets,
         BitcoinTx.Info calldata movingFundsTx,
         BitcoinTx.Proof calldata movingFundsProof,
         BitcoinTx.UTXO calldata mainUtxo,
@@ -91,17 +244,15 @@ library MovingFunds {
         // can assume the transaction happened on Bitcoin chain and has
         // a sufficient number of confirmations as determined by
         // `txProofDifficultyFactor` constant.
-        bytes32 movingFundsTxHash = BitcoinTx.validateProof(
+        bytes32 movingFundsTxHash = self.validateProof(
             movingFundsTx,
-            movingFundsProof,
-            self.proofDifficultyContext()
+            movingFundsProof
         );
 
         // Process the moving funds transaction input. Specifically, check if
         // it refers to the expected wallet's main UTXO.
         OutboundTx.processWalletOutboundTxInput(
             self,
-            wallets,
             movingFundsTx.inputVector,
             mainUtxo,
             walletPubKeyHash
@@ -118,8 +269,8 @@ library MovingFunds {
             "Transaction fee is too high"
         );
 
-        wallets.notifyFundsMoved(walletPubKeyHash, targetWalletsHash);
-
+        self.notifyWalletFundsMoved(walletPubKeyHash, targetWalletsHash);
+        // slither-disable-next-line reentrancy-events
         emit MovingFundsCompleted(walletPubKeyHash, movingFundsTxHash);
     }
 
@@ -139,7 +290,7 @@ library MovingFunds {
     ///      - The total outputs value must be evenly divided over all outputs.
     function processMovingFundsTxOutputs(bytes memory movingFundsTxOutputVector)
         internal
-        view
+        pure
         returns (bytes32 targetWalletsHash, uint256 outputsTotalValue)
     {
         // Determining the total number of Bitcoin transaction outputs in
@@ -277,4 +428,39 @@ library MovingFunds {
 
         return (targetWalletsHash, outputsTotalValue);
     }
+
+    /// @notice Notifies about a timed out moving funds process. Terminates
+    ///         the wallet and slashes signing group members as a result.
+    /// @param walletPubKeyHash 20-byte public key hash of the wallet
+    /// @dev Requirements:
+    ///      - The wallet must be in the MovingFunds state
+    ///      - The moving funds timeout must be actually exceeded
+    function notifyMovingFundsTimeout(
+        BridgeState.Storage storage self,
+        bytes20 walletPubKeyHash
+    ) external {
+        Wallets.Wallet storage wallet = self.registeredWallets[
+            walletPubKeyHash
+        ];
+
+        require(
+            wallet.state == Wallets.WalletState.MovingFunds,
+            "ECDSA wallet must be in MovingFunds state"
+        );
+
+        require(
+            /* solhint-disable-next-line not-rely-on-time */
+            block.timestamp >
+                wallet.movingFundsRequestedAt + self.movingFundsTimeout,
+            "Moving funds has not timed out yet"
+        );
+
+        self.terminateWallet(walletPubKeyHash);
+
+        // TODO: Perform slashing of wallet operators, reward the notifier
+        //       using seized amount, and add unit tests for that.
+
+        // slither-disable-next-line reentrancy-events
+        emit MovingFundsTimedOut(walletPubKeyHash);
+    }
 }

package/contracts/bridge/{Redeem.sol → Redemption.sol}

@@ -47,13 +47,12 @@ library OutboundTx {
     ///        performed the outbound transaction.
     function processWalletOutboundTxInput(
         BridgeState.Storage storage self,
-        Wallets.Data storage wallets,
         bytes memory walletOutboundTxInputVector,
         BitcoinTx.UTXO calldata mainUtxo,
         bytes20 walletPubKeyHash
     ) internal {
         // Assert that main UTXO for passed wallet exists in storage.
-        bytes32 mainUtxoHash = wallets
+        bytes32 mainUtxoHash = self
             .registeredWallets[walletPubKeyHash]
             .mainUtxoHash;
         require(mainUtxoHash != bytes32(0), "No main UTXO for given wallet");
@@ -141,10 +140,18 @@ library OutboundTx {
     }
 }
 
-// TODO: Rename to Redemption. All library names are nouns.
-library Redeem {
+/// @title Bridge redemption
+/// @notice The library handles the logic for redeeming Bitcoin balances from
+///         the Bridge.
+/// @dev To initiate a redemption, a user with a Bank balance supplies
+///      a Bitcoin address. Then, the system calculates the redemption fee, and
+///      releases balance to the provided Bitcoin address. Just like in case of
+///      sweeps of revealed deposits, redemption requests are processed in
+///      batches and require SPV proof to be submitted to the Bridge.
+library Redemption {
     using BridgeState for BridgeState.Storage;
-    using Wallets for Wallets.Data;
+    using Wallets for BridgeState.Storage;
+    using BitcoinTx for BridgeState.Storage;
 
     using BTCUtils for bytes;
     using BytesLib for bytes;
@@ -248,13 +255,12 @@ library Redeem {
     ///        contract can spend the given `amount`.
     function requestRedemption(
         BridgeState.Storage storage self,
-        Wallets.Data storage wallets,
         bytes20 walletPubKeyHash,
         BitcoinTx.UTXO calldata mainUtxo,
         bytes calldata redeemerOutputScript,
         uint64 amount
     ) external {
-        Wallets.Wallet storage wallet = wallets.registeredWallets[
+        Wallets.Wallet storage wallet = self.registeredWallets[
             walletPubKeyHash
         ];
 
@@ -419,37 +425,30 @@ library Redeem {
     ///        is identified, that check is omitted in further iterations.
     function submitRedemptionProof(
         BridgeState.Storage storage self,
-        Wallets.Data storage wallets,
         BitcoinTx.Info calldata redemptionTx,
         BitcoinTx.Proof calldata redemptionProof,
         BitcoinTx.UTXO calldata mainUtxo,
         bytes20 walletPubKeyHash
     ) external {
-        // TODO: Just as for `submitSweepProof`, fail early if the function
-        //       call gets frontrunned. See discussion:
-        //       https://github.com/keep-network/tbtc-v2/pull/106#discussion_r801745204
-
         // The actual transaction proof is performed here. After that point, we
         // can assume the transaction happened on Bitcoin chain and has
         // a sufficient number of confirmations as determined by
         // `txProofDifficultyFactor` constant.
-        bytes32 redemptionTxHash = BitcoinTx.validateProof(
+        bytes32 redemptionTxHash = self.validateProof(
             redemptionTx,
-            redemptionProof,
-            self.proofDifficultyContext()
+            redemptionProof
         );
 
         // Process the redemption transaction input. Specifically, check if it
         // refers to the expected wallet's main UTXO.
         OutboundTx.processWalletOutboundTxInput(
             self,
-            wallets,
             redemptionTx.inputVector,
             mainUtxo,
             walletPubKeyHash
         );
 
-        Wallets.Wallet storage wallet = wallets.registeredWallets[
+        Wallets.Wallet storage wallet = self.registeredWallets[
             walletPubKeyHash
         ];
 
@@ -600,11 +599,10 @@ library Redeem {
         bytes20 walletPubKeyHash,
         RedemptionTxOutputsProcessingInfo memory processInfo
     ) internal returns (RedemptionTxOutputsInfo memory resultInfo) {
-        // Helper variable that counts the number of processed redemption
-        // outputs. Redemptions can be either pending or reported as timed out.
-        // TODO: Revisit the approach with redemptions count according to
-        //       https://github.com/keep-network/tbtc-v2/pull/128#discussion_r808237765
-        uint256 processedRedemptionsCount = 0;
+        // Helper flag indicating whether there was at least one redemption
+        // output present (redemption must be either pending or reported as
+        // timed out).
+        bool redemptionPresent = false;
 
         // Outputs processing loop.
         for (uint256 i = 0; i < processInfo.outputsCount; i++) {
@@ -651,7 +649,7 @@ library Redeem {
                     );
                 resultInfo.totalBurnableValue += burnableValue;
                 resultInfo.totalTreasuryFee += treasuryFee;
-                processedRedemptionsCount++;
+                redemptionPresent = true;
             }
 
             // Make the `outputStartingIndex` pointing to the next output by
@@ -663,7 +661,7 @@ library Redeem {
         // referring back to the wallet PKH and just burning main UTXO value
         // for transaction fees.
         require(
-            processedRedemptionsCount > 0,
+            redemptionPresent,
             "Redemption transaction must process at least one redemption"
         );
     }
@@ -789,14 +787,13 @@ library Redeem {
     ///        timed-out).
     function notifyRedemptionTimeout(
         BridgeState.Storage storage self,
-        Wallets.Data storage wallets,
         bytes20 walletPubKeyHash,
         bytes calldata redeemerOutputScript
     ) external {
         uint256 redemptionKey = uint256(
             keccak256(abi.encodePacked(walletPubKeyHash, redeemerOutputScript))
         );
-        Redeem.RedemptionRequest memory request = self.pendingRedemptions[
+        Redemption.RedemptionRequest memory request = self.pendingRedemptions[
             redemptionKey
         ];
 
@@ -808,7 +805,7 @@ library Redeem {
         );
 
         // Update the wallet's pending redemptions value
-        Wallets.Wallet storage wallet = wallets.registeredWallets[
+        Wallets.Wallet storage wallet = self.registeredWallets[
             walletPubKeyHash
         ];
         wallet.pendingRedemptionsValue -=
@@ -838,9 +835,9 @@ library Redeem {
             wallet.state == Wallets.WalletState.MovingFunds
         ) {
             // Propagate timeout consequences to the wallet
-            wallets.notifyRedemptionTimedOut(walletPubKeyHash);
+            self.notifyWalletTimedOutRedemption(walletPubKeyHash);
         }
-
+        // slither-disable-next-line reentrancy-events
         emit RedemptionTimedOut(walletPubKeyHash, redeemerOutputScript);
 
         // Return the requested amount of tokens to the redeemer

package/contracts/bridge/Sweep.sol

@@ -23,8 +23,19 @@ import "./Wallets.sol";
 
 import "../bank/Bank.sol";
 
+/// @title Bridge deposit sweep
+/// @notice The library handles the logic for sweeping transactions revealed to
+///         the Bridge
+/// @dev Bridge active wallet periodically signs a transaction that unlocks all
+///      of the valid, revealed deposits above the dust threshold, combines them
+///      into a single UTXO with the existing main wallet UTXO, and relocks
+///      those transactions without a 30-day refund clause to the same wallet.
+///      This has two main effects: it consolidates the UTXO set and it disables
+///      the refund. Balances of depositors in the Bank are increased when the
+///      SPV sweep proof is submitted to the Bridge.
 library Sweep {
     using BridgeState for BridgeState.Storage;
+    using BitcoinTx for BridgeState.Storage;
 
     using BTCUtils for bytes;
 
@@ -94,23 +105,15 @@ library Sweep {
     ///        If there is no main UTXO, this parameter is ignored.
     function submitSweepProof(
         BridgeState.Storage storage self,
-        Wallets.Data storage wallets,
         BitcoinTx.Info calldata sweepTx,
         BitcoinTx.Proof calldata sweepProof,
         BitcoinTx.UTXO calldata mainUtxo
     ) external {
-        // TODO: Fail early if the function call gets frontrunned. See discussion:
-        //       https://github.com/keep-network/tbtc-v2/pull/106#discussion_r801745204
-
         // The actual transaction proof is performed here. After that point, we
         // can assume the transaction happened on Bitcoin chain and has
         // a sufficient number of confirmations as determined by
         // `txProofDifficultyFactor` constant.
-        bytes32 sweepTxHash = BitcoinTx.validateProof(
-            sweepTx,
-            sweepProof,
-            self.proofDifficultyContext()
-        );
+        bytes32 sweepTxHash = self.validateProof(sweepTx, sweepProof);
 
         // Process sweep transaction output and extract its target wallet
         // public key hash and value.
@@ -122,7 +125,7 @@ library Sweep {
         (
             Wallets.Wallet storage wallet,
             BitcoinTx.UTXO memory resolvedMainUtxo
-        ) = resolveSweepingWallet(wallets, walletPubKeyHash, mainUtxo);
+        ) = resolveSweepingWallet(self, walletPubKeyHash, mainUtxo);
 
         // Process sweep transaction inputs and extract all information needed
         // to perform deposit bookkeeping.
@@ -208,17 +211,18 @@ library Sweep {
     ///     - If the main UTXO of the sweeping wallet exists in the storage,
     ///       the passed `mainUTXO` parameter must be equal to the stored one.
     function resolveSweepingWallet(
-        Wallets.Data storage wallets,
+        BridgeState.Storage storage self,
         bytes20 walletPubKeyHash,
         BitcoinTx.UTXO calldata mainUtxo
     )
         internal
+        view
         returns (
             Wallets.Wallet storage wallet,
             BitcoinTx.UTXO memory resolvedMainUtxo
         )
     {
-        wallet = wallets.registeredWallets[walletPubKeyHash];
+        wallet = self.registeredWallets[walletPubKeyHash];
 
         Wallets.WalletState walletState = wallet.state;
         require(