@openzeppelin/upgrades-core 1.9.1

package/src/scripts/project-file.test.json

@@ -0,0 +1,25 @@
+{
+  "manifestVersion": "2.2",
+  "contracts": {
+    "Box": "Box"
+  },
+  "dependencies": {},
+  "name": "my-project",
+  "version": "1.0.0",
+  "compiler": {
+    "compilerSettings": {
+      "optimizer": {
+        "enabled": false,
+        "runs": "200"
+      }
+    },
+    "typechain": {
+      "enabled": false
+    },
+    "manager": "openzeppelin",
+    "solcVersion": "0.6.12",
+    "artifactsDir": "build/contracts",
+    "contractsDir": "contracts"
+  },
+  "telemetryOptIn": false
+}

package/src/set-proxy-kind.ts

@@ -0,0 +1,27 @@
+import { EthereumProvider } from './provider';
+import { ValidationOptions } from './validate';
+import { Manifest, DeploymentNotFound, ProxyDeployment } from './manifest';
+
+export async function setProxyKind(
+  provider: EthereumProvider,
+  proxyAddress: string,
+  opts: ValidationOptions,
+): Promise<ProxyDeployment['kind']> {
+  const manifest = await Manifest.forNetwork(provider);
+
+  const manifestDeployment = await manifest.getProxyFromAddress(proxyAddress).catch(e => {
+    if (e instanceof DeploymentNotFound) {
+      return undefined;
+    } else {
+      throw e;
+    }
+  });
+
+  if (opts.kind === undefined) {
+    opts.kind = manifestDeployment?.kind ?? 'transparent';
+  } else if (manifestDeployment && opts.kind !== manifestDeployment.kind) {
+    throw new Error(`Requested an upgrade of kind ${opts.kind} but proxy is ${manifestDeployment.kind}`);
+  }
+
+  return opts.kind;
+}

package/src/solc-api.ts

@@ -0,0 +1,42 @@
+import type { SourceUnit } from 'solidity-ast';
+
+export interface SolcOutput {
+  contracts: {
+    [file in string]: {
+      [contract in string]: {
+        evm: {
+          bytecode: SolcBytecode;
+          methodIdentifiers?: Record<string, string>;
+        };
+      };
+    };
+  };
+  sources: {
+    [file in string]: {
+      ast: SourceUnit;
+      id: number;
+    };
+  };
+}
+
+export interface SolcInput {
+  sources: {
+    [source in string]: {
+      content?: string;
+    };
+  };
+}
+
+export type SolcLinkReferences = {
+  [file in string]: {
+    [library in string]: {
+      length: number;
+      start: number;
+    }[];
+  };
+};
+
+export interface SolcBytecode {
+  linkReferences: SolcLinkReferences;
+  object: string;
+}

package/src/src-decoder.test.ts

@@ -0,0 +1,30 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+import test from 'ava';
+
+import { SolcInput, SolcOutput } from './solc-api';
+import { solcInputOutputDecoder } from './src-decoder';
+
+test('solcInputOutputDecoder', t => {
+  const solcInput: SolcInput = {
+    sources: {
+      'a.sol': { content: '\n\n' },
+      'b.sol': { content: '\n\n' },
+    },
+  };
+
+  const solcOutput: SolcOutput = {
+    contracts: {},
+    sources: {
+      'a.sol': { id: 0, ast: undefined as any },
+      'b.sol': { id: 1, ast: undefined as any },
+    },
+  };
+
+  const decodeSrc = solcInputOutputDecoder(solcInput, solcOutput);
+
+  t.is(decodeSrc({ src: '0:0:0' }), 'a.sol:1');
+  t.is(decodeSrc({ src: '1:0:0' }), 'a.sol:2');
+  t.is(decodeSrc({ src: '1:0:1' }), 'b.sol:2');
+  t.is(decodeSrc({ src: '2:0:1' }), 'b.sol:3');
+});

package/src/src-decoder.ts

@@ -0,0 +1,37 @@
+import path from 'path';
+import { SolcOutput, SolcInput } from './solc-api';
+
+export type SrcDecoder = (node: { src: string }) => string;
+
+interface Source {
+  name: string;
+  content: string;
+}
+
+export function solcInputOutputDecoder(solcInput: SolcInput, solcOutput: SolcOutput, basePath = '.'): SrcDecoder {
+  const sources: Record<number, Source> = {};
+
+  function getSource(sourceId: number): Source {
+    if (sourceId in sources) {
+      return sources[sourceId];
+    } else {
+      const sourcePath = Object.entries(solcOutput.sources).find(([, { id }]) => sourceId === id)?.[0];
+      if (sourcePath === undefined) {
+        throw new Error(`Source file not available`);
+      }
+      const content = solcInput.sources[sourcePath].content;
+      const name = path.relative(basePath, sourcePath);
+      if (content === undefined) {
+        throw new Error(`Content for ${name} not available`);
+      }
+      return (sources[sourceId] = { name, content });
+    }
+  }
+
+  return ({ src }) => {
+    const [begin, , sourceId] = src.split(':').map(Number);
+    const { name, content } = getSource(sourceId);
+    const line = content.substr(0, begin).split('\n').length;
+    return name + ':' + line;
+  };
+}

