@openzeppelin/upgrades-core 1.9.1

package/src/validate/query.ts

@@ -0,0 +1,127 @@
+import { Version, getVersion } from '../version';
+import { ValidationRunData, ValidationError } from './run';
+import { StorageLayout } from '../storage/layout';
+import { unlinkBytecode } from '../link-refs';
+import { ValidationOptions, processExceptions } from './overrides';
+import { ValidationErrors } from './error';
+import { ValidationData, normalizeValidationData } from './data';
+
+export function assertUpgradeSafe(data: ValidationData, version: Version, opts: ValidationOptions): void {
+  const dataV3 = normalizeValidationData(data);
+  const [contractName] = getContractNameAndRunValidation(dataV3, version);
+
+  let errors = getErrors(dataV3, version);
+  errors = processExceptions(contractName, errors, opts);
+
+  if (errors.length > 0) {
+    throw new ValidationErrors(contractName, errors);
+  }
+}
+
+export function getContractVersion(runData: ValidationRunData, contractName: string): Version {
+  const { version } = runData[contractName];
+  if (version === undefined) {
+    throw new Error(`Contract ${contractName} is abstract`);
+  }
+  return version;
+}
+
+export function getContractNameAndRunValidation(data: ValidationData, version: Version): [string, ValidationRunData] {
+  const dataV3 = normalizeValidationData(data);
+
+  let runValidation;
+  let contractName;
+
+  for (const validation of dataV3.log) {
+    contractName = Object.keys(validation).find(
+      name => validation[name].version?.withMetadata === version.withMetadata,
+    );
+    if (contractName !== undefined) {
+      runValidation = validation;
+      break;
+    }
+  }
+
+  if (contractName === undefined || runValidation === undefined) {
+    throw new Error('The requested contract was not found. Make sure the source code is available for compilation');
+  }
+
+  return [contractName, runValidation];
+}
+
+export function getStorageLayout(data: ValidationData, version: Version): StorageLayout {
+  const dataV3 = normalizeValidationData(data);
+  const [contractName, runValidation] = getContractNameAndRunValidation(dataV3, version);
+  return unfoldStorageLayout(runValidation, contractName);
+}
+
+export function unfoldStorageLayout(runData: ValidationRunData, contractName: string): StorageLayout {
+  const c = runData[contractName];
+  const layout: StorageLayout = { storage: [], types: {} };
+  for (const name of [contractName].concat(c.inherit)) {
+    layout.storage.unshift(...runData[name].layout.storage);
+    Object.assign(layout.types, runData[name].layout.types);
+  }
+  return layout;
+}
+
+export function* findVersionWithoutMetadataMatches(
+  data: ValidationData,
+  versionWithoutMetadata: string,
+): Generator<[string, ValidationRunData]> {
+  const dataV3 = normalizeValidationData(data);
+
+  for (const validation of dataV3.log) {
+    for (const contractName in validation) {
+      if (validation[contractName].version?.withoutMetadata === versionWithoutMetadata) {
+        yield [contractName, validation];
+      }
+    }
+  }
+}
+
+export function getUnlinkedBytecode(data: ValidationData, bytecode: string): string {
+  const dataV3 = normalizeValidationData(data);
+
+  for (const validation of dataV3.log) {
+    const linkableContracts = Object.keys(validation).filter(name => validation[name].linkReferences.length > 0);
+
+    for (const name of linkableContracts) {
+      const { linkReferences } = validation[name];
+      const unlinkedBytecode = unlinkBytecode(bytecode, linkReferences);
+      const version = getVersion(unlinkedBytecode);
+
+      if (validation[name].version?.withMetadata === version.withMetadata) {
+        return unlinkedBytecode;
+      }
+    }
+  }
+
+  return bytecode;
+}
+
+export function getErrors(data: ValidationData, version: Version): ValidationError[] {
+  const dataV3 = normalizeValidationData(data);
+  const [contractName, runValidation] = getContractNameAndRunValidation(dataV3, version);
+  const c = runValidation[contractName];
+
+  const errors = c.errors
+    .concat(...c.inherit.map(name => runValidation[name].errors))
+    .concat(...c.libraries.map(name => runValidation[name].errors));
+
+  const selfAndInheritedMethods = c.methods.concat(...c.inherit.map(name => runValidation[name].methods));
+
+  if (!selfAndInheritedMethods.includes('upgradeTo(address)')) {
+    errors.push({
+      src: c.src,
+      kind: 'missing-public-upgradeto',
+    });
+  }
+
+  return errors;
+}
+
+export function isUpgradeSafe(data: ValidationData, version: Version): boolean {
+  const dataV3 = normalizeValidationData(data);
+  return getErrors(dataV3, version).length == 0;
+}

