OpenZeppelin Foundry 升级 API - OpenZeppelin 文档

OpenZeppelin Foundry 升级 API

合约名称格式

合约名称必须以特定的格式提供，具体取决于上下文。以下是每个上下文所需的格式：

Foundry 制品格式

上下文：

• contractName 参数

• referenceContract 选项 (如果未设置 referenceBuildInfoDir 选项)

可以根据 Foundry 的 getCode cheatcode 采用以下任何一种形式：

• Solidity 文件名，例如 ContractV1.sol

• Solidity 文件名和合约名称，例如 ContractV1.sol:ContractV1

• 相对于项目根目录的制品路径，例如 out/ContractV1.sol/ContractV1.json

注解格式

上下文：

• @custom:oz-upgrades-from <reference> 注解

• referenceContract 选项 (如果设置了 referenceBuildInfoDir 选项)

可以根据 OpenZeppelin Upgrades CLI 采用以下任何一种形式：

• 合约名称，例如 ContractV1

• 完全限定的合约名称，例如 contracts/tokens/ContractV1.sol:ContractV1

如果设置了 referenceBuildInfoDir 选项，请包含构建信息目录的短名称作为前缀，从而产生以下形式之一：

• 构建信息目录的短名称和合约名称，例如 build-info-v1:ContractV1

• 构建信息目录的短名称和完全限定的合约名称，例如 build-info-v1:contracts/tokens/ContractV1.sol:ContractV1

常用选项

以下选项可以与以下某些函数一起使用。有关每个选项的详细说明，参见 Options.sol。

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";

用于从 Forge 脚本或测试中部署和管理可升级合约的库。

	需要 OpenZeppelin Contracts v5 或更高版本。

函数

• 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

使用给定合约作为实现来部署 UUPS 代理。

参数：

• contractName ( string) - 用作实现的合约的名称，例如 "MyContract.sol" 或 "MyContract.sol:MyContract" 或相对于项目根目录的制品路径

• initializerData ( bytes) - 在代理创建期间调用的初始化函数的编码调用数据，如果不需要初始化，则为空

• opts ( struct Options) - 常用选项

返回

• ( address) - 代理地址

deployUUPSProxy(string contractName, bytes initializerData) → address internal

使用给定合约作为实现来部署 UUPS 代理。

参数：

• contractName ( string) - 用作实现的合约的名称，例如 "MyContract.sol" 或 "MyContract.sol:MyContract" 或相对于项目根目录的制品路径

• initializerData ( bytes) - 在代理创建期间调用的初始化函数的编码调用数据，如果不需要初始化，则为空

返回

• ( address) - 代理地址

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

使用给定合约作为实现来部署透明代理。

参数：

• contractName ( string) - 用作实现的合约的名称，例如 "MyContract.sol" 或 "MyContract.sol:MyContract" 或相对于项目根目录的制品路径

• initialOwner ( address) - 要设置为由代理部署的 ProxyAdmin 合约所有者的地址

• initializerData ( bytes) - 在代理创建期间调用的初始化函数的编码调用数据，如果不需要初始化，则为空

• opts ( struct Options) - 常用选项

返回

• ( address) - 代理地址

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

使用给定合约作为实现来部署透明代理。

参数：

• contractName ( string) - 用作实现的合约的名称，例如 "MyContract.sol" 或 "MyContract.sol:MyContract" 或相对于项目根目录的制品路径

• initialOwner ( address) - 要设置为由代理部署的 ProxyAdmin 合约所有者的地址

• initializerData ( bytes) - 在代理创建期间调用的初始化函数的编码调用数据，如果不需要初始化，则为空

返回

• ( address) - 代理地址

upgradeProxy(address proxy, string contractName, bytes data, struct Options opts) internal

将代理升级到新的实现合约。仅支持 UUPS 或透明代理。

要求设置 referenceContract 选项，或者新的实现合约具有 @custom:oz-upgrades-from <reference> 注解。

参数：

• proxy ( address) - 要升级的代理的地址

• contractName ( string) - 要升级到的新实现合约的名称，例如 "MyContract.sol" 或 "MyContract.sol:MyContract" 或相对于项目根目录的制品路径

• data ( bytes) - 在升级过程中调用的任意函数的编码调用数据，如果升级过程中不需要调用任何函数，则为空

• opts ( struct Options) - 常用选项

upgradeProxy(address proxy, string contractName, bytes data) internal

