@openzeppelin/upgrades-core 1.26.1 → 1.27.0

package/src/cli/validate/build-info-file.test.ts

@@ -0,0 +1,211 @@
+import test, { ExecutionContext } from 'ava';
+
+import { promises as fs } from 'fs';
+import rimrafAsync from 'rimraf';
+import util from 'util';
+import path from 'path';
+import os from 'os';
+import { BuildInfoFile, getBuildInfoFiles } from './build-info-file';
+
+const rimraf = util.promisify(rimrafAsync);
+
+test.beforeEach(async t => {
+  process.chdir(await fs.mkdtemp(path.join(os.tmpdir(), `upgrades-core-test-${t.title.replace(/\s/g, '-')}-`)));
+});
+
+test.afterEach(async () => {
+  await rimraf(process.cwd());
+});
+
+const BUILD_INFO = {
+  input: {
+    language: 'Solidity',
+    sources: {
+      'mypath/MyContract.sol': {
+        content: 'contract MyContract {}',
+      },
+    },
+    settings: {
+      outputSelection: {
+        '*': {
+          '*': ['storageLayout'],
+        },
+      },
+    },
+  },
+  output: {
+    sources: {
+      'mypath/MyContract.sol': {
+        ast: {},
+        id: 123,
+      },
+    },
+  },
+};
+
+const BUILD_INFO_2 = {
+  input: {
+    language: 'Solidity',
+    sources: {
+      'mypath/MyContract.sol': {
+        content: 'contract MyContractModified {}',
+      },
+    },
+    settings: {
+      outputSelection: {
+        '*': {
+          '*': ['storageLayout'],
+        },
+      },
+    },
+  },
+  output: {
+    sources: {
+      'mypath/MyContract.sol': {
+        ast: {},
+        id: 456,
+      },
+    },
+  },
+};
+
+const BUILD_INFO_NO_LAYOUT = {
+  input: {
+    language: 'Solidity',
+    sources: {
+      'mypath/MyContract.sol': {
+        content: 'contract MyContract {}',
+      },
+    },
+    settings: {
+      outputSelection: {
+        '*': {
+          '*': ['abi'],
+        },
+      },
+    },
+  },
+  output: {
+    sources: {
+      'mypath/MyContract.sol': {
+        ast: {},
+        id: 123,
+      },
+    },
+  },
+};
+
+test.serial('get build info files - default hardhat', async t => {
+  await fs.mkdir('artifacts/build-info', { recursive: true });
+  await fs.mkdir('out/build-info', { recursive: true }); // should be ignored since it's empty
+
+  await fs.writeFile('artifacts/build-info/build-info.json', JSON.stringify(BUILD_INFO));
+  await fs.writeFile('artifacts/build-info/build-info-2.json', JSON.stringify(BUILD_INFO_2));
+
+  const buildInfoFiles = await getBuildInfoFiles();
+
+  assertBuildInfoFiles(t, buildInfoFiles);
+});
+
+test.serial('get build info files - default foundry', async t => {
+  await fs.mkdir('out/build-info', { recursive: true });
+  await fs.mkdir('artifacts/build-info', { recursive: true }); // should be ignored since it's empty
+
+  await fs.writeFile('out/build-info/build-info.json', JSON.stringify(BUILD_INFO));
+  await fs.writeFile('out/build-info/build-info-2.json', JSON.stringify(BUILD_INFO_2));
+
+  const buildInfoFiles = await getBuildInfoFiles();
+
+  assertBuildInfoFiles(t, buildInfoFiles);
+});
+
+test.serial('get build info files - both hardhat and foundry dirs exist', async t => {
+  await fs.mkdir('artifacts/build-info', { recursive: true });
+  await fs.writeFile('artifacts/build-info/build-info.json', JSON.stringify(BUILD_INFO));
+
+  await fs.mkdir('out/build-info', { recursive: true });
+  await fs.writeFile('out/build-info/build-info-2.json', JSON.stringify(BUILD_INFO_2));
+
+  const error = await t.throwsAsync(getBuildInfoFiles());
+  t.true(error?.message.includes('Found both Hardhat and Foundry build info directories'));
+});
+
+test.serial('get build info files - no default dirs exist', async t => {
+  const error = await t.throwsAsync(getBuildInfoFiles());
+  t.true(error?.message.includes('Could not find the default Hardhat or Foundry build info directory'));
+});
+
+test.serial('get build info files - override with custom relative path', async t => {
+  await fs.mkdir('artifacts/build-info', { recursive: true });
+  await fs.mkdir('out/build-info', { recursive: true });
+
+  await fs.mkdir('custom/build-info', { recursive: true });
+
+  await fs.writeFile('custom/build-info/build-info.json', JSON.stringify(BUILD_INFO));
+  await fs.writeFile('custom/build-info/build-info-2.json', JSON.stringify(BUILD_INFO_2));
+
+  const buildInfoFiles = await getBuildInfoFiles('custom/build-info');
+
+  assertBuildInfoFiles(t, buildInfoFiles);
+});
+
+test.serial('get build info files - override with custom absolute path', async t => {
+  await fs.mkdir('artifacts/build-info', { recursive: true });
+  await fs.mkdir('out/build-info', { recursive: true });
+
+  await fs.mkdir('custom/build-info', { recursive: true });
+
+  await fs.writeFile('custom/build-info/build-info.json', JSON.stringify(BUILD_INFO));
+  await fs.writeFile('custom/build-info/build-info-2.json', JSON.stringify(BUILD_INFO_2));
+
+  const buildInfoFiles = await getBuildInfoFiles(path.join(process.cwd(), 'custom/build-info'));
+
+  assertBuildInfoFiles(t, buildInfoFiles);
+});
+
+test.serial('invalid build info file', async t => {
+  await fs.mkdir('invalid-build-info', { recursive: true });
+
+  await fs.writeFile('invalid-build-info/invalid.json', JSON.stringify({ output: {} }));
+  const error = await t.throwsAsync(getBuildInfoFiles('invalid-build-info'));
+  t.true(error?.message.includes('must contain Solidity compiler input and output'));
+});
+
+test.serial('dir does not exist', async t => {
+  const error = await t.throwsAsync(getBuildInfoFiles('invalid-dir'));
+  t.true(error?.message.includes('does not exist'));
+});
+
+test.serial('no build info files', async t => {
+  await fs.mkdir('empty-dir', { recursive: true });
+  await fs.writeFile('empty-dir/notjson.txt', 'abc');
+
+  const error = await t.throwsAsync(getBuildInfoFiles('empty-dir'));
+  t.true(error?.message.includes('does not contain any build info files'));
+});
+
+test.serial('no storage layout', async t => {
+  await fs.mkdir('no-storage-layout', { recursive: true });
+  await fs.writeFile('no-storage-layout/build-info.json', JSON.stringify(BUILD_INFO_NO_LAYOUT));
+
+  const error = await t.throwsAsync(getBuildInfoFiles('no-storage-layout'));
+  t.true(error?.message.includes('does not contain storage layout'));
+});
+
+function assertBuildInfoFiles(t: ExecutionContext, buildInfoFiles: BuildInfoFile[]) {
+  t.is(buildInfoFiles.length, 2);
+
+  const buildInfoFile1 = buildInfoFiles.find(
+    b => b.input.sources['mypath/MyContract.sol'].content === 'contract MyContract {}',
+  );
+  const buildInfoFile2 = buildInfoFiles.find(
+    b => b.input.sources['mypath/MyContract.sol'].content === 'contract MyContractModified {}',
+  );
+
+  if (buildInfoFile1 === undefined || buildInfoFile2 === undefined) {
+    t.fail('build info files not found');
+  } else {
+    t.is(buildInfoFile1.output.sources['mypath/MyContract.sol'].id, 123);
+    t.is(buildInfoFile2.output.sources['mypath/MyContract.sol'].id, 456);
+  }
+}

