@openzeppelin/upgrades-core 1.45.0-alpha.1 → 1.46.0

package/src/cli/validate/build-info-file.test.ts

@@ -313,6 +313,55 @@ test.serial('get build info files - default foundry', async t => {
   assertBuildInfoFiles(t, buildInfoFiles);
 });
 
+test.serial('get build info files - Foundry format success path', async t => {
+  const dir = 'foundry-format-success';
+
+  await fs.mkdir(dir, { recursive: true });
+  await fs.writeFile(
+    `${dir}/build-info.json`,
+    JSON.stringify({
+      _format: 'ethers-rs-sol-build-info-1',
+      ...BUILD_INFO,
+    }),
+  );
+
+  const buildInfoFiles = await getBuildInfoFiles(dir);
+
+  t.is(buildInfoFiles.length, 1);
+  t.is(buildInfoFiles[0]?.dirShortName, dir);
+  t.is(buildInfoFiles[0]?.solcVersion, BUILD_INFO.solcVersion);
+  t.deepEqual(buildInfoFiles[0]?.input, BUILD_INFO.input);
+  t.deepEqual(buildInfoFiles[0]?.output, BUILD_INFO.output);
+});
+
+test.serial('get build info files - Hardhat 3 split format success path', async t => {
+  const dir = 'hh3-format-success';
+
+  await fs.mkdir(dir, { recursive: true });
+  await fs.writeFile(
+    `${dir}/solc-0_8_9-abc123.json`,
+    JSON.stringify({
+      _format: 'hh3-sol-build-info-1',
+      input: BUILD_INFO.input,
+      solcVersion: BUILD_INFO.solcVersion,
+    }),
+  );
+  await fs.writeFile(
+    `${dir}/solc-0_8_9-abc123.output.json`,
+    JSON.stringify({
+      output: BUILD_INFO.output,
+    }),
+  );
+
+  const buildInfoFiles = await getBuildInfoFiles(dir);
+
+  t.is(buildInfoFiles.length, 1);
+  t.is(buildInfoFiles[0]?.dirShortName, dir);
+  t.is(buildInfoFiles[0]?.solcVersion, BUILD_INFO.solcVersion);
+  t.deepEqual(buildInfoFiles[0]?.input, BUILD_INFO.input);
+  t.deepEqual(buildInfoFiles[0]?.output, BUILD_INFO.output);
+});
+
 test.serial('get build info files - both hardhat and foundry dirs exist', async t => {
   await fs.mkdir('artifacts/build-info', { recursive: true });
   await fs.writeFile('artifacts/build-info/build-info.json', JSON.stringify(BUILD_INFO));
@@ -363,6 +412,7 @@ test.serial('generic invalid build info file', async t => {
   await fs.writeFile('invalid-build-info/invalid.json', JSON.stringify({ output: {} }));
   const error = await t.throwsAsync(getBuildInfoFiles('invalid-build-info'));
   t.true(error?.message.includes('must include Solidity compiler input, output, and solcVersion'));
+  t.true(error?.message.includes('Got format: unknown'));
 });
 
 test.serial('Foundry format (ethers-rs) with missing output suggests forge clean && forge build', async t => {
@@ -383,6 +433,21 @@ test.serial('Foundry format (ethers-rs) with missing output suggests forge clean
   t.true(error?.message.includes('forge clean && forge build'));
 });
 
+test.serial('Hardhat 3 format with missing input and solcVersion suggests hardhat compile', async t => {
+  await fs.mkdir('hh3-format-missing-input', { recursive: true });
+
+  await fs.writeFile(
+    'hh3-format-missing-input/solc-0_8_0-abc123.json',
+    JSON.stringify({
+      _format: 'hh3-sol-build-info-1',
+    }),
+  );
+  const error = await t.throwsAsync(getBuildInfoFiles('hh3-format-missing-input'));
+  t.true(error?.message.includes('Hardhat 3 format'));
+  t.true(error?.message.includes('must contain input and solcVersion'));
+  t.true(error?.message.includes('hardhat compile'));
+});
+
 test.serial('Hardhat 3 format with missing .output.json suggests hardhat compile', async t => {
   await fs.mkdir('hh3-format-missing-output', { recursive: true });
 
@@ -396,7 +461,29 @@ test.serial('Hardhat 3 format with missing .output.json suggests hardhat compile
     }),
   );
   const error = await t.throwsAsync(getBuildInfoFiles('hh3-format-missing-output'));
-  t.true(error?.message.includes('could not be read') || error?.message.includes('missing Solidity compiler output'));
+  t.true(error?.message.includes('could not be read'));
+  t.false(error?.message.includes('missing Solidity compiler output'));
+  t.true(error?.message.includes('Hardhat 3'));
+  t.true(error?.message.includes('hardhat compile'));
+});
+
+test.serial('Hardhat 3 format with empty .output.json reports missing compiler output', async t => {
+  await fs.mkdir('hh3-format-empty-output', { recursive: true });
+
+  await fs.writeFile(
+    'hh3-format-empty-output/solc-0_8_0-abc123.json',
+    JSON.stringify({
+      _format: 'hh3-sol-build-info-1',
+      input: BUILD_INFO.input,
+      solcVersion: '0.8.9',
+    }),
+  );
+  await fs.writeFile('hh3-format-empty-output/solc-0_8_0-abc123.output.json', JSON.stringify({}));
+
+  const error = await t.throwsAsync(getBuildInfoFiles('hh3-format-empty-output'));
+  t.true(error?.message.includes('missing Solidity compiler output'));
+  t.false(error?.message.includes('could not be read'));
+  t.true(error?.message.includes('Hardhat 3'));
   t.true(error?.message.includes('hardhat compile'));
 });
 
@@ -494,6 +581,74 @@ test.serial('no output selection', async t => {
   t.true(error?.message.includes('is not from a full compilation'));
 });
 
+test.serial('Hardhat 3 format with userSourceNameMap remaps input and output sources', async t => {
+  const dir = 'hh3-source-name-map';
+
+  await fs.mkdir(dir, { recursive: true });
+  await fs.writeFile(
+    `${dir}/solc-0_8_9-abc123.json`,
+    JSON.stringify({
+      _format: 'hh3-sol-build-info-1',
+      solcVersion: '0.8.9',
+      input: {
+        language: 'Solidity',
+        sources: {
+          'project/contracts/MyContract.sol': {
+            content: 'contract MyContract {}',
+          },
+          'lib/Helper.sol': {
+            content: 'contract Helper {}',
+          },
+        },
+        settings: {
+          outputSelection: {
+            '*': {
+              '*': ['storageLayout'],
+            },
+          },
+        },
+      },
+      // Only maps project sources, not library sources
+      userSourceNameMap: {
+        'contracts/MyContract.sol': 'project/contracts/MyContract.sol',
+      },
+    }),
+  );
+  await fs.writeFile(
+    `${dir}/solc-0_8_9-abc123.output.json`,
+    JSON.stringify({
+      sources: {
+        'project/contracts/MyContract.sol': { ast: {}, id: 0 },
+        'lib/Helper.sol': { ast: {}, id: 1 },
+      },
+      contracts: {
+        'project/contracts/MyContract.sol': { MyContract: {} },
+      },
+    }),
+  );
+
+  const buildInfoFiles = await getBuildInfoFiles(dir);
+
+  t.is(buildInfoFiles.length, 1);
+  const file = buildInfoFiles[0];
+
+  const user = 'contracts/MyContract.sol';
+  const canonical = 'project/contracts/MyContract.sol';
+  const lib = 'lib/Helper.sol';
+
+  // Mapped: canonical paths replaced with user paths
+  t.truthy(file.input.sources[user]);
+  t.falsy(file.input.sources[canonical]);
+  t.truthy(file.output.sources[user]);
+  t.falsy(file.output.sources[canonical]);
+  t.truthy(file.output.contracts?.[user]);
+  t.falsy(file.output.contracts?.[canonical]);
+
+  // Unmapped: library deps preserved as-is
+  t.truthy(file.input.sources[lib]);
+  t.truthy(file.output.sources[lib]);
+});
+
 function assertBuildInfoFiles(t: ExecutionContext, buildInfoFiles: BuildInfoFile[]) {
   t.is(buildInfoFiles.length, 2);
 

package/src/cli/validate/build-info-file.ts

@@ -222,7 +222,12 @@ async function loadBuildInfo(buildInfoFilePath: string): Promise<{
         );
       }
 
-      if (outputData === undefined) {
+      if (
+        outputData === undefined ||
+        outputData === null ||
+        typeof outputData !== 'object' ||
+        (!('sources' in outputData) && !('contracts' in outputData) && !('errors' in outputData))
+      ) {
         throw new ValidateCommandError(
           `Build info file ${buildInfoFilePath} does not contain output, and output file ${outputFilePath} is missing Solidity compiler output.`,
           () => HH3_BUILD_INFO_HELP,

package/src/provider.ts

@@ -141,6 +141,7 @@ export const networkNames: { [chainId in number]?: string } = Object.freeze({
   42161: 'arbitrum-one',
   42170: 'arbitrum-nova',
   421613: 'arbitrum-goerli',
+  421614: 'arbitrum-sepolia',
   43113: 'avalanche-fuji',
   43114: 'avalanche',
   42220: 'celo',

package/src/storage/extract.ts

@@ -16,6 +16,7 @@ import { pick } from '../utils/pick';
 import { execall } from '../utils/execall';
 import { loadNamespaces } from './namespace';
 import { UpgradesError } from '../error';
+import { resolveBaseSlot } from '../utils/erc7201-builtin';
 
 const currentLayoutVersion = '1.2';
 
@@ -106,19 +107,34 @@ export function extractStorageLayout(
 
 function loadBaseSlot(contractDef: ContractDefinition, decodeSrc: SrcDecoder, layout: StorageLayout) {
   if (contractDef.storageLayout !== undefined) {
-    if (contractDef.storageLayout.baseSlotExpression.nodeType !== 'Literal') {
-      const src = decodeSrc(contractDef.storageLayout.baseSlotExpression);
-
-      // TODO when Slang supports Solidity 0.8.29, use it to parse the expression (of any node type) into a string, then just save it to `layout.baseSlot`.
-      // Then when comparing layouts in `storage/index.ts`, it will only be used when detailed storage layout is not available, and the comparison
-      // can be changed to a string comparison when `layout.baseSlot` not an integer literal.
-      throw new UpgradesError(
-        `${src}: Custom storage layout expression with node type ${contractDef.storageLayout.baseSlotExpression.nodeType} is not currently supported`,
-        () =>
-          'Please report this at https://zpl.in/upgrades/report and include the `layout at` expression from your contract.',
-      );
+    const baseSlotExpression = contractDef.storageLayout.baseSlotExpression;
+    if (baseSlotExpression.nodeType === 'Literal') {
+      layout.baseSlot = baseSlotExpression.value ?? undefined;
+      return;
     }
-    layout.baseSlot = contractDef.storageLayout.baseSlotExpression.value ?? undefined;
+
+    // Solidity 0.8.35+ allows the `erc7201(string)` comptime builtin as a base slot, e.g.
+    // `layout at erc7201("example.main")`. Resolve it to its computed storage location.
+    const resolvedSlot = resolveBaseSlot(baseSlotExpression);
+    if (resolvedSlot !== undefined) {
+      layout.baseSlot = resolvedSlot;
+      return;
+    }
+
+    const src = decodeSrc(baseSlotExpression);
+
+    // TODO if a base slot expression other than a numeric literal or an `erc7201(...)` builtin call
+    // needs to be supported, evaluate the right approach per expression — either resolve it to a
+    // computed value (like the erc7201 builtin) or compare its source text across upgrades. A
+    // source-text approach could use Slang to extract the expression's source span (Slang supports
+    // `StorageLayoutSpecifier` from 0.8.29) and store it as a string on `layout.baseSlot`, with the
+    // upgrade-time comparison in `storage/index.ts:validateBaseSlotUnchanged` falling back to a
+    // string compare when `layout.baseSlot` is not a numeric literal.
+    throw new UpgradesError(
+      `${src}: Custom storage layout expression with node type ${baseSlotExpression.nodeType} is not currently supported`,
+      () =>
+        'Please report this at https://zpl.in/upgrades/report and include the `layout at` expression from your contract.',
+    );
   }
 }
 

package/src/storage/namespace.ts

@@ -8,8 +8,8 @@ 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 { getErc7201BuiltinNamespaceId, resolveBaseSlot } from '../utils/erc7201-builtin';
 import { logWarning } from '../utils/log';
 
 /**
@@ -175,15 +175,18 @@ function checkCustomLayoutClashWithNamespace(
   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);
-      }
-    }
+  if (contractDef.storageLayout === undefined || !storageLocation.startsWith(ERC7201_FORMULA_PREFIX)) {
+    return;
+  }
+
+  const namespaceId = storageLocation.substring(ERC7201_FORMULA_PREFIX.length);
+
+  // Resolve the base slot (a numeric literal or an erc7201(...) builtin call) and compare it against
+  // the namespace's computed storage location. This covers `layout at erc7201("<id>")` using the same
+  // id as the namespace, since both resolve to the same hash.
+  const baseSlotNormalized = resolveBaseSlot(contractDef.storageLayout.baseSlotExpression);
+  if (baseSlotNormalized !== undefined && baseSlotNormalized === calculateERC7201StorageLocation(namespaceId)) {
+    throw new CustomLayoutClashWithNamespaceError(storageLocation, contractName, src);
   }
 }
 
@@ -192,8 +195,15 @@ function warnIfCustomLayoutAndNamespacesFound(
   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) {
+    // The warning is meant for users who pick an arbitrary literal slot that could land inside a
+    // namespace's range. When the base slot uses the erc7201 comptime builtin, it relies on the
+    // same collision resistance that namespaces rely on against each other, so suppress the warning;
+    // the tool likewise does not warn when multiple namespaces coexist.
+    if (getErc7201BuiltinNamespaceId(origContractDef.storageLayout.baseSlotExpression) !== undefined) {
+      return;
+    }
+
     const contractName = origContractDef.canonicalName ?? origContractDef.name;
     logWarning(
       `${decodeSrc(origContractDef.storageLayout)}: Ensure custom storage layout does not overlap with namespaced storage layout.`,

package/src/storage-erc7201-builtin.test.ts

@@ -0,0 +1,127 @@
+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';
+
+interface Context {
+  extractStorageLayout: (contract: string) => ReturnType<typeof extractStorageLayout>;
+  extractStorageLayoutFallback: (contract: string) => ReturnType<typeof extractStorageLayout>;
+}
+
+const test = _test as TestFn<Context>;
+
+const SOURCE = 'contracts/test/Erc7201Builtin.sol';
+
+test.before(async t => {
+  const buildInfo = await artifacts.getBuildInfo(`${SOURCE}:Erc7201Builtin`);
+  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[SOURCE].ast)) {
+    contracts[def.name] = def;
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+    storageLayouts[def.name] = solcOutput.contracts[SOURCE][def.name].storageLayout!;
+  }
+  const deref = astDereferencer(solcOutput);
+
+  t.context.extractStorageLayout = name =>
+    extractStorageLayout(contracts[name], dummyDecodeSrc, deref, storageLayouts[name]);
+
+  t.context.extractStorageLayoutFallback = name =>
+    extractStorageLayout(contracts[name], dummyDecodeSrc, deref, undefined);
+});
+
+const dummyDecodeSrc = () => 'file.sol:1';
+
+test('erc7201 builtin base slot - extract', t => {
+  const layout = t.context.extractStorageLayout('Erc7201Builtin');
+  t.is(layout.baseSlot, '0x183a6125c38840424c4a85fa12bab2ab606c4b6d0e7cc73c0c06ba5300eab500');
+  t.is(layout.storage.length, 1);
+  t.is(layout.storage[0].label, 'a');
+});
+
+test('erc7201 builtin base slot - append - ok', t => {
+  const v1 = t.context.extractStorageLayout('Erc7201Builtin');
+  const v2 = t.context.extractStorageLayout('Erc7201Builtin_Append_Ok');
+  t.deepEqual(getStorageUpgradeErrors(v1, v2), []);
+});
+
+test('erc7201 builtin base slot - append - fallback - ok', t => {
+  const v1 = t.context.extractStorageLayoutFallback('Erc7201Builtin');
+  const v2 = t.context.extractStorageLayoutFallback('Erc7201Builtin_Append_Ok');
+  t.deepEqual(getStorageUpgradeErrors(v1, v2), []);
+});
+
+test('erc7201 builtin base slot - changed id - bad', t => {
+  const v1 = t.context.extractStorageLayout('Erc7201Builtin');
+  const v2 = t.context.extractStorageLayout('Erc7201Builtin_Changed_Id_Bad');
+  const comparison = getStorageUpgradeErrors(v1, v2);
+  t.true(comparison.length > 0);
+  t.is(comparison[0].kind, 'layoutchange');
+});
+
+test('erc7201 builtin base slot - changed id - fallback - bad', t => {
+  const v1 = t.context.extractStorageLayoutFallback('Erc7201Builtin');
+  const v2 = t.context.extractStorageLayoutFallback('Erc7201Builtin_Changed_Id_Bad');
+  // Base slot differs between the two erc7201 ids, so the fallback base-slot check must fail.
+  t.throws(() => getStorageUpgradeErrors(v1, v2), {
+    message: /Base slot for custom storage layout changed/,
+  });
+});
+
+test('erc7201 builtin and literal-equivalent base slots compare equal', t => {
+  const builtin = t.context.extractStorageLayout('Erc7201Builtin');
+  const literal = t.context.extractStorageLayout('Erc7201Builtin_Literal_Equivalent');
+  // Both resolve to the same base slot; the fallback (base-slot) check must treat them as unchanged.
+  const builtinFallback = t.context.extractStorageLayoutFallback('Erc7201Builtin');
+  const literalFallback = t.context.extractStorageLayoutFallback('Erc7201Builtin_Literal_Equivalent');
+  t.deepEqual(getStorageUpgradeErrors(builtin, literal), []);
+  t.deepEqual(getStorageUpgradeErrors(builtinFallback, literalFallback), []);
+});
+
+test('erc7201 builtin base slot clashes with namespace - error', t => {
+  t.throws(() => t.context.extractStorageLayout('Erc7201Builtin_Clash'), {
+    message:
+      /Custom layout for contract Erc7201Builtin_Clash clashes with the storage location for namespace erc7201:example\.main/,
+  });
+});
+
+test('erc7201 builtin base slot different from namespace - no error and no warning', t => {
+  const warnings = captureWarnings(() => {
+    const layout = t.context.extractStorageLayout('Erc7201Builtin_NoClash_NoWarning');
+    t.truthy(layout.baseSlot);
+  });
+  t.deepEqual(warnings, []);
+});
+
+test('erc7201 builtin accepts a unicode string literal argument', t => {
+  const layout = t.context.extractStorageLayout('Erc7201Builtin_Unicode');
+  t.is(layout.baseSlot, '0x2d3e72b7d91644a80150e2643e65016def7067dc9568719707e7eca1a5dab800');
+});
+
+test('literal base slot with namespace - warning not suppressed', t => {
+  const warnings = captureWarnings(() => t.context.extractStorageLayout('Erc7201Builtin_LiteralBase_Warns'));
+  t.true(warnings.some(w => w.includes('custom storage layout')));
+});
+
+function captureWarnings(fn: () => void): string[] {
+  const warnings: string[] = [];
+  const original = console.error;
+  console.error = (...args: unknown[]) => {
+    warnings.push(args.map(String).join(' '));
+  };
+  try {
+    fn();
+  } finally {
+    console.error = original;
+  }
+  return warnings;
+}

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');
+});

package/src/utils/erc7201.ts

@@ -1,5 +1,7 @@
 import { keccak256 } from 'ethereumjs-util';
 
+import { toBytes32Hex } from './integer-literals';
+
 export const ERC7201_FORMULA_PREFIX = 'erc7201:';
 
 /**
@@ -12,14 +14,14 @@ export const ERC7201_FORMULA_PREFIX = 'erc7201:';
 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');
+  // Pad to 64 hex chars so that `Buffer.from` doesn't silently truncate odd-length input;
+  // `abi.encode(uint256)` is always 32 bytes.
+  const minusOneBuffer = Buffer.from(minusOne.toString(16).padStart(64, '0'), '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}`;
+  return toBytes32Hex(masked);
 }

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

@@ -1,6 +1,6 @@
 import test from 'ava';
 
-import { normalizeUint256Literal } from './integer-literals';
+import { normalizeUint256Literal, toBytes32Hex } from './integer-literals';
 
 const ZEROES = '0x0000000000000000000000000000000000000000000000000000000000000000';
 
@@ -71,3 +71,17 @@ test('full hex with leading and trailing zeroes', t => {
     '0x00ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff00',
   );
 });
+
+test('rejects values above uint256 max', t => {
+  const tooLarge = '0x10000000000000000000000000000000000000000000000000000000000000000';
+  const error = t.throws(() => normalizeUint256Literal(tooLarge));
+  t.regex(error?.message ?? '', /uint256 range/);
+});
+
+test('toBytes32Hex - boundaries', t => {
+  const MAX_HEX = '0x' + 'f'.repeat(64);
+  t.is(toBytes32Hex(0n), '0x' + '0'.repeat(64));
+  t.is(toBytes32Hex(BigInt(MAX_HEX)), MAX_HEX);
+  t.throws(() => toBytes32Hex(BigInt(MAX_HEX) + 1n), { message: /uint256 range/ });
+  t.throws(() => toBytes32Hex(-1n), { message: /uint256 range/ });
+});