@openzeppelin/upgrades-core 1.45.0 → 1.47.0

package/src/storage-struct-member-renamed-retyped.test.ts

@@ -0,0 +1,299 @@
+import _test, { TestFn } from 'ava';
+import { artifacts } from 'hardhat';
+import { BuildInfo } from 'hardhat/types';
+import { findAll } from 'solidity-ast/utils';
+
+import { SolcInput, SolcOutput } from './solc-api';
+import { validate, ValidationRunData } from './validate';
+import { withValidationDefaults } from './validate/overrides';
+import { solcInputOutputDecoder } from './src-decoder';
+import { getStorageUpgradeErrors, getStorageUpgradeReport } from './storage';
+import { StorageLayout, isStructMembers } from './storage/layout';
+import { stabilizeStorageLayout } from './utils/stabilize-layout';
+
+const source = 'contracts/test/StructMemberRenamedRetyped.sol';
+
+interface Context {
+  buildInfo: BuildInfo;
+  validate: (solcInput?: SolcInput, solcOutput?: SolcOutput) => ValidationRunData;
+  layout: (contract: string) => StorageLayout;
+}
+
+const test = _test as TestFn<Context>;
+
+test.before(async t => {
+  const buildInfo = await artifacts.getBuildInfo(`${source}:StructMemberRenamedRetypedV1`);
+  if (buildInfo === undefined) {
+    throw new Error('Build info not found');
+  }
+  t.context.buildInfo = buildInfo;
+  // The source decoder always uses the original build info, since the tests below only modify the input in ways
+  // that keep line numbers unchanged.
+  const decodeSrc = solcInputOutputDecoder(buildInfo.input, buildInfo.output);
+  t.context.validate = (solcInput = buildInfo.input, solcOutput = buildInfo.output) =>
+    validate(solcOutput, decodeSrc, buildInfo.solcVersion, solcInput);
+  const validation = t.context.validate();
+  t.context.layout = contract => validation[`${source}:${contract}`].layout;
+});
+
+function getStructMembers(layout: StorageLayout, label: string) {
+  const members = Object.values(layout.types).find(type => type.label === label)?.members;
+  if (members === undefined || !isStructMembers(members)) {
+    throw new Error(`Struct members not found for ${label}`);
+  }
+  return members;
+}
+
+/**
+ * Replaces the given comment inside a struct body with code of the same length, so that the AST offsets still line up
+ * but the text between two members is not whitespace or comments, as it would be with syntax that is not supported.
+ */
+function withUnexpectedStructSyntax(solcInput: SolcInput, comment: string): SolcInput {
+  const content = solcInput.sources[source].content;
+  if (content === undefined || !content.includes(comment)) {
+    throw new Error(`Comment ${comment} not found in ${source}`);
+  }
+  const code = 'uint256 q;'.padEnd(comment.length);
+  return { ...solcInput, sources: { ...solcInput.sources, [source]: { content: content.replace(comment, code) } } };
+}
+
+test('layout', t => {
+  t.snapshot(stabilizeStorageLayout(t.context.layout('StructMemberRenamedRetypedV2')));
+});
+
+test('upgrade ok', t => {
+  const v1 = t.context.layout('StructMemberRenamedRetypedV1');
+  const v2 = t.context.layout('StructMemberRenamedRetypedV2');
+  t.deepEqual(getStorageUpgradeErrors(v1, v2), []);
+});
+
+test('exact map', t => {
+  const members = getStructMembers(t.context.layout('StructMemberExactMap'), 'struct StructMemberExactMap.S');
+  t.is(members.length, 5);
+  for (const member of members) {
+    t.is(member.renamedFrom, `old_${member.label}`);
+    t.is(member.retypedFrom, undefined);
+  }
+});
+
+test('wrong retype', t => {
+  const v1 = t.context.layout('StructMemberBadV1');
+  const v2 = t.context.layout('StructMemberWrongRetypeV2');
+  t.like(getStorageUpgradeErrors(v1, v2), {
+    length: 1,
+    0: {
+      kind: 'typechange',
+      change: {
+        kind: 'struct members',
+        ops: {
+          length: 1,
+          0: { kind: 'typechange', original: { label: 'x' }, updated: { label: 'x', retypedFrom: 'address' } },
+        },
+      },
+      original: { label: 's' },
+      updated: { label: 's' },
+    },
+  });
+});
+
+test('retype with layout change', t => {
+  // A retype annotation that names the original type does not allow the member's size to change
+  const v1 = t.context.layout('StructMemberRetypeLayoutChangeV1');
+  const v2 = t.context.layout('StructMemberRetypeLayoutChangeV2');
+  t.like(getStorageUpgradeErrors(v1, v2), {
+    length: 1,
+    0: {
+      kind: 'typechange',
+      change: {
+        kind: 'struct members',
+        ops: {
+          length: 1,
+          0: {
+            kind: 'layoutchange',
+            original: { label: 'y' },
+            updated: { label: 'y', retypedFrom: 'uint256' },
+            change: { bytes: { from: '32', to: '16' } },
+          },
+        },
+      },
+      original: { label: 's' },
+      updated: { label: 's' },
+    },
+  });
+});
+
+test('annotation on the wrong member', t => {
+  // The annotation makes `x` match the original `y` with a different type, and `x` and `z` are left unmatched
+  const v1 = t.context.layout('StructMemberBadV1');
+  const v2 = t.context.layout('StructMemberWrongMemberV2');
+  t.like(getStorageUpgradeErrors(v1, v2), {
+    length: 1,
+    0: {
+      kind: 'typechange',
+      change: {
+        kind: 'struct members',
+        ops: {
+          length: 3,
+          0: { kind: 'delete', original: { label: 'x' } },
+          1: { kind: 'typechange', original: { label: 'y' }, updated: { label: 'x', renamedFrom: 'y' } },
+          2: { kind: 'insert', updated: { label: 'z' } },
+        },
+      },
+      original: { label: 's' },
+      updated: { label: 's' },
+    },
+  });
+});
+
+test('stale rename annotation', t => {
+  const v1 = t.context.layout('StructMemberBadV1');
+  const v2 = t.context.layout('StructMemberStaleRenameV2');
+  t.like(getStorageUpgradeErrors(v1, v2), {
+    length: 1,
+    0: {
+      kind: 'typechange',
+      change: {
+        kind: 'struct members',
+        ops: {
+          length: 1,
+          0: { kind: 'rename', original: { label: 'y' }, updated: { label: 'y', renamedFrom: 'q' } },
+        },
+      },
+      original: { label: 's' },
+      updated: { label: 's' },
+    },
+  });
+});
+
+test('unannotated rename and retype', t => {
+  const v1 = t.context.layout('StructMemberBadV1');
+  const v2 = t.context.layout('StructMemberUnannotatedV2');
+  t.like(getStorageUpgradeErrors(v1, v2), {
+    length: 1,
+    0: {
+      kind: 'typechange',
+      change: {
+        kind: 'struct members',
+        ops: {
+          length: 2,
+          0: { kind: 'typechange', original: { label: 'x' }, updated: { label: 'x' } },
+          1: { kind: 'rename', original: { label: 'y' }, updated: { label: 'z' } },
+        },
+      },
+      original: { label: 's' },
+      updated: { label: 's' },
+    },
+  });
+});
+
+test('annotated members without layout info', t => {
+  // Without the compiler's storage layout, members have no slots. A retype that is not known to be compatible is then uncertain.
+  const solcOutput: SolcOutput = JSON.parse(JSON.stringify(t.context.buildInfo.output));
+  for (const contracts of Object.values(solcOutput.contracts)) {
+    for (const contract of Object.values(contracts)) {
+      delete contract.storageLayout;
+    }
+  }
+  const validation = t.context.validate(undefined, solcOutput);
+  const v1 = validation[`${source}:StructMemberRenamedRetypedV1`].layout;
+  const v2 = validation[`${source}:StructMemberRenamedRetypedV2`].layout;
+  const report = getStorageUpgradeReport(v1, v2, withValidationDefaults({}));
+  t.false(report.ok);
+  t.like(report.ops, {
+    length: 4,
+    0: { kind: 'typechange', original: { label: 's' } },
+    1: { kind: 'typechange', original: { label: 'm' } },
+    2: { kind: 'typechange', original: { label: 'arr' } },
+    3: { kind: 'typechange', original: { label: 'other' } },
+  });
+  t.true(
+    report.explain().includes('Layout could have changed for `x` (bytes32 -> struct TransientSlot.TBytes32)'),
+    report.explain(),
+  );
+  t.snapshot(report.explain());
+});
+
+test('annotations are not read without source content', t => {
+  const { input } = t.context.buildInfo;
+  const sources = Object.fromEntries(Object.keys(input.sources).map(path => [path, {}]));
+  const validation = t.context.validate({ ...input, sources });
+  const v1 = validation[`${source}:StructMemberRenamedRetypedV1`].layout;
+  const v2 = validation[`${source}:StructMemberRenamedRetypedV2`].layout;
+  t.like(getStorageUpgradeErrors(v1, v2), {
+    length: 5,
+    0: { kind: 'typechange', original: { label: 's' } },
+    1: { kind: 'typechange', original: { label: 'm' } },
+    2: { kind: 'typechange', original: { label: 'arr' } },
+    3: { kind: 'typechange', original: { label: 'outer' } },
+    4: { kind: 'typechange', original: { label: 'other' } },
+  });
+});
+
+test('unexpected syntax in struct with annotations', t => {
+  const { input, output } = t.context.buildInfo;
+  const structDef = [...findAll('StructDefinition', output.sources[source].ast)].find(
+    s => s.canonicalName === 'StructMemberUnreadableAnnotated.S',
+  );
+  if (structDef === undefined) {
+    throw new Error('Struct not found');
+  }
+  const structSrc = solcInputOutputDecoder(input, output)(structDef);
+
+  const error = t.throws(() => t.context.validate(withUnexpectedStructSyntax(input, '// 12345678')));
+  t.true(
+    error?.message.includes(
+      `${structSrc}: Could not read storage annotations on members of struct \`StructMemberUnreadableAnnotated.S\``,
+    ),
+    error?.message,
+  );
+  t.true(
+    error?.message.includes(
+      'Please report this at https://zpl.in/upgrades/report and include the struct definition from your contract.',
+    ),
+    error?.message,
+  );
+});
+
+test('unexpected syntax in struct without annotations', t => {
+  const validation = t.context.validate(withUnexpectedStructSyntax(t.context.buildInfo.input, '// 87654321'));
+  const layout = validation[`${source}:StructMemberUnreadableUnannotated`].layout;
+  t.like(getStructMembers(layout, 'struct StructMemberUnreadableUnannotated.S'), {
+    length: 2,
+    0: { label: 'b', renamedFrom: undefined, retypedFrom: undefined },
+    1: { label: 'c', renamedFrom: undefined, retypedFrom: undefined },
+  });
+  // Other structs are unaffected
+  const v1 = validation[`${source}:StructMemberRenamedRetypedV1`].layout;
+  const v2 = validation[`${source}:StructMemberRenamedRetypedV2`].layout;
+  t.deepEqual(getStorageUpgradeErrors(v1, v2), []);
+});
+
+test('unexpected syntax in struct with other annotations', t => {
+  const validation = t.context.validate(withUnexpectedStructSyntax(t.context.buildInfo.input, '// 13572468'));
+  const layout = validation[`${source}:StructMemberUnreadableOtherAnnotation`].layout;
+  t.like(getStructMembers(layout, 'struct StructMemberUnreadableOtherAnnotation.S'), {
+    length: 2,
+    0: { label: 'b', renamedFrom: undefined, retypedFrom: undefined },
+    1: { label: 'c', renamedFrom: undefined, retypedFrom: undefined },
+  });
+});
+
+test('multiple annotations in a doc block without line prefixes', t => {
+  const layout = t.context.layout('StateVariableDocBlock');
+  t.like(layout.storage, { length: 1, 0: { label: 'x', renamedFrom: 'a', retypedFrom: 'uint8' } });
+});
+
+test('stale rename annotation report', t => {
+  const v1 = t.context.layout('StructMemberBadV1');
+  const v2 = t.context.layout('StructMemberStaleRenameV2');
+  const report = getStorageUpgradeReport(v1, v2, withValidationDefaults({}));
+  t.false(report.ok);
+  t.is(
+    report.explain(),
+    `${v2.storage[0].src}: Upgraded \`s\` to an incompatible type\n` +
+      '  - Bad upgrade from struct StructMemberBadV1.S to struct StructMemberStaleRenameV2.S\n' +
+      '  - In struct StructMemberStaleRenameV2.S\n' +
+      "    - `y` has a '@custom:oz-renamed-from q' annotation, but it was not renamed\n" +
+      '      > If the annotation is left over from an earlier upgrade, remove it.',
+  );
+});

