@keep-network/tbtc-v2 0.1.1-dev.31 → 0.1.1-dev.34

package/contracts/bridge/BridgeState.sol

@@ -0,0 +1,54 @@
+// SPDX-License-Identifier: MIT
+
+// ██████████████     ▐████▌     ██████████████
+// ██████████████     ▐████▌     ██████████████
+//               ▐████▌    ▐████▌
+//               ▐████▌    ▐████▌
+// ██████████████     ▐████▌     ██████████████
+// ██████████████     ▐████▌     ██████████████
+//               ▐████▌    ▐████▌
+//               ▐████▌    ▐████▌
+//               ▐████▌    ▐████▌
+//               ▐████▌    ▐████▌
+//               ▐████▌    ▐████▌
+//               ▐████▌    ▐████▌
+
+pragma solidity ^0.8.9;
+
+import "./Deposit.sol";
+
+library BridgeState {
+    struct Storage {
+        /// TODO: Make it governable.
+        /// @notice The minimal amount that can be requested to deposit.
+        ///         Value of this parameter must take into account the value of
+        ///         `depositTreasuryFeeDivisor` and `depositTxMaxFee`
+        ///         parameters in order to make requests that can incur the
+        ///         treasury and transaction fee and still satisfy the depositor.
+        uint64 depositDustThreshold;
+        /// TODO: Make it governable.
+        /// @notice Divisor used to compute the treasury fee taken from each
+        ///         deposit and transferred to the treasury upon sweep proof
+        ///         submission. That fee is computed as follows:
+        ///         `treasuryFee = depositedAmount / depositTreasuryFeeDivisor`
+        ///         For example, if the treasury fee needs to be 2% of each deposit,
+        ///         the `depositTreasuryFeeDivisor` should be set to `50`
+        ///         because `1/50 = 0.02 = 2%`.
+        uint64 depositTreasuryFeeDivisor;
+        /// @notice Collection of all revealed deposits indexed by
+        ///         keccak256(fundingTxHash | fundingOutputIndex).
+        ///         The fundingTxHash is bytes32 (ordered as in Bitcoin internally)
+        ///         and fundingOutputIndex an uint32. This mapping may contain valid
+        ///         and invalid deposits and the wallet is responsible for
+        ///         validating them before attempting to execute a sweep.
+        mapping(uint256 => Deposit.Request) deposits;
+        /// @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
+        ///         soon as these deposits get swept. Vaults not trusted by the
+        ///         Bridge can still be used by Bank balance owners on their own
+        ///         responsibility - anyone can approve their Bank balance to any
+        ///         address.
+        mapping(address => bool) isVaultTrusted;
+    }
+}

package/contracts/bridge/Deposit.sol

