@keep-network/tbtc-v2 0.1.1-dev.53 → 0.1.1-dev.56

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";
 
@@ -83,17 +84,39 @@ library BridgeState {
         // if per single redemption. `movingFundsTxMaxTotalFee` is a total
         // fee for the entire transaction.
         uint64 movingFundsTxMaxTotalFee;
-        // Time after which the moving funds process can be reported as
-        // timed out. It is counted from the moment when the wallet
-        // was requested to move their funds and switched to the MovingFunds
-        // state. Value in seconds.
-        uint32 movingFundsTimeout;
         // The minimal satoshi amount that makes sense to be transferred during
         // the moving funds process. Moving funds wallets having their BTC
         // balance below that value can begin closing immediately as
         // transferring such a low value may not be possible due to
         // BTC network fees.
         uint64 movingFundsDustThreshold;
+        // Time after which the moving funds process can be reported as
+        // timed out. It is counted from the moment when the wallet
+        // was requested to move their funds and switched to the MovingFunds
+        // state. Value in seconds.
+        uint32 movingFundsTimeout;
+        // The amount of stake slashed from each member of a wallet for a moving
+        // funds timeout.
+        uint96 movingFundsTimeoutSlashingAmount;
+        // 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].
+        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;
+        // 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`
@@ -158,16 +181,16 @@ library BridgeState {
         //    mapping basing on a timed out request stored previously in
         //    `pendingRedemptions` mapping.
         mapping(uint256 => Redemption.RedemptionRequest) timedOutRedemptions;
+        // The amount of ETH in wei the party challenging the wallet for fraud
+        // needs to deposit.
+        uint256 fraudChallengeDepositAmount;
+        // The amount of time the wallet has to defeat a fraud challenge.
+        uint256 fraudChallengeDefeatTimeout;
         // The amount of stake slashed from each member of a wallet for a fraud.
         uint96 fraudSlashingAmount;
         // The percentage of the notifier reward from the staking contract
         // the notifier of a fraud receives. The value is in the range [0, 100].
         uint256 fraudNotifierRewardMultiplier;
-        // The amount of time the wallet has to defeat a fraud challenge.
-        uint256 fraudChallengeDefeatTimeout;
-        // The amount of ETH in wei the party challenging the wallet for fraud
-        // needs to deposit.
-        uint256 fraudChallengeDepositAmount;
         // Collection of all submitted fraud challenges indexed by challenge
         // key built as `keccak256(walletPublicKey|sighash)`.
         mapping(uint256 => Fraud.FraudChallenge) fraudChallenges;
@@ -236,8 +259,11 @@ library BridgeState {
 
     event MovingFundsParametersUpdated(
         uint64 movingFundsTxMaxTotalFee,
+        uint64 movingFundsDustThreshold,
         uint32 movingFundsTimeout,
-        uint64 movingFundsDustThreshold
+        uint96 movingFundsTimeoutSlashingAmount,
+        uint256 movingFundsTimeoutNotifierRewardMultiplier,
+        uint64 movedFundsSweepTxMaxTotalFee
     );
 
     event WalletParametersUpdated(
@@ -251,10 +277,10 @@ library BridgeState {
     );
 
     event FraudParametersUpdated(
-        uint96 fraudSlashingAmount,
-        uint256 fraudNotifierRewardMultiplier,
+        uint256 fraudChallengeDepositAmount,
         uint256 fraudChallengeDefeatTimeout,
-        uint256 fraudChallengeDepositAmount
+        uint96 fraudSlashingAmount,
+        uint256 fraudNotifierRewardMultiplier
     );
 
     /// @notice Updates parameters of deposits.
@@ -416,50 +442,87 @@ library BridgeState {
     ///        BTC transaction fee that is acceptable in a single moving funds
     ///        transaction. This is a _total_ max fee for the entire moving
     ///        funds transaction.
-    /// @param _movingFundsTimeout New value of the moving funds timeout in
-    ///        seconds. It is the time after which the moving funds process can
-    ///        be reported as timed out. It is counted from the moment when the
-    ///        wallet was requested to move their funds and switched to the
-    ///        MovingFunds state.
     /// @param _movingFundsDustThreshold New value of the moving funds dust
     ///        threshold. It is the minimal satoshi amount that makes sense to
     //         be transferred during the moving funds process. Moving funds
     //         wallets having their BTC balance below that value can begin
     //         closing immediately as transferring such a low value may not be
     //         possible due to BTC network fees.
+    /// @param _movingFundsTimeout New value of the moving funds timeout in
+    ///        seconds. It is the time after which the moving funds process can
+    ///        be reported as timed out. It is counted from the moment when the
+    ///        wallet was requested to move their funds and switched to the
+    ///        MovingFunds state.
+    /// @param _movingFundsTimeoutSlashingAmount New value of the moving funds
+    ///        timeout slashing amount in T, it is the amount slashed from each
+    ///        wallet member for moving funds timeout
+    /// @param _movingFundsTimeoutNotifierRewardMultiplier New value of the
+    ///        moving funds timeout notifier reward multiplier as percentage,
+    ///        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.
     /// @dev Requirements:
     ///      - Moving funds transaction max total fee must be greater than zero
-    ///      - Moving funds timeout 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
     function updateMovingFundsParameters(
         Storage storage self,
         uint64 _movingFundsTxMaxTotalFee,
+        uint64 _movingFundsDustThreshold,
         uint32 _movingFundsTimeout,
-        uint64 _movingFundsDustThreshold
+        uint96 _movingFundsTimeoutSlashingAmount,
+        uint256 _movingFundsTimeoutNotifierRewardMultiplier,
+        uint64 _movedFundsSweepTxMaxTotalFee
     ) internal {
         require(
             _movingFundsTxMaxTotalFee > 0,
             "Moving funds transaction max total fee must be greater than zero"
         );
 
+        require(
+            _movingFundsDustThreshold > 0,
+            "Moving funds dust threshold must be greater than zero"
+        );
+
         require(
             _movingFundsTimeout > 0,
             "Moving funds timeout must be greater than zero"
         );
 
         require(
-            _movingFundsDustThreshold > 0,
-            "Moving funds dust threshold must be greater than zero"
+            _movingFundsTimeoutNotifierRewardMultiplier <= 100,
+            "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"
         );
 
         self.movingFundsTxMaxTotalFee = _movingFundsTxMaxTotalFee;
-        self.movingFundsTimeout = _movingFundsTimeout;
         self.movingFundsDustThreshold = _movingFundsDustThreshold;
+        self.movingFundsTimeout = _movingFundsTimeout;
+        self
+            .movingFundsTimeoutSlashingAmount = _movingFundsTimeoutSlashingAmount;
+        self
+            .movingFundsTimeoutNotifierRewardMultiplier = _movingFundsTimeoutNotifierRewardMultiplier;
+        self.movedFundsSweepTxMaxTotalFee = _movedFundsSweepTxMaxTotalFee;
 
         emit MovingFundsParametersUpdated(
             _movingFundsTxMaxTotalFee,
+            _movingFundsDustThreshold,
             _movingFundsTimeout,
-            _movingFundsDustThreshold
+            _movingFundsTimeoutSlashingAmount,
+            _movingFundsTimeoutNotifierRewardMultiplier,
+            _movedFundsSweepTxMaxTotalFee
         );
     }
 
@@ -536,6 +599,12 @@ library BridgeState {
     }
 
     /// @notice Updates parameters related to frauds.
+    /// @param _fraudChallengeDepositAmount New value of the fraud challenge
+    ///        deposit amount in wei, it is the amount of ETH the party
+    ///        challenging the wallet for fraud needs to deposit
+    /// @param _fraudChallengeDefeatTimeout New value of the challenge defeat
+    ///        timeout in seconds, it is the amount of time the wallet has to
+    ///        defeat a fraud challenge. The value must be greater than zero
     /// @param _fraudSlashingAmount New value of the fraud slashing amount in T,
     ///        it is the amount slashed from each wallet member for committing
     ///        a fraud
@@ -543,42 +612,36 @@ library BridgeState {
     ///        reward multiplier as percentage, it determines the percentage of
     ///        the notifier reward from the staking contact the notifier of
     ///        a fraud receives. The value must be in the range [0, 100]
-    /// @param _fraudChallengeDefeatTimeout New value of the challenge defeat
-    ///        timeout in seconds, it is the amount of time the wallet has to
-    ///        defeat a fraud challenge. The value must be greater than zero
-    /// @param _fraudChallengeDepositAmount New value of the fraud challenge
-    ///        deposit amount in wei, it is the amount of ETH the party
-    ///        challenging the wallet for fraud needs to deposit
     /// @dev Requirements:
-    ///      - Fraud notifier reward multiplier must be in the range [0, 100]
     ///      - Fraud challenge defeat timeout must be greater than 0
+    ///      - Fraud notifier reward multiplier must be in the range [0, 100]
     function updateFraudParameters(
         Storage storage self,
-        uint96 _fraudSlashingAmount,
-        uint256 _fraudNotifierRewardMultiplier,
+        uint256 _fraudChallengeDepositAmount,
         uint256 _fraudChallengeDefeatTimeout,
-        uint256 _fraudChallengeDepositAmount
+        uint96 _fraudSlashingAmount,
+        uint256 _fraudNotifierRewardMultiplier
     ) internal {
         require(
-            _fraudNotifierRewardMultiplier <= 100,
-            "Fraud notifier reward multiplier must be in the range [0, 100]"
+            _fraudChallengeDefeatTimeout > 0,
+            "Fraud challenge defeat timeout must be greater than zero"
         );
 
         require(
-            _fraudChallengeDefeatTimeout > 0,
-            "Fraud challenge defeat timeout must be greater than zero"
+            _fraudNotifierRewardMultiplier <= 100,
+            "Fraud notifier reward multiplier must be in the range [0, 100]"
         );
 
+        self.fraudChallengeDepositAmount = _fraudChallengeDepositAmount;
+        self.fraudChallengeDefeatTimeout = _fraudChallengeDefeatTimeout;
         self.fraudSlashingAmount = _fraudSlashingAmount;
         self.fraudNotifierRewardMultiplier = _fraudNotifierRewardMultiplier;
-        self.fraudChallengeDefeatTimeout = _fraudChallengeDefeatTimeout;
-        self.fraudChallengeDepositAmount = _fraudChallengeDepositAmount;
 
         emit FraudParametersUpdated(
-            _fraudSlashingAmount,
-            _fraudNotifierRewardMultiplier,
+            _fraudChallengeDepositAmount,
             _fraudChallengeDefeatTimeout,
-            _fraudChallengeDepositAmount
+            _fraudSlashingAmount,
+            _fraudNotifierRewardMultiplier
         );
     }
 }

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

package/contracts/bridge/Fraud.sol

@@ -277,7 +277,7 @@ library Fraud {
     ///        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.
+    ///        events of the `WalletRegistry` contract
     ///      - The amount of time indicated by `challengeDefeatTimeout` must pass
     ///        after the challenge was reported
     function notifyFraudChallengeDefeatTimeout(