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.

// 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:

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));