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';


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.


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



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



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.