How do upgradeable proxy contracts work? UUPS vs Transparent

Transparent proxy

The upgrade logic lives in the proxy. To avoid clashes between the proxy's admin functions and the implementation's functions, the proxy checks the caller:

• calls from the admin go to the proxy's own upgrade function and are never forwarded;
• calls from everyone else are always forwarded to the implementation.

In OpenZeppelin Contracts v5, TransparentUpgradeableProxy deploys its own ProxyAdmin contract in its constructor, and that ProxyAdmin is the only address that can upgrade. You control the ProxyAdmin through its owner, ideally a multisig. The admin can't use the application through the proxy, which is why a separate admin contract is used.

Trade-offs: the proxy is bigger and more expensive to deploy, and the admin check adds a little gas to every call. In exchange, the upgrade mechanism can't be removed or broken by a bad implementation.

UUPS proxy

In UUPS (Universal Upgradeable Proxy Standard, ERC-1822), the proxy is minimal and the upgrade function lives in the implementation. You inherit UUPSUpgradeable and decide who can upgrade by overriding _authorizeUpgrade:

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

import {Initializable} from "@openzeppelin/contracts-upgradeable/proxy/utils/Initializable.sol";
import {UUPSUpgradeable} from "@openzeppelin/contracts-upgradeable/proxy/utils/UUPSUpgradeable.sol";
import {OwnableUpgradeable} from "@openzeppelin/contracts-upgradeable/access/OwnableUpgradeable.sol";

contract BoxV1 is Initializable, OwnableUpgradeable, UUPSUpgradeable {
    uint256 public value;

    /// @custom:oz-upgrades-unsafe-allow constructor
    constructor() {
        _disableInitializers(); // nobody can initialize the implementation itself
    }

    function initialize(address initialOwner) public initializer {
        __Ownable_init(initialOwner);
    }

    function setValue(uint256 newValue) external onlyOwner {
        value = newValue;
    }

    function _authorizeUpgrade(address) internal override onlyOwner {}
}

Upgrades go through the proxy as a normal call: upgradeToAndCall(newImplementation, data), which runs _authorizeUpgrade first. OpenZeppelin's version also checks that the new implementation is itself UUPS-compatible before switching.

Trade-offs: cheaper deployment and calls, and you can eventually remove upgradeability by deploying an implementation without the upgrade function. The flip side is that you can do that by accident. If a new version forgets to inherit UUPSUpgradeable, or _authorizeUpgrade has a bug, the proxy may be stuck forever or upgradeable by anyone.

Pitfalls for both patterns

Initialize atomically. Deploy the proxy and call initialize in the same transaction (both OpenZeppelin proxy constructors accept initialization data). Otherwise someone can front-run your initialize and become the owner.

Disable initializers on the implementation. The implementation is a live contract too. The _disableInitializers() constructor above stops anyone from initializing it directly and taking ownership of it.

Never reorder storage. In V2, keep every existing state variable in the same order with the same type. Only add new variables after the existing ones. Don't change the inheritance order. Violating this makes V2 read V1's data from the wrong slots, silently corrupting balances or ownership. OpenZeppelin v5 upgradeable contracts keep their own state in namespaced storage (ERC-7201), which removes most of the need for the older __gap arrays, but your own variables still follow the rules.

Be careful with immutable variables and constructor logic. They're baked into the implementation's bytecode, not stored in the proxy, so they change with every upgrade and can't be set per proxy.

Validate before every upgrade. Use the OpenZeppelin plugins, which compare storage layouts between versions and refuse unsafe changes:

// Hardhat, with @openzeppelin/hardhat-upgrades
import { ethers, upgrades } from "hardhat";

const [owner] = await ethers.getSigners();
const Box = await ethers.getContractFactory("BoxV1");
const box = await upgrades.deployProxy(Box, [owner.address], { kind: "uups" });

const BoxV2 = await ethers.getContractFactory("BoxV2");
await upgrades.upgradeProxy(await box.getAddress(), BoxV2);

Foundry users get the same checks from the openzeppelin-foundry-upgrades library.

Which to choose

For new projects, UUPS is the common default and OpenZeppelin's recommendation, as long as you validate each upgrade. Pick Transparent if you want the upgrade path to be independent of implementation code.

Checklist

1. Replace constructors with initializer functions, and call _disableInitializers() in the implementation's constructor.
2. Deploy and initialize the proxy in one transaction.
3. Append-only storage; never reorder, remove or retype variables.
4. For UUPS, protect _authorizeUpgrade and keep inheriting UUPSUpgradeable in every version.
5. Run the OpenZeppelin upgrade validation before each upgrade.
6. Put upgrade rights behind a multisig and, ideally, a timelock.

Is ERC-20 approve dangerous? Allowances, permit and infinite approvals

Approve is safe; unlimited, forgotten allowances and unread permit signatures are not. Approve exact amounts, use permit with short deadlines, read every typed-data signature, and revoke old approvals.

#security#tokens#wallets