@keep-network/tbtc-v2 0.1.1-dev.60 → 0.1.1-dev.63

package/contracts/bridge/Bridge.sol

@@ -844,8 +844,8 @@ contract Bridge is Governable, EcdsaWalletOwner {
     ///         to protocol rules. To prevent spurious allegations, the caller
     ///         must deposit ETH that is returned back upon justified fraud
     ///         challenge or confiscated otherwise.
-    ///@param walletPublicKey The public key of the wallet in the uncompressed
-    ///       and unprefixed format (64 bytes)
+    /// @param walletPublicKey The public key of the wallet in the uncompressed
+    ///        and unprefixed format (64 bytes)
     /// @param sighash The hash that was used to produce the ECDSA signature
     ///        that is the subject of the fraud claim. This hash is constructed
     ///        by applying double SHA-256 over a serialized subset of the
@@ -905,6 +905,38 @@ contract Bridge is Governable, EcdsaWalletOwner {
         self.defeatFraudChallenge(walletPublicKey, preimage, witness);
     }
 
+    /// @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(
+        bytes calldata walletPublicKey,
+        bytes calldata heartbeatMessage
+    ) external {
+        self.defeatFraudChallengeWithHeartbeat(
+            walletPublicKey,
+            heartbeatMessage
+        );
+    }
+
     /// @notice Notifies about defeat timeout for the given fraud challenge.
     ///         Can be called only if there was a fraud challenge identified by
     ///         the provided `walletPublicKey` and `sighash` and it was not

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

@@ -0,0 +1,112 @@
+// SPDX-License-Identifier: MIT
+
+// ██████████████     ▐████▌     ██████████████
+// ██████████████     ▐████▌     ██████████████
+//               ▐████▌    ▐████▌
+//               ▐████▌    ▐████▌
+// ██████████████     ▐████▌     ██████████████
+// ██████████████     ▐████▌     ██████████████
+//               ▐████▌    ▐████▌
+//               ▐████▌    ▐████▌
+//               ▐████▌    ▐████▌
+//               ▐████▌    ▐████▌
+//               ▐████▌    ▐████▌
+//               ▐████▌    ▐████▌
+
+pragma solidity ^0.8.9;
+
+import {BytesLib} from "@keep-network/bitcoin-spv-sol/contracts/BytesLib.sol";
+
+/// @title Bridge wallet heartbeat
+/// @notice The library establishes expected format for heartbeat messages
+///         signed by wallet ECDSA signing group. Heartbeat messages are
+///         constructed in such a way that they can not be used as a Bitcoin
+///         transaction preimages.
+/// @dev The smallest Bitcoin non-coinbase transaction is a one spending an
+///      OP_TRUE anyonecanspend output and creating 1 OP_TRUE anyonecanspend
+///      output. Such a transaction has 61 bytes (see `BitcoinTx` documentation):
+///        4  bytes  for version
+///        1  byte   for tx_in_count
+///        36 bytes  for tx_in.previous_output
+///        1  byte   for tx_in.script_bytes (value: 0)
+///        0  bytes  for tx_in.signature_script
+///        4  bytes  for tx_in.sequence
+///        1  byte   for tx_out_count
+///        8  bytes  for tx_out.value
+///        1  byte   for tx_out.pk_script_bytes
+///        1  byte   for tx_out.pk_script
+///        4  bytes  for lock_time
+///
+///
+///      The smallest Bitcoin coinbase transaction is a one creating
+///      1 OP_TRUE anyonecanspend output and having an empty coinbase script.
+///      Such a transaction has 65 bytes:
+///        4  bytes  for version
+///        1  byte   for tx_in_count
+///        32 bytes  for tx_in.hash  (all 0x00)
+///        4  bytes  for tx_in.index (all 0xff)
+///        1  byte   for tx_in.script_bytes (value: 0)
+///        4  bytes  for tx_in.height
+///        0  byte   for tx_in.coinbase_script
+///        4  bytes  for tx_in.sequence
+///        1  byte   for tx_out_count
+///        8  bytes  for tx_out.value
+///        1  byte   for tx_out.pk_script_bytes
+///        1  byte   for tx_out.pk_script
+///        4  bytes  for lock_time
+///
+///
+///      A SIGHASH flag is used to indicate which part of the transaction is
+///      signed by the ECDSA signature. There are currently 3 flags:
+///      SIGHASH_ALL, SIGHASH_NONE, SIGHASH_SINGLE, and different combinations
+///      of these flags.
+///
+///      No matter the SIGHASH flag and no matter the combination, the following
+///      fields from the transaction are always included in the constructed
+///      preimage:
+///        4  bytes  for version
+///        36 bytes  for tx_in.previous_output (or tx_in.hash + tx_in.index for coinbase)
+///        4  bytes  for lock_time
+///
+///      Additionally, the last 4 bytes of the preimage determines the SIGHASH
+///      flag.
+///
+///      This is enough to say there is no way the preimage could be shorter
+///      than 4 + 36 + 4 + 4 = 48 bytes.
+///
+///      For this reason, we construct the heartbeat message, as a 16-byte
+///      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;
+
+    /// @notice Determines if the signed byte array is a valid, non-fraudulent
+    ///         heartbeat message.
+    /// @param message Message signed by the wallet. It is a potential heartbeat
+    ///        message, Bitcoin transaction preimage, or an arbitrary signed
+    ///        bytes
+    /// @dev Wallet heartbeat message must be exactly 16 bytes long with the first
+    ///      8 bytes set to 0xffffffffffffffff.
+    /// @return True if valid heartbeat message, false otherwise.
+    function isValidHeartbeatMessage(bytes calldata message)
+        internal
+        pure
+        returns (bool)
+    {
+        if (message.length != 16) {
+            return false;
+        }
+
+        if (message.slice8(0) != 0xffffffffffffffff) {
+            return false;
+        }
+
+        return true;
+    }
+}

