Skip to content

Upgrade Runbook

Purpose

Coordinate the full upgrade lifecycle across release engineering, governance signers, monitoring, and operations.

Procedure

  1. Build implementation and collect metadata: kind, version, policy hash, code hash.
  2. Complete storage-layout and threat review.
  3. Register targets or genesis implementations if required.
  4. Propose upgrade through Propose Upgrade.
  5. Queue upgrade through Queue Upgrade.
  6. Monitor through Monitor Queued Upgrades.
  7. Cancel if any abort condition appears.
  8. Execute after readyAt through Execute Upgrade.
  9. Run post-execution assertions and smoke checks.
  10. Archive evidence and reopen deposit/claim windows only after signoff.

Required Independent Review

At minimum: protocol engineering, release engineering, governance signer, operations, and security review for high-risk targets.

Abort Conditions

Abort for codehash drift, metadata mismatch, missing evidence, unexpected role/registrar event, unresolved vulnerability, or inability to cancel during the timelock.

Evidence To Archive

Build artifact, storage report, operation id, proposal/queue/execute txs, decoded calldata, monitoring transcript, post-state reads, and final approval.