OpenZeppelin Upgrades Core API

The core logic to check for upgrade safety as well as storage layout compatibility is implemented by the package @openzeppelin/upgrades-core.

The package exports a standalone interface that works with Solidity input and output JSON objects.

import { UpgradeableContract } from '@openzeppelin/upgrades-core';

UpgradeableContract

This class represents the implementation for an upgradeable contract and gives access to error reports.

constructor UpgradeableContract

constructor UpgradeableContract(
  name: string,
  solcInput: SolcInput,
  solcOutput: SolcOutput,
  opts?: {
    unsafeAllow?: ValidationError[],
    unsafeAllowRenames?: boolean,
    unsafeSkipStorageCheck?: boolean,
    kind?: 'uups' | 'transparent' | 'beacon',
  },
): UpgradeableContract

Creates a new instance of UpgradeableContract.

Parameters:

  • name - the name of the implementation contract as either a fully qualified name or contract name. If multiple contracts have the same name, you must use the fully qualified name e.g., contracts/Bar.sol:Bar.

  • solcInput - the Solidity input JSON object for the implementation contract.

  • solcOutput - the Solidity output JSON object for the implementation contract.

  • opts - an object with options as defined in Common Options.

In Hardhat, solcInput and solcOutput can be obtained from the Build Info file, which itself can be retrieved with hre.artifacts.getBuildInfo.

.getErrorReport

getErrorReport(): Report

Returns:

  • a report about errors pertaining to proxied contracts, e.g. the use of selfdestruct.

.getStorageUpgradeReport

getStorageUpgradeReport(
  upgradedContract: UpgradeableContract,
  opts?: {
    unsafeAllow?: ValidationError[],
    unsafeAllowRenames?: boolean,
    unsafeSkipStorageCheck?: boolean,
    kind?: 'uups' | 'transparent' | 'beacon',
  },
): Report

Compares the storage layout of an upgradeable contract with that of a proposed upgrade.

Parameters:

  • upgradedContract - another instance of UpgradeableContract representing the proposed upgrade.

  • opts - an object with options as defined in Common Options.

Returns:

  • a report about errors pertaining to proxied contracts, e.g. the use of selfdestruct, and storage layout conflicts.

Report

interface Report {
  ok: boolean;
  explain(color?: boolean): string;
}

An object that represents the results of an analysis.

Members:

  • ok - false if any errors were found, otherwise true.

  • explain() - returns a message explaining the errors in detail, if any.

← Hardhat Upgrades