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 specifyfalse
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 toUpgrade 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>