Proxy And Beacon Topology¶

graph TD
    GOV[CenturionUpgradeGovernor]
    DEP[Transparent Proxy: DepositContractCTN]
    CTRL[Transparent Proxy: EconomicController]
    FAC[Transparent Proxy: VaultFactory]
    CG[Transparent Proxy: ClaimGatekeeper]
    BEA[CenturionUpgradeableBeacon]
    V1[Vault Beacon Proxy: validator A]
    V2[Vault Beacon Proxy: validator B]

    GOV -->|proxy admin| DEP
    GOV -->|proxy admin| CTRL
    GOV -->|proxy admin| FAC
    GOV -->|proxy admin| CG
    GOV -->|upgradeAuthority| BEA
    BEA -->|implementation| V1
    BEA -->|implementation| V2
    FAC -->|deploys| V1
    FAC -->|deploys| V2
    CTRL -->|controller-only operations| V1
    CTRL -->|controller-only operations| V2

Transparent Proxy Notes¶

The governor is intended to be the EIP-1967 admin for transparent proxies. The proxy exposes slot-reading helpers (proxyAdmin, proxyImplementation, proxyInitializedVersion) so the governor can verify admin and implementation state without relying on admin-gated fallback behavior.

Beacon Notes¶

Validator vaults are beacon proxies. The factory deploys each vault proxy with initialization data, while the beacon controls the shared vault implementation. The governor is the beacon upgrade authority, and finalFreeze freezes every registered beacon by calling freezeForever.

Operational Consequences¶

• A factory or controller upgrade can affect future deposits and operational checks.
• A claim-gatekeeper upgrade can affect pending-claim validation and executor semantics.
• A vault beacon upgrade can affect all validator vaults at once.
• A deposit implementation upgrade can change admission and custody checks, so deposit windows must be closed around unreviewed queued deposit upgrades.

Source-Grounded Operating Model¶

Purpose¶

This page exists to document which contracts are upgraded through transparent proxies, which through the vault beacon, and which authority verifies policy. Treat it as an operating model, not as proof that any deployed address is already correct. Deployed-state evidence is still Evidence required unless archived separately.

Actors¶

registrar Safe, proposer, queuer, executor, canceller/guardian, freezer, deployment engineer, monitor.

Contracts Involved¶

CenturionUpgradeGovernor, CenturionTransparentProxy, CenturionUpgradeableBeacon, CenturionBeaconProxy, and all registered implementations.

Step-By-Step Flow¶

1. registrar records proxy and beacon targets with expected contract kind.
2. genesis implementations or queued upgrade implementations are approved with metadata and code hash.
3. proposer creates an upgrade operation and queuer starts the delay.
4. executor performs proxy or beacon upgrade after the delay.
5. deposit and other contracts use governor assertions to verify live policy.
6. emergency final freeze can permanently freeze registered beacons only when the freezer role acts.

Failure Modes¶

• proxy admin not governed.
• beacon authority mismatch.
• implementation metadata mismatch.
• queued malicious implementation.
• final freeze used before registered-beacon inventory is complete.

Fail-Closed Behavior¶

The handbook treats missing, stale, mismatched, or contradictory evidence as a stop condition. Onchain paths generally revert, cancel pending claims, or leave queued operations unexecuted rather than accepting a weaker proof. Operators should preserve the revert reason or event trail before retrying.

Operator Implications¶

• Do not substitute Upgrade governance evidence for Deposit permissioning evidence.
• Do not substitute Deposit permissioning evidence for Custody/readiness evidence.
• Do not substitute Custody/readiness evidence for Economic/claim safety evidence.
• Archive the source snapshot, transaction hashes, event logs, and reviewer approvals that correspond to the specific operation.

Source References¶

registerTransparentProxy, registerBeacon, assertTransparentProxyPolicy, assertBeaconPolicy, executeUpgrade, finalFreeze.