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 deploy and upgrade functions validate that the implementation contract is upgrade-safe, and will fail otherwise.

Common Options

The following options are common to some functions.

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

  • kind: ("uups" | "transparent" | "beacon") The kind of proxy to deploy, upgrade or import, or the kind of proxy that the implementation will be used with. deployProxy() and upgradeProxy() only support the values "uups" | "transparent". 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. See constructorArgs.

    • "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 or upgradeToAndCall 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.

  • redeployImplementation: ("always" | "never" | "onchange") Determines whether the implementation contract will be redeployed. Defaults to "onchange".

    • If set to "always", the implementation contract is always redeployed even if it was previously deployed with the same bytecode.

    • If set to "never", the implementation contract is never redeployed. If the implementation contract was not previously deployed or is not found in the network file, an error will be thrown.

    • If set to "onchange", the implementation contract is redeployed only if the bytecode has changed from previous deployments.

  • txOverrides: (TruffleTxOptions) A Truffle options object to override transaction parameters, such as gas and gasPrice. Applies to all transactions sent by a function with this option, even if the function sends multiple transactions.

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.

  • useDeployedImplementation: (boolean) Equivalent to setting redeployImplementation to "never".

deployProxy

async function deployProxy(
  Contract: ContractClass,
  args: unknown[] = [],
  opts?: {
    deployer?: Deployer,
    initializer?: string | false,
    unsafeAllow?: ValidationError[],
    constructorArgs?: unknown[],
    timeout?: number,
    pollingInterval?: number,
    redeployImplementation?: 'always' | 'never' | 'onchange',
    txOverrides?: TruffleTxOptions,
    kind?: 'uups' | 'transparent',
  },
): Promise<ContractInstance>

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.

Parameters:

  • Contract - a Truffle contract class to use as the implementation.

  • args - arguments for the initializer function.

  • opts - an object with options:

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

    • See Common Options.

Returns:

  • a contract instance with the proxy address and the implementation interface.

upgradeProxy

async function upgradeProxy(
  proxy: string | ContractInstance,
  Contract: ContractClass,
  opts?: {
    deployer?: Deployer,
    call?: string | { fn: string; args?: unknown[] },
    unsafeAllow?: ValidationError[],
    unsafeAllowRenames?: boolean,
    unsafeSkipStorageCheck?: boolean,
    constructorArgs?: unknown[],
    timeout?: number,
    pollingInterval?: number,
    redeployImplementation?: 'always' | 'never' | 'onchange',
    txOverrides?: TruffleTxOptions,
    kind?: 'uups' | 'transparent',
  },
): Promise<ContractInstance>

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.

Parameters:

  • proxy - the proxy address or proxy contract instance.

  • Contract - a Truffle contract class to use as the new implementation.

  • opts - an object with options:

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

Returns:

  • a contract instance with the proxy address and the new implementation interface.

deployBeacon

async function deployBeacon(
  Contract: ContractClass,
  opts?: {
    deployer?: Deployer,
    unsafeAllow?: ValidationError[],
    constructorArgs?: unknown[],
    timeout?: number,
    pollingInterval?: number,
    redeployImplementation?: 'always' | 'never' | 'onchange',
    txOverrides?: TruffleTxOptions,
  },
): Promise<ContractInstance>

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

Parameters:

  • Contract - a Truffle contract class to use as the implementation.

  • opts - an object with options:

Returns:

  • the beacon contract instance.

Since:

  • @openzeppelin/truffle-upgrades@1.12.0

upgradeBeacon

async function upgradeBeacon(
  beacon: string | ContractInstance,
  Contract: ContractClass,
  opts?: {
    deployer?: Deployer,
    unsafeAllow?: ValidationError[],
    unsafeAllowRenames?: boolean,
    unsafeSkipStorageCheck?: boolean,
    constructorArgs?: unknown[],
    timeout?: number,
    pollingInterval?: number,
    redeployImplementation?: 'always' | 'never' | 'onchange',
    txOverrides?: TruffleTxOptions,
  },
): Promise<ContractInstance>

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

Parameters:

  • beacon - the beacon address or beacon contract instance.

  • Contract - a Truffle contract class to use as the new implementation.

  • opts - an object with options:

Returns:

  • the beacon contract instance.

Since:

  • @openzeppelin/truffle-upgrades@1.12.0

deployBeaconProxy

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

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.

Parameters:

  • beacon - the beacon address or beacon contract instance.

  • attachTo - a Truffle contract class corresponding to the beacon’s current implementation contract.

  • args - arguments for the initializer function.

  • opts - an object with options:

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

Returns:

  • a contract instance with the beacon proxy address and the implementation interface.

Since:

  • @openzeppelin/truffle-upgrades@1.12.0

forceImport

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

Forces the import of an existing proxy, beacon, or implementation contract deployment to be used with this plugin. Provide the address of an existing proxy, beacon or implementation, along with the Truffle contract class of the implementation contract that was deployed.

When importing a proxy or beacon, the deployedImpl argument must be the contract class of the current implementation contract version that is being used, not the version that you are planning to upgrade to.

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 and implementation contracts.

Parameters:

  • address - the address of an existing proxy, beacon or implementation.

  • deployedImpl - the Truffle contract class of the implementation contract that was deployed.

  • opts - an object with options:

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

Returns:

  • a contract instance representing the imported proxy, beacon or implementation.

Since:

  • @openzeppelin/truffle-upgrades@1.13.0

validateImplementation

