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:

  • contractName parameter

  • referenceContract option if referenceBuildInfoDir option 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> annotation

  • referenceContract option if referenceBuildInfoDir option 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 { Options } from "openzeppelin-foundry-upgrades/Options.sol";
struct Options {
  string referenceContract;
  string referenceBuildInfoDir;
  bytes constructorData;
  string[] exclude;
  string unsafeAllow;
  bool unsafeAllowRenames;
  bool unsafeSkipProxyAdminCheck;
  bool unsafeSkipStorageCheck;
  bool unsafeSkipAllChecks;
  struct DefenderOptions defender;
}

DefenderOptions 

import { DefenderOptions } from "openzeppelin-foundry-upgrades/Options.sol";
struct DefenderOptions {
  bool useDefenderDeploy;
  bool skipVerifySourceCode;
  string relayerId;
  bytes32 salt;
  string upgradeApprovalProcessId;
  string licenseType;
  bool skipLicenseType;
  struct TxOverrides txOverrides;
  string metadata;
}

TxOverrides 

import { TxOverrides } from "openzeppelin-foundry-upgrades/Options.sol";
struct TxOverrides {
  uint256 gasLimit;
  uint256 gasPrice;
  uint256 maxFeePerGas;
  uint256 maxPriorityFeePerGas;
}

Upgrades.sol

Upgrades 

import { Upgrades } from "openzeppelin-foundry-upgrades/Upgrades.sol";

Library for deploying and managing upgradeable contracts from Forge scripts or tests.

Requires OpenZeppelin Contracts v5 or higher.
Functions

deployUUPSProxy(string contractName, bytes initializerData, struct Options opts) → address internal

Deploys a UUPS proxy using the given contract as the implementation.

Parameters:

  • 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 (struct Options) - Common options

Returns

  • (address) - Proxy address

deployUUPSProxy(string contractName, bytes initializerData) → address internal

Deploys a UUPS proxy using the given contract as the implementation.

Parameters:

  • 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

  • (address) - Proxy address

deployTransparentProxy(string contractName, address initialOwner, bytes initializerData, struct Options opts) → address internal

Deploys a transparent proxy using the given contract as the implementation.

Parameters:

  • 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 (struct Options) - Common options

Returns

  • (address) - Proxy address

deployTransparentProxy(string contractName, address initialOwner, bytes initializerData) → address internal

Deploys a transparent proxy using the given contract as the implementation.

Parameters:

  • 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

  • (address) - Proxy address

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.

Parameters:

  • 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 (struct Options) - Common options

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.

Parameters:

  • 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(address proxy, string contractName, bytes data, struct Options opts, address tryCaller) internal

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.

