@openzeppelin/upgrades-core 1.9.1

package/src/storage/index.ts

@@ -0,0 +1,73 @@
+export * from './compat';
+
+import { UpgradesError } from '../error';
+import { StorageLayout, getDetailedLayout } from './layout';
+import { StorageOperation, StorageItem, StorageLayoutComparator } from './compare';
+import { LayoutCompatibilityReport } from './report';
+import { ValidationOptions, withValidationDefaults } from '../validate/overrides';
+import { logNote, logWarning } from '../utils/log';
+
+export function assertStorageUpgradeSafe(
+  original: StorageLayout,
+  updated: StorageLayout,
+  unsafeAllowCustomTypes: boolean,
+): void;
+
+export function assertStorageUpgradeSafe(
+  original: StorageLayout,
+  updated: StorageLayout,
+  opts: Required<ValidationOptions>,
+): void;
+
+export function assertStorageUpgradeSafe(
+  original: StorageLayout,
+  updated: StorageLayout,
+  opts: Required<ValidationOptions> | boolean = false,
+): void {
+  if (typeof opts === 'boolean') {
+    const unsafeAllowCustomTypes = opts;
+    opts = withValidationDefaults({ unsafeAllowCustomTypes });
+  }
+
+  const originalDetailed = getDetailedLayout(original);
+  const updatedDetailed = getDetailedLayout(updated);
+  const comparator = new StorageLayoutComparator(opts.unsafeAllowCustomTypes, opts.unsafeAllowRenames);
+  const report = comparator.compareLayouts(originalDetailed, updatedDetailed);
+
+  if (comparator.hasAllowedUncheckedCustomTypes) {
+    logWarning(`Potentially unsafe deployment`, [
+      `You are using \`unsafeAllowCustomTypes\` to force approve structs or enums with missing data.`,
+      `Make sure you have manually checked the storage layout for incompatibilities.`,
+    ]);
+  } else if (opts.unsafeAllowCustomTypes) {
+    logNote(`\`unsafeAllowCustomTypes\` is no longer necessary. Structs are enums are automatically checked.\n`);
+  }
+
+  if (!report.pass) {
+    throw new StorageUpgradeErrors(report);
+  }
+}
+
+class StorageUpgradeErrors extends UpgradesError {
+  constructor(readonly report: LayoutCompatibilityReport) {
+    super(`New storage layout is incompatible`, () => report.explain());
+  }
+}
+
+// Kept for backwards compatibility and to avoid rewriting tests
+export function getStorageUpgradeErrors(
+  original: StorageLayout,
+  updated: StorageLayout,
+  opts: ValidationOptions = {},
+): StorageOperation<StorageItem>[] {
+  try {
+    assertStorageUpgradeSafe(original, updated, withValidationDefaults(opts));
+  } catch (e) {
+    if (e instanceof StorageUpgradeErrors) {
+      return e.report.ops;
+    } else {
+      throw e;
+    }
+  }
+  return [];
+}

package/src/storage/layout.ts

