Skip to content

Monitor Queued Upgrades

Purpose

Detect and respond to unsafe governance activity during the timelock window.

Inputs Needed

Operation id, decoded payload, release package, target registration reads, implementation metadata, queuedAt, readyAt, monitoring owner, and guardian contacts.

Procedure

  1. Subscribe to UpgradeProposed, UpgradeQueued, UpgradeExecuted, UpgradeCancelled, role events, registrar events, and FinalFreeze.
  2. On proposal, decode full payload and classify target.
  3. On queue, schedule human reviews and notify guardian.
  4. Re-read implementation code hash at least daily and immediately before execution.
  5. Compare role/registrar events during the delay against approved governance tickets.
  6. If any abort condition appears, prepare and execute cancelUpgrade.

Abort Conditions

Unknown target, unknown implementation, metadata drift, unexpected calldata, role-admin transfer, guardian role loss, registrar event without release ticket, vulnerability disclosure, or deposit/claim window conflict.

Evidence To Archive

Monitoring logs, decoded events, review timestamps, codehash reads, signer notifications, and cancel/execute recommendation.

Operational Procedure

Purpose

Use this runbook to watch proposal, queue, execution, cancellation, role, and final-freeze events continuously.

When To Use

Use it for production, staging, or rehearsal actions that affect live authority, validator custody, economic accounting, claims, or incident response. Do not use it as a substitute for source review; deployed-state evidence remains Evidence required unless captured for the exact chain and address set.

Required Authority

Required authority: read-only monitor, escalates to CANCELLER_ROLE or FREEZER_ROLE. Read-only preparation can be performed by an operator or auditor, but transaction submission must come from the documented production holder in the permission matrix.

Preconditions

  • The current source manifest and generated inventory are up to date.
  • The acting Safe or owner has been verified against the current permission matrix.
  • No unresolved incident is active for the same contract, validator, role, or operation.
  • The reviewer can identify which layer is affected: Upgrade governance, Deposit permissioning, Custody/readiness, or Economic/claim safety.

Inputs Required

  • e.
  • v.
  • e.
  • n.
  • t.
  • .
  • i.
  • n.
  • d.
  • e.
  • x.
  • e.
  • r.
  • ,.
  • .
  • r.
  • e.
  • g.
  • i.
  • s.
  • t.
  • e.
  • r.
  • e.
  • d.
  • .
  • t.
  • a.
  • r.
  • g.
  • e.
  • t.
  • .
  • l.
  • i.
  • s.
  • t.
  • ,.
  • .
  • a.
  • p.
  • p.
  • r.
  • o.
  • v.
  • e.
  • d.
  • .
  • r.
  • e.
  • l.
  • e.
  • a.
  • s.
  • e.
  • .
  • c.
  • a.
  • l.
  • e.
  • n.
  • d.
  • a.
  • r.
  • ,.
  • .
  • i.
  • n.
  • c.
  • i.
  • d.
  • e.
  • n.
  • t.
  • .
  • c.
  • h.
  • a.
  • n.
  • n.
  • e.
  • l.

Step-By-Step Procedure

  1. poll governor events.
  2. compare operation hashes to tickets.
  3. flag unknown targets or metadata.
  4. notify guardian on mismatch.
  5. archive daily report.

Independent Review Requirement

A second reviewer must check the decoded calldata, expected state transition, affected role or validator, and expected events before submission. For emergency use, capture the reviewer identity and incident ticket before or immediately after the transaction.

Abort Conditions

  • Source manifest hash drift or unexpected implementation metadata.
  • Caller or Safe does not match the permission matrix.
  • Revert reason points at a different layer than the runbook is trying to change.
  • Any required input is missing or only inferred.
  • A guardian, canceller, or incident commander has frozen the action window.

On-Chain Pre-Checks

Read current role/owner/admin state, operation status, target code hash where applicable, validator/vault mapping where applicable, and the latest readiness or claim state that the action depends on. Record block number and RPC endpoint.

On-Chain Post-Checks

Confirm the intended state changed, no adjacent authority changed unexpectedly, and no pending operation or stale intent was left active. Re-read the affected contract rather than relying only on transaction success.

Events Or Logs To Monitor

  • UpgradeProposed.
  • UpgradeQueued.
  • UpgradeExecuted.
  • UpgradeCancelled.
  • FinalFreeze.

Evidence To Archive

Archive calldata, transaction hash, decoded event logs, pre/post reads, reviewer approval, incident or change ticket, and any source-manifest or release-artifact references used to justify the action.

Escalation Path

Escalate to governance signers for authority or upgrade anomalies, to controller/risk owners for economic or claim anomalies, to admission operators for intent mistakes, and to security incident response for unexpected code, role, or event drift.