OpenZeppelin Foundry Upgrades API
Contract name formats
Contract names must be provided in specific formats depending on context. The following are the required formats for each context:
Foundry artifact format
Contexts:
contractNameparameterreferenceContractoption ifreferenceBuildInfoDiroption is not set
Can be in any of the following forms according to Foundry’s getCode cheatcode:
- the Solidity file name, e.g.
ContractV1.sol - the Solidity file name and the contract name, e.g.
ContractV1.sol:ContractV1 - the artifact path relative to the project root directory, e.g.
out/ContractV1.sol/ContractV1.json
Annotation format
Contexts:
@custom:oz-upgrades-from <reference>annotationreferenceContractoption ifreferenceBuildInfoDiroption is set
Can be in any of the following forms according to the OpenZeppelin Upgrades CLI:
- the contract name, e.g.
ContractV1 - fully qualified contract name, e.g.
contracts/tokens/ContractV1.sol:ContractV1
If the referenceBuildInfoDir option is set, include the build info directory short name as a prefix, resulting in one of the following forms:
- the build info directory short name and the contract name, e.g.
build-info-v1:ContractV1 - the build info directory short name and the fully qualified contract name, e.g.
build-info-v1:contracts/tokens/ContractV1.sol:ContractV1
Common Options
The following options can be used with some of the below functions. See Options.sol for detailed descriptions of each option.
Options 📁
import "@openzeppelin/src/Options.sol";DefenderOptions 📁
import "@openzeppelin/src/Options.sol";TxOverrides 📁
import "@openzeppelin/src/Options.sol";Upgrades.sol
Upgrades 📁
import "@openzeppelin/src/Upgrades.sol";Library for deploying and managing upgradeable contracts from Forge scripts or tests.
NOTE: Requires OpenZeppelin Contracts v5 or higher.
Functions
- deployUUPSProxy(contractName, initializerData, opts)
- deployUUPSProxy(contractName, initializerData)
- deployTransparentProxy(contractName, initialOwner, initializerData, opts)
- deployTransparentProxy(contractName, initialOwner, initializerData)
- upgradeProxy(proxy, contractName, data, opts)
- upgradeProxy(proxy, contractName, data)
- upgradeProxy(proxy, contractName, data, opts, tryCaller)
- upgradeProxy(proxy, contractName, data, tryCaller)
- deployBeacon(contractName, initialOwner, opts)
- deployBeacon(contractName, initialOwner)
- upgradeBeacon(beacon, contractName, opts)
- upgradeBeacon(beacon, contractName)
- upgradeBeacon(beacon, contractName, opts, tryCaller)
- upgradeBeacon(beacon, contractName, tryCaller)
- deployBeaconProxy(beacon, data)
- deployBeaconProxy(beacon, data, opts)
- validateImplementation(contractName, opts)
- deployImplementation(contractName, opts)
- validateUpgrade(contractName, opts)
- prepareUpgrade(contractName, opts)
- getAdminAddress(proxy)
- getImplementationAddress(proxy)
- getBeaconAddress(proxy)
deployUUPSProxy(string contractName, bytes initializerData, struct Options opts) → address
internal
Deploys a UUPS proxy using the given contract as the implementation.
deployUUPSProxy(string contractName, bytes initializerData) → address
internal
Deploys a UUPS proxy using the given contract as the implementation.
deployTransparentProxy(string contractName, address initialOwner, bytes initializerData, struct Options opts) → address
internal
Deploys a transparent proxy using the given contract as the implementation.
deployTransparentProxy(string contractName, address initialOwner, bytes initializerData) → address
internal
Deploys a transparent proxy using the given contract as the implementation.
upgradeProxy(address proxy, string contractName, bytes data, struct Options opts)
internal
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.
upgradeProxy(address proxy, string contractName, bytes data)
internal
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.
upgradeProxy(address proxy, string contractName, bytes data, struct Options opts, address tryCaller)
internal
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.
upgradeProxy(address proxy, string contractName, bytes data, address tryCaller)
internal
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.
deployBeacon(string contractName, address initialOwner, struct Options opts) → address
internal
Deploys an upgradeable beacon using the given contract as the implementation.
deployBeacon(string contractName, address initialOwner) → address
internal
Deploys an upgradeable beacon using the given contract as the implementation.
upgradeBeacon(address beacon, string contractName, struct Options opts)
internal
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.
upgradeBeacon(address beacon, string contractName)
internal
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.
upgradeBeacon(address beacon, string contractName, struct Options opts, address tryCaller)
internal
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.
upgradeBeacon(address beacon, string contractName, address tryCaller)
internal
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.
deployBeaconProxy(address beacon, bytes data) → address
internal
Deploys a beacon proxy using the given beacon and call data.
deployBeaconProxy(address beacon, bytes data, struct Options opts) → address
internal
Deploys a beacon proxy using the given beacon and call data.
validateImplementation(string contractName, struct Options opts)
internal
Validates an implementation contract, but does not deploy it.
deployImplementation(string contractName, struct Options opts) → address
internal
Validates and deploys an implementation contract, and returns its address.
validateUpgrade(string contractName, struct Options opts)
internal
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.
prepareUpgrade(string contractName, struct Options opts) → address
internal
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.
getAdminAddress(address proxy) → address
internal
Gets the admin address of a transparent proxy from its ERC1967 admin storage slot.
getImplementationAddress(address proxy) → address
internal
Gets the implementation address of a transparent or UUPS proxy from its ERC1967 implementation storage slot.
getBeaconAddress(address proxy) → address
internal
Gets the beacon address of a beacon proxy from its ERC1967 beacon storage slot.
UnsafeUpgrades 📁
import "@openzeppelin/src/Upgrades.sol";Library for deploying and managing upgradeable contracts from Forge tests, without validations.
Can be used with forge coverage. Requires implementation contracts to be instantiated first.
Does not require --ffi and does not require a clean compilation before each run.
Not supported for OpenZeppelin Defender deployments.
WARNING: Not recommended for use in Forge scripts.
UnsafeUpgrades does not validate whether your contracts are upgrade safe or whether new implementations are compatible with previous ones.
Use Upgrades if you want validations to be run.
NOTE: Requires OpenZeppelin Contracts v5 or higher.
Functions
- deployUUPSProxy(impl, initializerData)
- deployTransparentProxy(impl, initialOwner, initializerData)
- upgradeProxy(proxy, newImpl, data)
- upgradeProxy(proxy, newImpl, data, tryCaller)
- deployBeacon(impl, initialOwner)
- upgradeBeacon(beacon, newImpl)
- upgradeBeacon(beacon, newImpl, tryCaller)
- deployBeaconProxy(beacon, data)
- getAdminAddress(proxy)
- getImplementationAddress(proxy)
- getBeaconAddress(proxy)
deployUUPSProxy(address impl, bytes initializerData) → address
internal
Deploys a UUPS proxy using the given contract address as the implementation.
deployTransparentProxy(address impl, address initialOwner, bytes initializerData) → address
internal
Deploys a transparent proxy using the given contract address as the implementation.
upgradeProxy(address proxy, address newImpl, bytes data)
internal
Upgrades a proxy to a new implementation contract address. Only supported for UUPS or transparent proxies.
upgradeProxy(address proxy, address newImpl, bytes data, address tryCaller)
internal
Upgrades a proxy to a new implementation contract address. 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.
deployBeacon(address impl, address initialOwner) → address
internal
Deploys an upgradeable beacon using the given contract address as the implementation.
upgradeBeacon(address beacon, address newImpl)
internal
Upgrades a beacon to a new implementation contract address.
upgradeBeacon(address beacon, address newImpl, address tryCaller)
internal
Upgrades a beacon to a new implementation contract address.
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.
deployBeaconProxy(address beacon, bytes data) → address
internal
Deploys a beacon proxy using the given beacon and call data.
getAdminAddress(address proxy) → address
internal
Gets the admin address of a transparent proxy from its ERC1967 admin storage slot.
getImplementationAddress(address proxy) → address
internal
Gets the implementation address of a transparent or UUPS proxy from its ERC1967 implementation storage slot.
getBeaconAddress(address proxy) → address
internal
Gets the beacon address of a beacon proxy from its ERC1967 beacon storage slot.
LegacyUpgrades.sol
import "@openzeppelin/src/LegacyUpgrades.sol";Library for managing upgradeable contracts from Forge scripts or tests.
NOTE: Only for upgrading existing deployments using OpenZeppelin Contracts v4. For new deployments, use OpenZeppelin Contracts v5 and Upgrades.sol.
Functions
- upgradeProxy(proxy, contractName, data, opts)
- upgradeProxy(proxy, contractName, data)
- upgradeProxy(proxy, contractName, data, opts, tryCaller)
- upgradeProxy(proxy, contractName, data, tryCaller)
- upgradeBeacon(beacon, contractName, opts)
- upgradeBeacon(beacon, contractName)
- upgradeBeacon(beacon, contractName, opts, tryCaller)
- upgradeBeacon(beacon, contractName, tryCaller)
- validateUpgrade(contractName, opts)
- prepareUpgrade(contractName, opts)
- getAdminAddress(proxy)
- getImplementationAddress(proxy)
- getBeaconAddress(proxy)
upgradeProxy(address proxy, string contractName, bytes data, struct Options opts)
internal
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.
upgradeProxy(address proxy, string contractName, bytes data)
internal
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.
upgradeProxy(address proxy, string contractName, bytes data, struct Options opts, address tryCaller)
internal
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.
upgradeProxy(address proxy, string contractName, bytes data, address tryCaller)
internal
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.
upgradeBeacon(address beacon, string contractName, struct Options opts)
internal
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.
upgradeBeacon(address beacon, string contractName)
internal
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.
upgradeBeacon(address beacon, string contractName, struct Options opts, address tryCaller)
internal
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.
upgradeBeacon(address beacon, string contractName, address tryCaller)
internal
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.
validateUpgrade(string contractName, struct Options opts)
internal
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.
prepareUpgrade(string contractName, struct Options opts) → address
internal
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.
getAdminAddress(address proxy) → address
internal
Gets the admin address of a transparent proxy from its ERC1967 admin storage slot.
getImplementationAddress(address proxy) → address
internal
Gets the implementation address of a transparent or UUPS proxy from its ERC1967 implementation storage slot.
getBeaconAddress(address proxy) → address
internal
Gets the beacon address of a beacon proxy from its ERC1967 beacon storage slot.
UnsafeUpgrades 📁
import "@openzeppelin/src/LegacyUpgrades.sol";Library for managing upgradeable contracts from Forge tests, without validations.
Can be used with forge coverage. Requires implementation contracts to be instantiated first.
Does not require --ffi and does not require a clean compilation before each run.
Not supported for OpenZeppelin Defender deployments.
WARNING: Not recommended for use in Forge scripts.
UnsafeUpgrades does not validate whether your contracts are upgrade safe or whether new implementations are compatible with previous ones.
Use Upgrades if you want validations to be run.
NOTE: Only for upgrading existing deployments using OpenZeppelin Contracts v4. For new deployments, use OpenZeppelin Contracts v5 and Upgrades.sol.
Functions
- upgradeProxy(proxy, newImpl, data)
- upgradeProxy(proxy, newImpl, data, tryCaller)
- upgradeBeacon(beacon, newImpl)
- upgradeBeacon(beacon, newImpl, tryCaller)
- getAdminAddress(proxy)
- getImplementationAddress(proxy)
- getBeaconAddress(proxy)
upgradeProxy(address proxy, address newImpl, bytes data)
internal
Upgrades a proxy to a new implementation contract address. Only supported for UUPS or transparent proxies.
upgradeProxy(address proxy, address newImpl, bytes data, address tryCaller)
internal
Upgrades a proxy to a new implementation contract address. 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.
upgradeBeacon(address beacon, address newImpl)
internal
Upgrades a beacon to a new implementation contract address.
upgradeBeacon(address beacon, address newImpl, address tryCaller)
internal
Upgrades a beacon to a new implementation contract address.
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.
getAdminAddress(address proxy) → address
internal
Gets the admin address of a transparent proxy from its ERC1967 admin storage slot.
getImplementationAddress(address proxy) → address
internal
Gets the implementation address of a transparent or UUPS proxy from its ERC1967 implementation storage slot.
getBeaconAddress(address proxy) → address
internal
Gets the beacon address of a beacon proxy from its ERC1967 beacon storage slot.
Defender.sol
Defender 📁
import "@openzeppelin/src/Defender.sol";Library for interacting with OpenZeppelin Defender from Forge scripts or tests.
Functions
- deployContract(contractName)
- deployContract(contractName, defenderOpts)
- deployContract(contractName, constructorData)
- deployContract(contractName, constructorData, defenderOpts)
- proposeUpgrade(proxyAddress, newImplementationContractName, opts)
- getDeployApprovalProcess()
- getUpgradeApprovalProcess()
deployContract(string contractName) → address
internal
Deploys a contract to the current network using OpenZeppelin Defender.
WARNING: Do not use this function directly if you are deploying an upgradeable contract. This function does not validate whether the contract is upgrade safe.
NOTE: If using an EOA or Safe to deploy, go to Defender deploy to submit the pending deployment while the script is running. The script waits for the deployment to complete before it continues.
deployContract(string contractName, struct DefenderOptions defenderOpts) → address
internal
Deploys a contract to the current network using OpenZeppelin Defender.
WARNING: Do not use this function directly if you are deploying an upgradeable contract. This function does not validate whether the contract is upgrade safe.
NOTE: If using an EOA or Safe to deploy, go to Defender deploy to submit the pending deployment while the script is running. The script waits for the deployment to complete before it continues.
deployContract(string contractName, bytes constructorData) → address
internal
Deploys a contract with constructor arguments to the current network using OpenZeppelin Defender.
WARNING: Do not use this function directly if you are deploying an upgradeable contract. This function does not validate whether the contract is upgrade safe.
NOTE: If using an EOA or Safe to deploy, go to Defender deploy to submit the pending deployment while the script is running. The script waits for the deployment to complete before it continues.
deployContract(string contractName, bytes constructorData, struct DefenderOptions defenderOpts) → address
internal
Deploys a contract with constructor arguments to the current network using OpenZeppelin Defender.
WARNING: Do not use this function directly if you are deploying an upgradeable contract. This function does not validate whether the contract is upgrade safe.
NOTE: If using an EOA or Safe to deploy, go to Defender deploy to submit the pending deployment while the script is running. The script waits for the deployment to complete before it continues.
proposeUpgrade(address proxyAddress, string newImplementationContractName, struct Options opts) → struct ProposeUpgradeResponse
internal
Proposes an upgrade to an upgradeable proxy using OpenZeppelin Defender.
This function validates a new implementation contract in comparison with a reference contract, deploys the new implementation contract using Defender, and proposes an upgrade to the new implementation contract using an upgrade approval process on Defender.
Supported for UUPS or Transparent proxies. Not currently supported for beacon proxies or beacons.
For beacons, use Upgrades.prepareUpgrade along with a transaction proposal on Defender to upgrade the beacon to the deployed implementation.
Requires that either the referenceContract option is set, or the contract has a @custom:oz-upgrades-from <reference> annotation.
WARNING: Ensure that the reference contract is the same as the current implementation contract that the proxy is pointing to. This function does not validate that the reference contract is the current implementation.
NOTE: If using an EOA or Safe to deploy, go to Defender deploy to submit the pending deployment of the new implementation contract while the script is running. The script waits for the deployment to complete before it continues.
getDeployApprovalProcess() → struct ApprovalProcessResponse
internal
Gets the default deploy approval process configured for your deployment environment on OpenZeppelin Defender.
getUpgradeApprovalProcess() → struct ApprovalProcessResponse
internal
Gets the default upgrade approval process configured for your deployment environment on OpenZeppelin Defender. For example, this is useful for determining the default multisig wallet that you can use in your scripts to assign as the owner of your proxy.
ProposeUpgradeResponse 📁
import "@openzeppelin/src/Defender.sol";ApprovalProcessResponse 📁
import "@openzeppelin/src/Defender.sol";