package/src/cli/validate/build-info-file.ts

@@ -0,0 +1,145 @@
+import { SolcOutput, SolcInput } from '../..';
+
+import { promises as fs } from 'fs';
+import path from 'path';
+import { ValidateCommandError } from './error';
+
+const HARDHAT_COMPILE_COMMAND = 'npx hardhat clean && npx hardhat compile';
+const FOUNDRY_COMPILE_COMMAND = 'forge clean && forge build --build-info --extra-output storageLayout';
+const STORAGE_LAYOUT_HELP = `\
+If using Hardhat, include the 'storageLayout' output selection in your Hardhat config:
+module.exports = {
+  solidity: {
+    settings: {
+      outputSelection: {
+        '*': {
+          '*': ['storageLayout'],
+        },
+      },
+    },
+  },
+};
+Then recompile your contracts with '${HARDHAT_COMPILE_COMMAND}' and try again.
+
+If using Foundry, recompile your contracts with '${FOUNDRY_COMPILE_COMMAND}' and try again.`;
+
+/**
+ * A build info file containing Solidity compiler input and output JSON objects.
+ */
+export interface BuildInfoFile {
+  /**
+   * The Solidity compiler input JSON object.
+   */
+  input: SolcInput;
+
+  /**
+   * The Solidity compiler output JSON object.
+   */
+  output: SolcOutput;
+}
+
+/**
+ * Gets the build info files from the build info directory.
+ *
+ * @param buildInfoDir Build info directory, or undefined to use the default Hardhat or Foundry build-info dir.
+ * @returns The build info files with Solidity compiler input and output.
+ */
+export async function getBuildInfoFiles(buildInfoDir?: string) {
+  const dir = await findDir(buildInfoDir);
+  const jsonFiles = await getJsonFiles(dir);
+  return await readBuildInfo(jsonFiles);
+}
+
+async function findDir(buildInfoDir: string | undefined) {
+  if (buildInfoDir !== undefined && !(await hasJsonFiles(buildInfoDir))) {
+    throw new ValidateCommandError(
+      `The directory '${buildInfoDir}' does not exist or does not contain any build info files.`,
+      () =>
+        `Compile your contracts with '${HARDHAT_COMPILE_COMMAND}' or '${FOUNDRY_COMPILE_COMMAND}' and try again with the correct path to the build info directory.`,
+    );
+  }
+  const dir = buildInfoDir ?? (await findDefaultDir());
+  return dir;
+}
+
+async function findDefaultDir() {
+  const hardhatRelativeDir = path.join('artifacts', 'build-info');
+  const foundryRelativeDir = path.join('out', 'build-info');
+
+  const hardhatDir = path.join(process.cwd(), hardhatRelativeDir);
+  const foundryDir = path.join(process.cwd(), foundryRelativeDir);
+
+  const hasHardhatBuildInfo = await hasJsonFiles(hardhatDir);
+  const hasFoundryBuildInfo = await hasJsonFiles(foundryDir);
+
+  if (hasHardhatBuildInfo && hasFoundryBuildInfo) {
+    throw new ValidateCommandError(
+      `Found both Hardhat and Foundry build info directories: '${hardhatRelativeDir}' and '${foundryRelativeDir}'.`,
+      () => `Specify the build info directory that you want to validate.`,
+    );
+  } else if (hasHardhatBuildInfo) {
+    return hardhatDir;
+  } else if (hasFoundryBuildInfo) {
+    return foundryDir;
+  } else {
+    throw new ValidateCommandError(
+      `Could not find the default Hardhat or Foundry build info directory.`,
+      () =>
+        `Compile your contracts with '${HARDHAT_COMPILE_COMMAND}' or '${FOUNDRY_COMPILE_COMMAND}', or specify the build info directory that you want to validate.`,
+    );
+  }
+}
+
+async function hasJsonFiles(dir: string) {
+  return (await exists(dir)) && (await getJsonFiles(dir)).length > 0;
+}
+
+async function exists(dir: string) {
+  try {
+    await fs.access(dir);
+    return true;
+  } catch (e) {
+    return false;
+  }
+}
+
+async function getJsonFiles(dir: string): Promise<string[]> {
+  const files = await fs.readdir(dir);
+  const jsonFiles = files.filter(file => file.endsWith('.json'));
+  return jsonFiles.map(file => path.join(dir, file));
+}
+
+async function readBuildInfo(buildInfoFilePaths: string[]) {
+  const buildInfoFiles: BuildInfoFile[] = [];
+
+  for (const buildInfoFilePath of buildInfoFilePaths) {
+    const buildInfoJson = await readJSON(buildInfoFilePath);
+    if (buildInfoJson.input === undefined || buildInfoJson.output === undefined) {
+      throw new ValidateCommandError(
+        `Build info file ${buildInfoFilePath} must contain Solidity compiler input and output.`,
+      );
+    } else {
+      if (!hasStorageLayoutSetting(buildInfoJson)) {
+        throw new ValidateCommandError(
+          `Build info file ${buildInfoFilePath} does not contain storage layout.`,
+          () => STORAGE_LAYOUT_HELP,
+        );
+      }
+
+      buildInfoFiles.push({
+        input: buildInfoJson.input,
+        output: buildInfoJson.output,
+      });
+    }
+  }
+  return buildInfoFiles;
+}
+
+function hasStorageLayoutSetting(buildInfoJson: any) {
+  const o = buildInfoJson.input.settings?.outputSelection;
+  return o?.['*']?.['*'] && (o['*']['*'].includes('storageLayout') || o['*']['*'].includes('*'));
+}
+
+async function readJSON(path: string) {
+  return JSON.parse(await fs.readFile(path, 'utf8'));
+}

