Upgrade Safety

fact Two kinds of code change exist. A UUPS upgrade replaces the implementation behind one of the four periphery proxies (Treasury, BondDepository, RevenueRouter, Desk). A core replacement deploys a new immutable NoteCore and moves new issuance to it through SeriesRegistry. Existing note escrow remains in the immutable core, but upgrades can change periphery behaviour and introduce loss or availability risk. The design is described under Upgradeability and recovery; this page is the safety view.

Controls

The upgrade governor enforces minimum quorum, voting-period and governance-delay settings at construction. A configuration below those floors is rejected.

Storage-layout Gate

Every UUPS module stores state in a named ERC-7201 namespace; the slots are listed under Upgradeability and recovery. contracts/storage-layout/check_layout.py is the gate:

python3 contracts/storage-layout/check_layout.py snapshot   # regenerate contracts/storage-layout/<Contract>.json
python3 contracts/storage-layout/check_layout.py check      # CI: fail if any existing slot changed
python3 contracts/storage-layout/check_layout.py check --contract Desk --probe Desk=DeskStorageProbeV2Append --impl Desk=DeskV2   # must PASS
python3 contracts/storage-layout/check_layout.py check --contract Desk --probe Desk=DeskStorageProbeV2Reorder                    # must FAIL

A layout is compatible only if every existing member keeps its (slot, offset, type, label), new members are appended, and each namespace base slot equals both the snapshot and the *_STORAGE_LOCATION constant in source. Exit code 1 on any violation. test/upgrade/token/Upgrade.t.sol::test_storageLocations_matchErc7201Formula asserts the constants against the ERC-7201 formula on-chain, and the same suite performs a full V1 to V2 upgrade through a real governance, checking every namespace member survives.

Test Gate

For a core replacement the gate is the full core suite on the new NoteCore including Governance.t.sol (schedule, warp 48 h, execute) and the NoteCore invariant run including invariant_unwoundClaimsMatchSnapshot.

Review Checklist

Before voting for or executing an upgrade, the public evidence should support every line from on-chain data and the published source.

1. The proposal description begins with # <title> and has a ## Risk section naming the contracts touched and the version bump.
2. The queued operation on upgrade governance targets the expected proxy address (see Addresses) and calls upgradeToAndCall(v2, calldata); the calldata is either empty or a reinitializer(2) call whose arguments are stated in the proposal.
3. The V2 implementation is verified on the explorer at the commit named in the proposal, its constructor arguments equal V1’s immutables, and version() on the new implementation is higher than the proxy’s current version().
4. check_layout.py check passes against the committed snapshot with the V2 implementation and probe; the CI run is linked.
5. No state variable was added to inherited non-upgradeable OpenZeppelin contracts (Desk ERC-20 slots 0 to 4).
6. The operation does not call governance-authority configuration, renounceOwnership or transferOwnership unless that is the stated purpose of the proposal.
7. Pause status: if the module is paused for the upgrade, the proposal states who unpauses and when. A pause does not itself make a live note redeemable; each exit still requires its documented state and available transfers.
8. Timing: the operation’s execute time is at least 7 days after schedule, and the guardian’s veto window has been publicly announced.

Signals to Watch

• Upgraded(address implementation) on any proxy without a matching executed proposal.
• CallScheduled on either governance whose target or selector is not in the proposal.
• RoleGranted or RoleRevoked on either governance; roles should only change through a proposal.
• CoreRegistered or CoreDeprecated on SeriesRegistry.
• ModuleUpdated with an effectiveAt sooner than 24 hours from the event, which cannot happen and would indicate a different contract than the audited one.

Indexers can subscribe to these through the Events reference.