@openzeppelin/upgrades-core 1.28.0 → 1.30.0

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

@@ -0,0 +1,154 @@
+# Snapshot report for `src/utils/make-namespaced.test.ts`
+
+The actual snapshot is saved in `make-namespaced.test.ts.snap`.
+
+Generated by [AVA](https://avajs.dev).
+
+## make namespaced input
+
+> Snapshot 1
+
+    {
+      language: 'Solidity',
+      settings: {
+        optimizer: {
+          enabled: true,
+          runs: 200,
+        },
+        outputSelection: {
+          '*': {
+            '': [
+              'ast',
+            ],
+            '*': [
+              'storageLayout',
+            ],
+          },
+        },
+      },
+      sources: {
+        'contracts/test/NamespacedToModify.sol': {
+          content: `// SPDX-License-Identifier: MIT␊
+          pragma solidity ^0.8.20;␊
+          ␊
+          contract Example {␊
+              /// @custom:storage-location erc7201:example.main␊
+              struct MainStorage {␊
+                  uint256 x;␊
+                  uint256 y;␊
+              } MainStorage $MainStorage_random;␊
+          ␊
+              ␊
+              ␊
+          ␊
+              ␊
+              ␊
+          ␊
+              ␊
+              ␊
+              struct MyStruct { uint b; }␊
+          ␊
+              // keccak256(abi.encode(uint256(keccak256("example.main")) - 1)) & ~bytes32(uint256(0xff));␊
+              ␊
+          ␊
+              ␊
+          ␊
+              ␊
+          ␊
+              /// @notice standlone natspec␊
+          ␊
+              ␊
+              ␊
+          ␊
+              // standalone doc␊
+          ␊
+              /**␊
+               * standlone doc block␊
+               */␊
+          ␊
+              ␊
+              ␊
+          ␊
+              ␊
+              ␊
+          }␊
+          ␊
+          contract HasFunction {␊
+            ␊
+            ␊
+          }␊
+          ␊
+          contract UsingFunction is HasFunction {␊
+            ␊
+          }␊
+          ␊
+          uint256 constant FreeFunctionUsingSelector = 0;␊
+          ␊
+          uint256 constant CONSTANT_USING_SELECTOR = 0;␊
+          ␊
+          library Lib {␊
+            ␊
+          ␊
+            ␊
+          }␊
+          ␊
+          contract Consumer {␊
+            ␊
+          ␊
+            ␊
+          ␊
+            ␊
+          }␊
+          ␊
+          uint256 constant plusTwo = 0;␊
+          ␊
+          ␊
+          ␊
+          contract UsingForDirectives {␊
+            ␊
+          ␊
+            ␊
+          }`,
+        },
+      },
+    }
+
+## make namespaced input - solc 0.7
+
+> Snapshot 1
+
+    {
+      language: 'Solidity',
+      settings: {
+        optimizer: {
+          enabled: true,
+          runs: 200,
+        },
+        outputSelection: {
+          '*': {
+            '': [
+              'ast',
+            ],
+            '*': [
+              'storageLayout',
+            ],
+          },
+        },
+      },
+      sources: {
+        'contracts/test/NamespacedToModify07.sol': {
+          content: `// SPDX-License-Identifier: MIT␊
+          pragma solidity 0.7.6;␊
+           ␊
+          contract HasFunction {␊
+            ␊
+            ␊
+          }␊
+          ␊
+          contract UsingFunction is HasFunction {␊
+            ␊
+          }␊
+          `,
+        },
+      },
+    }

package/src/utils/make-namespaced.ts

@@ -0,0 +1,154 @@
+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';
+
+const OUTPUT_SELECTION = {
+  '*': {
+    '*': ['storageLayout'],
+    '': ['ast'],
+  },
+};
+
+/**
+ * Makes a modified version of the solc input to add state variables in each contract for namespaced struct definitions,
+ * so that the compiler will generate their types in the storage layout.
+ *
+ * This makes the following modifications to the input:
+ * - Adds a state variable for each namespaced struct definition
+ * - Deletes all contracts' functions since they are not needed for storage layout
+ * - Deletes all contracts' modifiers, variables, and parent constructor invocations to avoid compilation errors due to deleted functions and constructors
+ * - Deletes all using for directives (at file level and in contracts) since they may reference deleted functions
+ * - Converts all free functions and constants (at file level) to dummy variables (do not delete them since they might be imported by other files)
+ *
+ * Also sets the outputSelection to only include storageLayout and ast, since the other outputs are not needed.
+ *
+ * @param input The original solc input.
+ * @param output The original solc output.
+ * @returns The modified solc input with storage layout that includes namespaced type information.
+ */
+export function makeNamespacedInput(input: SolcInput, output: SolcOutput): SolcInput {
+  const modifiedSources: Record<string, { content?: string }> = {};
+
+  for (const [sourcePath] of Object.entries(input.sources)) {
+    const source = input.sources[sourcePath];
+
+    if (source.content === undefined) {
+      modifiedSources[sourcePath] = source;
+      continue;
+    }
+
+    const orig = Buffer.from(source.content, 'utf8');
+
+    const modifications: Modification[] = [];
+
+    for (const node of output.sources[sourcePath].ast.nodes) {
+      if (isNodeType('ContractDefinition', node)) {
+        const contractDef = node;
+
+        // Remove any calls to parent constructors from the inheritance list
+        const inherits = contractDef.baseContracts;
+        for (const inherit of inherits) {
+          if (Array.isArray(inherit.arguments)) {
+            assert(inherit.baseName.name !== undefined);
+            modifications.push(makeReplace(inherit, orig, inherit.baseName.name));
+          }
+        }
+
+        const contractNodes = contractDef.nodes;
+        for (const contractNode of contractNodes) {
+          if (
+            isNodeType('FunctionDefinition', contractNode) ||
+            isNodeType('ModifierDefinition', contractNode) ||
+            isNodeType('VariableDeclaration', contractNode)
+          ) {
+            if (contractNode.documentation) {
+              modifications.push(makeDelete(contractNode.documentation, orig));
+            }
+            modifications.push(makeDelete(contractNode, orig));
+          } else if (isNodeType('UsingForDirective', contractNode)) {
+            modifications.push(makeDelete(contractNode, orig));
+          } else if (isNodeType('StructDefinition', contractNode)) {
+            const storageLocation = getStorageLocationAnnotation(contractNode);
+            if (storageLocation !== undefined) {
+              const structName = contractNode.name;
+              const variableName = `$${structName}_${(Math.random() * 1e6).toFixed(0)}`;
+              const insertText = ` ${structName} ${variableName};`;
+
+              modifications.push(makeInsertAfter(contractNode, insertText));
+            }
+          }
+        }
+      } else if (isNodeType('FunctionDefinition', node) || isNodeType('VariableDeclaration', node)) {
+        if (node.documentation) {
+          modifications.push(makeDelete(node.documentation, orig));
+        }
+        // Replace with a dummy variable of arbitrary type
+        const name = node.name;
+        const insertText = `uint256 constant ${name} = 0;`;
+        modifications.push(makeReplace(node, orig, insertText));
+      } else if (isNodeType('UsingForDirective', node)) {
+        modifications.push(makeDelete(node, orig));
+      }
+    }
+
+    modifiedSources[sourcePath] = { ...source, content: getModifiedSource(orig, modifications) };
+  }
+
+  return { ...input, sources: modifiedSources, settings: { ...input.settings, outputSelection: OUTPUT_SELECTION } };
+}
+
+interface Modification {
+  start: number;
+  end: number;
+  text?: string;
+}
+
+function getPositions(node: Node) {
+  const [start, length] = node.src.split(':').map(Number);
+  const end = start + length;
+  return { start, end };
+}
+
+function makeReplace(node: Node, orig: Buffer, text: string): Modification {
+  // Replace is a delete and insert
+  const { start, end } = makeDelete(node, orig);
+  return { start, end, text };
+}
+
+function makeInsertAfter(node: Node, text: string): Modification {
+  const { end } = getPositions(node);
+  return { start: end, end, text };
+}
+
+function makeDelete(node: Node, orig: Buffer): Modification {
+  const positions = getPositions(node);
+  let end = positions.end;
+  // If the next character is a semicolon for variables, skip over it
+  if (isNodeType('VariableDeclaration', node) && end + 1 < orig.length && orig.toString('utf8', end, end + 1) === ';') {
+    end += 1;
+  }
+  return { start: positions.start, end };
+}
+
+function getModifiedSource(orig: Buffer, modifications: Modification[]): string {
+  let result = '';
+  let copyFromIndex = 0;
+
+  for (const modification of modifications) {
+    assert(modification.start >= copyFromIndex);
+    result += orig.toString('utf8', copyFromIndex, modification.start);
+
+    if (modification.text !== undefined) {
+      result += modification.text;
+    }
+
+    copyFromIndex = modification.end;
+  }
+
+  assert(copyFromIndex <= orig.length);
+  result += orig.toString('utf8', copyFromIndex);
+
+  return result;
+}

package/src/utils/stabilize-layout.ts

@@ -13,5 +13,10 @@ export function stabilizeStorageLayout(layout: StorageLayout) {
           : item.members.map(m => ({ ...m, type: stabilizeTypeIdentifier(m.type) })));
       return [stabilizeTypeIdentifier(type), { ...item, members }];
     }),
