@keep-network/tbtc-v2 0.1.1-dev.4 → 0.1.1-dev.40

package/contracts/bridge/BridgeState.sol

@@ -0,0 +1,172 @@
+// SPDX-License-Identifier: MIT
+
+// ██████████████     ▐████▌     ██████████████
+// ██████████████     ▐████▌     ██████████████
+//               ▐████▌    ▐████▌
+//               ▐████▌    ▐████▌
+// ██████████████     ▐████▌     ██████████████
+// ██████████████     ▐████▌     ██████████████
+//               ▐████▌    ▐████▌
+//               ▐████▌    ▐████▌
+//               ▐████▌    ▐████▌
+//               ▐████▌    ▐████▌
+//               ▐████▌    ▐████▌
+//               ▐████▌    ▐████▌
+
+pragma solidity ^0.8.9;
+
+import "./IRelay.sol";
+import "./Deposit.sol";
+import "./Redeem.sol";
+
+import "../bank/Bank.sol";
+
+library BridgeState {
+    struct Storage {
+        /// @notice The number of confirmations on the Bitcoin chain required to
+        ///         successfully evaluate an SPV proof.
+        uint256 txProofDifficultyFactor;
+        /// TODO: Revisit whether it should be governable or not.
+        /// @notice Address of the Bank this Bridge belongs to.
+        Bank bank;
+        /// TODO: Make it governable.
+        /// @notice Bitcoin relay providing the current Bitcoin network
+        ///         difficulty.
+        IRelay relay;
+        /// TODO: Revisit whether it should be governable or not.
+        /// @notice Address where the deposit and redemption treasury fees will
+        ///         be sent to. Treasury takes part in the operators rewarding
+        ///         process.
+        address treasury;
+        /// 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;
+        /// TODO: Make it governable.
+        /// @notice Maximum amount of BTC transaction fee that can be incurred by
+        ///         each swept deposit being part of the given sweep
+        ///         transaction. If the maximum BTC transaction fee is exceeded,
+        ///         such transaction is considered a fraud.
+        /// @dev This is a per-deposit input max fee for the sweep transaction.
+        uint64 depositTxMaxFee;
+        /// @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.DepositRequest) 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;
+        /// TODO: Make it governable.
+        /// @notice Maximum amount of the total BTC transaction fee that is
+        ///         acceptable in a single moving funds transaction.
+        /// @dev This is a TOTAL max fee for the moving funds transaction. Note
+        ///      that `depositTxMaxFee` is per single deposit and `redemptionTxMaxFee`
+        ///      if per single redemption. `movingFundsTxMaxTotalFee` is a total
+        ///      fee for the entire transaction.
+        uint64 movingFundsTxMaxTotalFee;
+        /// TODO: Make it governable.
+        /// @notice The minimal amount that can be requested for redemption.
+        ///         Value of this parameter must take into account the value of
+        ///         `redemptionTreasuryFeeDivisor` and `redemptionTxMaxFee`
+        ///         parameters in order to make requests that can incur the
+        ///         treasury and transaction fee and still satisfy the redeemer.
+        uint64 redemptionDustThreshold;
+        /// TODO: Make it governable.
+        /// @notice Divisor used to compute the treasury fee taken from each
+        ///         redemption request and transferred to the treasury upon
+        ///         successful request finalization. That fee is computed as follows:
+        ///         `treasuryFee = requestedAmount / redemptionTreasuryFeeDivisor`
+        ///         For example, if the treasury fee needs to be 2% of each
+        ///         redemption request, the `redemptionTreasuryFeeDivisor` should
+        ///         be set to `50` because `1/50 = 0.02 = 2%`.
+        uint64 redemptionTreasuryFeeDivisor;
+        /// TODO: Make it governable.
+        /// @notice Maximum amount of BTC transaction fee that can be incurred by
+        ///         each redemption request being part of the given redemption
+        ///         transaction. If the maximum BTC transaction fee is exceeded, such
+        ///         transaction is considered a fraud.
+        /// @dev This is a per-redemption output max fee for the redemption transaction.
+        uint64 redemptionTxMaxFee;
+        /// TODO: Make it governable.
+        /// @notice Time after which the redemption request can be reported as
+        ///         timed out. It is counted from the moment when the redemption
+        ///         request was created via `requestRedemption` call. Reported
+        ///         timed out requests are cancelled and locked TBTC is returned
+        ///         to the redeemer in full amount.
+        uint256 redemptionTimeout;
+        /// @notice Collection of all pending redemption requests indexed by
+        ///         redemption key built as
+        ///         keccak256(walletPubKeyHash | redeemerOutputScript). The
+        ///         walletPubKeyHash is the 20-byte wallet's public key hash
+        ///         (computed using Bitcoin HASH160 over the compressed ECDSA
+        ///         public key) and redeemerOutputScript is a Bitcoin script
+        ///         (P2PKH, P2WPKH, P2SH or P2WSH) that will be used to lock
+        ///         redeemed BTC as requested by the redeemer. Requests are added
+        ///         to this mapping by the `requestRedemption` method (duplicates
+        ///         not allowed) and are removed by one of the following methods:
+        ///         - `submitRedemptionProof` in case the request was handled
+        ///           successfully
+        ///         - `notifyRedemptionTimeout` in case the request was reported
+        ///           to be timed out
+        mapping(uint256 => Redeem.RedemptionRequest) pendingRedemptions;
+        /// @notice Collection of all timed out redemptions requests indexed by
+        ///         redemption key built as
+        ///         keccak256(walletPubKeyHash | redeemerOutputScript). The
+        ///         walletPubKeyHash is the 20-byte wallet's public key hash
+        ///         (computed using Bitcoin HASH160 over the compressed ECDSA
+        ///         public key) and redeemerOutputScript is the Bitcoin script
+        ///         (P2PKH, P2WPKH, P2SH or P2WSH) that is involved in the timed
+        ///         out request. Timed out requests are stored in this mapping to
+        ///         avoid slashing the wallets multiple times for the same timeout.
+        ///         Only one method can add to this mapping:
+        ///         - `notifyRedemptionTimeout` which puts the redemption key
+        ///           to this mapping basing on a timed out request stored
+        ///           previously in `pendingRedemptions` mapping.
+        mapping(uint256 => Redeem.RedemptionRequest) timedOutRedemptions;
+        /// @notice Collection of main UTXOs that are honestly spent indexed by
+        ///         keccak256(fundingTxHash | fundingOutputIndex). The fundingTxHash
+        ///         is bytes32 (ordered as in Bitcoin internally) and
+        ///         fundingOutputIndex an uint32. A main UTXO is considered honestly
+        ///         spent if it was used as an input of a transaction that have been
+        ///         proven in the Bridge.
+        mapping(uint256 => bool) spentMainUTXOs;
+    }
+
+    // TODO: Is it the right place for this function? Should we move it to Bridge?
+    /// @notice Determines the current Bitcoin SPV proof difficulty context.
+    /// @return proofDifficulty Bitcoin proof difficulty context.
+    function proofDifficultyContext(Storage storage self)
+        internal
+        view
+        returns (BitcoinTx.ProofDifficulty memory proofDifficulty)
+    {
+        IRelay relay = self.relay;
+        proofDifficulty.currentEpochDifficulty = relay
+            .getCurrentEpochDifficulty();
+        proofDifficulty.previousEpochDifficulty = relay
+            .getPrevEpochDifficulty();
+        proofDifficulty.difficultyFactor = self.txProofDifficultyFactor;
+
+        return proofDifficulty;
+    }
+}

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 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,
+        Wallets.Data storage wallets,
+        BitcoinTx.Info calldata fundingTx,
+        DepositRevealInfo 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();
+
+        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;
+
+        emit DepositRevealed(
+            fundingTxHash,
+            reveal.fundingOutputIndex,
+            reveal.depositor,
+            fundingOutputAmount,
+            reveal.blindingFactor,
+            reveal.walletPubKeyHash,
+            reveal.refundPubKeyHash,
+            reveal.refundLocktime,
+            reveal.vault
+        );
+    }
+}

package/contracts/bridge/EcdsaLib.sol

@@ -0,0 +1,30 @@
+pragma solidity ^0.8.9;
+
+import "@keep-network/bitcoin-spv-sol/contracts/BytesLib.sol";
+
+library EcdsaLib {
+    using BytesLib for bytes;
+
+    /// @notice Converts public key X and Y coordinates (32-byte each) to a
+    ///         compressed public key (33-byte). Compressed public key is X
+    ///         coordinate prefixed with `02` or `03` based on the Y coordinate parity.
+    ///         It is expected that the uncompressed public key is stripped
+    ///         (i.e. it is not prefixed with `04`).
+    /// @param x Wallet's public key's X coordinate.
+    /// @param y Wallet's public key's Y coordinate.
+    /// @return Compressed public key (33-byte), prefixed with `02` or `03`.
+    function compressPublicKey(bytes32 x, bytes32 y)
+        internal
+        pure
+        returns (bytes memory)
+    {
+        bytes1 prefix;
+        if (uint256(y) % 2 == 0) {
+            prefix = hex"02";
+        } else {
+            prefix = hex"03";
+        }
+
+        return bytes.concat(prefix, x);
+    }
+}