@openzeppelin/upgrades-core 1.9.1

package/src/utils/parse-type-id.ts

@@ -0,0 +1,104 @@
+import assert from 'assert';
+
+// This module parses type identifiers.
+
+export interface ParsedTypeId {
+  id: string;
+  head: string;
+  args?: ParsedTypeId[];
+  tail?: string;
+  rets?: ParsedTypeId[];
+}
+
+// The examples below illustrate the meaning of these properties.
+
+// 1) id = t_struct(MyStruct)storage
+//         └──────┘ └──────┘ └─────┘
+//           head    args[0]   tail
+//    rets = undefined
+
+// 2) id = t_function_internal_nonpayable(t_uint256,t_uint256)returns(t_address)
+//         └────────────────────────────┘ └───────┘ └───────┘         └───────┘
+//                      head               args[0]   args[1]           rets[0]
+//    tail = undefined
+
+// 3) id = t_uint256
+//         └───────┘
+//           head
+//    args = undefined
+//    tail = undefined
+//    rets = undefined
+
+export function parseTypeId(id: string): ParsedTypeId {
+  const matcher = new StatefulGlobalMatcher(id);
+
+  function parseList(): ParsedTypeId[] {
+    const args = [];
+
+    let i = matcher.index;
+    let delim;
+
+    while ((delim = matcher.match(/[(),]/))) {
+      if (delim[0] === '(') {
+        let depth = 1;
+        while (depth > 0) {
+          const paren = matcher.match(/[()]/)?.[0];
+          if (paren === '(') {
+            depth += 1;
+          } else if (paren === ')') {
+            depth -= 1;
+          } else {
+            throw new Error(`Malformed type id ${id}`);
+          }
+        }
+      } else {
+        const subtype = id.slice(i, delim.index);
+        if (subtype) {
+          args.push(parseTypeId(subtype));
+        }
+        i = delim.index + 1;
+        if (delim[0] === ')') {
+          break;
+        }
+      }
+    }
+
+    return args;
+  }
+
+  const openArgs = matcher.match(/\(/);
+  const head = id.slice(0, openArgs?.index);
+  let args, tail, rets;
+
+  if (openArgs) {
+    args = parseList();
+
+    const startTail = matcher.index;
+    const openRet = matcher.match(/\(/);
+
+    if (!openRet) {
+      tail = id.slice(startTail) || undefined;
+    } else {
+      assert(id.slice(startTail, openRet.index) === 'returns', `Malformed type id ${id}`);
+      rets = parseList();
+    }
+  }
+
+  return { id, head, args, tail, rets };
+}
+
+class StatefulGlobalMatcher {
+  index = 0;
+
+  constructor(private readonly text: string) {}
+
+  match(re: RegExp | string): RegExpExecArray | null {
+    const gre = new RegExp(re, 'g');
+    gre.lastIndex = this.index;
+    const match = gre.exec(this.text);
+    if (match !== null) {
+      this.index = gre.lastIndex;
+    }
+    return match;
+  }
+}

package/src/utils/pick.ts

@@ -0,0 +1,7 @@
+export function pick<T, K extends keyof T>(obj: T, keys: K[]): Pick<T, K> {
+  const res: Partial<Pick<T, K>> = {};
+  for (const k of keys) {
+    res[k] = obj[k];
+  }
+  return res as Pick<T, K>;
+}

package/src/utils/type-id.ts

@@ -0,0 +1,57 @@
+import assert from 'assert';
+
+// Type Identifiers in the AST are for some reason encoded so that they don't
+// contain parentheses or commas, which have been substituted as follows:
+//    (  ->  $_
+//    )  ->  _$
+//    ,  ->  _$_
+// This is particularly hard to decode because it is not a prefix-free code.
+// Thus, the following regex has to perform a lookahead to make sure it gets
+// the substitution right.
+export function decodeTypeIdentifier(typeIdentifier: string): string {
+  return typeIdentifier.replace(/(\$_|_\$_|_\$)(?=(\$_|_\$_|_\$)*([^_$]|$))/g, m => {
+    switch (m) {
+      case '$_':
+        return '(';
+      case '_$':
+        return ')';
+      case '_$_':
+        return ',';
+      default:
+        throw new Error('Unreachable');
+    }
+  });
+}
+
+// Some Type Identifiers contain a _storage_ptr suffix, but the _ptr part
+// appears in some places and not others. We remove it to get consistent type
+// ids from the different places in the AST.
+export function normalizeTypeIdentifier(typeIdentifier: string): string {
+  return decodeTypeIdentifier(typeIdentifier).replace(/_storage_ptr\b/g, '_storage');
+}
+
+// Type Identifiers contain AST id numbers, which makes them sensitive to
+// unrelated changes in the source code. This function stabilizes a type
+// identifier by removing all AST ids.
+export function stabilizeTypeIdentifier(typeIdentifier: string): string {
+  let decoded = decodeTypeIdentifier(typeIdentifier);
+  const re = /(t_struct|t_enum|t_contract)\(/g;
+  let match;
+  while ((match = re.exec(decoded))) {
+    let i;
+    let d = 1;
+    for (i = match.index + match[0].length; d !== 0; i++) {
+      assert(i < decoded.length, 'index out of bounds');
+      const c = decoded[i];
+      if (c === '(') {
+        d += 1;
+      } else if (c === ')') {
+        d -= 1;
+      }
+    }
+    const re2 = /\d+_?/y;
+    re2.lastIndex = i;
+    decoded = decoded.replace(re2, '');
+  }
+  return decoded;
+}

package/src/validate/compat.ts

@@ -0,0 +1,9 @@
+// Legacy interface for backwards compatibility
+
+import { ContractValidation, ValidationRunData } from './run';
+
+export type RunValidation = ValidationRunData;
+export type ValidationLog = RunValidation[];
+export type Validation = RunValidation;
+
+export type ValidationResult = ContractValidation;

package/src/validate/data.ts

@@ -0,0 +1,55 @@
+import versions from 'compare-versions';
+
+import { ValidationRunData } from './run';
+
+type ValidationDataV1 = ValidationRunData;
+
+type ValidationDataV2 = ValidationRunData[];
+
+const currentMajor = '3';
+const currentVersion = '3.2';
+
+interface ValidationDataV3 {
+  version: '3' | '3.1' | '3.2';
+  log: ValidationRunData[];
+}
+
+export type ValidationDataCurrent = ValidationDataV3;
+
+export type ValidationData = ValidationDataV1 | ValidationDataV2 | ValidationDataV3;
+
+export function normalizeValidationData(data: ValidationData): ValidationDataCurrent {
+  if (isCurrentValidationData(data, false)) {
+    return data;
+  } else if (Array.isArray(data)) {
+    return { version: currentVersion, log: data };
+  } else {
+    return { version: currentVersion, log: [data] };
+  }
+}
+
+export function isCurrentValidationData(data: ValidationData, exact = true): data is ValidationDataCurrent {
+  if (Array.isArray(data)) {
+    return false;
+  } else if (!('version' in data)) {
+    return false;
+  } else if (typeof data.version === 'string' && versions.validate(data.version)) {
+    if (exact) {
+      return data.version === currentVersion;
+    } else {
+      return versions.compare(data.version, `${currentMajor}.*`, '=');
+    }
+  } else {
+    throw new Error('Unknown version or malformed validation data');
+  }
+}
+
+export function concatRunData(
+  newRunData: ValidationRunData,
+  previousData?: ValidationDataCurrent,
+): ValidationDataCurrent {
+  return {
+    version: currentVersion,
+    log: [newRunData].concat(previousData?.log ?? []),
+  };
+}

package/src/validate/error.ts

@@ -0,0 +1,75 @@
+import chalk from 'chalk';
+
+import { ValidationError } from './run';
+import { UpgradesError, ErrorDescriptions } from '../error';
+
+export class ValidationErrors extends UpgradesError {
+  constructor(contractName: string, readonly errors: ValidationError[]) {
+    super(`Contract \`${contractName}\` is not upgrade safe`, () => {
+      return errors.map(describeError).join('\n\n');
+    });
+  }
+}
+
+const errorInfo: ErrorDescriptions<ValidationError> = {
+  constructor: {
+    msg: e => `Contract \`${e.contract}\` has a constructor`,
+    hint: () => 'Define an initializer instead',
+    link: 'https://zpl.in/upgrades/error-001',
+  },
+  delegatecall: {
+    msg: () => `Use of delegatecall is not allowed`,
+    link: 'https://zpl.in/upgrades/error-002',
+  },
+  selfdestruct: {
+    msg: () => `Use of selfdestruct is not allowed`,
+    link: 'https://zpl.in/upgrades/error-003',
+  },
+  'state-variable-assignment': {
+    msg: e => `Variable \`${e.name}\` is assigned an initial value`,
+    hint: () => 'Move the assignment to the initializer',
+    link: 'https://zpl.in/upgrades/error-004',
+  },
+  'state-variable-immutable': {
+    msg: e => `Variable \`${e.name}\` is immutable`,
+    hint: () => `Use a constant or mutable variable instead`,
+    link: 'https://zpl.in/upgrades/error-005',
+  },
+  'external-library-linking': {
+    msg: e => `Linking external libraries like \`${e.name}\` is not yet supported`,
+    hint: () =>
+      `Use libraries with internal functions only, or skip this check with the \`unsafeAllowLinkedLibraries\` flag \n` +
+      `    if you have manually checked that the libraries are upgrade safe`,
+    link: 'https://zpl.in/upgrades/error-006',
+  },
+  'struct-definition': {
+    msg: e => `Structs like \`${e.name}\` are supported in the latest version of the plugin`,
+    hint: () => `Update your dependency and run again`,
+  },
+  'enum-definition': {
+    msg: e => `Enums like \`${e.name}\` are supported in the latest version of the plugin`,
+    hint: () => `Update your dependency and run again`,
+  },
+  'missing-public-upgradeto': {
+    msg: () => `Implementation is missing a public \`upgradeTo(address)\` function`,
+    hint: () =>
+      `Inherit UUPSUpgradeable to include this function in your contract\n` +
+      `    @openzeppelin/contracts-upgradeable/proxy/utils/UUPSUpgradeable.sol`,
+    link: 'https://zpl.in/upgrades/error-008',
+  },
+};
+
+function describeError(e: ValidationError): string {
+  const info = errorInfo[e.kind];
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const log = [chalk.bold(e.src) + ': ' + info.msg(e as any)];
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const hint = info.hint?.(e as any);
+  if (hint) {
+    log.push(hint);
+  }
+  if (info.link) {
+    log.push(chalk.dim(info.link));
+  }
+  return log.join('\n    ');
+}

package/src/validate/index.ts

@@ -0,0 +1,17 @@
+export { validate, ValidationRunData, ContractValidation } from './run';
+export { ValidationOptions, withValidationDefaults } from './overrides';
+export { ValidationErrors } from './error';
+export { RunValidation, ValidationLog, Validation, ValidationResult } from './compat';
+export { ValidationData, ValidationDataCurrent, isCurrentValidationData, concatRunData } from './data';
+export {
+  getContractVersion,
+  getContractNameAndRunValidation,
+  getStorageLayout,
+  assertUpgradeSafe,
+  getUnlinkedBytecode,
+  getErrors,
+  isUpgradeSafe,
+} from './query';
+
+// Backwards compatibility
+export { silenceWarnings } from '../utils/log';

package/src/validate/overrides.ts

@@ -0,0 +1,93 @@
+import { ValidationError } from './run';
+import { ProxyDeployment } from '../manifest';
+import { logWarning } from '../utils/log';
+
+// Backwards compatibility
+export { silenceWarnings } from '../utils/log';
+
+export interface ValidationOptions {
+  unsafeAllowCustomTypes?: boolean;
+  unsafeAllowLinkedLibraries?: boolean;
+  unsafeAllowRenames?: boolean;
+  unsafeAllow?: ValidationError['kind'][];
+  kind?: ProxyDeployment['kind'];
+}
+
+export const ValidationErrorUnsafeMessages: Record<ValidationError['kind'], string[]> = {
+  'state-variable-assignment': [
+    `You are using the \`unsafeAllow.state-variable-assignment\` flag.`,
+    `The value will be stored in the implementation and not the proxy.`,
+  ],
+  'state-variable-immutable': [`You are using the \`unsafeAllow.state-variable-immutable\` flag.`],
+  'external-library-linking': [
+    `You are using the \`unsafeAllow.external-library-linking\` flag to include external libraries.`,
+    `Make sure you have manually checked that the linked libraries are upgrade safe.`,
+  ],
+  'struct-definition': [
+    `You are using the \`unsafeAllow.struct-definition\` flag to skip storage checks for structs.`,
+    `Make sure you have manually checked the storage layout for incompatibilities.`,
+  ],
+  'enum-definition': [
+    `You are using the \`unsafeAllow.enum-definition\` flag to skip storage checks for enums.`,
+    `Make sure you have manually checked the storage layout for incompatibilities.`,
+  ],
+  constructor: [`You are using the \`unsafeAllow.constructor\` flag.`],
+  delegatecall: [`You are using the \`unsafeAllow.delegatecall\` flag.`],
+  selfdestruct: [`You are using the \`unsafeAllow.selfdestruct\` flag.`],
+  'missing-public-upgradeto': [
+    `You are using the \`unsafeAllow.missing-public-upgradeto\` flag with uups proxy.`,
+    `Not having a public upgradeTo function in your implementation can break upgradeability.`,
+    `Some implementation might check that onchain, and cause the upgrade to revert.`,
+  ],
+};
+
+export function withValidationDefaults(opts: ValidationOptions): Required<ValidationOptions> {
+  const unsafeAllow = opts.unsafeAllow ?? [];
+  const unsafeAllowCustomTypes =
+    opts.unsafeAllowCustomTypes ??
+    (unsafeAllow.includes('struct-definition') && unsafeAllow.includes('enum-definition'));
+  const unsafeAllowLinkedLibraries =
+    opts.unsafeAllowLinkedLibraries ?? unsafeAllow.includes('external-library-linking');
+
+  if (unsafeAllowCustomTypes) {
+    unsafeAllow.push('enum-definition', 'struct-definition');
+  }
+  if (unsafeAllowLinkedLibraries) {
+    unsafeAllow.push('external-library-linking');
+  }
+  const kind = opts.kind ?? 'transparent';
+
+  const unsafeAllowRenames = opts.unsafeAllowRenames ?? false;
+
+  return { unsafeAllowCustomTypes, unsafeAllowLinkedLibraries, unsafeAllowRenames, unsafeAllow, kind };
+}
+
+export function processExceptions(
+  contractName: string,
+  errors: ValidationError[],
+  opts: ValidationOptions,
+): ValidationError[] {
+  const { unsafeAllow } = withValidationDefaults(opts);
+
+  if (opts.kind === 'transparent') {
+    errors = errors.filter(error => error.kind !== 'missing-public-upgradeto');
+  }
+
+  for (const [errorType, errorDescription] of Object.entries(ValidationErrorUnsafeMessages)) {
+    if (unsafeAllow.includes(errorType as ValidationError['kind'])) {
+      let exceptionsFound = false;
+
+      errors = errors.filter(error => {
+        const isException = errorType === error.kind;
+        exceptionsFound = exceptionsFound || isException;
+        return !isException;
+      });
+
+      if (exceptionsFound && errorDescription) {
+        logWarning(`Potentially unsafe deployment of ${contractName}`, errorDescription);
+      }
+    }
+  }
+
+  return errors;
+}

package/src/validate/query.test.ts

@@ -0,0 +1,48 @@
+import test from 'ava';
+
+import { ContractValidation, ValidationRunData } from './run';
+import { getUnlinkedBytecode } from './query';
+import { getVersion } from '../version';
+
+test('getUnlinkedBytecode', t => {
+  const unlinkedBytecode = '0x12__$5ae0c2211b657f8a7ca51e0b14f2a8333d$__78';
+  const linkedBytecode = '0x12456456456456456456456456456456456456456478';
+
+  const validation: Record<string, Partial<ContractValidation>> = {
+    B: {
+      version: getVersion(unlinkedBytecode),
+      linkReferences: [
+        {
+          src: '',
+          name: '',
+          start: 50,
+          length: 20,
+          placeholder: '__$5ae0c2211b657f8a7ca51e0b14f2a8333d$__',
+        },
+        {
+          src: '',
+          name: '',
+          start: 30,
+          length: 20,
+          placeholder: '__$5ae0c2211b657f8a7ca51e0b14f2a8333d$__',
+        },
+      ],
+    },
+    A: {
+      version: getVersion(unlinkedBytecode),
+      linkReferences: [
+        {
+          src: '',
+          name: '',
+          start: 1,
+          length: 20,
+          placeholder: '__$5ae0c2211b657f8a7ca51e0b14f2a8333d$__',
+        },
+      ],
+    },
+  };
+
+  const recovered = getUnlinkedBytecode(validation as ValidationRunData, linkedBytecode);
+
+  t.is(recovered, unlinkedBytecode);
+});