Core
Internal helper methods to validate/deploy implementations and perform upgrades. WARNING: DO NOT USE DIRECTLY. Use Upgrades.sol, LegacyUpgrades.sol or Defender.sol instead.
State Variables
IMPLEMENTATION_SLOT
Storage slot with the address of the implementation. This is the keccak-256 hash of "eip1967.proxy.implementation" subtracted by 1.
bytes32 private constant IMPLEMENTATION_SLOT = 0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc;
ADMIN_SLOT
Storage slot with the admin of the proxy. This is the keccak-256 hash of "eip1967.proxy.admin" subtracted by 1.
bytes32 private constant ADMIN_SLOT = 0xb53127684a568b3173ae13b9f8a6016e243e63b6e8ee1178d6a717850b5d6103;
BEACON_SLOT
Storage slot with the UpgradeableBeacon contract which defines the implementation for the proxy. This is the keccak-256 hash of "eip1967.proxy.beacon" subtracted by 1.
bytes32 private constant BEACON_SLOT = 0xa3f0ad74e5423aebfd80d3ef4346578335a9a72aeaee59ff6cb3582b35133d50;
Functions
upgradeProxy
Upgrades a proxy to a new implementation contract. Only supported for UUPS or transparent proxies.
Requires that either the referenceContract option is set, or the new implementation contract has a @custom:oz-upgrades-from <reference> annotation.
function upgradeProxy(address proxy, string memory contractName, bytes memory data, Options memory opts) internal;
Parameters
| Name | Type | Description |
|---|---|---|
proxy | address | Address of the proxy to upgrade |
contractName | string | Name of the new implementation contract to upgrade to, e.g. "MyContract.sol" or "MyContract.sol:MyContract" or artifact path relative to the project root directory |
data | bytes | Encoded call data of an arbitrary function to call during the upgrade process, or empty if no function needs to be called during the upgrade |
opts | Options | Common options |
upgradeProxy
For tests only. If broadcasting in scripts, use the --sender <ADDRESS> option with forge script instead.
Upgrades a proxy to a new implementation contract. Only supported for UUPS or transparent proxies.
Requires that either the referenceContract option is set, or the new implementation contract has a @custom:oz-upgrades-from <reference> annotation.
This function provides an additional tryCaller parameter to test an upgrade using a specific caller address.
Use this if you encounter OwnableUnauthorizedAccount errors in your tests.
function upgradeProxy(
address proxy,
string memory contractName,
bytes memory data,
Options memory opts,
address tryCaller
) internal tryPrank(tryCaller);
Parameters
| Name | Type | Description |
|---|---|---|
proxy | address | Address of the proxy to upgrade |
contractName | string | Name of the new implementation contract to upgrade to, e.g. "MyContract.sol" or "MyContract.sol:MyContract" or artifact path relative to the project root directory |
data | bytes | Encoded call data of an arbitrary function to call during the upgrade process, or empty if no function needs to be called during the upgrade |
opts | Options | Common options |
tryCaller | address | Address to use as the caller of the upgrade function. This should be the address that owns the proxy or its ProxyAdmin. |
upgradeProxyTo
Upgrades a proxy to a new implementation contract. Only supported for UUPS or transparent proxies.
function upgradeProxyTo(address proxy, address newImpl, bytes memory data) internal;
Parameters
| Name | Type | Description |
|---|---|---|
proxy | address | Address of the proxy to upgrade |
newImpl | address | Address of the new implementation contract to upgrade to |
data | bytes | Encoded call data of an arbitrary function to call during the upgrade process, or empty if no function needs to be called during the upgrade |
upgradeProxyTo
For tests only. If broadcasting in scripts, use the --sender <ADDRESS> option with forge script instead.
Upgrades a proxy to a new implementation contract. Only supported for UUPS or transparent proxies.
This function provides an additional tryCaller parameter to test an upgrade using a specific caller address.
Use this if you encounter OwnableUnauthorizedAccount errors in your tests.
function upgradeProxyTo(address proxy, address newImpl, bytes memory data, address tryCaller)
internal
tryPrank(tryCaller);
Parameters
| Name | Type | Description |
|---|---|---|
proxy | address | Address of the proxy to upgrade |
newImpl | address | Address of the new implementation contract to upgrade to |
data | bytes | Encoded call data of an arbitrary function to call during the upgrade process, or empty if no function needs to be called during the upgrade |
tryCaller | address | Address to use as the caller of the upgrade function. This should be the address that owns the proxy or its ProxyAdmin. |
upgradeBeacon
Upgrades a beacon to a new implementation contract.
Requires that either the referenceContract option is set, or the new implementation contract has a @custom:oz-upgrades-from <reference> annotation.
function upgradeBeacon(address beacon, string memory contractName, Options memory opts) internal;
Parameters
| Name | Type | Description |
|---|---|---|
beacon | address | Address of the beacon to upgrade |
contractName | string | Name of the new implementation contract to upgrade to, e.g. "MyContract.sol" or "MyContract.sol:MyContract" or artifact path relative to the project root directory |
opts | Options | Common options |
upgradeBeacon
For tests only. If broadcasting in scripts, use the --sender <ADDRESS> option with forge script instead.
Upgrades a beacon to a new implementation contract.
Requires that either the referenceContract option is set, or the new implementation contract has a @custom:oz-upgrades-from <reference> annotation.
This function provides an additional tryCaller parameter to test an upgrade using a specific caller address.
Use this if you encounter OwnableUnauthorizedAccount errors in your tests.
function upgradeBeacon(address beacon, string memory contractName, Options memory opts, address tryCaller)
internal
tryPrank(tryCaller);
Parameters
| Name | Type | Description |
|---|---|---|
beacon | address | Address of the beacon to upgrade |
contractName | string | Name of the new implementation contract to upgrade to, e.g. "MyContract.sol" or "MyContract.sol:MyContract" or artifact path relative to the project root directory |
opts | Options | Common options |
tryCaller | address | Address to use as the caller of the upgrade function. This should be the address that owns the beacon. |
upgradeBeaconTo
Upgrades a beacon to a new implementation contract address.
function upgradeBeaconTo(address beacon, address newImpl) internal;
Parameters
| Name | Type | Description |
|---|---|---|
beacon | address | Address of the beacon to upgrade |
newImpl | address | Address of the new implementation contract to upgrade to |
upgradeBeaconTo
For tests only. If broadcasting in scripts, use the --sender <ADDRESS> option with forge script instead.
Upgrades a beacon to a new implementation contract.
This function provides an additional tryCaller parameter to test an upgrade using a specific caller address.
Use this if you encounter OwnableUnauthorizedAccount errors in your tests.
function upgradeBeaconTo(address beacon, address newImpl, address tryCaller) internal tryPrank(tryCaller);
Parameters
| Name | Type | Description |
|---|---|---|
beacon | address | Address of the beacon to upgrade |
newImpl | address | Address of the new implementation contract to upgrade to |
tryCaller | address | Address to use as the caller of the upgrade function. This should be the address that owns the beacon. |
validateImplementation
Validates an implementation contract, but does not deploy it.
function validateImplementation(string memory contractName, Options memory opts) internal;
Parameters
| Name | Type | Description |
|---|---|---|
contractName | string | Name of the contract to validate, e.g. "MyContract.sol" or "MyContract.sol:MyContract" or artifact path relative to the project root directory |
opts | Options | Common options |
deployImplementation
Validates and deploys an implementation contract, and returns its address.
function deployImplementation(string memory contractName, Options memory opts) internal returns (address);
Parameters
| Name | Type | Description |
|---|---|---|
contractName | string | Name of the contract to deploy, e.g. "MyContract.sol" or "MyContract.sol:MyContract" or artifact path relative to the project root directory |
opts | Options | Common options |
Returns
| Name | Type | Description |
|---|---|---|
<none> | address | Address of the implementation contract |
validateUpgrade
Validates a new implementation contract in comparison with a reference contract, but does not deploy it.
Requires that either the referenceContract option is set, or the contract has a @custom:oz-upgrades-from <reference> annotation.
function validateUpgrade(string memory contractName, Options memory opts) internal;
Parameters
| Name | Type | Description |
|---|---|---|
contractName | string | Name of the contract to validate, e.g. "MyContract.sol" or "MyContract.sol:MyContract" or artifact path relative to the project root directory |
opts | Options | Common options |
prepareUpgrade
Validates a new implementation contract in comparison with a reference contract, deploys the new implementation contract,
and returns its address.
Requires that either the referenceContract option is set, or the contract has a @custom:oz-upgrades-from <reference> annotation.
Use this method to prepare an upgrade to be run from an admin address you do not control directly or cannot use from your deployment environment.
function prepareUpgrade(string memory contractName, Options memory opts) internal returns (address);
Parameters
| Name | Type | Description |
|---|---|---|
contractName | string | Name of the contract to deploy, e.g. "MyContract.sol" or "MyContract.sol:MyContract" or artifact path relative to the project root directory |
opts | Options | Common options |
Returns
| Name | Type | Description |
|---|---|---|
<none> | address | Address of the new implementation contract |
getAdminAddress
Gets the admin address of a transparent proxy from its ERC1967 admin storage slot.
function getAdminAddress(address proxy) internal view returns (address);
Parameters
| Name | Type | Description |
|---|---|---|
proxy | address | Address of a transparent proxy |
Returns
| Name | Type | Description |
|---|---|---|
<none> | address | Admin address |
getImplementationAddress
Gets the implementation address of a transparent or UUPS proxy from its ERC1967 implementation storage slot.
function getImplementationAddress(address proxy) internal view returns (address);
Parameters
| Name | Type | Description |
|---|---|---|
proxy | address | Address of a transparent or UUPS proxy |
Returns
| Name | Type | Description |
|---|---|---|
<none> | address | Implementation address |
getBeaconAddress
Gets the beacon address of a beacon proxy from its ERC1967 beacon storage slot.
function getBeaconAddress(address proxy) internal view returns (address);
Parameters
| Name | Type | Description |
|---|---|---|
proxy | address | Address of a beacon proxy |
Returns
| Name | Type | Description |
|---|---|---|
<none> | address | Beacon address |
tryPrank
For tests only. If broadcasting in scripts, use the --sender <ADDRESS> option with forge script instead.
Runs a function as a prank, or just runs the function normally if the prank could not be started.
modifier tryPrank(address deployer);
getUpgradeInterfaceVersion
Gets the upgrade interface version string from a proxy or admin contract using the UPGRADE_INTERFACE_VERSION() getter.
If the contract does not have the getter or the return data does not look like a string, this function returns an empty string.
function getUpgradeInterfaceVersion(address addr) internal view returns (string memory);
inferProxyAdmin
Infers whether the address might be a ProxyAdmin contract.
function inferProxyAdmin(address addr) internal view returns (bool);
_hasOwner
Returns true if the address is a contract with an owner() function that is not state-changing and returns something that might be an address,
otherwise returns false.
function _hasOwner(address addr) private view returns (bool);
_validate
function _validate(string memory contractName, Options memory opts, bool requireReference) private;
buildValidateCommand
function buildValidateCommand(string memory contractName, Options memory opts, bool requireReference)
internal
view
returns (string[] memory);
deploy
function deploy(string memory contractName, bytes memory constructorData, Options memory opts)
internal
returns (address);
_deploy
function _deploy(string memory contractName, bytes memory constructorData) private returns (address);
_deployFromBytecode
function _deployFromBytecode(bytes memory bytecode) private returns (address);