将代理升级到新的实现合约。仅支持 UUPS 或透明代理。

要求设置 referenceContract 选项，或者新的实现合约具有 @custom:oz-upgrades-from <reference> 注解。

参数：

• proxy ( address) - 要升级的代理的地址

• contractName ( string) - 要升级到的新实现合约的名称，例如 "MyContract.sol" 或 "MyContract.sol:MyContract" 或相对于项目根目录的制品路径

• data ( bytes) - 在升级过程中调用的任意函数的编码调用数据，如果升级过程中不需要调用任何函数，则为空

upgradeProxy(address proxy, string contractName, bytes data, struct Options opts, address tryCaller) internal

	仅用于测试。如果在脚本中广播，请改用带有 forge script 的 --sender <ADDRESS> 选项。

将代理升级到新的实现合约。仅支持 UUPS 或透明代理。

要求设置 referenceContract 选项，或者新的实现合约具有 @custom:oz-upgrades-from <reference> 注解。

此函数提供了一个额外的 tryCaller 参数，用于测试使用特定调用者地址的升级。 如果在测试中遇到 OwnableUnauthorizedAccount 错误，请使用此参数。

参数：

• proxy ( address) - 要升级的代理的地址

• contractName ( string) - 要升级到的新实现合约的名称，例如 "MyContract.sol" 或 "MyContract.sol:MyContract" 或相对于项目根目录的制品路径

• data ( bytes) - 在升级过程中调用的任意函数的编码调用数据，如果升级过程中不需要调用任何函数，则为空

• opts ( struct Options) - 常用选项

• tryCaller ( address) - 用作升级函数调用者的地址。这应该是拥有代理或其 ProxyAdmin 的地址。

upgradeProxy(address proxy, string contractName, bytes data, address tryCaller) internal

	仅用于测试。如果在脚本中广播，请改用带有 forge script 的 --sender <ADDRESS> 选项。

将代理升级到新的实现合约。仅支持 UUPS 或透明代理。

要求设置 referenceContract 选项，或者新的实现合约具有 @custom:oz-upgrades-from <reference> 注解。

此函数提供了一个额外的 tryCaller 参数，用于测试使用特定调用者地址的升级。 如果在测试中遇到 OwnableUnauthorizedAccount 错误，请使用此参数。

参数：

• proxy ( address) - 要升级的代理的地址

• contractName ( string) - 要升级到的新实现合约的名称，例如 "MyContract.sol" 或 "MyContract.sol:MyContract" 或相对于项目根目录的制品路径

• data ( bytes) - 在升级过程中调用的任意函数的编码调用数据，如果升级过程中不需要调用任何函数，则为空

• tryCaller ( address) - 用作升级函数调用者的地址。这应该是拥有代理或其 ProxyAdmin 的地址。

deployBeacon(string contractName, address initialOwner, struct Options opts) → address internal

使用给定合约作为实现来部署可升级的信标。

参数：

• contractName ( string) - 用作实现的合约的名称，例如 "MyContract.sol" 或 "MyContract.sol:MyContract" 或相对于项目根目录的制品路径

• initialOwner ( address) - 要设置为由部署的 UpgradeableBeacon 合约 所有者的地址

• opts ( struct Options) - 常用选项

返回

• ( address) - 信标地址

deployBeacon(string contractName, address initialOwner) → address internal

使用给定合约作为实现来部署可升级的信标。

参数：

• contractName ( string) - 用作实现的合约的名称，例如 "MyContract.sol" 或 "MyContract.sol:MyContract" 或相对于项目根目录的制品路径

• initialOwner ( address) - 要设置为由部署的 UpgradeableBeacon 合约 所有者的地址

返回

• ( address) - 信标地址

upgradeBeacon(address beacon, string contractName, struct Options opts) internal

将信标升级到新的实现合约。

要求设置 referenceContract 选项，或者新的实现合约具有 @custom:oz-upgrades-from <reference> 注解。

参数：

• beacon ( address) - 要升级的信标的地址

• contractName ( string) - 要升级到的新实现合约的名称，例如 "MyContract.sol" 或 "MyContract.sol:MyContract" 或相对于项目根目录的制品路径

• opts ( struct Options) - 常用选项

upgradeBeacon(address beacon, string contractName) internal

将信标升级到新的实现合约。

要求设置 referenceContract 选项，或者新的实现合约具有 @custom:oz-upgrades-from <reference> 注解。

参数：

