@openzeppelin/upgrades-core 1.45.0 → 1.47.0

package/src/cli/validate/validate-upgrade-safety.test.ts.md

@@ -96,3 +96,13 @@ Generated by [AVA](https://avajs.dev).
               Different representation sizes␊
     ␊
     FAILED (1 upgradeable contract detected, 0 passed, 1 failed)`
+
+## struct member annotations - namespace retype without layout info
+
+> Snapshot 1
+
+    ` ✘  contracts/test/cli/StructMemberAnnotations.sol:NamespaceRetypeV2 (upgrades from contracts/test/cli/StructMemberAnnotations.sol:NamespaceRetypeV1)␊
+    ␊
+          contracts/test/cli/StructMemberAnnotations.sol:52: Layout could have changed for \`x\` (bytes32 -> struct TransientSlot.TBytes32)␊
+    ␊
+    FAILED`

package/src/storage/compare.ts

@@ -203,12 +203,11 @@ export class StorageLayoutComparator {
       original.label !== updated.renamedFrom &&
       (updated.label !== original.label ||
         (updated.renamedFrom !== undefined && updated.renamedFrom !== original.renamedFrom));
-    const typeChange =
-      !this.isRetypedFromOriginal(original, updated) &&
-      this.getTypeChange(original.type, updated.type, { allowAppend: false });
+    const retypedFromOriginal = this.isRetypedFromOriginal(original, updated);
+    const typeChange = !retypedFromOriginal && this.getTypeChange(original.type, updated.type, { allowAppend: false });
     const layoutChange = this.getLayoutChange(original, updated);
 
-    if (updated.retypedFrom && layoutChange && (!layoutChange.uncertain || !layoutChange.knownCompatible)) {
+    if (retypedFromOriginal && layoutChange && (!layoutChange.uncertain || !layoutChange.knownCompatible)) {
       return { kind: 'layoutchange', original, updated, change: layoutChange, cost: LAYOUTCHANGE_COST };
     } else if (nameChange && endMatchesGap(original, updated)) {
       // original is a gap that was consumed by a non-gap ending at the same slot, which is safe

package/src/storage/extract.ts

@@ -8,14 +8,17 @@ import {
   TypeName,
 } from 'solidity-ast';
 import { isNodeType, findAll, ASTDereferencer } from 'solidity-ast/utils';
-import { StorageLayout, StructMember, TypeItem, isStructMembers, EnumMember } from './layout';
+import { StorageLayout, StorageField, StructMember, TypeItem, isStructMembers, EnumMember } from './layout';
 import { normalizeTypeIdentifier } from '../utils/type-id';
 import { SrcDecoder } from '../src-decoder';
 import { mapValues } from '../utils/map-values';
 import { pick } from '../utils/pick';
 import { execall } from '../utils/execall';
+import { ANNOTATION_REGEX, getDocumentation } from '../utils/annotations';
+import { StructDocsResolver } from '../utils/struct-member-docs';
 import { loadNamespaces } from './namespace';
 import { UpgradesError } from '../error';
+import { resolveBaseSlot } from '../utils/erc7201-builtin';
 
 const currentLayoutVersion = '1.2';
 
@@ -27,6 +30,7 @@ export interface CompilationContext {
   deref: ASTDereferencer;
   contractDef: ContractDefinition;
   storageLayout?: StorageLayout;
+  structDocs?: StructDocsResolver;
 }
 
 export function extractStorageLayout(
@@ -35,6 +39,7 @@ export function extractStorageLayout(
   deref: ASTDereferencer,
   storageLayout?: StorageLayout,
   namespacedContext?: CompilationContext,
+  structDocs?: StructDocsResolver,
 ): StorageLayout {
   const layout: StorageLayout = { storage: [], types: {}, layoutVersion: currentLayoutVersion, flat: false };
 
@@ -71,7 +76,7 @@ export function extractStorageLayout(
       const { varDecl, contract } = origin;
       const { renamedFrom, retypedFrom } = getRetypedRenamed(varDecl);
       // Solc layout doesn't bring members for enums so we get them using the ast method
-      loadLayoutType(varDecl.typeName, layout, deref);
+      loadLayoutType(varDecl.typeName, layout, deref, structDocs);
       const { label, offset, slot, type } = storage;
       const src = decodeSrc(varDecl);
       layout.storage.push({ label, offset, slot, type, contract, src, retypedFrom, renamedFrom });
@@ -92,13 +97,13 @@ export function extractStorageLayout(
             renamedFrom,
           });
 
-          loadLayoutType(varDecl.typeName, layout, deref);
+          loadLayoutType(varDecl.typeName, layout, deref, structDocs);
         }
       }
     }
   }
 
-  const origContext = { deref, contractDef, storageLayout };
+  const origContext = { deref, contractDef, storageLayout, structDocs };
   loadNamespaces(decodeSrc, layout, origContext, namespacedContext);
 
   return layout;
@@ -106,19 +111,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.',
+    );
   }
 }
 
