This is a low-level set of contracts implementing different proxy patterns with and without upgradeability. For an in-depth overview of this pattern check out the Proxy Upgrade Pattern page.

Most of the proxies below are built on an abstract base contract.

• Proxy: Abstract contract implementing the core delegation functionality.

In order to avoid clashes with the storage variables of the implementation contract behind a proxy, we use EIP1967 storage slots.

• ERC1967Upgrade: Internal functions to get and set the storage slots defined in EIP1967.
• ERC1967Proxy: A proxy using EIP1967 storage slots. Not upgradeable by default.

There are two alternative ways to add upgradeability to an ERC1967 proxy. Their differences are explained below in Transparent vs UUPS Proxies.

• TransparentUpgradeableProxy: A proxy with a built in admin and upgrade interface.
• UUPSUpgradeable: An upgradeability mechanism to be included in the implementation contract.

🔥 CAUTION
Using upgradeable proxies correctly and securely is a difficult task that requires deep knowledge of the proxy pattern, Solidity, and the EVM. Unless you want a lot of low level control, we recommend using the OpenZeppelin Upgrades Plugins for Truffle and Hardhat.

A different family of proxies are beacon proxies. This pattern, popularized by Dharma, allows multiple proxies to be upgraded to a different implementation in a single transaction.

• BeaconProxy: A proxy that retrieves its implementation from a beacon contract.
• UpgradeableBeacon: A beacon contract with a built in admin that can upgrade the BeaconProxy pointing to it.

In this pattern, the proxy contract doesn’t hold the implementation address in storage like an ERC1967 proxy. Instead, the address is stored in a separate beacon contract. The upgrade operations are sent to the beacon instead of to the proxy contract, and all proxies that follow that beacon are automatically upgraded.

Outside the realm of upgradeability, proxies can also be useful to make cheap contract clones, such as those created by an on-chain factory contract that creates many instances of the same contract. These instances are designed to be both cheap to deploy, and cheap to call.

• Clones: A library that can deploy cheap minimal non-upgradeable proxies.

Transparent vs UUPS Proxies

The original proxies included in OpenZeppelin followed the Transparent Proxy Pattern. While this pattern is still provided, our recommendation is now shifting towards UUPS proxies, which are both lightweight and versatile. The name UUPS comes from EIP1822, which first documented the pattern.

While both of these share the same interface for upgrades, in UUPS proxies the upgrade is handled by the implementation, and can eventually be removed. Transparent proxies, on the other hand, include the upgrade and admin logic in the proxy itself. This means TransparentUpgradeableProxy is more expensive to deploy than what is possible with UUPS proxies.

UUPS proxies are implemented using an ERC1967Proxy. Note that this proxy is not by itself upgradeable. It is the role of the implementation to include, alongside the contract’s logic, all the code necessary to update the implementation’s address that is stored at a specific slot in the proxy’s storage space. This is where the UUPSUpgradeable contract comes in. Inheriting from it (and overriding the _authorizeUpgrade function with the relevant access control mechanism) will turn your contract into a UUPS compliant implementation.

Note that since both proxies use the same storage slot for the implementation address, using a UUPS compliant implementation with a TransparentUpgradeableProxy might allow non-admins to perform upgrade operations.

By default, the upgrade functionality included in UUPSUpgradeable contains a security mechanism that will prevent any upgrades to a non UUPS compliant implementation. This prevents upgrades to an implementation contract that wouldn’t contain the necessary upgrade mechanism, as it would lock the upgradeability of the proxy forever. This security mechanism can be bypassed by either of:

• Adding a flag mechanism in the implementation that will disable the upgrade function when triggered.
• Upgrading to an implementation that features an upgrade mechanism without the additional security check, and then upgrading again to another implementation without the upgrade mechanism.

The current implementation of this security mechanism uses EIP1822 to detect the storage slot used by the implementation. A previous implementation, now deprecated, relied on a rollback check. It is possible to upgrade from a contract using the old mechanism to a new one. The inverse is however not possible, as old implementations (before version 4.5) did not include the ERC1822 interface.

Core

Proxy

ERC1967

IERC1967

ERC1967Proxy

ERC1967Upgrade

Transparent Proxy

TransparentUpgradeableProxy

ProxyAdmin

Beacon

BeaconProxy

IBeacon

UpgradeableBeacon

Minimal Clones

Clones

Utils

Initializable

UUPSUpgradeable

import "@openzeppelin/contracts/proxy/Clones.sol";

EIP 1167 is a standard for deploying minimal proxy contracts, also known as "clones".

To simply and cheaply clone contract functionality in an immutable way, this standard specifies a minimal bytecode implementation that delegates all calls to a known, fixed address.

The library includes functions to deploy a proxy using either create (traditional deployment) or create2 (salted deterministic deployment). It also includes functions to predict the addresses of clones deployed using the deterministic method.

Available since v3.4.

import "@openzeppelin/contracts/proxy/ERC1967/ERC1967Proxy.sol";

This contract implements an upgradeable proxy. It is upgradeable because calls are delegated to an implementation address that can be changed. This address is stored in storage in the location specified by EIP1967, so that it doesn't conflict with the storage layout of the implementation behind the proxy.

import "@openzeppelin/contracts/proxy/ERC1967/ERC1967Upgrade.sol";

This abstract contract provides getters and event emitting update functions for EIP1967 slots.

Available since v4.1.

import "@openzeppelin/contracts/proxy/Proxy.sol";

