Upgrades
Library for deploying and managing upgradeable contracts from Forge scripts or tests. NOTE: Requires OpenZeppelin Contracts v5 or higher.
Functions
deployUUPSProxy
Deploys a UUPS proxy using the given contract as the implementation.
function deployUUPSProxy(string memory contractName, bytes memory initializerData, Options memory opts)
internal
returns (address);
Parameters
| Name | Type | Description |
|---|---|---|
contractName | string | Name of the contract to use as the implementation, e.g. "MyContract.sol" or "MyContract.sol:MyContract" or artifact path relative to the project root directory |
initializerData | bytes | Encoded call data of the initializer function to call during creation of the proxy, or empty if no initialization is required |
opts | Options | Common options |
Returns
| Name | Type | Description |
|---|---|---|
<none> | address | Proxy address |
deployUUPSProxy
Deploys a UUPS proxy using the given contract as the implementation.
function deployUUPSProxy(string memory contractName, bytes memory initializerData) internal returns (address);
Parameters
| Name | Type | Description |
|---|---|---|
contractName | string | Name of the contract to use as the implementation, e.g. "MyContract.sol" or "MyContract.sol:MyContract" or artifact path relative to the project root directory |
initializerData | bytes | Encoded call data of the initializer function to call during creation of the proxy, or empty if no initialization is required |
Returns
| Name | Type | Description |
|---|---|---|
<none> | address | Proxy address |
deployTransparentProxy
Deploys a transparent proxy using the given contract as the implementation.
function deployTransparentProxy(
string memory contractName,
address initialOwner,
bytes memory initializerData,
Options memory opts
) internal returns (address);
Parameters
| Name | Type | Description |
|---|---|---|
contractName | string | Name of the contract to use as the implementation, e.g. "MyContract.sol" or "MyContract.sol:MyContract" or artifact path relative to the project root directory |
initialOwner | address | Address to set as the owner of the ProxyAdmin contract which gets deployed by the proxy |
initializerData | bytes | Encoded call data of the initializer function to call during creation of the proxy, or empty if no initialization is required |
opts | Options | Common options |
Returns
| Name | Type | Description |
|---|---|---|
<none> | address | Proxy address |
deployTransparentProxy
Deploys a transparent proxy using the given contract as the implementation.
function deployTransparentProxy(string memory contractName, address initialOwner, bytes memory initializerData)
internal
returns (address);
Parameters
| Name | Type | Description |
|---|---|---|
contractName | string | Name of the contract to use as the implementation, e.g. "MyContract.sol" or "MyContract.sol:MyContract" or artifact path relative to the project root directory |
initialOwner | address | Address to set as the owner of the ProxyAdmin contract which gets deployed by the proxy |
initializerData | bytes | Encoded call data of the initializer function to call during creation of the proxy, or empty if no initialization is required |
Returns
| Name | Type | Description |
|---|---|---|
<none> | address | Proxy address |
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
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) 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 |
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;
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. |
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, address tryCaller) 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 |
tryCaller | address | Address to use as the caller of the upgrade function. This should be the address that owns the proxy or its ProxyAdmin. |
deployBeacon
Deploys an upgradeable beacon using the given contract as the implementation.
function deployBeacon(string memory contractName, address initialOwner, Options memory opts)
internal
returns (address);
Parameters
| Name | Type | Description |
|---|---|---|
contractName | string | Name of the contract to use as the implementation, e.g. "MyContract.sol" or "MyContract.sol:MyContract" or artifact path relative to the project root directory |
initialOwner | address | Address to set as the owner of the UpgradeableBeacon contract which gets deployed |
opts | Options | Common options |
Returns
| Name | Type | Description |
|---|---|---|
<none> | address | Beacon address |
deployBeacon
Deploys an upgradeable beacon using the given contract as the implementation.
function deployBeacon(string memory contractName, address initialOwner) internal returns (address);
Parameters
| Name | Type | Description |
|---|---|---|
contractName | string | Name of the contract to use as the implementation, e.g. "MyContract.sol" or "MyContract.sol:MyContract" or artifact path relative to the project root directory |
initialOwner | address | Address to set as the owner of the UpgradeableBeacon contract which gets deployed |
Returns
| Name | Type | Description |
|---|---|---|
<none> | address | Beacon address |
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
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) 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 |
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;
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. |
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, address tryCaller) 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 |
tryCaller | address | Address to use as the caller of the upgrade function. This should be the address that owns the beacon. |
deployBeaconProxy
Deploys a beacon proxy using the given beacon and call data.
function deployBeaconProxy(address beacon, bytes memory data) internal returns (address);
Parameters
| Name | Type | Description |
|---|---|---|
beacon | address | Address of the beacon to use |
data | bytes | Encoded call data of the initializer function to call during creation of the proxy, or empty if no initialization is required |
Returns
| Name | Type | Description |
|---|---|---|
<none> | address | Proxy address |
deployBeaconProxy
Deploys a beacon proxy using the given beacon and call data.
function deployBeaconProxy(address beacon, bytes memory data, Options memory opts) internal returns (address);
Parameters
| Name | Type | Description |
|---|---|---|
beacon | address | Address of the beacon to use |
data | bytes | Encoded call data of the initializer function to call during creation of the proxy, or empty if no initialization is required |
opts | Options | Common options |
Returns
| Name | Type | Description |
|---|---|---|
<none> | address | Proxy address |
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 |