Proxies
Outdated Version
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.
The abstract Proxy contract implements the core delegation functionality. If the concrete proxies that we provide below are not suitable, we encourage building on top of this base contract since it contains an assembly block that may be hard to get right.
Upgradeability is implemented in the UpgradeableProxy contract, although it provides only an internal upgrade interface. For an upgrade interface exposed externally to an admin, we provide TransparentUpgradeableProxy. Both of these contracts use the storage slots specified in EIP1967 to avoid clashes with the storage of the implementation contract behind the proxy.
An alternative upgradeability mechanism is provided in Beacon. This pattern, popularized by Dharma, allows multiple proxies to be upgraded to a different implementation in a single transaction. In this pattern, the proxy contract doesn’t hold the implementation address in storage like UpgradeableProxy, but the address of a UpgradeableBeacon contract, which is where the implementation address is actually stored and retrieved from. The upgrade
operations that change the implementation contract address are then sent to the beacon instead of to the proxy contract, and all proxies that follow that beacon are automatically upgraded.
The Clones library provides a way to deploy minimal non-upgradeable proxies for cheap. This can be useful for applications that require deploying many instances of the same contract (for example one per user, or one per task). These instances are designed to be both cheap to deploy, and cheap to call. The drawback being that they are not upgradeable.
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 Buidler.
Core
Proxy
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 _implementation function.
Additionally, delegation to the implementation can be triggered manually through the _fallback function, or to a different 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(address implementation) *internal*
Delegates the current call to implementation
.
This function does not return to its internall call site, it will return directly to the external caller.
_implementation() → address *internal*
This is a virtual function that should be overriden so it returns the address to which the fallback function and _fallback should delegate.
_fallback() *internal*
Delegates the current call to the address returned by _implementation()
.
This function does not return to its internall 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 other
function in the contract matches the call data.
receive() *external*
Fallback function that delegates calls to the address returned by _implementation()
. Will run if call data
is empty.
_beforeFallback() *internal*
Hook that is called before falling back to the implementation. Can happen as part of a manual _fallback
call, or as part of the Solidity fallback
or receive
functions.
If overriden should call super._beforeFallback()
.
UpgradeableProxy
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.
Upgradeability is only provided internally through _upgradeTo. For an externally upgradeable proxy see TransparentUpgradeableProxy.
Functions
Proxy
Events
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 encoded
function call, and allows initializating the storage of the proxy like a Solidity constructor.
_implementation() → address impl *internal*
Returns the current implementation address.
_upgradeTo(address newImplementation) *internal*
Upgrades the proxy to a new implementation.
Emits an Upgraded event.
Upgraded(address implementation) *event*
Emitted when the implementation is upgraded.
TransparentUpgradeableProxy
This contract implements a proxy that is upgradeable by an admin.
To avoid https://medium.com/nomic-labs-blog/malicious-backdoors-in-ethereum-proxies-62629adf3357[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:
- 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.
- 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.
Modifiers
Functions
constructor(_logic, admin_, _data)
admin()
implementation()
changeAdmin(newAdmin)
upgradeTo(newImplementation)
upgradeToAndCall(newImplementation, data)
_admin()
_beforeFallback()
UpgradeableProxy
Proxy
Events
UpgradeableProxy
ifAdmin() *modifier*
Modifier used internally that will delegate the call to the implementation unless the sender is the admin.
constructor(address _logic, address admin_, bytes _data) *public*
Initializes an upgradeable proxy managed by _admin
, backed by the implementation at _logic
, and
optionally initialized with _data
as explained in UpgradeableProxy-constructor.
admin() → address admin_ *external*
Returns the current admin.
Only the admin can call this function. See ProxyAdmin-getProxyAdmin.
To get this value clients can read directly from the storage slot shown below (specified by EIP1967) using the
eth_getStorageAt
RPC call.
0xb53127684a568b3173ae13b9f8a6016e243e63b6e8ee1178d6a717850b5d6103
implementation() → address implementation_ *external*
Returns the current implementation.
Only the admin can call this function. See ProxyAdmin-getProxyImplementation.
To get this value clients can read directly from the storage slot shown below (specified by EIP1967) using the
eth_getStorageAt
RPC call.
0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc
changeAdmin(address newAdmin) *external*
Changes the admin of the proxy.
Emits an AdminChanged event.
Only the admin can call this function. See ProxyAdmin-changeProxyAdmin.
upgradeTo(address newImplementation) *external*
Upgrade the implementation of the proxy.
Only the admin can call this function. See ProxyAdmin-upgrade.
upgradeToAndCall(address newImplementation, bytes data) *external*
Upgrade the implementation of the proxy, and then call a function from the new implementation as specified
by data
, which should be an encoded function call. This is useful to initialize new storage variables in the
proxied contract.
Only the admin can call this function. See ProxyAdmin-upgradeAndCall.
_admin() → address adm *internal*
Returns the current admin.
_beforeFallback() *internal*
Makes sure the admin cannot access the fallback function. See Proxy-_beforeFallback.
AdminChanged(address previousAdmin, address newAdmin) *event*
Emitted when the admin account has changed.
Beacon
BeaconProxy
This contract implements a proxy that gets the implementation address for each call from a 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.
Functions
Proxy
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. This
will typically be an encoded function call, and allows initializating the storage of the proxy like a Solidity
constructor.
Requirements:
beacon
must be a contract with the interface IBeacon.
_beacon() → address beacon *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.
If data
is nonempty, it’s used as data in a delegate call to the implementation returned by the beacon.
Requirements:
beacon
must be a contract.- The implementation returned by
beacon
must be a contract.
IBeacon
This is the interface that BeaconProxy expects of its beacon.
Functions
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
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.
Functions
Ownable
Events
Ownable
constructor(address implementation_) *public*
Sets the address of the initial implementation, and the deployer account as the owner who can upgrade the beacon.
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.
*
Upgraded(address implementation) *event*
Emitted when the implementation returned by the beacon is changed.
Minimal Clones
Clones
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.
Functions
clone(master)
cloneDeterministic(master, salt)
predictDeterministicAddress(master, salt, deployer)
predictDeterministicAddress(master, salt)
clone(address master) → address instance *internal*
Deploys and returns the address of a clone that mimics the behaviour of master
.
This function uses the create opcode, which should never revert.
cloneDeterministic(address master, bytes32 salt) → address instance *internal*
Deploys and returns the address of a clone that mimics the behaviour of master
.
This function uses the create2 opcode and a salt
to deterministically deploy
the clone. Using the same master
and salt
multiple time will revert, since
the clones cannot be deployed twice at the same address.
predictDeterministicAddress(address master, bytes32 salt, address deployer) → address predicted *internal*
Computes the address of a clone deployed using Clones-cloneDeterministic.
predictDeterministicAddress(address master, bytes32 salt) → address predicted *internal*
Computes the address of a clone deployed using Clones-cloneDeterministic.
Utilities
Initializable
This is a base contract to aid in writing upgradeable contracts, or any kind of contract that will be deployed
behind a proxy. Since a proxied contract can’t have 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 initializer modifier provided by this contract will have this effect.
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 UpgradeableProxy-constructor.
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.
Modifiers
initializer() *modifier*
Modifier to protect an initializer function from being invoked twice.
ProxyAdmin
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.
Functions
getProxyImplementation(proxy)
getProxyAdmin(proxy)
changeProxyAdmin(proxy, newAdmin)
upgrade(proxy, implementation)
upgradeAndCall(proxy, implementation, data)
Ownable
Events
Ownable
getProxyImplementation(contract TransparentUpgradeableProxy proxy) → address *public*
Returns the current implementation of proxy
.
Requirements:
- This contract must be the admin of
proxy
.
getProxyAdmin(contract TransparentUpgradeableProxy proxy) → address *public*
Returns the current admin of proxy
.
Requirements:
- This contract must be the admin of
proxy
.
changeProxyAdmin(contract TransparentUpgradeableProxy proxy, address newAdmin) *public*
Changes the admin of proxy
to newAdmin
.
Requirements:
- This contract must be the current admin of
proxy
.
upgrade(contract TransparentUpgradeableProxy proxy, address implementation) *public*
Upgrades proxy
to implementation
. See TransparentUpgradeableProxy-upgradeTo.
Requirements:
- This contract must be the admin of
proxy
.
upgradeAndCall(contract TransparentUpgradeableProxy 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
.