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

package/contracts/bridge/BridgeState.sol

@@ -0,0 +1,251 @@
+// SPDX-License-Identifier: MIT
+
+// ██████████████     ▐████▌     ██████████████
+// ██████████████     ▐████▌     ██████████████
+//               ▐████▌    ▐████▌
+//               ▐████▌    ▐████▌
+// ██████████████     ▐████▌     ██████████████
+// ██████████████     ▐████▌     ██████████████
+//               ▐████▌    ▐████▌
+//               ▐████▌    ▐████▌
+//               ▐████▌    ▐████▌
+//               ▐████▌    ▐████▌
+//               ▐████▌    ▐████▌
+//               ▐████▌    ▐████▌
+
+pragma solidity ^0.8.9;
+
+import "./IRelay.sol";
+import "./Deposit.sol";
+import "./Redeem.sol";
+import "./Fraud.sol";
+import "./Wallets.sol";
+
+import "../bank/Bank.sol";
+
+library BridgeState {
+    // TODO: Make parameters governable
+    struct Storage {
+        // Address of the Bank the Bridge belongs to.
+        Bank bank;
+        // Bitcoin relay providing the current Bitcoin network difficulty.
+        IRelay relay;
+        // ECDSA Wallet Registry contract handle.
+        EcdsaWalletRegistry ecdsaWalletRegistry;
+        // The number of confirmations on the Bitcoin chain required to
+        // successfully evaluate an SPV proof.
+        uint256 txProofDifficultyFactor;
+        // Address where the deposit and redemption treasury fees will be sent
+        // to. Treasury takes part in the operators rewarding process.
+        address treasury;
+        // 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;
+        // 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;
+        // 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.
+        //
+        // This is a per-deposit input max fee for the sweep transaction.
+        uint64 depositTxMaxFee;
+        // 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;
+        // 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;
+        // Maximum amount of the total BTC transaction fee that is acceptable in
+        // a single moving funds transaction.
+        //
+        // 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;
+        // 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;
+        // 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;
+        // 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.
+        //
+        // This is a per-redemption output max fee for the redemption
+        // transaction.
+        uint64 redemptionTxMaxFee;
+        // 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;
+        // 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;
+        // 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;
+        // The amount of stake slashed from each member of a wallet for a fraud.
+        uint256 fraudSlashingAmount;
+        // The percentage of the notifier reward from the staking contract
+        // the notifier of a fraud receives. The value is in the range [0, 100].
+        uint256 fraudNotifierRewardMultiplier;
+        // The amount of time the wallet has to defeat a fraud challenge.
+        uint256 fraudChallengeDefeatTimeout;
+        // The amount of ETH in wei the party challenging the wallet for fraud
+        // needs to deposit.
+        uint256 fraudChallengeDepositAmount;
+        // Collection of all submitted fraud challenges indexed by challenge
+        // key built as `keccak256(walletPublicKey|sighash)`.
+        mapping(uint256 => Fraud.FraudChallenge) fraudChallenges;
+        // 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;
+        // Determines how frequently a new wallet creation can be requested.
+        // Value in seconds.
+        uint32 walletCreationPeriod;
+        // The minimum BTC threshold in satoshi that is used to decide about
+        // wallet creation or closing.
+        uint64 walletMinBtcBalance;
+        // The maximum BTC threshold in satoshi that is used to decide about
+        // wallet creation.
+        uint64 walletMaxBtcBalance;
+        // The maximum age of a wallet in seconds, after which the wallet
+        // moving funds process can be requested.
+        uint32 walletMaxAge;
+        // 20-byte wallet public key hash being reference to the currently
+        // active wallet. Can be unset to the zero value under certain
+        // circumstances.
+        bytes20 activeWalletPubKeyHash;
+        // Maps the 20-byte wallet public key hash (computed using Bitcoin
+        // HASH160 over the compressed ECDSA public key) to the basic wallet
+        // information like state and pending redemptions value.
+        mapping(bytes20 => Wallets.Wallet) registeredWallets;
+    }
+
+    event WalletParametersUpdated(
+        uint32 walletCreationPeriod,
+        uint64 walletMinBtcBalance,
+        uint64 walletMaxBtcBalance,
+        uint32 walletMaxAge
+    );
+
+    /// @notice Updates parameters of wallets.
+    /// @param _walletCreationPeriod New value of the wallet creation period in
+    ///        seconds, determines how frequently a new wallet creation can be
+    ///        requested
+    /// @param _walletMinBtcBalance New value of the wallet minimum BTC balance
+    ///        in sathoshis, used to decide about wallet creation or closing
+    /// @param _walletMaxBtcBalance New value of the wallet maximum BTC balance
+    ///        in sathoshis, used to decide about wallet creation
+    /// @param _walletMaxAge New value of the wallet maximum age in seconds,
+    ///        indicates the maximum age of a wallet in seconds, after which
+    ///        the wallet moving funds process can be requested
+    /// @dev Requirements:
+    ///      - Wallet minimum BTC balance must be greater than zero
+    ///      - Wallet maximum BTC balance must be greater than the wallet
+    ///        minimum BTC balance
+    function updateWalletParameters(
+        Storage storage self,
+        uint32 _walletCreationPeriod,
+        uint64 _walletMinBtcBalance,
+        uint64 _walletMaxBtcBalance,
+        uint32 _walletMaxAge
+    ) internal {
+        require(
+            _walletMinBtcBalance > 0,
+            "Wallet minimum BTC balance must be greater than zero"
+        );
+        require(
+            _walletMaxBtcBalance > _walletMinBtcBalance,
+            "Wallet maximum BTC balance must be greater than the minimum"
+        );
+
+        self.walletCreationPeriod = _walletCreationPeriod;
+        self.walletMinBtcBalance = _walletMinBtcBalance;
+        self.walletMaxBtcBalance = _walletMaxBtcBalance;
+        self.walletMaxAge = _walletMaxAge;
+
+        emit WalletParametersUpdated(
+            _walletCreationPeriod,
+            _walletMinBtcBalance,
+            _walletMaxBtcBalance,
+            _walletMaxAge
+        );
+    }
+
+    // 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,244 @@
+// 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 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 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);
+    }
+}