beacon-proxy

Beacon Proxy Pattern

Overview

The Beacon proxy pattern stores the implementation address in a shared Beacon contract. Multiple proxies point to the same Beacon. Upgrading the Beacon upgrades ALL proxies in a single transaction.

BeaconProxy-1 ──┐
BeaconProxy-2 ──┼──→ UpgradeableBeacon ──→ Implementation v1
BeaconProxy-3 ──┘

After upgrade:

BeaconProxy-1 ──┐
BeaconProxy-2 ──┼──→ UpgradeableBeacon ──→ Implementation v2
BeaconProxy-3 ──┘

UpgradeableBeacon

import {UpgradeableBeacon} from "@openzeppelin/contracts/proxy/beacon/UpgradeableBeacon.sol";

// Deploy beacon with initial implementation
address impl = address(new VaultV1());
UpgradeableBeacon beacon = new UpgradeableBeacon(impl, msg.sender);

// Upgrade all proxies at once
address newImpl = address(new VaultV2());
beacon.upgradeTo(newImpl);

BeaconProxy Deployment

import {BeaconProxy} from "@openzeppelin/contracts/proxy/beacon/BeaconProxy.sol";

// Each proxy points to the beacon (not the implementation directly)
bytes memory initData = abi.encodeCall(VaultV1.initialize, (owner, asset));
BeaconProxy proxy = new BeaconProxy(address(beacon), initData);

Complete Factory Pattern

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

import {UpgradeableBeacon} from "@openzeppelin/contracts/proxy/beacon/UpgradeableBeacon.sol";
import {BeaconProxy} from "@openzeppelin/contracts/proxy/beacon/BeaconProxy.sol";
import {Ownable} from "@openzeppelin/contracts/access/Ownable.sol";

contract VaultFactory is Ownable {
    UpgradeableBeacon public immutable beacon;
    address[] public allVaults;

    event VaultCreated(address indexed vault, address indexed owner, uint256 index);
    event ImplementationUpgraded(address indexed newImpl);

    constructor(address initialImpl) Ownable(msg.sender) {
        beacon = new UpgradeableBeacon(initialImpl, address(this));
    }

    function createVault(address vaultOwner, address asset)
        external returns (address vault)
    {
        bytes memory initData = abi.encodeCall(
            IVault.initialize, (vaultOwner, asset)
        );
        vault = address(new BeaconProxy(address(beacon), initData));
        allVaults.push(vault);
        emit VaultCreated(vault, vaultOwner, allVaults.length - 1);
    }

    function upgradeImplementation(address newImpl) external onlyOwner {
        beacon.upgradeTo(newImpl);
        emit ImplementationUpgraded(newImpl);
    }

    function implementation() external view returns (address) {
        return beacon.implementation();
    }

    function vaultCount() external view returns (uint256) {
        return allVaults.length;
    }
}