Propose Upgrade¶

Purpose¶

Create a governor operation for a reviewed implementation upgrade. Proposal records the payload but does not start the timelock.

Required Authority¶

PROPOSER_ROLE on CenturionUpgradeGovernor.

Preconditions¶

Target is already registered under the correct contract kind.
Implementation is deployed and its contractKind, implementationVersion, and economicPolicyHash match the release plan.
Storage-layout review is complete.
Initializer or reinitializer calldata is decoded and approved.
Guardian cancellation channel is available before queueing.

Procedure¶

Gather target type, target, implementation, contract kind, version, policy hash, salt, calldata, and expected initialized version.
Read live target registration from the governor.
Read implementation metadata directly from the implementation address.
Recompute expected code hash from the deployed bytecode.
Reproduce hashOperation independently.
Call proposeUpgrade(...) from the proposer Safe.
Confirm UpgradeProposed event fields match the release package.
Archive the operation id and decoded payload.

Independent Review¶

A reviewer who is not the proposer must verify metadata, calldata, storage layout, operation id, and target registration.

Abort Conditions¶

Abort if target kind is unexpected, implementation metadata differs, calldata is not decoded, storage review is missing, or a governance/role incident is active.

Post-Checks¶

operationKnown(operationId) is true.
getOperation(operationId) matches the intended payload.
Monitoring has the operation id before queueing.

Evidence To Archive¶

Release ticket, implementation source commit, bytecode hash, metadata reads, storage report, calldata decoder output, operation id, tx hash, and UpgradeProposed.

Operational Procedure¶

Purpose¶

Use this runbook to stage a reviewed implementation or beacon/proxy change before the timelock can start.

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: PROPOSER_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¶

a.
r.
t.
i.
f.
a.
c.
t.
.
p.
a.
t.
h.
,.
.
i.
m.
p.
l.
e.
m.
e.
n.
t.
a.
t.
i.
o.
n.
.
a.
d.
d.
r.
e.
s.
s.
,.
.
m.
e.
t.
a.
d.
a.
t.
a.
.
c.
o.
n.
s.
t.
a.
n.
t.
s.
,.
.
s.
t.
o.
r.
a.
g.
e.
-.
l.
a.
y.
o.
u.
t.
.
r.
e.
v.
i.
e.
w.
,.
.
p.
o.
l.
i.
c.
y.
.
h.
a.
s.
h.
,.
.
t.
a.
r.
g.
e.
t.
.
p.
r.
o.
x.
y.
.
o.
r.
.
b.
e.
a.
c.
o.
n.

Step-By-Step Procedure¶

decode target and calldata.
verify implementation code hash and metadata labels.
recompute operation hash.
submit proposeUpgrade.
publish operation hash to monitoring channel.

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.

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.