• beacon ( address) - 要升级的信标的地址

• contractName ( string) - 要升级到的新实现合约的名称，例如 "MyContract.sol" 或 "MyContract.sol:MyContract" 或相对于项目根目录的制品路径

upgradeBeacon(address beacon, string contractName, struct Options opts, address tryCaller) internal

	仅用于测试。如果在脚本中广播，请改用带有 forge script 的 --sender <ADDRESS> 选项。

将信标升级到新的实现合约。

要求设置 referenceContract 选项，或者新的实现合约具有 @custom:oz-upgrades-from <reference> 注解。

此函数提供了一个额外的 tryCaller 参数，用于测试使用特定调用者地址的升级。 如果在测试中遇到 OwnableUnauthorizedAccount 错误，请使用此参数。

参数：

• beacon ( address) - 要升级的信标的地址

• contractName ( string) - 要升级到的新实现合约的名称，例如 "MyContract.sol" 或 "MyContract.sol:MyContract" 或相对于项目根目录的制品路径

• opts ( struct Options) - 常用选项

• tryCaller ( address) - 用作升级函数调用者的地址。这应该是拥有信标的地址。

upgradeBeacon(address beacon, string contractName, address tryCaller) internal

	仅用于测试。如果在脚本中广播，请改用带有 forge script 的 --sender <ADDRESS> 选项。

将信标升级到新的实现合约。

要求设置 referenceContract 选项，或者新的实现合约具有 @custom:oz-upgrades-from <reference> 注解。

此函数提供了一个额外的 tryCaller 参数，用于测试使用特定调用者地址的升级。 如果在测试中遇到 OwnableUnauthorizedAccount 错误，请使用此参数。

参数：

• beacon ( address) - 要升级的信标的地址

• contractName ( string) - 要升级到的新实现合约的名称，例如 "MyContract.sol" 或 "MyContract.sol:MyContract" 或相对于项目根目录的制品路径

• tryCaller ( address) - 用作升级函数调用者的地址。这应该是拥有信标的地址。

deployBeaconProxy(address beacon, bytes data) → address internal

使用给定的信标和调用数据部署信标代理。

参数：

• beacon ( address) - 要使用的信标的地址

• data ( bytes) - 在代理创建期间调用的初始化函数的编码调用数据，如果不需要初始化，则为空

返回

• ( address) - 代理地址

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

使用给定的信标和调用数据部署信标代理。

参数：

• beacon ( address) - 要使用的信标的地址

• data ( bytes) - 在代理创建期间调用的初始化函数的编码调用数据，如果不需要初始化，则为空

• opts ( struct Options) - 常用选项

返回

• ( address) - 代理地址

validateImplementation(string contractName, struct Options opts) internal

验证实现合约，但不部署它。

参数：

• contractName ( string) - 要验证的合约的名称，例如 "MyContract.sol" 或 "MyContract.sol:MyContract" 或相对于项目根目录的制品路径

• opts ( struct Options) - 常用选项

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

验证并部署实现合约，并返回其地址。

参数：

• contractName ( string) - 要部署的合约的名称，例如 "MyContract.sol" 或 "MyContract.sol:MyContract" 或相对于项目根目录的制品路径

• opts ( struct Options) - 常用选项

返回

• ( address) - 实现合约的地址

validateUpgrade(string contractName, struct Options opts) internal

将新的实现合约与参考合约进行比较验证，但不部署它。

要求设置 referenceContract 选项，或者合约具有 @custom:oz-upgrades-from <reference> 注解。

参数：

• contractName ( string) - 要验证的合约的名称，例如 "MyContract.sol" 或 "MyContract.sol:MyContract" 或相对于项目根目录的制品路径

• opts ( struct Options) - 常用选项

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

将新的实现合约与参考合约进行比较验证，部署新的实现合约， 并返回其地址。

要求设置 referenceContract 选项，或者合约具有 @custom:oz-upgrades-from <reference> 注解。

使用此方法来准备从你不直接控制或无法从部署环境使用的管理地址运行的升级。

参数：

• contractName ( string) - 要部署的合约的名称，例如 "MyContract.sol" 或 "MyContract.sol:MyContract" 或相对于项目根目录的制品路径

• opts ( struct Options) - 常用选项

返回

• ( address) - 新的实现合约的地址

getAdminAddress(address proxy) → address internal

从其 ERC1967 管理存储槽中获取透明代理的管理地址。

参数：

• proxy ( address) - 透明代理的地址

