Governor Timelock

Overview

  • Replaces a Governor EOA with a contract-based timelock so all governor-privileged transactions execute after a delay.

  • Separates responsibilities via roles and enforces a schedule → wait → execute lifecycle.

  • Prevents immediate parameter and role changes. Certain meta‑changes are themselves timelocked.

Key Roles

  • PROPOSER_ROLE: Schedules proposals via scheduleProposals(...) or proposeRoleUpdates(...).

  • EXECUTOR_ROLE: Executes queued proposals during their execution window via executeProposals(...).

  • CANCELLER_ROLE: Unschedules proposals via unscheduleProposals(...) (cannot unschedule role updates).

  • ROLE_ADMIN: Proposes role changes using proposeRoleUpdates(...) and manages token withdrawer pending address.

  • tokenWithdrawer (separate address): Can rescue ERC20 tokens accidentally sent to the timelock.

Timelock Parameters

  • Defaults are set at deployment to at least MIN_DELAY = 1 day and MIN_EXECUTION_WINDOW = 1 day.

  • Default parameters can be changed with setDefaultTimelockParameters(delay, executionWindow). This function is onlySelf and must be executed via a timelocked proposal to the timelock itself.

  • Per‑function overrides: setFunctionTimelockParameters(target, selector, delay, executionWindow) supports either both values set to zero (use defaults) or both meeting minimums. This function is onlySelf and must be timelocked.

  • Changing a function’s timelock uses that function’s prior timelock parameters to gate the change (cannot reduce a delay instantly).

Proposal Lifecycle

  • Schedule: scheduleProposals(address[] targets, bytes[] data) records proposals with delayedUntil and validUntil and computes a proposalHash = keccak256(target, data).

  • Role updates: Must be scheduled via proposeRoleUpdates(bytes32[] roles, address[] accounts, bool[] shouldGrant) (not via scheduleProposals). These cannot be unscheduled.

  • Unschedule: unscheduleProposals(uint256[] proposalIds) allowed only when isUnschedulable is true (i.e., not role updates).

  • Execute: executeProposals(uint256[] ids, address[] targets, bytes[] data) checks existence, timing window, and data hash, deletes the proposal, then calls the target with the exact data.

  • Window semantics: Executable if block.timestamp is within [delayedUntil, validUntil] via isExecutable(id).

Security Notes

  • onlySelf gates sensitive meta‑operations (updateRole, timelock config), ensuring they can only be changed through the timelock.

  • Binds execution to exact calldata via the stored proposalHash.

  • Disallows scheduling to EOAs (target.code.length > 0).

  • Role updates, once queued, cannot be unscheduled.

Token Rescue

  • setPendingTokenWithdrawer(new) (ROLE_ADMIN) → acceptTokenWithdrawer() (new address) establishes the token withdrawer.

  • withdrawERC20Token(token, amount) callable only by tokenWithdrawer to rescue funds sent to the timelock.

Typical Workflows

  • Schedule and execute a MapleGlobals change:

    1. scheduleProposals([globals], [abi.encodeWithSelector(globals.setPlatformServiceFeeRate.selector, newRate)]) (PROPOSER).

    2. Wait until isExecutable(id) returns true within the execution window.

    3. executeProposals([id], [globals], [encodedData]) (EXECUTOR).

  • Grant EXECUTOR_ROLE to a new account:

    1. proposeRoleUpdates([EXECUTOR_ROLE], [newExecutor], [true]) (ROLE_ADMIN).

    2. After delay, executeProposals([id], [timelock], [abi.encodeWithSelector(timelock.updateRole.selector, EXECUTOR_ROLE, newExecutor, true)]) (EXECUTOR).

  • Set a per‑function override (e.g., extend delay for globals.setPriceOracle):

    1. Schedule setFunctionTimelockParameters(globals, setPriceOracle.selector, 2 days, 1 day) to the timelock (PROPOSER).

    2. Execute after the prior timelock for that function has elapsed (EXECUTOR).

Events and Monitoring

  • ProposalScheduled, ProposalExecuted, ProposalUnscheduled for lifecycle transitions.

  • FunctionTimelockSet, DefaultTimelockSet for configuration changes.

  • RoleUpdated for access changes. PendingTokenWithdrawerSet and TokenWithdrawerAccepted for rescue admin.

Deployment and Setup

  • Constructor arguments: tokenWithdrawer, proposer, executor, canceller, roleAdmin.

  • Defaults initialize to minimums and can be increased later via timelocked calls.

  • Recommended mapping:

    • Governance multisig: PROPOSER_ROLE, EXECUTOR_ROLE, ROLE_ADMIN.

    • Security/ops multisig: CANCELLER_ROLE (to unschedule non‑role proposals when needed).

Context

  • This contract replaces a Governor EOA so that all governor‑privileged transactions are enforced to pass through a timelock.

  • Pool Delegate–level timelocks (e.g., contract upgrades) remain documented separately. See technical-resources/admin-functions/timelocks.md.

PreviousGlobalsNextMapleTreasury

Last updated