Upgradeability and Recovery

fact Implements the Upgradeability and recovery addendum of PROTOCOL_SPEC.md. Sources: contracts/src/core/{NoteCore,SeriesRegistry}.sol, contracts/src/token/upgradeable/{GovernedUpgradeable,UUPSModule}.sol, contracts/script/{DeployCore,DeployToken}.s.sol. Storage tooling in contracts/storage-layout/.

The Hybrid Model

User escrow is never subject to a code change. Everything that holds note escrow is immutable and can only be replaced; the periphery that holds protocol-owned or pooled assets is upgradeable behind a separate 7-day governance.

UUPS modules expose version() ("1.0.0" at launch), keep state in ERC-7201 namespaces and call _disableInitializers() in their constructors. _authorizeUpgrade rejects unauthorised calls for anyone except the upgrade governance, including the governance owner, so a compromised 48-hour path cannot shorten the upgrade delay. Governance-authority configuration is callable only by the current upgrade governance, so rotating it is itself a 7-day operation.

Module Swaps with Grace

fact NoteCore and OracleAdapter keep {previous, current, effectiveAt} per slot.

effectiveAt = block.timestamp + MODULE_GRACE (24 h). A second change while one is pending reverts ModuleChangePending(key, effectiveAt). An observation whose close is before effectiveAt, even if processed later after a deferral, resolves with previous, so a swap can never retroactively change a price that was already due. Events: ModuleUpdated(bytes32 key, address old, address new, uint40 effectiveAt), ParamUpdated(key, old, new, effectiveAt), BackupFeedSet(primary, backup, effectiveAt).

Governance should space swaps by more than the 72-hour deferralWindow, because one pending change per slot means a very old deferred observation could otherwise resolve with a newer module.

Versioned Series and the Registry

fact SeriesRegistry is an immutable, Ownable directory owned by the governance. Versions are dense from 1; 0 means unknown.

NoteCore.createSeries reverts CoreDeprecated() unless registry.isActive(address(this)). No other core function consults the registry, so deprecation can never trap a series: every series on a deprecated core keeps observing, settling and paying out to term. Upgrading the core means deploying a new NoteCore that points at the same registry, register, then deprecate(oldVersion), all through the governance. The app’s Governance overview lists each module’s version and address, and series that have been unwound carry an Unwound status throughout the app.

Deprecating the only active version leaves activeCore() == 0; that is the intended “freeze new issuance” state, not an error. The registry does not verify that a registered address is a NoteCore; the deploy script and the proposal review process must.

Which Contracts Can and Cannot Be Upgraded in Place

Only Treasury, BondDepository, RevenueRouter and Desk inherit UUPSModule; they are the only contracts whose code can change behind an existing address. NoteCore, NoteLegs, SeriesRegistry, OracleAdapter, MarketCalendar, NOTE, sNOTE, veNOTE, GaugeController, EmissionSchedule, Minter, every gauge and both automation contracts (NoteAutomation, RollPolicy) are plain deployments with no proxy. A fix to any of them is a redeploy, never an upgrade, and any change plan that lists an “upgrade” for one of these contracts is wrong.

Core Replacement Path (a Fix to NoteCore)

A NoteCore change is a new core version. Live series stay on the old core to term; only new issuance moves. The address of the core is an immutable in every contract that talks to it, so those contracts are redeployed as well:

fact The steps below follow from the immutables in source, not from a script; the deploy scripts cover a fresh deployment only.

1. Deploy the new NoteCore against the same SeriesRegistry, OracleAdapter, MarketCalendar and feeSink.
2. Deploy a new NoteLegs for the new core: NoteLegs.core is immutable and its onlyCore mint and burn accept the one address given at construction, so legs cannot be re-pointed. Leg ids of the old core stay on the old legs contract and remain redeemable there.
3. Redeploy the periphery implementations whose constructors bake in CORE, CORE_VIEWS and LEGS (Treasury, Desk, BondDepository) and schedule them through the 7-day upgrade governance as ordinary UUPS upgrades; state in the ERC-7201 namespaces is preserved. Old-core leg positions held by these modules are settled on the old core before the switch, or the new implementation keeps a read path to the old core for them.
4. Redeploy NoteAutomation and RollPolicy (their core is immutable), fund the new automation contract and retire the old one once no old-core series still needs strikes or observations.
5. Redeploy SeriesGauge instances for the new core (CORE and LEGS are immutable), addGauge them on the GaugeController and killGauge the old ones once their series have settled.
6. SeriesRegistry.register(newCore) then deprecate(oldVersion) through the 48-hour governance. From that point createSeries on the old core reverts CoreDeprecated().
7. Update the addresses page and the core address configured in the app; the app’s governance overview reads activeVersion and activeCore from the registry and shows the switch.

Module swaps (OracleAdapter, MarketCalendar, feeSink) do not need a new core; they go through the grace-period path described under Module swaps with grace.

Recovery Unwind, Step by Step

fact Per-series emergency exit for a Subscription or Live series when something outside the series’ own rules has gone wrong (a bug, a frozen Stock Token, a permanently dead feed). Holders receive exactly their recorded entitlement; governance sets no amounts and no address other than the holder can receive value.

