Upgrades

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

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

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.

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.

upgradeBeacon

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

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.

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.

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

Keyboard shortcuts