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.

new UpgradeableContract(name, solcInput, solcOutput, opts?);

name is 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.

opts is 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

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

contract.getErrorReport()

getStorageUpgradeReport

Compares the storage layout of an upgradeable contract with that of a proposed upgrade. Receives as an argument another instance of UpgradeableContract.

contract.getStorageUpgradeReport(upgradedContract)

Report

An object that represents the results of an analysis.

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

The field ok is false if any errors were found, and true otherwise.

The method explain() will return a message explaining the errors in detail, if any.