package/src/storage-struct-member-renamed-retyped.test.ts.md

@@ -0,0 +1,260 @@
+# Snapshot report for `src/storage-struct-member-renamed-retyped.test.ts`
+
+The actual snapshot is saved in `storage-struct-member-renamed-retyped.test.ts.snap`.
+
+Generated by [AVA](https://avajs.dev).
+
+## layout
+
+> Snapshot 1
+
+    {
+      baseSlot: undefined,
+      namespaces: [],
+      storage: [
+        {
+          contract: 'StructMemberRenamedRetypedV2',
+          label: 's',
+          offset: 0,
+          renamedFrom: undefined,
+          retypedFrom: undefined,
+          slot: '0',
+          src: 'contracts/test/StructMemberRenamedRetyped.sol:62',
+          type: 't_struct(S)storage',
+        },
+        {
+          contract: 'StructMemberRenamedRetypedV2',
+          label: 'm',
+          offset: 0,
+          renamedFrom: undefined,
+          retypedFrom: undefined,
+          slot: '5',
+          src: 'contracts/test/StructMemberRenamedRetyped.sol:63',
+          type: 't_mapping(t_uint256,t_struct(S)storage)',
+        },
+        {
+          contract: 'StructMemberRenamedRetypedV2',
+          label: 'arr',
+          offset: 0,
+          renamedFrom: undefined,
+          retypedFrom: undefined,
+          slot: '6',
+          src: 'contracts/test/StructMemberRenamedRetyped.sol:64',
+          type: 't_array(t_struct(S)storage)dyn_storage',
+        },
+        {
+          contract: 'StructMemberRenamedRetypedV2',
+          label: 'outer',
+          offset: 0,
+          renamedFrom: undefined,
+          retypedFrom: undefined,
+          slot: '7',
+          src: 'contracts/test/StructMemberRenamedRetyped.sol:65',
+          type: 't_struct(Outer)storage',
+        },
+        {
+          contract: 'StructMemberRenamedRetypedV2',
+          label: 'other',
+          offset: 0,
+          renamedFrom: undefined,
+          retypedFrom: undefined,
+          slot: '10',
+          src: 'contracts/test/StructMemberRenamedRetyped.sol:66',
+          type: 't_struct(OtherFileV2)storage',
+        },
+      ],
+      types: [
+        [
+          't_array(t_struct(S)storage)dyn_storage',
+          {
+            label: 'struct StructMemberRenamedRetypedV2.S[]',
+            members: undefined,
+            numberOfBytes: '32',
+          },
+        ],
+        [
+          't_bool',
+          {
+            label: 'bool',
+            members: undefined,
+            numberOfBytes: '1',
+          },
+        ],
+        [
+          't_bytes32',
+          {
+            label: 'bytes32',
+            members: undefined,
+            numberOfBytes: '32',
+          },
+        ],
+        [
+          't_mapping(t_uint256,t_struct(S)storage)',
+          {
+            label: 'mapping(uint256 => struct StructMemberRenamedRetypedV2.S)',
+            members: undefined,
+            numberOfBytes: '32',
+          },
+        ],
+        [
+          't_struct(Inner)storage',
+          {
+            label: 'struct StructMemberRenamedRetypedV2.Inner',
+            members: [
+              {
+                label: 'g',
+                offset: 0,
+                renamedFrom: 'a',
+                retypedFrom: 'uint8',
+                slot: '0',
+                type: 't_bool',
+              },
+              {
+                label: 'bb',
+                offset: 0,
+                renamedFrom: 'b',
+                slot: '1',
+                type: 't_bytes32',
+              },
+            ],
+            numberOfBytes: '64',
+          },
+        ],
+        [
+          't_struct(OtherFileV2)storage',
+          {
+            label: 'struct OtherFileV2',
+            members: [
+              {
+                label: 'a',
+                offset: 0,
+                retypedFrom: 'bytes32',
+                slot: '0',
+                type: 't_struct(TBytes32)storage',
+              },
+              {
+                label: 'c',
+                offset: 0,
+                renamedFrom: 'b',
+                slot: '1',
+                type: 't_uint256',
+              },
+            ],
+            numberOfBytes: '64',
+          },
+        ],
+        [
+          't_struct(Outer)storage',
+          {
+            label: 'struct StructMemberRenamedRetypedV2.Outer',
+            members: [
+              {
+                label: 'inner',
+                offset: 0,
+                slot: '0',
+                type: 't_struct(Inner)storage',
+              },
+              {
+                label: 'n',
+                offset: 0,
+                slot: '2',
+                type: 't_uint256',
+              },
+            ],
+            numberOfBytes: '96',
+          },
+        ],
+        [
+          't_struct(S)storage',
+          {
+            label: 'struct StructMemberRenamedRetypedV2.S',
+            members: [
+              {
+                label: 'x',
+                offset: 0,
+                retypedFrom: 'bytes32',
+                slot: '0',
+                type: 't_struct(TBytes32)storage',
+              },
+              {
+                label: 'z',
+                offset: 0,
+                renamedFrom: 'y',
+                slot: '1',
+                type: 't_uint256',
+              },
+              {
+                label: 'f',
+                offset: 0,
+                retypedFrom: 'uint8',
+                slot: '2',
+                type: 't_bool',
+              },
+              {
+                label: 'c',
+                offset: 0,
+                slot: '3',
+                type: 't_uint256',
+              },
+              {
+                label: 'd',
+                offset: 0,
+                renamedFrom: 'oldD',
+                slot: '4',
+                type: 't_uint256',
+              },
+            ],
+            numberOfBytes: '160',
+          },
+        ],
+        [
+          't_struct(TBytes32)storage',
+          {
+            label: 'struct TransientSlot.TBytes32',
+            members: [
+              {
+                label: '_placeholder',
+                offset: 0,
+                slot: '0',
+                type: 't_bytes32',
+              },
+            ],
+            numberOfBytes: '32',
+          },
+        ],
+        [
+          't_uint256',
+          {
+            label: 'uint256',
+            members: undefined,
+            numberOfBytes: '32',
+          },
+        ],
+      ],
+    }
+
+## annotated members without layout info
+
+> Snapshot 1
+
+    `contracts/test/StructMemberRenamedRetyped.sol:62: Upgraded \`s\` to an incompatible type␊
+      - Bad upgrade from struct StructMemberRenamedRetypedV1.S to struct StructMemberRenamedRetypedV2.S␊
+      - In struct StructMemberRenamedRetypedV2.S␊
+        - Layout could have changed for \`x\` (bytes32 -> struct TransientSlot.TBytes32)␊
+    ␊
+    contracts/test/StructMemberRenamedRetyped.sol:63: Upgraded \`m\` to an incompatible type␊
+      - In mapping(uint256 => struct StructMemberRenamedRetypedV2.S)␊
+        - Bad upgrade from struct StructMemberRenamedRetypedV1.S to struct StructMemberRenamedRetypedV2.S␊
+      - In struct StructMemberRenamedRetypedV2.S␊
+        - Layout could have changed for \`x\` (bytes32 -> struct TransientSlot.TBytes32)␊
+    ␊
+    contracts/test/StructMemberRenamedRetyped.sol:64: Upgraded \`arr\` to an incompatible type␊
+      - In struct StructMemberRenamedRetypedV2.S[]␊
+        - Bad upgrade from struct StructMemberRenamedRetypedV1.S to struct StructMemberRenamedRetypedV2.S␊
+      - In struct StructMemberRenamedRetypedV2.S␊
+        - Layout could have changed for \`x\` (bytes32 -> struct TransientSlot.TBytes32)␊
+    ␊
+    contracts/test/StructMemberRenamedRetyped.sol:66: Upgraded \`other\` to an incompatible type␊
+      - Bad upgrade from struct OtherFileV1 to struct OtherFileV2␊
+      - In struct OtherFileV2␊
+        - Layout could have changed for \`a\` (bytes32 -> struct TransientSlot.TBytes32)`

package/src/utils/annotations.ts

@@ -1,6 +1,9 @@
 import { execall } from './execall';
 import { Node } from 'solidity-ast/node';
 
+// Matches one NatSpec tag: `@title:tag args`, where the args run until the next line that starts with a tag
+export const ANNOTATION_REGEX = /^\s*(?:@(?<title>\w+)(?::(?<tag>[a-z][a-z-]*))? )?(?<args>(?:(?!^\s*@\w+)[^])*)/m;
+
 /**
  * Whether the given doc string has an annotation tag.
  */
@@ -18,10 +21,7 @@ export function hasAnnotationTag(doc: string, tag: string): boolean {
  */
 export function getAnnotationArgs(doc: string, tag: string, supportedArgs?: readonly string[]) {
   const result: string[] = [];
-  for (const { groups } of execall(
-    /^\s*(?:@(?<title>\w+)(?::(?<tag>[a-z][a-z-]*))? )?(?<args>(?:(?!^\s*@\w+)[^])*)/m,
-    doc,
-  )) {
+  for (const { groups } of execall(ANNOTATION_REGEX, doc)) {
     if (groups && groups.title === 'custom' && groups.tag === tag) {
       const trimmedArgs = groups.args.trim();
       if (trimmedArgs.length > 0) {

package/src/utils/erc7201-builtin.ts

@@ -0,0 +1,91 @@
+import { Expression, Literal } from 'solidity-ast';
+import { calculateERC7201StorageLocation } from './erc7201';
+import { normalizeUint256Literal } from './integer-literals';
+import { UpgradesError } from '../error';
+
+/**
+ * Recognizes the Solidity 0.8.35+ `erc7201(string)` comptime builtin, which evaluates the ERC-7201
+ * storage location for a namespace id and can be used in a compile-time context such as a `layout at`
+ * specifier (e.g. `contract C layout at erc7201("example.main")`).
+ *
+ * The builtin compiles to an ordinary `FunctionCall` node, so it is matched by its shape rather than
+ * by a dedicated AST node type.
+ *
+ * @param node The expression to check.
+ * @returns The namespace id passed to the builtin (without the `erc7201:` prefix), or undefined if the
+ *   expression is not a call to the `erc7201` builtin with a single string literal argument.
+ */
+export function getErc7201BuiltinNamespaceId(node: Expression): string | undefined {
+  // Check that this is a function call to an identifier named `erc7201`. Return undefined for
+  // anything else so the caller can fall through to other base-slot forms.
+  if (node.nodeType !== 'FunctionCall' || node.kind !== 'functionCall') {
+    return undefined;
+  }
+  const callee = node.expression;
+  if (callee.nodeType !== 'Identifier' || callee.name !== 'erc7201') {
+    return undefined;
+  }
+
+  // Beyond this point, the call is to `erc7201(...)`. Check its expected shape — one string-literal
+  // argument with no user-defined declaration shadowing the builtin — and throw if anything is off.
+  // Valid Solidity 0.8.35+ cannot produce these mismatches in a call to the builtin:
+  //   - User-defined `erc7201` (`referencedDeclaration >= 0`): solc resolves the call to the builtin
+  //     when both are in scope, so this shape doesn't reach a successful compile.
+  //   - Wrong number of arguments: enforced by the builtin's signature.
+  //   - Non-`Literal` argument or non-string literal `kind`: the builtin's signature requires a
+  //     comptime-constant string literal. `hex"..."` is type `bytes` and wouldn't typecheck.
+  // We throw instead of returning undefined so a future solc emitting one of these surfaces loudly.
+  if (typeof callee.referencedDeclaration === 'number' && callee.referencedDeclaration >= 0) {
+    throw unexpectedErc7201BuiltinAst('callee resolves to a user-defined declaration');
+  }
+  if (node.arguments.length !== 1) {
+    throw unexpectedErc7201BuiltinAst(`expected 1 argument, got ${node.arguments.length}`);
+  }
+  const arg = node.arguments[0];
+  if (arg.nodeType !== 'Literal') {
+    throw unexpectedErc7201BuiltinAst(`argument is ${arg.nodeType}, expected Literal`);
+  }
+  if (arg.kind !== 'string' && arg.kind !== 'unicodeString') {
+    throw unexpectedErc7201BuiltinAst(`argument literal kind is ${arg.kind}, expected string or unicodeString`);
+  }
+
+  return getStringLiteralValue(arg);
+}
+
+function unexpectedErc7201BuiltinAst(detail: string): UpgradesError {
+  return new UpgradesError(
+    `Unexpected AST for \`erc7201(...)\` builtin call: ${detail}`,
+    () =>
+      'Please report this at https://zpl.in/upgrades/report and include the `erc7201(...)` expression from your contract.',
+  );
+}
+
+/**
+ * Resolves an expression to its base slot as a normalized uint256 hex string, for either a numeric
+ * literal or an `erc7201(...)` builtin call.
+ *
+ * @param node The expression to resolve.
+ * @returns The normalized base slot hex string, or undefined if the expression is neither a numeric
+ *   literal nor a resolvable `erc7201(...)` builtin call.
+ */
+export function resolveBaseSlot(node: Expression): string | undefined {
+  if (node.nodeType === 'Literal') {
+    return normalizeUint256Literal(node.value);
+  }
+
+  const id = getErc7201BuiltinNamespaceId(node);
+  if (id !== undefined) {
+    return calculateERC7201StorageLocation(id);
+  }
+
+  return undefined;
+}
+
+function getStringLiteralValue(literal: Literal): string {
+  // solc populates `value` for `kind: 'string'`/`'unicodeString'` literals; throw defensively if
+  // a future solc ever produces a null/missing `value` for such a literal.
+  if (literal.value === undefined || literal.value === null) {
+    throw unexpectedErc7201BuiltinAst('string literal `value` is null or missing');
+  }
+  return literal.value;
+}

package/src/utils/erc7201.test.ts

@@ -8,3 +8,15 @@ test('calculateERC7201StorageLocation', t => {
     '0x183a6125c38840424c4a85fa12bab2ab606c4b6d0e7cc73c0c06ba5300eab500',
   );
 });
+
+// `keccak256("ns2") - 1` is 63 hex chars (odd-length), which must be zero-padded to 32 bytes
+// before hashing. Regression test for truncation of the intermediate buffer.
+test('calculateERC7201StorageLocation - odd-length intermediate hash', t => {
+  t.is(calculateERC7201StorageLocation('ns2'), '0xa61069020885c09e922542fb3fa98c8d50e6481fc1251ff86c3319a70f0f7d00');
+});
+
+// `keccak256("ns297") - 1` is 62 hex chars (i.e., its top byte is `0x00`). Without zero-padding,
+// `Buffer.from('hex')` would interpret it as a 31-byte buffer rather than 32, producing the wrong hash.
+test('calculateERC7201StorageLocation - leading-zero-byte intermediate hash', t => {
+  t.is(calculateERC7201StorageLocation('ns297'), '0xe06f9faa11c8032ea604e1764972c1a5594987f1678d8fabf921c28d1a7a4c00');
+});