OpenZeppelin SDK is not being actively developed. We recommend using Upgrades Plugins instead. For more information, see Building for interoperability: why we’re focusing on Upgrades Plugins.

API Reference

Proxies

Proxy

Implements delegation of calls to other contracts, with proper forwarding of return values and bubbling of failures. It defines a fallback function that delegates all calls to the address returned by the abstract _implementation() internal function.

fallback() external

Fallback function. Implemented entirely in _fallback.

_implementation() → address internal

_delegate(address implementation) internal

Delegates execution to an implementation contract. This is a low level function that doesn’t return to its internal call site. It will return to the external caller whatever the implementation returns.

_willFallback() internal

Function that is run as the first thing in the fallback function. Can be redefined in derived contracts to add functionality. Redefinitions must call super._willFallback().

_fallback() internal

fallback implementation. Extracted to enable manual triggering.

UpgradeabilityProxy

Extends BaseUpgradeabilityProxy with a constructor for initializing implementation and init data.

Events
BaseUpgradeabilityProxy

constructor(address _logic, bytes _data) public

Contract constructor.

AdminUpgradeabilityProxy

Extends from BaseAdminUpgradeabilityProxy with a constructor for initializing the implementation, admin, and init data.

Modifiers
BaseAdminUpgradeabilityProxy
Events
BaseAdminUpgradeabilityProxy
BaseUpgradeabilityProxy

constructor(address _logic, address _admin, bytes _data) public

BaseAdminUpgradeabilityProxy

This contract combines an upgradeability proxy with an authorization mechanism for administrative tasks. All external functions in this contract must be guarded by the ifAdmin modifier. See ethereum/solidity#3864 for a Solidity feature proposal that would enable this to be done automatically.

Modifiers

ifAdmin() modifier

Modifier to check whether the msg.sender is the admin. If it is, it will run the function. Otherwise, it will delegate the call to the implementation.

admin() → address external

implementation() → address external

changeAdmin(address newAdmin) external

Changes the admin of the proxy. Only the current admin can call this function.

upgradeTo(address newImplementation) external

Upgrade the backing implementation of the proxy. Only the admin can call this function.

upgradeToAndCall(address newImplementation, bytes data) external

Upgrade the backing implementation of the proxy and call a function on the new implementation. This is useful to initialize the proxied contract.

_admin() → address adm internal

_setAdmin(address newAdmin) internal

Sets the address of the proxy admin.

_willFallback() internal

Only fall back when the sender is not the admin.

AdminChanged(address previousAdmin, address newAdmin) event

Emitted when the administration has been transferred.

BaseUpgradeabilityProxy

This contract implements a proxy that allows to change the implementation address to which it will delegate. Such a change is called an implementation upgrade.

_implementation() → address impl internal

Returns the current implementation.

_upgradeTo(address newImplementation) internal

Upgrades the proxy to a new implementation.

_setImplementation(address newImplementation) internal

Sets the implementation address of the proxy.

Upgraded(address implementation) event

Emitted when the implementation is upgraded.

InitializableAdminUpgradeabilityProxy

Extends from BaseAdminUpgradeabilityProxy with an initializer for initializing the implementation, admin, and init data.

Modifiers
BaseAdminUpgradeabilityProxy
Events
BaseAdminUpgradeabilityProxy
BaseUpgradeabilityProxy

initialize(address _logic, address _admin, bytes _data) public

InitializableUpgradeabilityProxy

Extends BaseUpgradeabilityProxy with an initializer for initializing implementation and init data.

Events
BaseUpgradeabilityProxy

initialize(address _logic, bytes _data) public

Contract initializer.

ProxyAdmin

This contract is the admin of a proxy, and is in charge of upgrading it as well as transferring it to another admin.

Modifiers
OpenZeppelinUpgradesOwnable
Events
OpenZeppelinUpgradesOwnable

getProxyImplementation(contract AdminUpgradeabilityProxy proxy) → address public

Returns the current implementation of a proxy. This is needed because only the proxy admin can query it.

getProxyAdmin(contract AdminUpgradeabilityProxy proxy) → address public

Returns the admin of a proxy. Only the admin can query it.

changeProxyAdmin(contract AdminUpgradeabilityProxy proxy, address newAdmin) public

Changes the admin of a proxy.

upgrade(contract AdminUpgradeabilityProxy proxy, address implementation) public

Upgrades a proxy to the newest implementation of a contract.

upgradeAndCall(contract AdminUpgradeabilityProxy proxy, address implementation, bytes data) public

Upgrades a proxy to the newest implementation of a contract and forwards a function call to it. This is useful to initialize the proxied contract.

ProxyFactory

constructor() public

deployMinimal(address _logic, bytes _data) → address proxy public

deploy(uint256 _salt, address _logic, address _admin, bytes _data) → address public

deploySigned(uint256 _salt, address _logic, address _admin, bytes _data, bytes _signature) → address public

getDeploymentAddress(uint256 _salt, address _sender) → address public

