OpenZeppelin Hardhat Upgrades API

Both deployProxy and upgradeProxy functions will return instances of ethers.js contracts, and require ethers.js contract factories as arguments. All functions validate that the implementation contract is upgrade-safe, and will fail otherwise.

Common Options

The following options are common to all functions.

  • kind: ("uups" | "transparent") Choose between a UUPS or Transparent proxy. Defaults to Transparent. See Transparent vs UUPS.

  • unsafeAllow: (ValidationError[]) Selectively disable one or more validation errors:

    • "external-library-linking": Allows a deployment with external libraries linked to the implementation contract. (External libraries are otherwise not yet supported.)

    • "struct-definition", "enum-definition": Used to be necessary to deploy a contract with structs or enums. No longer necessary.

    • "state-variable-assignment": Allows assigning state variables in a contract even though they will be stored in the implementation.

    • "state-variable-immutable": Allows use of immutable variables, which are not unsafe

    • "constructor": Allows defining a constructor. Note that constructor arguments are not supported regardless of this option.

    • "delegatecall", "selfdestruct": Allow the use of these operations. Incorrect use of this option can put funds at risk of permanent loss. See Can I safely use delegatecall and selfdestruct?

    • "missing-public-upgradeto": Allow UUPS implementations that do not contain a public upgradeTo function. Enabling this option is likely to cause a revert due to the built-in UUPS safety mechanism.

  • unsafeAllowRenames: (boolean) Configure storage layout check to allow variable renaming.

Note that the options un unsafeAllow can also be specified in a more granular way directly in the source code if using Solidity >=0.8.2. See How can I disable some of the checks?

The following options have been deprecated.

  • unsafeAllowLinkedLibraries: Equivalent to including "external-library-linking" in unsafeAllow.

  • unsafeAllowCustomTypes: Equivalent to including "struct-definition" and "enum-definition" in unsafeAllow. No longer necessary.

deployProxy

Creates a proxy given an ethers contract factory to use as implementation, and returns a contract instance with the proxy address and the implementation interface. If args is set, will call an initializer function initialize with the supplied args during proxy deployment.

  • initializer: set a different initializer function to call, or specify false to disable initialization

  • See Common Options.

async function deployProxy(
  Contract: ethers.ContractFactory,
  args: unknown[] = [],
  opts: {
    initializer: string | false,
    unsafeAllow: ValidationError[],
    kind: 'uups' | 'transparent',
  } = {},
): Promise<ethers.Contract>

upgradeProxy

Upgrades a proxy at a specified address to a new implementation contract, and returns a contract instance with the proxy address and the new implementation interface.

See Common Options.

async function upgradeProxy(
  proxyAddress: string,
  Contract: ethers.ContractFactory,
  opts: {
    unsafeAllow: ValidationError[],
  } = {},
): Promise<ethers.Contract>

prepareUpgrade

Validates and deploys a new implementation contract, and returns its address. Use this method to prepare an upgrade to be run from an admin address you do not control directly or cannot use from Hardhat.

See Common Options.

async function prepareUpgrade(
  proxyAddress: string,
  Contract: ethers.ContractFactory,
  opts: {
    unsafeAllow: ValidationError[],
  } = {},
): Promise<string>

defender.proposeUpgrade

This method requires the @openzeppelin/hardhat-defender package, as well as configuring a Defender Team API Key.

Similar to prepareUpgrade. This method validates and deploys the new implementation contract, but also creates an upgrade proposal in Defender Admin, for review and approval by the upgrade administrators.

  • title: title of the upgrade proposal as seen in Defender Admin, defaults to Upgrade to 0x12345678 (using the first 8 digits of the new implementation address)

  • description: description of the upgrade proposal as seen in Defender Admin, defaults to the full implementation address.

  • multisig: address of the multisignature wallet contract with the rights to execute the upgrade. This is autodetected in Transparent proxies, but required for UUPS proxies (read more here). Both Gnosis Safe and Gnosis MultisigWallet multisigs are supported.

  • proxyAdmin: address of the ProxyAdmin contract that manages the proxy, if exists. This is autodetected in Transparent proxies, but required for UUPS proxies (read more here), though UUPS proxies typically do not require the usage of a ProxyAdmin.

  • See Common Options.

async function proposeUpgrade(
  proxyAddress: string,
  ImplFactory: ContractFactory,
  opts: {
    unsafeAllow?: ValidationError[],
    title?: string,
    description?: string,
    multisig?: string,
    proxyAdmin?: string,
  } = {},
): Promise<void>

admin.changeAdminForProxy

Changes the admin for a specific proxy. Receives the address of the proxy to change, and the new admin address.

async function changeAdminForProxy(
  proxyAddress: string,
  newAdmin: string,
): Promise<void>

admin.transferProxyAdminOwnership

Changes the owner of the proxy admin contract, which is the default admin for upgrade rights over all proxies. Receives the new admin address.

async function transferProxyAdminOwnership(
  newAdmin: string,
): Promise<void>

erc1967

Functions in this module provide access to the ERC1967 variables of a proxy contract.

async function erc1967.getImplementationAddress(proxyAddress: string): Promise<string>;
async function erc1967.getBeaconAddress(proxyAddress: string): Promise<string>;
async function erc1967.getAdminAddress(proxyAddress: string): Promise<string>;

silenceWarnings

Silences all subsequent warnings about the use of unsafe flags. Prints a last warning before doing so.

This function is useful for tests, but its use in production deployment scripts is discouraged. 
function silenceWarnings()
← Truffle Upgrades