OpenZeppelin Truffle Upgrades API

Both deployProxy and upgradeProxy functions will return instances of Truffle contracts, and require Truffle contract classes (retrieved via artifacts.require) as arguments. For beacons, deployBeacon and upgradeBeacon will both return an upgradable beacon instance that can be used with a beacon proxy. All functions validate that the implementation contract is upgrade-safe, and will fail otherwise.

Common Options

The following options are common to all functions.

  • deployer: Should be set to the Truffle migration deployer during migrations.

  • kind: ("uups" | "transparent") Choose between a UUPS or Transparent proxy. Defaults to Transparent. See Transparent vs UUPS. Not applicable for Beacon proxies except for forceImport.

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

  • unsafeSkipStorageCheck: (boolean) upgrades the proxy or beacon without first checking for storage layout compatibility errors. This is a dangerous option meant to be used as a last resort.

  • constructorArgs: (unknown[]) Provide arguments for the constructor of the implementation contract. Note that these are different from initializer arguments, and will be used in the deployment of the implementation contract itself. Can be used to initialize immutable variables.

Note that the options 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 UUPS or Transparent proxy given a Truffle contract class to use as implementation, and returns a contract instance with the proxy address and the implementation interface. During a migration, the proxy address will be stored in the implementation contract’s artifact, so you can use Truffle’s deployed() function to load it.

If args is set, will call an initializer function initialize with the supplied args during proxy deployment.

If you call deployProxy several times for the same implementation contract, several proxies will be deployed, but only one implementation contract will be used.

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

  • See Common Options.

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

upgradeProxy

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

  • call: enables the execution of an arbitrary function call during the upgrade process. This call is described using a function name or signature and optional arguments. It is batched into the upgrade transaction, making it safe to call migration initializing functions.

  • See Common Options.

async function upgradeProxy(
  proxyAddress: string,
  Contract: ContractClass,
  opts: {
    deployer: Deployer,
    call: string | { fn: string; args?: unknown[] },
    unsafeAllow: ValidationError[],
    unsafeSkipStorageCheck: boolean;
  } = {},
): Promise<ContractInstance>

deployBeacon

Creates an upgradable beacon given a Truffle contract class to use as implementation, and returns the beacon contract instance.

async function deployBeacon(
  Contract: ContractClass,
  opts: {
    unsafeAllow: ValidationError[],
  } = {},
): Promise<ContractInstance>

upgradeBeacon

Upgrades an upgradable beacon at a specified address to a new implementation contract, and returns the beacon contract instance.

async function upgradeBeacon(
  beaconAddress: string,
  Contract: ContractClass,
  opts: {
    unsafeAllow: ValidationError[],
    unsafeSkipStorageCheck: boolean;
  } = {},
): Promise<ContractInstance>

deployBeaconProxy

Creates a Beacon proxy given an existing beacon contract address and a Truffle contract class corresponding to the beacon’s current implementation contract, and returns a contract instance with the beacon 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

async function deployBeaconProxy(
  beaconAddress: string,
  attachTo: ContractClass,
  args: unknown[] = [],
  opts: {
    initializer?: string | false,
  } = {},
): Promise<ContractInstance>

forceImport

Forces the import of an existing proxy or beacon deployment to be used with this plugin. Provide the address of an existing proxy or beacon and the Truffle contract class of the implementation contract that was deployed. Use this function to recreate a lost network file by importing previous deployments, or to register proxies or beacons for upgrading even if they were not originally deployed by this plugin. Supported for UUPS, Transparent, and Beacon proxies, as well as beacons.

  • kind: ("uups" | "transparent" | "beacon") forces a proxy to be treated as a UUPS, Transparent, or Beacon proxy. If not provided, the proxy kind will be automatically detected.

  • See Common Options.

async function forceImport(
  proxyOrBeaconAddress: string,
  deployedImpl: ContractClass,
  opts: {
    kind?: 'uups' | 'transparent' | 'beacon',
  } = {},
): Promise<ContractInstance>

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 Truffle. Supported for UUPS, Transparent, and Beacon proxies, as well as beacons.

See Common Options.

async function prepareUpgrade(
  proxyOrBeaconAddress: string,
  Contract: ContractClass,
  opts: {
    deployer: Deployer,
    unsafeAllow: ValidationError[],
    unsafeSkipStorageCheck: boolean;
  } = {},
): Promise<string>

admin.changeProxyAdmin

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

async function changeProxyAdmin(
  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>;

beacon

This module provides a convenience function to get the implementation address from a beacon contract.

async function beacon.getImplementationAddress(beaconAddress: 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()
← Frequently Asked Questions
Hardhat Upgrades →