Governance Upgrade Lifecycle¶

stateDiagram-v2
    [*] --> Draft
    Draft --> Proposed: PROPOSER_ROLE proposeUpgrade
    Proposed --> Queued: QUEUER_ROLE queueUpgrade
    Queued --> Executable: readyAt reached
    Queued --> Cancelled: CANCELLER_ROLE cancelUpgrade
    Proposed --> Cancelled: CANCELLER_ROLE cancelUpgrade
    Executable --> Executed: EXECUTOR_ROLE executeUpgrade
    Executable --> Cancelled: CANCELLER_ROLE cancelUpgrade
    Executed --> [*]
    Cancelled --> [*]
    Draft --> Rejected: review failed
    Rejected --> [*]

States And Transitions¶

State	Entry	Exit	Required authority
`Draft`	Release package exists off-chain.	Proposal or rejection.	None on-chain.
`Proposed`	`proposeUpgrade` stores operation.	Queue or cancel.	`PROPOSER_ROLE`, then `QUEUER_ROLE` or `CANCELLER_ROLE`.
`Queued`	`queueUpgrade` sets `readyAt`.	Ready, cancel, or continued monitoring.	`QUEUER_ROLE`, `CANCELLER_ROLE`.
`Executable`	Time reaches `readyAt`.	Execute or cancel.	`EXECUTOR_ROLE`, `CANCELLER_ROLE`.
`Executed`	Target upgraded.	Terminal.	`EXECUTOR_ROLE`.
`Cancelled`	Operation marked cancelled.	Terminal.	`CANCELLER_ROLE`.

Fail-Closed Behavior¶

The governor reverts on unknown operations, unqueued execution, already finalized operations, early execution, target-kind mismatch, unapproved implementation, metadata mismatch, and final-frozen paths protected by notFinalFrozen.

Operator Implications¶

Queued operations are live risk. Monitoring must be active from UpgradeQueued until UpgradeExecuted or UpgradeCancelled.

Expanded State Model¶

State List¶

Unknown.
Proposed.
Queued.
Ready.
Executed.
Cancelled.
FinalFrozen.

Transition Table¶

From	To	Transition trigger	Actor or data source	Fail-closed behavior
`Unknown`	`Proposed`	Source event/function evidence	Operator or controller data source	Fail closed if evidence missing
`Proposed`	`Queued`	Source event/function evidence	Operator or controller data source	Fail closed if evidence missing
`Queued`	`Ready`	Source event/function evidence	Operator or controller data source	Fail closed if evidence missing
`Ready`	`Executed`	Source event/function evidence	Operator or controller data source	Fail closed if evidence missing
`Proposed/Queued`	`Cancelled`	Source event/function evidence	Operator or controller data source	Fail closed if evidence missing
`Any nonfinal state`	`FinalFrozen`	Source event/function evidence	Operator or controller data source	Fail closed if evidence missing

Contract And Function References¶

Use the generated Solidity inventory to reconcile each transition with the current contract functions and events before relying on the state machine for production. For governance upgrade transitions, source-grounded references must include the relevant controller, deposit, governor, gatekeeper, factory, or vault function named by the page.

Operational Impact¶

Every transition changes what an operator is allowed to do next. A transition into a blocked, cancelled, slashed, unsafe, or final state must stop routine automation until an independent reviewer confirms the next runbook.

Incident Implications¶

Unexpected transitions are incident evidence. Archive block number, transaction hash, decoded events, current state reads, and offchain source data. If the transition cannot be traced to a known runbook or approved automation, escalate before retrying dependent actions.