@@ -0,0 +1,88 @@
+import { parseTypeId, ParsedTypeId } from '../utils/parse-type-id';
+
+// The interfaces below are generic in the way types are represented (through the parameter `Type`). When stored on
+// disk, the type is represented by a string: the type id. When loaded onto memory to run the storage layout comparisons
+// found in this module, the type id is replaced by its parsed structure together with the corresponding TypeItem, e.g.
+// the struct members if it is a struct type.
+
+export interface StorageLayout {
+  layoutVersion?: string;
+  storage: StorageItem[];
+  types: Record<string, TypeItem>;
+}
+
+export interface StorageItem<Type = string> {
+  contract: string;
+  label: string;
+  type: Type;
+  src: string;
+}
+
+export interface TypeItem<Type = string> {
+  label: string;
+  members?: TypeItemMembers<Type>;
+}
+
+export type TypeItemMembers<Type = string> = StructMember<Type>[] | EnumMember[];
+
+export interface StructMember<Type = string> {
+  label: string;
+  type: Type;
+}
+
+export type EnumMember = string;
+
+export interface ParsedTypeDetailed extends ParsedTypeId {
+  item: TypeItem<ParsedTypeDetailed>;
+  args?: ParsedTypeDetailed[];
+  rets?: ParsedTypeDetailed[];
+}
+
+type Replace<T, K extends string, V> = Omit<T, K> & Record<K, V>;
+
+export function getDetailedLayout(layout: StorageLayout): StorageItem<ParsedTypeDetailed>[] {
+  const cache: Record<string, ParsedTypeDetailed> = {};
+
+  return layout.storage.map(parseWithDetails);
+
+  function parseWithDetails<I extends { type: string }>(item: I): Replace<I, 'type', ParsedTypeDetailed> {
+    const parsed = parseTypeId(item.type);
+    const withDetails = addDetailsToParsedType(parsed);
+    return { ...item, type: withDetails };
+  }
+
+  function addDetailsToParsedType(parsed: ParsedTypeId): ParsedTypeDetailed {
+    if (parsed.id in cache) {
+      return cache[parsed.id];
+    }
+
+    const item = layout.types[parsed.id];
+    const detailed: ParsedTypeDetailed = {
+      ...parsed,
+      args: undefined,
+      rets: undefined,
+      item: {
+        ...item,
+        members: undefined,
+      },
+    };
+
+    // store in cache before recursion below
+    cache[parsed.id] = detailed;
+
+    detailed.args = parsed.args?.map(addDetailsToParsedType);
+    detailed.rets = parsed.args?.map(addDetailsToParsedType);
+    detailed.item.members =
+      item?.members && (isStructMembers(item?.members) ? item.members.map(parseWithDetails) : item?.members);
+
+    return detailed;
+  }
+}
+
+export function isEnumMembers<T>(members: TypeItemMembers<T>): members is EnumMember[] {
+  return members.length === 0 || typeof members[0] === 'string';
+}
+
+export function isStructMembers<T>(members: TypeItemMembers<T>): members is StructMember<T>[] {
+  return members.length === 0 || typeof members[0] === 'object';
+}

package/src/storage/report.test.ts

@@ -0,0 +1,95 @@
+import _test, { TestInterface } 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 './compare';
+import { StorageLayout, getDetailedLayout } from './layout';
+
+interface Context {
+  extractStorageLayout: (contract: string) => ReturnType<typeof extractStorageLayout>;
+}
+
+const test = _test as TestInterface<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 getReport(original: StorageLayout, updated: StorageLayout) {
+  const originalDetailed = getDetailedLayout(original);
+  const updatedDetailed = getDetailedLayout(updated);
+  const comparator = new StorageLayoutComparator();
+  return comparator.compareLayouts(originalDetailed, updatedDetailed);
+}
+
+test('structs', t => {
+  const v1 = t.context.extractStorageLayout('StorageUpgrade_Struct_V1');
+  const v2 = t.context.extractStorageLayout('StorageUpgrade_Struct_V2_Bad');
+  const report = getReport(v1, v2);
+  t.snapshot(report.explain());
+});
+
+test('enums', t => {
+  const v1 = t.context.extractStorageLayout('StorageUpgrade_Enum_V1');
+  const v2 = t.context.extractStorageLayout('StorageUpgrade_Enum_V2_Bad');
+  const report = getReport(v1, v2);
+  t.snapshot(report.explain());
+});
+
+test('obvious mismatch', t => {
+  const v1 = t.context.extractStorageLayout('StorageUpgrade_ObviousMismatch_V1');
+  const v2 = t.context.extractStorageLayout('StorageUpgrade_ObviousMismatch_V2_Bad');
+  const report = getReport(v1, v2);
+  t.snapshot(report.explain());
+});
+
+test('array', t => {
+  const v1 = t.context.extractStorageLayout('StorageUpgrade_Array_V1');
+  const v2 = t.context.extractStorageLayout('StorageUpgrade_Array_V2_Bad');
+  const report = getReport(v1, v2);
+  t.snapshot(report.explain());
+});
+
+test('mapping', t => {
+  const v1 = t.context.extractStorageLayout('StorageUpgrade_Mapping_V1');
+  const v2 = t.context.extractStorageLayout('StorageUpgrade_Mapping_V2_Bad');
+  const report = getReport(v1, v2);
+  t.snapshot(report.explain());
+});
+
+test('mapping enum key', t => {
+  const v1 = t.context.extractStorageLayout('StorageUpgrade_MappingEnumKey_V1');
+  const v2 = t.context.extractStorageLayout('StorageUpgrade_MappingEnumKey_V2_Bad');
+  const report = getReport(v1, v2);
+  t.snapshot(report.explain());
+});
+
+test('rename', t => {
+  const v1 = t.context.extractStorageLayout('StorageUpgrade_Rename_V1');
+  const v2 = t.context.extractStorageLayout('StorageUpgrade_Rename_V2');
+  const report = getReport(v1, v2);
+  t.snapshot(report.explain());
+});
+
+test('replace', t => {
+  const v1 = t.context.extractStorageLayout('StorageUpgrade_Replace_V1');
+  const v2 = t.context.extractStorageLayout('StorageUpgrade_Replace_V2');
+  const report = getReport(v1, v2);
+  t.snapshot(report.explain());
+});

