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.

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.

Options are:

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

  • unsafeAllowLinkedLibraries: allows a deployment with external libraries linked to the implementation contract (required since the plugins do not support external libraries yet)

  • unsafeAllowCustomTypes: an override for a few situations where structs or enums cannot be automatically verified for safety

async function deployProxy(
  Contract: ethers.ContractFactory,
  args: unknown[] = [],
  opts: { initializer: string | false, unsafeAllowCustomTypes: boolean, unsafeAllowLinkedLibraries: boolean } = {},
): 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.

Options are:

  • unsafeAllowLinkedLibraries: allows an upgrade with external libraries linked to the implementation contract (required since the plugins do not support external libraries yet)

  • unsafeAllowCustomTypes: an override for a few situations where structs or enums cannot be automatically verified for safety

async function upgradeProxy(
  proxyAddress: string,
  Contract: ethers.ContractFactory,
  opts: { unsafeAllowCustomTypes: boolean, unsafeAllowLinkedLibraries: boolean } = {},
): 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.

Options are:

  • unsafeAllowLinkedLibraries: allows an upgrade with external libraries linked to the implementation contract (required since the plugins do not support external libraries yet)

  • unsafeAllowCustomTypes: an override for a few situations where structs or enums cannot be automatically verified for safety

async function prepareUpgrade(
  proxyAddress: string,
  Contract: ethers.ContractFactory,
  opts: { unsafeAllowCustomTypes: boolean, unsafeAllowLinkedLibraries: boolean } = {},
): 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.

Options are:

  • unsafeAllowCustomTypes: an override for a few situations where structs or enums cannot be automatically verified for safety

  • unsafeAllowLinkedLibraries: allows an upgrade with external libraries linked to the implementation contract (required since the plugins do not support external libraries yet)

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

async function proposeUpgrade(
  proxyAddress: string,
  ImplFactory: ContractFactory,
  opts: {
    unsafeAllowCustomTypes: boolean, unsafeAllowLinkedLibraries: boolean,
    title: string, description: 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>

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