Parameters:

  • 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 (struct 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(address proxy, string contractName, bytes data, address tryCaller) internal

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.

Parameters:

  • 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(string contractName, address initialOwner, struct Options opts) → address internal

Deploys an upgradeable beacon using the given contract as the implementation.

Parameters:

  • 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 (struct Options) - Common options

Returns

  • (address) - Beacon address

deployBeacon(string contractName, address initialOwner) → address internal

Deploys an upgradeable beacon using the given contract as the implementation.

Parameters:

  • 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

  • (address) - Beacon address

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.

Parameters:

  • 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 (struct Options) - Common options

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.

Parameters:

  • 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(address beacon, string contractName, struct Options opts, address tryCaller) internal

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.

Parameters:

  • 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 (struct 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(address beacon, string contractName, address tryCaller) internal

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.

Parameters:

  • 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(address beacon, bytes data) → address internal

Deploys a beacon proxy using the given beacon and call data.

Parameters:

  • 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

  • (address) - Proxy address

deployBeaconProxy(address beacon, bytes data, struct Options opts) → address internal

Deploys a beacon proxy using the given beacon and call data.

Parameters:

  • 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 (struct Options) - Common options

Returns

  • (address) - Proxy address

validateImplementation(string contractName, struct Options opts) internal

Validates an implementation contract, but does not deploy it.

Parameters:

  • 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 (struct Options) - Common options

deployImplementation(string contractName, struct Options opts) → address internal

Validates and deploys an implementation contract, and returns its address.

Parameters:

  • 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 (struct Options) - Common options

Returns

  • (address) - Address of the implementation contract

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.

Parameters:

  • 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 (struct Options) - Common options

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.

Parameters:

  • 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 (struct Options) - Common options

Returns

  • (address) - Address of the new implementation contract

getAdminAddress(address proxy) → address internal

Gets the admin address of a transparent proxy from its ERC1967 admin storage slot.

Parameters:

  • proxy (address) - Address of a transparent proxy

Returns

  • (address) - Admin address

getImplementationAddress(address proxy) → address internal

Gets the implementation address of a transparent or UUPS proxy from its ERC1967 implementation storage slot.

Parameters:

  • proxy (address) - Address of a transparent or UUPS proxy

Returns

  • (address) - Implementation address

getBeaconAddress(address proxy) → address internal

Gets the beacon address of a beacon proxy from its ERC1967 beacon storage slot.

Parameters:

  • proxy (address) - Address of a beacon proxy

Returns

  • (address) - Beacon address

UnsafeUpgrades 

import { UnsafeUpgrades } from "openzeppelin-foundry-upgrades/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.

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.
Requires OpenZeppelin Contracts v5 or higher.
Functions

deployUUPSProxy(address impl, bytes initializerData) → address internal

Deploys a UUPS proxy using the given contract address as the implementation.

Parameters:

  • impl (address) - Address of the contract to use as the implementation

  • initializerData (bytes) - Encoded call data of the initializer function to call during creation of the proxy, or empty if no initialization is required

Returns

  • (address) - Proxy address

deployTransparentProxy(address impl, address initialOwner, bytes initializerData) → address internal

Deploys a transparent proxy using the given contract address as the implementation.

Parameters:

  • impl (address) - Address of the contract to use as the implementation

  • 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

  • (address) - Proxy address

upgradeProxy(address proxy, address newImpl, bytes data) internal

Upgrades a proxy to a new implementation contract address. Only supported for UUPS or transparent proxies.

Parameters:

  • 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

upgradeProxy(address proxy, address newImpl, bytes data, address tryCaller) internal

For tests only. If broadcasting in scripts, use the --sender <ADDRESS> option with forge script instead.

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.

Parameters:

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

deployBeacon(address impl, address initialOwner) → address internal

Deploys an upgradeable beacon using the given contract address as the implementation.

Parameters:

  • impl (address) - Address of the contract to use as the implementation

  • initialOwner (address) - Address to set as the owner of the UpgradeableBeacon contract which gets deployed

Returns

  • (address) - Beacon address

upgradeBeacon(address beacon, address newImpl) internal

Upgrades a beacon to a new implementation contract address.

Parameters:

  • beacon (address) - Address of the beacon to upgrade

  • newImpl (address) - Address of the new implementation contract to upgrade to

upgradeBeacon(address beacon, address newImpl, address tryCaller) internal

For tests only. If broadcasting in scripts, use the --sender <ADDRESS> option with forge script instead.

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.

Parameters:

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

deployBeaconProxy(address beacon, bytes data) → address internal

Deploys a beacon proxy using the given beacon and call data.

Parameters:

  • 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

  • (address) - Proxy address

getAdminAddress(address proxy) → address internal

Gets the admin address of a transparent proxy from its ERC1967 admin storage slot.

Parameters:

  • proxy (address) - Address of a transparent proxy

Returns

  • (address) - Admin address

getImplementationAddress(address proxy) → address internal

Gets the implementation address of a transparent or UUPS proxy from its ERC1967 implementation storage slot.

Parameters:

  • proxy (address) - Address of a transparent or UUPS proxy

Returns

  • (address) - Implementation address

getBeaconAddress(address proxy) → address internal

Gets the beacon address of a beacon proxy from its ERC1967 beacon storage slot.

Parameters:

  • proxy (address) - Address of a beacon proxy

Returns

  • (address) - Beacon address

LegacyUpgrades.sol

Upgrades 

import { Upgrades } from "openzeppelin-foundry-upgrades/LegacyUpgrades.sol";

Library for managing upgradeable contracts from Forge scripts or tests.

Only for upgrading existing deployments using OpenZeppelin Contracts v4. For new deployments, use OpenZeppelin Contracts v5 and Upgrades.sol.
Functions

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.

Parameters:

  • 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 (struct Options) - Common options

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.

Parameters:

  • 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(address proxy, string contractName, bytes data, struct Options opts, address tryCaller) internal

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.

Parameters:

  • 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 (struct 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(address proxy, string contractName, bytes data, address tryCaller) internal

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.

Parameters:

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

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.

Parameters:

  • 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 (struct Options) - Common options

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.

Parameters:

  • 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(address beacon, string contractName, struct Options opts, address tryCaller) internal

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.

Parameters:

  • 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 (struct 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(address beacon, string contractName, address tryCaller) internal

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.

Parameters:

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

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.

Parameters:

  • 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 (struct Options) - Common options

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.

Parameters:

  • 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 (struct Options) - Common options

Returns

  • (address) - Address of the new implementation contract

getAdminAddress(address proxy) → address internal

Gets the admin address of a transparent proxy from its ERC1967 admin storage slot.

Parameters:

  • proxy (address) - Address of a transparent proxy

Returns

  • (address) - Admin address

getImplementationAddress(address proxy) → address internal

Gets the implementation address of a transparent or UUPS proxy from its ERC1967 implementation storage slot.

Parameters:

  • proxy (address) - Address of a transparent or UUPS proxy

Returns

  • (address) - Implementation address

getBeaconAddress(address proxy) → address internal

Gets the beacon address of a beacon proxy from its ERC1967 beacon storage slot.

Parameters:

  • proxy (address) - Address of a beacon proxy

Returns

  • (address) - Beacon address

UnsafeUpgrades 

import { UnsafeUpgrades } from "openzeppelin-foundry-upgrades/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.

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.
Only for upgrading existing deployments using OpenZeppelin Contracts v4. For new deployments, use OpenZeppelin Contracts v5 and Upgrades.sol.
Functions

upgradeProxy(address proxy, address newImpl, bytes data) internal

Upgrades a proxy to a new implementation contract address. Only supported for UUPS or transparent proxies.

Parameters:

  • 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

upgradeProxy(address proxy, address newImpl, bytes data, address tryCaller) internal

For tests only. If broadcasting in scripts, use the --sender <ADDRESS> option with forge script instead.

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.

Parameters:

  • 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(address beacon, address newImpl) internal

Upgrades a beacon to a new implementation contract address.

Parameters:

  • beacon (address) - Address of the beacon to upgrade

  • newImpl (address) - Address of the new implementation contract to upgrade to

upgradeBeacon(address beacon, address newImpl, address tryCaller) internal

For tests only. If broadcasting in scripts, use the --sender <ADDRESS> option with forge script instead.

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.

Parameters:

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

getAdminAddress(address proxy) → address internal

Gets the admin address of a transparent proxy from its ERC1967 admin storage slot.

Parameters:

  • proxy (address) - Address of a transparent proxy

Returns

  • (address) - Admin address

getImplementationAddress(address proxy) → address internal

Gets the implementation address of a transparent or UUPS proxy from its ERC1967 implementation storage slot.

Parameters:

  • proxy (address) - Address of a transparent or UUPS proxy

Returns

  • (address) - Implementation address

getBeaconAddress(address proxy) → address internal

Gets the beacon address of a beacon proxy from its ERC1967 beacon storage slot.

Parameters:

  • proxy (address) - Address of a beacon proxy

Returns

  • (address) - Beacon address

Defender.sol

Defender 

import { Defender } from "openzeppelin-foundry-upgrades/Defender.sol";

Library for interacting with OpenZeppelin Defender from Forge scripts or tests.

Functions

deployContract(string contractName) → address internal

Deploys a contract to the current network using OpenZeppelin Defender.

Do not use this function directly if you are deploying an upgradeable contract. This function does not validate whether the contract is upgrade safe.
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.

Parameters:

  • 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

Returns

  • (address) - Address of the deployed contract

deployContract(string contractName, struct DefenderOptions defenderOpts) → address internal

Deploys a contract to the current network using OpenZeppelin Defender.

Do not use this function directly if you are deploying an upgradeable contract. This function does not validate whether the contract is upgrade safe.
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.

Parameters:

  • 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

  • defenderOpts (struct DefenderOptions) - Defender deployment options. Note that the useDefenderDeploy option is always treated as true when called from this function.

Returns

  • (address) - Address of the deployed contract

deployContract(string contractName, bytes constructorData) → address internal

Deploys a contract with constructor arguments to the current network using OpenZeppelin Defender.

Do not use this function directly if you are deploying an upgradeable contract. This function does not validate whether the contract is upgrade safe.
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.

Parameters:

  • 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

  • constructorData (bytes) - Encoded constructor arguments

Returns

  • (address) - Address of the deployed contract

deployContract(string contractName, bytes constructorData, struct DefenderOptions defenderOpts) → address internal

Deploys a contract with constructor arguments to the current network using OpenZeppelin Defender.

Do not use this function directly if you are deploying an upgradeable contract. This function does not validate whether the contract is upgrade safe.
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.

Parameters:

  • 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

  • constructorData (bytes) - Encoded constructor arguments

  • defenderOpts (struct DefenderOptions) - Defender deployment options. Note that the useDefenderDeploy option is always treated as true when called from this function.

Returns

  • (address) - Address of the deployed contract

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.

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

Parameters:

  • proxyAddress (address) - The proxy address

  • newImplementationContractName (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 (struct Options) - Common options. Note that the defender.useDefenderDeploy option is always treated as true when called from this function.

Returns

  • (struct ProposeUpgradeResponse) - Struct containing the proposal ID and URL for the upgrade proposal

getDeployApprovalProcess() → struct ApprovalProcessResponse internal

Gets the default deploy approval process configured for your deployment environment on OpenZeppelin Defender.

Returns

  • (struct ApprovalProcessResponse) - Struct with the default deploy approval process ID and the associated address, such as a Relayer, EOA, or multisig wallet address.

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.

Returns

  • (struct ApprovalProcessResponse) - Struct with the default upgrade approval process ID and the associated address, such as a multisig or governor contract address.

← Hardhat Upgrades API
Upgrades Core & CLI →