package/src/validate/run.ts

@@ -0,0 +1,278 @@
+import { Node } from 'solidity-ast/node';
+import { isNodeType, findAll } from 'solidity-ast/utils';
+import type { ContractDefinition } from 'solidity-ast';
+
+import { SolcOutput, SolcBytecode } from '../solc-api';
+import { SrcDecoder } from '../src-decoder';
+import { astDereferencer } from '../ast-dereferencer';
+import { isNullish } from '../utils/is-nullish';
+import { getFunctionSignature } from '../utils/function';
+import { Version, getVersion } from '../version';
+import { extractLinkReferences, LinkReference } from '../link-refs';
+import { extractStorageLayout } from '../storage/extract';
+import { StorageLayout } from '../storage/layout';
+
+export type ValidationRunData = Record<string, ContractValidation>;
+
+export interface ContractValidation {
+  version?: Version;
+  src: string;
+  inherit: string[];
+  libraries: string[];
+  methods: string[];
+  linkReferences: LinkReference[];
+  errors: ValidationError[];
+  layout: StorageLayout;
+}
+
+const errorKinds = [
+  'state-variable-assignment',
+  'state-variable-immutable',
+  'external-library-linking',
+  'struct-definition',
+  'enum-definition',
+  'constructor',
+  'delegatecall',
+  'selfdestruct',
+  'missing-public-upgradeto',
+] as const;
+
+export type ValidationError =
+  | ValidationErrorConstructor
+  | ValidationErrorOpcode
+  | ValidationErrorWithName
+  | ValidationErrorUpgradeability;
+
+interface ValidationErrorBase {
+  src: string;
+  kind: typeof errorKinds[number];
+}
+
+interface ValidationErrorWithName extends ValidationErrorBase {
+  name: string;
+  kind:
+    | 'state-variable-assignment'
+    | 'state-variable-immutable'
+    | 'external-library-linking'
+    | 'struct-definition'
+    | 'enum-definition';
+}
+
+interface ValidationErrorConstructor extends ValidationErrorBase {
+  kind: 'constructor';
+  contract: string;
+}
+
+interface ValidationErrorOpcode extends ValidationErrorBase {
+  kind: 'delegatecall' | 'selfdestruct';
+}
+
+interface ValidationErrorUpgradeability extends ValidationErrorBase {
+  kind: 'missing-public-upgradeto';
+}
+
+function* execall(re: RegExp, text: string) {
+  re = new RegExp(re, re.flags + (re.sticky ? '' : 'y'));
+  while (true) {
+    const match = re.exec(text);
+    if (match && match[0] !== '') {
+      yield match;
+    } else {
+      break;
+    }
+  }
+}
+
+function getAllowed(node: Node): string[] {
+  if ('documentation' in node) {
+    const doc = typeof node.documentation === 'string' ? node.documentation : node.documentation?.text ?? '';
+
+    const result: string[] = [];
+    for (const { groups } of execall(
+      /^\s*(?:@(?<title>\w+)(?::(?<tag>[a-z][a-z-]*))? )?(?<args>(?:(?!^\s@\w+)[^])*)/m,
+      doc,
+    )) {
+      if (groups && groups.title === 'custom' && groups.tag === 'oz-upgrades-unsafe-allow') {
+        result.push(...groups.args.split(/\s+/));
+      }
+    }
+
+    result.forEach(arg => {
+      if (!(errorKinds as readonly string[]).includes(arg)) {
+        throw new Error(`NatSpec: oz-upgrades-unsafe-allow argument not recognized: ${arg}`);
+      }
+    });
+
+    return result;
+  } else {
+    return [];
+  }
+}
+
+function skipCheck(error: string, node: Node): boolean {
+  return getAllowed(node).includes(error);
+}
+
+export function validate(solcOutput: SolcOutput, decodeSrc: SrcDecoder): ValidationRunData {
+  const validation: ValidationRunData = {};
+  const fromId: Record<number, string> = {};
+  const inheritIds: Record<string, number[]> = {};
+  const libraryIds: Record<string, number[]> = {};
+
+  const deref = astDereferencer(solcOutput);
+
+  for (const source in solcOutput.contracts) {
+    for (const contractName in solcOutput.contracts[source]) {
+      const bytecode = solcOutput.contracts[source][contractName].evm.bytecode;
+      const version = bytecode.object === '' ? undefined : getVersion(bytecode.object);
+      const linkReferences = extractLinkReferences(bytecode);
+
+      validation[contractName] = {
+        src: contractName,
+        version,
+        inherit: [],
+        libraries: [],
+        methods: [],
+        linkReferences,
+        errors: [],
+        layout: {
+          storage: [],
+          types: {},
+        },
+      };
+    }
+
+    for (const contractDef of findAll('ContractDefinition', solcOutput.sources[source].ast)) {
+      fromId[contractDef.id] = contractDef.name;
+
+      // May be undefined in case of duplicate contract names in Truffle
+      const bytecode = solcOutput.contracts[source][contractDef.name]?.evm.bytecode;
+
+      if (contractDef.name in validation && bytecode !== undefined) {
+        inheritIds[contractDef.name] = contractDef.linearizedBaseContracts.slice(1);
+        libraryIds[contractDef.name] = getReferencedLibraryIds(contractDef);
+
+        validation[contractDef.name].src = decodeSrc(contractDef);
+        validation[contractDef.name].errors = [
+          ...getConstructorErrors(contractDef, decodeSrc),
+          ...getOpcodeErrors(contractDef, decodeSrc),
+          ...getStateVariableErrors(contractDef, decodeSrc),
+          // TODO: add linked libraries support
+          // https://github.com/OpenZeppelin/openzeppelin-upgrades/issues/52
+          ...getLinkingErrors(contractDef, bytecode),
+        ];
+
+        validation[contractDef.name].layout = extractStorageLayout(contractDef, decodeSrc, deref);
+        validation[contractDef.name].methods = [...findAll('FunctionDefinition', contractDef)]
+          .filter(fnDef => ['external', 'public'].includes(fnDef.visibility))
+          .map(fnDef => getFunctionSignature(fnDef, deref));
+      }
+    }
+  }
+
+  for (const contractName in inheritIds) {
+    validation[contractName].inherit = inheritIds[contractName].map(id => fromId[id]);
+  }
+
+  for (const contractName in libraryIds) {
+    validation[contractName].libraries = libraryIds[contractName].map(id => fromId[id]);
+  }
+
+  return validation;
+}
+
+function* getConstructorErrors(contractDef: ContractDefinition, decodeSrc: SrcDecoder): Generator<ValidationError> {
+  for (const fnDef of findAll('FunctionDefinition', contractDef, node => skipCheck('constructor', node))) {
+    if (fnDef.kind === 'constructor' && ((fnDef.body?.statements?.length ?? 0) > 0 || fnDef.modifiers.length > 0)) {
+      yield {
+        kind: 'constructor',
+        contract: contractDef.name,
+        src: decodeSrc(fnDef),
+      };
+    }
+  }
+}
+
+function* getOpcodeErrors(contractDef: ContractDefinition, decodeSrc: SrcDecoder): Generator<ValidationErrorOpcode> {
+  for (const fnCall of findAll('FunctionCall', contractDef, node => skipCheck('delegatecall', node))) {
+    const fn = fnCall.expression;
+    if (fn.typeDescriptions.typeIdentifier?.match(/^t_function_baredelegatecall_/)) {
+      yield {
+        kind: 'delegatecall',
+        src: decodeSrc(fnCall),
+      };
+    }
+  }
+  for (const fnCall of findAll('FunctionCall', contractDef, node => skipCheck('selfdestruct', node))) {
+    const fn = fnCall.expression;
+    if (fn.typeDescriptions.typeIdentifier?.match(/^t_function_selfdestruct_/)) {
+      yield {
+        kind: 'selfdestruct',
+        src: decodeSrc(fnCall),
+      };
+    }
+  }
+}
+
+function* getStateVariableErrors(
+  contractDef: ContractDefinition,
+  decodeSrc: SrcDecoder,
+): Generator<ValidationErrorWithName> {
+  for (const varDecl of contractDef.nodes) {
+    if (isNodeType('VariableDeclaration', varDecl)) {
+      if (!varDecl.constant && !isNullish(varDecl.value)) {
+        if (!skipCheck('state-variable-assignment', contractDef) && !skipCheck('state-variable-assignment', varDecl)) {
+          yield {
+            kind: 'state-variable-assignment',
+            name: varDecl.name,
+            src: decodeSrc(varDecl),
+          };
+        }
+      }
+      if (varDecl.mutability === 'immutable') {
+        if (!skipCheck('state-variable-immutable', contractDef) && !skipCheck('state-variable-immutable', varDecl)) {
+          yield {
+            kind: 'state-variable-immutable',
+            name: varDecl.name,
+            src: decodeSrc(varDecl),
+          };
+        }
+      }
+    }
+  }
+}
+
+function getReferencedLibraryIds(contractDef: ContractDefinition): number[] {
+  const implicitUsage = [...findAll('UsingForDirective', contractDef)].map(
+    usingForDirective => usingForDirective.libraryName.referencedDeclaration,
+  );
+
+  const explicitUsage = [...findAll('Identifier', contractDef)]
+    .filter(identifier => identifier.typeDescriptions.typeString?.match(/^type\(library/))
+    .map(identifier => {
+      if (isNullish(identifier.referencedDeclaration)) {
+        throw new Error('Broken invariant: Identifier.referencedDeclaration should not be null');
+      }
+      return identifier.referencedDeclaration;
+    });
+
+  return [...new Set(implicitUsage.concat(explicitUsage))];
+}
+
+function* getLinkingErrors(
+  contractDef: ContractDefinition,
+  bytecode: SolcBytecode,
+): Generator<ValidationErrorWithName> {
+  const { linkReferences } = bytecode;
+  for (const source of Object.keys(linkReferences)) {
+    for (const libName of Object.keys(linkReferences[source])) {
+      if (!skipCheck('external-library-linking', contractDef)) {
+        yield {
+          kind: 'external-library-linking',
+          name: libName,
+          src: source,
+        };
+      }
+    }
+  }
+}

package/src/validate.test.ts

@@ -0,0 +1,133 @@
+import _test, { TestInterface } from 'ava';
+import { artifacts } from 'hardhat';
+
+import {
+  validate,
+  getStorageLayout,
+  getContractVersion,
+  assertUpgradeSafe,
+  ValidationOptions,
+  RunValidation,
+} from './validate';
+import { solcInputOutputDecoder } from './src-decoder';
+
+interface Context {
+  validation: RunValidation;
+}
+
+const test = _test as TestInterface<Context>;
+
+test.before(async t => {
+  const contracts = [
+    'contracts/test/Validations.sol:HasEmptyConstructor',
+    'contracts/test/ValidationsNatspec.sol:HasNonEmptyConstructorNatspec1',
+    'contracts/test/Proxiable.sol:ChildOfProxiable',
+  ];
+
+  t.context.validation = {} as RunValidation;
+  for (const contract of contracts) {
+    const buildInfo = await artifacts.getBuildInfo(contract);
+    if (buildInfo === undefined) {
+      throw new Error(`Build info not found for contract ${contract}`);
+    }
+    const solcOutput = buildInfo.output;
+    const solcInput = buildInfo.input;
+    const decodeSrc = solcInputOutputDecoder(solcInput, solcOutput);
+    Object.assign(t.context.validation, validate(solcOutput, decodeSrc));
+  }
+});
+
+function testValid(name: string, kind: ValidationOptions['kind'], valid: boolean) {
+  testOverride(name, kind, {}, valid);
+}
+
+function testOverride(name: string, kind: ValidationOptions['kind'], opts: ValidationOptions, valid: boolean) {
+  const optKeys = Object.keys(opts);
+  const describeOpts = optKeys.length > 0 ? '(' + optKeys.join(', ') + ')' : '';
+  const testName = [valid ? 'accepts' : 'rejects', kind, name, describeOpts].join(' ');
+  test(testName, t => {
+    const version = getContractVersion(t.context.validation, name);
+    const assertUpgSafe = () => assertUpgradeSafe([t.context.validation], version, { kind, ...opts });
+    if (valid) {
+      t.notThrows(assertUpgSafe);
+    } else {
+      t.throws(assertUpgSafe);
+    }
+  });
+}
+
+testValid('HasEmptyConstructor', 'transparent', true);
+testValid('HasConstantStateVariableAssignment', 'transparent', true);
+testValid('HasStateVariable', 'transparent', true);
+testValid('UsesImplicitSafeInternalLibrary', 'transparent', true);
+testValid('UsesExplicitSafeInternalLibrary', 'transparent', true);
+
+testValid('HasNonEmptyConstructor', 'transparent', false);
+testValid('ParentHasNonEmptyConstructor', 'transparent', false);
+testValid('AncestorHasNonEmptyConstructor', 'transparent', false);
+testValid('HasStateVariableAssignment', 'transparent', false);
+testValid('HasImmutableStateVariable', 'transparent', false);
+testValid('HasSelfDestruct', 'transparent', false);
+testValid('HasDelegateCall', 'transparent', false);
+testValid('ImportedParentHasStateVariableAssignment', 'transparent', false);
+testValid('UsesImplicitUnsafeInternalLibrary', 'transparent', false);
+testValid('UsesExplicitUnsafeInternalLibrary', 'transparent', false);
+testValid('UsesImplicitUnsafeExternalLibrary', 'transparent', false);
+testValid('UsesExplicitUnsafeExternalLibrary', 'transparent', false);
+
+// Linked external libraries are not yet supported
+// see: https://github.com/OpenZeppelin/openzeppelin-upgrades/issues/52
+testValid('UsesImplicitSafeExternalLibrary', 'transparent', false);
+testValid('UsesExplicitSafeExternalLibrary', 'transparent', false);
+
+test('inherited storage', t => {
+  const version = getContractVersion(t.context.validation, 'StorageInheritChild');
+  const layout = getStorageLayout([t.context.validation], version);
+  t.is(layout.storage.length, 8);
+  for (let i = 0; i < layout.storage.length; i++) {
+    t.is(layout.storage[i].label, `v${i}`);
+    t.truthy(layout.types[layout.storage[i].type]);
+  }
+});
+
+testOverride('UsesImplicitSafeExternalLibrary', 'transparent', { unsafeAllowLinkedLibraries: true }, true);
+testOverride('UsesExplicitSafeExternalLibrary', 'transparent', { unsafeAllowLinkedLibraries: true }, true);
+testOverride('UsesImplicitSafeExternalLibrary', 'transparent', { unsafeAllow: ['external-library-linking'] }, true);
+testOverride('UsesExplicitSafeExternalLibrary', 'transparent', { unsafeAllow: ['external-library-linking'] }, true);
+
+testValid('HasEmptyConstructor', 'uups', false);
+testValid('HasInternalUpgradeToFunction', 'uups', false);
+testValid('HasUpgradeToFunction', 'uups', true);
+testValid('ParentHasUpgradeToFunction', 'uups', true);
+testValid('ChildOfProxiable', 'uups', true);
+
+testValid('HasNonEmptyConstructorNatspec1', 'transparent', true);
+testValid('HasNonEmptyConstructorNatspec2', 'transparent', true);
+testValid('HasNonEmptyConstructorNatspec3', 'transparent', true);
+testValid('HasNonEmptyConstructorNatspec4', 'transparent', true);
+testValid('ParentHasNonEmptyConstructorNatspec1', 'transparent', true);
+testValid('ParentHasNonEmptyConstructorNatspec2', 'transparent', true);
+testValid('AncestorHasNonEmptyConstructorNatspec1', 'transparent', true);
+testValid('AncestorHasNonEmptyConstructorNatspec2', 'transparent', true);
+testValid('HasStateVariableAssignmentNatspec1', 'transparent', true);
+testValid('HasStateVariableAssignmentNatspec2', 'transparent', true);
+testValid('HasStateVariableAssignmentNatspec3', 'transparent', false);
+testValid('HasImmutableStateVariableNatspec1', 'transparent', true);
+testValid('HasImmutableStateVariableNatspec2', 'transparent', true);
+testValid('HasImmutableStateVariableNatspec3', 'transparent', false);
+testValid('HasSelfDestructNatspec1', 'transparent', true);
+testValid('HasSelfDestructNatspec2', 'transparent', true);
+testValid('HasSelfDestructNatspec3', 'transparent', true);
+testValid('HasDelegateCallNatspec1', 'transparent', true);
+testValid('HasDelegateCallNatspec2', 'transparent', true);
+testValid('HasDelegateCallNatspec3', 'transparent', true);
+testValid('ImportedParentHasStateVariableAssignmentNatspec1', 'transparent', true);
+testValid('ImportedParentHasStateVariableAssignmentNatspec2', 'transparent', true);
+testValid('UsesImplicitSafeInternalLibraryNatspec', 'transparent', true);
+testValid('UsesImplicitSafeExternalLibraryNatspec', 'transparent', true);
+testValid('UsesImplicitUnsafeInternalLibraryNatspec', 'transparent', true);
+testValid('UsesImplicitUnsafeExternalLibraryNatspec', 'transparent', true);
+testValid('UsesExplicitSafeInternalLibraryNatspec', 'transparent', true);
+testValid('UsesExplicitSafeExternalLibraryNatspec', 'transparent', true);
+testValid('UsesExplicitUnsafeInternalLibraryNatspec', 'transparent', true);
+testValid('UsesExplicitUnsafeExternalLibraryNatspec', 'transparent', true);