@keep-network/tbtc-v2 0.1.1-dev.62 → 0.1.1-dev.65

package/contracts/bridge/DepositSweep.sol

@@ -39,6 +39,29 @@ library DepositSweep {
 
     using BTCUtils for bytes;
 
+    /// @notice Represents temporary information needed during the processing
+    ///         of the deposit sweep Bitcoin transaction inputs. This structure
+    ///         is an internal one and should not be exported outside of the
+    ///         deposit sweep transaction processing code.
+    /// @dev Allows to mitigate "stack too deep" errors on EVM.
+    struct DepositSweepTxInputsProcessingInfo {
+        // Input vector of the deposit sweep Bitcoin transaction. It is
+        // assumed the vector's structure is valid so it must be validated
+        // using e.g. `BTCUtils.validateVin` function before being used
+        // during the processing. The validation is usually done as part
+        // of the `BitcoinTx.validateProof` call that checks the SPV proof.
+        bytes sweepTxInputVector;
+        // Data of the wallet's main UTXO. If no main UTXO exists for the given
+        // sweeping wallet, this parameter's fields should be zeroed to bypass
+        // the main UTXO validation
+        BitcoinTx.UTXO mainUtxo;
+        // Address of the vault where all swept deposits should be routed to.
+        // It is used to validate whether all swept deposits have been revealed
+        // with the same `vault` parameter. It is an optional parameter.
+        // Set to zero address if deposits are not routed to a vault.
+        address vault;
+    }
+
     /// @notice Represents an outcome of the sweep Bitcoin transaction
     ///         inputs processing.
     struct DepositSweepTxInputsInfo {
@@ -83,6 +106,15 @@ library DepositSweep {
     /// @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
+    /// @param vault Optional address of the vault where all swept deposits
+    ///        should be routed to. All deposits swept as part of the transaction
+    ///        must have their `vault` parameters set to the same address.
+    ///        If this parameter is set to an address of a trusted vault, swept
+    ///        deposits are routed to that vault.
+    ///        If this parameter is set to the zero address or to an address
+    ///        of a non-trusted vault, swept deposits are not routed to a
+    ///        vault but depositors' balances are increased in the Bank
+    ///        individually.
     /// @dev Requirements:
     ///      - `sweepTx` components must match the expected structure. See
     ///        `BitcoinTx.Info` docs for reference. Their values must exactly
@@ -96,6 +128,9 @@ library DepositSweep {
     ///        revealed deposits UTXOs. That transaction must have only
     ///        one P2(W)PKH output locking funds on the 20-byte wallet public
     ///        key hash.
+    ///      - All revealed deposits that are swept by `sweepTx` must have
+    ///        their `vault` parameters set to the same address as the address
+    ///        passed in the `vault` function parameter.
     ///      - `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
@@ -107,7 +142,8 @@ library DepositSweep {
         BridgeState.Storage storage self,
         BitcoinTx.Info calldata sweepTx,
         BitcoinTx.Proof calldata sweepProof,
-        BitcoinTx.UTXO calldata mainUtxo
+        BitcoinTx.UTXO calldata mainUtxo,
+        address vault
     ) external {
         // The actual transaction proof is performed here. After that point, we
         // can assume the transaction happened on Bitcoin chain and has
@@ -132,8 +168,11 @@ library DepositSweep {
         DepositSweepTxInputsInfo
             memory inputsInfo = processDepositSweepTxInputs(
                 self,
-                sweepTx.inputVector,
-                resolvedMainUtxo
+                DepositSweepTxInputsProcessingInfo(
+                    sweepTx.inputVector,
+                    resolvedMainUtxo,
+                    vault
+                )
             );
 
         // Helper variable that will hold the sum of treasury fees paid by
@@ -189,15 +228,26 @@ library DepositSweep {
         // slither-disable-next-line reentrancy-events
         emit DepositsSwept(walletPubKeyHash, sweepTxHash);
 
-        // Update depositors balances in the Bank.
-        self.bank.increaseBalances(
-            inputsInfo.depositors,
-            inputsInfo.depositedAmounts
-        );
+        if (vault != address(0) && self.isVaultTrusted[vault]) {
+            // If the `vault` address is not zero and belongs to a trusted
+            // vault, route the deposits to that vault.
+            self.bank.increaseBalanceAndCall(
+                vault,
+                inputsInfo.depositors,
+                inputsInfo.depositedAmounts
+            );
+        } else {
+            // If the `vault` address is zero or belongs to a non-trusted
+            // vault, increase balances in the Bank individually for each
+            // depositor.
+            self.bank.increaseBalances(
+                inputsInfo.depositors,
+                inputsInfo.depositedAmounts
+            );
+        }
+
         // Pass the treasury fee to the treasury address.
         self.bank.increaseBalance(self.treasury, totalTreasuryFee);
-
-        // TODO: Handle deposits having `vault` set.
     }
 
     /// @notice Resolves sweeping wallet based on the provided wallet public key
@@ -299,32 +349,23 @@ library DepositSweep {
     ///         if one of the inputs cannot be recognized as a pointer to a
     ///         revealed deposit or expected main UTXO.
     ///         This function also marks each processed deposit as swept.
-    /// @param sweepTxInputVector Bitcoin sweep transaction input vector.
-    ///        This function assumes vector's structure is valid so it must be
-    ///        validated using e.g. `BTCUtils.validateVin` function before
-    ///        it is passed here
-    /// @param mainUtxo Data of the wallet's main UTXO. If no main UTXO
-    ///        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.
+    /// @return resultInfo Outcomes of the processing.
     function processDepositSweepTxInputs(
         BridgeState.Storage storage self,
-        bytes memory sweepTxInputVector,
-        BitcoinTx.UTXO memory mainUtxo
-    ) internal returns (DepositSweepTxInputsInfo memory info) {
+        DepositSweepTxInputsProcessingInfo memory processInfo
+    ) internal returns (DepositSweepTxInputsInfo memory resultInfo) {
         // 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.
-        bool mainUtxoExpected = mainUtxo.txHash != bytes32(0);
+        bool mainUtxoExpected = processInfo.mainUtxo.txHash != bytes32(0);
         bool mainUtxoFound = false;
 
         // Determining the total number of sweep transaction inputs in the same
         // way as for number of outputs. See `BitcoinTx.inputVector` docs for
         // more details.
-        (
-            uint256 inputsCompactSizeUintLength,
-            uint256 inputsCount
-        ) = sweepTxInputVector.parseVarInt();
+        (uint256 inputsCompactSizeUintLength, uint256 inputsCount) = processInfo
+            .sweepTxInputVector
+            .parseVarInt();
 
         // To determine the first input starting index, we must jump over
         // the compactSize uint which prepends the input vector. One byte
@@ -346,11 +387,13 @@ library DepositSweep {
         // Determine the swept deposits count. If main UTXO is NOT expected,
         // all inputs should be deposits. If main UTXO is expected, one input
         // should point to that main UTXO.
-        info.depositors = new address[](
+        resultInfo.depositors = new address[](
             !mainUtxoExpected ? inputsCount : inputsCount - 1
         );
-        info.depositedAmounts = new uint256[](info.depositors.length);
-        info.treasuryFees = new uint256[](info.depositors.length);
+        resultInfo.depositedAmounts = new uint256[](
+            resultInfo.depositors.length
+        );
+        resultInfo.treasuryFees = new uint256[](resultInfo.depositors.length);
 
         // Initialize helper variables.
         uint256 processedDepositsCount = 0;
@@ -362,7 +405,7 @@ library DepositSweep {
                 uint32 outpointIndex,
                 uint256 inputLength
             ) = parseDepositSweepTxInputAt(
-                    sweepTxInputVector,
+                    processInfo.sweepTxInputVector,
                     inputStartingIndex
                 );
 
@@ -377,7 +420,12 @@ library DepositSweep {
                 // a revealed deposit.
                 require(deposit.sweptAt == 0, "Deposit already swept");
 
-                if (processedDepositsCount == info.depositors.length) {
+                require(
+                    deposit.vault == processInfo.vault,
+                    "Deposit should be routed to another vault"
+                );
+
+                if (processedDepositsCount == resultInfo.depositors.length) {
                     // If this condition is true, that means a deposit input
                     // took place of an expected main UTXO input.
                     // In other words, there is no expected main UTXO
@@ -390,22 +438,27 @@ library DepositSweep {
                 /* solhint-disable-next-line not-rely-on-time */
                 deposit.sweptAt = uint32(block.timestamp);
 
-                info.depositors[processedDepositsCount] = deposit.depositor;
-                info.depositedAmounts[processedDepositsCount] = deposit.amount;
-                info.inputsTotalValue += info.depositedAmounts[
+                resultInfo.depositors[processedDepositsCount] = deposit
+                    .depositor;
+                resultInfo.depositedAmounts[processedDepositsCount] = deposit
+                    .amount;
+                resultInfo.inputsTotalValue += resultInfo.depositedAmounts[
                     processedDepositsCount
                 ];
-                info.treasuryFees[processedDepositsCount] = deposit.treasuryFee;
+                resultInfo.treasuryFees[processedDepositsCount] = deposit
+                    .treasuryFee;
 
                 processedDepositsCount++;
             } else if (
                 mainUtxoExpected != mainUtxoFound &&
-                mainUtxo.txHash == outpointTxHash &&
-                mainUtxo.txOutputIndex == outpointIndex
+                processInfo.mainUtxo.txHash == outpointTxHash &&
+                processInfo.mainUtxo.txOutputIndex == outpointIndex
             ) {
                 // If we entered here, that means the input was identified as
                 // the expected main UTXO.
-                info.inputsTotalValue += mainUtxo.txOutputValue;
+                resultInfo.inputsTotalValue += processInfo
+                    .mainUtxo
+                    .txOutputValue;
                 mainUtxoFound = true;
 
                 // Main UTXO used as an input, mark it as spent.
@@ -426,7 +479,7 @@ library DepositSweep {
         }
 
         // Construction of the input processing loop guarantees that:
-        // `processedDepositsCount == info.depositors.length == info.depositedAmounts.length`
+        // `processedDepositsCount == resultInfo.depositors.length == resultInfo.depositedAmounts.length`
         // is always true at this point. We just use the first variable
         // to assert the total count of swept deposit is bigger than zero.
         require(
@@ -441,7 +494,7 @@ library DepositSweep {
             "Expected main UTXO not present in sweep transaction inputs"
         );
 
-        return info;
+        return resultInfo;
     }
 
     /// @notice Parses a Bitcoin transaction input starting at the given index.

package/contracts/bridge/Fraud.sol

@@ -22,6 +22,7 @@ import {CheckBitcoinSigs} from "@keep-network/bitcoin-spv-sol/contracts/CheckBit
 import "./BitcoinTx.sol";
 import "./EcdsaLib.sol";
 import "./BridgeState.sol";
+import "./Heartbeat.sol";
 import "./MovingFunds.sol";
 import "./Wallets.sol";
 
@@ -38,10 +39,18 @@ import "./Wallets.sol";
 ///      signature must be provided as were used to calculate the sighash during
 ///      the challenge. The wallet provides the preimage which produces sighash
 ///      used to generate the ECDSA signature that is the subject of the fraud
-///      claim. The fraud challenge defeat attempt will only succeed if the
-///      inputs in the preimage are considered honestly spent by the wallet.
-///      Therefore the transaction spending the UTXO must be proven in the
-///      Bridge before a challenge defeat is called.
+///      claim.
+///
+///      The fraud challenge defeat attempt will succeed if the inputs in the
+///      preimage are considered honestly spent by the wallet. Therefore the
+///      transaction spending the UTXO must be proven in the Bridge before
+///      a challenge defeat is called.
+///
+///      Another option is when a malicious wallet member used a signed heartbeat
+///      message periodically produced by the wallet off-chain to challenge the
+///      wallet for a fraud. Anyone from the wallet can defeat the challenge by
+///      proving the sighash and signature were produced for a heartbeat message
+///      following a strict format.
 library Fraud {
     using Wallets for BridgeState.Storage;
 
@@ -73,6 +82,10 @@ library Fraud {
 
     event FraudChallengeDefeatTimedOut(
         bytes20 walletPubKeyHash,
+        // Sighash calculated as a Bitcoin's hash256 (double sha2) of:
+        // - a preimage of a transaction spending UTXO according to the protocol
+        //   rules OR
+        // - a valid heartbeat message produced by the wallet off-chain.
         bytes32 sighash
     );
 
@@ -234,6 +247,69 @@ library Fraud {
             "Spent UTXO not found among correctly spent UTXOs"
         );
 
+        resolveFraudChallenge(self, walletPublicKey, challenge, sighash);
+    }
+
+    /// @notice Allows to defeat a pending fraud challenge against a wallet by
+    ///         proving the sighash and signature were produced for an off-chain
+    ///         wallet heartbeat message following a strict format.
+    ///         In order to defeat the challenge the same `walletPublicKey` and
+    ///         signature (represented by `r`, `s` and `v`) must be provided as
+    ///         were used to calculate the sighash during heartbeat message
+    ///         signing. The fraud challenge defeat attempt will only succeed if
+    ///         the signed message follows a strict format required for
+    ///         heartbeat messages. If successfully defeated, the fraud
+    ///         challenge is marked as resolved and the amount of ether
+    ///         deposited by the challenger is sent to the treasury.
+    /// @param walletPublicKey The public key of the wallet in the uncompressed
+    ///        and unprefixed format (64 bytes)
+    /// @param heartbeatMessage Off-chain heartbeat message meeting the heartbeat
+    ///        message format requirements which produces sighash used to
+    ///        generate the ECDSA signature that is the subject of the fraud
+    ///        claim
+    /// @dev Requirements:
+    ///      - `walletPublicKey` and `sighash` calculated as
+    ///        `hash256(heartbeatMessage)` must identify an open fraud challenge
+    ///      - `heartbeatMessage` must follow a strict format of heartbeat
+    ///        messages
+    function defeatFraudChallengeWithHeartbeat(
+        BridgeState.Storage storage self,
+        bytes calldata walletPublicKey,
+        bytes calldata heartbeatMessage
+    ) external {
+        bytes32 sighash = heartbeatMessage.hash256();
+
+        uint256 challengeKey = uint256(
+            keccak256(abi.encodePacked(walletPublicKey, sighash))
+        );
+
+        FraudChallenge storage challenge = self.fraudChallenges[challengeKey];
+
+        require(challenge.reportedAt > 0, "Fraud challenge does not exist");
+        require(
+            !challenge.resolved,
+            "Fraud challenge has already been resolved"
+        );
+
+        require(
+            Heartbeat.isValidHeartbeatMessage(heartbeatMessage),
+            "Not a valid heartbeat message"
+        );
+
+        resolveFraudChallenge(self, walletPublicKey, challenge, sighash);
+    }
+
+    /// @notice Called only for successfully defeated fraud challenges.
+    ///         The fraud challenge is marked as resolved and the amount of
+    ///         ether deposited by the challenger is sent to the treasury.
+    /// @dev Requirements:
+    ///      - Must be called only for successfully defeated fraud challenges.
+    function resolveFraudChallenge(
+        BridgeState.Storage storage self,
+        bytes calldata walletPublicKey,
+        FraudChallenge storage challenge,
+        bytes32 sighash
+    ) internal {
         // Mark the challenge as resolved as it was successfully defeated
         challenge.resolved = true;
 
@@ -248,6 +324,7 @@ library Fraud {
             walletPublicKey.slice32(32)
         );
         bytes20 walletPubKeyHash = compressedWalletPublicKey.hash160View();
+
         // slither-disable-next-line reentrancy-events
         emit FraudChallengeDefeated(walletPubKeyHash, sighash);
     }

package/contracts/bridge/Heartbeat.sol

@@ -78,6 +78,11 @@ import {BytesLib} from "@keep-network/bitcoin-spv-sol/contracts/BytesLib.sol";
 ///      message. The first 8 bytes are 0xffffffffffffffff. The last 8 bytes
 ///      are for an arbitrary uint64, being a signed heartbeat nonce (for
 ///      example, the last Ethereum block hash).
+///
+///      The message being signed by the wallet when executing the heartbeat
+///      protocol should be Bitcoin's hash256 (double SHA-256) of the heartbeat
+///      message:
+///        heartbeat_sighash = hash256(heartbeat_message)
 library Heartbeat {
     using BytesLib for bytes;
 

package/contracts/bridge/Redemption.sol

@@ -825,7 +825,6 @@ library Redemption {
             request.treasuryFee;
 
         require(
-            // TODO: Allow the wallets in `Closing` state when the state is added
             wallet.state == Wallets.WalletState.Live ||
                 wallet.state == Wallets.WalletState.MovingFunds ||
                 wallet.state == Wallets.WalletState.Terminated,

package/export.json

@@ -14871,6 +14871,24 @@
           "stateMutability": "nonpayable",
           "type": "function"
         },
+        {
+          "inputs": [
+            {
+              "internalType": "bytes",
+              "name": "walletPublicKey",
+              "type": "bytes"
+            },
+            {
+              "internalType": "bytes",
+              "name": "heartbeatMessage",
+              "type": "bytes"
+            }
+          ],
+          "name": "defeatFraudChallengeWithHeartbeat",
+          "outputs": [],
+          "stateMutability": "nonpayable",
+          "type": "function"
+        },
         {
           "inputs": [],
           "name": "depositParameters",
@@ -16019,6 +16037,11 @@
               "internalType": "struct BitcoinTx.UTXO",
               "name": "mainUtxo",
               "type": "tuple"
+            },
+            {
+              "internalType": "address",
+              "name": "vault",
+              "type": "address"
             }
           ],
           "name": "submitDepositSweepProof",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@keep-network/tbtc-v2",
-  "version": "0.1.1-dev.62+main.0b72875d1c74fabf79b85822aa47ac160f8b4c92",
+  "version": "0.1.1-dev.65+main.ad746e2ab0fb8878671f7ff1ebc591c4765fdff5",
   "license": "MIT",
   "files": [
     "artifacts/",