package/src/cli/validate/contract-report.ts

@@ -0,0 +1,130 @@
+import _chalk from 'chalk';
+import debug from '../../utils/debug';
+import {
+  getContractVersion,
+  getStorageLayout,
+  ValidationOptions,
+  withValidationDefaults,
+  Version,
+  ValidationData,
+  ValidateUpgradeSafetyOptions,
+  getErrors,
+  UpgradeableContractErrorReport,
+  getStorageUpgradeReport,
+} from '../..';
+import { Report } from '../../standalone';
+import { getUpgradeabilityAssessment } from './upgradeability-assessment';
+import { SourceContract } from './validations';
+import { LayoutCompatibilityReport } from '../../storage/report';
+import { indent } from '../../utils/indent';
+
+/**
+ * Report for an upgradeable contract.
+ * Contains the standalone report, and if there is a reference contract, the reference contract name and storage layout report.
+ */
+export class UpgradeableContractReport implements Report {
+  constructor(
+    readonly contract: string,
+    readonly reference: string | undefined,
+    readonly standaloneReport: UpgradeableContractErrorReport,
+    readonly storageLayoutReport: LayoutCompatibilityReport | undefined,
+  ) {}
+
+  get ok(): boolean {
+    return this.standaloneReport.ok && (this.storageLayoutReport === undefined || this.storageLayoutReport.ok);
+  }
+
+  /**
+   * Explain any errors in the report.
+   */
+  explain(color = true): string {
+    const result: string[] = [];
+    const chalk = new _chalk.Instance({ level: color && _chalk.supportsColor ? _chalk.supportsColor.level : 0 });
+    const icon = this.ok ? chalk.green('✔') : chalk.red('✘');
+    if (this.reference === undefined) {
+      result.push(` ${icon}  ${this.contract}`);
+    } else {
+      result.push(` ${icon}  ${this.contract} (upgrades from ${this.reference})`);
+    }
+    if (!this.standaloneReport.ok) {
+      result.push(indent(this.standaloneReport.explain(color), 6));
+    }
+    if (this.storageLayoutReport !== undefined && !this.storageLayoutReport.ok) {
+      result.push(indent(this.storageLayoutReport.explain(color), 6));
+    }
+    return result.join('\n\n');
+  }
+}
+
+/**
+ * Gets upgradeble contract reports for the upgradeable contracts in the given set of source contracts.
+ * Only contracts that are detected as upgradeable will be included in the reports.
+ * Reports include upgradeable contracts regardless of whether they pass or fail upgrade safety checks.
+ *
+ * @param sourceContracts The source contracts to check, which must include all contracts that are referenced by the given contracts. Can also include non-upgradeable contracts, which will be ignored.
+ * @param opts The validation options.
+ * @returns The upgradeable contract reports.
+ */
+export function getContractReports(sourceContracts: SourceContract[], opts: ValidateUpgradeSafetyOptions) {
+  const upgradeableContractReports: UpgradeableContractReport[] = [];
+  for (const sourceContract of sourceContracts) {
+    const upgradeabilityAssessment = getUpgradeabilityAssessment(sourceContract, sourceContracts);
+    if (upgradeabilityAssessment.upgradeable) {
+      const reference = upgradeabilityAssessment.referenceContract;
+      const uups = upgradeabilityAssessment.uups;
+      const kind = uups ? 'uups' : 'transparent';
+
+      const report = getUpgradeableContractReport(sourceContract, reference, { ...opts, kind: kind });
+      if (report !== undefined) {
+        upgradeableContractReports.push(report);
+      }
+    }
+  }
+  return upgradeableContractReports;
+}
+
+function getUpgradeableContractReport(
+  contract: SourceContract,
+  referenceContract: SourceContract | undefined,
+  opts: ValidationOptions,
+): UpgradeableContractReport | undefined {
+  let version;
+  try {
+    version = getContractVersion(contract.validationData, contract.name);
+  } catch (e: any) {
+    if (e.message.endsWith('is abstract')) {
+      // Skip abstract upgradeable contracts - they will be validated as part of their caller contracts
+      // for the functions that are in use.
+      return undefined;
+    } else {
+      throw e;
+    }
+  }
+
+  debug('Checking: ' + contract.fullyQualifiedName);
+  const standaloneReport = getStandaloneReport(contract.validationData, version, opts);
+
+  let reference: string | undefined;
+  let storageLayoutReport: LayoutCompatibilityReport | undefined;
+
+  if (opts.unsafeSkipStorageCheck !== true && referenceContract !== undefined) {
+    const layout = getStorageLayout(contract.validationData, version);
+
+    const referenceVersion = getContractVersion(referenceContract.validationData, referenceContract.name);
+    const referenceLayout = getStorageLayout(referenceContract.validationData, referenceVersion);
+
+    reference = referenceContract.fullyQualifiedName;
+    storageLayoutReport = getStorageUpgradeReport(referenceLayout, layout, withValidationDefaults(opts));
+  }
+
+  return new UpgradeableContractReport(contract.fullyQualifiedName, reference, standaloneReport, storageLayoutReport);
+}
+
+function getStandaloneReport(
+  data: ValidationData,
+  version: Version,
+  opts: ValidationOptions,
+): UpgradeableContractErrorReport {
+  const errors = getErrors(data, version, withValidationDefaults(opts));
+  return new UpgradeableContractErrorReport(errors);
+}

