@openzeppelin/upgrades-core 1.35.0 → 1.36.0

package/src/cli/validate/validate-upgrade-safety.ts

@@ -1,3 +1,4 @@
+import path from 'path';
 import { ValidationOptions, withValidationDefaults } from '../..';
 
 import { getBuildInfoFiles } from './build-info-file';
@@ -22,10 +23,11 @@ export type SpecifiedContracts = {
  * Validates the upgrade safety of all contracts in the build info dir's build info files.
  * Only contracts that are detected as upgradeable will be validated.
  *
- * @param buildInfoDir Absolute path of build info directory, or undefined to use the default Hardhat or Foundry build-info dir.
+ * @param buildInfoDir Path of build info directory, or undefined to use the default Hardhat or Foundry build-info dir.
  * @param contract The name or fully qualified name of the contract to validate. If not specified, all upgradeable contracts in the build info directory will be validated.
  * @param reference The name or fully qualified name of the reference contract to use for storage layout comparisons. Can only be used along with `contract`. If not specified, uses the `@custom:oz-upgrades-from` annotation in the contract that is being validated.
  * @param opts Validation options, or undefined to use the default validation options.
+ * @param referenceBuildInfoDirs Optional paths of additional build info directories from previous versions of the project to use for storage layout comparisons. When using this option, refer to one of these directories using prefix `<dirName>:` before the contract name or fully qualified name in the `reference` param or `@custom:oz-upgrades-from` annotation, where `<dirName>` is the directory short name. Each directory short name must be unique, including compared to the main build info directory.
  * @returns The project report.
  */
 export async function validateUpgradeSafety(
@@ -33,28 +35,56 @@ export async function validateUpgradeSafety(
   contract?: string,
   reference?: string,
   opts: ValidateUpgradeSafetyOptions = {},
+  referenceBuildInfoDirs?: string[],
 ): Promise<ProjectReport> {
   const allOpts = withCliDefaults(opts);
 
   const buildInfoFiles = await getBuildInfoFiles(buildInfoDir);
   const sourceContracts = validateBuildInfoContracts(buildInfoFiles);
 
-  const specifiedContracts = findSpecifiedContracts(sourceContracts, allOpts, contract, reference);
+  const buildInfoDictionary: BuildInfoDictionary = {};
+  buildInfoDictionary[''] = sourceContracts;
+  if (buildInfoFiles.length > 0) {
+    buildInfoDictionary[buildInfoFiles[0].dirShortName] = sourceContracts;
+  }
+
+  if (referenceBuildInfoDirs !== undefined) {
+    for (const referenceBuildInfoDir of referenceBuildInfoDirs) {
+      const key = path.basename(referenceBuildInfoDir);
+
+      if (buildInfoDictionary[key] !== undefined) {
+        throw new Error(`Reference build info directory short name '${key}' is not unique.`);
+      }
+
+      const referenceBuildInfoFiles = await getBuildInfoFiles(referenceBuildInfoDir);
+      buildInfoDictionary[key] = validateBuildInfoContracts(referenceBuildInfoFiles);
+    }
+  }
 
-  const contractReports = getContractReports(sourceContracts, allOpts, specifiedContracts);
+  const specifiedContracts = findSpecifiedContracts(buildInfoDictionary, allOpts, contract, reference);
+
+  const contractReports = getContractReports(buildInfoDictionary, allOpts, specifiedContracts);
   return getProjectReport(contractReports, specifiedContracts !== undefined);
 }
 
+/**
+ * Dictionary of build info directories and the contracts they contain.
+ * Main build info directory can be found with the key '' and also with its short name.
+ */
+export interface BuildInfoDictionary {
+  [buildInfoDirName: string]: SourceContract[];
+}
+
 export function findSpecifiedContracts(
-  sourceContracts: SourceContract[],
+  buildInfoDictionary: BuildInfoDictionary,
   opts: Required<ValidateUpgradeSafetyOptions>,
   contractName?: string,
   referenceName?: string,
 ): SpecifiedContracts | undefined {
   if (contractName !== undefined) {
     return {
-      contract: findContract(contractName, undefined, sourceContracts),
-      reference: referenceName !== undefined ? findContract(referenceName, undefined, sourceContracts) : undefined,
+      contract: findContract(contractName, undefined, buildInfoDictionary, true), // only search main build info dir for the specified contract
+      reference: referenceName !== undefined ? findContract(referenceName, undefined, buildInfoDictionary) : undefined,
     };
   } else if (referenceName !== undefined) {
     throw new Error(`The reference option can only be specified when the contract option is also specified.`);

package/src/cli/validate/validations.test.ts

@@ -14,13 +14,17 @@ const test = _test as TestFn<Context>;
 const SOURCE_FILE = 'contracts/test/cli/Validate.sol';
 
 test.before(async t => {
-  const buildInfo = await artifacts.getBuildInfo(`${SOURCE_FILE}:Safe`);
+  const hardhatBuildInfo = await artifacts.getBuildInfo(`${SOURCE_FILE}:Safe`);
 
-  if (buildInfo === undefined) {
+  if (hardhatBuildInfo === undefined) {
     t.fail();
   } else {
-    const sourceContracts = validateBuildInfoContracts([buildInfo]);
-    t.context.reports = getContractReports(sourceContracts, withCliDefaults({}));
+    const buildInfoFile = {
+      ...hardhatBuildInfo,
+      dirShortName: 'build-info',
+    };
+    const sourceContracts = validateBuildInfoContracts([buildInfoFile]);
+    t.context.reports = getContractReports({ '': sourceContracts }, withCliDefaults({}));
   }
 });
 

package/src/cli/validate/validations.ts

@@ -13,6 +13,7 @@ export interface SourceContract {
   name: string;
   fullyQualifiedName: string;
   validationData: ValidationRunData;
+  buildInfoDirShortName: string;
 }
 
 export function validateBuildInfoContracts(buildInfoFiles: BuildInfoFile[]): SourceContract[] {
@@ -48,6 +49,7 @@ function addContractsFromBuildInfo(
         name: contractDef.name,
         fullyQualifiedName,
         validationData: validationData,
+        buildInfoDirShortName: buildInfoFile.dirShortName,
       });
     }
   }

package/src/cli/validate.ts

@@ -16,6 +16,7 @@ Options:
   --contract <CONTRACT>  The name or fully qualified name of the contract to validate. If not specified, all upgradeable contracts in the build info directory will be validated.
   --reference <REFERENCE_CONTRACT>  Can only be used when the --contract option is also provided. The name or fully qualified name of the reference contract to use for storage layout comparisons. If not specified, uses the @custom:oz-upgrades-from annotation if it is defined in the contract that is being validated.
   --requireReference  Can only be used when the --contract option is also provided. Not compatible with --unsafeSkipStorageCheck. If specified, requires either the --reference option to be provided or the contract to have a @custom:oz-upgrades-from annotation.
+  --referenceBuildInfoDirs  Optional paths of additional build info directories from previous versions of the project to use for storage layout comparisons. When using this option, refer to one of these directories using prefix '<dirName>:' before the contract name or fully qualified name in the --reference option or @custom:oz-upgrades-from annotation, where <dirName> is the directory short name. Each directory short name must be unique, including compared to the main build info directory.
   --unsafeAllow "<VALIDATION_ERRORS>"  Selectively disable one or more validation errors. Comma-separated list with one or more of the following: ${errorKinds.join(
     ', ',
   )}
@@ -32,6 +33,7 @@ export async function main(args: string[]): Promise<void> {
       functionArgs.contract,
       functionArgs.reference,
       functionArgs.opts,
+      functionArgs.referenceBuildInfoDirs,
     );
     console.log(result.explain());
     process.exitCode = result.ok ? 0 : 1;
@@ -48,7 +50,7 @@ function parseArgs(args: string[]) {
       'unsafeAllowLinkedLibraries',
       'requireReference',
     ],
-    string: ['unsafeAllow', 'contract', 'reference'],
+    string: ['unsafeAllow', 'contract', 'reference', 'referenceBuildInfoDirs'],
     alias: { h: 'help' },
   });
   const extraArgs = parsedArgs._;
@@ -71,6 +73,7 @@ interface FunctionArgs {
   contract?: string;
   reference?: string;
   opts: Required<ValidateUpgradeSafetyOptions>;
+  referenceBuildInfoDirs?: string[];
 }
 
 /**
@@ -90,6 +93,7 @@ export function getFunctionArgs(parsedArgs: minimist.ParsedArgs, extraArgs: stri
     const contract = getAndValidateString(parsedArgs, 'contract');
     const reference = getAndValidateString(parsedArgs, 'reference');
     const opts = withDefaults(parsedArgs);
+    const referenceBuildInfoDirs = getAndValidateString(parsedArgs, 'referenceBuildInfoDirs')?.split(/,+/);
 
     if (contract === undefined) {
       if (reference !== undefined) {
@@ -98,7 +102,7 @@ export function getFunctionArgs(parsedArgs: minimist.ParsedArgs, extraArgs: stri
         throw new Error('The --requireReference option can only be used along with the --contract option.');
       }
     }
-    return { buildInfoDir, contract, reference, opts };
+    return { buildInfoDir, contract, reference, opts, referenceBuildInfoDirs };
   }
 }
 
@@ -125,6 +129,7 @@ function validateOptions(parsedArgs: minimist.ParsedArgs) {
         'contract',
         'reference',
         'requireReference',
+        'referenceBuildInfoDirs',
       ].includes(key),
   );
   if (invalidArgs.length > 0) {

package/src/utils/make-namespaced.test.ts.md

@@ -97,6 +97,8 @@ Generated by [AVA](https://avajs.dev).
           ␊
           abstract contract HasFunction {␊
             ␊
+            enum $astId_id_random { dummy }␊
+          ␊
             function foo() pure public returns (bool) {}␊
           }␊
           ␊
@@ -228,6 +230,19 @@ Generated by [AVA](https://avajs.dev).
           ␊
           abstract contract DeploysContractToImmutable {␊
               enum $astId_id_random { dummy }␊
+          }␊
+          ␊
+          abstract contract HasSpecialFunctions {␊
+              ␊
+              ␊
+              enum $astId_id_random { dummy }␊
+          ␊
+              enum $astId_id_random { dummy }␊
+          ␊
+              // Regular function but payable␊
+              function hasPayable() public payable {}␊
+          ␊
+              bytes4 constant PAYABLE_SELECTOR = this.hasPayable.selector;␊
           }`,
         },
         'contracts/test/NamespacedToModifyImported.sol': {
@@ -344,7 +359,9 @@ Generated by [AVA](https://avajs.dev).
           }␊
           ␊
           abstract contract HasFunction {␊
-            ␊
+            /// @param myInt an integer␊
+            enum $astId_id_random { dummy }␊
+          ␊
             function foo() pure public returns (bool) {}␊
           }␊
           ␊
@@ -517,6 +534,19 @@ Generated by [AVA](https://avajs.dev).
           ␊
           abstract contract DeploysContractToImmutable {␊
               enum $astId_id_random { dummy }␊
+          }␊
+          ␊
+          abstract contract HasSpecialFunctions {␊
+              /// @param data call data␊
+              /// @return dataReturn returned data␊
+              enum $astId_id_random { dummy }␊
+          ␊
+              enum $astId_id_random { dummy }␊
+          ␊
+              // Regular function but payable␊
+              function hasPayable() public payable {}␊
+          ␊
+              bytes4 constant PAYABLE_SELECTOR = this.hasPayable.selector;␊
           }`,
         },
         'contracts/test/NamespacedToModifyImported.sol': {
@@ -559,7 +589,7 @@ Generated by [AVA](https://avajs.dev).
           pragma solidity 0.7.6;␊
            ␊
           abstract contract HasFunction {␊
-            ␊
+            enum $astId_id_random { dummy }␊
             function foo() pure public returns (bool) {}␊
           }␊
           ␊

package/src/utils/make-namespaced.ts

@@ -2,7 +2,7 @@ import { isNodeType } from 'solidity-ast/utils';
 import { Node } from 'solidity-ast/node';
 import { SolcInput, SolcOutput } from '../solc-api';
 import { getStorageLocationAnnotation } from '../storage/namespace';
-import { assert } from './assert';
+import { assert, assertUnreachable } from './assert';
 import { FunctionDefinition, VariableDeclaration } from 'solidity-ast';
 
 const OUTPUT_SELECTION = {
@@ -18,9 +18,13 @@ const OUTPUT_SELECTION = {
  *
  * This makes the following modifications to the input:
  * - Adds a state variable for each namespaced struct definition
- * - For each contract, for all node types that are not needed for storage layout or may reference deleted functions and constructors, converts them to dummy enums with random id
+ * - For each contract, for all node types that are not needed for storage layout or may call functions and constructors, converts them to dummy enums with random id
  * - Converts all using for directives (at file level and in contracts) to dummy enums with random id (do not delete them to avoid orphaning possible NatSpec documentation)
- * - Converts all custom errors, free functions and constants (at file level) to dummy enums with the same name (do not delete them since they might be imported by other files)
+ * - Converts all custom errors and constants (at file level) to dummy enums with the same name (do not delete them since they might be imported by other files)
+ * - Replaces functions as follows:
+ *   - For regular function and free function, keep declarations since they may be referenced by constants (free functions may also be imported by other files). But simplify compilation by removing modifiers and body, and replace return parameters with bools which can be default initialized.
+ *   - Constructors are not needed, since we removed anything that may call constructors. Convert to dummy enums to avoid orphaning possible NatSpec.
+ *   - Fallback and receive functions are not needed, since they don't have signatures. Convert to dummy enums to avoid orphaning possible NatSpec.
  *
  * Also sets the outputSelection to only include storageLayout and ast, since the other outputs are not needed.
  *
@@ -228,28 +232,39 @@ function toDummyEnumWithAstId(astId: number) {
 }
 
 function replaceFunction(node: FunctionDefinition, orig: Buffer, modifications: Modification[]) {
-  if (node.kind === 'constructor') {
-    modifications.push(makeDelete(node, orig));
-  } else {
-    if (node.modifiers.length > 0) {
-      for (const modifier of node.modifiers) {
-        modifications.push(makeDelete(modifier, orig));
+  switch (node.kind) {
+    case 'freeFunction':
+    case 'function': {
+      if (node.modifiers.length > 0) {
+        for (const modifier of node.modifiers) {
+          modifications.push(makeDelete(modifier, orig));
+        }
       }
-    }
 
-    if (node.returnParameters.parameters.length > 0) {
-      modifications.push(
-        makeReplace(
-          node.returnParameters,
-          orig,
-          `(${node.returnParameters.parameters.map(param => toReturnParameterReplacement(param)).join(', ')})`,
-        ),
-      );
-    }
+      if (node.returnParameters.parameters.length > 0) {
+        modifications.push(
+          makeReplace(
+            node.returnParameters,
+            orig,
+            `(${node.returnParameters.parameters.map(param => toReturnParameterReplacement(param)).join(', ')})`,
+          ),
+        );
+      }
+
+      if (node.body) {
+        modifications.push(makeReplace(node.body, orig, '{}'));
+      }
 
-    if (node.body) {
-      modifications.push(makeReplace(node.body, orig, '{}'));
+      break;
+    }
+    case 'constructor':
+    case 'fallback':
+    case 'receive': {
+      modifications.push(makeReplace(node, orig, toDummyEnumWithAstId(node.id)));
+      break;
     }
+    default:
+      return assertUnreachable(node.kind);
   }
 }