@keep-network/tbtc-v2 0.1.1-dev.13 → 0.1.1-dev.14

package/contracts/bridge/Bridge.sol

@@ -93,7 +93,7 @@ contract Bridge is Ownable {
     }
 
     /// @notice Represents tBTC deposit data.
-    struct DepositInfo {
+    struct DepositRequest {
         // Ethereum depositor address.
         address depositor;
         // Deposit amount in satoshi.
@@ -109,18 +109,113 @@ contract Bridge is Ownable {
         uint32 sweptAt;
     }
 
+    /// @notice Represents a redemption request.
+    struct RedemptionRequest {
+        // ETH address of the redeemer who created the request.
+        address redeemer;
+        // Requested TBTC amount in satoshi.
+        uint64 requestedAmount;
+        // Treasury TBTC fee in satoshi at the moment of request creation.
+        uint64 treasuryFee;
+        // Transaction maximum BTC fee in satoshi at the moment of request
+        // creation.
+        uint64 txMaxFee;
+        // UNIX timestamp the request was created at.
+        uint32 requestedAt;
+    }
+
+    /// @notice Represents an outcome of the redemption Bitcoin transaction
+    ///         outputs processing.
+    struct RedemptionTxOutputsInfo {
+        // Total TBTC value in satoshi that should be burned by the Bridge.
+        // It includes the total amount of all BTC redeemed in the transaction
+        // and the fee paid to BTC miners for the redemption transaction.
+        uint64 totalBurnableValue;
+        // Total TBTC value in satoshi that should be transferred to
+        // the treasury. It is a sum of all treasury fees paid by all
+        // redeemers included in the redemption transaction.
+        uint64 totalTreasuryFee;
+        // Index of the change output. The change output becomes
+        // the new main wallet's UTXO.
+        uint32 changeIndex;
+        // Value in satoshi of the change output.
+        uint64 changeValue;
+    }
+
+    /// @notice Represents wallet state:
+    enum WalletState {
+        /// @dev The wallet is unknown to the Bridge.
+        Unknown,
+        /// @dev The wallet can sweep deposits and accept redemption requests.
+        Active,
+        /// @dev The wallet was deemed unhealthy and is expected to move their
+        ///      outstanding funds to another wallet. The wallet can still
+        ///      fulfill their pending redemption requests although new
+        ///      redemption requests and new deposit reveals are not accepted.
+        MovingFunds,
+        /// @dev The wallet moved or redeemed all their funds and cannot
+        ///      perform any action.
+        Closed,
+        /// @dev The wallet committed a fraud that was reported. The wallet is
+        ///      blocked and can not perform any actions in the Bridge.
+        ///      Off-chain coordination with the wallet operators is needed to
+        ///      recover funds.
+        Terminated
+    }
+
+    /// @notice Holds information about a wallet.
+    struct Wallet {
+        // Current state of the wallet.
+        WalletState state;
+        // The total redeemable value of pending redemption requests targeting
+        // that wallet.
+        uint64 pendingRedemptionsValue;
+    }
+
     /// @notice The number of confirmations on the Bitcoin chain required to
     ///         successfully evaluate an SPV proof.
     uint256 public immutable txProofDifficultyFactor;
 
-    // TODO: Revisit whether it should be updatable or not.
+    /// TODO: Revisit whether it should be governable or not.
     /// @notice Address of the Bank this Bridge belongs to.
     Bank public immutable bank;
 
-    /// TODO: Make it updatable.
+    /// TODO: Make it governable.
     /// @notice Handle to the Bitcoin relay.
     IRelay public immutable relay;
 
+    /// TODO: Revisit whether it should be governable or not.
+    /// @notice Address where the redemptions treasury fees will be sent to.
+    ///         Treasury takes part in the operators rewarding process.
+    address public immutable treasury;
+
+    /// TODO: Make it governable.
+    /// @notice The minimal amount that can be requested for redemption.
+    ///         Value of this parameter should be always bigger than the sum
+    ///         of `redemptionTreasuryFee` and `redemptionTxMaxFee` to make
+    ///         redemptions possible.
+    uint64 public redemptionDustThreshold;
+
+    /// TODO: Make it governable.
+    /// @notice Amount of TBTC that is taken from each redemption request and
+    ///         transferred to the treasury upon successful request finalization.
+    uint64 public redemptionTreasuryFee;
+
+    /// 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.
+    uint64 public 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 public redemptionTimeout;
+
     /// @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
@@ -132,18 +227,66 @@ contract Bridge is Ownable {
 
     /// @notice Collection of all revealed deposits indexed by
     ///         keccak256(fundingTxHash | fundingOutputIndex).
-    ///         The fundingTxHash is LE bytes32 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 => DepositInfo) public deposits;
-
-    /// @notice Maps the wallet public key hash (computed using HASH160 opcode)
-    ///         to the latest wallet's main UTXO computed as
+    ///         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 => DepositRequest) public deposits;
+
+    /// @notice Maps the 20-byte wallet public key hash (computed using
+    ///         Bitcoin HASH160 over the compressed ECDSA public key) to
+    ///         the latest wallet's main UTXO computed as
     ///         keccak256(txHash | txOutputIndex | txOutputValue). The `tx`
     ///         prefix refers to the transaction which created that main UTXO.
+    ///         The txHash is bytes32 (ordered as in Bitcoin internally),
+    ///         txOutputIndex an uint32, and txOutputValue an uint64 value.
     mapping(bytes20 => bytes32) public mainUtxos;
 
+    /// @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
+    ///         - `submitRedemptionFraudProof` in case the request was handled
+    ///           in an fraudulent way amount-wise.
+    mapping(uint256 => RedemptionRequest) public 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.
+    ///
+    // TODO: Remove that Slither disable once this variable is used.
+    // slither-disable-next-line uninitialized-state
+    mapping(uint256 => RedemptionRequest) public timedOutRedemptions;
+
+    /// @notice 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.
+    ///
+    // TODO: Remove that Slither disable once this variable is used.
+    // slither-disable-next-line uninitialized-state
+    mapping(bytes20 => Wallet) public wallets;
+
     event VaultStatusUpdated(address indexed vault, bool isTrusted);
 
     event DepositRevealed(
@@ -160,9 +303,24 @@ contract Bridge is Ownable {
 
     event DepositsSwept(bytes20 walletPubKeyHash, bytes32 sweepTxHash);
 
+    event RedemptionRequested(
+        bytes20 walletPubKeyHash,
+        bytes redeemerOutputScript,
+        address redeemer,
+        uint64 requestedAmount,
+        uint64 treasuryFee,
+        uint64 txMaxFee
+    );
+
+    event RedemptionsCompleted(
+        bytes20 walletPubKeyHash,
+        bytes32 redemptionTxHash
+    );
+
     constructor(
         address _bank,
         address _relay,
+        address _treasury,
         uint256 _txProofDifficultyFactor
     ) {
         require(_bank != address(0), "Bank address cannot be zero");
@@ -171,9 +329,21 @@ contract Bridge is Ownable {
         require(_relay != address(0), "Relay address cannot be zero");
         relay = IRelay(_relay);
 
+        require(_treasury != address(0), "Treasury address cannot be zero");
+        treasury = _treasury;
+
         txProofDifficultyFactor = _txProofDifficultyFactor;
+
+        // TODO: Revisit initial values.
+        redemptionDustThreshold = 1000000; // 1000000 satoshi = 0.01 BTC
+        redemptionTreasuryFee = 100000; // 100000 satoshi
+        redemptionTxMaxFee = 1000; // 1000 satoshi
+        redemptionTimeout = 172800; // 48 hours
     }
 
+    // TODO: Add function `onNewWalletCreated` according to discussion:
+    //       https://github.com/keep-network/tbtc-v2/pull/128#discussion_r809885230
+
     /// @notice Allows the Governance to mark the given vault address as trusted
     ///         or no longer trusted. Vaults are not trusted by default.
     ///         Trusted vault must meet the following criteria:
@@ -234,6 +404,9 @@ contract Bridge is Ownable {
             "Vault is not trusted"
         );
 
+        // TODO: Validate if `walletPubKeyHash` is a known and active wallet.
+        // TODO: Should we enforce a specific locktime at contract level?
+
         bytes memory expectedScript =
             abi.encodePacked(
                 hex"14", // Byte length of depositor Ethereum address.
@@ -308,7 +481,7 @@ contract Bridge is Ownable {
             )
                 .hash256View();
 
-        DepositInfo storage deposit =
+        DepositRequest storage deposit =
             deposits[
                 uint256(
                     keccak256(
@@ -392,7 +565,7 @@ contract Bridge is Ownable {
         // can assume the transaction happened on Bitcoin chain and has
         // a sufficient number of confirmations as determined by
         // `txProofDifficultyFactor` constant.
-        bytes32 sweepTxHash = validateSweepTxProof(sweepTx, sweepProof);
+        bytes32 sweepTxHash = validateBitcoinTxProof(sweepTx, sweepProof);
 
         // Process sweep transaction output and extract its target wallet
         // public key hash and value.
@@ -462,40 +635,40 @@ contract Bridge is Ownable {
         // TODO: Handle deposits having `vault` set.
     }
 
-    /// @notice Validates the SPV proof of the Bitcoin sweep transaction.
+    /// @notice Validates the SPV proof of the Bitcoin transaction.
     ///         Reverts in case the validation or proof verification fail.
-    /// @param sweepTx Bitcoin sweep transaction data
-    /// @param sweepProof Bitcoin sweep proof data
-    /// @return sweepTxHash Proven 32-byte sweep transaction hash.
-    function validateSweepTxProof(
-        BitcoinTx.Info calldata sweepTx,
-        BitcoinTx.Proof calldata sweepProof
-    ) internal view returns (bytes32 sweepTxHash) {
+    /// @param txInfo Bitcoin transaction data
+    /// @param proof Bitcoin proof data
+    /// @return txHash Proven 32-byte transaction hash.
+    function validateBitcoinTxProof(
+        BitcoinTx.Info calldata txInfo,
+        BitcoinTx.Proof calldata proof
+    ) internal view returns (bytes32 txHash) {
         require(
-            sweepTx.inputVector.validateVin(),
+            txInfo.inputVector.validateVin(),
             "Invalid input vector provided"
         );
         require(
-            sweepTx.outputVector.validateVout(),
+            txInfo.outputVector.validateVout(),
             "Invalid output vector provided"
         );
 
-        sweepTxHash = abi
+        txHash = abi
             .encodePacked(
-            sweepTx
+            txInfo
                 .version,
-            sweepTx
+            txInfo
                 .inputVector,
-            sweepTx
+            txInfo
                 .outputVector,
-            sweepTx
+            txInfo
                 .locktime
         )
             .hash256View();
 
-        checkProofFromTxHash(sweepTxHash, sweepProof);
+        checkProofFromTxHash(txHash, proof);
 
-        return sweepTxHash;
+        return txHash;
     }
 
     /// @notice Checks the given Bitcoin transaction hash against the SPV proof.
@@ -686,18 +859,18 @@ contract Bridge is Ownable {
 
         // Inputs processing loop.
         for (uint256 i = 0; i < inputsCount; i++) {
-            // Check if we are at the end of the input vector.
-            if (inputStartingIndex >= sweepTxInputVector.length) {
-                break;
-            }
-
-            (bytes32 inputTxHash, uint32 inputTxIndex, uint256 inputLength) =
-                parseTxInputAt(sweepTxInputVector, inputStartingIndex);
+            (
+                bytes32 outpointTxHash,
+                uint32 outpointIndex,
+                uint256 inputLength
+            ) = parseTxInputAt(sweepTxInputVector, inputStartingIndex);
 
-            DepositInfo storage deposit =
+            DepositRequest storage deposit =
                 deposits[
                     uint256(
-                        keccak256(abi.encodePacked(inputTxHash, inputTxIndex))
+                        keccak256(
+                            abi.encodePacked(outpointTxHash, outpointIndex)
+                        )
                     )
                 ];
 
@@ -726,7 +899,7 @@ contract Bridge is Ownable {
                 processedDepositsCount++;
             } else if (
                 mainUtxoExpected != mainUtxoFound &&
-                mainUtxo.txHash == inputTxHash
+                mainUtxo.txHash == outpointTxHash
             ) {
                 // If we entered here, that means the input was identified as
                 // the expected main UTXO.
@@ -763,9 +936,9 @@ contract Bridge is Ownable {
     /// @notice Parses a Bitcoin transaction input starting at the given index.
     /// @param inputVector Bitcoin transaction input vector
     /// @param inputStartingIndex Index the given input starts at
-    /// @return inputTxHash 32-byte hash of the Bitcoin transaction which is
+    /// @return outpointTxHash 32-byte hash of the Bitcoin transaction which is
     ///         pointed in the given input's outpoint.
-    /// @return inputTxIndex 4-byte index of the Bitcoin transaction output
+    /// @return outpointIndex 4-byte index of the Bitcoin transaction output
     ///         which is pointed in the given input's outpoint.
     /// @return inputLength Byte length of the given input.
     /// @dev This function assumes vector's structure is valid so it must be
@@ -778,26 +951,651 @@ contract Bridge is Ownable {
         internal
         pure
         returns (
-            bytes32 inputTxHash,
-            uint32 inputTxIndex,
+            bytes32 outpointTxHash,
+            uint32 outpointIndex,
             uint256 inputLength
         )
     {
-        inputTxHash = inputVector.extractInputTxIdLeAt(inputStartingIndex);
+        outpointTxHash = inputVector.extractInputTxIdLeAt(inputStartingIndex);
 
-        inputTxIndex = BTCUtils.reverseUint32(
+        outpointIndex = BTCUtils.reverseUint32(
             uint32(inputVector.extractTxIndexLeAt(inputStartingIndex))
         );
 
         inputLength = inputVector.determineInputLengthAt(inputStartingIndex);
 
-        return (inputTxHash, inputTxIndex, inputLength);
+        return (outpointTxHash, outpointIndex, inputLength);
+    }
+
+    /// @notice Requests redemption of the given amount from the specified
+    ///         wallet to the redeemer Bitcoin output script.
+    /// @param walletPubKeyHash The 20-byte wallet public key hash (computed
+    //         using Bitcoin HASH160 over the compressed ECDSA public key)
+    /// @param mainUtxo Data of the wallet's main UTXO, as currently known on
+    ///        the Ethereum chain
+    /// @param redeemerOutputScript The redeemer's length-prefixed output
+    ///        script (P2PKH, P2WPKH, P2SH or P2WSH) that will be used to lock
+    ///        redeemed BTC
+    /// @param amount Requested amount in satoshi. This is also the TBTC amount
+    ///        that is taken from redeemer's balance in the Bank upon request.
+    ///        Once the request is handled, the actual amount of BTC locked
+    ///        on the redeemer output script will be always lower than this value
+    ///        since the treasury and Bitcoin transaction fees must be incurred.
+    ///        The minimal amount satisfying the request can be computed as:
+    ///        `amount - redemptionTreasuryFee - redemptionTxMaxFee`.
+    ///        Fees values are taken at the moment of request creation.
+    /// @dev Requirements:
+    ///      - Wallet behind `walletPubKeyHash` must be active
+    ///      - `mainUtxo` components must point to the recent main UTXO
+    ///        of the given wallet, as currently known on the Ethereum chain.
+    ///      - `redeemerOutputScript` must be a proper Bitcoin script
+    ///      - `redeemerOutputScript` cannot have wallet PKH as payload
+    ///      - `amount` must be above or equal the `redemptionDustThreshold`
+    ///      - Given `walletPubKeyHash` and `redeemerOutputScript` pair can be
+    ///        used for only one pending request at the same time
+    ///      - Wallet must have enough Bitcoin balance to proceed the request
+    ///      - Redeemer must make an allowance in the Bank that the Bridge
+    ///        contract can spend the given `amount`.
+    function requestRedemption(
+        bytes20 walletPubKeyHash,
+        BitcoinTx.UTXO calldata mainUtxo,
+        bytes calldata redeemerOutputScript,
+        uint64 amount
+    ) external {
+        require(
+            wallets[walletPubKeyHash].state == WalletState.Active,
+            "Wallet must be in Active state"
+        );
+
+        bytes32 mainUtxoHash = mainUtxos[walletPubKeyHash];
+        require(
+            mainUtxoHash != bytes32(0),
+            "No main UTXO for the given wallet"
+        );
+        require(
+            keccak256(
+                abi.encodePacked(
+                    mainUtxo.txHash,
+                    mainUtxo.txOutputIndex,
+                    mainUtxo.txOutputValue
+                )
+            ) == mainUtxoHash,
+            "Invalid main UTXO data"
+        );
+
+        // TODO: Confirm if `walletPubKeyHash` should be validated by checking
+        //       if it is the oldest one who can handle the request. This will
+        //       be suggested by the dApp but may not be respected by users who
+        //       interact directly with the contract. Do we need to enforce it
+        //       here? One option is not to enforce it, to save on gas, but if
+        //       we see this rule is not respected, upgrade Bridge contract to
+        //       require it.
+
+        // Validate if redeemer output script is a correct standard type
+        // (P2PKH, P2WPKH, P2SH or P2WSH). This is done by building a stub
+        // output with 0 as value and using `BTCUtils.extractHash` on it. Such
+        // a function extracts the payload properly only from standard outputs
+        // so if it succeeds, we have a guarantee the redeemer output script
+        // is proper. Worth to note `extractHash` ignores the value at all
+        // so this is why we can use 0 safely. This way of validation is the
+        // same as in tBTC v1.
+        bytes memory redeemerOutputScriptPayload =
+            abi.encodePacked(bytes8(0), redeemerOutputScript).extractHash();
+        require(
+            redeemerOutputScriptPayload.length > 0,
+            "Redeemer output script must be a standard type"
+        );
+        // Check if the redeemer output script payload does not point to the
+        // wallet public key hash.
+        require(
+            keccak256(abi.encodePacked(walletPubKeyHash)) !=
+                keccak256(redeemerOutputScriptPayload),
+            "Redeemer output script must not point to the wallet PKH"
+        );
+
+        require(
+            amount >= redemptionDustThreshold,
+            "Redemption amount too small"
+        );
+
+        // The redemption key is built on top of the wallet public key hash
+        // and redeemer output script pair. That means there can be only one
+        // request asking for redemption from the given wallet to the given
+        // BTC script at the same time.
+        uint256 redemptionKey =
+            uint256(
+                keccak256(
+                    abi.encodePacked(walletPubKeyHash, redeemerOutputScript)
+                )
+            );
+
+        // Check if given redemption key is not used by a pending redemption.
+        // There is no need to check for existence in `timedOutRedemptions`
+        // since the wallet's state is changed to other than Active after
+        // first time out is reported so making new requests is not possible.
+        // slither-disable-next-line incorrect-equality
+        require(
+            pendingRedemptions[redemptionKey].requestedAt == 0,
+            "There is a pending redemption request from this wallet to the same address"
+        );
+
+        uint64 treasuryFee = redemptionTreasuryFee;
+        uint64 txMaxFee = redemptionTxMaxFee;
+
+        // The main wallet UTXO's value doesn't include all pending redemptions.
+        // To determine if the requested redemption can be performed by the
+        // wallet we need to subtract the total value of all pending redemptions
+        // from that wallet's main UTXO value. Given that the treasury fee is
+        // not redeemed from the wallet, we are subtracting it.
+        wallets[walletPubKeyHash].pendingRedemptionsValue +=
+            amount -
+            treasuryFee;
+        require(
+            mainUtxo.txOutputValue >=
+                wallets[walletPubKeyHash].pendingRedemptionsValue,
+            "Insufficient wallet funds"
+        );
+
+        pendingRedemptions[redemptionKey] = RedemptionRequest(
+            msg.sender,
+            amount,
+            treasuryFee,
+            txMaxFee,
+            /* solhint-disable-next-line not-rely-on-time */
+            uint32(block.timestamp)
+        );
+
+        emit RedemptionRequested(
+            walletPubKeyHash,
+            redeemerOutputScript,
+            msg.sender,
+            amount,
+            treasuryFee,
+            txMaxFee
+        );
+
+        bank.transferBalanceFrom(msg.sender, address(this), amount);
+    }
+
+    /// @notice Used by the wallet to prove the BTC redemption transaction
+    ///         and to make the necessary bookkeeping. Redemption is only
+    ///         accepted if it satisfies SPV proof.
+    ///
+    ///         The function is performing Bank balance updates by burning
+    ///         the total redeemed Bitcoin amount from Bridge balance and
+    ///         transferring the treasury fee sum to the treasury address.
+    ///
+    ///         It is possible to prove the given redemption only one time.
+    /// @param redemptionTx Bitcoin redemption transaction data
+    /// @param redemptionProof Bitcoin redemption proof data
+    /// @param mainUtxo Data of the wallet's main UTXO, as currently known on
+    ///        the Ethereum chain
+    /// @param walletPubKeyHash 20-byte public key hash (computed using Bitcoin
+    ///        HASH160 over the compressed ECDSA public key) of the wallet which
+    ///        performed the redemption transaction
+    /// @dev Requirements:
+    ///      - `redemptionTx` components must match the expected structure. See
+    ///        `BitcoinTx.Info` docs for reference. Their values must exactly
+    ///        correspond to appropriate Bitcoin transaction fields to produce
+    ///        a provable transaction hash.
+    ///      - The `redemptionTx` should represent a Bitcoin transaction with
+    ///        exactly 1 input that refers to the wallet's main UTXO. That
+    ///        transaction should have 1..n outputs handling existing pending
+    ///        redemption requests or pointing to reported timed out requests.
+    ///        There can be also 1 optional output representing the
+    ///        change and pointing back to the 20-byte wallet public key hash.
+    ///        The change should be always present if the redeemed value sum
+    ///        is lower than the total wallet's BTC balance.
+    ///      - `redemptionProof` components must match the expected structure.
+    ///        See `BitcoinTx.Proof` docs for reference. The `bitcoinHeaders`
+    ///        field must contain a valid number of block headers, not less
+    ///        than the `txProofDifficultyFactor` contract constant.
+    ///      - `mainUtxo` components must point to the recent main UTXO
+    ///        of the given wallet, as currently known on the Ethereum chain.
+    ///        Additionally, the recent main UTXO on Ethereum must be set.
+    ///      - `walletPubKeyHash` must be connected with the main UTXO used
+    ///        as transaction single input.
+    ///      Other remarks:
+    ///      - Putting the change output as the first transaction output can
+    ///        save some gas because the output processing loop begins each
+    ///        iteration by checking whether the given output is the change
+    ///        thus uses some gas for making the comparison. Once the change
+    ///        is identified, that check is omitted in further iterations.
+    function submitRedemptionProof(
+        BitcoinTx.Info calldata redemptionTx,
+        BitcoinTx.Proof calldata redemptionProof,
+        BitcoinTx.UTXO calldata mainUtxo,
+        bytes20 walletPubKeyHash
+    ) external {
+        // TODO: Just as for `submitSweepProof`, fail early if the function
+        //       call gets frontrunned. See discussion:
+        //       https://github.com/keep-network/tbtc-v2/pull/106#discussion_r801745204
+
+        // The actual transaction proof is performed here. After that point, we
+        // can assume the transaction happened on Bitcoin chain and has
+        // a sufficient number of confirmations as determined by
+        // `txProofDifficultyFactor` constant.
+        bytes32 redemptionTxHash =
+            validateBitcoinTxProof(redemptionTx, redemptionProof);
+
+        // Perform validation of the redemption transaction input. Specifically,
+        // check if it refers to the expected wallet's main UTXO.
+        validateRedemptionTxInput(
+            redemptionTx.inputVector,
+            mainUtxo,
+            walletPubKeyHash
+        );
+
+        WalletState walletState = wallets[walletPubKeyHash].state;
+        require(
+            walletState == WalletState.Active ||
+                walletState == WalletState.MovingFunds,
+            "Wallet must be in Active or MovingFuds state"
+        );
+
+        // Process redemption transaction outputs to extract some info required
+        // for further processing.
+        RedemptionTxOutputsInfo memory outputsInfo =
+            processRedemptionTxOutputs(
+                redemptionTx.outputVector,
+                walletPubKeyHash
+            );
+
+        if (outputsInfo.changeValue > 0) {
+            // If the change value is grater than zero, it means the change
+            // output exists and can be used as new wallet's main UTXO.
+            mainUtxos[walletPubKeyHash] = keccak256(
+                abi.encodePacked(
+                    redemptionTxHash,
+                    outputsInfo.changeIndex,
+                    outputsInfo.changeValue
+                )
+            );
+        } else {
+            // If the change value is zero, it means the change output doesn't
+            // exists and no funds left on the wallet. Delete the main UTXO
+            // for that wallet to represent that state in a proper way.
+            delete mainUtxos[walletPubKeyHash];
+        }
+
+        wallets[walletPubKeyHash].pendingRedemptionsValue -= outputsInfo
+            .totalBurnableValue;
+
+        emit RedemptionsCompleted(walletPubKeyHash, redemptionTxHash);
+
+        bank.decreaseBalance(outputsInfo.totalBurnableValue);
+        bank.transferBalance(treasury, outputsInfo.totalTreasuryFee);
+    }
+
+    /// @notice Validates whether the redemption Bitcoin transaction input
+    ///         vector contains a single input referring to the wallet's main
+    ///         UTXO. Reverts in case the validation fails.
+    /// @param redemptionTxInputVector Bitcoin redemption transaction input
+    ///        vector. This function assumes vector's structure is valid so it
+    ///        must be validated using e.g. `BTCUtils.validateVin` function
+    ///        before it is passed here
+    /// @param mainUtxo Data of the wallet's main UTXO, as currently known on
+    ///        the Ethereum chain.
+    /// @param walletPubKeyHash 20-byte public key hash (computed using Bitcoin
+    //         HASH160 over the compressed ECDSA public key) of the wallet which
+    ///        performed the redemption transaction.
+    function validateRedemptionTxInput(
+        bytes memory redemptionTxInputVector,
+        BitcoinTx.UTXO calldata mainUtxo,
+        bytes20 walletPubKeyHash
+    ) internal view {
+        // Assert that main UTXO for passed wallet exists in storage.
+        bytes32 mainUtxoHash = mainUtxos[walletPubKeyHash];
+        require(mainUtxoHash != bytes32(0), "No main UTXO for given wallet");
+
+        // Assert that passed main UTXO parameter is the same as in storage and
+        // can be used for further processing.
+        require(
+            keccak256(
+                abi.encodePacked(
+                    mainUtxo.txHash,
+                    mainUtxo.txOutputIndex,
+                    mainUtxo.txOutputValue
+                )
+            ) == mainUtxoHash,
+            "Invalid main UTXO data"
+        );
+
+        // Assert that the single redemption transaction input actually
+        // refers to the wallet's main UTXO.
+        (bytes32 redemptionTxOutpointTxHash, uint32 redemptionTxOutpointIndex) =
+            processRedemptionTxInput(redemptionTxInputVector);
+        require(
+            mainUtxo.txHash == redemptionTxOutpointTxHash &&
+                mainUtxo.txOutputIndex == redemptionTxOutpointIndex,
+            "Redemption transaction input must point to the wallet's main UTXO"
+        );
+    }
+
+    /// @notice Processes the Bitcoin redemption transaction input vector. It
+    ///         extracts the single input then the transaction hash and output
+    ///         index from its outpoint.
+    /// @param redemptionTxInputVector Bitcoin redemption transaction input
+    ///        vector. This function assumes vector's structure is valid so it
+    ///        must be validated using e.g. `BTCUtils.validateVin` function
+    ///        before it is passed here
+    /// @return outpointTxHash 32-byte hash of the Bitcoin transaction which is
+    ///         pointed in the input's outpoint.
+    /// @return outpointIndex 4-byte index of the Bitcoin transaction output
+    ///         which is pointed in the input's outpoint.
+    function processRedemptionTxInput(bytes memory redemptionTxInputVector)
+        internal
+        pure
+        returns (bytes32 outpointTxHash, uint32 outpointIndex)
+    {
+        // To determine the total number of redemption transaction inputs,
+        // we need to parse the compactSize uint (VarInt) the input vector is
+        // prepended by. That compactSize uint encodes the number of vector
+        // elements using the format presented in:
+        // https://developer.bitcoin.org/reference/transactions.html#compactsize-unsigned-integers
+        // We don't need asserting the compactSize uint is parseable since it
+        // was already checked during `validateVin` validation.
+        // See `BitcoinTx.inputVector` docs for more details.
+        (, uint256 inputsCount) = redemptionTxInputVector.parseVarInt();
+        require(
+            inputsCount == 1,
+            "Redemption transaction must have a single input"
+        );
+
+        bytes memory input = redemptionTxInputVector.extractInputAtIndex(0);
+
+        outpointTxHash = input.extractInputTxIdLE();
+
+        outpointIndex = BTCUtils.reverseUint32(
+            uint32(input.extractTxIndexLE())
+        );
+
+        // There is only one input in the transaction. Input has an outpoint
+        // field that is a reference to the transaction being spent (see
+        // `BitcoinTx` docs). The outpoint contains the hash of the transaction
+        // to spend (`outpointTxHash`) and the index of the specific output
+        // from that transaction (`outpointIndex`).
+        return (outpointTxHash, outpointIndex);
+    }
+
+    /// @notice Processes the Bitcoin redemption transaction output vector.
+    ///         It extracts each output and tries to identify it as a pending
+    ///         redemption request, reported timed out request, or change.
+    ///         Reverts if one of the outputs cannot be recognized properly.
+    ///         This function also marks each request as processed by removing
+    ///         them from `pendingRedemptions` mapping.
+    /// @param redemptionTxOutputVector Bitcoin redemption transaction output
+    ///        vector. This function assumes vector's structure is valid so it
+    ///        must be validated using e.g. `BTCUtils.validateVout` function
+    ///        before it is passed here
+    /// @param walletPubKeyHash 20-byte public key hash (computed using Bitcoin
+    //         HASH160 over the compressed ECDSA public key) of the wallet which
+    ///        performed the redemption transaction.
+    /// @return info Outcomes of the processing.
+    function processRedemptionTxOutputs(
+        bytes memory redemptionTxOutputVector,
+        bytes20 walletPubKeyHash
+    ) internal returns (RedemptionTxOutputsInfo memory info) {
+        // Determining the total number of redemption transaction outputs in
+        // the same way as for number of inputs. See `BitcoinTx.outputVector`
+        // docs for more details.
+        (uint256 outputsCompactSizeUintLength, uint256 outputsCount) =
+            redemptionTxOutputVector.parseVarInt();
+
+        // To determine the first output starting index, we must jump over
+        // the compactSize uint which prepends the output 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 outputStartingIndex = 1 + outputsCompactSizeUintLength;
+
+        // Calculate the keccak256 for two possible wallet's P2PKH or P2WPKH
+        // scripts that can be used to lock the change. This is done upfront to
+        // save on gas. Both scripts have a strict format defined by Bitcoin.
+        //
+        // The P2PKH script has format <0x1976a914> <20-byte PKH> <0x88ac>.
+        bytes32 walletP2PKHScriptKeccak =
+            keccak256(
+                abi.encodePacked(hex"1976a914", walletPubKeyHash, hex"88ac")
+            );
+        // The P2WPKH script has format <0x160014> <20-byte PKH>.
+        bytes32 walletP2WPKHScriptKeccak =
+            keccak256(abi.encodePacked(hex"160014", walletPubKeyHash));
+
+        // Helper variable that counts the number of processed redemption
+        // outputs. Redemptions can be either pending or reported as timed out.
+        // TODO: Revisit the approach with redemptions count according to
+        //       https://github.com/keep-network/tbtc-v2/pull/128#discussion_r808237765
+        uint256 processedRedemptionsCount = 0;
+
+        // Outputs processing loop.
+        for (uint256 i = 0; i < outputsCount; i++) {
+            // TODO: Check if we can optimize gas costs by adding
+            //       `extractValueAt` and `extractHashAt` in `bitcoin-spv-sol`
+            //       in order to avoid allocating bytes in memory.
+            uint256 outputLength =
+                redemptionTxOutputVector.determineOutputLengthAt(
+                    outputStartingIndex
+                );
+            bytes memory output =
+                redemptionTxOutputVector.slice(
+                    outputStartingIndex,
+                    outputLength
+                );
+
+            // Extract the value from given output.
+            uint64 outputValue = output.extractValue();
+            // The output consists of an 8-byte value and a variable length
+            // script. To extract that script we slice the output staring from
+            // 9th byte until the end.
+            bytes memory outputScript = output.slice(8, output.length - 8);
+
+            if (
+                info.changeValue == 0 &&
+                (keccak256(outputScript) == walletP2PKHScriptKeccak ||
+                    keccak256(outputScript) == walletP2WPKHScriptKeccak) &&
+                outputValue > 0
+            ) {
+                // If we entered here, that means the change output with a
+                // proper non-zero value was found.
+                info.changeIndex = uint32(i);
+                info.changeValue = outputValue;
+            } else {
+                // If we entered here, that the means the given output is
+                // supposed to represent a redemption. Build the redemption key
+                // to perform that check.
+                uint256 redemptionKey =
+                    uint256(
+                        keccak256(
+                            abi.encodePacked(walletPubKeyHash, outputScript)
+                        )
+                    );
+
+                if (pendingRedemptions[redemptionKey].requestedAt != 0) {
+                    // If we entered here, that means the output was identified
+                    // as a pending redemption request.
+                    RedemptionRequest storage request =
+                        pendingRedemptions[redemptionKey];
+                    // Compute the request's redeemable amount as the requested
+                    // amount reduced by the treasury fee. The request's
+                    // minimal amount is then the redeemable amount reduced by
+                    // the maximum transaction fee.
+                    uint64 redeemableAmount =
+                        request.requestedAmount - request.treasuryFee;
+                    // Output value must fit between the request's redeemable
+                    // and minimal amounts to be deemed valid.
+                    require(
+                        redeemableAmount - request.txMaxFee <= outputValue &&
+                            outputValue <= redeemableAmount,
+                        "Output value is not within the acceptable range of the pending request"
+                    );
+                    // Add the redeemable amount to the total burnable value
+                    // the Bridge will use to decrease its balance in the Bank.
+                    info.totalBurnableValue += redeemableAmount;
+                    // Add the request's treasury fee to the total treasury fee
+                    // value the Bridge will transfer to the treasury.
+                    info.totalTreasuryFee += request.treasuryFee;
+                    // Request was properly handled so remove its redemption
+                    // key from the mapping to make it reusable for further
+                    // requests.
+                    delete pendingRedemptions[redemptionKey];
+
+                    processedRedemptionsCount++;
+                } else {
+                    // If we entered here, the output is not a redemption
+                    // request but there is still a chance the given output is
+                    // related to a reported timed out redemption request.
+                    // If so, check if the output value matches the request
+                    // amount to confirm this is an overdue request fulfillment
+                    // then bypass this output and process the subsequent
+                    // ones. That also means the wallet was already punished
+                    // for the inactivity. Otherwise, just revert.
+                    RedemptionRequest storage request =
+                        timedOutRedemptions[redemptionKey];
+
+                    require(
+                        request.requestedAt != 0,
+                        "Output is a non-requested redemption"
+                    );
+
+                    uint64 redeemableAmount =
+                        request.requestedAmount - request.treasuryFee;
+
+                    require(
+                        redeemableAmount - request.txMaxFee <= outputValue &&
+                            outputValue <= redeemableAmount,
+                        "Output value is not within the acceptable range of the timed out request"
+                    );
+
+                    processedRedemptionsCount++;
+                }
+            }
+
+            // Make the `outputStartingIndex` pointing to the next output by
+            // increasing it by current output's length.
+            outputStartingIndex += outputLength;
+        }
+
+        // Protect against the cases when there is only a single change output
+        // referring back to the wallet PKH and just burning main UTXO value
+        // for transaction fees.
+        require(
+            processedRedemptionsCount > 0,
+            "Redemption transaction must process at least one redemption"
+        );
+
+        return info;
     }
 
-    // TODO It is possible a malicious wallet can sweep deposits that can not
-    //      be later proved on Ethereum. For example, a deposit with
-    //      an incorrect amount revealed. We need to provide a function for honest
-    //      depositors, next to sweep, to prove their swept balances on Ethereum
-    //      selectively, based on deposits they have earlier received.
-    //      (UPDATE PR #90: Is it still the case since amounts are inferred?)
+    // TODO: Function `notifyRedemptionTimeout. That function must:
+    //       1. Take a the `walletPubKey` and `redeemerOutputScript` as params.
+    //       2. Build the redemption key using those params.
+    //       3. Use the redemption key and take the request from
+    //          `pendingRedemptions` mapping.
+    //       4. If request doesn't exist in mapping - revert.
+    //       5. If request exits, and is timed out - remove the redemption key
+    //          from `pendingRedemptions` and put it to `timedOutRedemptions`
+    //          by copying the entire `RedemptionRequest` struct there. No need
+    //          to check if `timedOutRedemptions` mapping already contains
+    //          that key because `requestRedemption` blocks requests targeting
+    //          non-active wallets. Because `notifyRedemptionTimeout` changes
+    //          wallet state after first call (point 9), there is no possibility
+    //          that the given redemption key could be reported as timed out
+    //          multiple times. At the same time, if the given redemption key
+    //          was already marked as fraudulent due to an amount-related fraud,
+    //          it will not be possible to report a time out on it since it
+    //          won't be present in `pendingRedemptions` mapping.
+    //       6. Return the `requestedAmount` to the `redeemer`.
+    //       7. Reduce the `pendingRedemptionsValue` (`wallets` mapping) for
+    //          given wallet by request's redeemable amount computed as
+    //          `requestedAmount - treasuryFee`.
+    //       8. Punish the wallet, probably by slashing its operators.
+    //       9. Change wallet's state in `wallets` mapping to `MovingFunds` in
+    //          order to prevent against new redemption requests hitting
+    //          that wallet.
+    //      10. Expect the wallet to transfer its funds to another healthy
+    //          wallet (just as in case of failed heartbeat). The wallet is
+    //          expected to finish the already queued redemption requests
+    //          before moving funds but we are not going to enforce it on-chain.
+
+    // TODO: Function `submitRedemptionFraudProof`
+    //
+    //       Deposit and redemption fraud proofs are challenging to implement
+    //       and it may happen we will have to rely on the coverage pool
+    //       (https://github.com/keep-network/coverage-pools) and DAO to
+    //       reimburse unlucky depositors and bring back the balance to the
+    //       system in case  of a wallet fraud by liquidating a part of the
+    //       coverage pool manually.
+    //
+    //       The probability of 51-of-100 wallet being fraudulent is negligible:
+    //       https://github.com/keep-network/tbtc-v2/blob/main/docs/rfc/rfc-2.adoc#111-group-size-and-threshold
+    //       and the coverage pool would be there to bring the balance back in
+    //       case we are unlucky and malicious wallet emerges.
+    //
+    //       We do not want to slash for a misbehavior that is not provable
+    //       on-chain and it is possible to construct such a Bitcoin transaction
+    //       that is not provable on Ethereum, see
+    //       https://consensys.net/diligence/blog/2020/05/tbtc-navigating-the-cross-chain-conundrum
+    //
+    //       The algorithm described below assumes we will be able to prove the
+    //       TX on Ethereum which may not always be the case. Consider the steps
+    //       below as an idea, and not necessarily how this function will be
+    //       implemented because it may happen this function will never be
+    //       implemented, given the Bitcoin transaction size problems.
+    //
+    //       The algorithm:
+    //       1. Take a `BitcoinTx.Info` and `BitcoinTx.Proof` of the
+    //          fraudulent transaction. It should also accept `walletPubKeyHash`
+    //          and index of fraudulent output. Probably index of fraudulent
+    //          input will be also required if the transaction is supposed
+    //          to have a bad input vector.
+    //       2. Perform SPV proof to make sure it occurred on Bitcoin chain.
+    //          If not - revert.
+    //       3. Check if wallet state is Active or MovingFunds. If not, revert.
+    //       4. Validate the number of inputs. If there is one input and it
+    //          points to the wallet's main UTXO - move to point 5. If there
+    //          are multiple inputs and there is wallet's main UTXO in the set,
+    //          check if this is  a sweep transaction. If it's not a sweep,
+    //          consider it as fraudulent and move to point 6.
+    //          In all other cases revert the call.
+    //       5. Extract the output and analyze its type. The output is not
+    //          a fraud and the call should be reverted ONLY IF one of the
+    //          following conditions is true:
+    //          - Output is a requested redemption held by `pendingRedemptions`
+    //            and output value fulfills the request range. There is an
+    //            open question if a misfunded request should be removed
+    //            from `pendingRedemptions` (probably yes) and whether the
+    //            redeemer should be reimbursed in case of an underfund.
+    //          - Output is a timed out redemption held by `timedOutRedemptions`
+    //            and output value fulfills the request range.
+    //          - Output is a proper change i.e. a single output targeting
+    //            the wallet PKH back and having a non-zero value.
+    //          - Wallet is in MovingFunds state, the output points to the
+    //            expected target wallet, have non-zero value, and is a single
+    //            output in the vector.
+    //          In all other cases consider the transaction as fraud and
+    //          proceed to point 6.
+    //       6. Punish the wallet, probably by severely slashing its operators.
+    //       7. Change wallet's state in `wallets` mapping to `Terminated` in
+    //          order to prevent against new redemption requests hitting
+    //          that wallet. This also prevents against reporting a fraud
+    //          multiple times for one transaction (see point 3) and blocks
+    //          submission of sweep and redemption proofs. `Terminated` wallet
+    //          is blocked in the Bridge forever. If the fraud was a mistake
+    //          done by the wallet and the wallet is still honest deep in its
+    //          heart, the wallet can coordinate off-chain to recover the BTC
+    //          and donate it to another wallet. If they recover all of the
+    //          remaining BTC, DAO might decide to reward them with tokens so
+    //          that they can have at least some portion of their slashed
+    //          tokens back.
 }