+    namespaces: layout.namespaces
+      ? Object.entries(layout.namespaces).map(([ns, items]) => {
+          return [ns, items.map(item => ({ ...item, type: stabilizeTypeIdentifier(item.type) }))];
+        })
+      : undefined,
   };
 }

package/src/validate/overrides.ts

@@ -73,7 +73,7 @@ export const ValidationErrorUnsafeMessages: Record<ValidationError['kind'], stri
   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.`,
+    `Not having a public upgradeTo or upgradeToAndCall function in your implementation can break upgradeability.`,
     `Some implementation might check that onchain, and cause the upgrade to revert.`,
   ],
 };

package/src/validate/query.ts

@@ -8,6 +8,7 @@ import { ValidationData, normalizeValidationData } from './data';
 import { ProxyDeployment } from '../manifest';
 
 const upgradeToSignature = 'upgradeTo(address)';
+const upgradeToAndCallSignature = 'upgradeToAndCall(address,bytes)';
 
 export function assertUpgradeSafe(data: ValidationData, version: Version, opts: ValidationOptions): void {
   const dataV3 = normalizeValidationData(data);
@@ -92,9 +93,11 @@ export function unfoldStorageLayout(runData: ValidationRunData, fullContractName
       solcVersion,
       storage: c.layout.storage,
       types: c.layout.types,
+      namespaces: c.layout.namespaces,
     };
   } else {
-    const layout: StorageLayout = { solcVersion, storage: [], types: {} };
+    // Namespaces are pre-flattened
+    const layout: StorageLayout = { solcVersion, storage: [], types: {}, namespaces: c.layout.namespaces };
     for (const name of [fullContractName].concat(c.inherit)) {
       layout.storage.unshift(...runData[name].layout.storage);
       Object.assign(layout.types, runData[name].layout.types);
@@ -147,7 +150,10 @@ export function getErrors(data: ValidationData, version: Version, opts: Validati
 
   const selfAndInheritedMethods = getAllMethods(runValidation, fullContractName);
 
-  if (!selfAndInheritedMethods.includes(upgradeToSignature)) {
+  if (
+    !selfAndInheritedMethods.includes(upgradeToSignature) &&
+    !selfAndInheritedMethods.includes(upgradeToAndCallSignature)
+  ) {
     errors.push({
       src: c.src,
       kind: 'missing-public-upgradeto',
@@ -188,7 +194,7 @@ export function isUpgradeSafe(data: ValidationData, version: Version): boolean {
 
 export function inferUUPS(runValidation: ValidationRunData, fullContractName: string): boolean {
   const methods = getAllMethods(runValidation, fullContractName);
-  return methods.includes(upgradeToSignature);
+  return methods.includes(upgradeToSignature) || methods.includes(upgradeToAndCallSignature);
 }
 
 export function inferProxyKind(data: ValidationData, version: Version): ProxyDeployment['kind'] {

package/src/validate/report.ts

@@ -57,9 +57,10 @@ const errorInfo: ErrorDescriptions<ValidationError> = {
     hint: () => `Update your dependency and run again`,
   },
   'missing-public-upgradeto': {
-    msg: () => `Implementation is missing a public \`upgradeTo(address)\` function`,
+    msg: () =>
+      `Implementation is missing a public \`upgradeTo(address)\` or \`upgradeToAndCall(address,bytes)\` function`,
     hint: () =>
