Lesson 8 — Upgradeability: transparent and UUPS proxies, storage layout

**The proxy pattern.** An upgradeable system uses two contracts: a *proxy* (which holds the actual storage and is the address users interact with) and an *implementation* (which holds the code). The proxy uses `delegatecall` to forward every function call into the implementation — `delegatecall` runs the implementation's code in the proxy's storage and `msg.sender` context. Upgrading means deploying a new implementation contract and pointing the proxy at it; the storage (balances, mappings, ownership) is preserved across upgrades.

**The fundamental constraint: storage layout.** Because proxy storage is shared across implementation versions, the layout of storage variables must be identical between versions or storage corruption occurs. If V1 has `address owner` at slot 0 and `uint256 totalSupply` at slot 1, V2 cannot insert a new variable before either of them — doing so would have V2's `totalSupply` read from the slot that holds `owner`. The fix is appending new variables only at the end, and adding 'storage gaps' (`uint256[50] __gap;`) at the end of each implementation to reserve future slots. Audit reports flag *any* reordering of existing storage in upgrades.

**Transparent vs UUPS proxies.** Two dominant patterns. (1) **Transparent proxy** (older OpenZeppelin default): the proxy contract contains the `upgradeTo` function and a check that admin calls are handled by the proxy directly while user calls fall through to the implementation. Higher gas per call (the admin-check on every call), simpler implementation. (2) **UUPS (Universal Upgradeable Proxy Standard, EIP-1822)**: the `upgradeTo` function lives in the implementation itself, gated by the implementation's own access control. Lower gas per call, but a bug in the upgrade-authorisation logic in any implementation version can permanently break upgradeability. UUPS is now the OpenZeppelin default and the more common pattern in modern protocols.

**Initialiser races and uninitialised proxies.** Because constructors don't run when an implementation is delegate-called by a proxy, upgradeable contracts use an `initialize()` function instead. If `initialize` lacks the `initializer` modifier, anyone can call it after deployment (the Audius bug from lesson 6). Worse: in UUPS proxies, leaving the *implementation* contract uninitialised allows an attacker to call `initialize` on the implementation directly (not on the proxy) and then call `selfdestruct` via a delegate-call from the implementation's own initialised admin context — bricking the implementation for all proxies that delegate-call into it. The fix is the `_disableInitializers()` call in the implementation's constructor.

**The Wormhole upgrade bug (February 2022, $325M).** Wormhole's Solana bridge had an upgrade authorisation flaw: a signature-verification check that didn't validate which guardian had signed an upgrade. The attacker forged guardian signatures for an upgrade payload that, when processed, allowed minting wrapped ETH on Solana without backing. Technically a signature-verification bug, but its impact was amplified because it lived in an upgradeable system: a single bug in the upgrade path produced unbounded loss before the next upgrade could correct it.

**The Audius / OpenZeppelin UUPS initialiser bug (July 2022).** Multiple Audius governance contracts had unguarded `initialize` calls in upgradeable proxies. An attacker called `initialize` on the proxy, set themselves as admin, executed an upgrade to a malicious implementation that drained funds. Identified, OpenZeppelin issued an advisory and patched the standard UUPS template; protocols that had used the older template needed to verify their deployments. The class of bug — uninitialised proxy admin — recurs because the failure mode is invisible until exploited.

**The trust assumption.** Even with all the technical bugs avoided, an upgradeable contract has the social property that whoever controls the upgrade can change the contract's behaviour arbitrarily. A protocol with 'instant admin upgrade' and a single owner is functionally a centralised service masquerading as a smart contract. The convention is upgrades behind a multisig + timelock (e.g., 7-day timelock; users can exit if they see an upgrade they dislike). Reading a protocol's upgrade-admin-address, timelock-delay, and recent-upgrade-history on-chain is part of evaluating whether to trust it with capital.