package/src/storage/compare.ts

@@ -0,0 +1,249 @@
+import { levenshtein, Operation } from '../levenshtein';
+import { ParsedTypeDetailed, StorageItem as _StorageItem } from './layout';
+import { UpgradesError } from '../error';
+import { StructMember as _StructMember, isEnumMembers, isStructMembers } from './layout';
+import { LayoutCompatibilityReport } from './report';
+import { assert } from '../utils/assert';
+import { isValueType } from '../utils/is-value-type';
+
+export type StorageItem = _StorageItem<ParsedTypeDetailed>;
+type StructMember = _StructMember<ParsedTypeDetailed>;
+
+export type StorageField = StorageItem | StructMember;
+export type StorageOperation<F extends StorageField> = Operation<F, StorageFieldChange<F>>;
+
+export type EnumOperation = Operation<string, { kind: 'replace'; original: string; updated: string }>;
+
+type StorageFieldChange<F extends StorageField> = (
+  | { kind: 'replace' | 'rename' }
+  | { kind: 'typechange'; change: TypeChange }
+) & {
+  original: F;
+  updated: F;
+};
+
+export type TypeChange = (
+  | {
+      kind:
+        | 'obvious mismatch'
+        | 'unknown'
+        | 'array grow'
+        | 'array shrink'
+        | 'array dynamic'
+        | 'enum resize'
+        | 'missing members';
+    }
+  | {
+      kind: 'mapping key' | 'mapping value' | 'array value';
+      inner: TypeChange;
+    }
+  | {
+      kind: 'enum members';
+      ops: EnumOperation[];
+    }
+  | {
+      kind: 'struct members';
+      ops: StorageOperation<StructMember>[];
+      allowAppend: boolean;
+    }
+) & {
+  original: ParsedTypeDetailed;
+  updated: ParsedTypeDetailed;
+};
+
+export class StorageLayoutComparator {
+  hasAllowedUncheckedCustomTypes = false;
+
+  // Holds a stack of type comparisons to detect recursion
+  stack = new Set<string>();
+  cache = new Map<string, TypeChange | undefined>();
+
+  constructor(readonly unsafeAllowCustomTypes = false, readonly unsafeAllowRenames = false) {}
+
+  compareLayouts(original: StorageItem[], updated: StorageItem[]): LayoutCompatibilityReport {
+    return new LayoutCompatibilityReport(this.layoutLevenshtein(original, updated, { allowAppend: true }));
+  }
+
+  private layoutLevenshtein<F extends StorageField>(
+    original: F[],
+    updated: F[],
+    { allowAppend }: { allowAppend: boolean },
+  ): StorageOperation<F>[] {
+    const ops = levenshtein(original, updated, (a, b) => this.getFieldChange(a, b));
+
+    if (allowAppend) {
+      return ops.filter(o => o.kind !== 'append');
+    } else {
+      return ops;
+    }
+  }
+
+  getFieldChange<F extends StorageField>(original: F, updated: F): StorageFieldChange<F> | undefined {
+    const nameChange = !this.unsafeAllowRenames && original.label !== updated.label;
+    const typeChange = this.getTypeChange(original.type, updated.type, { allowAppend: false });
+
+    if (typeChange && nameChange) {
+      return { kind: 'replace', original, updated };
+    } else if (nameChange) {
+      return { kind: 'rename', original, updated };
+    } else if (typeChange) {
+      return { kind: 'typechange', change: typeChange, original, updated };
+    }
+  }
+
+  getTypeChange(
+    original: ParsedTypeDetailed,
+    updated: ParsedTypeDetailed,
+    { allowAppend }: { allowAppend: boolean },
+  ): TypeChange | undefined {
+    const key = JSON.stringify({ original: original.id, updated: updated.id, allowAppend });
+
+    if (this.cache.has(key)) {
+      return this.cache.get(key);
+    }
+
+    if (this.stack.has(key)) {
+      throw new UpgradesError(`Recursive types are not supported`, () => `Recursion found in ${updated.item.label}\n`);
+    }
+
+    try {
+      this.stack.add(key);
+      const result = this.uncachedGetTypeChange(original, updated, { allowAppend });
+      this.cache.set(key, result);
+      return result;
+    } finally {
+      this.stack.delete(key);
+    }
+  }
+
+  private uncachedGetTypeChange(
+    original: ParsedTypeDetailed,
+    updated: ParsedTypeDetailed,
+    { allowAppend }: { allowAppend: boolean },
+  ): TypeChange | undefined {
+    if (original.head !== updated.head) {
+      return { kind: 'obvious mismatch', original, updated };
+    }
+
+    if (original.args === undefined || updated.args === undefined) {
+      // both should be undefined at the same time
+      assert(original.args === updated.args);
+      return undefined;
+    }
+
+    switch (original.head) {
+      case 't_contract':
+        // no storage layout errors can be introduced here since it is just an address
+        return undefined;
+
+      case 't_struct': {
+        const originalMembers = original.item.members;
+        const updatedMembers = updated.item.members;
+        if (originalMembers === undefined || updatedMembers === undefined) {
+          if (this.unsafeAllowCustomTypes) {
+            this.hasAllowedUncheckedCustomTypes = true;
+            return undefined;
+          } else {
+            return { kind: 'missing members', original, updated };
+          }
+        }
+        assert(isStructMembers(originalMembers) && isStructMembers(updatedMembers));
+        const ops = this.layoutLevenshtein(originalMembers, updatedMembers, { allowAppend });
+        if (ops.length > 0) {
+          return { kind: 'struct members', ops, original, updated, allowAppend };
+        } else {
+          return undefined;
+        }
+      }
+
+      case 't_enum': {
+        const originalMembers = original.item.members;
+        const updatedMembers = updated.item.members;
+        if (originalMembers === undefined || updatedMembers === undefined) {
+          if (this.unsafeAllowCustomTypes) {
+            this.hasAllowedUncheckedCustomTypes = true;
+            return undefined;
+          } else {
+            return { kind: 'missing members', original, updated };
+          }
+        }
+        assert(isEnumMembers(originalMembers) && isEnumMembers(updatedMembers));
+        if (enumSize(originalMembers.length) !== enumSize(updatedMembers.length)) {
+          return { kind: 'enum resize', original, updated };
+        } else {
+          const ops = levenshtein(originalMembers, updatedMembers, (a, b) =>
+            a === b ? undefined : { kind: 'replace' as const, original: a, updated: b },
+          ).filter(o => o.kind !== 'append');
+          if (ops.length > 0) {
+            return { kind: 'enum members', ops, original, updated };
+          } else {
+            return undefined;
+          }
+        }
+      }
+
+      case 't_mapping': {
+        const [originalKey, originalValue] = original.args;
+        const [updatedKey, updatedValue] = updated.args;
+
+        // validate an invariant we assume from solidity: key types are always simple value types
+        assert(isValueType(originalKey) && isValueType(updatedKey));
+
+        // network files migrated from the OZ CLI have an unknown key type
+        // we allow it to match with any other key type, carrying over the semantics of OZ CLI
+        const keyChange =
+          originalKey.head === 'unknown'
+            ? undefined
+            : this.getTypeChange(originalKey, updatedKey, { allowAppend: false });
+
+        if (keyChange) {
+          return { kind: 'mapping key', inner: keyChange, original, updated };
+        } else {
+          // mapping value types are allowed to grow
+          const inner = this.getTypeChange(originalValue, updatedValue, { allowAppend: true });
+          if (inner) {
+            return { kind: 'mapping value', inner, original, updated };
+          } else {
+            return undefined;
+          }
+        }
+      }
+
+      case 't_array': {
+        const originalLength = original.tail?.match(/^(\d+|dyn)/)?.[0];
+        const updatedLength = updated.tail?.match(/^(\d+|dyn)/)?.[0];
+        assert(originalLength !== undefined && updatedLength !== undefined);
+
+        if (originalLength === 'dyn' || updatedLength === 'dyn') {
+          if (originalLength !== updatedLength) {
+            return { kind: 'array dynamic', original, updated };
+          }
+        }
+
+        const originalLengthInt = parseInt(originalLength, 10);
+        const updatedLengthInt = parseInt(updatedLength, 10);
+
+        if (updatedLengthInt < originalLengthInt) {
+          return { kind: 'array shrink', original, updated };
+        } else if (!allowAppend && updatedLengthInt > originalLengthInt) {
+          return { kind: 'array grow', original, updated };
+        }
+
+        const inner = this.getTypeChange(original.args[0], updated.args[0], { allowAppend: false });
+
+        if (inner) {
+          return { kind: 'array value', inner, original, updated };
+        } else {
+          return undefined;
+        }
+      }
+
+      default:
+        return { kind: 'unknown', original, updated };
+    }
+  }
+}
+
+function enumSize(memberCount: number): number {
+  return Math.ceil(Math.log2(Math.max(2, memberCount)) / 8);
+}

