Redemptions veto mechanism

solidity/contracts/bridge/Bridge.sol

@@ -236,6 +236,8 @@ contract Bridge is
 
     event TreasuryUpdated(address treasury);
 
+    event RedemptionWatchtowerSet(address redemptionWatchtower);
+
     modifier onlySpvMaintainer() {
         require(
             self.isSpvMaintainer[msg.sender],
@@ -1944,4 +1946,48 @@ contract Bridge is
     function txProofDifficultyFactor() external view returns (uint256) {
         return self.txProofDifficultyFactor;
     }
+
+    /// @notice Sets the redemption watchtower address.
+    /// @param redemptionWatchtower Address of the redemption watchtower.
+    /// @dev Requirements:
+    ///      - The caller must be the governance,
+    ///      - Redemption watchtower address must not be already set,
+    ///      - Redemption watchtower address must not be 0x0.
+    function setRedemptionWatchtower(address redemptionWatchtower)
+        external
+        onlyGovernance
+    {
+        // The internal function is defined in the `BridgeState` library.
+        self.setRedemptionWatchtower(redemptionWatchtower);
+    }
+
+    /// @return Address of the redemption watchtower.
+    function getRedemptionWatchtower() external view returns (address) {
+        return self.redemptionWatchtower;
+    }
+
+    /// @notice Notifies that a redemption request was vetoed in the watchtower.
+    ///         This function is responsible for adjusting the Bridge's state
+    ///         accordingly.
+    ///         The results of calling this function:
+    ///         - the pending redemptions value for the wallet is decreased
+    ///           by the requested amount (minus treasury fee),
+    ///         - the request is removed from pending redemptions mapping,
+    ///         - the tokens taken from the redeemer on redemption request are
+    ///           detained and passed to the redemption watchtower
+    ///           (as Bank's balance) for further processing.
+    /// @param walletPubKeyHash 20-byte public key hash of the wallet.
+    /// @param redeemerOutputScript  The redeemer's length-prefixed output
+    ///        script (P2PKH, P2WPKH, P2SH or P2WSH).
+    /// @dev Requirements:
+    ///      - The caller must be the redemption watchtower,
+    ///      - The redemption request identified by `walletPubKeyHash` and
+    ///        `redeemerOutputScript` must exist.
+    function notifyRedemptionVeto(
+        bytes20 walletPubKeyHash,
+        bytes calldata redeemerOutputScript
+    ) external {
+        // The caller is checked in the internal function.
+        self.notifyRedemptionVeto(walletPubKeyHash, redeemerOutputScript);
+    }
 }

solidity/contracts/bridge/BridgeGovernance.sol

@@ -1766,4 +1766,20 @@ contract BridgeGovernance is Ownable {
     function governanceDelay() internal view returns (uint256) {
         return governanceDelays[0];
     }
+
+    /// @notice Sets the redemption watchtower address. This function does not
+    ///         have a governance delay as setting the redemption watchtower is
+    ///         a one-off action performed during initialization of the
+    ///         redemption veto mechanism.
+    /// @param redemptionWatchtower Address of the redemption watchtower.
+    /// @dev Requirements:
+    ///      - The caller must be the owner,
+    ///      - Redemption watchtower address must not be already set,
+    ///      - Redemption watchtower address must not be 0x0.
+    function setRedemptionWatchtower(address redemptionWatchtower)
+        external
+        onlyOwner
+    {
+        bridge.setRedemptionWatchtower(redemptionWatchtower);
+    }
 }

solidity/contracts/bridge/BridgeState.sol

@@ -181,7 +181,10 @@ library BridgeState {
         // 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.
+        // to the redeemer in full amount. If a redemption watchtower
+        // is set, the redemption timeout should be greater than the maximum
+        // value of the redemption delay that can be enforced by the watchtower.
+        // Consult `IRedemptionWatchtower.getRedemptionDelay` for more details.
         uint32 redemptionTimeout;
         // The amount of stake slashed from each member of a wallet for a
         // redemption timeout.
@@ -314,14 +317,17 @@ library BridgeState {
         // HASH160 over the compressed ECDSA public key) to the basic wallet
         // information like state and pending redemptions value.
         mapping(bytes20 => Wallets.Wallet) registeredWallets;
+        // Address of the redemption watchtower. The redemption watchtower
+        // is responsible for vetoing redemption requests.
+        address redemptionWatchtower;
         // Reserved storage space in case we need to add more variables.
         // The convention from OpenZeppelin suggests the storage space should
         // add up to 50 slots. Here we want to have more slots as there are
         // planned upgrades of the Bridge contract. If more entires are added to
         // the struct in the upcoming versions we need to reduce the array size.
         // See https://docs.openzeppelin.com/contracts/4.x/upgradeable#storage_gaps
         // slither-disable-next-line unused-state
-        uint256[50] __gap;
+        uint256[49] __gap;
     }
 
     event DepositParametersUpdated(
@@ -374,6 +380,8 @@ library BridgeState {
 
     event TreasuryUpdated(address treasury);
 
+    event RedemptionWatchtowerSet(address redemptionWatchtower);
+
     /// @notice Updates parameters of deposits.
     /// @param _depositDustThreshold New value of the deposit dust threshold in
     ///        satoshis. It is the minimal amount that can be requested to
@@ -826,4 +834,27 @@ library BridgeState {
         self.treasury = _treasury;
         emit TreasuryUpdated(_treasury);
     }
+
+    /// @notice Sets the redemption watchtower address.
+    /// @param _redemptionWatchtower Address of the redemption watchtower.
+    /// @dev Requirements:
+    ///      - Redemption watchtower address must not be already set,
+    ///      - Redemption watchtower address must not be 0x0.
+    function setRedemptionWatchtower(
+        Storage storage self,
+        address _redemptionWatchtower
+    ) internal {
+        require(
+            self.redemptionWatchtower == address(0),
+            "Redemption watchtower already set"
+        );
+
+        require(
+            _redemptionWatchtower != address(0),
+            "Redemption watchtower address must not be 0x0"
+        );
+
+        self.redemptionWatchtower = _redemptionWatchtower;
+        emit RedemptionWatchtowerSet(_redemptionWatchtower);
+    }
 }

solidity/contracts/bridge/Redemption.sol

@@ -24,6 +24,45 @@ import "./Wallets.sol";
 
 import "../bank/Bank.sol";
 
+/// @notice Interface of the RedemptionWatchtower.
+interface IRedemptionWatchtower {
+    /// @notice Determines whether a redemption request is considered safe.
+    /// @param walletPubKeyHash 20-byte public key hash of the wallet that
+    ///        is meant to handle the redemption request.
+    /// @param redeemerOutputScript The redeemer's length-prefixed output
+    ///        script (P2PKH, P2WPKH, P2SH or P2WSH) that is meant to
+    ///        receive the redeemed amount.
+    /// @param balanceOwner The address of the Bank balance owner whose balance
+    ///        is getting redeemed.
+    /// @param redeemer The address that requested the redemption and will be
+    ///        able to claim Bank balance if anything goes wrong during the
+    ///        redemption. In the most basic case, when someone redeems their
+    ///        Bitcoin balance from the Bank, `balanceOwner` is the same
+    ///        as `redeemer`. However, when a Vault is redeeming part of its
+    ///        balance for some redeemer address (for example, someone who has
+    ///        earlier deposited into that Vault), `balanceOwner` is the Vault,
+    ///        and `redeemer` is the address for which the vault is redeeming
+    ///        its balance to.
+    /// @return True if the redemption request is safe, false otherwise.
+    ///         Specific safety criteria depend on the implementation.
+    function isSafeRedemption(
+        bytes20 walletPubKeyHash,
+        bytes calldata redeemerOutputScript,
+        address balanceOwner,
+        address redeemer
+    ) external view returns (bool);
+
+    /// @notice Returns the applicable redemption delay for a redemption
+    ///         request identified by the given redemption key.
+    /// @param redemptionKey Redemption key built as
+    ///        `keccak256(keccak256(redeemerOutputScript) | walletPubKeyHash)`.
+    /// @return Redemption delay.
+    function getRedemptionDelay(uint256 redemptionKey)
+        external
+        view
+        returns (uint32);
+}
+
 /// @notice Aggregates functions common to the redemption transaction proof
 ///         validation and to the moving funds transaction proof validation.
 library OutboundTx {
@@ -382,6 +421,8 @@ library Redemption {
     ///        `amount - (amount / redemptionTreasuryFeeDivisor) - redemptionTxMaxFee`.
     ///        Fees values are taken at the moment of request creation.
     /// @dev Requirements:
+    ///      - If the redemption watchtower is set, the redemption request must
+    ///        be considered safe by the watchtower,
     ///      - Wallet behind `walletPubKeyHash` must be live,
     ///      - `mainUtxo` components must point to the recent main UTXO
     ///        of the given wallet, as currently known on the Ethereum chain,
@@ -402,6 +443,19 @@ library Redemption {
         bytes memory redeemerOutputScript,
         uint64 amount
     ) internal {
+        if (self.redemptionWatchtower != address(0)) {
+            require(
+                IRedemptionWatchtower(self.redemptionWatchtower)
+                    .isSafeRedemption(
+                        walletPubKeyHash,
+                        redeemerOutputScript,
+                        balanceOwner,
+                        redeemer
+                    ),
+                "Redemption request rejected by the watchtower"
+            );
+        }
+
         Wallets.Wallet storage wallet = self.registeredWallets[
             walletPubKeyHash
         ];
@@ -1075,4 +1129,67 @@ library Redemption {
         }
         return key;
     }
+
+    /// @notice Notifies that a redemption request was vetoed in the watchtower.
+    ///         This function is responsible for adjusting the Bridge's state
+    ///         accordingly.
+    ///         The results of calling this function:
+    ///         - the pending redemptions value for the wallet is decreased
+    ///           by the requested amount (minus treasury fee),
+    ///         - the request is removed from pending redemptions mapping,
+    ///         - the tokens taken from the redeemer on redemption request are
+    ///           detained and passed to the redemption watchtower
+    ///           (as Bank's balance) for further processing.
+    /// @param walletPubKeyHash 20-byte public key hash of the wallet.
+    /// @param redeemerOutputScript  The redeemer's length-prefixed output
+    ///        script (P2PKH, P2WPKH, P2SH or P2WSH).
+    /// @dev Requirements:
+    ///      - The caller must be the redemption watchtower,
+    ///      - The redemption request identified by `walletPubKeyHash` and
+    ///        `redeemerOutputScript` must exist.
+    function notifyRedemptionVeto(
+        BridgeState.Storage storage self,
+        bytes20 walletPubKeyHash,
+        bytes calldata redeemerOutputScript
+    ) external {
+        require(
+            msg.sender == self.redemptionWatchtower,
+            "Caller is not the redemption watchtower"
+        );
+
+        uint256 redemptionKey = getRedemptionKey(
+            walletPubKeyHash,
+            redeemerOutputScript
+        );
+        Redemption.RedemptionRequest storage redemption = self
+            .pendingRedemptions[redemptionKey];
+
+        // Should never happen, but just in case.
+        require(
+            redemption.requestedAt != 0,
+            "Redemption request does not exist"
+        );
+
+        // Update the wallet's pending redemptions value. This is the
+        // same logic as performed upon redemption request timeout.
+        // If we don't do this, the wallet will hold the reserve
+        // for a redemption request that will never be processed.
+        self.registeredWallets[walletPubKeyHash].pendingRedemptionsValue -=
+            redemption.requestedAmount -
+            redemption.treasuryFee;
+
+        // Capture the amount that should be transferred to the
+        // redemption watchtower. Use the whole requested amount as a detained
+        // amount because the treasury fee is deducted in `submitRedemptionProof`.
+        // Since the redemption did not happen, the treasury fee was not
+        // deducted and the whole requested amount should be detained.
+        uint64 detainedAmount = redemption.requestedAmount;
+
+        // Delete the redemption request from the pending redemptions
+        // mapping. This is important to avoid this redemption request
+        // to be processed by the wallet or reported as timed out.
+        delete self.pendingRedemptions[redemptionKey];
+
+        self.bank.transferBalance(self.redemptionWatchtower, detainedAmount);
+    }
 }