返回

• ( address) - 管理地址

getImplementationAddress(address proxy) → address internal

从其 ERC1967 实现存储槽中获取透明或 UUPS 代理的实现地址。

参数：

• proxy ( address) - 透明或 UUPS 代理的地址

返回

• ( address) - 实现地址

getBeaconAddress(address proxy) → address internal

从其 ERC1967 信标存储槽中获取信标代理的信标地址。

参数：

• proxy ( address) - 信标代理的地址

返回

• ( address) - 信标地址

UnsafeUpgrades

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

用于从 Forge 测试中部署和管理可升级合约的库，无需验证。

可以与 forge coverage 一起使用。需要先实例化实现合约。 不需要 --ffi，并且每次运行前不需要进行干净的编译。

不支持 OpenZeppelin Defender 部署。

	不建议在 Forge 脚本中使用。<br>UnsafeUpgrades 不验证你的合约是否升级安全，或者新的实现是否与以前的实现兼容。<br>如果你希望运行验证，请使用 Upgrades。

	需要 OpenZeppelin Contracts v5 或更高版本。

函数

• 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

使用给定的合约地址作为实现来部署 UUPS 代理。

参数：

• impl ( address) - 用作实现的合约的地址

• initializerData ( bytes) - 在代理创建期间调用的初始化函数的编码调用数据，如果不需要初始化，则为空

返回

• ( address) - 代理地址

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

使用给定的合约地址作为实现来部署透明代理。

参数：

• impl ( address) - 用作实现的合约的地址

• initialOwner ( address) - 要设置为由代理部署的 ProxyAdmin 合约所有者的地址

• initializerData ( bytes) - 在代理创建期间调用的初始化函数的编码调用数据，如果不需要初始化，则为空

返回

• ( address) - 代理地址

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

将代理升级到新的实现合约地址。仅支持 UUPS 或透明代理。

参数：

• proxy ( address) - 要升级的代理的地址

• newImpl ( address) - 要升级到的新实现合约的地址

• data ( bytes) - 在升级过程中调用的任意函数的编码调用数据，如果升级过程中不需要调用任何函数，则为空

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

	仅用于测试。如果在脚本中广播，请改用带有 forge script 的 --sender <ADDRESS> 选项。

将代理升级到新的实现合约地址。仅支持 UUPS 或透明代理。

此函数提供了一个额外的 tryCaller 参数，用于测试使用特定调用者地址的升级。 如果在测试中遇到 OwnableUnauthorizedAccount 错误，请使用此参数。

参数：

• proxy ( address) - 要升级的代理的地址

• newImpl ( address) - 要升级到的新实现合约的地址

• data ( bytes) - 在升级过程中调用的任意函数的编码调用数据，如果升级过程中不需要调用任何函数，则为空

• tryCaller ( address) - 用作升级函数调用者的地址。这应该是拥有代理或其 ProxyAdmin 的地址。

deployBeacon(address impl, address initialOwner) → address internal

使用给定的合约地址作为实现来部署可升级的信标。

参数：

• impl ( address) - 用作实现的合约的地址

• initialOwner ( address) - 要设置为由部署的 UpgradeableBeacon 合约 所有者的地址

返回

• ( address) - 信标地址

upgradeBeacon(address beacon, address newImpl) internal

将信标升级到新的实现合约地址。

参数：

• beacon ( address) - 要升级的信标的地址

• newImpl ( address) - 要升级到的新实现合约的地址

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

	仅用于测试。如果在脚本中广播，请改用带有 forge script 的 --sender <ADDRESS> 选项。

将信标升级到新的实现合约地址。

此函数提供了一个额外的 tryCaller 参数，用于测试使用特定调用者地址的升级。 如果在测试中遇到 OwnableUnauthorizedAccount 错误，请使用此参数。

参数：

• beacon ( address) - 要升级的信标的地址

• newImpl ( address) - 要升级到的新实现合约的地址

• tryCaller ( address) - 用作升级函数调用者的地址。这应该是拥有信标的地址。

deployBeaconProxy(address beacon, bytes data) → address internal

使用给定的信标和调用数据部署信标代理。

参数：

• beacon ( address) - 要使用的信标的地址

• data ( bytes) - 在代理创建期间调用的初始化函数的编码调用数据，如果不需要初始化，则为空

返回

• ( address) - 代理地址

getAdminAddress(address proxy) → address internal