package/src/cli/validate/error.ts

@@ -0,0 +1,3 @@
+import { UpgradesError } from '../..';
+
+export class ValidateCommandError extends UpgradesError {}

package/src/cli/validate/project-report.test.ts

@@ -0,0 +1,124 @@
+import { getProjectReport } from './project-report';
+import { UpgradeableContractErrorReport } from '../../validate';
+
+import _test, { TestFn } from 'ava';
+import { ContractDefinition } from 'solidity-ast';
+import { findAll } from 'solidity-ast/utils';
+import { artifacts } from 'hardhat';
+
+import { SolcOutput } from '../../solc-api';
+import { astDereferencer } from '../../ast-dereferencer';
+import { extractStorageLayout } from '../../storage/extract';
+import { StorageLayoutComparator } from '../../storage/compare';
+import { StorageLayout, getDetailedLayout } from '../../storage/layout';
+import { UpgradeableContractReport } from './contract-report';
+
+interface Context {
+  extractStorageLayout: (contract: string) => ReturnType<typeof extractStorageLayout>;
+}
+
+const test = _test as TestFn<Context>;
+
+const dummyDecodeSrc = () => 'file.sol:1';
+
+test.before(async t => {
+  const buildInfo = await artifacts.getBuildInfo('contracts/test/Storage.sol:Storage1');
+  if (buildInfo === undefined) {
+    throw new Error('Build info not found');
+  }
+  const solcOutput: SolcOutput = buildInfo.output;
+  const contracts: Record<string, ContractDefinition> = {};
+  for (const def of findAll('ContractDefinition', solcOutput.sources['contracts/test/Storage.sol'].ast)) {
+    contracts[def.name] = def;
+  }
+  const deref = astDereferencer(solcOutput);
+  t.context.extractStorageLayout = name => extractStorageLayout(contracts[name], dummyDecodeSrc, deref);
+});
+
+function getLayoutReport(original: StorageLayout, updated: StorageLayout) {
+  const originalDetailed = getDetailedLayout(original);
+  const updatedDetailed = getDetailedLayout(updated);
+  const comparator = new StorageLayoutComparator();
+  return comparator.compareLayouts(originalDetailed, updatedDetailed);
+}
+
+test('get project report - ok - no upgradeable', async t => {
+  const report = getProjectReport([]);
+  t.true(report.ok);
+  t.is(report.numPassed, 0);
+  t.is(report.numTotal, 0);
+  t.is(report.explain(), 'No upgradeable contracts detected.');
+});
+
+test('get project report - ok - console', async t => {
+  const report = getProjectReport([
+    new UpgradeableContractReport(
+      'mypath/MyContract.sol:MyContract1',
+      undefined,
+      new UpgradeableContractErrorReport([]),
+      undefined,
+    ),
+  ]);
+
+  t.true(report.ok);
+  t.is(report.numPassed, 1);
+  t.is(report.numTotal, 1);
+  t.regex(report.explain(), /SUCCESS \(1 upgradeable contracts detected, 1 passed, 0 failed\)/);
+});
+
+test('get project report - errors - console', async t => {
+  const v1 = t.context.extractStorageLayout('StorageUpgrade_Replace_V1');
+  const v2 = t.context.extractStorageLayout('StorageUpgrade_Replace_V2');
+  const layoutReport = getLayoutReport(v1, v2);
+
+  const report = getProjectReport([
+    new UpgradeableContractReport(
+      'mypath/MyContract.sol:MyContract',
+      undefined,
+      new UpgradeableContractErrorReport([
+        {
+          src: 'MyContract.sol:10',
+          kind: 'missing-public-upgradeto',
+        },
+        {
+          src: 'MyContract.sol:20',
+          kind: 'delegatecall',
+        },
+      ]),
+      undefined,
+    ),
+    new UpgradeableContractReport('MyContract2', 'MyContract', new UpgradeableContractErrorReport([]), layoutReport),
+  ]);
+
+  t.false(report.ok);
+  t.is(report.numPassed, 0);
+  t.is(report.numTotal, 2);
+  t.snapshot(report.explain());
+});
+
+test('get project report - some passed', async t => {
+  const report = getProjectReport([
+    new UpgradeableContractReport(
+      'mypath/MyContract.sol:MyContract1',
+      undefined,
+      new UpgradeableContractErrorReport([
+        {
+          src: 'MyContract.sol:10',
+          kind: 'missing-public-upgradeto',
+        },
+      ]),
+      undefined,
+    ),
+    new UpgradeableContractReport(
+      'mypath/MyContract.sol:MyContract2',
+      undefined,
+      new UpgradeableContractErrorReport([]),
+      undefined,
+    ),
+  ]);
+
+  t.false(report.ok);
+  t.is(report.numPassed, 1);
+  t.is(report.numTotal, 2);
+  t.snapshot(report.explain());
+});