package/src/storage/report.test.ts.md

@@ -0,0 +1,154 @@
+# Snapshot report for `src/storage/report.test.ts`
+
+The actual snapshot is saved in `report.test.ts.snap`.
+
+Generated by [AVA](https://avajs.dev).
+
+## structs
+
+> Snapshot 1
+
+    `file.sol:1: Upgraded \`data1\` to an incompatible type␊
+      - Bad upgrade from struct StorageUpgrade_Struct_V1.Struct1 to struct StorageUpgrade_Struct_V2_Bad.Struct2Minus␊
+      - In struct StorageUpgrade_Struct_V2_Bad.Struct2Minus␊
+        - Deleted \`s1\`␊
+          > Keep the variable even if unused␊
+    ␊
+    file.sol:1: Upgraded \`data2\` to an incompatible type␊
+      - Bad upgrade from struct StorageUpgrade_Struct_V1.Struct1 to struct StorageUpgrade_Struct_V2_Bad.Struct2Plus␊
+      - In struct StorageUpgrade_Struct_V2_Bad.Struct2Plus␊
+        - Added \`z\`␊
+          ␊
+    ␊
+    file.sol:1: Upgraded \`m\` to an incompatible type␊
+      - In mapping(uint256 => struct StorageUpgrade_Struct_V2_Bad.Struct2Minus)␊
+        - Bad upgrade from struct StorageUpgrade_Struct_V1.Struct1 to struct StorageUpgrade_Struct_V2_Bad.Struct2Minus␊
+      - In struct StorageUpgrade_Struct_V2_Bad.Struct2Minus␊
+        - Deleted \`s1\`␊
+          > Keep the variable even if unused␊
+    ␊
+    file.sol:1: Upgraded \`a1\` to an incompatible type␊
+      - In struct StorageUpgrade_Struct_V2_Bad.Struct2Minus[10]␊
+        - Bad upgrade from struct StorageUpgrade_Struct_V1.Struct1 to struct StorageUpgrade_Struct_V2_Bad.Struct2Minus␊
+      - In struct StorageUpgrade_Struct_V2_Bad.Struct2Minus␊
+        - Deleted \`s1\`␊
+          > Keep the variable even if unused␊
+    ␊
+    file.sol:1: Upgraded \`a2\` to an incompatible type␊
+      - In struct StorageUpgrade_Struct_V2_Bad.Struct2Plus[10]␊
+        - Bad upgrade from struct StorageUpgrade_Struct_V1.Struct1 to struct StorageUpgrade_Struct_V2_Bad.Struct2Plus␊
+      - In struct StorageUpgrade_Struct_V2_Bad.Struct2Plus␊
+        - Added \`z\`␊
+          ␊
+    ␊
+    file.sol:1: Upgraded \`data3\` to an incompatible type␊
+      - Bad upgrade from struct StorageUpgrade_Struct_V1.Struct1 to struct StorageUpgrade_Struct_V2_Bad.Struct2Changed␊
+      - In struct StorageUpgrade_Struct_V2_Bad.Struct2Changed␊
+        - Upgraded \`x\` to an incompatible type␊
+          - Bad upgrade from uint256 to string␊
+        - Upgraded \`s1\` to an incompatible type␊
+          - Bad upgrade from string to uint256␊
+        - Upgraded \`inner\` to an incompatible type␊
+          - Bad upgrade from struct StorageUpgrade_Struct_V1.StructInner to struct StorageUpgrade_Struct_V2_Bad.StructInnerPlus␊
+      - In struct StorageUpgrade_Struct_V2_Bad.StructInnerPlus␊
+        - Added \`z\`␊
+          `
+
+## enums
+
+> Snapshot 1
+
+    `file.sol:1: Upgraded \`data1\` to an incompatible type␊
+      - Bad upgrade from enum StorageUpgrade_Enum_V1.Enum1 to enum StorageUpgrade_Enum_V2_Bad.Enum2Delete␊
+      - In enum StorageUpgrade_Enum_V2_Bad.Enum2Delete␊
+        - Deleted \`B\`␊
+    ␊
+    file.sol:1: Upgraded \`data2\` to an incompatible type␊
+      - Bad upgrade from enum StorageUpgrade_Enum_V1.Enum1 to enum StorageUpgrade_Enum_V2_Bad.Enum2Replace␊
+      - In enum StorageUpgrade_Enum_V2_Bad.Enum2Replace␊
+        - Replaced \`B\` with \`X\`␊
+    ␊
+    file.sol:1: Upgraded \`data3\` to an incompatible type␊
+      - Bad upgrade from enum StorageUpgrade_Enum_V1.Enum1 to enum StorageUpgrade_Enum_V2_Bad.Enum2Insert␊
+      - In enum StorageUpgrade_Enum_V2_Bad.Enum2Insert␊
+        - Inserted \`X\`␊
+    ␊
+    file.sol:1: Upgraded \`data4\` to an incompatible type␊
+      - Bad upgrade from enum StorageUpgrade_Enum_V1.Enum1 to enum StorageUpgrade_Enum_V2_Bad.Enum2TooLarge␊
+        Different representation sizes`
+
+## obvious mismatch
+
+> Snapshot 1
+
+    `file.sol:1: Upgraded \`x1\` to an incompatible type␊
+      - Bad upgrade from uint256 to string␊
+    ␊
+    file.sol:1: Upgraded \`s1\` to an incompatible type␊
+      - Bad upgrade from struct StorageUpgrade_ObviousMismatch_V1.S to uint256␊
+    ␊
+    file.sol:1: Upgraded \`a1\` to an incompatible type␊
+      - Bad upgrade from uint256[] to mapping(uint256 => uint256)`
+
+## array
+
+> Snapshot 1
+
+    `file.sol:1: Upgraded \`x1\` to an incompatible type␊
+      - Bad array resize from 20 to 15␊
+        Size cannot decrease␊
+    ␊
+    file.sol:1: Upgraded \`x2\` to an incompatible type␊
+      - Bad array resize from 20 to 25␊
+        Size cannot increase here␊
+    ␊
+    file.sol:1: Upgraded \`x3\` to an incompatible type␊
+      - Bad upgrade from fixed to dynamic size array␊
+    ␊
+    file.sol:1: Upgraded \`x4\` to an incompatible type␊
+      - Bad upgrade from fixed to dynamic size array␊
+    ␊
+    file.sol:1: Upgraded \`m\` to an incompatible type␊
+      - In mapping(uint256 => uint256[15])␊
+        - Bad array resize from 20 to 15␊
+          Size cannot decrease`
+
+## mapping
+
+> Snapshot 1
+
+    `file.sol:1: Upgraded \`m1\` to an incompatible type␊
+      - In mapping(uint256 => uint256)␊
+        - Bad upgrade from uint256[10] to uint256␊
+    ␊
+    file.sol:1: Upgraded \`m2\` to an incompatible type␊
+      - In key of mapping(bool => uint256)␊
+        - Bad upgrade from undefined to bool`
+
+## mapping enum key
+
+> Snapshot 1
+
+    `file.sol:1: Upgraded \`m2\` to an incompatible type␊
+      - In key of mapping(enum E2_Bad => uint256)␊
+        - Bad upgrade from enum E1 to enum E2_Bad␊
+    ␊
+    file.sol:1: Upgraded \`m3\` to an incompatible type␊
+      - In key of mapping(enum E1 => uint256)␊
+        - Bad upgrade from uint8 to enum E1␊
+    ␊
+    file.sol:1: Upgraded \`m4\` to an incompatible type␊
+      - In key of mapping(uint256 => uint256)␊
+        - Bad upgrade from contract Storage1 to uint256`
+
+## rename
+
+> Snapshot 1
+
+    'file.sol:1: Renamed `x2` to `renamed`'
+
+## replace
+
+> Snapshot 1
+
+    'file.sol:1: Replaced `x2` with `renamed` of incompatible type'

package/src/storage/report.ts

@@ -0,0 +1,215 @@
+import chalk from 'chalk';
+
+import type { BasicOperation } from '../levenshtein';
+import type { ParsedTypeDetailed } from './layout';
+import type { StorageOperation, StorageItem, StorageField, TypeChange, EnumOperation } from './compare';
+import { itemize, itemizeWith } from '../utils/itemize';
+import { indent } from '../utils/indent';
+import { assert } from '../utils/assert';
+
+export class LayoutCompatibilityReport {
+  readonly pass: boolean;
+
+  constructor(readonly ops: StorageOperation<StorageItem>[]) {
+    this.pass = ops.length === 0;
+  }
+
+  explain(): string {
+    const res = [];
+
+    for (const op of this.ops) {
+      const src = 'updated' in op ? op.updated.src : op.original.contract;
+      res.push(
+        chalk.bold(src) + ':' + indent(explainStorageOperation(op, { kind: 'layout', allowAppend: true }), 2, 1),
+      );
+    }
+
+    return res.join('\n\n');
+  }
+}
+
+interface StorageOperationContext {
+  kind: 'struct' | 'layout';
+  allowAppend: boolean;
+}
+
+function explainStorageOperation(op: StorageOperation<StorageField>, ctx: StorageOperationContext): string {
+  switch (op.kind) {
+    case 'typechange': {
+      const basic = explainTypeChange(op.change);
+      const details =
+        ctx.kind === 'layout' // explain details for layout only
+          ? new Set(
+              getAllTypeChanges(op.change)
+                .map(explainTypeChangeDetails)
+                .filter((d?: string): d is string => d !== undefined),
+            )
+          : [];
+      return `Upgraded ${label(op.updated)} to an incompatible type\n` + itemize(basic, ...details);
+    }
+
+    case 'rename':
+      return `Renamed ${label(op.original)} to ${label(op.updated)}`;
+
+    case 'replace':
+      return `Replaced ${label(op.original)} with ${label(op.updated)} of incompatible type`;
+
+    default: {
+      const title = explainBasicOperation(op, t => t.label);
+      const hints = [];
+
+      switch (op.kind) {
+        case 'insert': {
+          if (ctx.kind === 'struct') {
+            if (ctx.allowAppend) {
+              hints.push('New struct members should be placed after existing ones');
+            } else {
+              hints.push('New struct members are not allowed here. Define a new struct');
+            }
+          } else {
+            hints.push('New variables should be placed after all existing inherited variables');
+          }
+          break;
+        }
+
+        case 'delete': {
+          hints.push('Keep the variable even if unused');
+          break;
+        }
+      }
+
+      return title + '\n' + itemizeWith('>', ...hints);
+    }
+  }
+}
+
+function explainTypeChange(ch: TypeChange): string {
+  switch (ch.kind) {
+    case 'obvious mismatch':
+    case 'struct members':
+    case 'enum members':
+      return `Bad upgrade ${describeTransition(ch.original, ch.updated)}`;
+
+    case 'enum resize':
+      return `Bad upgrade ${describeTransition(ch.original, ch.updated)}\nDifferent representation sizes`;
+
+    case 'mapping key':
+      return `In key of ${ch.updated.item.label}\n` + itemize(explainTypeChange(ch.inner));
+
+    case 'mapping value':
+    case 'array value':
+      return `In ${ch.updated.item.label}\n` + itemize(explainTypeChange(ch.inner));
+
+    case 'array shrink':
+    case 'array grow': {
+      assert(ch.original.tail && ch.updated.tail);
+      const originalSize = parseInt(ch.original.tail, 10);
+      const updatedSize = parseInt(ch.updated.tail, 10);
+      const note = ch.kind === 'array shrink' ? 'Size cannot decrease' : 'Size cannot increase here';
+      return `Bad array resize from ${originalSize} to ${updatedSize}\n${note}`;
+    }
+
+    case 'array dynamic': {
+      assert(ch.original.tail && ch.updated.tail);
+      const [originalSize, updatedSize] = ch.original.tail === 'dyn' ? ['dynamic', 'fixed'] : ['fixed', 'dynamic'];
+      return `Bad upgrade from ${originalSize} to ${updatedSize} size array`;
+    }
+
+    case 'missing members': {
+      const type = ch.updated.head.replace(/^t_/, ''); // t_struct, t_enum -> struct, enum
+      return `Insufficient data to compare ${type}s\nManually assess compatibility, then use option \`unsafeAllowCustomTypes: true\``;
+    }
+
+    case 'unknown':
+      return `Unknown type ${ch.updated.item.label}`;
+  }
+}
+
+function getAllTypeChanges(root: TypeChange): TypeChange[] {
+  const list = [root];
+
+  for (const ch of list) {
+    switch (ch.kind) {
+      case 'mapping value':
+      case 'array value':
+        list.push(ch.inner);
+        break;
+
+      case 'struct members': {
+        for (const op of ch.ops) {
+          if (op.kind === 'typechange') {
+            list.push(op.change);
+          }
+        }
+        break;
+      }
+
+      // We mention all other kinds explicitly to review any future new kinds
+      case 'obvious mismatch':
+      case 'enum members':
+      case 'enum resize':
+      case 'mapping key':
+      case 'array shrink':
+      case 'array grow':
+      case 'array dynamic':
+      case 'missing members':
+      case 'unknown':
+        break;
+    }
+  }
+
+  return list;
+}
+
+function explainTypeChangeDetails(ch: TypeChange): string | undefined {
+  switch (ch.kind) {
+    case 'struct members': {
+      const { allowAppend } = ch;
+      return (
+        `In ${ch.updated.item.label}\n` +
+        itemize(...ch.ops.map(op => explainStorageOperation(op, { kind: 'struct', allowAppend })))
+      );
+    }
+
+    case 'enum members':
+      return `In ${ch.updated.item.label}\n` + itemize(...ch.ops.map(explainEnumOperation));
+  }
+}
+
+function explainEnumOperation(op: EnumOperation): string {
+  switch (op.kind) {
+    case 'replace':
+      return `Replaced \`${op.original}\` with \`${op.updated}\``;
+
+    default:
+      return explainBasicOperation(op, t => t);
+  }
+}
+
+function explainBasicOperation<T>(op: BasicOperation<T>, getName: (t: T) => string): string {
+  switch (op.kind) {
+    case 'delete':
+      return `Deleted \`${getName(op.original)}\``;
+
+    case 'insert':
+      return `Inserted \`${getName(op.updated)}\``;
+
+    case 'append':
+      return `Added \`${getName(op.updated)}\``;
+  }
+}
+
+function describeTransition(original: ParsedTypeDetailed, updated: ParsedTypeDetailed): string {
+  const originalLabel = original.item.label;
+  const updatedLabel = updated.item.label;
+
+  if (originalLabel === updatedLabel) {
+    return `to ${updatedLabel}`;
+  } else {
+    return `from ${originalLabel} to ${updatedLabel}`;
+  }
+}
+
+function label(variable: { label: string }): string {
+  return '`' + variable.label + '`';
+}