1. Pause. The guardian or the governance calls NoteCore.pause(). Deposits, finalizeStrike and observe stop; claim, redeem, refund, settle and sweepFees continue.
2. Propose. The governance calls proposeUnwind(seriesId). Requires whenPaused and status Subscription or Live; emits UnwindProposed(seriesId, at). Terminal series (Autocalled, Matured, Cancelled, Unwound) cannot be proposed.
3. Veto window. The guardian or the governance may cancelUnwind(seriesId) at any time before execution; emits UnwindCancelled. A proposal that goes stale because the series autocalls in the meantime is cancelled this way. While any unwind proposal is open, sweepExcess reverts UnwindPending(count).
4. Unwind. After the 48-hour delay the governance executes unwind(seriesId) (still whenPaused). The core enforces the delay on its own: unwind reverts TooEarly(proposedAt + UNWIND_GRACE) until UNWIND_GRACE = 48 hours has elapsed since proposeUnwind, whatever the governance schedule. Status becomes Unwound; the contract snapshots quoteEscrow − accruedFees and stockEscrow and emits SeriesUnwound(seriesId, quoteLiabilities, stockLiabilities). From here observe, finalizeStrike and deposits revert InvalidStatus.
5. Withdraw. Each holder calls withdrawUnwound(seriesId); emits UnwoundWithdrawn. This function is never pausable. A second call reverts NothingToWithdraw.
6. Fees. sweepFees(seriesId) still moves accrued fees to the fee sink; fees are excluded from the unwind snapshot. An Unwound series is terminal, so its keeper reserve is zero and the whole of accruedFees is sweepable.
7. Dust. Once every holder has withdrawn, the governance may call writeOffDust(seriesId, to) on a terminal series (Cancelled, Autocalled, Matured or Unwound) whose remaining quote escrow is at most dustLimitQuote() (one hundredth of a quote unit, 0.01 USDG) and whose remaining stock escrow is at most DUST_LIMIT_STOCK (1e-6 of a Stock Token). Larger residues revert NotDust(quoteAmount, stockAmount); every bucket of the series is zeroed and DustWrittenOff(seriesId, to, quoteAmount, stockAmount) is emitted. Integrators can read the resulting status with crank(seriesId), which runs any due strike or observation and returns the Status afterwards without reverting on an existing series.

What a Holder Receives

Partial leg transfers before the unwind move the entitlement with the leg. The invariant suite asserts that for every Unwound series Σ paid since unwind + (quoteEscrow − accruedFees) == unwoundQuote and Σ stock paid + stockEscrow == unwoundStock, that the snapshot never changes, and that only fees plus floor-rounding dust remain after every holder has withdrawn. See Invariants.

Excess Sweep

fact sweepExcess(token, to) (governance, nonReentrant) transfers IERC20(token).balanceOf(core) − recordedLiabilities(token), where recordedLiabilities(quote) = totalQuoteEscrow and recordedLiabilities(underlying) = totalStockEscrow[underlying]; for any unrelated token the full balance is excess. Emits ExcessSwept.

• Reverts NoExcess(token) when nothing sits above liabilities, so the call can never take from escrow.
• Reverts UnwindPending(count) while any unwind proposal is open, because paused-state accounting is unfinished.
• Rounding dust is part of the recorded escrow and is therefore never sweepable.

Storage-layout Policy for UUPS Modules

fact Each upgradeable contract keeps mutable state in an ERC-7201 namespace, keccak256(abi.encode(uint256(keccak256(id)) − 1)) & ~0xff.

Desk inherits OpenZeppelin’s non-upgradeable ERC20 and ERC4626, so its ERC-20 balances, allowances, supply, name and symbol occupy plain slots 0 to 4 (recorded as top_level in the snapshot). External dependencies (QUOTE, NOTE_TOKEN, CORE, CORE_VIEWS, LEGS, TREASURY, SNOTE, ERC-4626 asset) are immutables baked into each implementation and must be re-supplied identically to a V2 constructor.

Rules for a V2:

1. Never reorder, remove, retype or re-pack existing namespace members. Append only, or open a fresh namespace such as notesystems.storage.<Contract>V2Extension.
2. New initialisation uses reinitializer(2) (then 3, and so on), never initializer. Re-running initialize reverts InvalidInitialization.
3. Re-supply every immutable identically; bump version(); keep _disableInitializers() in the constructor.
4. Do not add state variables to inherited non-upgradeable OpenZeppelin contracts (Desk’s ERC-20 slots).
5. Run python3 contracts/storage-layout/check_layout.py check --contract X --impl X=XV2 --probe X=XStorageProbeV2 and the full token suite; regenerate the snapshot only after the upgrade has executed.

The checker runs forge inspect for the top-level layout and for each namespace struct via probe contracts, and fails (exit 1) if any existing member changes its (slot, offset, type, label), if members are not append-only, or if a namespace base slot differs from the snapshot or the *_STORAGE_LOCATION constant. Upgrade.t.sol additionally asserts the constants against the ERC-7201 formula on-chain. The procedure is summarised for reviewers under Upgrade safety.

Known Limitations

• SeriesRegistry is single-step Ownable without pause; a wrong transferOwnership is unrecoverable, so it is only ever executed through the governance.
• governance executors are open by design; the delay and the guardian veto are the only protections against a compromised proposer.
• renounceOwnership on modules is not disabled at the contract level; a scheduled renounce would make unpause impossible and is treated as forbidden by process; reviewers should reject any queued operation that calls it.
• The guardian can pause indefinitely (a liveness risk for strikes and observations, never for exits); only the governance can unpause.