proxy-patterns

# Proxy Patterns Overview ## How Proxies Work A proxy contract delegates all calls to an implementation contract via `delegatecall`. Storage lives in the proxy, logic lives in the implementation. Upgrading means pointing the proxy at a new implementation. ``` User → Proxy (storage) --delegatecall--> Implementation (logic) ``` ## Pattern Comparison | Pattern | Gas (deploy) | Gas (call) | Upgrade mechanism | Best for | |---------|-------------|-----------|-------------------|----------| | UUPS | Low | Low (~200 overhead) | Implementation upgrades itself | Most contracts | | Transparent | Medium | Medium (~2100 overhead) | Admin-only proxy upgrade | Governed protocols | | Beacon | Medium | Medium (~2600 overhead) | Beacon stores impl address | Many identical proxies | | Minimal (1167) | Very low | Low (~700 overhead) | Not upgradeable | Factory clones | | Diamond (2535) | High | Medium | Per-function routing | Large systems | ## UUPS Proxy (EIP-1822) — Recommended Default The upgrade logic lives in the implementation contract. Smaller proxy, cheaper deployment. ```solidity // SPDX-License-Identifier: MIT pragma solidity ^0.8.20; import {UUPSUpgradeable} from "@openzeppelin/contracts-upgradeable/proxy/utils/UUPSUpgradeable.sol"; import {Initializable} from "@openzeppelin/contracts-upgradeable/proxy/utils/Initializable.sol"; import {OwnableUpgradeable} from "@openzeppelin/contracts-upgradeable/access/OwnableUpgradeable.sol"; contract MyContractV1 is Initializable, UUPSUpgradeable, OwnableUpgradeable { uint256 public value; /// @custom:oz-upgrades-unsafe-allow constructor constructor() { _disableInitializers(); } function initialize(address owner_) external initializer { __Ownable_init(owner_); __UUPSUpgradeable_init(); } function setValue(uint256 v) external { value = v; } function _authorizeUpgrade(address newImpl) internal override onlyOwner {} } ``` Deploy with: ```solidity import {ERC1967Proxy} from "@openzeppelin/contracts/proxy/ERC1967/ERC1967Proxy.sol"; address impl = address(new MyContractV1()); bytes memory data = abi.encodeCall(MyContractV1.initialize, (msg.sender)); address proxy = address(new ERC1967Proxy(impl, data)); ``` ## Transparent Upgradeable Proxy Upgrade logic is in the proxy itself. Admin address is blocked from calling implementation functions (prevents selector clashing). ```solidity import {TransparentUpgradeableProxy} from "@openzeppelin/contracts/proxy/transparent/TransparentUpgradeableProxy.sol"; import {ProxyAdmin} from "@openzeppelin/contracts/proxy/transparent/ProxyAdmin.sol"; ProxyAdmin admin = new ProxyAdmin(msg.sender); TransparentUpgradeableProxy proxy = new TransparentUpgradeableProxy( address(impl), address(admin), initData ); // Upgrade: admin.upgradeAndCall(ITransparentUpgradeableProxy(address(proxy)), newImpl, ""); ``` ## Storage Layout Rules (Critical) Upgradeable contracts MUST follow strict storage rules: 1. **Never remove or reorder storage variables** — only append 2. **Use storage gaps for inheritance chains**: ```solidity contract BaseV1 is Initializable { uint256 public x; uint256[49] private __gap; // reserve 49 slots // V2 can use a gap slot: // uint256 public y; // uint256[48] private __gap; } ``` 3. **No constructors** — use `initialize` + `Initializable` 4. **No immutable variables that depend on constructor** (immutables are in bytecode, not storage) ## Decision Tree ``` Need upgradeability? ├── No → Minimal Proxy (EIP-1167) for clones, or deploy directly └── Yes ├── Many identical proxies? → Beacon Proxy ├── Large contract (>24kb)? → Diamond (EIP-2535) ├── Governance / multisig admin? → Transparent Proxy └── Default → UUPS Proxy ``` ## Upgrade Safety Checklist - [ ] Storage layout is append-only (no reorder, no removal) - [ ] Use `__gap` arrays in base contracts (reserve 50 slots) - [ ] Constructor calls `_disableInitializers()` - [ ] `initialize` uses `initializer` modifier - [ ] `_authorizeUpgrade` has proper access control (UUPS) - [ ] New implementation is tested against existing storage - [ ] Run `forge inspect --storage-layout` to compare layouts - [ ] Test upgrade path: deploy v1 → upgrade to v2 → verify state - [ ] ERC-1967 storage slots used for impl/admin/beacon addresses - [ ] No `selfdestruct` in implementation (would kill proxy) ## ERC-1967 Storage Slots Standard slots prevent storage collisions: ```solidity // Implementation: bytes32(uint256(keccak256("eip1967.proxy.implementation")) - 1) bytes32 constant IMPLEMENTATION_SLOT = 0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc; // Admin: bytes32(uint256(keccak256("eip1967.proxy.admin")) - 1) bytes32 constant ADMIN_SLOT = 0xb53127684a568b3173ae13b9f8a6016e243e63b6e8ee1178d6a717850b5d6103; // Beacon: bytes32(uint256(keccak256("eip1967.proxy.beacon")) - 1) bytes32 constant BEACON_SLOT = 0xa3f0ad74e5423aebfd80d3ef4346578335a9a72aeaee59ff6cb3582b35133d50; ``` ## Testing Upgrades with Foundry ```solidity function test_upgrade() public { // Deploy V1 MyContractV1 implV1 = new MyContractV1(); ERC1967Proxy proxy = new ERC1967Proxy( address(implV1), abi.encodeCall(MyContractV1.initialize, (address(this))) ); MyContractV1(address(proxy)).setValue(42); // Deploy V2 and upgrade MyContractV2 implV2 = new MyContractV2(); MyContractV1(address(proxy)).upgradeToAndCall(address(implV2), ""); // State is preserved assertEq(MyContractV2(address(proxy)).value(), 42); // New V2 functionality works MyContractV2(address(proxy)).newFunction(); } ```