@openzeppelin/upgrades-core 1.28.0 → 1.30.0

package/src/impl-address.ts

@@ -1,12 +1,11 @@
-import { keccak256 } from 'ethereumjs-util';
 import {
-  call,
   EIP1967BeaconNotFound,
   EIP1967ImplementationNotFound,
   getBeaconAddress,
   getImplementationAddress,
   UpgradesError,
 } from '.';
+import { callOptionalSignature } from './call-optional-signature';
 
 import { EthereumProvider } from './provider';
 import { parseAddress } from './utils/address';
@@ -24,27 +23,17 @@ export async function getImplementationAddressFromBeacon(
   provider: EthereumProvider,
   beaconAddress: string,
 ): Promise<string> {
-  const implementationFunction = '0x' + keccak256(Buffer.from('implementation()')).toString('hex').slice(0, 8);
-  let result: string | undefined;
-  try {
-    const implAddress = await call(provider, beaconAddress, implementationFunction);
-    result = parseAddress(implAddress);
-  } catch (e: any) {
-    if (
-      !(
-        e.message.includes('function selector was not recognized') ||
-        e.message.includes('invalid opcode') ||
-        e.message.includes('revert') ||
-        e.message.includes('execution error')
-      )
-    ) {
-      throw e;
-    } // otherwise fall through with no result
+  const impl = await callOptionalSignature(provider, beaconAddress, 'implementation()');
+  let parsedImplAddress;
+  if (impl !== undefined) {
+    parsedImplAddress = parseAddress(impl);
   }
-  if (result === undefined) {
+
+  if (parsedImplAddress === undefined) {
     throw new InvalidBeacon(`Contract at ${beaconAddress} doesn't look like a beacon`);
+  } else {
+    return parsedImplAddress;
   }
-  return result;
 }
 
 /**

package/src/index.ts

@@ -57,3 +57,6 @@ export {
 } from './usage-error';
 
 export { ValidateUpgradeSafetyOptions, validateUpgradeSafety, ProjectReport, ReferenceContractNotFound } from './cli';
+
+export { getUpgradeInterfaceVersion } from './upgrade-interface-version';
+export { makeNamespacedInput } from './utils/make-namespaced';

package/src/levenshtein.ts

@@ -6,6 +6,13 @@ export type BasicOperation<T> =
   | {
       kind: 'delete';
       original: T;
+    }
+  | {
+      kind: 'delete-namespace';
+      namespace: string;
+      original: {
+        contract: string;
+      };
     };
 
 export type Operation<T, C> = C | BasicOperation<T>;

package/src/solc-api.ts

@@ -22,6 +22,13 @@ export interface SolcOutput {
       id: number;
     };
   };
+  errors?: {
+    severity: 'error' | 'warning';
+    formattedMessage: string;
+    sourceLocation?: {
+      file: string;
+    };
+  }[];
 }
 
 export interface SolcInput {
@@ -30,6 +37,13 @@ export interface SolcInput {
       content?: string;
     };
   };
+  settings?: {
+    outputSelection?: {
+      [file in string]: {
+        [contract in string]: string[];
+      };
+    };
+  };
 }
 
 export type SolcLinkReferences = {

package/src/standalone.test.ts

@@ -61,3 +61,29 @@ test('dont report renamed version update', t => {
   const goodReport2 = v2.getStorageUpgradeReport(v3);
   t.true(goodReport2.ok);
 });
+
+test('namespaced output', async t => {
+  const buildInfo = await artifacts.getBuildInfo('contracts/test/Namespaced.sol:Example');
+  if (buildInfo === undefined) {
+    throw new Error('Build info not found');
+  }
+
+  const impl = new UpgradeableContract('Example', buildInfo.input, buildInfo.output, {}, '0.8.20');
+  const report = impl.getErrorReport();
+  t.true(report.ok);
+});
+
+test('namespaced output without version', async t => {
+  const buildInfo = await artifacts.getBuildInfo('contracts/test/Namespaced.sol:Example');
+  if (buildInfo === undefined) {
+    throw new Error('Build info not found');
+  }
+
+  const error = t.throws(() => new UpgradeableContract('Example', buildInfo.input, buildInfo.output));
+  t.assert(
+    error?.message.includes(
+      `contracts/test/Namespaced.sol: Namespace annotations require Solidity version >= 0.8.20, but no solcVersion parameter was provided`,
+    ),
+    error?.message,
+  );
+});

package/src/standalone.ts

@@ -18,6 +18,9 @@ export interface Report {
   explain(color?: boolean): string;
 }
 
+/**
+ * @deprecated Use `validateUpgradeSafety` instead.
+ */
 export class UpgradeableContract {
   readonly version: Version;
   readonly errors: ValidationError[];
@@ -28,11 +31,12 @@ export class UpgradeableContract {
     solcInput: SolcInput,
     solcOutput: SolcOutput,
     opts: ValidationOptions = {},
+    solcVersion?: string,
   ) {
     const decodeSrc = solcInputOutputDecoder(solcInput, solcOutput);
-    const validation = validate(solcOutput, decodeSrc);
+    const validation = validate(solcOutput, decodeSrc, solcVersion, solcInput);
     this.version = getContractVersion(validation, name);
-    this.errors = getErrors(validation, this.version, opts);
+    this.errors = getErrors(validation, this.version, withValidationDefaults(opts));
     this.layout = getStorageLayout(validation, this.version);
   }
 

package/src/storage/compare.ts

@@ -108,8 +108,40 @@ export class StorageLayoutComparator {
     readonly unsafeAllowRenames = false,
   ) {}
 
-  compareLayouts(original: StorageItem[], updated: StorageItem[]): LayoutCompatibilityReport {
-    return new LayoutCompatibilityReport(this.layoutLevenshtein(original, updated, { allowAppend: true }));
+  compareLayouts(
+    original: StorageItem[],
+    updated: StorageItem[],
+    originalNamespaces?: Record<string, StorageItem[]>,
+    updatedNamespaces?: Record<string, StorageItem[]>,
+  ): LayoutCompatibilityReport {
+    const ops = this.layoutLevenshtein(original, updated, { allowAppend: true });
+    const namespacedOps = this.getNamespacedStorageOperations(originalNamespaces, updatedNamespaces);
+
+    return new LayoutCompatibilityReport([...ops, ...namespacedOps]);
+  }
+
+  private getNamespacedStorageOperations(
+    originalNamespaces?: Record<string, StorageItem[]>,
+    updatedNamespaces?: Record<string, StorageItem[]>,
+  ) {
+    const ops: StorageOperation<StorageItem>[] = [];
+    if (originalNamespaces !== undefined) {
+      for (const [storageLocation, origNamespacedLayout] of Object.entries(originalNamespaces)) {
+        const updatedNamespacedLayout = updatedNamespaces?.[storageLocation];
+        if (updatedNamespacedLayout !== undefined) {
+          ops.push(...this.layoutLevenshtein(origNamespacedLayout, updatedNamespacedLayout, { allowAppend: true }));
+        } else if (origNamespacedLayout.length > 0) {
+          ops.push({
+            kind: 'delete-namespace',
+            namespace: storageLocation,
+            original: {
+              contract: origNamespacedLayout[0].contract,
+            },
+          });
+        }
+      }
+    }
+    return ops;
   }
 
   private layoutLevenshtein<F extends StorageField>(

package/src/storage/extract.ts

@@ -1,18 +1,20 @@
-import assert from 'assert';
+import assert from 'assert/strict';
 import {
   ContractDefinition,
   StructDefinition,
   EnumDefinition,
   TypeDescriptions,
   VariableDeclaration,
+  TypeName,
 } from 'solidity-ast';
 import { isNodeType, findAll, ASTDereferencer } from 'solidity-ast/utils';
-import { StorageLayout, TypeItem } from './layout';
+import { StorageLayout, 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 { loadNamespaces } from './namespace';
 
 const currentLayoutVersion = '1.2';
 
@@ -20,31 +22,53 @@ export function isCurrentLayoutVersion(layout: StorageLayout): boolean {
   return layout?.layoutVersion === currentLayoutVersion;
 }
 
+export interface CompilationContext {
+  deref: ASTDereferencer;
+  contractDef: ContractDefinition;
+  storageLayout?: StorageLayout;
+}
+
 export function extractStorageLayout(
   contractDef: ContractDefinition,
   decodeSrc: SrcDecoder,
   deref: ASTDereferencer,
-  storageLayout?: StorageLayout | undefined,
+  storageLayout?: StorageLayout,
+  namespacedContext?: CompilationContext,
 ): StorageLayout {
   const layout: StorageLayout = { storage: [], types: {}, layoutVersion: currentLayoutVersion, flat: false };
-  if (storageLayout !== undefined) {
-    layout.types = mapValues(storageLayout.types, m => {
-      return {
-        label: m.label,
-        members: m.members?.map(m =>
-          typeof m === 'string' ? m : pick(m, ['label', 'type', 'offset', 'slot']),
-        ) as TypeItem['members'],
-        numberOfBytes: m.numberOfBytes,
-      };
-    });
 
+  // The namespaced context will contain the types of namespaces that may not be included
+  // in the original storage layout.
+  // Some types will be present in both and they must be exactly equivalent.
+  // If they are not, it fails an assertion because this may be a clash between different types.
+  const combinedTypes = { ...namespacedContext?.storageLayout?.types, ...storageLayout?.types };
+  if (namespacedContext?.storageLayout?.types) {
+    for (const t in storageLayout?.types) {
+      if (t in namespacedContext.storageLayout.types) {
+        assert.deepEqual(namespacedContext.storageLayout.types[t], storageLayout?.types[t]);
+      }
+    }
+  }
+
+  layout.types = mapValues(combinedTypes, m => {
+    return {
+      label: m.label,
+      members:
+        m.members && isStructMembers(m.members)
+          ? m.members.map(m => pick(m, ['label', 'type', 'offset', 'slot']))
+          : m.members,
+      numberOfBytes: m.numberOfBytes,
+    };
+  });
+
+  if (storageLayout !== undefined) {
     for (const storage of storageLayout.storage) {
       const origin = getOriginContract(contractDef, storage.astId, deref);
       assert(origin, `Did not find variable declaration node for '${storage.label}'`);
       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, layout, deref);
+      loadLayoutType(varDecl.typeName, layout, deref);
       const { label, offset, slot, type } = storage;
       const src = decodeSrc(varDecl);
       layout.storage.push({ label, offset, slot, type, contract, src, retypedFrom, renamedFrom });
@@ -65,11 +89,15 @@ export function extractStorageLayout(
             renamedFrom,
           });
 
-          loadLayoutType(varDecl, layout, deref);
+          loadLayoutType(varDecl.typeName, layout, deref);
         }
       }
     }
   }
+
+  const origContext = { deref, contractDef, storageLayout };
+  loadNamespaces(decodeSrc, layout, origContext, namespacedContext);
+
   return layout;
 }
 
@@ -92,14 +120,34 @@ function typeDescriptions(x: { typeDescriptions: TypeDescriptions }): RequiredTy
   return x.typeDescriptions as RequiredTypeDescriptions;
 }
 
-function getTypeMembers(typeDef: StructDefinition | EnumDefinition): TypeItem['members'] {
+type GotTypeMembers<
+  D extends EnumDefinition | StructDefinition,
+  F extends 'src' | 'typeName',
+> = D extends EnumDefinition ? EnumMember[] : (StructMember & Pick<VariableDeclaration, F>)[];
+
+export function getTypeMembers<D extends EnumDefinition | StructDefinition>(typeDef: D): GotTypeMembers<D, never>;
+export function getTypeMembers<D extends EnumDefinition | StructDefinition, F extends 'src' | 'typeName'>(
+  typeDef: D,
+  includeFields: { [f in F]: true },
+): GotTypeMembers<D, F>;
+export function getTypeMembers(
+  typeDef: StructDefinition | EnumDefinition,
+  includeFields: { src?: boolean; typeName?: boolean } = {},
+): TypeItem['members'] {
   if (typeDef.nodeType === 'StructDefinition') {
     return typeDef.members.map(m => {
       assert(typeof m.typeDescriptions.typeIdentifier === 'string');
-      return {
+      const member: StructMember & Partial<Pick<VariableDeclaration, 'src' | 'typeName'>> = {
         label: m.name,
         type: normalizeTypeIdentifier(m.typeDescriptions.typeIdentifier),
       };
+      if (includeFields.src && m.src) {
+        member.src = m.src;
+      }
+      if (includeFields.typeName && m.typeName) {
+        member.typeName = m.typeName;
+      }
+      return member;
     });
   } else {
     return typeDef.members.map(m => m.name);
@@ -116,16 +164,16 @@ function getOriginContract(contract: ContractDefinition, astId: number | undefin
   }
 }
 
-function loadLayoutType(varDecl: VariableDeclaration, layout: StorageLayout, deref: ASTDereferencer) {
+export function loadLayoutType(typeName: TypeName | null | undefined, layout: StorageLayout, deref: ASTDereferencer) {
   // Note: A UserDefinedTypeName can also refer to a ContractDefinition but we won't care about those.
   const derefUserDefinedType = deref(['StructDefinition', 'EnumDefinition', 'UserDefinedValueTypeDefinition']);
 
-  assert(varDecl.typeName != null);
+  assert(typeName != null);
 
   // We will recursively look for all types involved in this variable declaration in order to store their type
   // information. We iterate over a Map that is indexed by typeIdentifier to ensure we visit each type only once.
   // Note that there can be recursive types.
-  const typeNames = new Map([...findTypeNames(varDecl.typeName)].map(n => [typeDescriptions(n).typeIdentifier, n]));
+  const typeNames = new Map([...findTypeNames(typeName)].map(n => [typeDescriptions(n).typeIdentifier, n]));
 
   for (const typeName of typeNames.values()) {
     const { typeIdentifier, typeString: label } = typeDescriptions(typeName);

package/src/storage/index.ts

@@ -43,8 +43,16 @@ export function getStorageUpgradeReport(
 ): LayoutCompatibilityReport {
   const originalDetailed = getDetailedLayout(original);
   const updatedDetailed = getDetailedLayout(updated);
+  const originalDetailedNamespaces = getDetailedNamespacedLayout(original);
+  const updatedDetailedNamespaces = getDetailedNamespacedLayout(updated);
+
   const comparator = new StorageLayoutComparator(opts.unsafeAllowCustomTypes, opts.unsafeAllowRenames);
-  const report = comparator.compareLayouts(originalDetailed, updatedDetailed);
+  const report = comparator.compareLayouts(
+    originalDetailed,
+    updatedDetailed,
+    originalDetailedNamespaces,
+    updatedDetailedNamespaces,
+  );
 
   if (comparator.hasAllowedUncheckedCustomTypes) {
     logWarning(`Potentially unsafe deployment`, [
@@ -58,6 +66,19 @@ export function getStorageUpgradeReport(
   return report;
 }
 
+function getDetailedNamespacedLayout(layout: StorageLayout): Record<string, StorageItem[]> {
+  const detailedNamespaces: Record<string, StorageItem[]> = {};
+  if (layout.namespaces !== undefined) {
+    for (const [storageLocation, namespacedLayout] of Object.entries(layout.namespaces)) {
+      detailedNamespaces[storageLocation] = getDetailedLayout({
+        storage: namespacedLayout,
+        types: layout.types,
+      });
+    }
+  }
+  return detailedNamespaces;
+}
+
 export class StorageUpgradeErrors extends UpgradesError {
   constructor(readonly report: LayoutCompatibilityReport) {
     super(`New storage layout is incompatible`, () => report.explain());

package/src/storage/layout.ts

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

package/src/storage/namespace.ts

@@ -0,0 +1,262 @@
+import assert from 'assert';
+import { ContractDefinition, StructDefinition } from 'solidity-ast';
+import { isNodeType } from 'solidity-ast/utils';
+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 { UpgradesError } from '../error';
+
+/**
+ * Loads a contract's namespaces and namespaced type information into the storage layout.
+ *
+ * The provided compilation contexts must include both the original compilation and optionally
+ * a namespaced compilation where contracts have been modified to include namespaced type information.
+ *
+ * If namespaced compilation is included, storage slots and offsets will be included in the loaded namespaces and types.
+ *
+ * This function looks up namespaces and their members from the namespaced compilation context's AST if available
+ * (meaning node ids would be from the namespaced compilation), and looks up slots and offsets from the compiled type information.
+ * However, it saves the original source locations from the original context so that line numbers are
+ * consistent with the original source code.
+ *
+ * @param decodeSrc Source decoder for the original source code.
+ * @param layout The storage layout object to load namespaces into.
+ * @param origContext The original compilation context, which is used to lookup original source locations.
+ * @param namespacedContext The namespaced compilation context, which represents a namespaced compilation.
+ */
+export function loadNamespaces(
+  decodeSrc: SrcDecoder,
+  layout: StorageLayout,
+  origContext: CompilationContext,
+  namespacedContext?: CompilationContext,
+) {
+  const namespacesWithSrc: Record<string, NamespaceWithSrc> = {};
+
+  const origLinearized = origContext.contractDef.linearizedBaseContracts.map(id =>
+    getReferencedContract(origContext, id),
+  );
+  const namespacedLinearized = namespacedContext?.contractDef.linearizedBaseContracts.map(id =>
+    getReferencedContract(namespacedContext, id),
+  );
+  assert(namespacedLinearized === undefined || origLinearized.length === namespacedLinearized.length);
+  const context = namespacedContext ?? origContext;
+  const linearized = namespacedLinearized ?? origLinearized;
+  for (const [i, contractDef] of linearized.entries()) {
+    const origContractDef = origLinearized[i];
+    const contractContext = { ...context, contractDef };
+    addContractNamespacesWithSrc(
+      namespacesWithSrc,
+      decodeSrc,
+      layout,
+      contractContext,
+      origContractDef,
+      origContext.contractDef.canonicalName ?? origContext.contractDef.name,
+    );
+  }
+
+  // Add to layout without the namespaced structs' src locations, since those are no longer needed
+  // as they were only used to give duplicate namespace errors above.
+  layout.namespaces = Object.fromEntries(
+    Object.entries(namespacesWithSrc).map(([id, namespaceWithSrc]) => [id, namespaceWithSrc.namespace]),
+  );
+}
+
+class DuplicateNamespaceError extends UpgradesError {
+  constructor(id: string, contractName: string, src1: string, src2: string) {
+    super(
+      `Namespace ${id} is defined multiple times for contract ${contractName}`,
+      () => `\
+The namespace ${id} was found in structs at the following locations:
+- ${src1}
+- ${src2}
+
+Use a unique namespace id for each struct annotated with '@custom:storage-location erc7201:<NAMESPACE_ID>' in your contract and its inherited contracts.`,
+    );
+  }
+}
+
+/**
+ * Namespaced storage items, along with the original source location of the namespace struct.
+ */
+interface NamespaceWithSrc {
+  namespace: StorageItem<string>[];
+  src: string;
+}
+
+/**
+ * Gets the contract definition for the given referenced id.
+ */
+function getReferencedContract(context: CompilationContext, referencedId: number) {
+  // Optimization to avoid dereferencing if the referenced id is the same as the current contract
+  return context.contractDef.id === referencedId
+    ? context.contractDef
+    : context.deref(['ContractDefinition'], referencedId);
+}
+
+/**
+ * Add namespaces and source locations for the given compilation context's contract.
+ * Does not include inherited contracts.
+ *
+ * @param namespacesWithSrc The record of namespaces with source locations to add to.
+ * @param decodeSrc Source decoder for the original source code.
+ * @param layout The storage layout object to load types into.
+ * @param contractContext The compilation context for this specific contract to load namespaces for.
+ * @param origContractDef The AST node for this specific contract but from the original compilation context.
+ * @param leastDerivedContractName The name of the least derived contract in the inheritance list.
+ * @throws DuplicateNamespaceError if a duplicate namespace is found when adding to the `namespaces` record.
+ */
+function addContractNamespacesWithSrc(
+  namespacesWithSrc: Record<string, NamespaceWithSrc>,
+  decodeSrc: SrcDecoder,
+  layout: StorageLayout,
+  contractContext: CompilationContext,
+  origContractDef: ContractDefinition,
+  leastDerivedContractName: string,
+) {
+  for (const node of contractContext.contractDef.nodes) {
+    if (isNodeType('StructDefinition', node)) {
+      const storageLocation = getStorageLocationAnnotation(node);
+      if (storageLocation !== undefined) {
+        const origSrc = decodeSrc(getOriginalStruct(node.canonicalName, origContractDef));
+
+        if (namespacesWithSrc[storageLocation] !== undefined) {
+          throw new DuplicateNamespaceError(
+            storageLocation,
+            leastDerivedContractName,
+            namespacesWithSrc[storageLocation].src,
+            origSrc,
+          );
+        } else {
+          namespacesWithSrc[storageLocation] = {
+            namespace: getNamespacedStorageItems(node, decodeSrc, layout, contractContext, origContractDef),
+            src: origSrc,
+          };
+        }
+      }
+    }
+  }
+}
+
+/**
+ * Gets the storage location string from the `@custom:storage-location` annotation.
+ *
+ * For example, when using ERC-7201 (https://eips.ethereum.org/EIPS/eip-7201), the result will be `erc7201:<NAMESPACE_ID>`
+ *
+ * @param node The node that may have a `@custom:storage-location` annotation.
+ * @returns The storage location string, or undefined if the node does not have a `@custom:storage-location` annotation.
+ * @throws Error if the node has the annotation `@custom:storage-location` but it does not have exactly one argument.
+ */
+export function getStorageLocationAnnotation(node: Node) {
+  const doc = getDocumentation(node);
+  if (hasAnnotationTag(doc, 'storage-location')) {
+    const storageLocationArgs = getAnnotationArgs(doc, 'storage-location');
+    if (storageLocationArgs.length !== 1) {
+      throw new Error('@custom:storage-location annotation must have exactly one argument');
+    }
+    return storageLocationArgs[0];
+  }
+}
+
+/**
+ * Gets the storage items for the given struct node.
+ * Includes loading recursive type information, and adds slot and offset if they are available in the given compilation context's layout.
+ */
+function getNamespacedStorageItems(
+  node: StructDefinition,
+  decodeSrc: SrcDecoder,
+  layout: StorageLayout,
+  context: CompilationContext,
+  origContractDef: ContractDefinition,
+): StorageItem[] {
+  const storageItems: StorageItem[] = [];
+
+  for (const astMember of getTypeMembers(node, { typeName: true })) {
+    const item: StorageItem = {
+      contract: context.contractDef.name,
+      label: astMember.label,
+      type: astMember.type,
+      src: decodeSrc({ src: getOriginalMemberSrc(node.canonicalName, astMember.label, origContractDef) }),
+    };
+
+    const layoutMember = findLayoutStructMember(
+      context.storageLayout?.types ?? {},
+      node.canonicalName,
+      astMember.label,
+    );
+
+    if (layoutMember?.offset !== undefined && layoutMember?.slot !== undefined) {
+      item.offset = layoutMember.offset;
+      item.slot = layoutMember.slot;
+    }
+
+    storageItems.push(item);
+
+    // 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);
+  }
+  return storageItems;
+}
+
+/**
+ * Gets the struct definition matching the given canonical name from the original contract definition.
+ */
+function getOriginalStruct(structCanonicalName: string, origContractDef: ContractDefinition) {
+  for (const node of origContractDef.nodes) {
+    if (isNodeType('StructDefinition', node)) {
+      if (node.canonicalName === structCanonicalName) {
+        return node;
+      }
+    }
+  }
+  throw new Error(
+    `Could not find original source location for namespace struct with name ${structCanonicalName} from contract ${origContractDef.name}`,
+  );
+}
+
+/**
+ * Gets the original source location for the given struct canonical name and struct member label.
+ */
+function getOriginalMemberSrc(structCanonicalName: string, memberLabel: string, origContractDef: ContractDefinition) {
+  const node = getOriginalStruct(structCanonicalName, origContractDef);
+  if (node !== undefined) {
+    for (const member of getTypeMembers(node, { src: true })) {
+      if (member.label === memberLabel) {
+        return member.src;
+      }
+    }
+  }
+
+  throw new Error(
+    `Could not find original source location for namespace struct with name ${structCanonicalName} and member ${memberLabel}`,
+  );
+}
+
+/**
+ * From the given layout types, gets the struct member matching the given struct canonical name and struct member label.
+ */
+function findLayoutStructMember(
+  types: Record<string, TypeItem<string>>,
+  structCanonicalName: string,
+  memberLabel: string,
+) {
+  const structType = findTypeWithLabel(types, `struct ${structCanonicalName}`);
+  const structMembers = structType?.members;
+  if (structMembers !== undefined) {
+    assert(isStructMembers(structMembers));
+    for (const structMember of structMembers) {
+      if (structMember.label === memberLabel) {
+        return structMember;
+      }
+    }
+  }
+}
+
+/**
+ * From the given layout types, gets the type matching the given type label.
+ */
+function findTypeWithLabel(types: Record<string, TypeItem>, label: string) {
+  return Object.values(types).find(type => type.label === label);
+}