package/src/cli/validate/project-report.test.ts.md

@@ -0,0 +1,40 @@
+# Snapshot report for `src/cli/validate/project-report.test.ts`
+
+The actual snapshot is saved in `project-report.test.ts.snap`.
+
+Generated by [AVA](https://avajs.dev).
+
+## get project report - errors - console
+
+> Snapshot 1
+
+    ` ✘  mypath/MyContract.sol:MyContract␊
+    ␊
+          MyContract.sol:10: Implementation is missing a public \`upgradeTo(address)\` function␊
+              Inherit UUPSUpgradeable to include this function in your contract␊
+              @openzeppelin/contracts-upgradeable/proxy/utils/UUPSUpgradeable.sol␊
+              https://zpl.in/upgrades/error-008␊
+          ␊
+          MyContract.sol:20: Use of delegatecall is not allowed␊
+              https://zpl.in/upgrades/error-002␊
+    ␊
+     ✘  MyContract2 (upgrades from MyContract)␊
+    ␊
+          file.sol:1: Replaced \`x2\` with \`renamed\` of incompatible type␊
+    ␊
+    FAILED (2 upgradeable contracts detected, 0 passed, 2 failed)`
+
+## get project report - some passed
+
+> Snapshot 1
+
+    ` ✘  mypath/MyContract.sol:MyContract1␊
+    ␊
+          MyContract.sol:10: Implementation is missing a public \`upgradeTo(address)\` function␊
+              Inherit UUPSUpgradeable to include this function in your contract␊
+              @openzeppelin/contracts-upgradeable/proxy/utils/UUPSUpgradeable.sol␊
+              https://zpl.in/upgrades/error-008␊
+    ␊
+     ✔  mypath/MyContract.sol:MyContract2␊
+    ␊
+    FAILED (2 upgradeable contract detected, 1 passed, 1 failed)`