Timelocks and Governance Safety Mechanisms

Detailed Instructions

Begin by drafting the upgrade payload, which is the encoded function call data for the timelock to execute. This typically targets the upgradeTo(address) or upgradeToAndCall(address,bytes) function of a Transparent or UUPS proxy. Use a local fork of the mainnet state (e.g., with Foundry's anvil or Hardhat) to simulate the proposal.

• Sub-step 1: Write and compile the new implementation contract. Calculate its address and generate the low-level call data using abi.encodeWithSignature.
• Sub-step 2: Fork the mainnet at the latest block. Impersonate the timelock address and execute the proposal call to verify it succeeds without reverting.
• Sub-step 3: Run your protocol's full test suite against the forked state with the new implementation to check for integration issues and state corruption.

solidityCopy
// Example: Encoding an upgrade call for a UUPS proxy
bytes memory payload = abi.encodeWithSignature(
    "upgradeTo(address)",
    newImplementationAddress
);

Tip: Always test the upgrade on a public testnet after successful forked simulations to catch any environment-specific issues.

Detailed Instructions

Once testing is complete, the proposal must be formally queued. Call the timelock's queue function, providing the target address (the proxy admin or proxy itself), value (usually 0), the encoded payload, the predecessor (typically bytes32(0) for no dependency), and a unique salt (like keccak256("UpgradeV2")). This transaction is usually submitted by the governance contract (e.g., Governor) after a successful vote. The timelock will calculate a unique operationId as keccak256(abi.encode(target, value, payload, predecessor, salt)) and store it with a scheduled execution timestamp.

• Sub-step 1: Verify the proposal's eta (estimated time of availability) is correctly calculated as block.timestamp + delay, where delay is the timelock's minimum delay (e.g., 48 hours).
• Sub-step 2: Confirm the transaction succeeds and emits a Queue event containing the operationId. Store this ID.
• Sub-step 3: Monitor the timelock state using a block explorer or custom script to ensure the proposal remains in the queue and the eta is immutable.

Tip: The salt allows for proposal cancellation before execution by revealing the same salt in a cancel transaction, providing a safety mechanism if the proposal is malicious.

Detailed Instructions

The timelock delay is a critical security period allowing stakeholders to review the queued action. During this time, monitor network social channels and block explorers for any community concerns or technical warnings. As the eta approaches, prepare the execution transaction. You must have the exact same parameters used in the queue call: target, value, payload, predecessor, and salt. Any discrepancy will cause the execution to revert.

• Sub-step 1: Several hours before the eta, re-verify the new implementation contract's code on Etherscan and confirm its bytecode matches your deployed version.
• Sub-step 2: Check that the proxy's admin or owner is still the timelock address, ensuring no administrative changes have compromised the upgrade path.
• Sub-step 3: Form the execution transaction locally and perform a dry-run via eth_call to a recent block to ensure it will succeed when block.timestamp >= eta.

javascriptCopy
// Example: Checking if a proposal is ready for execution
const isReady = await timelockContract.isOperationReady(operationId);
console.log(`Proposal ready: ${isReady}`);

Tip: Use a multisig or the governance contract itself to execute the proposal, never a single private key, to maintain decentralization and fault tolerance.

Detailed Instructions

After the delay has passed, call execute on the timelock with the exact parameters. This will trigger the upgrade call to the proxy contract. Upon successful execution, the timelock emits an Execute event and clears the operation from its queue. Immediate verification is critical. First, confirm the proxy's implementation address has updated by calling the proxy's implementation() function (or the ERC-1967 storage slot).

• Sub-step 1: Execute the transaction. Verify it succeeds and gas usage is within expected bounds, indicating no unexpected reverts in the upgrade logic.
• Sub-step 2: Call key read-only functions on the upgraded contract to verify state integrity and new functionality. For example, check that user balances are preserved and new features return correct data.
• Sub-step 3: Run a subset of critical integration tests against the live mainnet contract (using read-only calls) to ensure core protocol mechanics are operational.

solidityCopy
// Example: Reading the ERC-1967 implementation slot
address impl;
assembly {
    impl := sload(0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc)
}

Tip: Have a prepared rollback plan and associated payload ready in the timelock queue before executing, in case a critical bug is discovered immediately after upgrade.