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

package/contracts/bridge/Fraud.sol

@@ -0,0 +1,508 @@
+// SPDX-License-Identifier: MIT
+
+// ██████████████     ▐████▌     ██████████████
+// ██████████████     ▐████▌     ██████████████
+//               ▐████▌    ▐████▌
+//               ▐████▌    ▐████▌
+// ██████████████     ▐████▌     ██████████████
+// ██████████████     ▐████▌     ██████████████
+//               ▐████▌    ▐████▌
+//               ▐████▌    ▐████▌
+//               ▐████▌    ▐████▌
+//               ▐████▌    ▐████▌
+//               ▐████▌    ▐████▌
+//               ▐████▌    ▐████▌
+
+pragma solidity ^0.8.9;
+
+import {BytesLib} from "@keep-network/bitcoin-spv-sol/contracts/BytesLib.sol";
+import {BTCUtils} from "@keep-network/bitcoin-spv-sol/contracts/BTCUtils.sol";
+import {CheckBitcoinSigs} from "@keep-network/bitcoin-spv-sol/contracts/CheckBitcoinSigs.sol";
+
+import "./BitcoinTx.sol";
+import "./EcdsaLib.sol";
+import "./BridgeState.sol";
+import "./MovingFunds.sol";
+import "./Wallets.sol";
+
+/// @title Bridge fraud
+/// @notice The library handles the logic for challenging Bridge wallets that
+///         committed fraud.
+/// @dev Anyone can submit a fraud challenge indicating that a UTXO being under
+///      the wallet control was unlocked by the wallet but was not used
+///      according to the protocol rules. That means the wallet signed
+///      a transaction input pointing to that UTXO and there is a unique
+///      sighash and signature pair associated with that input.
+///
+///      In order to defeat the challenge, the same wallet public key and
+///      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.
+library Fraud {
+    using Wallets for BridgeState.Storage;
+
+    using BytesLib for bytes;
+    using BTCUtils for bytes;
+    using BTCUtils for uint32;
+    using EcdsaLib for bytes;
+
+    struct FraudChallenge {
+        // The address of the party challenging the wallet.
+        address challenger;
+        // The amount of ETH the challenger deposited.
+        uint256 depositAmount;
+        // The timestamp the challenge was submitted at.
+        uint32 reportedAt;
+        // The flag indicating whether the challenge has been resolved.
+        bool resolved;
+    }
+
+    event FraudChallengeSubmitted(
+        bytes20 walletPubKeyHash,
+        bytes32 sighash,
+        uint8 v,
+        bytes32 r,
+        bytes32 s
+    );
+
+    event FraudChallengeDefeated(bytes20 walletPubKeyHash, bytes32 sighash);
+
+    event FraudChallengeDefeatTimedOut(
+        bytes20 walletPubKeyHash,
+        bytes32 sighash
+    );
+
+    /// @notice Submits a fraud challenge indicating that a UTXO being under
+    ///         wallet control was unlocked by the wallet but was not used
+    ///         according to the protocol rules. That means the wallet signed
+    ///         a transaction input pointing to that UTXO and there is a unique
+    ///         sighash and signature pair associated with that input. This
+    ///         function uses those parameters to create a fraud accusation that
+    ///         proves a given transaction input unlocking the given UTXO was
+    ///         actually signed by the wallet. This function cannot determine
+    ///         whether the transaction was actually broadcast and the input was
+    ///         consumed in a fraudulent way so it just opens a challenge period
+    ///         during which the wallet can defeat the challenge by submitting
+    ///         proof of a transaction that consumes the given input according
+    ///         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 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
+    ///        transaction. The exact subset used as hash preimage depends on
+    ///        the transaction input the signature is produced for. See BIP-143
+    ///        for reference
+    /// @param signature Bitcoin signature in the R/S/V format
+    /// @dev Requirements:
+    ///      - Wallet behind `walletPublicKey` must be in Live or MovingFunds
+    ///        or Closing state
+    ///      - The challenger must send appropriate amount of ETH used as
+    ///        fraud challenge deposit
+    ///      - The signature (represented by r, s and v) must be generated by
+    ///        the wallet behind `walletPublicKey` during signing of `sighash`
+    ///      - Wallet can be challenged for the given signature only once
+    function submitFraudChallenge(
+        BridgeState.Storage storage self,
+        bytes calldata walletPublicKey,
+        bytes32 sighash,
+        BitcoinTx.RSVSignature calldata signature
+    ) external {
+        require(
+            msg.value >= self.fraudChallengeDepositAmount,
+            "The amount of ETH deposited is too low"
+        );
+
+        require(
+            CheckBitcoinSigs.checkSig(
+                walletPublicKey,
+                sighash,
+                signature.v,
+                signature.r,
+                signature.s
+            ),
+            "Signature verification failure"
+        );
+
+        bytes memory compressedWalletPublicKey = EcdsaLib.compressPublicKey(
+            walletPublicKey.slice32(0),
+            walletPublicKey.slice32(32)
+        );
+        bytes20 walletPubKeyHash = compressedWalletPublicKey.hash160View();
+
+        Wallets.Wallet storage wallet = self.registeredWallets[
+            walletPubKeyHash
+        ];
+
+        require(
+            wallet.state == Wallets.WalletState.Live ||
+                wallet.state == Wallets.WalletState.MovingFunds ||
+                wallet.state == Wallets.WalletState.Closing,
+            "Wallet must be in Live or MovingFunds or Closing state"
+        );
+
+        uint256 challengeKey = uint256(
+            keccak256(abi.encodePacked(walletPublicKey, sighash))
+        );
+
+        FraudChallenge storage challenge = self.fraudChallenges[challengeKey];
+        require(challenge.reportedAt == 0, "Fraud challenge already exists");
+
+        challenge.challenger = msg.sender;
+        challenge.depositAmount = msg.value;
+        /* solhint-disable-next-line not-rely-on-time */
+        challenge.reportedAt = uint32(block.timestamp);
+        challenge.resolved = false;
+        // slither-disable-next-line reentrancy-events
+        emit FraudChallengeSubmitted(
+            walletPubKeyHash,
+            sighash,
+            signature.v,
+            signature.r,
+            signature.s
+        );
+    }
+
+    /// @notice Allows to defeat a pending fraud challenge against a wallet if
+    ///         the transaction that spends the UTXO follows the protocol rules.
+    ///         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 input signing.
+    ///         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.
+    ///         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 preimage The preimage which produces sighash used to generate the
+    ///        ECDSA signature that is the subject of the fraud claim. It is a
+    ///        serialized subset of the transaction. The exact subset used as
+    ///        the preimage depends on the transaction input the signature is
+    ///        produced for. See BIP-143 for reference
+    /// @param witness Flag indicating whether the preimage was produced for a
+    ///        witness input. True for witness, false for non-witness input.
+    /// @dev Requirements:
+    ///      - `walletPublicKey` and `sighash` calculated as `hash256(preimage)`
+    ///        must identify an open fraud challenge
+    ///      - the preimage must be a valid preimage of a transaction generated
+    ///        according to the protocol rules and already proved in the Bridge
+    ///      - before a defeat attempt is made the transaction that spends the
+    ///        given UTXO must be proven in the Bridge
+    function defeatFraudChallenge(
+        BridgeState.Storage storage self,
+        bytes calldata walletPublicKey,
+        bytes calldata preimage,
+        bool witness
+    ) external {
+        bytes32 sighash = preimage.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"
+        );
+
+        // Ensure SIGHASH_ALL type was used during signing, which is represented
+        // by type value `1`.
+        require(extractSighashType(preimage) == 1, "Wrong sighash type");
+
+        uint256 utxoKey = witness
+            ? extractUtxoKeyFromWitnessPreimage(preimage)
+            : extractUtxoKeyFromNonWitnessPreimage(preimage);
+
+        // Check that the UTXO key identifies a correctly spent UTXO.
+        require(
+            self.deposits[utxoKey].sweptAt > 0 ||
+                self.spentMainUTXOs[utxoKey] ||
+                self.movedFundsSweepRequests[utxoKey].state ==
+                MovingFunds.MovedFundsSweepRequestState.Processed,
+            "Spent UTXO not found among correctly spent UTXOs"
+        );
+
+        // Mark the challenge as resolved as it was successfully defeated
+        challenge.resolved = true;
+
+        // Send the ether deposited by the challenger to the treasury
+        /* solhint-disable avoid-low-level-calls */
+        // slither-disable-next-line low-level-calls,unchecked-lowlevel,arbitrary-send
+        self.treasury.call{gas: 100000, value: challenge.depositAmount}("");
+        /* solhint-enable avoid-low-level-calls */
+
+        bytes memory compressedWalletPublicKey = EcdsaLib.compressPublicKey(
+            walletPublicKey.slice32(0),
+            walletPublicKey.slice32(32)
+        );
+        bytes20 walletPubKeyHash = compressedWalletPublicKey.hash160View();
+        // slither-disable-next-line reentrancy-events
+        emit FraudChallengeDefeated(walletPubKeyHash, sighash);
+    }
+
+    /// @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
+    ///         defeated on time. The amount of time that needs to pass after a
+    ///         fraud challenge is reported is indicated by the
+    ///         `challengeDefeatTimeout`. After a successful fraud challenge
+    ///         defeat timeout notification the fraud challenge is marked as
+    ///         resolved, the stake of each operator is slashed, the ether
+    ///         deposited is returned to the challenger and the challenger is
+    ///         rewarded.
+    /// @param walletPublicKey The public key of the wallet in the uncompressed
+    ///        and unprefixed format (64 bytes)
+    /// @param walletMembersIDs Identifiers of the wallet signing group members
+    /// @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
+    ///        transaction. The exact subset used as hash preimage depends on
+    ///        the transaction input the signature is produced for. See BIP-143
+    ///        for reference
+    /// @dev Requirements:
+    ///      - The wallet must be in the Live or MovingFunds or Closing or
+    ///        Terminated state
+    ///      - The `walletPublicKey` and `sighash` must identify an open fraud
+    ///        challenge
+    ///      - The expression `keccak256(abi.encode(walletMembersIDs))` must
+    ///        be exactly the same as the hash stored under `membersIdsHash`
+    ///        for the given `walletID`. Those IDs are not directly stored
+    ///        in the contract for gas efficiency purposes but they can be
+    ///        read from appropriate `DkgResultSubmitted` and `DkgResultApproved`
+    ///        events of the `WalletRegistry` contract
+    ///      - The amount of time indicated by `challengeDefeatTimeout` must pass
+    ///        after the challenge was reported
+    function notifyFraudChallengeDefeatTimeout(
+        BridgeState.Storage storage self,
+        bytes calldata walletPublicKey,
+        uint32[] calldata walletMembersIDs,
+        bytes32 sighash
+    ) external {
+        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(
+            /* solhint-disable-next-line not-rely-on-time */
+            block.timestamp >=
+                challenge.reportedAt + self.fraudChallengeDefeatTimeout,
+            "Fraud challenge defeat period did not time out yet"
+        );
+
+        challenge.resolved = true;
+        // Return the ether deposited by the challenger
+        /* solhint-disable avoid-low-level-calls */
+        // slither-disable-next-line low-level-calls,unchecked-lowlevel
+        challenge.challenger.call{gas: 100000, value: challenge.depositAmount}(
+            ""
+        );
+        /* solhint-enable avoid-low-level-calls */
+
+        bytes memory compressedWalletPublicKey = EcdsaLib.compressPublicKey(
+            walletPublicKey.slice32(0),
+            walletPublicKey.slice32(32)
+        );
+        bytes20 walletPubKeyHash = compressedWalletPublicKey.hash160View();
+
+        Wallets.Wallet storage wallet = self.registeredWallets[
+            walletPubKeyHash
+        ];
+
+        Wallets.WalletState walletState = wallet.state;
+
+        if (
+            walletState == Wallets.WalletState.Live ||
+            walletState == Wallets.WalletState.MovingFunds ||
+            walletState == Wallets.WalletState.Closing
+        ) {
+            self.terminateWallet(walletPubKeyHash);
+
+            self.ecdsaWalletRegistry.seize(
+                self.fraudSlashingAmount,
+                self.fraudNotifierRewardMultiplier,
+                challenge.challenger,
+                wallet.ecdsaWalletID,
+                walletMembersIDs
+            );
+        } else if (walletState == Wallets.WalletState.Terminated) {
+            // This is a special case when the wallet was already terminated
+            // due to a previous deliberate protocol violation. In that
+            // case, this function should be still callable for other fraud
+            // challenges timeouts in order to let the challenger unlock its
+            // ETH deposit back. However, the wallet termination logic is
+            // not called and the challenger is not rewarded.
+        } else {
+            revert(
+                "Wallet must be in Live or MovingFunds or Closing or Terminated state"
+            );
+        }
+
+        // slither-disable-next-line reentrancy-events
+        emit FraudChallengeDefeatTimedOut(walletPubKeyHash, sighash);
+    }
+
+    /// @notice Extracts the UTXO keys from the given preimage used during
+    ///         signing of a witness input.
+    /// @param preimage The preimage which produces sighash used to generate the
+    ///        ECDSA signature that is the subject of the fraud claim. It is a
+    ///        serialized subset of the transaction. The exact subset used as
+    ///        the preimage depends on the transaction input the signature is
+    ///        produced for. See BIP-143 for reference
+    /// @return utxoKey UTXO key that identifies spent input.
+    function extractUtxoKeyFromWitnessPreimage(bytes calldata preimage)
+        internal
+        pure
+        returns (uint256 utxoKey)
+    {
+        // The expected structure of the preimage created during signing of a
+        // witness input:
+        // - transaction version (4 bytes)
+        // - hash of previous outpoints of all inputs (32 bytes)
+        // - hash of sequences of all inputs (32 bytes)
+        // - outpoint (hash + index) of the input being signed (36 bytes)
+        // - the unlocking script of the input (variable length)
+        // - value of the outpoint (8 bytes)
+        // - sequence of the input being signed (4 bytes)
+        // - hash of all outputs (32 bytes)
+        // - transaction locktime (4 bytes)
+        // - sighash type (4 bytes)
+
+        // See Bitcoin's BIP-143 for reference:
+        // https://github.com/bitcoin/bips/blob/master/bip-0143.mediawiki.
+
+        // The outpoint (hash and index) is located at the constant offset of
+        // 68 (4 + 32 + 32).
+        bytes32 outpointTxHash = preimage.extractInputTxIdLeAt(68);
+        uint32 outpointIndex = BTCUtils.reverseUint32(
+            uint32(preimage.extractTxIndexLeAt(68))
+        );
+
+        return
+            uint256(keccak256(abi.encodePacked(outpointTxHash, outpointIndex)));
+    }
+
+    /// @notice Extracts the UTXO key from the given preimage used during
+    ///         signing of a non-witness input.
+    /// @param preimage The preimage which produces sighash used to generate the
+    ///        ECDSA signature that is the subject of the fraud claim. It is a
+    ///        serialized subset of the transaction. The exact subset used as
+    ///        the preimage depends on the transaction input the signature is
+    ///        produced for. See BIP-143 for reference
+    /// @return utxoKey UTXO key that identifies spent input.
+    function extractUtxoKeyFromNonWitnessPreimage(bytes calldata preimage)
+        internal
+        pure
+        returns (uint256 utxoKey)
+    {
+        // The expected structure of the preimage created during signing of a
+        // non-witness input:
+        // - transaction version (4 bytes)
+        // - number of inputs written as compactSize uint (1 byte, 3 bytes,
+        //   5 bytes or 9 bytes)
+        // - for each input
+        //   - outpoint (hash and index) (36 bytes)
+        //   - unlocking script for the input being signed (variable length)
+        //     or `00` for all other inputs (1 byte)
+        //   - input sequence (4 bytes)
+        // - number of outputs written as compactSize uint (1 byte, 3 bytes,
+        //   5 bytes or 9 bytes)
+        // - outputs (variable length)
+        // - transaction locktime (4 bytes)
+        // - sighash type (4 bytes)
+
+        // See example for reference:
+        // https://en.bitcoin.it/wiki/OP_CHECKSIG#Code_samples_and_raw_dumps.
+
+        // The input data begins at the constant offset of 4 (the first 4 bytes
+        // are for the transaction version).
+        (uint256 inputsCompactSizeUintLength, uint256 inputsCount) = preimage
+            .parseVarIntAt(4);
+
+        // To determine the first input starting index, we must jump 4 bytes
+        // over the transaction version length and the compactSize uint which
+        // prepends the input vector. One byte must be added because
+        // `BtcUtils.parseVarInt` does not include compactSize uint tag in the
+        // returned length.
+        //
+        // For >= 0 && <= 252, `BTCUtils.determineVarIntDataLengthAt`
+        // returns `0`, so we jump over one byte of compactSize uint.
+        //
+        // For >= 253 && <= 0xffff there is `0xfd` tag,
+        // `BTCUtils.determineVarIntDataLengthAt` returns `2` (no
+        // tag byte included) so we need to jump over 1+2 bytes of
+        // compactSize uint.
+        //
+        // Please refer `BTCUtils` library and compactSize uint
+        // docs in `BitcoinTx` library for more details.
+        uint256 inputStartingIndex = 4 + 1 + inputsCompactSizeUintLength;
+
+        for (uint256 i = 0; i < inputsCount; i++) {
+            uint256 inputLength = preimage.determineInputLengthAt(
+                inputStartingIndex
+            );
+
+            (, uint256 scriptSigLength) = preimage.extractScriptSigLenAt(
+                inputStartingIndex
+            );
+
+            if (scriptSigLength > 0) {
+                // The input this preimage was generated for was found.
+                // All the other inputs in the preimage are marked with a null
+                // scriptSig ("00") which has length of 1.
+                bytes32 outpointTxHash = preimage.extractInputTxIdLeAt(
+                    inputStartingIndex
+                );
+                uint32 outpointIndex = BTCUtils.reverseUint32(
+                    uint32(preimage.extractTxIndexLeAt(inputStartingIndex))
+                );
+
+                utxoKey = uint256(
+                    keccak256(abi.encodePacked(outpointTxHash, outpointIndex))
+                );
+
+                break;
+            }
+
+            inputStartingIndex += inputLength;
+        }
+
+        return utxoKey;
+    }
+
+    /// @notice Extracts the sighash type from the given preimage.
+    /// @param preimage Serialized subset of the transaction. See BIP-143 for
+    ///        reference
+    /// @dev Sighash type is stored as the last 4 bytes in the preimage (little
+    ///      endian).
+    /// @return sighashType Sighash type as a 32-bit integer.
+    function extractSighashType(bytes calldata preimage)
+        internal
+        pure
+        returns (uint32 sighashType)
+    {
+        bytes4 sighashTypeBytes = preimage.slice4(preimage.length - 4);
+        uint32 sighashTypeLE = uint32(sighashTypeBytes);
+        return sighashTypeLE.reverseUint32();
+    }
+}