从其 ERC1967 管理存储槽中获取透明代理的管理地址。

参数：

• proxy ( address) - 透明代理的地址

返回

• ( address) - 管理地址

getImplementationAddress(address proxy) → address internal

从其 ERC1967 实现存储槽中获取透明或 UUPS 代理的实现地址。

参数：

• proxy ( address) - 透明或 UUPS 代理的地址

返回

• ( address) - 实现地址

getBeaconAddress(address proxy) → address internal

从其 ERC1967 信标存储槽中获取信标代理的信标地址。

参数：

• proxy ( address) - 信标代理的地址

返回

• ( address) - 信标地址

LegacyUpgrades.sol

Upgrades

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

用于从 Forge 脚本或测试中管理可升级合约的库。

	仅用于升级使用 OpenZeppelin Contracts v4 的现有部署。<br>对于新的部署，请使用 OpenZeppelin Contracts v5 和 Upgrades.sol。

函数

• 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

将代理升级到新的实现合约。仅支持 UUPS 或透明代理。

要求设置 referenceContract 选项，或者新的实现合约具有 @custom:oz-upgrades-from <reference> 注解。

参数：

• proxy ( address) - 要升级的代理的地址- contractName (string) - 要升级到的新实现合约的名称，例如 "MyContract.sol" 或 "MyContract.sol:MyContract" 或相对于项目根目录的 artifact 路径

• data (bytes) - 在升级过程中调用的任意函数的编码调用数据，如果升级过程中不需要调用函数，则为空

• opts (struct Options) - 常用选项

upgradeProxy(address proxy, string contractName, bytes data) internal

将代理升级到新的实现合约。仅支持 UUPS 或透明代理。

要求设置 referenceContract 选项，或新的实现合约具有 @custom:oz-upgrades-from <reference> 注解。

参数：

• proxy (address) - 要升级的代理的地址

• contractName (string) - 要升级到的新实现合约的名称，例如 "MyContract.sol" 或 "MyContract.sol:MyContract" 或相对于项目根目录的 artifact 路径

• data (bytes) - 在升级过程中调用的任意函数的编码调用数据，如果升级过程中不需要调用函数，则为空

upgradeProxy(address proxy, string contractName, bytes data, struct Options opts, address tryCaller) internal

	仅用于测试。如果在脚本中广播，请使用带有 forge script 的 --sender <ADDRESS> 选项。

将代理升级到新的实现合约。仅支持 UUPS 或透明代理。

要求设置 referenceContract 选项，或新的实现合约具有 @custom:oz-upgrades-from <reference> 注解。

此函数提供了一个额外的 tryCaller 参数，用于测试使用特定调用者地址的升级。 如果在测试中遇到 OwnableUnauthorizedAccount 错误，请使用此参数。

参数：

• proxy (address) - 要升级的代理的地址

• contractName (string) - 要升级到的新实现合约的名称，例如 "MyContract.sol" 或 "MyContract.sol:MyContract" 或相对于项目根目录的 artifact 路径

• data (bytes) - 在升级过程中调用的任意函数的编码调用数据，如果升级过程中不需要调用函数，则为空

• opts (struct Options) - 常用选项

• tryCaller (address) - 用作升级函数调用者的地址。这应该是拥有代理或其 ProxyAdmin 的地址。

upgradeProxy(address proxy, string contractName, bytes data, address tryCaller) internal

	仅用于测试。如果在脚本中广播，请使用带有 forge script 的 --sender <ADDRESS> 选项。

将代理升级到新的实现合约。仅支持 UUPS 或透明代理。

要求设置 referenceContract 选项，或新的实现合约具有 @custom:oz-upgrades-from <reference> 注解。

此函数提供了一个额外的 tryCaller 参数，用于测试使用特定调用者地址的升级。 如果在测试中遇到 OwnableUnauthorizedAccount 错误，请使用此参数。

参数：

• proxy (address) - 要升级的代理的地址

• contractName (string) - 要升级到的新实现合约的名称，例如 "MyContract.sol" 或 "MyContract.sol:MyContract" 或相对于项目根目录的 artifact 路径

• data (bytes) - 在升级过程中调用的任意函数的编码调用数据，如果升级过程中不需要调用函数，则为空

• tryCaller (address) - 用作升级函数调用者的地址。这应该是拥有代理或其 ProxyAdmin 的地址。

upgradeBeacon(address beacon, string contractName, struct Options opts) internal

将信标升级到新的实现合约。

