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

  • unsafeAllowCustomTypes: allows a deployment where structs or enums are used in the implementation contract (required since storage compatibility validations do not handle custom types, so make sure the change you are introducing is safe)

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

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:

  • unsafeAllowCustomTypes: allows an upgrade where structs or enums are used in the implementation contract (required since storage compatibility validations do not handle custom types, so make sure the change you are introducing is safe)

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

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:

  • unsafeAllowCustomTypes: allows an upgrade where structs or enums are used in the implementation contract (required since storage compatibility validations do not handle custom types, so make sure the change you are introducing is safe)

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

async function prepareUpgrade(
  proxyAddress: string,
  Contract: ethers.ContractFactory,
  opts: { unsafeAllowCustomTypes: boolean, unsafeAllowLinkedLibraries: boolean } = {},
): Promise<string>

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>
← Truffle Upgrades