Skip to content

Commit a446dbc

Browse files
smartcontractsalcuecamaurelianalcueca
authored
feat: TimelockGuard (#324)
* feat: TimelockGuard introduces the TimelockGuard proposal. * Update safe-modules/timelock-guard.md Co-authored-by: Maurelian <[email protected]> * Resolved comments, added cancellation feature, removed dual delay * Incorporated other notes from the design review * Final edits with regards to cancellation threshold and cancellation flow implementation * Added possibility of dynamic cancellation threshold * Included comment on single contract for liveness module and timelock guard * removed .DS_Store * addressed multiple comments from @wildmolasses and @smartcontracts * Edited for clarity after adressing the comments. * Details around instant execution * Update safe-modules/timelock-guard.md Co-authored-by: Maurelian <[email protected]> * Removing L1PAO from scope * Allowing for a disabled timelock to be installed * We can just not enable the guard * Making it clear that the timelock guard and the liveness module are a single contract. --------- Co-authored-by: Alberto Cuesta Cañada <[email protected]> Co-authored-by: Maurelian <[email protected]> Co-authored-by: alcueca <[email protected]> Co-authored-by: Alberto Cuesta Cañada <[email protected]>
1 parent 0c5401e commit a446dbc

File tree

1 file changed

+169
-0
lines changed

1 file changed

+169
-0
lines changed

‎safe-modules/timelock-guard.md‎

Lines changed: 169 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,169 @@
1+
# TimelockGuard
2+
3+
## Context and Problem Statement
4+
5+
<!-- The Context and Problem Statement section is one of the most critical parts of the design
6+
document process. Use this section to clearly highlight the background context for the problem,
7+
the specific issues being faced by customers, and any constraints on a solution as defined either
8+
by customers or by technical limitations. Context and Problem Statement is an opportunity to tell
9+
the story that helps to motivate the rest of the design document. -->
10+
11+
[Safe Accounts](https://safe.global) are configured as a set of owner addresses where some
12+
threshold of addresses can sign and ultimately execute a transaction through the account. One
13+
common concern with Safe accounts is that, by default, transactions execute immediately once signed
14+
without any type of delay.
15+
16+
A mandatory transaction delay is a significant improvement in the security model for Safe accounts
17+
because it provides ample time for review and entirely mitigates the impact of compromised signing
18+
machines. It would be immensely valuable to OP Labs and Optimism Foundation multisig operations if
19+
all multisigs managed by these entities were to require mandatory delays. We want to build a
20+
component that we can fit into our existing multisigs that provides this delay with minimal
21+
configuration and minimal overhead for both signers and multisig leads.
22+
23+
## Customer Description
24+
25+
<!-- Provide a brief summary of the customers for this design document. -->
26+
27+
The customers for this design doc are any participants in the multisig accounts that would utilize
28+
this guard, as well as any 3rd parties who rely on the security properties of these accounts.
29+
30+
### Customer Reviewers
31+
32+
<!-- Identify at least one customer who should be involved in the review of this document. -->
33+
34+
- Optimism Foundation Finance
35+
- OP Labs Finance
36+
37+
## Requirements and Constraints
38+
39+
<!-- Identify the solution requirements and any additional design constraints from the Context and
40+
Problem Statement section in a bulleted list. -->
41+
42+
- Mitigate the impact of a malicious majority of owners capable to execute a single transaction.
43+
- Mitigate the impact of an honest majority approving a malicious or erroneous transaction.
44+
- Keep code as minimal as possible to avoid complex logic in Safe modules/guards.
45+
- Limit mental overhead for Safe owners and multisig leads, don't break workflows if possible.
46+
- Apply cleanly for all of the major multisigs.
47+
- Support nonceless execution, which we are planning to implement for operational reasons.
48+
- The designed solution should be aplicable to single and arbitrarily nested Safe configurations.
49+
50+
## Proposed Solution
51+
52+
<!-- Explain the solution that you believe best addresses the problem described above. -->
53+
54+
We propose the introduction of a new Safe guard, the `TimelockGuard`. The `TimelockGuard` would
55+
take advantage of functionality in the latest version of Safe accounts to enforce a mandatory
56+
timelock with minimal effort on the part of signers and a mostly unchanged workflow for multisig
57+
leads.
58+
59+
### Singleton
60+
61+
`TimelockGuard` is a singleton that exists at a known address on all chains and has no constructor
62+
parameters. Any Safe on any network can choose to configure the Guard and then enable the Guard
63+
within the Safe.
64+
65+
The timelock guard will be merged with the liveness module contract that we install so that we can
66+
install the exact same contract address on any safe and just configure it during installation.
67+
68+
### Configuration
69+
70+
A transaction from the Safe configures the Guard by executing a transaction that sets
71+
a delay period.
72+
73+
### Transaction Execution Flow
74+
75+
1. Users sign the transaction normally, either via the UI or via `superchain-ops`.
76+
2. Anyone can collect the signatures and send the transaction calldata along with the signatures
77+
to `TimelockGuard.schedule`, instead of executing via `Safe.execTransaction`. This function has
78+
the exact same inputs as `execTransaction` and is therefore compatible with both the standard
79+
Safe and the proposed nonceless execution module.
80+
3. `TimelockGuard.schedule` verifies the signatures attached to the transaction and starts a timer
81+
for execution of the transaction.
82+
4. After the specified time, anyone can then call `Safe.execTransaction` as normal and execution
83+
will complete as expected.
84+
85+
### Replayability Of Transactions
86+
Each scheduled transaction would be identified by a hash derived from the transaction parameters,
87+
which already include a nonce for replayability protection. Cancelled transactions will be marked
88+
as cancelled so that they can't be scheduled again with the same signatures.
89+
90+
### Storage Of Scheduled Transactions
91+
Scheduled transactions will be stored with as many of its parameters as possible, limited by the
92+
gas required to execute the most complex expected transactions withi projected block gas limits.
93+
Rich transaction data helps with identifying the effects of a transaction, in particular to
94+
external operators such as bug bounty hunters that might lack the tools or the context from
95+
internal operators.
96+
97+
### Transaction Cancellation Flow
98+
To cancel a scheduled transaction, a `cancellation_threshold` number of owners would need to
99+
signal that they agree with the cancellation. Cancelled transactions would need to be signed again
100+
to be scheduled again.
101+
102+
In nested safe setups, the owners of a child multisig would need to signal the rejection of the
103+
transaction in numbers no less than the `cancellation_threshold` of the child multisig, for the
104+
child multisig to signal rejection of the transaction to the parent multisig.
105+
106+
#### Dynamic `cancellation_threshold`
107+
A `cancellation_threshold` of 1 is convenient for usability as it requires the least
108+
number of owners to signal their agreement to cancel a transaction in an emergency situation.
109+
110+
However, a `cancellation_threshold` that is set too low can also be abused by malicious owners to
111+
permanently block the multisig from executing transactions, inducing a liveness failure.
112+
113+
A dynamic `cancellation_threshold` is chosen as a best compromise between security and usability.
114+
The `cancellation_threshold` would start at 1 and increase by 1 with each successful consecutive
115+
cancellation. The `cancellation_threshold` would reset to 1 with the successful execution of an
116+
scheduled transaction.
117+
118+
The upper boundary to the `cancellation_threshold` would be the "blocking minority", defined as
119+
the minimum number of `owners` that can stop the multisig from approving transactions, which is
120+
`min(quorum, total_owners - quorum + 1)`.
121+
122+
### Interaction with the LivenessModule
123+
The LivenessModule will execute an ownership change through the safe if a challenge is successful,
124+
this ownership challenge should not be cancellable, so it shouldn't be subject to the scheduling
125+
flow.
126+
127+
When using a LivenessModule, the liveness challenges are responded with a regular transaction which
128+
is subject to the timelock delay, and as such the LivenessModule needs to have a challenge response
129+
time that allows for both assembling a quorum of signers and executed a delayed transaction. An
130+
integrated LivenessModule and TimelockGuard is a viable option.
131+
132+
## Alternatives Considered
133+
<!-- Describe any alternatives that were considered during the development of this design. Explain
134+
why the alternative designs were ultimately not chosen and where they failed to meet the product
135+
requirements. -->
136+
137+
Other potential designs that were considered make trade-offs for security or usability that are
138+
suboptimal. Examples of this are:
139+
140+
- Allowing any user to reveal a transaction for later execution, which creates more considerations
141+
for monitoring/offchain infrastructure and changes the transaction flow.
142+
- Having multisigs queue transaction via the timelock directly and then allowing anyone to execute
143+
the transaction via a module, which changes the signing flow significantly and means transactions
144+
are challenging to simulate properly.
145+
- Configurable `cancellation_thresholds` were considered, but the risk of misconfiguration over
146+
time was expected to be considerable.
147+
- A fixed `cancellation_threshold` of 1 was considered, but the risk of operational disruption by
148+
malicious actors was considered unacceptable.
149+
150+
We could not find any alternative design with the simplicity and security of the one that was
151+
ultimately presented in this document.
152+
153+
## Risks and Uncertainties
154+
155+
<!-- Explain any risks and uncertainties that this design includes. Highlight aspects of the design
156+
that remain unclear and any potential issues we may face down the line. -->
157+
158+
### Timelock Overhead
159+
Any type of mandatory timelock introduces overhead for multisigs that want to execute transactions
160+
in a timely fashion. Multisig leads will have to plan ahead of time in a way that they were not
161+
previously required to do.
162+
163+
### Time Critical Transactions
164+
Some multisigs may face scenarios where they need to be able to execute transactions very quickly
165+
in a worst-case scenario. We should do our best to avoid these situations as much as possible and
166+
use other protocol features (like the Pause) to mitigate them entirely.
167+
168+
Instant execution is not required for finance multisigs. The delay will however be no longer than
169+
the time required for a transaction review by trained finance staff.

0 commit comments

Comments
 (0)