This abstract contract provides a fallback function that delegates all calls to another contract using the EVM instruction delegatecall. We refer to the second contract as the implementation behind the proxy, and it has to be specified by overriding the virtual ERC1967Proxy._implementation function.

Additionally, delegation to the implementation can be triggered manually through the Proxy._fallback function, or to a different contract through the Votes._delegate function.

The success and return data of the delegated call will be returned back to the caller of the proxy.

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

This contract implements a proxy that gets the implementation address for each call from an UpgradeableBeacon.

The beacon address is stored in storage slot uint256(keccak256('eip1967.proxy.beacon')) - 1, so that it doesn't conflict with the storage layout of the implementation behind the proxy.

Available since v3.4.

import "@openzeppelin/contracts/proxy/beacon/IBeacon.sol";

This is the interface that BeaconProxy expects of its beacon.

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

This contract is used in conjunction with one or more instances of BeaconProxy to determine their implementation contract, which is where they will delegate all function calls.

An owner is able to change the implementation the beacon points to, thus upgrading the proxies that use this beacon.

import "@openzeppelin/contracts/proxy/transparent/ProxyAdmin.sol";

This is an auxiliary contract meant to be assigned as the admin of a TransparentUpgradeableProxy. For an explanation of why you would want to use this see the documentation for TransparentUpgradeableProxy.

import "@openzeppelin/contracts/proxy/transparent/TransparentUpgradeableProxy.sol";

Interface for TransparentUpgradeableProxy. In order to implement transparency, TransparentUpgradeableProxy does not implement this interface directly, and some of its functions are implemented by an internal dispatch mechanism. The compiler is unaware that these functions are implemented by TransparentUpgradeableProxy and will not include them in the ABI so this interface must be used to interact with it.

import "@openzeppelin/contracts/proxy/transparent/TransparentUpgradeableProxy.sol";

This contract implements a proxy that is upgradeable by an admin.

To avoid proxy selector clashing, which can potentially be used in an attack, this contract uses the transparent proxy pattern. This pattern implies two things that go hand in hand:

1. If any account other than the admin calls the proxy, the call will be forwarded to the implementation, even if that call matches one of the admin functions exposed by the proxy itself.
2. If the admin calls the proxy, it can access the admin functions, but its calls will never be forwarded to the implementation. If the admin tries to call a function on the implementation it will fail with an error that says "admin cannot fallback to proxy target".

These properties mean that the admin account can only be used for admin actions like upgrading the proxy or changing the admin, so it's best if it's a dedicated account that is not used for anything else. This will avoid headaches due to sudden errors when trying to call a function from the proxy implementation.

Our recommendation is for the dedicated account to be an instance of the ProxyAdmin contract. If set up this way, you should think of the ProxyAdmin instance as the real administrative interface of your proxy.

NOTE: The real interface of this proxy is that defined in ITransparentUpgradeableProxy. This contract does not inherit from that interface, and instead the admin functions are implicitly implemented using a custom dispatch mechanism in _fallback. Consequently, the compiler will not produce an ABI for this contract. This is necessary to fully implement transparency without decoding reverts caused by selector clashes between the proxy and the implementation.

import "@openzeppelin/contracts/proxy/utils/Initializable.sol";

This is a base contract to aid in writing upgradeable contracts, or any kind of contract that will be deployed behind a proxy. Since proxied contracts do not make use of a constructor, it's common to move constructor logic to an external initializer function, usually called initialize. It then becomes necessary to protect this initializer function so it can only be called once. The Initializable.initializer modifier provided by this contract will have this effect.

The initialization functions use a version number. Once a version number is used, it is consumed and cannot be reused. This mechanism prevents re-execution of each "step" but allows the creation of new initialization steps in case an upgrade adds a module that needs to be initialized.

For example:

[.hljs-theme-light.nopadding]

contract MyToken is ERC20Upgradeable {
    function initialize() initializer public {
        __ERC20_init("MyToken", "MTK");
    }
}

contract MyTokenV2 is MyToken, ERC20PermitUpgradeable {
    function initializeV2() reinitializer(2) public {
        __ERC20Permit_init("MyToken");
    }
}

TIP: To avoid leaving the proxy in an uninitialized state, the initializer function should be called as early as possible by providing the encoded function call as the _data argument to ERC1967Proxy.constructor.

CAUTION: When used with inheritance, manual care must be taken to not invoke a parent initializer twice, or to ensure that all initializers are idempotent. This is not verified automatically as constructors are by Solidity.

[CAUTION]

Avoid leaving a contract uninitialized.

An uninitialized contract can be taken over by an attacker. This applies to both a proxy and its implementation contract, which may impact the proxy. To prevent the implementation contract from being used, you should invoke the Initializable._disableInitializers function in the constructor to automatically lock it when it is deployed:

[.hljs-theme-light.nopadding]

/// @custom:oz-upgrades-unsafe-allow constructor
constructor() {
    _disableInitializers();
}

====

import "@openzeppelin/contracts/proxy/utils/UUPSUpgradeable.sol";

An upgradeability mechanism designed for UUPS proxies. The functions included here can perform an upgrade of an ERC1967Proxy, when this contract is set as the implementation behind such a proxy.

A security mechanism ensures that an upgrade does not turn off upgradeability accidentally, although this risk is reinstated if the upgrade retains upgradeability but removes the security mechanism, e.g. by replacing UUPSUpgradeable with a custom implementation of upgrades.

The UUPSUpgradeable._authorizeUpgrade function must be overridden to include access restriction to the upgrade mechanism.

Available since v4.1.

function _authorizeUpgrade(address) internal override onlyOwner {}