@@ -185,7 +205,12 @@ function getOriginContract(contract: ContractDefinition, astId: number | undefin
   }
 }
 
-export function loadLayoutType(typeName: TypeName | null | undefined, layout: StorageLayout, deref: ASTDereferencer) {
+export function loadLayoutType(
+  typeName: TypeName | null | undefined,
+  layout: StorageLayout,
+  deref: ASTDereferencer,
+  structDocs?: StructDocsResolver,
+) {
   // Note: A UserDefinedTypeName can also refer to a ContractDefinition but we won't care about those.
   const derefUserDefinedType = deref(['StructDefinition', 'EnumDefinition', 'UserDefinedValueTypeDefinition']);
 
@@ -208,6 +233,10 @@ export function loadLayoutType(typeName: TypeName | null | undefined, layout: St
         layout.types[type].underlying = typeDef.underlyingType.typeDescriptions.typeIdentifier ?? undefined;
       } else {
         layout.types[type].members ??= getTypeMembers(typeDef);
+        if (typeDef.nodeType === 'StructDefinition' && structDocs !== undefined) {
+          // Add annotations whether the members came from the compiler's storage layout or from the AST above
+          setStructMemberAnnotations(layout.types[type], structDocs(typeDef));
+        }
       }
 
       // Recursively look for the types referenced in this definition and add them to the queue.
@@ -222,22 +251,46 @@ export function loadLayoutType(typeName: TypeName | null | undefined, layout: St
 }
 
 function getRetypedRenamed(varDecl: VariableDeclaration) {
+  return getRetypedRenamedFromDoc(getDocumentation(varDecl));
+}
+
+export function getRetypedRenamedFromDoc(doc: string) {
   let retypedFrom, renamedFrom;
-  if ('documentation' in varDecl) {
-    const docs =
-      typeof varDecl.documentation === 'string' ? varDecl.documentation : (varDecl.documentation?.text ?? '');
-    for (const { groups } of execall(
-      /^\s*(?:@(?<title>\w+)(?::(?<tag>[a-z][a-z-]*))? )?(?<args>(?:(?!^\s@\w+)[^])*)/m,
-      docs,
-    )) {
-      if (groups?.title === 'custom') {
-        if (groups.tag === 'oz-retyped-from') {
-          retypedFrom = groups.args.trim();
-        } else if (groups.tag === 'oz-renamed-from') {
-          renamedFrom = groups.args.trim();
-        }
+  for (const { groups } of execall(ANNOTATION_REGEX, doc)) {
+    if (groups?.title === 'custom') {
+      if (groups.tag === 'oz-retyped-from') {
+        retypedFrom = groups.args.trim();
+      } else if (groups.tag === 'oz-renamed-from') {
+        renamedFrom = groups.args.trim();
       }
     }
   }
   return { retypedFrom, renamedFrom };
 }
+
+/**
+ * Sets `renamedFrom` and `retypedFrom` on the given layout field (a namespace member or a member of a struct type)
+ * from the annotations in that member's NatSpec, for the storage layout comparison to use. Each field is only set if
+ * the NatSpec has the corresponding annotation, so unannotated members have no `renamedFrom` or `retypedFrom` key.
+ */
+export function setMemberAnnotations(field: StorageField, docs: Map<string, string>) {
+  const doc = docs.get(field.label);
+  if (doc !== undefined) {
+    const { retypedFrom, renamedFrom } = getRetypedRenamedFromDoc(doc);
+    if (retypedFrom !== undefined) {
+      field.retypedFrom = retypedFrom;
+    }
+    if (renamedFrom !== undefined) {
+      field.renamedFrom = renamedFrom;
+    }
+  }
+}
+
+function setStructMemberAnnotations(typeItem: TypeItem, docs: Map<string, string> | undefined) {
+  if (docs !== undefined) {
+    assert(typeItem.members !== undefined && isStructMembers(typeItem.members));
+    for (const member of typeItem.members) {
+      setMemberAnnotations(member, docs);
+    }
+  }
+}

package/src/storage/namespace.ts

@@ -5,11 +5,11 @@ import { StorageItem, StorageLayout, TypeItem, isStructMembers } from './layout'
 import { SrcDecoder } from '../src-decoder';
 import { getAnnotationArgs, getDocumentation, hasAnnotationTag } from '../utils/annotations';
 import { Node } from 'solidity-ast/node';
-import { CompilationContext, getTypeMembers, loadLayoutType } from './extract';
+import { CompilationContext, getTypeMembers, loadLayoutType, setMemberAnnotations } 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';
 
 /**
@@ -49,7 +49,9 @@ export function loadNamespaces(
   const linearized = namespacedLinearized ?? origLinearized;
   for (const [i, contractDef] of linearized.entries()) {
     const origContractDef = origLinearized[i];
-    const contractContext = { ...context, contractDef };
+    // Member documentation is read from the original sources, so the resolver comes from the original context
+    // even when the namespaced context is used to look up the structs.
+    const contractContext = { ...context, contractDef, structDocs: origContext.structDocs };
     addContractNamespacesWithSrc(
       namespacesWithSrc,
       decodeSrc,
@@ -175,15 +177,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 +197,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.`,
@@ -238,6 +250,7 @@ function getNamespacedStorageItems(
   origContractDef: ContractDefinition,
 ): StorageItem[] {
   const storageItems: StorageItem[] = [];
+  const docs = context.structDocs === undefined ? undefined : context.structDocs(node);
 
   for (const astMember of getTypeMembers(node, { typeName: true })) {
     const item: StorageItem = {
@@ -247,6 +260,10 @@ function getNamespacedStorageItems(
       src: decodeSrc({ src: getOriginalMemberSrc(node.canonicalName, astMember.label, origContractDef) }),
     };
 
+    if (docs !== undefined) {
+      setMemberAnnotations(item, docs);
+    }
+
     const layoutMember = findLayoutStructMember(
       context.storageLayout?.types ?? {},
       node.canonicalName,
@@ -262,7 +279,7 @@ function getNamespacedStorageItems(
 
     // If context is namespaced, we have storage layout, and this will fill in enum members just like in extractStorageLayout.
     // If context is original, this will add the types from the namespace structs to the layout.
-    loadLayoutType(astMember.typeName, layout, context.deref);
+    loadLayoutType(astMember.typeName, layout, context.deref, context.structDocs);
   }
   return storageItems;
 }

package/src/storage/report-rename-retype.test.ts

@@ -9,6 +9,8 @@ import { getStorageUpgradeErrors } from '.';
 
 interface Context {
   extractStorageLayout: (contract: string) => ReturnType<typeof extractStorageLayout>;
+  // Without the compiler's storage layout, the variables have no slots
+  extractStorageLayoutWithoutSlots: (contract: string) => ReturnType<typeof extractStorageLayout>;
 }
 
 const test = _test as TestFn<Context>;
@@ -50,6 +52,8 @@ test.before(async t => {
 
   t.context.extractStorageLayout = name =>
     extractStorageLayout(contracts[name], dummyDecodeSrc, deref[name], storageLayout[name]);
+  t.context.extractStorageLayoutWithoutSlots = name =>
+    extractStorageLayout(contracts[name], dummyDecodeSrc, deref[name]);
 });
 
 function getReport(original: StorageLayout, updated: StorageLayout) {
@@ -130,3 +134,40 @@ test('retype with layout change', t => {
   t.false(report.ok);
   t.snapshot(report.explain());
 });
+
+test('retype without layout info', t => {
+  // Without slots, a retype is uncertain unless the types are known to be compatible
+  const v1 = t.context.extractStorageLayoutWithoutSlots('NonHardcodedRetypeV1');
+  const v2 = t.context.extractStorageLayoutWithoutSlots('NonHardcodedRetypeV2');
+  const report = getReport(v1, v2);
+  t.false(report.ok);
+  t.true(report.explain().includes('Layout could have changed for `a` (address -> bytes20)'), report.explain());
+
+  const compatibleV1 = t.context.extractStorageLayoutWithoutSlots('RetypeV1');
+  const compatibleV2 = t.context.extractStorageLayoutWithoutSlots('RetypeV2');
+  t.true(getReport(compatibleV1, compatibleV2).ok);
+});
+
+test('kept retype annotation without layout info', t => {
+  // Upgrading from and to the same contract: `a` stays `bytes20` and keeps its `@custom:oz-retyped-from address`
+  // annotation from an earlier retype, which doesn't apply to this upgrade
+  const original = t.context.extractStorageLayoutWithoutSlots('NonHardcodedRetypeV2');
+  const updated = t.context.extractStorageLayoutWithoutSlots('NonHardcodedRetypeV2');
+  t.true(getReport(original, updated).ok);
+});
+
+test('rename annotation without rename', t => {
+  const v1 = t.context.extractStorageLayout('StaleRenameV1');
+  const v2 = t.context.extractStorageLayout('StaleRenameV2');
+  const report = getReport(v1, v2);
+  t.false(report.ok);
+  t.is(
+    report.explain(),
+    "file.sol:1: `y` has a '@custom:oz-renamed-from x' annotation, but it was not renamed\n" +
+      '  > If the annotation is left over from an earlier upgrade, remove it.',
+  );
+
+  // A rename to a different name is reported as such
+  const renamed = getReport(v1, t.context.extractStorageLayout('RenameV1'));
+  t.is(renamed.explain(), 'file.sol:1: Renamed `y` to `x`');
+});

package/src/storage/report.ts

@@ -109,8 +109,16 @@ function explainStorageOperation(op: StorageOperation<StorageField>, ctx: Storag
     case 'finishgap':
       return `Converted end of storage gap ${label(op.original)} to ${label(op.updated)}`;
 
-    case 'rename':
+    case 'rename': {
+      if (op.original.label === op.updated.label && op.updated.renamedFrom !== undefined) {
+        // The field keeps its name, so the annotation describes a rename that did not happen in this upgrade
+        return printWithHints({
+          title: `${label(op.updated)} has a '@custom:oz-renamed-from ${op.updated.renamedFrom}' annotation, but it was not renamed`,
+          hints: ['If the annotation is left over from an earlier upgrade, remove it.'],
+        });
+      }
       return `Renamed ${label(op.original)} to ${label(op.updated)}`;
+    }
 
     case 'replace':
       return `Replaced ${label(op.original)} with ${label(op.updated)} of incompatible type`;

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