async function validateImplementation(
  Contract: ContractClass,
  opts?: {
    unsafeAllow?: ValidationError[],
    kind?: 'uups' | 'transparent' | 'beacon',
  },
): Promise<void>

Validates an implementation contract without deploying it.

Parameters:

  • Contract - the Truffle contract class of the implementation contract.

  • opts - an object with options:

Since:

  • @openzeppelin/truffle-upgrades@1.16.0

deployImplementation

async function deployImplementation(
  Contract: ContractClass,
  opts?: {
    deployer?: Deployer,
    unsafeAllow?: ValidationError[],
    constructorArgs?: unknown[],
    timeout?: number,
    pollingInterval?: number,
    redeployImplementation?: 'always' | 'never' | 'onchange',
    txOverrides?: TruffleTxOptions,
    kind?: 'uups' | 'transparent' | 'beacon',
  },
): Promise<string>

Validates and deploys an implementation contract, and returns its address.

Parameters:

  • Contract - a Truffle contract class to use as the implementation.

  • opts - an object with options:

Returns:

  • the address of the implementation contract.

Since:

  • @openzeppelin/truffle-upgrades@1.16.0

validateUpgrade

async function validateUpgrade(
  referenceAddressOrContract: string | ContractClass,
  newContract: ContractClass,
  opts?: {
    unsafeAllow?: ValidationError[],
    unsafeAllowRenames?: boolean,
    unsafeSkipStorageCheck?: boolean,
    kind?: 'uups' | 'transparent' | 'beacon',
  },
): Promise<void>

Validates a new implementation contract without deploying it and without actually upgrading to it. Compares the current implementation contract to the new implementation contract to check for storage layout compatibility errors. If referenceAddressOrContract is the current implementation address, the kind option is required.

Parameters:

  • referenceAddressOrContract - a proxy or beacon address that uses the current implementation, or an address or Truffle contract class corresponding to the current implementation.

  • newContract - the new implementation contract.

  • opts - an object with options:

Since:

  • @openzeppelin/truffle-upgrades@1.16.0

Examples:

Validate upgrading an existing proxy to a new contract (replace PROXY_ADDRESS with the address of your proxy):

const { validateUpgrade } = require('@openzeppelin/truffle-upgrades');

const BoxV2 = artifacts.require('BoxV2');
await validateUpgrade(PROXY_ADDRESS, BoxV2);

Validate upgrading between two contract implementations:

const { validateUpgrade } = require('@openzeppelin/truffle-upgrades');

const Box = artifacts.require('Box');
const BoxV2 = artifacts.require('BoxV2');
await validateUpgrade(Box, BoxV2);

prepareUpgrade

async function prepareUpgrade(
  referenceAddressOrContract: string | ContractInstance,
  Contract: ContractClass,
  opts?: {
    deployer?: Deployer,
    unsafeAllow?: ValidationError[],
    unsafeAllowRenames?: boolean,
    unsafeSkipStorageCheck?: boolean,
    constructorArgs?: unknown[],
    timeout?: number,
    pollingInterval?: number,
    redeployImplementation?: 'always' | 'never' | 'onchange',
    txOverrides?: TruffleTxOptions,
    kind?: 'uups' | 'transparent' | 'beacon',
  },
): Promise<string>

Validates and deploys a new implementation contract, and returns its address. If referenceAddressOrContract is the current implementation address, the kind option is required. Use this method to prepare an upgrade to be run from an admin address you do not control directly or cannot use from Truffle.

Parameters:

  • referenceAddressOrContract - the proxy or beacon or implementation address or contract instance.

  • Contract - the new implementation contract.

  • opts - an object with options:

Returns:

  • the address of the new implementation contract.

deployProxyAdmin

async function deployProxyAdmin(
  opts?: {
    deployer?: Deployer,
    timeout?: number,
    pollingInterval?: number,
    txOverrides?: TruffleTxOptions,
  },
): Promise<string>

Deploys a proxy admin contract and returns its address if one was not already deployed on the current network, or just returns the address of the proxy admin if one was already deployed. Note that this plugin currently only supports using one proxy admin per network.

Parameters:

Returns:

  • the address of the proxy admin.

Since:

  • @openzeppelin/truffle-upgrades@1.16.0

admin.changeProxyAdmin

async function changeProxyAdmin(
  proxyAddress: string,
  newAdmin: string,
  opts?: {
    deployer?: Deployer,
    txOverrides?: TruffleTxOptions,
  },
): Promise<void>

Changes the admin for a specific proxy.

Parameters:

  • proxyAddress - the address of the proxy to change.

  • newAdmin - the new admin address.

  • opts - an object with options:

admin.transferProxyAdminOwnership

async function transferProxyAdminOwnership(
  newAdmin: string,
  opts?: {
    deployer?: Deployer,
    txOverrides?: TruffleTxOptions,
  },

): Promise<void>

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

Parameters:

  • newAdmin - the new admin address.

  • opts - an object with options:

erc1967

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

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

Parameters:

  • proxyAddress - the proxy address.

Returns:

  • the implementation, beacon, or admin address depending on the function called.

beacon

async function beacon.getImplementationAddress(beaconAddress: string): Promise<string>;

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

Parameters:

  • beaconAddress - the beacon address.

Returns:

  • the implementation address.

Since:

  • @openzeppelin/truffle-upgrades@1.12.0

silenceWarnings

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

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

← Frequently Asked Questions
Hardhat Upgrades →