-      `Inherit UUPSUpgradeable to include this function in your contract\n` +
+      `Inherit UUPSUpgradeable to include one or both of these functions in your contract\n` +
       `    @openzeppelin/contracts-upgradeable/proxy/utils/UUPSUpgradeable.sol`,
     link: 'https://zpl.in/upgrades/error-008',
   },

package/src/validate/run.ts

@@ -1,8 +1,10 @@
 import { Node } from 'solidity-ast/node';
 import { isNodeType, findAll, ASTDereferencer, astDereferencer } from 'solidity-ast/utils';
 import type { ContractDefinition, FunctionDefinition } from 'solidity-ast';
+import debug from '../utils/debug';
+import * as versions from 'compare-versions';
 
-import { SolcOutput, SolcBytecode } from '../solc-api';
+import { SolcOutput, SolcBytecode, SolcInput } from '../solc-api';
 import { SrcDecoder } from '../src-decoder';
 import { isNullish } from '../utils/is-nullish';
 import { getFunctionSignature } from '../utils/function';
@@ -12,6 +14,8 @@ import { extractStorageLayout } from '../storage/extract';
 import { StorageLayout } from '../storage/layout';
 import { getFullyQualifiedName } from '../utils/contract-name';
 import { getAnnotationArgs as getSupportedAnnotationArgs, getDocumentation } from '../utils/annotations';
