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.
_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.
UpgradeabilityProxy
Extends BaseUpgradeabilityProxy with a constructor for initializing implementation and init data.
AdminUpgradeabilityProxy
Extends from BaseAdminUpgradeabilityProxy with a constructor for initializing the implementation, admin, and init data.
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.
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.
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.
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.
InitializableAdminUpgradeabilityProxy
Extends from BaseAdminUpgradeabilityProxy with an initializer for initializing the implementation, admin, and init data.
InitializableUpgradeabilityProxy
Extends BaseUpgradeabilityProxy with an initializer for initializing implementation and init data.
ProxyAdmin
This contract is the admin of a proxy, and is in charge of upgrading it as well as transferring it to another admin.
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.
ProxyFactory
deploySigned(uint256 _salt, address _logic, address _admin, bytes _data, bytes _signature) → 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
Application
App
Contract for upgradeable applications. It handles the creation of proxies.
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, uint64[3] public
Returns information on a package given its name.
setPackage(string packageName, contract Package package, 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.
ImplementationDirectory
Implementation provider that stores contract implementations in a mapping.
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.
ImplementationProvider
Abstract contract for providing implementation addresses for other contracts by name.
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.
getVersion(uint64[3] semanticVersion) → address contractAddress, bytes contentURI public
Returns a version given its semver identifier.
getContract(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(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(uint64[3] semanticVersion) → bool public
Checks whether a version is present in the package.
getLatest() → 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) → 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.
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.