upgradeable-proxy

Upgradeable Proxy Playbook

Proxies separate storage (proxy) from logic (implementation). The proxy delegatecalls into the implementation, executing logic in the proxy's storage context. Three common patterns:

1. Transparent Proxy (OZ TransparentUpgradeableProxy)
2. UUPS (OZ UUPSUpgradeable, OZ 4.1+)
3. Diamond / EIP-2535 (multi-facet, much more complex)

Each has distinct bug classes.

Audit checklist

1. Uninitialized implementation

Implementations should be initialized at deployment to prevent third-party initialization:

// Vulnerable — anyone can call initialize() on the implementation
// directly (not via proxy) and become its owner
contract VulnImpl {
    function initialize(address owner_) external {
        owner = owner_;
    }
}

// Safe — disable initializers on impl deployment
contract SafeImpl is Initializable {
    constructor() { _disableInitializers(); }

    function initialize(address owner_) external initializer {
        owner = owner_;
    }
}

Attack: attacker calls initialize on the impl contract → becomes "owner" of the impl. While this doesn't immediately drain the proxy, it CAN matter if _authorizeUpgrade reads impl-side state, or if selfdestruct is exposed and impl auth is on owner. Past incident: Parity multisig 2017 — $280M frozen.

# Find unprotected impl
grep -rn 'initialize\|_disableInitializers' src/

2. Storage slot collisions

Proxy and impl share storage. New impl versions must lay storage identical to old:

// V1
contract LogicV1 {
    address public owner;     // slot 0
    uint256 public total;     // slot 1
}

// V2 — BUG: inserted new var at top
contract LogicV2 {
    uint256 public newVar;    // slot 0 — overwrites owner!
    address public owner;     // slot 1
    uint256 public total;     // slot 2
}

After upgrade, owner is read from where total was; arbitrary value.

Check:

• New vars only appended at the end
• Inheritance order unchanged
• OZ __gap reserved slots used in upgradeable libs