+import { getStorageLocationAnnotation } from '../storage/namespace';
+import { UpgradesError } from '../error';
 
 export type ValidationRunData = Record<string, ContractValidation>;
 
@@ -116,7 +120,29 @@ function skipCheck(error: string, node: Node): boolean {
   return getAllowed(node, false).includes(error) || getAllowed(node, true).includes(error);
 }
 
-export function validate(solcOutput: SolcOutput, decodeSrc: SrcDecoder, solcVersion?: string): ValidationRunData {
+/**
+ * Runs validations on the given solc output.
+ *
+ * If `namespacedOutput` is provided, it is used to extract storage layout information for namespaced types.
+ * It must be from a compilation with the same sources as `solcInput` and `solcOutput`, but with storage variables
+ * injected for each namespaced struct so that the types are available in the storage layout. This can be obtained by
+ * calling the `makeNamespacedInput` function from this package to create modified solc input, then compiling
+ * that modified solc input to get the namespaced output.
+ *
+ * @param solcOutput Solc output to validate
+ * @param decodeSrc Source decoder for the original source code
+ * @param solcVersion The version of solc used to compile the contracts
+ * @param solcInput Solc input that the compiler was invoked with
+ * @param namespacedOutput Namespaced solc output to extract storage layout information for namespaced types
+ * @returns A record of validation results for each fully qualified contract name
+ */
+export function validate(
+  solcOutput: SolcOutput,
+  decodeSrc: SrcDecoder,
+  solcVersion?: string,
+  solcInput?: SolcInput,
+  namespacedOutput?: SolcOutput,
+): ValidationRunData {
   const validation: ValidationRunData = {};
   const fromId: Record<number, string> = {};
   const inheritIds: Record<string, number[]> = {};
@@ -128,6 +154,9 @@ export function validate(solcOutput: SolcOutput, decodeSrc: SrcDecoder, solcVers
   const selfDestructCache = initOpcodeCache();
 
   for (const source in solcOutput.contracts) {
+    checkNamespaceSolidityVersion(source, solcVersion, solcInput);
+    checkNamespacesOutsideContract(source, solcOutput, decodeSrc);
+
     for (const contractName in solcOutput.contracts[source]) {
       const bytecode = solcOutput.contracts[source][contractName].evm.bytecode;
       const version = bytecode.object === '' ? undefined : getVersion(bytecode.object);
@@ -176,7 +205,9 @@ export function validate(solcOutput: SolcOutput, decodeSrc: SrcDecoder, solcVers
           decodeSrc,
           deref,
           solcOutput.contracts[source][contractDef.name].storageLayout,
+          getNamespacedCompilationContext(source, contractDef, namespacedOutput),
         );
+
         validation[key].methods = [...findAll('FunctionDefinition', contractDef)]
           .filter(fnDef => ['external', 'public'].includes(fnDef.visibility))
           .map(fnDef => getFunctionSignature(fnDef, deref));
@@ -195,6 +226,82 @@ export function validate(solcOutput: SolcOutput, decodeSrc: SrcDecoder, solcVers
   return validation;
 }
 
+function checkNamespaceSolidityVersion(source: string, solcVersion?: string, solcInput?: SolcInput) {
+  if (solcInput === undefined) {
+    // This should only be missing if using an old version of the Hardhat or Truffle plugin.
+    // Even without this param, namespace layout checks would still occur if compiled with solc version >= 0.8.20
+    debug('Cannot check Solidity version for namespaces because solcInput is undefined');
+  } else {
+    // Solc versions older than 0.8.20 do not have documentation for structs.
+    // Use a regex to check for strings that look like namespace annotations, and if found, check that the compiler version is >= 0.8.20
+    const content = solcInput.sources[source].content;
+    const hasMatch = content !== undefined && content.match(/@custom:storage-location/);
+    if (hasMatch) {
+      if (solcVersion === undefined) {
+        throw new UpgradesError(
+          `${source}: Namespace annotations require Solidity version >= 0.8.20, but no solcVersion parameter was provided`,
+          () =>
+            `Structs with the @custom:storage-location annotation can only be used with Solidity version 0.8.20 or higher. Pass the solcVersion parameter to the validate function, or remove the annotation if the struct is not used for namespaced storage.`,
+        );
+      } else if (versions.compare(solcVersion, '0.8.20', '<')) {
+        throw new UpgradesError(
+          `${source}: Namespace annotations require Solidity version >= 0.8.20, but ${solcVersion} was used`,
+          () =>
+            `Structs with the @custom:storage-location annotation can only be used with Solidity version 0.8.20 or higher. Use a newer version of Solidity, or remove the annotation if the struct is not used for namespaced storage.`,
+        );
+      }
+    }
+  }
+}
+
+function checkNamespacesOutsideContract(source: string, solcOutput: SolcOutput, decodeSrc: SrcDecoder) {
+  for (const node of solcOutput.sources[source].ast.nodes) {
+    if (isNodeType('StructDefinition', node)) {
+      const storageLocation = getStorageLocationAnnotation(node);
+      if (storageLocation !== undefined) {
+        throw new UpgradesError(
+          `${decodeSrc(node)}: Namespace struct ${node.name} is defined outside of a contract`,
+          () =>
+            `Structs with the @custom:storage-location annotation must be defined within a contract. Move the struct definition into a contract, or remove the annotation if the struct is not used for namespaced storage.`,
+        );
+      }
+    }
+  }
+}
+
+function getNamespacedCompilationContext(
+  source: string,
+  contractDef: ContractDefinition,
+  namespacedOutput?: SolcOutput,
+) {
+  if (namespacedOutput === undefined || contractDef.canonicalName === undefined) {
+    return undefined;
+  }
+
+  if (namespacedOutput.sources[source] === undefined) {
+    throw new Error(`Source ${source} not found in namespaced solc output`);
+  }
+
+  const namespacedContractDef = namespacedOutput.sources[source].ast.nodes
+    .filter(isNodeType('ContractDefinition'))
+    .find(c => c.canonicalName === contractDef.canonicalName);
+
+  if (namespacedContractDef === undefined) {
+    throw new Error(`Contract definition with name ${contractDef.canonicalName} not found in namespaced solc output`);
+  }
+
+  const storageLayout = namespacedOutput.contracts[source][contractDef.name].storageLayout;
+  if (storageLayout === undefined) {
+    throw new Error(`Storage layout for contract ${contractDef.canonicalName} not found in namespaced solc output`);
+  }
+
+  return {
+    contractDef: namespacedContractDef,
+    deref: astDereferencer(namespacedOutput),
+    storageLayout: storageLayout,
+  };
+}
+
 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)) {

package/src/validate.test.ts

@@ -99,7 +99,10 @@ testOverride('UsesExplicitSafeExternalLibrary', 'transparent', { unsafeAllow: ['
 testValid('HasEmptyConstructor', 'uups', false);
 testValid('HasInternalUpgradeToFunction', 'uups', false);
 testValid('HasUpgradeToFunction', 'uups', true);
+testValid('HasInternalUpgradeToAndCallFunction', 'uups', false);
+testValid('HasUpgradeToAndCallFunction', 'uups', true);
 testValid('ParentHasUpgradeToFunction', 'uups', true);
+testValid('ParentHasUpgradeToAndCallFunction', 'uups', true);
 testValid('ChildOfProxiable', 'uups', true);
 
 testValid('HasNonEmptyConstructorNatspec1', 'transparent', true);