@openzeppelin/upgrades-core 1.43.0 → 1.44.1

package/src/storage/index.ts

@@ -6,6 +6,7 @@ import { StorageOperation, StorageItem, StorageLayoutComparator } from './compar
 import { LayoutCompatibilityReport } from './report';
 import { ValidationOptions, withValidationDefaults } from '../validate/overrides';
 import { logNote, logWarning } from '../utils/log';
+import { normalizeUint256Literal } from '../utils/integer-literals';
 
 export function assertStorageUpgradeSafe(
   original: StorageLayout,
@@ -36,11 +37,39 @@ export function assertStorageUpgradeSafe(
   }
 }
 
+function validateBaseSlotUnchanged(original: StorageLayout, updated: StorageLayout) {
+  const origNormalized = normalizeUint256Literal(original.baseSlot);
+  const updatedNormalized = normalizeUint256Literal(updated.baseSlot);
+
+  if (origNormalized !== updatedNormalized) {
+    throw new UpgradesError(
+      `Base slot for custom storage layout changed from ${origNormalized} to ${updatedNormalized}`,
+      () => `\
+Do not change the base slot during upgrades when using custom storage layout.
+
+If you need to change the base slot, ensure you also do the following:
+1. Adjust all storage variables to continue using their original slots.
+2. Configure your Solidity compiler options to include storage layouts according to https://docs.openzeppelin.com/upgrades-plugins/api-core#compile_contracts_with_storage_layouts
+3. Recompile both the original and updated contracts.
+4. Run the storage layout check again.`,
+    );
+  }
+}
+
 export function getStorageUpgradeReport(
   original: StorageLayout,
   updated: StorageLayout,
   opts: Required<ValidationOptions>,
 ): LayoutCompatibilityReport {
+  if (opts.unsafeSkipStorageCheck) {
+    return new LayoutCompatibilityReport([]);
+  }
+
+  if (original.storage.some(item => item.slot === undefined) || updated.storage.some(item => item.slot === undefined)) {
+    // Compiler was not configured to output detailed storage layout with slot information
+    validateBaseSlotUnchanged(original, updated);
+  }
+
   const originalDetailed = getDetailedLayout(original);
   const updatedDetailed = getDetailedLayout(updated);
   const originalDetailedNamespaces = getDetailedNamespacedLayout(original);

package/src/storage/layout.ts

@@ -12,6 +12,7 @@ export interface StorageLayout {
   types: Record<string, TypeItem>;
   flat?: boolean;
   namespaces?: Record<string, StorageItem[]>;
+  baseSlot?: string;
 }
 
 export type StorageField<Type = string> = StorageItem<Type> | StructMember<Type>;

package/src/storage/namespace.ts

@@ -8,6 +8,9 @@ import { Node } from 'solidity-ast/node';
 import { CompilationContext, getTypeMembers, loadLayoutType } from './extract';
 import { UpgradesError } from '../error';
 import * as versions from 'compare-versions';
+import { normalizeUint256Literal } from '../utils/integer-literals';
+import { calculateERC7201StorageLocation, ERC7201_FORMULA_PREFIX } from '../utils/erc7201';
+import { logWarning } from '../utils/log';
 
 /**
  * Loads a contract's namespaces and namespaced type information into the storage layout.
@@ -57,8 +60,10 @@ export function loadNamespaces(
     );
   }
 
+  warnIfCustomLayoutAndNamespacesFound(namespacesWithSrc, decodeSrc, origContext.contractDef);
+
   // Add to layout without the namespaced structs' src locations, since those are no longer needed
-  // as they were only used to give duplicate namespace errors above.
+  // as they were only used to give duplicate namespace errors in `addContractNamespacesWithSrc` above.
   layout.namespaces = Object.fromEntries(
     Object.entries(namespacesWithSrc).map(([id, namespaceWithSrc]) => [id, namespaceWithSrc.namespace]),
   );
@@ -78,6 +83,19 @@ Use a unique namespace id for each struct annotated with '@custom:storage-locati
   }
 }
 
+class CustomLayoutClashWithNamespaceError extends UpgradesError {
+  constructor(id: string, contractName: string, src: string) {
+    super(
+      `Custom layout for contract ${contractName} clashes with the storage location for namespace ${id}`,
+      () => `\
+The namespace ${id} is defined in a struct at the following location:
+- ${src}
+
+Specify a different custom layout for the contract or use a different namespace for the struct.`,
+    );
+  }
+}
+
 /**
  * Namespaced storage items, along with the original source location of the namespace struct.
  */
@@ -130,6 +148,8 @@ function addContractNamespacesWithSrc(
             origSrc,
           );
         } else {
+          checkCustomLayoutClashWithNamespace(origContractDef, storageLocation, leastDerivedContractName, origSrc);
+
           namespacesWithSrc[storageLocation] = {
             namespace: getNamespacedStorageItems(node, decodeSrc, layout, contractContext, origContractDef),
             src: origSrc,
@@ -140,6 +160,52 @@ function addContractNamespacesWithSrc(
   }
 }
 
+/**
+ * Checks if a custom layout's base slot clashes with a namespace's base slot, and throws an error if it does.
+ *
+ * @param contractDef The contract definition to check.
+ * @param storageLocation The namespace storage location string, e.g. `erc7201:<NAMESPACE_ID>`.
+ * @param contractName The name of the contract.
+ * @param src The original source location of the struct with the namespace.
+ * @throws CustomLayoutClashWithNamespaceError if the custom layout clashes with the namespace.
+ */
+function checkCustomLayoutClashWithNamespace(
+  contractDef: ContractDefinition,
+  storageLocation: string,
+  contractName: string,
+  src: string,
+) {
+  if (contractDef.storageLayout !== undefined && storageLocation.startsWith(ERC7201_FORMULA_PREFIX)) {
+    const namespaceId = storageLocation.substring(ERC7201_FORMULA_PREFIX.length);
+    const calculatedStorageLocation = calculateERC7201StorageLocation(namespaceId);
+    if (contractDef.storageLayout.baseSlotExpression.nodeType === 'Literal') {
+      const baseSlotNormalized = normalizeUint256Literal(contractDef.storageLayout.baseSlotExpression.value); // TODO: when Solidity supports an erc7201 helper function, also check that for clash
+      if (baseSlotNormalized === calculatedStorageLocation) {
+        throw new CustomLayoutClashWithNamespaceError(storageLocation, contractName, src);
+      }
+    }
+  }
+}
+
+function warnIfCustomLayoutAndNamespacesFound(
+  namespacesWithSrc: Record<string, NamespaceWithSrc>,
+  decodeSrc: SrcDecoder,
+  origContractDef: ContractDefinition,
+) {
+  // TODO: when Solidity supports an erc7201 helper function, only give this warning if the custom storage layout is not using the erc7201 helper function
+  if (Object.entries(namespacesWithSrc).length > 0 && origContractDef.storageLayout !== undefined) {
+    const contractName = origContractDef.canonicalName ?? origContractDef.name;
+    logWarning(
+      `${decodeSrc(origContractDef.storageLayout)}: Ensure custom storage layout does not overlap with namespaced storage layout.`,
+      [
+        `Contract \`${contractName}\` has both custom storage layout and namespaces.`,
+        'The Upgrades Plugin validates that they do not use the same base slot, but does not check for overlaps.',
+        "Ensure the base slot for the contract's `layout at` specifier is chosen such that its storage variables do not overlap with any namespaces.",
+      ],
+    );
+  }
+}
+
 /**
  * Gets the storage location string from the `@custom:storage-location` annotation.
  *

package/src/storage-0.8.test.ts.md

@@ -9,6 +9,7 @@ Generated by [AVA](https://avajs.dev).
 > Snapshot 1
 
     {
+      baseSlot: undefined,
       namespaces: [],
       storage: [
         {
@@ -47,6 +48,7 @@ Generated by [AVA](https://avajs.dev).
 > Snapshot 1
 
     {
+      baseSlot: undefined,
       namespaces: [],
       storage: [
         {
@@ -85,6 +87,7 @@ Generated by [AVA](https://avajs.dev).
 > Snapshot 1
 
     {
+      baseSlot: undefined,
       namespaces: [],
       storage: [
         {
@@ -120,6 +123,7 @@ Generated by [AVA](https://avajs.dev).
 > Snapshot 1
 
     {
+      baseSlot: undefined,
       namespaces: [],
       storage: [
         {

package/src/storage-custom-layout.test.ts

@@ -0,0 +1,358 @@
+import _test, { TestFn } from 'ava';
+import { ContractDefinition } from 'solidity-ast';
+import { findAll, astDereferencer } from 'solidity-ast/utils';
+import { artifacts } from 'hardhat';
+
+import { SolcOutput } from './solc-api';
+import { getStorageUpgradeErrors } from './storage';
+import { StorageLayout } from './storage/layout';
+import { extractStorageLayout } from './storage/extract';
+import { stabilizeStorageLayout } from './utils/stabilize-layout';
+
+interface Context {
+  extractStorageLayout: (contract: string) => ReturnType<typeof extractStorageLayout>;
+  extractStorageLayoutFallback: (contract: string) => ReturnType<typeof extractStorageLayout>;
+}
+
+const test = _test as TestFn<Context>;
+
+test.before(async t => {
+  const buildInfo = await artifacts.getBuildInfo('contracts/test/CustomLayout.sol:CustomLayout');
+  if (buildInfo === undefined) {
+    throw new Error('Build info not found');
+  }
+  const solcOutput: SolcOutput = buildInfo.output;
+  const contracts: Record<string, ContractDefinition> = {};
+  const storageLayouts: Record<string, StorageLayout> = {};
+  for (const def of findAll('ContractDefinition', solcOutput.sources['contracts/test/CustomLayout.sol'].ast)) {
+    contracts[def.name] = def;
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+    storageLayouts[def.name] = solcOutput.contracts['contracts/test/CustomLayout.sol'][def.name].storageLayout!;
+  }
+  const deref = astDereferencer(solcOutput);
+
+  t.context.extractStorageLayout = name =>
+    extractStorageLayout(contracts[name], dummyDecodeSrc, deref, storageLayouts[name]);
+
+  // For testing fallback behavior when storage layout is missing from compilation output
+  t.context.extractStorageLayoutFallback = name =>
+    extractStorageLayout(contracts[name], dummyDecodeSrc, deref, undefined);
+});
+
+const dummyDecodeSrc = () => 'file.sol:1';
+
+test('CustomLayout', t => {
+  const layout = t.context.extractStorageLayout('CustomLayout');
+  t.snapshot(stabilizeStorageLayout(layout));
+});
+
+test('CustomLayout - fallback', t => {
+  const layout = t.context.extractStorageLayoutFallback('CustomLayout');
+  t.snapshot(stabilizeStorageLayout(layout));
+});
+
+test('CustomLayout same root - ok', t => {
+  const v1 = t.context.extractStorageLayout('CustomLayout');
+  const v2 = t.context.extractStorageLayout('CustomLayout_Same_Root_Ok');
+  const comparison = getStorageUpgradeErrors(v1, v2);
+  t.deepEqual(comparison, []);
+});
+
+test('CustomLayout same root - fallback - ok', t => {
+  const v1 = t.context.extractStorageLayoutFallback('CustomLayout');
+  const v2 = t.context.extractStorageLayoutFallback('CustomLayout_Same_Root_Ok');
+  const comparison = getStorageUpgradeErrors(v1, v2);
+  t.deepEqual(comparison, []);
+});
+
+test('CustomLayout same root decimal - ok', t => {
+  const v1 = t.context.extractStorageLayout('CustomLayout');
+  const v2 = t.context.extractStorageLayout('CustomLayout_Same_Root_Decimal_Ok');
+  const comparison = getStorageUpgradeErrors(v1, v2);
+  t.deepEqual(comparison, []);
+});
+
+test('CustomLayout same root decimal - fallback - ok', t => {
+  const v1 = t.context.extractStorageLayoutFallback('CustomLayout');
+  const v2 = t.context.extractStorageLayoutFallback('CustomLayout_Same_Root_Decimal_Ok');
+  const comparison = getStorageUpgradeErrors(v1, v2);
+  t.deepEqual(comparison, []);
+});
+
+test('CustomLayout same root scientific notation - ok', t => {
+  const v1 = t.context.extractStorageLayout('CustomLayout');
+  const v2 = t.context.extractStorageLayout('CustomLayout_Same_Root_ScientificNotation_Ok');
+  const comparison = getStorageUpgradeErrors(v1, v2);
+  t.deepEqual(comparison, []);
+});
+
+test('CustomLayout same root scientific notation - fallback - ok', t => {
+  const v1 = t.context.extractStorageLayoutFallback('CustomLayout');
+  const v2 = t.context.extractStorageLayoutFallback('CustomLayout_Same_Root_ScientificNotation_Ok');
+  const comparison = getStorageUpgradeErrors(v1, v2);
+  t.deepEqual(comparison, []);
+});
+
+test('CustomLayout changed root - bad', t => {
+  const v1 = t.context.extractStorageLayout('CustomLayout');
+  const v2 = t.context.extractStorageLayout('CustomLayout_Changed_Root_Bad');
+  const comparison = getStorageUpgradeErrors(v1, v2);
+  t.like(comparison, {
+    length: 2,
+    0: {
+      kind: 'layoutchange',
+      change: {
+        slot: {
+          from: '1',
+          to: '2',
+        },
+      },
+      original: { label: 'x' },
+      updated: { label: 'x' },
+    },
+    1: {
+      kind: 'layoutchange',
+      change: {
+        slot: {
+          from: '2',
+          to: '3',
+        },
+      },
+      original: { label: 'y' },
+      updated: { label: 'y' },
+    },
+  });
+});
+
+test('CustomLayout changed root - fallback - bad', t => {
+  const v1 = t.context.extractStorageLayoutFallback('CustomLayout');
+  const v2 = t.context.extractStorageLayoutFallback('CustomLayout_Changed_Root_Bad');
+  const error = t.throws(() => getStorageUpgradeErrors(v1, v2));
+  t.snapshot(error?.message);
+});
+
+test('CustomLayout changed root decimal - bad', t => {
+  const v1 = t.context.extractStorageLayout('CustomLayout');
+  const v2 = t.context.extractStorageLayout('CustomLayout_Changed_Root_Decimal_Bad');
+  const comparison = getStorageUpgradeErrors(v1, v2);
+  t.like(comparison, {
+    length: 2,
+    0: {
+      kind: 'layoutchange',
+      change: {
+        slot: {
+          from: '1',
+          to: '2',
+        },
+      },
+      original: { label: 'x' },
+      updated: { label: 'x' },
+    },
+    1: {
+      kind: 'layoutchange',
+      change: {
+        slot: {
+          from: '2',
+          to: '3',
+        },
+      },
+      original: { label: 'y' },
+      updated: { label: 'y' },
+    },
+  });
+});
+
+test('CustomLayout changed root decimal - fallback - bad', t => {
+  const v1 = t.context.extractStorageLayoutFallback('CustomLayout');
+  const v2 = t.context.extractStorageLayoutFallback('CustomLayout_Changed_Root_Decimal_Bad');
+  const error = t.throws(() => getStorageUpgradeErrors(v1, v2));
+  t.snapshot(error?.message);
+});
+
+test('CustomLayout changed root scientific notation - bad', t => {
+  const v1 = t.context.extractStorageLayout('CustomLayout');
+  const v2 = t.context.extractStorageLayout('CustomLayout_Changed_Root_ScientificNotation_Bad');
+  const comparison = getStorageUpgradeErrors(v1, v2);
+  t.like(comparison, {
+    length: 2,
+    0: {
+      kind: 'layoutchange',
+      change: {
+        slot: {
+          from: '1',
+          to: '20000000000',
+        },
+      },
+      original: { label: 'x' },
+      updated: { label: 'x' },
+    },
+    1: {
+      kind: 'layoutchange',
+      change: {
+        slot: {
+          from: '2',
+          to: '20000000001',
+        },
+      },
+      original: { label: 'y' },
+      updated: { label: 'y' },
+    },
+  });
+});
+
+test('CustomLayout changed root scientific notation - fallback - bad', t => {
+  const v1 = t.context.extractStorageLayoutFallback('CustomLayout');
+  const v2 = t.context.extractStorageLayoutFallback('CustomLayout_Changed_Root_ScientificNotation_Bad');
+  const error = t.throws(() => getStorageUpgradeErrors(v1, v2));
+  t.snapshot(error?.message);
+});
+
+test('CustomLayout changed to default - bad', t => {
+  const v1 = t.context.extractStorageLayout('CustomLayout');
+  const v2 = t.context.extractStorageLayout('CustomLayout_Changed_To_Default_Bad');
+  const comparison = getStorageUpgradeErrors(v1, v2);
+  t.like(comparison, {
+    length: 2,
+    0: {
+      kind: 'layoutchange',
+      change: {
+        slot: {
+          from: '1',
+          to: '0',
+        },
+      },
+      original: { label: 'x' },
+      updated: { label: 'x' },
+    },
+    1: {
+      kind: 'layoutchange',
+      change: {
+        slot: {
+          from: '2',
+          to: '1',
+        },
+      },
+      original: { label: 'y' },
+      updated: { label: 'y' },
+    },
+  });
+});
+
+test('CustomLayout changed to default - fallback - bad', t => {
+  const v1 = t.context.extractStorageLayoutFallback('CustomLayout');
+  const v2 = t.context.extractStorageLayoutFallback('CustomLayout_Changed_To_Default_Bad');
+  const error = t.throws(() => getStorageUpgradeErrors(v1, v2));
+  t.snapshot(error?.message);
+});
+
+test('CustomLayout changed root - ok', t => {
+  const v1 = t.context.extractStorageLayout('CustomLayout');
+  const v2 = t.context.extractStorageLayout('CustomLayout_Changed_Root_Ok');
+  const comparison = getStorageUpgradeErrors(v1, v2);
+  t.deepEqual(comparison, []);
+});
+
+test('CustomLayout changed root - fallback - bad (no layout info)', t => {
+  const v1 = t.context.extractStorageLayoutFallback('CustomLayout');
+  const v2 = t.context.extractStorageLayoutFallback('CustomLayout_Changed_Root_Ok');
+  const error = t.throws(() => getStorageUpgradeErrors(v1, v2));
+  t.snapshot(error?.message);
+});
+
+test('CustomLayout changed root - fallback - unsafeSkipStorageCheck', t => {
+  const v1 = t.context.extractStorageLayoutFallback('CustomLayout');
+  const v2 = t.context.extractStorageLayoutFallback('CustomLayout_Changed_Root_Ok');
+  const comparison = getStorageUpgradeErrors(v1, v2, { unsafeSkipStorageCheck: true });
+  t.deepEqual(comparison, []);
+});
+
+test('CustomLayout changed to default - ok', t => {
+  const v1 = t.context.extractStorageLayout('CustomLayout');
+  const v2 = t.context.extractStorageLayout('CustomLayout_Changed_To_Default_Ok');
+  const comparison = getStorageUpgradeErrors(v1, v2);
+  t.deepEqual(comparison, []);
+});
+
+test('CustomLayout changed to default - fallback - bad (no layout info)', t => {
+  const v1 = t.context.extractStorageLayoutFallback('CustomLayout');
+  const v2 = t.context.extractStorageLayoutFallback('CustomLayout_Changed_To_Default_Ok');
+  const error = t.throws(() => getStorageUpgradeErrors(v1, v2));
+  t.snapshot(error?.message);
+});
+
+test('CustomLayout changed to default - fallback - unsafeSkipStorageCheck', t => {
+  const v1 = t.context.extractStorageLayoutFallback('CustomLayout');
+  const v2 = t.context.extractStorageLayoutFallback('CustomLayout_Changed_To_Default_Ok');
+  const comparison = getStorageUpgradeErrors(v1, v2, { unsafeSkipStorageCheck: true });
+  t.deepEqual(comparison, []);
+});
+
+test('CustomLayout unsupported node type', t => {
+  const error = t.throws(() => t.context.extractStorageLayout('CustomLayout_Unsupported_Node_Type'));
+  t.snapshot(error?.message);
+});
+
+test('Namespaced - default to custom layout without regular variables - ok', t => {
+  const v1 = t.context.extractStorageLayout('Namespaced_Default_Layout');
+  const v2 = t.context.extractStorageLayout('Namespaced_Custom_Layout_Unaffected');
+  const comparison = getStorageUpgradeErrors(v1, v2);
+  t.deepEqual(comparison, []);
+});
+
+test('Namespaced - default to custom layout without regular variables - fallback - ok', t => {
+  const v1 = t.context.extractStorageLayoutFallback('Namespaced_Default_Layout');
+  const v2 = t.context.extractStorageLayoutFallback('Namespaced_Custom_Layout_Unaffected');
+  const comparison = getStorageUpgradeErrors(v1, v2);
+  t.deepEqual(comparison, []);
+});
+
+test('Namespaced - custom layout clash', t => {
+  const error = t.throws(() => t.context.extractStorageLayout('Namespaced_Custom_Layout_Clash'));
+  t.snapshot(error?.message);
+});
+
+test('Namespaced - custom layout clash decimal', t => {
+  const error = t.throws(() => t.context.extractStorageLayout('Namespaced_Custom_Layout_Clash_Decimal'));
+  t.snapshot(error?.message);
+});
+
+test('Namespaced - custom layout clash extra colon', t => {
+  const error = t.throws(() => t.context.extractStorageLayout('Namespaced_Custom_Layout_Clash_Extra_Colon'));
+  t.snapshot(error?.message);
+});
+
+test('CustomLayout no namespace formula - ok', t => {
+  const layout = t.context.extractStorageLayout('CustomLayout_No_Namespace_Formula');
+  t.snapshot(stabilizeStorageLayout(layout));
+});
+
+test('CustomLayout unknown namespace formula - ok', t => {
+  const layout = t.context.extractStorageLayout('CustomLayout_Unknown_Namespace_Formula');
+  t.snapshot(stabilizeStorageLayout(layout));
+});
+
+test('CustomLayout multiple namespaces', t => {
+  const layout = t.context.extractStorageLayout('CustomLayout_Multiple_Namespaces');
+  t.snapshot(stabilizeStorageLayout(layout));
+});
+
+test('Gap - changed root - ok', t => {
+  const v1 = t.context.extractStorageLayout('Gap');
+  const v2 = t.context.extractStorageLayout('Gap_Changed_Root_Ok');
+  const comparison = getStorageUpgradeErrors(v1, v2);
+  t.deepEqual(comparison, []);
+});
+
+test('Gap - changed root - fallback - bad (no layout info)', t => {
+  const v1 = t.context.extractStorageLayoutFallback('Gap');
+  const v2 = t.context.extractStorageLayoutFallback('Gap_Changed_Root_Ok');
+  const error = t.throws(() => getStorageUpgradeErrors(v1, v2));
+  t.snapshot(error?.message);
+});
+
+test('Gap - changed root - fallback - unsafeSkipStorageCheck', t => {
+  const v1 = t.context.extractStorageLayoutFallback('Gap');
+  const v2 = t.context.extractStorageLayoutFallback('Gap_Changed_Root_Ok');
+  const comparison = getStorageUpgradeErrors(v1, v2, { unsafeSkipStorageCheck: true });
+  t.deepEqual(comparison, []);
+});