A timelock forces a delay between approving an administrative action and running it, so users and monitors can see a change coming and react. OpenZeppelin's TimelockController is a common implementation. It only protects anyone if the delay is meaningful and the roles around it are locked down.
What the controller does
Per the documentation, TimelockController introduces a delay between a proposal and its execution. It can be used with or without a governance contract.
An operation is one call or a batch of calls. A proposer schedules it. After the delay an executor runs it. Batched calls run atomically. Operations move through Unset, Pending, Ready and Done, and each is identified by a hash of its contents. A pending operation can be cancelled, and if it is scheduled again the timer restarts.
Roles
- Proposer schedules and cancels operations. The documentation calls this a critical role and suggests a multisig, an account, or a DAO.
- Executor runs operations once the timer expires. Assigning the zero address lets anyone execute.
- Canceller is needed to cancel. The constructor grants it to proposers.
- Admin manages proposers and executors. For self governance only the timelock should hold it, and any admin supplied by the deployer should renounce it after setup.
The minimum delay
The minimum delay is set at deployment. Each scheduled operation must use a delay at least that long, or scheduling fails. Changing the minimum means scheduling and executing an operation that targets the timelock itself.
How a timelock fits an upgrade process
The ethereum.org upgrade guide recommends decentralizing upgrade control, for example with a multisig or a DAO vote, and adding timelocks so users can exit if they disagree with a change. It also states the trade-off: timelocks slow emergency patches. Plan for that by keeping a separate, narrower emergency path such as a pause, discussed in circuit breakers for contracts.
Ways the delay gets defeated
- The deployer keeps the admin role after launch.
- The delay is so short that nobody can react in time.
- Nobody watches scheduled operations, so the warning goes unread.
- A second privileged path bypasses the timelock entirely.
- The proposer is one hot key.
The fix for the third is simple and often skipped: alert on every scheduled operation and name an owner for each alert.
Questions for your own design
- Who can schedule, and is that more than one person?
- How long is the delay compared with how long users need to exit?
- Is every admin function behind the timelock, or only some?
- What is the emergency path, and who holds it?
- Who is paged when something is scheduled?
Safeguard's policy and gate features apply the same idea to code changes: a review step between a change and its release. Free scan: gold.safeguard.sh/scan.
Quick check
Does a timelock stop a malicious upgrade?
It does not stop it. It makes the change visible before it takes effect, which only helps if someone is watching and users can leave.
What does assigning the zero address as executor mean?
According to the documentation, anyone can execute operations once the delay has passed.
Sources
Last reviewed: 19 October 2026.