要求设置 referenceContract 选项，或新的实现合约具有 @custom:oz-upgrades-from <reference> 注解。

参数：

• beacon (address) - 要升级的信标的地址

• contractName (string) - 要升级到的新实现合约的名称，例如 "MyContract.sol" 或 "MyContract.sol:MyContract" 或相对于项目根目录的 artifact 路径

• opts (struct Options) - 常用选项

upgradeBeacon(address beacon, string contractName) internal

将信标升级到新的实现合约。

要求设置 referenceContract 选项，或新的实现合约具有 @custom:oz-upgrades-from <reference> 注解。

参数：

• beacon (address) - 要升级的信标的地址

• contractName (string) - 要升级到的新实现合约的名称，例如 "MyContract.sol" 或 "MyContract.sol:MyContract" 或相对于项目根目录的 artifact 路径

upgradeBeacon(address beacon, string contractName, struct Options opts, address tryCaller) internal

	仅用于测试。如果在脚本中广播，请使用带有 forge script 的 --sender <ADDRESS> 选项。

将信标升级到新的实现合约。

要求设置 referenceContract 选项，或新的实现合约具有 @custom:oz-upgrades-from <reference> 注解。

此函数提供了一个额外的 tryCaller 参数，用于测试使用特定调用者地址的升级。 如果在测试中遇到 OwnableUnauthorizedAccount 错误，请使用此参数。

参数：

• beacon (address) - 要升级的信标的地址

• contractName (string) - 要升级到的新实现合约的名称，例如 "MyContract.sol" 或 "MyContract.sol:MyContract" 或相对于项目根目录的 artifact 路径

• opts (struct Options) - 常用选项

• tryCaller (address) - 用作升级函数调用者的地址。这应该是拥有信标的地址。

upgradeBeacon(address beacon, string contractName, address tryCaller) internal

	仅用于测试。如果在脚本中广播，请使用带有 forge script 的 --sender <ADDRESS> 选项。

将信标升级到新的实现合约。

要求设置 referenceContract 选项，或新的实现合约具有 @custom:oz-upgrades-from <reference> 注解。

此函数提供了一个额外的 tryCaller 参数，用于测试使用特定调用者地址的升级。 如果在测试中遇到 OwnableUnauthorizedAccount 错误，请使用此参数。

参数：

• beacon (address) - 要升级的信标的地址

• contractName (string) - 要升级到的新实现合约的名称，例如 "MyContract.sol" 或 "MyContract.sol:MyContract" 或相对于项目根目录的 artifact 路径

• tryCaller (address) - 用作升级函数调用者的地址。这应该是拥有信标的地址。

validateUpgrade(string contractName, struct Options opts) internal

将新的实现合约与参考合约进行比较验证，但不部署它。

要求设置 referenceContract 选项，或合约具有 @custom:oz-upgrades-from <reference> 注解。

参数：

• contractName (string) - 要验证的合约的名称，例如 "MyContract.sol" 或 "MyContract.sol:MyContract" 或相对于项目根目录的 artifact 路径

• opts (struct Options) - 常用选项

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

将新的实现合约与参考合约进行比较验证，部署新的实现合约， 并返回其地址。

要求设置 referenceContract 选项，或合约具有 @custom:oz-upgrades-from <reference> 注解。

使用此方法准备要从你不直接控制或无法从你的部署环境使用的管理地址运行的升级。

参数：

• contractName (string) - 要部署的合约的名称，例如 "MyContract.sol" 或 "MyContract.sol:MyContract" 或相对于项目根目录的 artifact 路径

• opts (struct Options) - 常用选项

返回值

• (address) - 新的实现合约的地址

getAdminAddress(address proxy) → address internal

从透明代理的 ERC1967 管理存储槽中获取管理地址。

参数：

• proxy (address) - 透明代理的地址

返回值

• (address) - 管理地址

getImplementationAddress(address proxy) → address internal

从透明或 UUPS 代理的 ERC1967 实现存储槽中获取实现地址。

参数：

• proxy (address) - 透明或 UUPS 代理的地址

返回值

• (address) - 实现地址

getBeaconAddress(address proxy) → address internal

从信标代理的 ERC1967 信标存储槽中获取信标地址。

参数：

• proxy (address) - 信标代理的地址

返回值

• (address) - 信标地址

UnsafeUpgrades

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

用于从 Forge 测试中管理可升级合约的库，无需验证。