getSigner(uint256 _salt, address _logic, address _admin, bytes _data, bytes _signature) → address public

_deployProxy(uint256 _salt, address _logic, address _admin, bytes _data, address _sender) → address internal

_createProxy(uint256 _salt, address _sender) → contract InitializableAdminUpgradeabilityProxy internal

_getSalt(uint256 _salt, address _sender) → bytes32 internal

ProxyCreated(address proxy) event

Application

App

Contract for upgradeable applications. It handles the creation of proxies.

Modifiers
OpenZeppelinUpgradesOwnable

constructor() public

Constructor function.

getProvider(string packageName) → contract ImplementationProvider provider public

Returns the provider for a given package name, or zero if not set.

getPackage(string packageName) → contract Package, [.var-type]#uint64[3] [.item-kind]#public

Returns information on a package given its name.

setPackage(string packageName, contract Package package, [.var-type]#uint64[3# version)] public

Sets a package in a specific version as a dependency for this application. Requires the version to be present in the package.

unsetPackage(string packageName) public

Unsets a package given its name. Reverts if the package is not set in the application.

getImplementation(string packageName, string contractName) → address public

Returns the implementation address for a given contract name, provided by the ImplementationProvider.

create(string packageName, string contractName, address admin, bytes data) → contract AdminUpgradeabilityProxy public

Creates a new proxy for the given contract and forwards a function call to it. This is useful to initialize the proxied contract.

ProxyCreated(address proxy) event

Emitted when a new proxy is created.

PackageChanged(string providerName, address package, [.var-type]#uint64[3# version)] event

Emitted when a package dependency is changed in the application.

ImplementationDirectory

Implementation provider that stores contract implementations in a mapping.

Modifiers
OpenZeppelinUpgradesOwnable

whenNotFrozen() modifier

Modifier that allows functions to be called only before the contract is frozen.

freeze() public

Makes the directory irreversibly immutable. It can only be called once, by the owner.

getImplementation(string contractName) → address public

Returns the implementation address of a contract.

setImplementation(string contractName, address implementation) public

Sets the address of the implementation of a contract in the directory.

unsetImplementation(string contractName) public

Removes the address of a contract implementation from the directory.

ImplementationChanged(string contractName, address implementation) event

Emitted when the implementation of a contract is changed.

Frozen() event

Emitted when the implementation directory is frozen.

ImplementationProvider

Abstract contract for providing implementation addresses for other contracts by name.

getImplementation(string contractName) → address public

Abstract function to return the implementation address of a contract.

Package

A package is composed by a set of versions, identified via semantic versioning, where each version has a contract address that refers to a reusable implementation, plus an optional content URI with metadata. Note that the semver identifier is restricted to major, minor, and patch, as prerelease tags are not supported.

Modifiers
OpenZeppelinUpgradesOwnable

getVersion([.var-type]#uint64[3# semanticVersion) → address contractAddress, bytes contentURI] public

Returns a version given its semver identifier.

getContract([.var-type]#uint64[3# semanticVersion) → address contractAddress] public

Returns a contract for a version given its semver identifier. This method is equivalent to getVersion, but returns only the contract address.

addVersion([.var-type]#uint64[3# semanticVersion, address contractAddress, bytes contentURI)] public

Adds a new version to the package. Only the Owner can add new versions. Reverts if the specified semver identifier already exists. Emits a VersionAdded event if successful.

hasVersion([.var-type]#uint64[3# semanticVersion) → bool] public

Checks whether a version is present in the package.

getLatest() → [.var-type]#uint64[3# semanticVersion, address contractAddress, bytes contentURI] public

Returns the version with the highest semver identifier registered in the package. For instance, if 1.2.0, 1.3.0, and 2.0.0 are present, will always return 2.0.0, regardless of the order in which they were registered. Returns zero if no versions are registered.

getLatestByMajor(uint64 major) → [.var-type]#uint64[3# semanticVersion, address contractAddress, bytes contentURI] public

Returns the version with the highest semver identifier for the given major. For instance, if 1.2.0, 1.3.0, and 2.0.0 are present, will return 1.3.0 for major 1, regardless of the order in which they were registered. Returns zero if no versions are registered for the specified major.

semanticVersionHash([.var-type]#uint64[3# version) → bytes32] internal

semanticVersionIsZero([.var-type]#uint64[3# version) → bool] internal

VersionAdded([.var-type]#uint64[3# semanticVersion, address contractAddress, bytes contentURI)] event

Emitted when a version is added to the package.

Utility

Initializable

Helper contract to support initializer functions. To use it, replace the constructor with a function that has the initializer modifier. WARNING: Unlike constructors, initializer functions must be manually invoked. This applies both to deploying an Initializable contract, as well as extending an Initializable contract via inheritance. WARNING: When used with inheritance, manual care must be taken to not invoke a parent initializer twice, or ensure that all initializers are idempotent, because this is not dealt with automatically as with constructors.

Modifiers

initializer() modifier

Modifier to use in the initializer function of a contract.