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

package/contracts/bridge/Deposit.sol

@@ -0,0 +1,266 @@
+// SPDX-License-Identifier: MIT
+
+// ██████████████     ▐████▌     ██████████████
+// ██████████████     ▐████▌     ██████████████
+//               ▐████▌    ▐████▌
+//               ▐████▌    ▐████▌
+// ██████████████     ▐████▌     ██████████████
+// ██████████████     ▐████▌     ██████████████
+//               ▐████▌    ▐████▌
+//               ▐████▌    ▐████▌
+//               ▐████▌    ▐████▌
+//               ▐████▌    ▐████▌
+//               ▐████▌    ▐████▌
+//               ▐████▌    ▐████▌
+
+pragma solidity ^0.8.9;
+
+import {BTCUtils} from "@keep-network/bitcoin-spv-sol/contracts/BTCUtils.sol";
+import {BytesLib} from "@keep-network/bitcoin-spv-sol/contracts/BytesLib.sol";
+
+import "./BitcoinTx.sol";
+import "./BridgeState.sol";
+import "./Wallets.sol";
+
+/// @title Bridge deposit
+/// @notice The library handles the logic for revealing Bitcoin deposits to
+///         the Bridge.
+/// @dev The depositor puts together a P2SH or P2WSH address to deposit the
+///      funds. This script is unique to each depositor and looks like this:
+///
+///      ```
+///      <depositorAddress> DROP
+///      <blindingFactor> DROP
+///      DUP HASH160 <walletPubKeyHash> EQUAL
+///      IF
+///        CHECKSIG
+///      ELSE
+///        DUP HASH160 <refundPubkeyHash> EQUALVERIFY
+///        <refundLocktime> CHECKLOCKTIMEVERIFY DROP
+///        CHECKSIG
+///      ENDIF
+///      ```
+///
+///      Since each depositor has their own Ethereum address and their own
+///      secret blinding factor, each depositor’s script is unique, and the hash
+///      of each depositor’s script is unique.
+library Deposit {
+    using BTCUtils for bytes;
+    using BytesLib for bytes;
+
+    /// @notice Represents data which must be revealed by the depositor during
+    ///         deposit reveal.
+    struct DepositRevealInfo {
+        // Index of the funding output belonging to the funding transaction.
+        uint32 fundingOutputIndex;
+        // Ethereum depositor address.
+        address depositor;
+        // The blinding factor as 8 bytes. Byte endianness doesn't matter
+        // as this factor is not interpreted as uint.
+        bytes8 blindingFactor;
+        // The compressed Bitcoin public key (33 bytes and 02 or 03 prefix)
+        // of the deposit's wallet hashed in the HASH160 Bitcoin opcode style.
+        bytes20 walletPubKeyHash;
+        // The compressed Bitcoin public key (33 bytes and 02 or 03 prefix)
+        // that can be used to make the deposit refund after the refund
+        // locktime passes. Hashed in the HASH160 Bitcoin opcode style.
+        bytes20 refundPubKeyHash;
+        // The refund locktime (4-byte LE). Interpreted according to locktime
+        // parsing rules described in:
+        // https://developer.bitcoin.org/devguide/transactions.html#locktime-and-sequence-number
+        // and used with OP_CHECKLOCKTIMEVERIFY opcode as described in:
+        // https://github.com/bitcoin/bips/blob/master/bip-0065.mediawiki
+        bytes4 refundLocktime;
+        // Address of the Bank vault to which the deposit is routed to.
+        // Optional, can be 0x0. The vault must be trusted by the Bridge.
+        address vault;
+    }
+
+    /// @notice Represents tBTC deposit request data.
+    struct DepositRequest {
+        // Ethereum depositor address.
+        address depositor;
+        // Deposit amount in satoshi.
+        uint64 amount;
+        // UNIX timestamp the deposit was revealed at.
+        uint32 revealedAt;
+        // Address of the Bank vault the deposit is routed to.
+        // Optional, can be 0x0.
+        address vault;
+        // Treasury TBTC fee in satoshi at the moment of deposit reveal.
+        uint64 treasuryFee;
+        // UNIX timestamp the deposit was swept at. Note this is not the
+        // time when the deposit was swept on the Bitcoin chain but actually
+        // the time when the sweep proof was delivered to the Ethereum chain.
+        uint32 sweptAt;
+    }
+
+    event DepositRevealed(
+        bytes32 fundingTxHash,
+        uint32 fundingOutputIndex,
+        address depositor,
+        uint64 amount,
+        bytes8 blindingFactor,
+        bytes20 walletPubKeyHash,
+        bytes20 refundPubKeyHash,
+        bytes4 refundLocktime,
+        address vault
+    );
+
+    /// @notice Used by the depositor to reveal information about their P2(W)SH
+    ///         Bitcoin deposit to the Bridge on Ethereum chain. The off-chain
+    ///         wallet listens for revealed deposit events and may decide to
+    ///         include the revealed deposit in the next executed sweep.
+    ///         Information about the Bitcoin deposit can be revealed before or
+    ///         after the Bitcoin transaction with P2(W)SH deposit is mined on
+    ///         the Bitcoin chain. Worth noting, the gas cost of this function
+    ///         scales with the number of P2(W)SH transaction inputs and
+    ///         outputs. The deposit may be routed to one of the trusted vaults.
+    ///         When a deposit is routed to a vault, vault gets notified when
+    ///         the deposit gets swept and it may execute the appropriate action.
+    /// @param fundingTx Bitcoin funding transaction data, see `BitcoinTx.Info`
+    /// @param reveal Deposit reveal data, see `RevealInfo struct
+    /// @dev Requirements:
+    ///      - `reveal.walletPubKeyHash` must identify a `Live` wallet
+    ///      - `reveal.vault` must be 0x0 or point to a trusted vault
+    ///      - `reveal.fundingOutputIndex` must point to the actual P2(W)SH
+    ///        output of the BTC deposit transaction
+    ///      - `reveal.depositor` must be the Ethereum address used in the
+    ///        P2(W)SH BTC deposit transaction,
+    ///      - `reveal.blindingFactor` must be the blinding factor used in the
+    ///        P2(W)SH BTC deposit transaction,
+    ///      - `reveal.walletPubKeyHash` must be the wallet pub key hash used in
+    ///        the P2(W)SH BTC deposit transaction,
+    ///      - `reveal.refundPubKeyHash` must be the refund pub key hash used in
+    ///        the P2(W)SH BTC deposit transaction,
+    ///      - `reveal.refundLocktime` must be the refund locktime used in the
+    ///        P2(W)SH BTC deposit transaction,
+    ///      - BTC deposit for the given `fundingTxHash`, `fundingOutputIndex`
+    ///        can be revealed only one time.
+    ///
+    ///      If any of these requirements is not met, the wallet _must_ refuse
+    ///      to sweep the deposit and the depositor has to wait until the
+    ///      deposit script unlocks to receive their BTC back.
+    function revealDeposit(
+        BridgeState.Storage storage self,
+        BitcoinTx.Info calldata fundingTx,
+        DepositRevealInfo calldata reveal
+    ) external {
+        require(
+            self.registeredWallets[reveal.walletPubKeyHash].state ==
+                Wallets.WalletState.Live,
+            "Wallet must be in Live state"
+        );
+
+        require(
+            reveal.vault == address(0) || self.isVaultTrusted[reveal.vault],
+            "Vault is not trusted"
+        );
+
+        // TODO: Should we enforce a specific locktime at contract level?
+
+        bytes memory expectedScript = abi.encodePacked(
+            hex"14", // Byte length of depositor Ethereum address.
+            reveal.depositor,
+            hex"75", // OP_DROP
+            hex"08", // Byte length of blinding factor value.
+            reveal.blindingFactor,
+            hex"75", // OP_DROP
+            hex"76", // OP_DUP
+            hex"a9", // OP_HASH160
+            hex"14", // Byte length of a compressed Bitcoin public key hash.
+            reveal.walletPubKeyHash,
+            hex"87", // OP_EQUAL
+            hex"63", // OP_IF
+            hex"ac", // OP_CHECKSIG
+            hex"67", // OP_ELSE
+            hex"76", // OP_DUP
+            hex"a9", // OP_HASH160
+            hex"14", // Byte length of a compressed Bitcoin public key hash.
+            reveal.refundPubKeyHash,
+            hex"88", // OP_EQUALVERIFY
+            hex"04", // Byte length of refund locktime value.
+            reveal.refundLocktime,
+            hex"b1", // OP_CHECKLOCKTIMEVERIFY
+            hex"75", // OP_DROP
+            hex"ac", // OP_CHECKSIG
+            hex"68" // OP_ENDIF
+        );
+
+        bytes memory fundingOutput = fundingTx
+            .outputVector
+            .extractOutputAtIndex(reveal.fundingOutputIndex);
+        bytes memory fundingOutputHash = fundingOutput.extractHash();
+
+        if (fundingOutputHash.length == 20) {
+            // A 20-byte output hash is used by P2SH. That hash is constructed
+            // by applying OP_HASH160 on the locking script. A 20-byte output
+            // hash is used as well by P2PKH and P2WPKH (OP_HASH160 on the
+            // public key). However, since we compare the actual output hash
+            // with an expected locking script hash, this check will succeed only
+            // for P2SH transaction type with expected script hash value. For
+            // P2PKH and P2WPKH, it will fail on the output hash comparison with
+            // the expected locking script hash.
+            require(
+                fundingOutputHash.slice20(0) == expectedScript.hash160View(),
+                "Wrong 20-byte script hash"
+            );
+        } else if (fundingOutputHash.length == 32) {
+            // A 32-byte output hash is used by P2WSH. That hash is constructed
+            // by applying OP_SHA256 on the locking script.
+            require(
+                fundingOutputHash.toBytes32() == sha256(expectedScript),
+                "Wrong 32-byte script hash"
+            );
+        } else {
+            revert("Wrong script hash length");
+        }
+
+        // Resulting TX hash is in native Bitcoin little-endian format.
+        bytes32 fundingTxHash = abi
+            .encodePacked(
+                fundingTx.version,
+                fundingTx.inputVector,
+                fundingTx.outputVector,
+                fundingTx.locktime
+            )
+            .hash256View();
+
+        DepositRequest storage deposit = self.deposits[
+            uint256(
+                keccak256(
+                    abi.encodePacked(fundingTxHash, reveal.fundingOutputIndex)
+                )
+            )
+        ];
+        require(deposit.revealedAt == 0, "Deposit already revealed");
+
+        uint64 fundingOutputAmount = fundingOutput.extractValue();
+
+        require(
+            fundingOutputAmount >= self.depositDustThreshold,
+            "Deposit amount too small"
+        );
+
+        deposit.amount = fundingOutputAmount;
+        deposit.depositor = reveal.depositor;
+        /* solhint-disable-next-line not-rely-on-time */
+        deposit.revealedAt = uint32(block.timestamp);
+        deposit.vault = reveal.vault;
+        deposit.treasuryFee = self.depositTreasuryFeeDivisor > 0
+            ? fundingOutputAmount / self.depositTreasuryFeeDivisor
+            : 0;
+        // slither-disable-next-line reentrancy-events
+        emit DepositRevealed(
+            fundingTxHash,
+            reveal.fundingOutputIndex,
+            reveal.depositor,
+            fundingOutputAmount,
+            reveal.blindingFactor,
+            reveal.walletPubKeyHash,
+            reveal.refundPubKeyHash,
+            reveal.refundLocktime,
+            reveal.vault
+        );
+    }
+}