@openzeppelin/upgrades-core 1.43.0 → 1.44.0

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

@@ -0,0 +1,353 @@
+# Snapshot report for `src/storage-custom-layout.test.ts`
+
+The actual snapshot is saved in `storage-custom-layout.test.ts.snap`.
+
+Generated by [AVA](https://avajs.dev).
+
+## CustomLayout
+
+> Snapshot 1
+
+    {
+      baseSlot: '0x1',
+      namespaces: [],
+      storage: [
+        {
+          contract: 'Base',
+          label: 'x',
+          offset: 0,
+          renamedFrom: undefined,
+          retypedFrom: undefined,
+          slot: '1',
+          src: 'file.sol:1',
+          type: 't_uint256',
+        },
+        {
+          contract: 'CustomLayout',
+          label: 'y',
+          offset: 0,
+          renamedFrom: undefined,
+          retypedFrom: undefined,
+          slot: '2',
+          src: 'file.sol:1',
+          type: 't_uint256',
+        },
+      ],
+      types: [
+        [
+          't_uint256',
+          {
+            label: 'uint256',
+            members: undefined,
+            numberOfBytes: '32',
+          },
+        ],
+      ],
+    }
+
+## CustomLayout - fallback
+
+> Snapshot 1
+
+    {
+      baseSlot: '0x1',
+      namespaces: [],
+      storage: [
+        {
+          contract: 'CustomLayout',
+          label: 'y',
+          renamedFrom: undefined,
+          retypedFrom: undefined,
+          src: 'file.sol:1',
+          type: 't_uint256',
+        },
+      ],
+      types: [
+        [
+          't_uint256',
+          {
+            label: 'uint256',
+            members: undefined,
+          },
+        ],
+      ],
+    }
+
+## CustomLayout changed root - fallback - bad
+
+> Snapshot 1
+
+    `Base slot for custom storage layout changed from 0x0000000000000000000000000000000000000000000000000000000000000001 to 0x0000000000000000000000000000000000000000000000000000000000000002␊
+    ␊
+    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.`
+
+## CustomLayout changed root decimal - fallback - bad
+
+> Snapshot 1
+
+    `Base slot for custom storage layout changed from 0x0000000000000000000000000000000000000000000000000000000000000001 to 0x0000000000000000000000000000000000000000000000000000000000000002␊
+    ␊
+    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.`
+
+## CustomLayout changed root scientific notation - fallback - bad
+
+> Snapshot 1
+
+    `Base slot for custom storage layout changed from 0x0000000000000000000000000000000000000000000000000000000000000001 to 0x00000000000000000000000000000000000000000000000000000004a817c800␊
+    ␊
+    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.`
+
+## CustomLayout changed to default - fallback - bad
+
+> Snapshot 1
+
+    `Base slot for custom storage layout changed from 0x0000000000000000000000000000000000000000000000000000000000000001 to 0x0000000000000000000000000000000000000000000000000000000000000000␊
+    ␊
+    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.`
+
+## CustomLayout changed root - fallback - bad (no layout info)
+
+> Snapshot 1
+
+    `Base slot for custom storage layout changed from 0x0000000000000000000000000000000000000000000000000000000000000001 to 0x0000000000000000000000000000000000000000000000000000000000000000␊
+    ␊
+    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.`
+
+## CustomLayout changed to default - fallback - bad (no layout info)
+
+> Snapshot 1
+
+    `Base slot for custom storage layout changed from 0x0000000000000000000000000000000000000000000000000000000000000001 to 0x0000000000000000000000000000000000000000000000000000000000000000␊
+    ␊
+    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.`
+
+## CustomLayout unsupported node type
+
+> Snapshot 1
+
+    `file.sol:1: Custom storage layout expression with node type BinaryOperation is not currently supported␊
+    ␊
+    Please report this at https://zpl.in/upgrades/report and include the \`layout at\` expression from your contract.`
+
+## Namespaced - custom layout clash
+
+> Snapshot 1
+
+    `Custom layout for contract Namespaced_Custom_Layout_Clash clashes with the storage location for namespace erc7201:example.main␊
+    ␊
+    The namespace erc7201:example.main is defined in a struct at the following location:␊
+    - file.sol:1␊
+    ␊
+    Specify a different custom layout for the contract or use a different namespace for the struct.`
+
+## Namespaced - custom layout clash decimal
+
+> Snapshot 1
+
+    `Custom layout for contract Namespaced_Custom_Layout_Clash_Decimal clashes with the storage location for namespace erc7201:example.main␊
+    ␊
+    The namespace erc7201:example.main is defined in a struct at the following location:␊
+    - file.sol:1␊
+    ␊
+    Specify a different custom layout for the contract or use a different namespace for the struct.`
+
+## Namespaced - custom layout clash extra colon
+
+> Snapshot 1
+
+    `Custom layout for contract Namespaced_Custom_Layout_Clash_Extra_Colon clashes with the storage location for namespace erc7201:example:main␊
+    ␊
+    The namespace erc7201:example:main is defined in a struct at the following location:␊
+    - file.sol:1␊
+    ␊
+    Specify a different custom layout for the contract or use a different namespace for the struct.`
+
+## CustomLayout no namespace formula - ok
+
+> Snapshot 1
+
+    {
+      baseSlot: '0x183a6125c38840424c4a85fa12bab2ab606c4b6d0e7cc73c0c06ba5300eab500',
+      namespaces: [
+        [
+          'example.main',
+          [
+            {
+              contract: 'CustomLayout_No_Namespace_Formula',
+              label: 'x',
+              src: 'file.sol:1',
+              type: 't_uint256',
+            },
+            {
+              contract: 'CustomLayout_No_Namespace_Formula',
+              label: 'y',
+              src: 'file.sol:1',
+              type: 't_uint256',
+            },
+          ],
+        ],
+      ],
+      storage: [
+        {
+          contract: 'CustomLayout_No_Namespace_Formula',
+          label: 'a',
+          offset: 0,
+          renamedFrom: undefined,
+          retypedFrom: undefined,
+          slot: '10958655983261152271848436692291137275443024275653522991983264966744321209600',
+          src: 'file.sol:1',
+          type: 't_uint256',
+        },
+      ],
+      types: [
+        [
+          't_uint256',
+          {
+            label: 'uint256',
+            members: undefined,
+            numberOfBytes: '32',
+          },
+        ],
+      ],
+    }
+
+## CustomLayout unknown namespace formula - ok
+
+> Snapshot 1
+
+    {
+      baseSlot: '0x183a6125c38840424c4a85fa12bab2ab606c4b6d0e7cc73c0c06ba5300eab500',
+      namespaces: [
+        [
+          'erc0000:example.main',
+          [
+            {
+              contract: 'CustomLayout_Unknown_Namespace_Formula',
+              label: 'x',
+              src: 'file.sol:1',
+              type: 't_uint256',
+            },
+            {
+              contract: 'CustomLayout_Unknown_Namespace_Formula',
+              label: 'y',
+              src: 'file.sol:1',
+              type: 't_uint256',
+            },
+          ],
+        ],
+      ],
+      storage: [
+        {
+          contract: 'CustomLayout_Unknown_Namespace_Formula',
+          label: 'a',
+          offset: 0,
+          renamedFrom: undefined,
+          retypedFrom: undefined,
+          slot: '10958655983261152271848436692291137275443024275653522991983264966744321209600',
+          src: 'file.sol:1',
+          type: 't_uint256',
+        },
+      ],
+      types: [
+        [
+          't_uint256',
+          {
+            label: 'uint256',
+            members: undefined,
+            numberOfBytes: '32',
+          },
+        ],
+      ],
+    }
+
+## CustomLayout multiple namespaces
+
+> Snapshot 1
+
+    {
+      baseSlot: '0x1',
+      namespaces: [
+        [
+          'erc7201:example.b',
+          [
+            {
+              contract: 'NamespaceB',
+              label: 'x',
+              src: 'file.sol:1',
+              type: 't_uint256',
+            },
+          ],
+        ],
+        [
+          'erc7201:example.a',
+          [
+            {
+              contract: 'NamespaceA',
+              label: 'x',
+              src: 'file.sol:1',
+              type: 't_uint256',
+            },
+          ],
+        ],
+      ],
+      storage: [],
+      types: [
+        [
+          't_uint256',
+          {
+            label: 'uint256',
+            members: undefined,
+          },
+        ],
+      ],
+    }
+
+## Gap - changed root - fallback - bad (no layout info)
+
+> Snapshot 1
+
+    `Base slot for custom storage layout changed from 0x0000000000000000000000000000000000000000000000000000000000000000 to 0x0000000000000000000000000000000000000000000000000000000000000019␊
+    ␊
+    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.`

package/src/storage-memory-0.5.test.ts.md

@@ -9,6 +9,7 @@ Generated by [AVA](https://avajs.dev).
 > Snapshot 1
 
     {
+      baseSlot: undefined,
       namespaces: [],
       storage: [
         {
@@ -95,6 +96,7 @@ Generated by [AVA](https://avajs.dev).
 > Snapshot 1
 
     {
+      baseSlot: undefined,
       namespaces: [],
       storage: [
         {

package/src/storage-namespaced-layout.test.ts.md

@@ -9,6 +9,7 @@ Generated by [AVA](https://avajs.dev).
 > Snapshot 1
 
     {
+      baseSlot: undefined,
       namespaces: [
         [
           'erc7201:example.main',

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

@@ -9,6 +9,7 @@ Generated by [AVA](https://avajs.dev).
 > Snapshot 1
 
     {
+      baseSlot: undefined,
       namespaces: [
         [
           'erc7201:example.main',
@@ -45,6 +46,7 @@ Generated by [AVA](https://avajs.dev).
 > Snapshot 1
 
     {
+      baseSlot: undefined,
       namespaces: [
         [
           'erc7201:one',

package/src/storage.test.ts.md

@@ -9,6 +9,7 @@ Generated by [AVA](https://avajs.dev).
 > Snapshot 1
 
     {
+      baseSlot: undefined,
       namespaces: [],
       storage: [
         {
@@ -93,6 +94,7 @@ Generated by [AVA](https://avajs.dev).
 > Snapshot 1
 
     {
+      baseSlot: undefined,
       namespaces: [],
       storage: [
         {

package/src/utils/erc7201.test.ts

@@ -0,0 +1,10 @@
+import test from 'ava';
+
+import { calculateERC7201StorageLocation } from './erc7201';
+
+test('calculateERC7201StorageLocation', t => {
+  t.is(
+    calculateERC7201StorageLocation('example.main'),
+    '0x183a6125c38840424c4a85fa12bab2ab606c4b6d0e7cc73c0c06ba5300eab500',
+  );
+});

package/src/utils/erc7201.ts

@@ -0,0 +1,25 @@
+import { keccak256 } from 'ethereumjs-util';
+
+export const ERC7201_FORMULA_PREFIX = 'erc7201:';
+
+/**
+ * Returns the ERC-7201 storage location hash for a given namespace id using formula:
+ * keccak256(abi.encode(uint256(keccak256(bytes(id))) - 1)) & ~bytes32(uint256(0xff))
+ *
+ * @param id The namespace id, not including the 'erc7201:' prefix
+ * @returns The ERC-7201 storage location hash as a hex string
+ */
+export function calculateERC7201StorageLocation(id: string): string {
+  const firstHash = keccak256(Buffer.from(id));
+  const minusOne = BigInt(`0x${firstHash.toString('hex')}`) - 1n;
+  const minusOneBuffer = Buffer.from(minusOne.toString(16), 'hex');
+
+  const secondHash = keccak256(minusOneBuffer);
+
+  const mask = BigInt('0xff');
+  const masked = BigInt(`0x${secondHash.toString('hex')}`) & ~mask;
+
+  const padded = masked.toString(16).padStart(64, '0');
+
+  return `0x${padded}`;
+}

package/src/utils/integer-literals.test.ts

@@ -0,0 +1,73 @@
+import test from 'ava';
+
+import { normalizeUint256Literal } from './integer-literals';
+
+const ZEROES = '0x0000000000000000000000000000000000000000000000000000000000000000';
+
+test('falsy', t => {
+  t.is(normalizeUint256Literal(undefined), ZEROES);
+  t.is(normalizeUint256Literal(null), ZEROES);
+  t.is(normalizeUint256Literal(''), ZEROES);
+});
+
+test('hex', t => {
+  t.is(normalizeUint256Literal('0x12e3'), '0x00000000000000000000000000000000000000000000000000000000000012e3');
+});
+
+test('hex - leading zeroes', t => {
+  t.is(normalizeUint256Literal('0x0012e3'), '0x00000000000000000000000000000000000000000000000000000000000012e3');
+});
+
+test('hex - capital', t => {
+  t.is(normalizeUint256Literal('0x12E3'), '0x00000000000000000000000000000000000000000000000000000000000012e3');
+});
+
+test('decimal', t => {
+  t.is(normalizeUint256Literal('1234'), '0x00000000000000000000000000000000000000000000000000000000000004d2');
+});
+
+test('zeroes', t => {
+  t.is(normalizeUint256Literal('0'), ZEROES);
+  t.is(normalizeUint256Literal('0x000'), ZEROES);
+  t.is(normalizeUint256Literal(ZEROES), ZEROES);
+  t.is(normalizeUint256Literal('-0'), ZEROES);
+});
+
+test('underscores', t => {
+  t.is(normalizeUint256Literal('1_23_4'), '0x00000000000000000000000000000000000000000000000000000000000004d2');
+});
+
+test('scientific notation', t => {
+  t.is(normalizeUint256Literal('20e10'), '0x0000000000000000000000000000000000000000000000000000002e90edd000');
+});
+
+test('scientific notation - capital', t => {
+  t.is(normalizeUint256Literal('20E10'), '0x0000000000000000000000000000000000000000000000000000002e90edd000');
+});
+
+test('scientific notation - fractional base', t => {
+  t.is(normalizeUint256Literal('2.5e3'), '0x00000000000000000000000000000000000000000000000000000000000009c4');
+});
+
+test('scientific notation - negative exponent', t => {
+  t.is(normalizeUint256Literal('250000e-2'), '0x00000000000000000000000000000000000000000000000000000000000009c4');
+});
+
+test('scientific notation - invalid integer literal', t => {
+  const error = t.throws(() => normalizeUint256Literal('2e-3'));
+  t.is(error?.message, 'Invalid integer literal: 2e-3');
+});
+
+test('full hex', t => {
+  t.is(
+    normalizeUint256Literal('0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff'),
+    '0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff',
+  );
+});
+
+test('full hex with leading and trailing zeroes', t => {
+  t.is(
+    normalizeUint256Literal('0x00ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff00'),
+    '0x00ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff00',
+  );
+});

package/src/utils/integer-literals.ts

@@ -0,0 +1,29 @@
+import BigNumber from 'bignumber.js';
+
+/**
+ * Converts a Solidity unsigned integer literal according to https://docs.soliditylang.org/en/latest/types.html#rational-literals
+ * to a 64-byte padded hex string.
+ *
+ * Accepts decimal, hexadecimal, and scientific notation formats.
+ *
+ * If the input is null or undefined, returns '0x0000000000000000000000000000000000000000000000000000000000000000'.
+ *
+ * Assumes the input is a valid uint256-compatible literal for Solidity, and only performs minimal validation.
+ *
+ * @param literal Integer literal to convert
+ * @returns Hex string with 0x prefix, padded to 64 bytes with leading zeroes
+ */
+export function normalizeUint256Literal(literal: string | null | undefined): string {
+  if (!literal) {
+    return '0x0000000000000000000000000000000000000000000000000000000000000000';
+  }
+  const lowercaseNoUnderscores = literal.replace(/_/g, '').toLowerCase();
+
+  const parsed = new BigNumber(lowercaseNoUnderscores);
+  if (!parsed.isInteger()) {
+    throw new Error(`Invalid integer literal: ${literal}`);
+  }
+  const calculatedValueAsHex = parsed.toString(16);
+  const padded = calculatedValueAsHex.padStart(64, '0');
+  return `0x${padded}`;
+}

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

@@ -27,6 +27,13 @@ test('make namespaced input - solc 0.7', async t => {
   await testMakeNamespaced(origBuildInfo, t, '0.7.6');
 });
 
+test('make namespaced input - custom layout', async t => {
+  const origBuildInfo = await artifacts.getBuildInfo(
+    'contracts/test/NamespacedToModifyCustomLayout.sol:ExampleCustomLayout',
+  );
+  await testMakeNamespaced(origBuildInfo, t, '0.8.29');
+});
+
 async function testMakeNamespaced(
   origBuildInfo: BuildInfo | undefined,
   t: ExecutionContext<unknown>,

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

@@ -688,3 +688,53 @@ Generated by [AVA](https://avajs.dev).
         },
       },
     }
+
+## make namespaced input - custom layout
+
+> Snapshot 1
+
+    {
+      language: 'Solidity',
+      settings: {
+        evmVersion: 'paris',
+        optimizer: {
+          enabled: true,
+          runs: 200,
+        },
+        outputSelection: {
+          '*': {
+            '': [
+              'ast',
+            ],
+            '*': [
+              'storageLayout',
+            ],
+          },
+        },
+      },
+      sources: {
+        'contracts/test/NamespacedToModifyCustomLayout.sol': {
+          content: `// SPDX-License-Identifier: MIT␊
+          pragma solidity ^0.8.29;␊
+          ␊
+          abstract contract Base {␊
+          }␊
+          ␊
+          abstract contract ExampleCustomLayout  is Base {␊
+              /// @custom:storage-location erc7201:example.main␊
+              struct MainStorage {␊
+                  uint256 x;␊
+                  uint256 z;␊
+              } MainStorage $MainStorage_random;␊
+          }␊
+          ␊
+          abstract contract ExampleCustomLayout_DifferentSpecifierOrder is Base  {␊
+              /// @custom:storage-location erc7201:example.main␊
+              struct MainStorage {␊
+                  uint256 x;␊
+                  uint256 z;␊
+              } MainStorage $MainStorage_random;␊
+          }`,
+        },
+      },
+    }

package/src/utils/make-namespaced.ts

@@ -63,6 +63,11 @@ export function makeNamespacedInput(input: SolcInput, output: SolcOutput, _solcV
             modifications.push(makeInsertBefore(contractDef, 'abstract '));
           }
 
+          // Remove custom layout annotation
+          if (contractDef.storageLayout !== undefined) {
+            modifications.push(makeDelete(contractDef.storageLayout, orig));
+          }
+
           // Remove any calls to parent constructors from the inheritance list
           const inherits = contractDef.baseContracts;
           for (const inherit of inherits) {

package/src/utils/stabilize-layout.ts

@@ -18,5 +18,6 @@ export function stabilizeStorageLayout(layout: StorageLayout) {
           return [ns, items.map(item => ({ ...item, type: stabilizeTypeIdentifier(item.type) }))];
         })
       : undefined,
+    baseSlot: layout.baseSlot,
   };
 }

package/src/validate-initializers.test.ts

@@ -240,7 +240,7 @@ testAccepts('Recursive_Ok', 'transparent');
 testAccepts('ERC20_Ok', 'uups');
 testRejects('ERC20_Bad', 'uups', {
   contains: [
-    'Missing initializer calls for one or more parent contracts: `ERC20Upgradeable, ERC20PausableUpgradeable, OwnableUpgradeable, ERC20PermitUpgradeable`',
+    'Missing initializer calls for one or more parent contracts: `ERC20Upgradeable, OwnableUpgradeable, ERC20PermitUpgradeable`',
   ],
   count: 1,
 });