package/src/storage/compat.ts

@@ -0,0 +1,3 @@
+export { StorageItem, StorageLayout, TypeItem, TypeItemMembers, StructMember } from './layout';
+export { extractStorageLayout } from './extract';
+export { decodeTypeIdentifier, stabilizeTypeIdentifier } from '../utils/type-id';

package/src/storage/extract.ts

@@ -0,0 +1,110 @@
+import assert from 'assert';
+import { ContractDefinition, StructDefinition, EnumDefinition, TypeDescriptions } from 'solidity-ast';
+import { isNodeType, findAll } from 'solidity-ast/utils';
+
+import { StorageLayout, TypeItem } from './layout';
+import { normalizeTypeIdentifier } from '../utils/type-id';
+import { SrcDecoder } from '../src-decoder';
+import { ASTDereferencer } from '../ast-dereferencer';
+
+const currentLayoutVersion = '1.1';
+
+export function isCurrentLayoutVersion(layout: StorageLayout): boolean {
+  return layout?.layoutVersion === currentLayoutVersion;
+}
+
+export function extractStorageLayout(
+  contractDef: ContractDefinition,
+  decodeSrc: SrcDecoder,
+  deref: ASTDereferencer,
+): StorageLayout {
+  const layout: StorageLayout = { storage: [], types: {}, layoutVersion: currentLayoutVersion };
+
+  // Note: A UserDefinedTypeName can also refer to a ContractDefinition but we won't care about those.
+  const derefUserDefinedType = deref(['StructDefinition', 'EnumDefinition']);
+
+  for (const varDecl of contractDef.nodes) {
+    if (isNodeType('VariableDeclaration', varDecl)) {
+      if (!varDecl.constant && varDecl.mutability !== 'immutable') {
+        const type = normalizeTypeIdentifier(typeDescriptions(varDecl).typeIdentifier);
+
+        layout.storage.push({
+          contract: contractDef.name,
+          label: varDecl.name,
+          type,
+          src: decodeSrc(varDecl),
+        });
+
+        assert(varDecl.typeName != null);
+
+        // We will recursively look for all types involved in this variable declaration in order to store their type
+        // information. We iterate over a Map that is indexed by typeIdentifier to ensure we visit each type only once.
+        // Note that there can be recursive types.
+        const typeNames = new Map(
+          [...findTypeNames(varDecl.typeName)].map(n => [typeDescriptions(n).typeIdentifier, n]),
+        );
+
+        for (const typeName of typeNames.values()) {
+          const { typeIdentifier, typeString: label } = typeDescriptions(typeName);
+
+          const type = normalizeTypeIdentifier(typeIdentifier);
+
+          if (type in layout.types) {
+            continue;
+          }
+
+          let members;
+
+          if ('referencedDeclaration' in typeName && !/^t_contract\b/.test(type)) {
+            const typeDef = derefUserDefinedType(typeName.referencedDeclaration);
+            members = getTypeMembers(typeDef);
+            // Recursively look for the types referenced in this definition and add them to the queue.
+            for (const typeName of findTypeNames(typeDef)) {
+              const { typeIdentifier } = typeDescriptions(typeName);
+              if (!typeNames.has(typeIdentifier)) {
+                typeNames.set(typeIdentifier, typeName);
+              }
+            }
+          }
+
+          layout.types[type] = { label, members };
+        }
+      }
+    }
+  }
+
+  return layout;
+}
+
+const findTypeNames = findAll([
+  'ArrayTypeName',
+  'ElementaryTypeName',
+  'FunctionTypeName',
+  'Mapping',
+  'UserDefinedTypeName',
+]);
+
+interface RequiredTypeDescriptions {
+  typeIdentifier: string;
+  typeString: string;
+}
+
+function typeDescriptions(x: { typeDescriptions: TypeDescriptions }): RequiredTypeDescriptions {
+  assert(typeof x.typeDescriptions.typeIdentifier === 'string');
+  assert(typeof x.typeDescriptions.typeString === 'string');
+  return x.typeDescriptions as RequiredTypeDescriptions;
+}
+
+function getTypeMembers(typeDef: StructDefinition | EnumDefinition): TypeItem['members'] {
+  if (typeDef.nodeType === 'StructDefinition') {
+    return typeDef.members.map(m => {
+      assert(typeof m.typeDescriptions.typeIdentifier === 'string');
+      return {
+        label: m.name,
+        type: normalizeTypeIdentifier(m.typeDescriptions.typeIdentifier),
+      };
+    });
+  } else {
+    return typeDef.members.map(m => m.name);
+  }
+}