Upgrades

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()

Fallback function. Implemented entirely in _fallback.

_implementation() → address

_delegate(address implementation)

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()

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()

fallback implementation. Extracted to enable manual triggering.

UpgradeabilityProxy

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

constructor(address _logic, bytes _data)

Contract constructor.

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 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

implementation() → address

changeAdmin(address newAdmin)

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

upgradeTo(address newImplementation)

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

upgradeToAndCall(address newImplementation, bytes data)

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

_setAdmin(address newAdmin)

Sets the address of the proxy admin.

_willFallback()

Only fall back when the sender is not the admin.

AdminChanged(address previousAdmin, address newAdmin)

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

Returns the current implementation.

_upgradeTo(address newImplementation)

Upgrades the proxy to a new implementation.

_setImplementation(address newImplementation)

Sets the implementation address of the proxy.

Upgraded(address implementation)

Emitted when the implementation is upgraded.

InitializableAdminUpgradeabilityProxy

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

Modifiers

initialize(address _logic, address _admin, bytes _data)

InitializableUpgradeabilityProxy

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

initialize(address _logic, bytes _data)

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

getProxyImplementation(contract AdminUpgradeabilityProxy proxy) → address

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

getProxyAdmin(contract AdminUpgradeabilityProxy proxy) → address

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

changeProxyAdmin(contract AdminUpgradeabilityProxy proxy, address newAdmin)

Changes the admin of a proxy.

upgrade(contract AdminUpgradeabilityProxy proxy, address implementation)

Upgrades a proxy to the newest implementation of a contract.

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

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()

deployMinimal(address _logic, bytes _data) → address proxy

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

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

getDeploymentAddress(uint256 _salt, address _sender) → address

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

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

_createProxy(uint256 _salt, address _sender) → contract InitializableAdminUpgradeabilityProxy

_getSalt(uint256 _salt, address _sender) → bytes32

ProxyCreated(address proxy)

Application

App

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

Modifiers

constructor()

Constructor function.

getProvider(string packageName) → contract ImplementationProvider provider

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

getPackage(string packageName) → contract Package, uint64[3]

Returns information on a package given its name.

setPackage(string packageName, contract Package package, uint64[3] version)

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)

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

getImplementation(string packageName, string contractName) → address

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

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

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)

Emitted when a new proxy is created.

PackageChanged(string providerName, address package, uint64[3] version)

Emitted when a package dependency is changed in the application.

ImplementationDirectory

Implementation provider that stores contract implementations in a mapping.

whenNotFrozen()

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

freeze()

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

getImplementation(string contractName) → address

Returns the implementation address of a contract.

setImplementation(string contractName, address implementation)

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

unsetImplementation(string contractName)

Removes the address of a contract implementation from the directory.

ImplementationChanged(string contractName, address implementation)

Emitted when the implementation of a contract is changed.

Frozen()

Emitted when the implementation directory is frozen.

ImplementationProvider

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

getImplementation(string contractName) → address

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

getVersion(uint64[3] semanticVersion) → address contractAddress, bytes contentURI

Returns a version given its semver identifier.

getContract(uint64[3] semanticVersion) → address contractAddress

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)

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

Checks whether a version is present in the package.

getLatest() → uint64[3] semanticVersion, address contractAddress, bytes contentURI

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

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(uint64[3] version) → bytes32

semanticVersionIsZero(uint64[3] version) → bool

VersionAdded(uint64[3] semanticVersion, address contractAddress, bytes contentURI)

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 to use in the initializer function of a contract.