Implement basic redemptions veto mechanism (TIP-072) #781
Comments
This was referenced Feb 20, 2024
tomaszslabon
added a commit
that referenced
this issue
Mar 6, 2024
Closes: #781 Here we present the implementation of the redemptions veto mechanism, specified in the [TIP-072: Optimistic redemptions](https://forum.threshold.network/t/tip-072-optimistic-redemptions/793). ### High-level architecture The current byte size of the `Bridge` contract (~22 kB) is close to the limit. To leave some space for future `Bridge` upgrades, we decided to encapsulate the logic of the redemption veto mechanism in a separate upgradeable contract called `RedemptionWatchtower`, and attach it to the existing `Bridge` instance. Such a design has a positive impact on the `Bridge` size, nicely separates the concerns, and reduces the amount of direct changes in the living `Bridge` instance. The `RedemptionWatchtower` contract acts as a central point for redemption guardians, manages vetoed redemptions, and provides other functionality specified in the TIP. It also serves as a source of information about vetoed redemptions, banned redeemers, and processing delays that should be preserved for specific redemption requests. The chart below presents how the `RedemptionWatchtower` fits into the existing architecture and provides an overview of interactions between relevant smart contracts and system actors: ``` +---------------+ | | +---------+ Wallets +-------------+ | | | | pendingRedemptions | +---------------+ | validateRedemptionProposal | | | | v v +--------------------------+ +-----------------------------+ | | pendingRedemptions | | | Bridge |<-------------------------+ WalletProposalValidator | | | | | +----+---------------------+ +-------+---------------------+ | ^ | | | | | | | | | | getRedemptionDelay | | notifyRedemptionVeto | | +---------+ | | | | | | | | isSafeRedemption +----+---------------------+ | +-------------------->| |<------+ | RedemptionWatchtower | +------->| |<------+ | +--------------------------+ | | ^ | | | | | | | raiseObjection | | management | security | | actions | actions | | | | | | +-------+-------+ +-------+-------+ +-------+-------+ | | | | | | | Guardians | | Manager | | Owner | | | | | | | +---------------+ +---------------+ +---------------+ ``` ### The `RedemptionWatchtower` contract The `RedemptionWatchtower` contract interacts with several actors of the protocol. Each actor has a different set of capabilities: **Owner (Threshold Council)** The owner can call the following functions: - `enableWatchtower` which enables the veto mechanism for the first time. This function must set the watchtower's manager and can establish an initial set of guardians. This function also captures the timestamp of the call. This information is necessary to ensure the proper lifecycle of the veto mechanism (shut down after 18 months). It is also crucial for determining stalled redemptions that were created in the pre-veto era and can be vetoed indefinitely. - `removeGuardian` that can be used to remove specific guardians. This function is a safeguard against malicious guardians hence, it must be directly available to the owner. **Manager (Token holder DAO)** As per the TIP, most of the governance should be the authority of the Token holder DAO. To make it possible, we are introducing the role of the watchtower's manager who can use the following functions: - `addGuardian` which allows adding new redemption guardians - `updateWatchtowerParameters` that can update all governable parameters that steer the veto mechanism. Those parameters are redemption veto delays, veto time and financial penalties, and the mechanism lifetime. - `unban` which can be used to unban redeemers who were banned mistakenly. This is a safeguard for guardian mistakes that must be in place to protect honest redeemers. **Guardians** Guardians are the executors of the veto process. The only function they can call is `raiseObjection`. That function should be used to raise objections against specific redemption requests. Three subsequent objections lead to a redemption veto. Vetoed redemptions are not processed by the protocol, the requested amount is diminished by a penalty fee, and frozen for a specific time. Once the freeze period ends, the redeemer can claim those funds back. Moreover, redeemers whose redemptions were vetoed become banned and cannot ask for redemptions in the future. Last but not least, even a single objection (not leading to a veto) against a redemption (from a given wallet to a given BTC address) prevents asking the same wallet to redeem to the same BTC address in the future (this is similar to timed out redemptions). **Others** The `RedemptionWatchtower` exposes some functions available to the broad public. Those are: - `isSafeRedemption` which determines whether a redemption involving a specific wallet, BTC address, Bank's balance owner, and redeemer can be considered as safe. This function leverages the objections history and banned redeemers to determine so. A redemption is considered safe if neither the balance owner nor redeemer is banned and past redemptions from the given wallet to the given BTC address were not subject to guardian objections. - `getRedemptionDelay` that informs tBTC wallets about processing delays that should be preserved for specific redemption requests. Delays are determined based on raised objections. - `withdrawVetoedFunds` which can be used by redeemers to withdraw funds from vetoed redemptions once the freeze period ends. - `disableWatchtower` that can be used by anyone to disable the veto mechanism once the watchtower's lifetime elapses. ### Changes in the `Bridge` contract Integration of the `RedemptionWatchtower` contract with the existing `Bridge` incurs several changes in the latter. First and foremost, the `Bridge`'s state gains a new address field (`redemptionWatchtower`) that points to the `RedemptionWatchtower` contract. That field can be set using the new `setRedemptionWatchtower` function available for the `Bridge`'s governance. Secondly, the `Bridge` exposes a new `notifyRedemptionVeto` callback function. This function can be called only by the `redemptionWatchtower` address. The main responsibility of this function is propagating the consequences of a redemption veto to the `Bridge`'s state, namely: - Reduce the pending redemptions value of the target wallet (supposed to handle the vetoed redemption). This is the same action as performed upon redemption timeout. This must be done because otherwise, the wallet would hold the reserve for a redemption request that would never be processed - Delete the redemption request from the pending redemptions mapping. This is important to avoid the vetoed redemption request being processed by the wallet or reported as timed out - Detain the redemption's request amount and transfer it under the control of the redemption watchtower for further processing (i.e. burn the penalty fee and allow withdrawal of the rest after the freeze period) Last but not least, the `Bridge` leverages the `redemptionWatchtower` address to determine the safety of upcoming redemption requests. This is achieved using the `isSafeRedemption` call. This way, redemptions from banned redeemers (and balance owners) are blocked. The same applies to redemptions from specific wallets to specific BTC addresses which were subject to guardian objections in the past. ### Changes in the `WalletProposalValidator` contract The last piece of the puzzle is the integration of the veto mechanism with the off-chain tBTC wallets. Wallets must respect the new veto delay and not process redemptions during the period a redemption veto can still land. According to [RFC-12](https://github.com/keep-network/tbtc-v2/blob/main/docs/rfc/rfc-12.adoc#224-introduce-the-walletproposalvalidator-contract), the tBTC wallets always consult the `WalletProposalValidator` to validate the ongoing redemption proposal before issuing the redemption transaction on the Bitcoin chain. That means it is enough to modify the `WalletProposalValidator.validateRedemptionProposal` function and take the veto delay into account there. The `validateRedemptionProposal` function calls the `RedemptionWatchtower.getRedemptionDelay` function for each redemption in the proposal and considers it valid only if the returned veto delay (counted since the redemption creation timestamp) already elapsed. This logic guarantees that a particular redemption proposal can only be considered valid if all of its redemption requests have surpassed their respective veto delay periods. In light of the above, we should also prevent invalid redemption proposals (with redemptions violating the veto delay) from being issued by RFC-12 coordinators. An invalid proposal means a coordination window miss and the optimal strategy here is ensuring proposal validity at generation time. This requires adjustments in the [off-chain redemption proposal generator logic](https://github.com/keep-network/keep-core/blob/2a76f4de820eb13b2d49c67a15a59eac7552fa26/pkg/tbtcpg/redemptions.go#L70). This work is beyond the scope of this pull request and will be addressed in a follow-up PR. The ultimate protection against wallets not obeying the aforementioned rules is the fact that vetoed redemptions are removed from the `pendingRedemption` set in the `Bridge`. That means the `Bridge` will reject an SPV proof of a redemption transaction that handles at least one vetoed redemption request (that happens in the `submitRedemptionProof` function). In such a case, the given wallet will be deemed as fraudulent and punished according to the protocol rules.
tomaszslabon
added a commit
to keep-network/keep-core
that referenced
this issue
Mar 7, 2024
Refs: keep-network/tbtc-v2#781 Depends on: keep-network/tbtc-v2#788 (the `client-build-test-publish` job will become green once 788 is merged and a new `tbtc-v2@development` package with `RedemptionWatchtower` artifact will be published to npm) The optimistic redemption upgrade introduces a veto mechanism (keep-network/tbtc-v2#788) that enforces a processing delay on each redemption request. The exact delay value depends on the number of objections raised against the given redemption request. The `WalletProposalValidator` contract has been modified to include validation of that delay factor. The first change ed9c4ae introduces the same for the redemption proposal generator. This ensures the generator issues proposals that conform to the on-chain validation rules and coordination windows are not being wasted. By the way, we are taking an opportunity to optimize the deposit sweep proposal generation. The `WalletProposalValidator` contract enforces the minimum age of a deposit that can become part of the proposal. The proposal generator was missing this check and was often producing invalid proposals that were violating the on-chain minimum deposit age rule. We fix that in 55be487.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
This task is about implementing the initial version of the redemptions veto mechanism, as specified in TIP-072: Optimistic redemptions. The scope of this task includes all necessary contract-side changes that will allow guardians to issue objections. The scope DOES NOT include guardian automation.
Tasks
The text was updated successfully, but these errors were encountered: