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 ```solidity 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 ```solidity 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 ```solidity // 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; } } ``` ## Implementation Contract ```solidity // SPDX-License-Identifier: MIT pragma solidity ^0.8.20; import {Initializable} from "@openzeppelin/contracts-upgradeable/proxy/utils/Initializable.sol"; import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol"; import {SafeERC20} from "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol"; interface IVault { function initialize(address owner, address asset) external; } contract VaultV1 is Initializable, IVault { using SafeERC20 for IERC20; address public owner; IERC20 public asset; uint256 public totalDeposited; /// @custom:oz-upgrades-unsafe-allow constructor constructor() { _disableInitializers(); } function initialize(address owner_, address asset_) external override initializer { owner = owner_; asset = IERC20(asset_); } function deposit(uint256 amount) external { asset.safeTransferFrom(msg.sender, address(this), amount); totalDeposited += amount; } function withdraw(uint256 amount) external { require(msg.sender == owner, "Not owner"); totalDeposited -= amount; asset.safeTransfer(owner, amount); } } contract VaultV2 is Initializable, IVault { using SafeERC20 for IERC20; address public owner; IERC20 public asset; uint256 public totalDeposited; // V2: new storage variable (appended, never reorder) uint256 public depositCap; /// @custom:oz-upgrades-unsafe-allow constructor constructor() { _disableInitializers(); } function initialize(address owner_, address asset_) external override initializer { owner = owner_; asset = IERC20(asset_); } function setDepositCap(uint256 cap) external { require(msg.sender == owner, "Not owner"); depositCap = cap; } function deposit(uint256 amount) external { require(depositCap == 0 || totalDeposited + amount <= depositCap, "Cap exceeded"); asset.safeTransferFrom(msg.sender, address(this), amount); totalDeposited += amount; } function withdraw(uint256 amount) external { require(msg.sender == owner, "Not owner"); totalDeposited -= amount; asset.safeTransfer(owner, amount); } } ``` ## Beacon vs UUPS vs Transparent | Feature | Beacon | UUPS | Transparent | |---------|--------|------|-------------| | Upgrade scope | All proxies at once | One proxy at a time | One proxy at a time | | Who upgrades | Beacon owner | Implementation | Proxy admin | | Gas per call | +2600 (SLOAD beacon) | +200 | +2100 (admin check) | | Deploy cost/proxy | ~47k | ~65k | ~120k | | Best for | Many identical instances | General purpose | Governed contracts | ## When to Use Beacon - Deploying many proxies with the same implementation (vaults, accounts, pools) - Need to upgrade all instances simultaneously - Factory pattern where users deploy their own instance - Protocol wants single upgrade transaction (simpler governance) ## Gas Considerations Each call to a BeaconProxy costs an extra `SLOAD` (~2100 gas cold, ~100 warm) to read the implementation address from the Beacon. For high-frequency calls, consider caching patterns or UUPS instead. ## Deterministic Beacon Proxies ```solidity function createVaultDeterministic( address vaultOwner, address asset, bytes32 salt ) external returns (address vault) { bytes memory initData = abi.encodeCall(IVault.initialize, (vaultOwner, asset)); vault = address(new BeaconProxy{salt: salt}(address(beacon), initData)); allVaults.push(vault); } ``` ## Testing ```solidity function test_beaconUpgrade() public { VaultV1 implV1 = new VaultV1(); VaultFactory factory = new VaultFactory(address(implV1)); address vault = factory.createVault(alice, address(usdc)); assertEq(factory.implementation(), address(implV1)); // Deposit with V1 vm.startPrank(alice); usdc.approve(vault, 100e6); VaultV1(vault).deposit(100e6); assertEq(VaultV1(vault).totalDeposited(), 100e6); vm.stopPrank(); // Upgrade to V2 VaultV2 implV2 = new VaultV2(); factory.upgradeImplementation(address(implV2)); // State preserved, new function available assertEq(VaultV2(vault).totalDeposited(), 100e6); vm.prank(alice); VaultV2(vault).setDepositCap(1000e6); assertEq(VaultV2(vault).depositCap(), 1000e6); } ``` ## Security Checklist - [ ] Beacon owner is a multisig or governance contract - [ ] Implementation follows storage layout rules (append-only) - [ ] `_disableInitializers()` in implementation constructor - [ ] Test upgrade path preserves all existing state - [ ] New implementation is deployed and verified before upgrade - [ ] Beacon address is immutable in factory (cannot be swapped)