package/contracts/vault/DonationVault.sol

@@ -0,0 +1,125 @@
+// SPDX-License-Identifier: MIT
+
+// ██████████████     ▐████▌     ██████████████
+// ██████████████     ▐████▌     ██████████████
+//               ▐████▌    ▐████▌
+//               ▐████▌    ▐████▌
+// ██████████████     ▐████▌     ██████████████
+// ██████████████     ▐████▌     ██████████████
+//               ▐████▌    ▐████▌
+//               ▐████▌    ▐████▌
+//               ▐████▌    ▐████▌
+//               ▐████▌    ▐████▌
+//               ▐████▌    ▐████▌
+//               ▐████▌    ▐████▌
+
+pragma solidity ^0.8.9;
+
+import "./IVault.sol";
+import "../bank/Bank.sol";
+
+/// @title BTC donation vault
+/// @notice Vault that allows making BTC donations to the system. Upon deposit,
+///         this vault does not increase depositors' balances and always
+///         decreases its own balance in the same transaction. The vault also
+///         allows making donations using existing Bank balances.
+///
+///         BEWARE: ALL BTC DEPOSITS TARGETING THIS VAULT ARE NOT REDEEMABLE
+///         AND THERE IS NO WAY TO RESTORE THE DONATED BALANCE.
+///         USE THIS VAULT ONLY WHEN YOU REALLY KNOW WHAT YOU ARE DOING!
+contract DonationVault is IVault {
+    Bank public bank;
+
+    event DonationReceived(address donor, uint256 donatedAmount);
+
+    modifier onlyBank() {
+        require(msg.sender == address(bank), "Caller is not the Bank");
+        _;
+    }
+
+    constructor(Bank _bank) {
+        require(
+            address(_bank) != address(0),
+            "Bank can not be the zero address"
+        );
+
+        bank = _bank;
+    }
+
+    /// @notice Transfers the given `amount` of the Bank balance from the
+    ///         caller to the Donation Vault and immediately decreases the
+    ///         vault's balance in the Bank by the transferred `amount`.
+    /// @param amount Amount of the Bank balance to donate
+    /// @dev Requirements:
+    ///      - The caller's balance in the Bank must be greater than or equal
+    ///        to the `amount`.
+    ///      - Donation Vault must have an allowance for caller's balance in
+    ///        the Bank for at least `amount`.
+    function donate(uint256 amount) external {
+        address donor = msg.sender;
+
+        require(
+            bank.balanceOf(donor) >= amount,
+            "Amount exceeds balance in the bank"
+        );
+
+        emit DonationReceived(donor, amount);
+
+        bank.transferBalanceFrom(donor, address(this), amount);
+        bank.decreaseBalance(amount);
+    }
+
+    /// @notice Transfers the given `amount` of the Bank balance from the
+    ///         `owner` to the Donation Vault and immediately decreases the
+    ///         vault's balance in the Bank by the transferred `amount`.
+    /// @param owner Address of the Bank balance owner who approved their
+    ///        balance to be used by the vault
+    /// @param amount The amount of the Bank balance approved by the owner
+    ///        to be used by the vault
+    /// @dev Requirements:
+    ///      - Can only be called by the Bank via `approveBalanceAndCall`.
+    ///      - The `owner` balance in the Bank must be greater than or equal
+    ///        to the `amount`.
+    function receiveBalanceApproval(address owner, uint256 amount)
+        external
+        override
+        onlyBank
+    {
+        require(
+            bank.balanceOf(owner) >= amount,
+            "Amount exceeds balance in the bank"
+        );
+
+        emit DonationReceived(owner, amount);
+
+        bank.transferBalanceFrom(owner, address(this), amount);
+        bank.decreaseBalance(amount);
+    }
+
+    /// @notice Ignores the deposited amounts and does not increase depositors'
+    ///         individual balances. The vault decreases its own tBTC balance
+    ///         in the Bank by the total deposited amount.
+    /// @param depositors Addresses of depositors whose deposits have been swept
+    /// @param depositedAmounts Amounts deposited by individual depositors and
+    ///        swept
+    /// @dev Requirements:
+    ///      - Can only be called by the Bank after the Bridge swept deposits
+    ///        and Bank increased balance for the vault.
+    ///      - The `depositors` array must not be empty.
+    ///      - The `depositors` array length must be equal to the
+    ///        `depositedAmounts` array length.
+    function receiveBalanceIncrease(
+        address[] calldata depositors,
+        uint256[] calldata depositedAmounts
+    ) external override onlyBank {
+        require(depositors.length != 0, "No depositors specified");
+
+        uint256 totalAmount = 0;
+        for (uint256 i = 0; i < depositors.length; i++) {
+            totalAmount += depositedAmounts[i];
+            emit DonationReceived(depositors[i], depositedAmounts[i]);
+        }
+
+        bank.decreaseBalance(totalAmount);
+    }
+}

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",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@keep-network/tbtc-v2",
-  "version": "0.1.1-dev.60+main.89dbb465ebef3bee9f0d8ff369d3b0b8cde22427",
+  "version": "0.1.1-dev.63+main.68e692f8fe53043af3c81bd88afd16954759ad5d",
   "license": "MIT",
   "files": [
     "artifacts/",