| This document is better viewed at https://docs.openzeppelin.com/contracts/api/proxy |
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.
| 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
import "@openzeppelin/contracts/proxy/Proxy.sol";This abstract contract provides a fallback function that delegates all calls to another contract using the EVMinstruction delegatecall. We refer to the second contract as the implementation behind the proxy, and it has tobe specified by overriding the virtual _implementation function.
Additionally, delegation to the implementation can be triggered manually through the _fallback function, or to adifferent contract through the _delegate function.
The success and return data of the delegated call will be returned back to the caller of the proxy.
Functions
_delegate(implementation)
_implementation()
_fallback()
fallback()
receive()
_beforeFallback()
_delegate(address implementation) internal
Delegates the current call to implementation.
This function does not return to its internal call site, it will return directly to the external caller.
_implementation() → address internal
This is a virtual function that should be overridden so it returns the address to which the fallback functionand _fallback should delegate.
_fallback() internal
Delegates the current call to the address returned by _implementation().
This function does not return to its internal call site, it will return directly to the external caller.
fallback() external
Fallback function that delegates calls to the address returned by _implementation(). Will run if no otherfunction in the contract matches the call data.
receive() external
Fallback function that delegates calls to the address returned by _implementation(). Will run if call datais empty.
_beforeFallback() internal
Hook that is called before falling back to the implementation. Can happen as part of a manual _fallbackcall, or as part of the Solidity fallback or receive functions.
If overridden should call super._beforeFallback().
ERC1967
ERC1967Proxy
import "@openzeppelin/contracts/proxy/ERC1967/ERC1967Proxy.sol";This contract implements an upgradeable proxy. It is upgradeable because calls are delegated to animplementation address that can be changed. This address is stored in storage in the location specified byEIP1967, so that it doesn’t conflict with the storage layout of theimplementation behind the proxy.
Functions
constructor(_logic, _data)
_implementation()
ERC1967Upgrade
_getImplementation()
_upgradeTo(newImplementation)
_upgradeToAndCall(newImplementation, data, forceCall)
_upgradeToAndCallUUPS(newImplementation, data, forceCall)
_getAdmin()
_changeAdmin(newAdmin)
_getBeacon()
_upgradeBeaconToAndCall(newBeacon, data, forceCall)
Proxy
_delegate(implementation)
_fallback()
fallback()
receive()
_beforeFallback()
constructor(address _logic, bytes _data) public
Initializes the upgradeable proxy with an initial implementation specified by _logic.
If _data is nonempty, it’s used as data in a delegate call to _logic. This will typically be an encodedfunction call, and allows initializing the storage of the proxy like a Solidity constructor.
_implementation() → address impl internal
Returns the current implementation address.
ERC1967Upgrade
import "@openzeppelin/contracts/proxy/ERC1967/ERC1967Upgrade.sol";This abstract contract provides getters and event emitting update functions forEIP1967 slots.
Available since v4.1.
Functions
_getImplementation()
_upgradeTo(newImplementation)
_upgradeToAndCall(newImplementation, data, forceCall)
_upgradeToAndCallUUPS(newImplementation, data, forceCall)
_getAdmin()
_changeAdmin(newAdmin)
_getBeacon()
_upgradeBeaconToAndCall(newBeacon, data, forceCall)
Events
_getImplementation() → address internal
Returns the current implementation address.
_upgradeTo(address newImplementation) internal
Perform implementation upgrade
Emits an {Upgraded} event.
_upgradeToAndCall(address newImplementation, bytes data, bool forceCall) internal
Perform implementation upgrade with additional setup call.
Emits an {Upgraded} event.
_upgradeToAndCallUUPS(address newImplementation, bytes data, bool forceCall) internal
Perform implementation upgrade with security checks for UUPS proxies, and additional setup call.
Emits an {Upgraded} event.
_getAdmin() → address internal
Returns the current admin.
_changeAdmin(address newAdmin) internal
Changes the admin of the proxy.
Emits an {AdminChanged} event.
_getBeacon() → address internal
Returns the current beacon.
_upgradeBeaconToAndCall(address newBeacon, bytes data, bool forceCall) internal
Perform beacon upgrade with additional setup call. Note: This upgrades the address of the beacon, it doesnot upgrade the implementation contained in the beacon (see UpgradeableBeacon._setImplementation for that).
Emits a {BeaconUpgraded} event.
Transparent Proxy
TransparentUpgradeableProxy
import "@openzeppelin/contracts/proxy/transparent/TransparentUpgradeableProxy.sol";This contract implements a proxy that is upgradeable by an admin.
To avoid proxy selectorclashing, which can potentially be used in an attack, this contract uses thetransparent proxy pattern. This pattern implies twothings that go hand in hand:
If any account other than the admin calls the proxy, the call will be forwarded to the implementation, even ifthat call matches one of the admin functions exposed by the proxy itself.
If the admin calls the proxy, it can access the admin functions, but its calls will never be forwarded to theimplementation. 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 changingthe admin, so it’s best if it’s a dedicated account that is not used for anything else. This will avoid headaches dueto 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.
The real interface of this proxy is that defined in ITransparentUpgradeableProxy. This contract does notinherit from that interface, and instead the admin functions are implicitly implemented using a custom dispatchmechanism in _fallback. Consequently, the compiler will not produce an ABI for this contract. This is necessary tofully implement transparency without decoding reverts caused by selector clashes between the proxy and theimplementation. |
| It is not recommended to extend this contract to add additional external functions. If you do so, the compilerwill not check that there are no selector conflicts, due to the note above. A selector clash between any new functionand the functions declared in ITransparentUpgradeableProxy will be resolved in favor of the new one. This couldrender the admin operations inaccessible, which could prevent upgradeability. Transparency may also be compromised. |
Modifiers
ifAdmin()
Functions
constructor(_logic, admin_, _data)
_fallback()
_admin()
ERC1967Proxy
_implementation()
ERC1967Upgrade
_getImplementation()
_upgradeTo(newImplementation)
_upgradeToAndCall(newImplementation, data, forceCall)
_upgradeToAndCallUUPS(newImplementation, data, forceCall)
_getAdmin()
_changeAdmin(newAdmin)
_getBeacon()
_upgradeBeaconToAndCall(newBeacon, data, forceCall)
Proxy
_delegate(implementation)
fallback()
receive()
_beforeFallback()
ifAdmin() modifier
Modifier used internally that will delegate the call to the implementation unless the sender is the admin.
| This modifier is deprecated, as it could cause issues if the modified function has arguments, and theimplementation provides a function with the same selector. |
constructor(address _logic, address admin_, bytes _data) public
Initializes an upgradeable proxy managed by _admin, backed by the implementation at _logic, andoptionally initialized with _data as explained in ERC1967Proxy.constructor.
_fallback() internal
If caller is the admin process the call internally, otherwise transparently fallback to the proxy behavior
_admin() → address internal
Returns the current admin.
| This function is deprecated. Use ERC1967Upgrade._getAdmin instead. |
ProxyAdmin
import "@openzeppelin/contracts/proxy/transparent/ProxyAdmin.sol";This is an auxiliary contract meant to be assigned as the admin of a TransparentUpgradeableProxy. For anexplanation of why you would want to use this see the documentation for TransparentUpgradeableProxy.
Functions
getProxyImplementation(proxy)
getProxyAdmin(proxy)
changeProxyAdmin(proxy, newAdmin)
upgrade(proxy, implementation)
upgradeAndCall(proxy, implementation, data)
Events
getProxyImplementation(contract ITransparentUpgradeableProxy proxy) → address public
Returns the current implementation of proxy.
Requirements:
This contract must be the admin of
proxy.
getProxyAdmin(contract ITransparentUpgradeableProxy proxy) → address public
Returns the current admin of proxy.
Requirements:
This contract must be the admin of
proxy.
changeProxyAdmin(contract ITransparentUpgradeableProxy proxy, address newAdmin) public
Changes the admin of proxy to newAdmin.
Requirements:
This contract must be the current admin of
proxy.
upgrade(contract ITransparentUpgradeableProxy proxy, address implementation) public
Upgrades proxy to implementation. See {TransparentUpgradeableProxy-upgradeTo}.
Requirements:
This contract must be the admin of
proxy.
upgradeAndCall(contract ITransparentUpgradeableProxy proxy, address implementation, bytes data) public
Upgrades proxy to implementation and calls a function on the new implementation. See{TransparentUpgradeableProxy-upgradeToAndCall}.
Requirements:
This contract must be the admin of
proxy.
Beacon
BeaconProxy
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’tconflict with the storage layout of the implementation behind the proxy.
Available since v3.4.
Functions
constructor(beacon, data)
_beacon()
_implementation()
_setBeacon(beacon, data)
ERC1967Upgrade
_getImplementation()
_upgradeTo(newImplementation)
_upgradeToAndCall(newImplementation, data, forceCall)
_upgradeToAndCallUUPS(newImplementation, data, forceCall)
_getAdmin()
_changeAdmin(newAdmin)
_getBeacon()
_upgradeBeaconToAndCall(newBeacon, data, forceCall)
Proxy
_delegate(implementation)
_fallback()
fallback()
receive()
_beforeFallback()
constructor(address beacon, bytes data) public
Initializes the proxy with beacon.
If data is nonempty, it’s used as data in a delegate call to the implementation returned by the beacon. Thiswill typically be an encoded function call, and allows initializing the storage of the proxy like a Solidityconstructor.
Requirements:
beaconmust be a contract with the interface IBeacon.
_beacon() → address internal
Returns the current beacon address.
_implementation() → address internal
Returns the current implementation address of the associated beacon.
_setBeacon(address beacon, bytes data) internal
Changes the proxy to use a new beacon. Deprecated: see _upgradeBeaconToAndCall.
If data is nonempty, it’s used as data in a delegate call to the implementation returned by the beacon.
Requirements:
beaconmust be a contract.The implementation returned by
beaconmust be a contract.
IBeacon
import "@openzeppelin/contracts/proxy/beacon/IBeacon.sol";This is the interface that BeaconProxy expects of its beacon.
Functions
implementation()
implementation() → address external
Must return an address that can be used as a delegate call target.
BeaconProxy will check that this address is a contract.
UpgradeableBeacon
import "@openzeppelin/contracts/proxy/beacon/UpgradeableBeacon.sol";This contract is used in conjunction with one or more instances of BeaconProxy to determine theirimplementation 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.
Functions
constructor(implementation_)
implementation()
upgradeTo(newImplementation)
Events
Upgraded(implementation)
constructor(address implementation_) public
Sets the address of the initial implementation, and the deployer account as the owner who can upgrade thebeacon.
implementation() → address public
Returns the current implementation address.
upgradeTo(address newImplementation) public
Upgrades the beacon to a new implementation.
Emits an Upgraded event.
Requirements:
msg.sender must be the owner of the contract.
newImplementationmust be a contract.
Upgraded(address indexed implementation) event
Emitted when the implementation returned by the beacon is changed.
Minimal Clones
Clones
import "@openzeppelin/contracts/proxy/Clones.sol";EIP 1167 is a standard fordeploying minimal proxy contracts, also known as "clones".
To simply and cheaply clone contract functionality in an immutable way, this standard specifiesa 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 thedeterministic method.
Available since v3.4.
Functions
clone(implementation)
cloneDeterministic(implementation, salt)
predictDeterministicAddress(implementation, salt, deployer)
predictDeterministicAddress(implementation, salt)
clone(address implementation) → address instance internal
Deploys and returns the address of a clone that mimics the behaviour of implementation.
This function uses the create opcode, which should never revert.
cloneDeterministic(address implementation, bytes32 salt) → address instance internal
Deploys and returns the address of a clone that mimics the behaviour of implementation.
This function uses the create2 opcode and a salt to deterministically deploythe clone. Using the same implementation and salt multiple time will revert, sincethe clones cannot be deployed twice at the same address.
predictDeterministicAddress(address implementation, bytes32 salt, address deployer) → address predicted internal
Computes the address of a clone deployed using Clones.cloneDeterministic.
predictDeterministicAddress(address implementation, bytes32 salt) → address predicted internal
Computes the address of a clone deployed using Clones.cloneDeterministic.
Utils
Initializable
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 deployedbehind a proxy. Since proxied contracts do not make use of a constructor, it’s common to move constructor logic to anexternal initializer function, usually called initialize. It then becomes necessary to protect this initializerfunction so it can only be called once. The 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 bereused. This mechanism prevents re-execution of each "step" but allows the creation of new initialization steps incase an upgrade adds a module that needs to be initialized.
For example:
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"); }}To avoid leaving the proxy in an uninitialized state, the initializer function should be called as early aspossible by providing the encoded function call as the _data argument to ERC1967Proxy.constructor. |
| When used with inheritance, manual care must be taken to not invoke a parent initializer twice, or to ensurethat all initializers are idempotent. This is not verified automatically as constructors are by Solidity. |
Avoid leaving a contract uninitialized. An uninitialized contract can be taken over by an attacker. This applies to both a proxy and its implementationcontract, which may impact the proxy. To prevent the implementation contract from being used, you should invokethe _disableInitializers function in the constructor to automatically lock it when it is deployed: |
Modifiers
initializer()
reinitializer(version)
onlyInitializing()
Functions
_disableInitializers()
_getInitializedVersion()
_isInitializing()
Events
Initialized(version)
initializer() modifier
A modifier that defines a protected initializer function that can be invoked at most once. In its scope,onlyInitializing functions can be used to initialize parent contracts.
Similar to reinitializer(1), except that functions marked with initializer can be nested in the context of aconstructor.
Emits an Initialized event.
reinitializer(uint8 version) modifier
A modifier that defines a protected reinitializer function that can be invoked at most once, and only if thecontract hasn’t been initialized to a greater version before. In its scope, onlyInitializing functions can beused to initialize parent contracts.
A reinitializer may be used after the original initialization step. This is essential to configure modules thatare added through upgrades and that require initialization.
When version is 1, this modifier is similar to initializer, except that functions marked with reinitializercannot be nested. If one is invoked in the context of another, execution will revert.
Note that versions can jump in increments greater than 1; this implies that if multiple reinitializers coexist ina contract, executing them in the right order is up to the developer or operator.
| setting the version to 255 will prevent any future reinitialization. |
Emits an Initialized event.
onlyInitializing() modifier
Modifier to protect an initialization function so that it can only be invoked by functions with theinitializer and reinitializer modifiers, directly or indirectly.
_disableInitializers() internal
Locks the contract, preventing any future reinitialization. This cannot be part of an initializer call.Calling this in the constructor of a contract will prevent that contract from being initialized or reinitializedto any version. It is recommended to use this to lock implementation contracts that are designed to be calledthrough proxies.
Emits an Initialized event the first time it is successfully executed.
_getInitializedVersion() → uint8 internal
Returns the highest version that has been initialized. See reinitializer.
_isInitializing() → bool internal
Returns true if the contract is currently initializing. See onlyInitializing.
Initialized(uint8 version) event
Triggered when the contract has been initialized or reinitialized.
UUPSUpgradeable
import "@openzeppelin/contracts/proxy/utils/UUPSUpgradeable.sol";An upgradeability mechanism designed for UUPS proxies. The functions included here can perform an upgrade of anERC1967Proxy, 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 isreinstated if the upgrade retains upgradeability but removes the security mechanism, e.g. by replacingUUPSUpgradeable with a custom implementation of upgrades.
The _authorizeUpgrade function must be overridden to include access restriction to the upgrade mechanism.
Available since v4.1.
Modifiers
onlyProxy()
notDelegated()
Functions
proxiableUUID()
upgradeTo(newImplementation)
upgradeToAndCall(newImplementation, data)
_authorizeUpgrade(newImplementation)
ERC1967Upgrade
_getImplementation()
_upgradeTo(newImplementation)
_upgradeToAndCall(newImplementation, data, forceCall)
_upgradeToAndCallUUPS(newImplementation, data, forceCall)
_getAdmin()
_changeAdmin(newAdmin)
_getBeacon()
_upgradeBeaconToAndCall(newBeacon, data, forceCall)
onlyProxy() modifier
Check that the execution is being performed through a delegatecall call and that the execution context isa proxy contract with an implementation (as defined in ERC1967) pointing to self. This should only be the casefor UUPS and transparent proxies that are using the current contract as their implementation. Execution of afunction through ERC1167 minimal proxies (clones) would not normally pass this test, but is not guaranteed tofail.
notDelegated() modifier
Check that the execution is not being performed through a delegate call. This allows a function to becallable on the implementing contract but not through proxies.
proxiableUUID() → bytes32 external
Implementation of the ERC1822 proxiableUUID function. This returns the storage slot used by theimplementation. It is used to validate the implementation’s compatibility when performing an upgrade.
A proxy pointing at a proxiable contract should not be considered proxiable itself, because this risksbricking a proxy that upgrades to it, by delegating to itself until out of gas. Thus it is critical that thisfunction revert if invoked through a proxy. This is guaranteed by the notDelegated modifier. |
upgradeTo(address newImplementation) public
Upgrade the implementation of the proxy to newImplementation.
Calls _authorizeUpgrade.
Emits an Upgraded event.
upgradeToAndCall(address newImplementation, bytes data) public
Upgrade the implementation of the proxy to newImplementation, and subsequently execute the function callencoded in data.
Calls _authorizeUpgrade.
Emits an Upgraded event.
_authorizeUpgrade(address newImplementation) internal
Function that should revert when msg.sender is not authorized to upgrade the contract. Called byupgradeTo and upgradeToAndCall.
Normally, this function will use an access control modifier such as Ownable.onlyOwner.
function _authorizeUpgrade(address) internal override onlyOwner {}