diff --git a/safe-modules/timelock-guard.md b/safe-modules/timelock-guard.md new file mode 100644 index 00000000..84f38df1 --- /dev/null +++ b/safe-modules/timelock-guard.md @@ -0,0 +1,169 @@ +# TimelockGuard + +## Context and Problem Statement + + + +[Safe Accounts](https://safe.global) are configured as a set of owner addresses where some +threshold of addresses can sign and ultimately execute a transaction through the account. One +common concern with Safe accounts is that, by default, transactions execute immediately once signed +without any type of delay. + +A mandatory transaction delay is a significant improvement in the security model for Safe accounts +because it provides ample time for review and entirely mitigates the impact of compromised signing +machines. It would be immensely valuable to OP Labs and Optimism Foundation multisig operations if +all multisigs managed by these entities were to require mandatory delays. We want to build a +component that we can fit into our existing multisigs that provides this delay with minimal +configuration and minimal overhead for both signers and multisig leads. + +## Customer Description + + + +The customers for this design doc are any participants in the multisig accounts that would utilize +this guard, as well as any 3rd parties who rely on the security properties of these accounts. + +### Customer Reviewers + + + +- Optimism Foundation Finance +- OP Labs Finance + +## Requirements and Constraints + + + +- Mitigate the impact of a malicious majority of owners capable to execute a single transaction. +- Mitigate the impact of an honest majority approving a malicious or erroneous transaction. +- Keep code as minimal as possible to avoid complex logic in Safe modules/guards. +- Limit mental overhead for Safe owners and multisig leads, don't break workflows if possible. +- Apply cleanly for all of the major multisigs. +- Support nonceless execution, which we are planning to implement for operational reasons. +- The designed solution should be aplicable to single and arbitrarily nested Safe configurations. + +## Proposed Solution + + + +We propose the introduction of a new Safe guard, the `TimelockGuard`. The `TimelockGuard` would +take advantage of functionality in the latest version of Safe accounts to enforce a mandatory +timelock with minimal effort on the part of signers and a mostly unchanged workflow for multisig +leads. + +### Singleton + +`TimelockGuard` is a singleton that exists at a known address on all chains and has no constructor +parameters. Any Safe on any network can choose to configure the Guard and then enable the Guard +within the Safe. + +The timelock guard will be merged with the liveness module contract that we install so that we can +install the exact same contract address on any safe and just configure it during installation. + +### Configuration + +A transaction from the Safe configures the Guard by executing a transaction that sets +a delay period. + +### Transaction Execution Flow + +1. Users sign the transaction normally, either via the UI or via `superchain-ops`. +2. Anyone can collect the signatures and send the transaction calldata along with the signatures + to `TimelockGuard.schedule`, instead of executing via `Safe.execTransaction`. This function has + the exact same inputs as `execTransaction` and is therefore compatible with both the standard + Safe and the proposed nonceless execution module. +3. `TimelockGuard.schedule` verifies the signatures attached to the transaction and starts a timer + for execution of the transaction. +4. After the specified time, anyone can then call `Safe.execTransaction` as normal and execution + will complete as expected. + +### Replayability Of Transactions +Each scheduled transaction would be identified by a hash derived from the transaction parameters, +which already include a nonce for replayability protection. Cancelled transactions will be marked +as cancelled so that they can't be scheduled again with the same signatures. + +### Storage Of Scheduled Transactions +Scheduled transactions will be stored with as many of its parameters as possible, limited by the +gas required to execute the most complex expected transactions withi projected block gas limits. +Rich transaction data helps with identifying the effects of a transaction, in particular to +external operators such as bug bounty hunters that might lack the tools or the context from +internal operators. + +### Transaction Cancellation Flow +To cancel a scheduled transaction, a `cancellation_threshold` number of owners would need to +signal that they agree with the cancellation. Cancelled transactions would need to be signed again +to be scheduled again. + +In nested safe setups, the owners of a child multisig would need to signal the rejection of the +transaction in numbers no less than the `cancellation_threshold` of the child multisig, for the +child multisig to signal rejection of the transaction to the parent multisig. + +#### Dynamic `cancellation_threshold` +A `cancellation_threshold` of 1 is convenient for usability as it requires the least +number of owners to signal their agreement to cancel a transaction in an emergency situation. + +However, a `cancellation_threshold` that is set too low can also be abused by malicious owners to +permanently block the multisig from executing transactions, inducing a liveness failure. + +A dynamic `cancellation_threshold` is chosen as a best compromise between security and usability. +The `cancellation_threshold` would start at 1 and increase by 1 with each successful consecutive +cancellation. The `cancellation_threshold` would reset to 1 with the successful execution of an +scheduled transaction. + +The upper boundary to the `cancellation_threshold` would be the "blocking minority", defined as +the minimum number of `owners` that can stop the multisig from approving transactions, which is +`min(quorum, total_owners - quorum + 1)`. + +### Interaction with the LivenessModule +The LivenessModule will execute an ownership change through the safe if a challenge is successful, +this ownership challenge should not be cancellable, so it shouldn't be subject to the scheduling +flow. + +When using a LivenessModule, the liveness challenges are responded with a regular transaction which +is subject to the timelock delay, and as such the LivenessModule needs to have a challenge response +time that allows for both assembling a quorum of signers and executed a delayed transaction. An +integrated LivenessModule and TimelockGuard is a viable option. + +## Alternatives Considered + + +Other potential designs that were considered make trade-offs for security or usability that are +suboptimal. Examples of this are: + +- Allowing any user to reveal a transaction for later execution, which creates more considerations + for monitoring/offchain infrastructure and changes the transaction flow. +- Having multisigs queue transaction via the timelock directly and then allowing anyone to execute + the transaction via a module, which changes the signing flow significantly and means transactions + are challenging to simulate properly. +- Configurable `cancellation_thresholds` were considered, but the risk of misconfiguration over + time was expected to be considerable. +- A fixed `cancellation_threshold` of 1 was considered, but the risk of operational disruption by + malicious actors was considered unacceptable. + +We could not find any alternative design with the simplicity and security of the one that was +ultimately presented in this document. + +## Risks and Uncertainties + + + +### Timelock Overhead +Any type of mandatory timelock introduces overhead for multisigs that want to execute transactions +in a timely fashion. Multisig leads will have to plan ahead of time in a way that they were not +previously required to do. + +### Time Critical Transactions +Some multisigs may face scenarios where they need to be able to execute transactions very quickly +in a worst-case scenario. We should do our best to avoid these situations as much as possible and +use other protocol features (like the Pause) to mitigate them entirely. + +Instant execution is not required for finance multisigs. The delay will however be no longer than +the time required for a transaction review by trained finance staff.