可以与 forge coverage 一起使用。要求首先实例化实现合约。 不需要 --ffi，也不需要在每次运行之前进行干净的编译。

不支持 OpenZeppelin Defender 部署。

	不建议在 Forge 脚本中使用。<br>UnsafeUpgrades 不验证你的合约是否升级安全，也不验证新的实现是否与之前的实现兼容。<br>如果你希望运行验证，请使用 Upgrades。

	仅用于使用 OpenZeppelin Contracts v4 升级现有部署。<br>对于新的部署，请使用 OpenZeppelin Contracts v5 和 Upgrades.sol。

函数

• 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

将代理升级到新的实现合约地址。仅支持 UUPS 或透明代理。

参数：

• proxy (address) - 要升级的代理的地址

• newImpl (address) - 要升级到的新实现合约的地址

• data (bytes) - 在升级过程中调用的任意函数的编码调用数据，如果升级过程中不需要调用函数，则为空

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

	仅用于测试。如果在脚本中广播，请使用带有 forge script 的 --sender <ADDRESS> 选项。

将代理升级到新的实现合约地址。仅支持 UUPS 或透明代理。

此函数提供了一个额外的 tryCaller 参数，用于测试使用特定调用者地址的升级。 如果在测试中遇到 OwnableUnauthorizedAccount 错误，请使用此参数。

参数：

• proxy (address) - 要升级的代理的地址

• newImpl (address) - 要升级到的新实现合约的地址

• data (bytes) - 在升级过程中调用的任意函数的编码调用数据，如果升级过程中不需要调用函数，则为空

• tryCaller (address) - 用作升级函数调用者的地址。这应该是拥有代理或其 ProxyAdmin 的地址。

upgradeBeacon(address beacon, address newImpl) internal

将信标升级到新的实现合约地址。

参数：

• beacon (address) - 要升级的信标的地址

• newImpl (address) - 要升级到的新实现合约的地址

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

	仅用于测试。如果在脚本中广播，请使用带有 forge script 的 --sender <ADDRESS> 选项。

将信标升级到新的实现合约地址。

此函数提供了一个额外的 tryCaller 参数，用于测试使用特定调用者地址的升级。 如果在测试中遇到 OwnableUnauthorizedAccount 错误，请使用此参数。

参数：

• beacon (address) - 要升级的信标的地址

• newImpl (address) - 要升级到的新实现合约的地址

• tryCaller (address) - 用作升级函数调用者的地址。这应该是拥有信标的地址。

getAdminAddress(address proxy) → address internal

从透明代理的 ERC1967 管理存储槽中获取管理地址。

参数：

• proxy (address) - 透明代理的地址

返回值

• (address) - 管理地址

getImplementationAddress(address proxy) → address internal

从透明或 UUPS 代理的 ERC1967 实现存储槽中获取实现地址。

参数：

• proxy (address) - 透明或 UUPS 代理的地址

返回值

• (address) - 实现地址

getBeaconAddress(address proxy) → address internal

从信标代理的 ERC1967 信标存储槽中获取信标地址。

参数：

• proxy (address) - 信标代理的地址

返回值

• (address) - 信标地址

Defender.sol

Defender

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

用于从 Forge 脚本或测试中与 OpenZeppelin Defender 交互的库。

函数

• deployContract(contractName)

• deployContract(contractName, defenderOpts)

• deployContract(contractName, constructorData)

• deployContract(contractName, constructorData, defenderOpts)

• proposeUpgrade(proxyAddress, newImplementationContractName, opts)

• getDeployApprovalProcess()

• getUpgradeApprovalProcess()

deployContract(string contractName) → address internal

使用 OpenZeppelin Defender 将合约部署到当前网络。

	如果你要部署可升级合约，请勿直接使用此函数。此函数不验证合约是否升级安全。

	如果使用 EOA 或 Safe 进行部署，请在脚本运行时转到 Defender deploy 提交待处理的部署。<br>脚本会等待部署完成后再继续。

参数：

• contractName (string) - 要部署的合约的名称，例如 "MyContract.sol" 或 "MyContract.sol:MyContract" 或相对于项目根目录的 artifact 路径

返回值

• (address) - 已部署合约的地址

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

使用 OpenZeppelin Defender 将合约部署到当前网络。

	如果你要部署可升级合约，请勿直接使用此函数。此函数不验证合约是否升级安全。

	如果使用 EOA 或 Safe 进行部署，请在脚本运行时转到 Defender deploy 提交待处理的部署。<br>脚本会等待部署完成后再继续。

