@keep-network/tbtc-v2 0.1.1-dev.55 → 0.1.1-dev.58

package/contracts/bridge/Bridge.sol

@@ -22,7 +22,7 @@ import {IWalletOwner as EcdsaWalletOwner} from "@keep-network/ecdsa/contracts/ap
 import "./IRelay.sol";
 import "./BridgeState.sol";
 import "./Deposit.sol";
-import "./Sweep.sol";
+import "./DepositSweep.sol";
 import "./Redemption.sol";
 import "./BitcoinTx.sol";
 import "./EcdsaLib.sol";
@@ -60,7 +60,7 @@ import "../bank/Bank.sol";
 contract Bridge is Governable, EcdsaWalletOwner {
     using BridgeState for BridgeState.Storage;
     using Deposit for BridgeState.Storage;
-    using Sweep for BridgeState.Storage;
+    using DepositSweep for BridgeState.Storage;
     using Redemption for BridgeState.Storage;
     using MovingFunds for BridgeState.Storage;
     using Wallets for BridgeState.Storage;
@@ -121,6 +121,14 @@ contract Bridge is Governable, EcdsaWalletOwner {
 
     event MovingFundsBelowDustReported(bytes20 walletPubKeyHash);
 
+    event MovedFundsSwept(bytes20 walletPubKeyHash, bytes32 sweepTxHash);
+
+    event MovedFundsSweepTimedOut(
+        bytes20 walletPubKeyHash,
+        bytes32 movingFundsTxHash,
+        uint32 movingFundsTxOutputIndex
+    );
+
     event NewWalletRequested();
 
     event NewWalletRegistered(
@@ -180,7 +188,11 @@ contract Bridge is Governable, EcdsaWalletOwner {
         uint64 movingFundsDustThreshold,
         uint32 movingFundsTimeout,
         uint96 movingFundsTimeoutSlashingAmount,
-        uint256 movingFundsTimeoutNotifierRewardMultiplier
+        uint256 movingFundsTimeoutNotifierRewardMultiplier,
+        uint64 movedFundsSweepTxMaxTotalFee,
+        uint32 movedFundsSweepTimeout,
+        uint96 movedFundsSweepTimeoutSlashingAmount,
+        uint256 movedFundsSweepTimeoutNotifierRewardMultiplier
     );
 
     event WalletParametersUpdated(
@@ -239,6 +251,10 @@ contract Bridge is Governable, EcdsaWalletOwner {
         self.movingFundsTimeout = 7 days;
         self.movingFundsTimeoutSlashingAmount = 10000 * 1e18; // 10000 T
         self.movingFundsTimeoutNotifierRewardMultiplier = 100; //100%
+        self.movedFundsSweepTxMaxTotalFee = 10000; // 10000 satoshi
+        self.movedFundsSweepTimeout = 7 days;
+        self.movedFundsSweepTimeoutSlashingAmount = 10000 * 1e18; // 10000 T
+        self.movedFundsSweepTimeoutNotifierRewardMultiplier = 100; //100%
         self.fraudChallengeDepositAmount = 2 ether;
         self.fraudChallengeDefeatTimeout = 7 days;
         self.fraudSlashingAmount = 10000 * 1e18; // 10000 T
@@ -331,12 +347,12 @@ contract Bridge is Governable, EcdsaWalletOwner {
     ///      - `mainUtxo` components must point to the recent main UTXO
     ///        of the given wallet, as currently known on the Ethereum chain.
     ///        If there is no main UTXO, this parameter is ignored.
-    function submitSweepProof(
+    function submitDepositSweepProof(
         BitcoinTx.Info calldata sweepTx,
         BitcoinTx.Proof calldata sweepProof,
         BitcoinTx.UTXO calldata mainUtxo
     ) external {
-        self.submitSweepProof(sweepTx, sweepProof, mainUtxo);
+        self.submitDepositSweepProof(sweepTx, sweepProof, mainUtxo);
     }
 
     /// @notice Requests redemption of the given amount from the specified
@@ -503,6 +519,7 @@ contract Bridge is Governable, EcdsaWalletOwner {
     /// @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 pending moved funds sweep 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`
@@ -641,6 +658,85 @@ contract Bridge is Governable, EcdsaWalletOwner {
         self.notifyMovingFundsBelowDust(walletPubKeyHash, mainUtxo);
     }
 
+    /// @notice Used by the wallet to prove the BTC moved funds sweep
+    ///         transaction and to make the necessary state changes. Moved
+    ///         funds sweep is only accepted if it satisfies SPV proof.
+    ///
+    ///         The function validates the sweep transaction structure by
+    ///         checking if it actually spends the moved funds UTXO and the
+    ///         sweeping wallet's main UTXO (optionally), and if it locks the
+    ///         value on the sweeping wallet's 20-byte public key hash using a
+    ///         reasonable transaction fee. If all preconditions are
+    ///         met, this function updates the sweeping wallet main UTXO, thus
+    ///         their BTC balance.
+    ///
+    ///         It is possible to prove the given sweep transaction only
+    ///         one time.
+    /// @param sweepTx Bitcoin sweep funds transaction data
+    /// @param sweepProof Bitcoin sweep funds proof data
+    /// @param mainUtxo Data of the sweeping wallet's main UTXO, as currently
+    ///        known on the Ethereum chain
+    /// @dev Requirements:
+    ///      - `sweepTx` components must match the expected structure. See
+    ///        `BitcoinTx.Info` docs for reference. Their values must exactly
+    ///        correspond to appropriate Bitcoin transaction fields to produce
+    ///        a provable transaction hash.
+    ///      - The `sweepTx` should represent a Bitcoin transaction with
+    ///        the first input pointing to a moved funds sweep request targeted
+    ///        to the wallet, and optionally, the second input pointing to the
+    ///        wallet's main UTXO, if the sweeping wallet has a main UTXO set.
+    ///        There should be only one output locking funds on the sweeping
+    ///        wallet 20-byte public key hash.
+    ///      - `sweepProof` components must match the expected structure.
+    ///        See `BitcoinTx.Proof` docs for reference. The `bitcoinHeaders`
+    ///        field must contain a valid number of block headers, not less
+    ///        than the `txProofDifficultyFactor` contract constant.
+    ///      - `mainUtxo` components must point to the recent main UTXO
+    ///        of the sweeping wallet, as currently known on the Ethereum chain.
+    ///        If there is no main UTXO, this parameter is ignored.
+    ///      - The sweeping wallet must be in the Live or MovingFunds state.
+    ///      - The total Bitcoin transaction fee must be lesser or equal
+    ///        to `movedFundsSweepTxMaxTotalFee` governable parameter.
+    function submitMovedFundsSweepProof(
+        BitcoinTx.Info calldata sweepTx,
+        BitcoinTx.Proof calldata sweepProof,
+        BitcoinTx.UTXO calldata mainUtxo
+    ) external {
+        self.submitMovedFundsSweepProof(sweepTx, sweepProof, mainUtxo);
+    }
+
+    /// @notice Notifies about a timed out moved funds sweep process. If the
+    ///         wallet is not terminated yet, that function terminates
+    ///         the wallet and slashes signing group members as a result.
+    ///         Marks the given sweep request as TimedOut.
+    /// @param movingFundsTxHash 32-byte hash of the moving funds transaction
+    ///        that caused the sweep request to be created
+    /// @param movingFundsTxOutputIndex Index of the moving funds transaction
+    ///        output that is subject of the sweep request.
+    /// @param walletMembersIDs Identifiers of the wallet signing group members
+    /// @dev Requirements:
+    ///      - The moved funds sweep request must be in the Pending state
+    ///      - The moved funds sweep timeout must be actually exceeded
+    ///      - The wallet must be either in the Live or MovingFunds or
+    ///        Terminated state
+    ///      - The expression `keccak256(abi.encode(walletMembersIDs))` must
+    ///        be exactly the same as the hash stored under `membersIdsHash`
+    ///        for the given `walletID`. Those IDs are not directly stored
+    ///        in the contract for gas efficiency purposes but they can be
+    ///        read from appropriate `DkgResultSubmitted` and `DkgResultApproved`
+    ///        events of the `WalletRegistry` contract
+    function notifyMovedFundsSweepTimeout(
+        bytes32 movingFundsTxHash,
+        uint32 movingFundsTxOutputIndex,
+        uint32[] calldata walletMembersIDs
+    ) external {
+        self.notifyMovedFundsSweepTimeout(
+            movingFundsTxHash,
+            movingFundsTxOutputIndex,
+            walletMembersIDs
+        );
+    }
+
     /// @notice Requests creation of a new wallet. This function just
     ///         forms a request and the creation process is performed
     ///         asynchronously. Once a wallet is created, the ECDSA Wallet
@@ -998,25 +1094,55 @@ contract Bridge is Governable, EcdsaWalletOwner {
     ///        it determines the percentage of the notifier reward from the
     ///        staking contact the notifier of a moving funds timeout receives.
     ///        The value must be in the range [0, 100]
+    /// @param movedFundsSweepTxMaxTotalFee New value of the moved funds sweep
+    ///        transaction max total fee in satoshis. It is the maximum amount
+    ///        of the total BTC transaction fee that is acceptable in a single
+    ///        moved funds sweep transaction. This is a _total_ max fee for the
+    ///        entire moved funds sweep transaction.
+    /// @param movedFundsSweepTimeout New value of the moved funds sweep
+    ///        timeout in seconds. It is the time after which the moved funds
+    ///        sweep process can be reported as timed out. It is counted from
+    ///        the moment when the wallet was requested to sweep the received
+    ///        funds.
+    /// @param movedFundsSweepTimeoutSlashingAmount New value of the moved
+    ///        funds sweep timeout slashing amount in T, it is the amount
+    ///        slashed from each wallet member for moved funds sweep timeout
+    /// @param movedFundsSweepTimeoutNotifierRewardMultiplier New value of
+    ///        the moved funds sweep timeout notifier reward multiplier as
+    ///        percentage, it determines the percentage of the notifier reward
+    ///        from the staking contact the notifier of a moved funds sweep
+    ///        timeout receives. The value must be in the range [0, 100]
     /// @dev Requirements:
     ///      - Moving funds transaction max total fee must be greater than zero
     ///      - Moving funds dust threshold must be greater than zero
     ///      - Moving funds timeout must be greater than zero
     ///      - Moving funds timeout notifier reward multiplier must be in the
     ///        range [0, 100]
+    ///      - Moved funds sweep transaction max total fee must be greater than zero
+    ///      - Moved funds sweep timeout must be greater than zero
+    ///      - Moved funds sweep timeout notifier reward multiplier must be in the
+    ///        range [0, 100]
     function updateMovingFundsParameters(
         uint64 movingFundsTxMaxTotalFee,
         uint64 movingFundsDustThreshold,
         uint32 movingFundsTimeout,
         uint96 movingFundsTimeoutSlashingAmount,
-        uint256 movingFundsTimeoutNotifierRewardMultiplier
+        uint256 movingFundsTimeoutNotifierRewardMultiplier,
+        uint64 movedFundsSweepTxMaxTotalFee,
+        uint32 movedFundsSweepTimeout,
+        uint96 movedFundsSweepTimeoutSlashingAmount,
+        uint256 movedFundsSweepTimeoutNotifierRewardMultiplier
     ) external onlyGovernance {
         self.updateMovingFundsParameters(
             movingFundsTxMaxTotalFee,
             movingFundsDustThreshold,
             movingFundsTimeout,
             movingFundsTimeoutSlashingAmount,
-            movingFundsTimeoutNotifierRewardMultiplier
+            movingFundsTimeoutNotifierRewardMultiplier,
+            movedFundsSweepTxMaxTotalFee,
+            movedFundsSweepTimeout,
+            movedFundsSweepTimeoutSlashingAmount,
+            movedFundsSweepTimeoutNotifierRewardMultiplier
         );
     }
 
@@ -1200,6 +1326,23 @@ contract Bridge is Governable, EcdsaWalletOwner {
         return self.fraudChallenges[challengeKey];
     }
 
+    /// @notice Collection of all moved funds sweep requests indexed by
+    ///         `keccak256(movingFundsTxHash | movingFundsOutputIndex)`.
+    ///         The `movingFundsTxHash` is `bytes32` (ordered as in Bitcoin
+    ///         internally) and `movingFundsOutputIndex` an `uint32`. Each entry
+    ///         is actually an UTXO representing the moved funds and is supposed
+    ///         to be swept with the current main UTXO of the recipient wallet.
+    /// @param requestKey Request key built as
+    ///        `keccak256(movingFundsTxHash | movingFundsOutputIndex)`
+    /// @return Details of the moved funds sweep request.
+    function movedFundsSweepRequests(uint256 requestKey)
+        external
+        view
+        returns (MovingFunds.MovedFundsSweepRequest memory)
+    {
+        return self.movedFundsSweepRequests[requestKey];
+    }
+
     /// @notice Indicates if the vault with the given address is trusted or not.
     ///         Depositors can route their revealed deposits only to trusted
     ///         vaults and have trusted vaults notified about new deposits as
@@ -1313,6 +1456,20 @@ contract Bridge is Governable, EcdsaWalletOwner {
     /// @return movingFundsTimeoutNotifierRewardMultiplier The percentage of the
     ///         notifier reward from the staking contract the notifier of a
     ///         moving funds timeout receives. The value is in the range [0, 100].
+    /// @return movedFundsSweepTxMaxTotalFee Maximum amount of the total BTC
+    ///         transaction fee that is acceptable in a single moved funds
+    ///         sweep transaction. This is a _total_ max fee for the entire
+    ///         moved funds sweep transaction.
+    /// @return movedFundsSweepTimeout Time after which the moved funds sweep
+    ///         process can be reported as timed out. It is counted from the
+    ///         moment when the wallet was requested to sweep the received funds.
+    ///         Value in seconds.
+    /// @return movedFundsSweepTimeoutSlashingAmount The amount of stake slashed
+    ///         from each member of a wallet for a moved funds sweep timeout.
+    /// @return movedFundsSweepTimeoutNotifierRewardMultiplier The percentage
+    ///         of the notifier reward from the staking contract the notifier
+    ///         of a moved funds sweep timeout receives. The value is in the
+    ///         range [0, 100].
     function movingFundsParameters()
         external
         view
@@ -1321,7 +1478,11 @@ contract Bridge is Governable, EcdsaWalletOwner {
             uint64 movingFundsDustThreshold,
             uint32 movingFundsTimeout,
             uint96 movingFundsTimeoutSlashingAmount,
-            uint256 movingFundsTimeoutNotifierRewardMultiplier
+            uint256 movingFundsTimeoutNotifierRewardMultiplier,
+            uint64 movedFundsSweepTxMaxTotalFee,
+            uint32 movedFundsSweepTimeout,
+            uint96 movedFundsSweepTimeoutSlashingAmount,
+            uint256 movedFundsSweepTimeoutNotifierRewardMultiplier
         )
     {
         movingFundsTxMaxTotalFee = self.movingFundsTxMaxTotalFee;
@@ -1331,6 +1492,12 @@ contract Bridge is Governable, EcdsaWalletOwner {
             .movingFundsTimeoutSlashingAmount;
         movingFundsTimeoutNotifierRewardMultiplier = self
             .movingFundsTimeoutNotifierRewardMultiplier;
+        movedFundsSweepTxMaxTotalFee = self.movedFundsSweepTxMaxTotalFee;
+        movedFundsSweepTimeout = self.movedFundsSweepTimeout;
+        movedFundsSweepTimeoutSlashingAmount = self
+            .movedFundsSweepTimeoutSlashingAmount;
+        movedFundsSweepTimeoutNotifierRewardMultiplier = self
+            .movedFundsSweepTimeoutNotifierRewardMultiplier;
     }
 
     /// @return walletCreationPeriod Determines how frequently a new wallet

package/contracts/bridge/BridgeState.sol

@@ -22,6 +22,7 @@ import "./Deposit.sol";
 import "./Redemption.sol";
 import "./Fraud.sol";
 import "./Wallets.sol";
+import "./MovingFunds.sol";
 
 import "../bank/Bank.sol";
 
@@ -101,6 +102,32 @@ library BridgeState {
         // the notifier of a moving funds timeout receives. The value is in the
         // range [0, 100].
         uint256 movingFundsTimeoutNotifierRewardMultiplier;
+        // Maximum amount of the total BTC transaction fee that is acceptable in
+        // a single moved funds sweep transaction.
+        //
+        // This is a TOTAL max fee for the moved funds sweep transaction. Note
+        // that `depositTxMaxFee` is per single deposit and `redemptionTxMaxFee`
+        // if per single redemption. `movedFundsSweepTxMaxTotalFee` is a total
+        // fee for the entire transaction.
+        uint64 movedFundsSweepTxMaxTotalFee;
+        // Time after which the moved funds sweep process can be reported as
+        // timed out. It is counted from the moment when the recipient wallet
+        // was requested to sweep the received funds. Value in seconds.
+        uint32 movedFundsSweepTimeout;
+        // The amount of stake slashed from each member of a wallet for a moved
+        // funds sweep timeout.
+        uint96 movedFundsSweepTimeoutSlashingAmount;
+        // The percentage of the notifier reward from the staking contract
+        // the notifier of a moved funds sweep timeout receives. The value is
+        // in the range [0, 100].
+        uint256 movedFundsSweepTimeoutNotifierRewardMultiplier;
+        // Collection of all moved funds sweep requests indexed by
+        // `keccak256(movingFundsTxHash | movingFundsOutputIndex)`.
+        // The `movingFundsTxHash` is `bytes32` (ordered as in Bitcoin
+        // internally) and `movingFundsOutputIndex` an `uint32`. Each entry
+        // is actually an UTXO representing the moved funds and is supposed
+        // to be swept with the current main UTXO of the recipient wallet.
+        mapping(uint256 => MovingFunds.MovedFundsSweepRequest) movedFundsSweepRequests;
         // The minimal amount that can be requested for redemption.
         // Value of this parameter must take into account the value of
         // `redemptionTreasuryFeeDivisor` and `redemptionTxMaxFee`
@@ -246,7 +273,11 @@ library BridgeState {
         uint64 movingFundsDustThreshold,
         uint32 movingFundsTimeout,
         uint96 movingFundsTimeoutSlashingAmount,
-        uint256 movingFundsTimeoutNotifierRewardMultiplier
+        uint256 movingFundsTimeoutNotifierRewardMultiplier,
+        uint64 movedFundsSweepTxMaxTotalFee,
+        uint32 movedFundsSweepTimeout,
+        uint96 movedFundsSweepTimeoutSlashingAmount,
+        uint256 movedFundsSweepTimeoutNotifierRewardMultiplier
     );
 
     event WalletParametersUpdated(
@@ -444,19 +475,45 @@ library BridgeState {
     ///        it determines the percentage of the notifier reward from the
     ///        staking contact the notifier of a moving funds timeout receives.
     ///        The value must be in the range [0, 100]
+    /// @param _movedFundsSweepTxMaxTotalFee New value of the moved funds sweep
+    ///        transaction max total fee in satoshis. It is the maximum amount
+    ///        of the total BTC transaction fee that is acceptable in a single
+    ///        moved funds sweep transaction. This is a _total_ max fee for the
+    ///        entire moved funds sweep transaction.
+    /// @param _movedFundsSweepTimeout New value of the moved funds sweep
+    ///        timeout in seconds. It is the time after which the moved funds
+    ///        sweep process can be reported as timed out. It is counted from
+    ///        the moment when the wallet was requested to sweep the received
+    ///        funds.
+    /// @param _movedFundsSweepTimeoutSlashingAmount New value of the moved
+    ///        funds sweep timeout slashing amount in T, it is the amount
+    ///        slashed from each wallet member for moved funds sweep timeout
+    /// @param _movedFundsSweepTimeoutNotifierRewardMultiplier New value of
+    ///        the moved funds sweep timeout notifier reward multiplier as
+    ///        percentage, it determines the percentage of the notifier reward
+    ///        from the staking contact the notifier of a moved funds sweep
+    ///        timeout receives. The value must be in the range [0, 100]
     /// @dev Requirements:
     ///      - Moving funds transaction max total fee must be greater than zero
     ///      - Moving funds dust threshold must be greater than zero
     ///      - Moving funds timeout must be greater than zero
     ///      - Moving funds timeout notifier reward multiplier must be in the
     ///        range [0, 100]
+    ///      - Moved funds sweep transaction max total fee must be greater than zero
+    ///      - Moved funds sweep timeout must be greater than zero
+    ///      - Moved funds sweep timeout notifier reward multiplier must be in the
+    ///        range [0, 100]
     function updateMovingFundsParameters(
         Storage storage self,
         uint64 _movingFundsTxMaxTotalFee,
         uint64 _movingFundsDustThreshold,
         uint32 _movingFundsTimeout,
         uint96 _movingFundsTimeoutSlashingAmount,
-        uint256 _movingFundsTimeoutNotifierRewardMultiplier
+        uint256 _movingFundsTimeoutNotifierRewardMultiplier,
+        uint64 _movedFundsSweepTxMaxTotalFee,
+        uint32 _movedFundsSweepTimeout,
+        uint96 _movedFundsSweepTimeoutSlashingAmount,
+        uint256 _movedFundsSweepTimeoutNotifierRewardMultiplier
     ) internal {
         require(
             _movingFundsTxMaxTotalFee > 0,
@@ -478,6 +535,21 @@ library BridgeState {
             "Moving funds timeout notifier reward multiplier must be in the range [0, 100]"
         );
 
+        require(
+            _movedFundsSweepTxMaxTotalFee > 0,
+            "Moved funds sweep transaction max total fee must be greater than zero"
+        );
+
+        require(
+            _movedFundsSweepTimeout > 0,
+            "Moved funds sweep timeout must be greater than zero"
+        );
+
+        require(
+            _movedFundsSweepTimeoutNotifierRewardMultiplier <= 100,
+            "Moved funds sweep timeout notifier reward multiplier must be in the range [0, 100]"
+        );
+
         self.movingFundsTxMaxTotalFee = _movingFundsTxMaxTotalFee;
         self.movingFundsDustThreshold = _movingFundsDustThreshold;
         self.movingFundsTimeout = _movingFundsTimeout;
@@ -485,13 +557,23 @@ library BridgeState {
             .movingFundsTimeoutSlashingAmount = _movingFundsTimeoutSlashingAmount;
         self
             .movingFundsTimeoutNotifierRewardMultiplier = _movingFundsTimeoutNotifierRewardMultiplier;
+        self.movedFundsSweepTxMaxTotalFee = _movedFundsSweepTxMaxTotalFee;
+        self.movedFundsSweepTimeout = _movedFundsSweepTimeout;
+        self
+            .movedFundsSweepTimeoutSlashingAmount = _movedFundsSweepTimeoutSlashingAmount;
+        self
+            .movedFundsSweepTimeoutNotifierRewardMultiplier = _movedFundsSweepTimeoutNotifierRewardMultiplier;
 
         emit MovingFundsParametersUpdated(
             _movingFundsTxMaxTotalFee,
             _movingFundsDustThreshold,
             _movingFundsTimeout,
             _movingFundsTimeoutSlashingAmount,
-            _movingFundsTimeoutNotifierRewardMultiplier
+            _movingFundsTimeoutNotifierRewardMultiplier,
+            _movedFundsSweepTxMaxTotalFee,
+            _movedFundsSweepTimeout,
+            _movedFundsSweepTimeoutSlashingAmount,
+            _movedFundsSweepTimeoutNotifierRewardMultiplier
         );
     }
 

package/contracts/bridge/{Sweep.sol → DepositSweep.sol}

@@ -33,7 +33,7 @@ import "../bank/Bank.sol";
 ///      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 {
+library DepositSweep {
     using BridgeState for BridgeState.Storage;
     using BitcoinTx for BridgeState.Storage;
 
@@ -41,7 +41,7 @@ library Sweep {
 
     /// @notice Represents an outcome of the sweep Bitcoin transaction
     ///         inputs processing.
-    struct SweepTxInputsInfo {
+    struct DepositSweepTxInputsInfo {
         // Sum of all inputs values i.e. all deposits and main UTXO value,
         // if present.
         uint256 inputsTotalValue;
@@ -103,7 +103,7 @@ library Sweep {
     ///      - `mainUtxo` components must point to the recent main UTXO
     ///        of the given wallet, as currently known on the Ethereum chain.
     ///        If there is no main UTXO, this parameter is ignored.
-    function submitSweepProof(
+    function submitDepositSweepProof(
         BridgeState.Storage storage self,
         BitcoinTx.Info calldata sweepTx,
         BitcoinTx.Proof calldata sweepProof,
@@ -120,20 +120,21 @@ library Sweep {
         (
             bytes20 walletPubKeyHash,
             uint64 sweepTxOutputValue
-        ) = processSweepTxOutput(sweepTx.outputVector);
+        ) = processDepositSweepTxOutput(sweepTx.outputVector);
 
         (
             Wallets.Wallet storage wallet,
             BitcoinTx.UTXO memory resolvedMainUtxo
-        ) = resolveSweepingWallet(self, walletPubKeyHash, mainUtxo);
+        ) = resolveDepositSweepingWallet(self, walletPubKeyHash, mainUtxo);
 
         // Process sweep transaction inputs and extract all information needed
         // to perform deposit bookkeeping.
-        SweepTxInputsInfo memory inputsInfo = processSweepTxInputs(
-            self,
-            sweepTx.inputVector,
-            resolvedMainUtxo
-        );
+        DepositSweepTxInputsInfo
+            memory inputsInfo = processDepositSweepTxInputs(
+                self,
+                sweepTx.inputVector,
+                resolvedMainUtxo
+            );
 
         // Helper variable that will hold the sum of treasury fees paid by
         // all deposits.
@@ -145,7 +146,7 @@ library Sweep {
         (
             uint256 depositTxFee,
             uint256 depositTxFeeRemainder
-        ) = sweepTxFeeDistribution(
+        ) = depositSweepTxFeeDistribution(
                 inputsInfo.inputsTotalValue,
                 sweepTxOutputValue,
                 inputsInfo.depositedAmounts.length
@@ -206,11 +207,16 @@ library Sweep {
     /// @param mainUtxo Data of the wallet's main UTXO, as currently known on
     ///        the Ethereum chain. If no main UTXO exists for the given wallet,
     ///        this parameter is ignored
+    /// @return wallet Data of the sweeping wallet.
+    /// @return resolvedMainUtxo The actual main UTXO of the sweeping wallet
+    ///         resolved by cross-checking the `mainUtxo` parameter with
+    ///         the chain state. If the validation went well, this is the
+    ///         plain-text main UTXO corresponding to the `wallet.mainUtxoHash`.
     /// @dev Requirements:
     ///     - Sweeping wallet must be either in Live or MovingFunds state.
     ///     - 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(
+    function resolveDepositSweepingWallet(
         BridgeState.Storage storage self,
         bytes20 walletPubKeyHash,
         BitcoinTx.UTXO calldata mainUtxo
@@ -261,7 +267,7 @@ library Sweep {
     ///        it is passed here
     /// @return walletPubKeyHash 20-byte wallet public key hash.
     /// @return value 8-byte sweep transaction output value.
-    function processSweepTxOutput(bytes memory sweepTxOutputVector)
+    function processDepositSweepTxOutput(bytes memory sweepTxOutputVector)
         internal
         pure
         returns (bytes20 walletPubKeyHash, uint64 value)
@@ -282,6 +288,8 @@ library Sweep {
 
         bytes memory output = sweepTxOutputVector.extractOutputAtIndex(0);
         value = output.extractValue();
+        // TODO: Extract `walletPubKeyHash` using `self.extractPubKeyHash`
+        //       in order to get stronger validation.
         bytes memory walletPubKeyHashBytes = output.extractHash();
         // The sweep transaction output should always be P2PKH or P2WPKH.
         // In both cases, the wallet public key hash should be 20 bytes length.
@@ -311,11 +319,11 @@ library Sweep {
     ///        exists for the given the wallet, this parameter's fields should
     ///        be zeroed to bypass the main UTXO validation
     /// @return info Outcomes of the processing.
-    function processSweepTxInputs(
+    function processDepositSweepTxInputs(
         BridgeState.Storage storage self,
         bytes memory sweepTxInputVector,
         BitcoinTx.UTXO memory mainUtxo
-    ) internal returns (SweepTxInputsInfo memory info) {
+    ) internal returns (DepositSweepTxInputsInfo memory info) {
         // If the passed `mainUtxo` parameter's values are zeroed, the main UTXO
         // for the given wallet doesn't exist and it is not expected to be
         // included in the sweep transaction input vector.
@@ -365,7 +373,10 @@ library Sweep {
                 bytes32 outpointTxHash,
                 uint32 outpointIndex,
                 uint256 inputLength
-            ) = parseTxInputAt(sweepTxInputVector, inputStartingIndex);
+            ) = parseDepositSweepTxInputAt(
+                    sweepTxInputVector,
+                    inputStartingIndex
+                );
 
             Deposit.DepositRequest storage deposit = self.deposits[
                 uint256(
@@ -402,6 +413,7 @@ library Sweep {
             } else if (
                 mainUtxoExpected != mainUtxoFound &&
                 mainUtxo.txHash == outpointTxHash
+                // TODO: We probably need to check `mainUtxo.txOutputIndex == outpointIndex` as well.
             ) {
                 // If we entered here, that means the input was identified as
                 // the expected main UTXO.
@@ -455,7 +467,7 @@ library Sweep {
     /// @dev This function assumes vector's structure is valid so it must be
     ///      validated using e.g. `BTCUtils.validateVin` function before it
     ///      is passed here.
-    function parseTxInputAt(
+    function parseDepositSweepTxInputAt(
         bytes memory inputVector,
         uint256 inputStartingIndex
     )
@@ -490,7 +502,7 @@ library Sweep {
     ///         transaction fee than cannot be distributed over all deposits.
     /// @dev It is up to the caller to decide how the remainder should be
     ///      counted in. This function only computes its value.
-    function sweepTxFeeDistribution(
+    function depositSweepTxFeeDistribution(
         uint256 sweepTxInputsTotalValue,
         uint256 sweepTxOutputValue,
         uint256 depositsCount