package/contracts/bridge/Heartbeat.sol

@@ -0,0 +1,107 @@
+// 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).
+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/bridge/IRelay.sol

@@ -0,0 +1,28 @@
+// SPDX-License-Identifier: MIT
+
+// ██████████████     ▐████▌     ██████████████
+// ██████████████     ▐████▌     ██████████████
+//               ▐████▌    ▐████▌
+//               ▐████▌    ▐████▌
+// ██████████████     ▐████▌     ██████████████
+// ██████████████     ▐████▌     ██████████████
+//               ▐████▌    ▐████▌
+//               ▐████▌    ▐████▌
+//               ▐████▌    ▐████▌
+//               ▐████▌    ▐████▌
+//               ▐████▌    ▐████▌
+//               ▐████▌    ▐████▌
+
+pragma solidity ^0.8.9;
+
+/// @title Interface for the Bitcoin relay
+/// @notice Contains only the methods needed by tBTC v2. The Bitcoin relay
+///         provides the difficulty of the previous and current epoch. One
+///         difficulty epoch spans 2016 blocks.
+interface IRelay {
+    /// @notice Returns the difficulty of the current epoch.
+    function getCurrentEpochDifficulty() external view returns (uint256);
+
+    /// @notice Returns the difficulty of the previous epoch.
+    function getPrevEpochDifficulty() external view returns (uint256);
+}