Skip to content
Financial Context Wiki

How does a governance timelock operate?

A governance timelock turns an approved action into a publicly observable operation that must wait before execution. Learn how IDs, roles, delays, expiry, cancellation, and exit windows work.

Updated

For educational purposes only; not investment advice. Investing may result in loss.

Direct answer

A governance timelock is an execution controller, not another vote. After governance authorizes a payload, an approved proposer schedules the exact operation. The contract records when it may become executable and rejects execution before that time. This delay makes a pending upgrade, parameter change, treasury transfer, or role change observable before it takes effect.

The headline delay is only one part of the control. Review the operation ID, earliest execution time, any expiry rule, predecessor, proposer, executor, canceller, administrator, and every other path that can control the target. A 48-hour timelock does not provide a 48-hour exit window if the operation is queued late, monitoring is delayed, withdrawals take longer, or another privileged key can perform the same change immediately.

A timelock does not decide whether an action is legitimate or safe. It provides time for people and automated monitors to decode the calls, simulate their effects, cancel or pause when authorized, communicate the change, and exit positions when a real exit path exists.

How it works

  1. Authority is attached to the timelock. The timelock must own or hold the relevant role on the target contract. If a governor holds no authority over the target, passing a proposal changes nothing; if a separate administrator retains parallel authority, that path may bypass the delay.
  2. A proposer schedules an exact operation. In OpenZeppelin’s TimelockController, a single-operation ID hashes target, value, data, predecessor, and salt; batch operations hash the corresponding arrays plus the same dependency and salt. Changing any field creates a different operation ID. The salt distinguishes otherwise identical actions.
  3. The minimum delay starts at scheduling. A successful vote does not necessarily start the timelock. Scheduling records a ready timestamp using a delay that must be at least the contract’s current minimum. OpenZeppelin operations move from Unset to Waiting, then Ready, and finally Done after successful execution.
  4. Dependencies and permissions are checked at execution. A predecessor must already be Done. The caller must satisfy the executor rule, and the target call must succeed. An executor cannot alter the scheduled payload. Granting the executor role to address(0) makes execution permissionless after maturity, which improves liveness but lets any account choose the exact eligible execution moment.
  5. Cancellation returns a pending operation to its initial state. In current OpenZeppelin contracts, an account with CANCELLER_ROLE can cancel an operation while it is pending, including when it is ready but not yet executed. Rescheduling starts a new timer. Role wiring matters: older versions and other timelocks may give cancellation to the proposer or administrator instead.
  6. Expiry is implementation-specific. OpenZeppelin’s TimelockController has no built-in grace-period expiry; a ready operation remains ready until it is executed or cancelled. Compound v2’s Timelock instead requires execution no later than eta + GRACE_PERIOD, and its source sets GRACE_PERIOD to 14 days. Governor Bravo labels a queued proposal expired after that boundary.
  7. Administration must also be delayed. OpenZeppelin allows updateDelay only through a call from the timelock to itself. A self-administered deployment similarly forces role changes through scheduled operations. A temporary external admin used during setup should renounce that role after configuration; otherwise it remains a separate trust path.

For each queued action, reconstruct a control record from contract state and events: chain ID, timelock and target addresses, operation ID, decoded payload, proposer, schedule transaction and timestamp, minimum delay, ready time, expiry if any, predecessor, executor policy, cancellation authority, and final transaction status. Do not infer these fields from a governance website alone.

Worked example

Assume a proposal lowers a lending market’s liquidation threshold from 75% to 60%. Voting ends at Monday 12:00 UTC, but a proposer does not schedule the operation until Tuesday 18:00 UTC. The scheduled delay is 48 hours, so the earliest execution is Thursday 18:00 UTC, not Wednesday 12:00 UTC.

The operation contains the risk-manager contract as target, zero native-token value, encoded parameter-change data, no predecessor, and a disclosed salt. Recomputing the hash from those fields must match the emitted operation ID. A different market address, threshold, or salt is a different operation even if the interface description looks the same.

Users therefore have 48 hours from scheduling, but their usable exit time is shorter. If the alert arrives 6 hours after scheduling and an unstaking or withdrawal queue takes 24 hours, only 18 hours of buffer remain:

usable response time = ready time - detection time - exit settlement time

If an emergency multisig can pause withdrawals immediately, it may reduce loss during an incident but also make exit impossible before the queued change. Review that authority independently. After execution, verify the target’s actual storage and emitted events; a timelock execution transaction can succeed while an expected economic result is still misunderstood.

Risks and controls

  • Bypass authority. Enumerate owners, proxy administrators, access-control roles, upgrade beacons, emergency councils, modules, and cross-chain executors. The shortest privileged path determines the effective delay.
  • Payload substitution or poor decoding. Recompute the operation ID from raw fields, resolve proxy implementations, decode every selector and argument, and simulate the complete batch. Human-readable proposal text is not the executable payload.
  • Insufficient notice. Alert from on-chain schedule and cancellation events, not only forum posts. Measure notice from confirmed scheduling to the earliest executable block or timestamp, then subtract detection and exit-settlement time.
  • Cancellation failure. Confirm which accounts can cancel, whether they are live, what threshold they require, and whether cancellation remains possible after the operation becomes ready. Rehearse the transaction before an incident.
  • Executor failure or timing games. Restricted executors can become unavailable or intentionally delay execution. Open execution improves liveness but permits third parties to execute immediately at maturity, so dependent prices, oracle updates, and user positions must be safe at that boundary.
  • Stale queued actions. Where no expiry exists, old ready operations can remain executable indefinitely. Track and explicitly cancel abandoned operations. Where a grace period exists, monitor its exact end and require a fresh governance cycle after expiry.
  • Dependency and batch risk. Verify the predecessor ID and atomic batch ordering. One reverting call can block an atomic batch; an incorrect dependency can deadlock an otherwise valid operation.
  • Unsafe administration. Make delay reductions, role grants, and timelock replacement subject to the timelock itself. Remove deployment administrators, preserve at least one viable proposer and executor, and avoid a configuration that permanently locks control.
  • No credible exit. Compare the delay with withdrawal queues, bridge finality, market liquidity, pause powers, and congestion. A published delay is not user protection when assets cannot leave before execution.

The operational standard is an evidence-backed timeline, not a displayed countdown. Archive the schedule event, decoded calls, simulation result, role holders, cancellation plan, earliest and latest execution times, communication channels, and post-execution state diff.

Common misconceptions

  • “The delay starts when voting ends.” It normally starts when the successful action is scheduled, unless the deployed implementation explicitly couples those moments.
  • “Anyone can execute, so anyone can change the proposal.” An open executor can trigger only an already scheduled payload whose operation ID and conditions match.
  • “Ready means the action must execute immediately.” Ready means eligible. Execution still needs a transaction, permissions, satisfied dependencies, and a successful target call.
  • “Every timelock has an execution window.” Expiry varies by implementation. Compound v2 uses a grace period; OpenZeppelin’s TimelockController does not expire ready operations by default.
  • “A long timelock removes governance risk.” Delay helps only when monitoring, comprehension, cancellation or pause, communication, and exit are all feasible before execution. Parallel administrators and blocked withdrawals can nullify the benefit.

Sources

Navigation

Search the wiki...