@keep-network/tbtc-v2 0.1.1-dev.9 → 0.1.1-dev.90

package/contracts/bank/Bank.sol

@@ -13,24 +13,25 @@
 //               ▐████▌    ▐████▌
 //               ▐████▌    ▐████▌
 
-pragma solidity 0.8.4;
+pragma solidity ^0.8.9;
 
 import "@openzeppelin/contracts/access/Ownable.sol";
 
+import "./IReceiveBalanceApproval.sol";
 import "../vault/IVault.sol";
 
 /// @title Bitcoin Bank
 /// @notice Bank is a central component tracking Bitcoin balances. Balances can
-///         be transferred between holders and holders can approve their
-///         balances to be spent by others. Balances in the Bank are updated for
-///         depositors who deposit their Bitcoin into the Bridge and only the
-///         Bridge can increase balances.
+///         be transferred between balance owners, and balance owners can
+///         approve their balances to be spent by others. Balances in the Bank
+///         are updated for depositors who deposited their Bitcoin into the
+///         Bridge and only the Bridge can increase balances.
 /// @dev Bank is a governable contract and the Governance can upgrade the Bridge
 ///      address.
 contract Bank is Ownable {
     address public bridge;
 
-    /// @notice The balance of a given account in the Bank. Zero by default.
+    /// @notice The balance of the given account in the Bank. Zero by default.
     mapping(address => uint256) public balanceOf;
 
     /// @notice The remaining amount of balance a spender will be
@@ -38,16 +39,17 @@ contract Bank is Ownable {
     ///         `transferBalanceFrom`. Zero by default.
     mapping(address => mapping(address => uint256)) public allowance;
 
-    /// @notice Returns the current nonce for EIP2612 permission for the
-    ///         provided balance owner for a replay protection. Used to
-    ///         construct EIP2612 signature provided to `permit` function.
+    /// @notice Returns the current nonce for an EIP2612 permission for the
+    ///         provided balance owner to protect against replay attacks. Used
+    ///         to construct an EIP2612 signature provided to the `permit`
+    ///         function.
     mapping(address => uint256) public nonce;
 
     uint256 public immutable cachedChainId;
     bytes32 public immutable cachedDomainSeparator;
 
-    /// @notice Returns EIP2612 Permit message hash. Used to construct EIP2612
-    ///         signature provided to `permit` function.
+    /// @notice Returns an EIP2612 Permit message hash. Used to construct
+    ///         an EIP2612 signature provided to the `permit` function.
     bytes32 public constant PERMIT_TYPEHASH =
         keccak256(
             "Permit(address owner,address spender,uint256 value,uint256 nonce,uint256 deadline)"
@@ -86,6 +88,9 @@ contract Bank is Ownable {
     ///      check the status of the Bridge. The Governance implementation needs
     ///      to ensure all requirements for the upgrade are satisfied before
     ///      executing this function.
+    ///      Requirements:
+    ///      - The new Bridge address must not be zero.
+    /// @param _bridge The new Bridge address.
     function updateBridge(address _bridge) external onlyOwner {
         require(_bridge != address(0), "Bridge address must not be 0x0");
         bridge = _bridge;
@@ -97,25 +102,59 @@ contract Bank is Ownable {
     /// @dev Requirements:
     ///       - `recipient` cannot be the zero address,
     ///       - the caller must have a balance of at least `amount`.
+    /// @param recipient The recipient of the balance.
+    /// @param amount The amount of the balance transferred.
     function transferBalance(address recipient, uint256 amount) external {
         _transferBalance(msg.sender, recipient, amount);
     }
 
     /// @notice Sets `amount` as the allowance of `spender` over the caller's
     ///         balance.
-    /// @dev If the `amount` is set to `type(uint256).max` then
+    /// @dev If the `amount` is set to `type(uint256).max`,
     ///      `transferBalanceFrom` will not reduce an allowance.
     ///      Beware that changing an allowance with this function brings the
     ///      risk that someone may use both the old and the new allowance by
     ///      unfortunate transaction ordering. Please use
     ///      `increaseBalanceAllowance` and `decreaseBalanceAllowance` to
     ///      eliminate the risk.
+    /// @param spender The address that will be allowed to spend the balance.
+    /// @param amount The amount the spender is allowed to spend.
     function approveBalance(address spender, uint256 amount) external {
         _approveBalance(msg.sender, spender, amount);
     }
 
-    /// @notice Atomically increases the balance allowance granted to `spender`
-    ///         by the caller by the given `addedValue`.
+    /// @notice Sets the `amount` as an allowance of a smart contract `spender`
+    ///         over the caller's balance and calls the `spender` via
+    ///         `receiveBalanceApproval`.
+    /// @dev If the `amount` is set to `type(uint256).max`, the potential
+    ///     `transferBalanceFrom` executed in `receiveBalanceApproval` of
+    ///      `spender` will not reduce an allowance. Beware that changing an
+    ///      allowance with this function brings the risk that `spender` may use
+    ///      both the old and the new allowance by unfortunate transaction
+    ///      ordering. Please use `increaseBalanceAllowance` and
+    ///      `decreaseBalanceAllowance` to eliminate the risk.
+    /// @param spender The smart contract that will be allowed to spend the
+    ///        balance.
+    /// @param amount The amount the spender contract is allowed to spend.
+    /// @param extraData Extra data passed to the `spender` contract via
+    ///        `receiveBalanceApproval` call.
+    function approveBalanceAndCall(
+        address spender,
+        uint256 amount,
+        bytes calldata extraData
+    ) external {
+        _approveBalance(msg.sender, spender, amount);
+        IReceiveBalanceApproval(spender).receiveBalanceApproval(
+            msg.sender,
+            amount,
+            extraData
+        );
+    }
+
+    /// @notice Atomically increases the caller's balance allowance granted to
+    ///         `spender` by the given `addedValue`.
+    /// @param spender The spender address for which the allowance is increased.
+    /// @param addedValue The amount by which the allowance is increased.
     function increaseBalanceAllowance(address spender, uint256 addedValue)
         external
     {
@@ -126,8 +165,14 @@ contract Bank is Ownable {
         );
     }
 
-    /// @notice Atomically decreases the balance allowance granted to `spender`
-    ///         by the caller by the given `subtractedValue`.
+    /// @notice Atomically decreases the caller's balance allowance granted to
+    ///         `spender` by the given `subtractedValue`.
+    /// @dev Requirements:
+    ///      - `spender` must not be the zero address,
+    ///      - the current allowance for `spender` must not be lower than
+    ///        the `subtractedValue`.
+    /// @param spender The spender address for which the allowance is decreased.
+    /// @param subtractedValue The amount by which the allowance is decreased.
     function decreaseBalanceAllowance(address spender, uint256 subtractedValue)
         external
     {
@@ -151,8 +196,11 @@ contract Bank is Ownable {
     /// @dev Requirements:
     ///      - `recipient` cannot be the zero address,
     ///      - `spender` must have a balance of at least `amount`,
-    ///      - the caller must have allowance for `spender`'s balance of at
+    ///      - the caller must have an allowance for `spender`'s balance of at
     ///        least `amount`.
+    /// @param spender The address from which the balance is transferred.
+    /// @param recipient The address to which the balance is transferred.
+    /// @param amount The amount of balance that is transferred.
     function transferBalanceFrom(
         address spender,
         address recipient,
@@ -171,12 +219,13 @@ contract Bank is Ownable {
         _transferBalance(spender, recipient, amount);
     }
 
-    /// @notice EIP2612 approval made with secp256k1 signature.
-    ///         Users can authorize a transfer of their balance with a signature
-    ///         conforming EIP712 standard, rather than an on-chain transaction
-    ///         from their address. Anyone can submit this signature on the
-    ///         user's behalf by calling the permit function, paying gas fees,
-    ///         and possibly performing other actions in the same transaction.
+    /// @notice An EIP2612 approval made with secp256k1 signature. Users can
+    ///         authorize a transfer of their balance with a signature
+    ///         conforming to the EIP712 standard, rather than an on-chain
+    ///         transaction from their address. Anyone can submit this signature
+    ///         on the user's behalf by calling the `permit` function, paying
+    ///         gas fees, and possibly performing other actions in the same
+    ///         transaction.
     /// @dev The deadline argument can be set to `type(uint256).max to create
     ///      permits that effectively never expire.  If the `amount` is set
     ///      to `type(uint256).max` then `transferBalanceFrom` will not
@@ -185,6 +234,13 @@ contract Bank is Ownable {
     ///      new allowance by unfortunate transaction ordering. Please use
     ///      `increaseBalanceAllowance` and `decreaseBalanceAllowance` to
     ///      eliminate the risk.
+    /// @param owner The balance owner who signed the permission.
+    /// @param spender The address that will be allowed to spend the balance.
+    /// @param amount The amount the spender is allowed to spend.
+    /// @param deadline The UNIX time until which the permit is valid.
+    /// @param v V part of the permit signature.
+    /// @param r R part of the permit signature.
+    /// @param s S part of the permit signature.
     function permit(
         address owner,
         address spender,
@@ -207,23 +263,22 @@ contract Bank is Ownable {
         );
         require(v == 27 || v == 28, "Invalid signature 'v' value");
 
-        bytes32 digest =
-            keccak256(
-                abi.encodePacked(
-                    "\x19\x01",
-                    DOMAIN_SEPARATOR(),
-                    keccak256(
-                        abi.encode(
-                            PERMIT_TYPEHASH,
-                            owner,
-                            spender,
-                            amount,
-                            nonce[owner]++,
-                            deadline
-                        )
+        bytes32 digest = keccak256(
+            abi.encodePacked(
+                "\x19\x01",
+                DOMAIN_SEPARATOR(),
+                keccak256(
+                    abi.encode(
+                        PERMIT_TYPEHASH,
+                        owner,
+                        spender,
+                        amount,
+                        nonce[owner]++,
+                        deadline
                     )
                 )
-            );
+            )
+        );
         address recoveredAddress = ecrecover(digest, v, r, s);
         require(
             recoveredAddress != address(0) && recoveredAddress == owner,
@@ -235,7 +290,10 @@ contract Bank is Ownable {
     /// @notice Increases balances of the provided `recipients` by the provided
     ///         `amounts`. Can only be called by the Bridge.
     /// @dev Requirements:
-    ///       - length of `recipients` and `amounts` must be the same.
+    ///       - length of `recipients` and `amounts` must be the same,
+    ///       - none of `recipients` addresses must point to the Bank.
+    /// @param recipients Balance increase recipients.
+    /// @param amounts Amounts by which balances are increased.
     function increaseBalances(
         address[] calldata recipients,
         uint256[] calldata amounts
@@ -251,6 +309,10 @@ contract Bank is Ownable {
 
     /// @notice Increases balance of the provided `recipient` by the provided
     ///         `amount`. Can only be called by the Bridge.
+    /// @dev Requirements:
+    ///      - `recipient` address must not point to the Bank.
+    /// @param recipient Balance increase recipient.
+    /// @param amount Amount by which the balance is increased.
     function increaseBalance(address recipient, uint256 amount)
         external
         onlyBridge
@@ -259,39 +321,37 @@ contract Bank is Ownable {
     }
 
     /// @notice Increases the given smart contract `vault`'s balance and
-    ///         notifies the `vault` contract. Called by the Bridge after
-    ///         the deposits routed by depositors to that `vault` have been
-    ///         swept by the Bridge. This way, the depositor does not have to
-    ///         issue a separate  transaction to the `vault` contract.
+    ///         notifies the `vault` contract about it.
     ///         Can be called only by the Bridge.
     /// @dev Requirements:
     ///       - `vault` must implement `IVault` interface,
-    ///       - length of `depositors` and `depositedAmounts` must be the same.
-    /// @param vault Address of `IVault` recipient contract
-    /// @param depositors Addresses of depositors whose deposits have been swept
-    /// @param depositedAmounts Amounts deposited by individual depositors and
-    ///        swept. The `vault`'s balance in the Bank will be increased by the
-    ///        sum of all elements in this array.
+    ///       - length of `recipients` and `amounts` must be the same.
+    /// @param vault Address of `IVault` recipient contract.
+    /// @param recipients Balance increase recipients.
+    /// @param amounts Amounts by which balances are increased.
     function increaseBalanceAndCall(
         address vault,
-        address[] calldata depositors,
-        uint256[] calldata depositedAmounts
+        address[] calldata recipients,
+        uint256[] calldata amounts
     ) external onlyBridge {
         require(
-            depositors.length == depositedAmounts.length,
+            recipients.length == amounts.length,
             "Arrays must have the same length"
         );
         uint256 totalAmount = 0;
-        for (uint256 i = 0; i < depositedAmounts.length; i++) {
-            totalAmount += depositedAmounts[i];
+        for (uint256 i = 0; i < amounts.length; i++) {
+            totalAmount += amounts[i];
         }
         _increaseBalance(vault, totalAmount);
-        IVault(vault).onBalanceIncreased(depositors, depositedAmounts);
+        IVault(vault).receiveBalanceIncrease(recipients, amounts);
     }
 
     /// @notice Decreases caller's balance by the provided `amount`. There is no
     ///         way to restore the balance so do not call this function unless
     ///         you really know what you are doing!
+    /// @dev Requirements:
+    ///      - The caller must have a balance of at least `amount`.
+    /// @param amount The amount by which the balance is decreased.
     function decreaseBalance(uint256 amount) external {
         balanceOf[msg.sender] -= amount;
         emit BalanceDecreased(msg.sender, amount);
@@ -299,7 +359,7 @@ contract Bank is Ownable {
 
     /// @notice Returns hash of EIP712 Domain struct with `TBTC Bank` as
     ///         a signing domain and Bank contract as a verifying contract.
-    ///         Used to construct EIP2612 signature provided to `permit`
+    ///         Used to construct an EIP2612 signature provided to the `permit`
     ///         function.
     /* solhint-disable-next-line func-name-mixedcase */
     function DOMAIN_SEPARATOR() public view returns (bytes32) {
@@ -342,7 +402,9 @@ contract Bank is Ownable {
 
         uint256 spenderBalance = balanceOf[spender];
         require(spenderBalance >= amount, "Transfer amount exceeds balance");
-        unchecked {balanceOf[spender] = spenderBalance - amount;}
+        unchecked {
+            balanceOf[spender] = spenderBalance - amount;
+        }
         balanceOf[recipient] += amount;
         emit BalanceTransferred(spender, recipient, amount);
     }

package/contracts/bank/IReceiveBalanceApproval.sol

@@ -0,0 +1,45 @@
+// SPDX-License-Identifier: MIT
+
+// ██████████████     ▐████▌     ██████████████
+// ██████████████     ▐████▌     ██████████████
+//               ▐████▌    ▐████▌
+//               ▐████▌    ▐████▌
+// ██████████████     ▐████▌     ██████████████
+// ██████████████     ▐████▌     ██████████████
+//               ▐████▌    ▐████▌
+//               ▐████▌    ▐████▌
+//               ▐████▌    ▐████▌
+//               ▐████▌    ▐████▌
+//               ▐████▌    ▐████▌
+//               ▐████▌    ▐████▌
+
+pragma solidity ^0.8.9;
+
+/// @title IReceiveBalanceApproval
+/// @notice `IReceiveBalanceApproval` is an interface for a smart contract
+///         consuming Bank balances approved to them in the same transaction by
+///         other contracts or externally owned accounts (EOA).
+interface IReceiveBalanceApproval {
+    /// @notice Called by the Bank in `approveBalanceAndCall` function after
+    ///         the balance `owner` approved `amount` of their balance in the
+    ///         Bank for the contract. This way, the depositor can approve
+    ///         balance and call the contract to use the approved balance in
+    ///         a single transaction.
+    /// @param owner Address of the Bank balance owner who approved their
+    ///        balance to be used by the contract.
+    /// @param amount The amount of the Bank balance approved by the owner
+    ///        to be used by the contract.
+    /// @param extraData The `extraData` passed to `Bank.approveBalanceAndCall`.
+    /// @dev The implementation must ensure this function can only be called
+    ///      by the Bank. The Bank does _not_ guarantee that the `amount`
+    ///      approved by the `owner` currently exists on their balance. That is,
+    ///      the `owner` could approve more balance than they currently have.
+    ///      This works the same as `Bank.approve` function. The contract must
+    ///      ensure the actual balance is checked before performing any action
+    ///      based on it.
+    function receiveBalanceApproval(
+        address owner,
+        uint256 amount,
+        bytes calldata extraData
+    ) external;
+}

package/contracts/bridge/BitcoinTx.sol

@@ -13,20 +13,26 @@
 //               ▐████▌    ▐████▌
 //               ▐████▌    ▐████▌
 
-pragma solidity 0.8.4;
+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 {ValidateSPV} from "@keep-network/bitcoin-spv-sol/contracts/ValidateSPV.sol";
+
+import "./BridgeState.sol";
 
 /// @title Bitcoin transaction
 /// @notice Allows to reference Bitcoin raw transaction in Solidity.
 /// @dev See https://developer.bitcoin.org/reference/transactions.html#raw-transaction-format
 ///
-///      Raw Bitcon transaction data:
+///      Raw Bitcoin transaction data:
 ///
 ///      | Bytes  |     Name     |        BTC type        |        Description        |
 ///      |--------|--------------|------------------------|---------------------------|
 ///      | 4      | version      | int32_t (LE)           | TX version number         |
 ///      | varies | tx_in_count  | compactSize uint (LE)  | Number of TX inputs       |
 ///      | varies | tx_in        | txIn[]                 | TX inputs                 |
-///      | varies | tx_out count | compactSize uint (LE)  | Number of TX outputs      |
+///      | varies | tx_out_count | compactSize uint (LE)  | Number of TX outputs      |
 ///      | varies | tx_out       | txOut[]                | TX outputs                |
 ///      | 4      | lock_time    | uint32_t (LE)          | Unix time or block number |
 ///
@@ -36,8 +42,8 @@ pragma solidity 0.8.4;
 ///      | Bytes  |       Name       |        BTC type        |                 Description                 |
 ///      |--------|------------------|------------------------|---------------------------------------------|
 ///      | 36     | previous_output  | outpoint               | The previous outpoint being spent           |
-///      | varies | script bytes     | compactSize uint (LE)  | The number of bytes in the signature script |
-///      | varies | signature script | char[]                 | The signature script, empty for P2WSH       |
+///      | varies | script_bytes     | compactSize uint (LE)  | The number of bytes in the signature script |
+///      | varies | signature_script | char[]                 | The signature script, empty for P2WSH       |
 ///      | 4      | sequence         | uint32_t (LE)          | Sequence number                             |
 ///
 ///
@@ -68,17 +74,37 @@ pragma solidity 0.8.4;
 ///
 ///      (*) compactSize uint is often references as VarInt)
 ///
+///      Coinbase transaction input (txIn):
+///
+///      | Bytes  |       Name       |        BTC type        |                 Description                 |
+///      |--------|------------------|------------------------|---------------------------------------------|
+///      | 32     | hash             | char[32]               | A 32-byte 0x0  null (no previous_outpoint)  |
+///      | 4      | index            | uint32_t (LE)          | 0xffffffff (no previous_outpoint)           |
+///      | varies | script_bytes     | compactSize uint (LE)  | The number of bytes in the coinbase script  |
+///      | varies | height           | char[]                 | The block height of this block (BIP34) (*)  |
+///      | varies | coinbase_script  | none                   |  Arbitrary data, max 100 bytes              |
+///      | 4      | sequence         | uint32_t (LE)          | Sequence number
+///
+///      (*)  Uses script language: starts with a data-pushing opcode that indicates how many bytes to push to
+///           the stack followed by the block height as a little-endian unsigned integer. This script must be as
+///           short as possible, otherwise it may be rejected. The data-pushing opcode will be 0x03 and the total
+///           size four bytes until block 16,777,216 about 300 years from now.
 library BitcoinTx {
-    /// @notice Represents Bitcoin transaction data for funding BTC deposit
-    ///         P2(W)SH transaction.
+    using BTCUtils for bytes;
+    using BTCUtils for uint256;
+    using BytesLib for bytes;
+    using ValidateSPV for bytes;
+    using ValidateSPV for bytes32;
+
+    /// @notice Represents Bitcoin transaction data.
     struct Info {
-        /// @notice Bitcoin transaction version
-        /// @dev `version` from raw Bitcon transaction data.
+        /// @notice Bitcoin transaction version.
+        /// @dev `version` from raw Bitcoin transaction data.
         ///      Encoded as 4-bytes signed integer, little endian.
         bytes4 version;
         /// @notice All Bitcoin transaction inputs, prepended by the number of
         ///         transaction inputs.
-        /// @dev `tx_in_count | tx_in` from raw Bitcon transaction data.
+        /// @dev `tx_in_count | tx_in` from raw Bitcoin transaction data.
         ///
         ///      The number of transaction inputs encoded as compactSize
         ///      unsigned integer, little-endian.
@@ -100,5 +126,201 @@ library BitcoinTx {
         /// @dev `lock_time` from raw Bitcoin transaction data.
         ///      Encoded as 4-bytes unsigned integer, little endian.
         bytes4 locktime;
+        // This struct doesn't contain `__gap` property as the structure is not
+        // stored, it is used as a function's calldata argument.
+    }
+
+    /// @notice Represents data needed to perform a Bitcoin SPV proof.
+    struct Proof {
+        /// @notice The merkle proof of transaction inclusion in a block.
+        bytes merkleProof;
+        /// @notice Transaction index in the block (0-indexed).
+        uint256 txIndexInBlock;
+        /// @notice Single byte-string of 80-byte bitcoin headers,
+        ///         lowest height first.
+        bytes bitcoinHeaders;
+        // This struct doesn't contain `__gap` property as the structure is not
+        // stored, it is used as a function's calldata argument.
+    }
+
+    /// @notice Represents info about an unspent transaction output.
+    struct UTXO {
+        /// @notice Hash of the transaction the output belongs to.
+        /// @dev Byte order corresponds to the Bitcoin internal byte order.
+        bytes32 txHash;
+        /// @notice Index of the transaction output (0-indexed).
+        uint32 txOutputIndex;
+        /// @notice Value of the transaction output.
+        uint64 txOutputValue;
+        // This struct doesn't contain `__gap` property as the structure is not
+        // stored, it is used as a function's calldata argument.
+    }
+
+    /// @notice Represents Bitcoin signature in the R/S/V format.
+    struct RSVSignature {
+        /// @notice Signature r value.
+        bytes32 r;
+        /// @notice Signature s value.
+        bytes32 s;
+        /// @notice Signature recovery value.
+        uint8 v;
+        // This struct doesn't contain `__gap` property as the structure is not
+        // stored, it is used as a function's calldata argument.
+    }
+
+    /// @notice Validates the SPV proof of the Bitcoin transaction.
+    ///         Reverts in case the validation or proof verification fail.
+    /// @param txInfo Bitcoin transaction data.
+    /// @param proof Bitcoin proof data.
+    /// @return txHash Proven 32-byte transaction hash.
+    function validateProof(
+        BridgeState.Storage storage self,
+        Info calldata txInfo,
+        Proof calldata proof
+    ) internal view returns (bytes32 txHash) {
+        require(
+            txInfo.inputVector.validateVin(),
+            "Invalid input vector provided"
+        );
+        require(
+            txInfo.outputVector.validateVout(),
+            "Invalid output vector provided"
+        );
+
+        txHash = abi
+            .encodePacked(
+                txInfo.version,
+                txInfo.inputVector,
+                txInfo.outputVector,
+                txInfo.locktime
+            )
+            .hash256View();
+
+        require(
+            txHash.prove(
+                proof.bitcoinHeaders.extractMerkleRootLE(),
+                proof.merkleProof,
+                proof.txIndexInBlock
+            ),
+            "Tx merkle proof is not valid for provided header and tx hash"
+        );
+
+        evaluateProofDifficulty(self, proof.bitcoinHeaders);
+
+        return txHash;
+    }
+
+    /// @notice Evaluates the given Bitcoin proof difficulty against the actual
+    ///         Bitcoin chain difficulty provided by the relay oracle.
+    ///         Reverts in case the evaluation fails.
+    /// @param bitcoinHeaders Bitcoin headers chain being part of the SPV
+    ///        proof. Used to extract the observed proof difficulty.
+    function evaluateProofDifficulty(
+        BridgeState.Storage storage self,
+        bytes memory bitcoinHeaders
+    ) internal view {
+        IRelay relay = self.relay;
+        uint256 currentEpochDifficulty = relay.getCurrentEpochDifficulty();
+        uint256 previousEpochDifficulty = relay.getPrevEpochDifficulty();
+
+        uint256 requestedDiff = 0;
+        uint256 firstHeaderDiff = bitcoinHeaders
+            .extractTarget()
+            .calculateDifficulty();
+
+        if (firstHeaderDiff == currentEpochDifficulty) {
+            requestedDiff = currentEpochDifficulty;
+        } else if (firstHeaderDiff == previousEpochDifficulty) {
+            requestedDiff = previousEpochDifficulty;
+        } else {
+            revert("Not at current or previous difficulty");
+        }
+
+        uint256 observedDiff = bitcoinHeaders.validateHeaderChain();
+
+        require(
+            observedDiff != ValidateSPV.getErrBadLength(),
+            "Invalid length of the headers chain"
+        );
+        require(
+            observedDiff != ValidateSPV.getErrInvalidChain(),
+            "Invalid headers chain"
+        );
+        require(
+            observedDiff != ValidateSPV.getErrLowWork(),
+            "Insufficient work in a header"
+        );
+
+        require(
+            observedDiff >= requestedDiff * self.txProofDifficultyFactor,
+            "Insufficient accumulated difficulty in header chain"
+        );
+    }
+
+    /// @notice Extracts public key hash from the provided P2PKH or P2WPKH output.
+    ///         Reverts if the validation fails.
+    /// @param output The transaction output.
+    /// @return pubKeyHash 20-byte public key hash the output locks funds on.
+    /// @dev Requirements:
+    ///      - The output must be of P2PKH or P2WPKH type and lock the funds
+    ///        on a 20-byte public key hash.
+    function extractPubKeyHash(BridgeState.Storage storage, bytes memory output)
+        internal
+        pure
+        returns (bytes20 pubKeyHash)
+    {
+        bytes memory pubKeyHashBytes = output.extractHash();
+
+        require(
+            pubKeyHashBytes.length == 20,
+            "Output's public key hash must have 20 bytes"
+        );
+
+        pubKeyHash = pubKeyHashBytes.slice20(0);
+
+        // We need to make sure that the 20-byte public key hash
+        // is actually used in the right context of a P2PKH or P2WPKH
+        // output. To do so, we must extract the full script from the output
+        // and compare with the expected P2PKH and P2WPKH scripts
+        // referring to that 20-byte public key hash. The output consists
+        // of an 8-byte value and a variable length script. To extract the
+        // script we slice the output starting from 9th byte until the end.
+        bytes32 outputScriptKeccak = keccak256(
+            output.slice(8, output.length - 8)
+        );
+        // Build the expected P2PKH script which has the following byte
+        // format: <0x1976a914> <20-byte PKH> <0x88ac>. According to
+        // https://en.bitcoin.it/wiki/Script#Opcodes this translates to:
+        // - 0x19: Byte length of the entire script
+        // - 0x76: OP_DUP
+        // - 0xa9: OP_HASH160
+        // - 0x14: Byte length of the public key hash
+        // - 0x88: OP_EQUALVERIFY
+        // - 0xac: OP_CHECKSIG
+        // which matches the P2PKH structure as per:
+        // https://en.bitcoin.it/wiki/Transaction#Pay-to-PubkeyHash
+        bytes32 P2PKHScriptKeccak = keccak256(
+            abi.encodePacked(hex"1976a914", pubKeyHash, hex"88ac")
+        );
+        // Build the expected P2WPKH script which has the following format:
+        // <0x160014> <20-byte PKH>. According to
+        // https://en.bitcoin.it/wiki/Script#Opcodes this translates to:
+        // - 0x16: Byte length of the entire script
+        // - 0x00: OP_0
+        // - 0x14: Byte length of the public key hash
+        // which matches the P2WPKH structure as per:
+        // https://github.com/bitcoin/bips/blob/master/bip-0141.mediawiki#P2WPKH
+        bytes32 P2WPKHScriptKeccak = keccak256(
+            abi.encodePacked(hex"160014", pubKeyHash)
+        );
+        // Make sure the actual output script matches either the P2PKH
+        // or P2WPKH format.
+        require(
+            outputScriptKeccak == P2PKHScriptKeccak ||
+                outputScriptKeccak == P2WPKHScriptKeccak,
+            "Output must be P2PKH or P2WPKH"
+        );
+
+        return pubKeyHash;
     }
 }