参数：

• contractName (string) - 要部署的合约的名称，例如 "MyContract.sol" 或 "MyContract.sol:MyContract" 或相对于项目根目录的 artifact 路径

• defenderOpts (struct DefenderOptions) - Defender 部署选项。请注意，从该函数调用时，useDefenderDeploy 选项始终被视为 true。

返回值

• (address) - 已部署合约的地址

deployContract(string contractName, bytes constructorData) → address internal

使用 OpenZeppelin Defender 将带有构造函数参数的合约部署到当前网络。

	如果你要部署可升级合约，请勿直接使用此函数。此函数不验证合约是否升级安全。

	如果使用 EOA 或 Safe 进行部署，请在脚本运行时转到 Defender deploy 提交待处理的部署。<br>脚本会等待部署完成后再继续。

参数：

• contractName (string) - 要部署的合约的名称，例如 "MyContract.sol" 或 "MyContract.sol:MyContract" 或相对于项目根目录的 artifact 路径

• constructorData (bytes) - 编码的构造函数参数

返回值

• (address) - 已部署合约的地址

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

使用 OpenZeppelin Defender 将带有构造函数参数的合约部署到当前网络。

	如果你要部署可升级合约，请勿直接使用此函数。此函数不验证合约是否升级安全。

	如果使用 EOA 或 Safe 进行部署，请在脚本运行时转到 Defender deploy 提交待处理的部署。<br>脚本会等待部署完成后再继续。

参数：

• contractName (string) - 要部署的合约的名称，例如 "MyContract.sol" 或 "MyContract.sol:MyContract" 或相对于项目根目录的 artifact 路径

• constructorData (bytes) - 编码的构造函数参数

• defenderOpts (struct DefenderOptions) - Defender 部署选项。请注意，从该函数调用时，useDefenderDeploy 选项始终被视为 true。

返回值

• (address) - 已部署合约的地址

proposeUpgrade(address proxyAddress, string newImplementationContractName, struct Options opts) → struct ProposeUpgradeResponse internal

使用 OpenZeppelin Defender 建议对可升级代理进行升级。

此函数将新的实现合约与参考合约进行比较验证，使用 Defender 部署新的实现合约， 并使用 Defender 上的升级批准流程建议升级到新的实现合约。

支持 UUPS 或透明代理。目前不支持信标代理或信标。 对于信标，请使用 Upgrades.prepareUpgrade 以及 Defender 上的交易提议来将信标升级到已部署的实现。

要求设置 referenceContract 选项，或合约具有 @custom:oz-upgrades-from <reference> 注解。

	确保参考合约与代理指向的当前实现合约相同。<br>此函数不验证参考合约是否为当前实现。

	如果使用 EOA 或 Safe 进行部署，请在脚本运行时转到 Defender deploy 提交新的实现合约的待处理部署。<br>脚本会等待部署完成后再继续。

参数：

• proxyAddress (address) - 代理地址

• newImplementationContractName (string) - 要升级到的新实现合约的名称，例如 "MyContract.sol" 或 "MyContract.sol:MyContract" 或相对于项目根目录的 artifact 路径

• opts (struct Options) - 常用选项。请注意，从该函数调用时，defender.useDefenderDeploy 选项始终被视为 true。

返回值

• (struct ProposeUpgradeResponse) - 包含升级提议的提议 ID 和 URL 的结构

getDeployApprovalProcess() → struct ApprovalProcessResponse internal

获取在 OpenZeppelin Defender 上为你的部署环境配置的默认部署批准流程。

返回值

• (struct ApprovalProcessResponse) - 具有默认部署批准流程 ID 和关联地址（例如 Relayer、EOA 或多重签名钱包地址）的结构。

getUpgradeApprovalProcess() → struct ApprovalProcessResponse internal

获取在 OpenZeppelin Defender 上为你的部署环境配置的默认升级批准流程。 例如，这对于确定可以在脚本中用作代理所有者的默认多重签名钱包非常有用。

返回值

• (struct ApprovalProcessResponse) - 具有默认升级批准流程 ID 和关联地址（例如多重签名或治理合约地址）的结构。

← Hardhat Upgrades API

Upgrades Core & CLI →

• 原文链接： docs.openzeppelin.com/up...
• 登链社区 AI 助手，为大家转译优秀英文文章，如有翻译不通的地方，还请包涵～