@@ -0,0 +1,247 @@
+// 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";
+
+library Deposit {
+    using Wallets for Wallets.Data;
+
+    using BTCUtils for bytes;
+    using BytesLib for bytes;
+
+    /// @notice Represents data which must be revealed by the depositor during
+    ///         deposit reveal.
+    struct RevealInfo {
+        // 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 Request {
+        // 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,
+        Wallets.Data storage wallets,
+        BitcoinTx.Info calldata fundingTx,
+        RevealInfo calldata reveal
+    ) external {
+        require(
+            wallets.registeredWallets[reveal.walletPubKeyHash].state ==
+                Wallets.WalletState.Live,
+            "Wallet is not 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();
+
+        Request 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;
+
+        emit DepositRevealed(
+            fundingTxHash,
+            reveal.fundingOutputIndex,
+            reveal.depositor,
+            fundingOutputAmount,
+            reveal.blindingFactor,
+            reveal.walletPubKeyHash,
+            reveal.refundPubKeyHash,
+            reveal.refundLocktime,
+            reveal.vault
+        );
+    }
+}

package/contracts/bridge/Wallets.sol

@@ -92,9 +92,13 @@ library Wallets {
         uint32 createdAt;
         // UNIX timestamp indicating the moment the wallet was requested to
         // move their funds.
-        uint32 moveFundsRequestedAt;
+        uint32 movingFundsRequestedAt;
         // Current state of the wallet.
         WalletState state;
+        // Moving funds target wallet commitment submitted by the wallet. It
+        // is built by applying the keccak256 hash over the list of 20-byte
+        // public key hashes of the target wallets.
+        bytes32 movingFundsTargetWalletsCommitmentHash;
     }
 
     event WalletCreationPeriodUpdated(uint32 newCreationPeriod);
@@ -308,7 +312,7 @@ library Wallets {
 
         // Compress wallet's public key and calculate Bitcoin's hash160 of it.
         bytes20 walletPubKeyHash = bytes20(
-            EcdsaLib.compressPublicKey(publicKeyX, publicKeyY).hash160()
+            EcdsaLib.compressPublicKey(publicKeyX, publicKeyY).hash160View()
         );
 
         Wallet storage wallet = self.registeredWallets[walletPubKeyHash];
@@ -346,7 +350,7 @@ library Wallets {
 
         // Compress wallet's public key and calculate Bitcoin's hash160 of it.
         bytes20 walletPubKeyHash = bytes20(
-            EcdsaLib.compressPublicKey(publicKeyX, publicKeyY).hash160()
+            EcdsaLib.compressPublicKey(publicKeyX, publicKeyY).hash160View()
         );
 
         require(
@@ -448,16 +452,12 @@ library Wallets {
         if (wallet.mainUtxoHash == bytes32(0)) {
             // If the wallet has no main UTXO, that means its BTC balance
             // is zero and it should be closed immediately.
-            wallet.state = WalletState.Closed;
-
-            emit WalletClosed(wallet.ecdsaWalletID, walletPubKeyHash);
-
-            self.registry.closeWallet(wallet.ecdsaWalletID);
+            closeWallet(self, walletPubKeyHash);
         } else {
             // Otherwise, initialize the moving funds process.
             wallet.state = WalletState.MovingFunds;
             /* solhint-disable-next-line not-rely-on-time */
-            wallet.moveFundsRequestedAt = uint32(block.timestamp);
+            wallet.movingFundsRequestedAt = uint32(block.timestamp);
 
             emit WalletMovingFunds(wallet.ecdsaWalletID, walletPubKeyHash);
         }
@@ -470,9 +470,21 @@ library Wallets {
         }
     }
 
-    // TODO: Implement functions that will be called upon moving funds process
-    //       end. Remember the moving funds process ends up with a successful
-    //       proof or a timeout.
+    /// @notice Closes the given wallet and notifies the ECDSA registry
+    ///         about this fact.
+    /// @param walletPubKeyHash 20-byte public key hash of the wallet
+    /// @dev Requirements:
+    ///      - The caller must make sure that the wallet is in the
+    ///        Live or MovingFunds state.
+    function closeWallet(Data storage self, bytes20 walletPubKeyHash) internal {
+        Wallet storage wallet = self.registeredWallets[walletPubKeyHash];
+
+        wallet.state = WalletState.Closed;
+
+        emit WalletClosed(wallet.ecdsaWalletID, walletPubKeyHash);
+
+        self.registry.closeWallet(wallet.ecdsaWalletID);
+    }
 
     /// @notice Reports about a fraud committed by the given wallet. This
     ///         function performs slashing and wallet termination in reaction
@@ -482,9 +494,19 @@ library Wallets {
     /// @dev Requirements:
     ///      - Wallet must be in Live or MovingFunds state
     function notifyFraud(Data storage self, bytes20 walletPubKeyHash) external {
-        // TODO: Perform slashing of wallet operators and add unit tests for that.
+        WalletState walletState = self
+            .registeredWallets[walletPubKeyHash]
+            .state;
+
+        require(
+            walletState == WalletState.Live ||
+                walletState == WalletState.MovingFunds,
+            "ECDSA wallet must be in Live or MovingFunds state"
+        );
 
         terminateWallet(self, walletPubKeyHash);
+
+        // TODO: Perform slashing of wallet operators and add unit tests for that.
     }
 
     /// @notice Terminates the given wallet and notifies the ECDSA registry
@@ -494,16 +516,12 @@ library Wallets {
     ///         creation immediately.
     /// @param walletPubKeyHash 20-byte public key hash of the wallet
     /// @dev Requirements:
-    ///      - Wallet must be in Live or MovingFunds state
+    ///      - The caller must make sure that the wallet is in the
+    ///        Live or MovingFunds state.
     function terminateWallet(Data storage self, bytes20 walletPubKeyHash)
         internal
     {
         Wallet storage wallet = self.registeredWallets[walletPubKeyHash];
-        require(
-            wallet.state == WalletState.Live ||
-                wallet.state == WalletState.MovingFunds,
-            "ECDSA wallet must be in Live or MovingFunds state"
-        );
 
         wallet.state = WalletState.Terminated;
 
@@ -518,4 +536,56 @@ library Wallets {
 
         self.registry.closeWallet(wallet.ecdsaWalletID);
     }
+
+    /// @notice Notifies that the wallet completed the moving funds process
+    ///         successfully. Checks if the funds were moved to the expected
+    ///         target wallets. Closes the source wallet if everything went
+    ///         good and reverts otherwise.
+    /// @param walletPubKeyHash 20-byte public key hash of the wallet
+    /// @param targetWalletsHash 32-byte keccak256 hash over the list of
+    ///        20-byte public key hashes of the target wallets actually used
+    ///        within the moving funds transactions.
+    /// @dev Requirements:
+    ///      - The caller must make sure the moving funds transaction actually
+    ///        happened on Bitcoin chain and fits the protocol requirements.
+    ///      - The source wallet must be in the MovingFunds state
+    ///      - The target wallets commitment must be submitted by the source
+    ///        wallet.
+    ///      - The actual target wallets used in the moving funds transaction
+    ///        must be exactly the same as the target wallets commitment.
+    function notifyFundsMoved(
+        Data storage self,
+        bytes20 walletPubKeyHash,
+        bytes32 targetWalletsHash
+    ) external {
+        Wallet storage wallet = self.registeredWallets[walletPubKeyHash];
+        // Check that the wallet is in the MovingFunds state but don't check
+        // if the moving funds timeout is exceeded. That should give a
+        // possibility to move funds in case when timeout was hit but was
+        // not reported yet.
+        require(
+            wallet.state == WalletState.MovingFunds,
+            "ECDSA wallet must be in MovingFunds state"
+        );
+
+        bytes32 targetWalletsCommitmentHash = wallet
+            .movingFundsTargetWalletsCommitmentHash;
+
+        require(
+            targetWalletsCommitmentHash != bytes32(0),
+            "Target wallets commitment not submitted yet"
+        );
+
+        // Make sure that the target wallets where funds were moved to are
+        // exactly the same as the ones the source wallet committed to.
+        require(
+            targetWalletsCommitmentHash == targetWalletsHash,
+            "Target wallets don't correspond to the commitment"
+        );
+
+        // If funds were moved, the wallet has no longer a main UTXO.
+        delete wallet.mainUtxoHash;
+
+        closeWallet(self, walletPubKeyHash);
+    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@keep-network/tbtc-v2",
-  "version": "0.1.1-dev.31+main.749b9391b64c3a3fcc1eb2a1412a5f5620189e34",
+  "version": "0.1.1-dev.34+main.2216025329269acf92935ba67297c49576c45fae",
   "license": "MIT",
   "files": [
     "artifacts/",