Proxy Patterns

User → Proxy (storage) --delegatecall--> Implementation (logic)

// 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 {}
}

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

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

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

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

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

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