slotdiff 0.1.0-alpha.1 → 0.2.0-alpha.1

package/src/erc7201.ts

@@ -0,0 +1,412 @@
+/**
+ * ERC-7201 namespaces by the slot the code really uses.
+ *
+ * OpenZeppelin matches namespaces by their `@custom:storage-location
+ * erc7201:<id>` annotation and never checks the `bytes32` slot the code assigns
+ * (`assembly { $.slot := LOCATION }`). The two can disagree. A changed
+ * constant behind an unchanged annotation moves the storage while the layout
+ * check passes; a corrected annotation over an unchanged constant leaves the
+ * storage in place while the check reports a deleted namespace. Reading the
+ * slot from the AST catches the first and fixes the second.
+ */
+
+import type { SolcOutput, StorageLayout } from "@openzeppelin/upgrades-core";
+// Not exported from the package index; the package has no exports map, and
+// all exist since 1.46.0, the lowest version slotdiff accepts.
+import { getStorageLocationAnnotation } from "@openzeppelin/upgrades-core/dist/storage/namespace.js";
+import { calculateERC7201StorageLocation } from "@openzeppelin/upgrades-core/dist/utils/erc7201.js";
+import { resolveBaseSlot } from "@openzeppelin/upgrades-core/dist/utils/erc7201-builtin.js";
+import {
+  normalizeUint256Literal,
+  toBytes32Hex,
+} from "@openzeppelin/upgrades-core/dist/utils/integer-literals.js";
+
+export interface NamespaceSlot {
+  /** `erc7201:<id>`, as annotated. */
+  namespace: string;
+  /** The slot the annotation implies. */
+  expected: string;
+  /** The slot the code assigns, when it could be read and is unique. */
+  actual?: string;
+  /**
+   * `match`: the code uses the annotated slot. `mismatch`: it uses `actual`
+   * instead. `conflict`: it assigns different slots in different places.
+   * `unread`: no assignment was found, or one could not be evaluated.
+   */
+  status: "match" | "mismatch" | "conflict" | "unread";
+}
+
+interface AstNode {
+  nodeType?: string;
+  id?: number;
+  [key: string]: unknown;
+}
+
+/**
+ * How each of `namespaces` (`erc7201:<id>` keys of `contract`'s layout,
+ * `source.sol:Name`) is assigned in `output`. Only structs declared in the
+ * contract or its bases count, as for OpenZeppelin: a sibling contract in the
+ * same build (a V1 next to its V2, a test copy) may declare the same id.
+ */
+export function namespaceSlots(
+  output: SolcOutput,
+  contract: string,
+  namespaces: string[],
+): NamespaceSlot[] {
+  const colon = contract.lastIndexOf(":");
+  // Most derived first, as solc lists them: the order virtual calls resolve in.
+  let linearized: number[] = [];
+  walk(output.sources?.[contract.slice(0, colon)]?.ast, (node) => {
+    if (node.nodeType === "ContractDefinition" && node.name === contract.slice(colon + 1)) {
+      linearized = node.linearizedBaseContracts as number[];
+    }
+  });
+  const bases = new Set(linearized);
+
+  // Only code the contract can run counts: its bases (minus the functions they
+  // override), libraries and free functions, not a sibling contract (a test
+  // harness) in the same files.
+  const byId = new Map<number, AstNode>();
+  const touched = new Set<number>();
+  const overridden = new Set<number>();
+  for (const source of Object.values(output.sources ?? {})) {
+    walk(source.ast as unknown as AstNode, (node) => {
+      if (typeof node.id === "number") byId.set(node.id, node);
+      // Any Solidity use of a local after its declaration, so a local is read
+      // only when nothing but assembly reads it.
+      if (node.nodeType === "Identifier") touched.add(node.referencedDeclaration as number);
+      if (node.nodeType === "FunctionDefinition" && bases.has(node.scope as number)) {
+        for (const base of (node.baseFunctions ?? []) as number[]) overridden.add(base);
+      }
+    });
+  }
+  const assemblies: AstNode[] = [];
+  for (const source of Object.values(output.sources ?? {})) {
+    walk(source.ast as unknown as AstNode, (node) => {
+      const sibling =
+        node.nodeType === "ContractDefinition" &&
+        node.contractKind !== "library" &&
+        !bases.has(node.id as number);
+      if (sibling || overridden.has(node.id as number)) return false;
+      if (node.nodeType === "InlineAssembly") assemblies.push(node);
+    });
+  }
+  const ctx = { byId, linearized, bases, touched };
+
+  // Struct id → every slot value assigned to a pointer of that struct (undefined: unreadable).
+  const assigned = new Map<number, Array<string | undefined>>();
+  for (const assembly of assemblies) {
+    const refs = (assembly.externalReferences ?? []) as Array<{
+      declaration: number;
+      src: string;
+      suffix?: string;
+    }>;
+    const declarationAt = (src: unknown) => refs.find((r) => r.src === src)?.declaration ?? -1;
+    walk(assembly.AST as AstNode, (node) => {
+      if (node.nodeType !== "YulAssignment") return;
+      for (const target of node.variableNames as AstNode[]) {
+        if (typeof target.name !== "string") continue;
+        if (!target.name.endsWith(".slot")) {
+          touched.add(declarationAt(target.src));
+          continue;
+        }
+        const pointer = byId.get(declarationAt(target.src));
+        const struct = (pointer?.typeName as AstNode | undefined)?.referencedDeclaration;
+        if (typeof struct !== "number") continue;
+        const value = node.value as AstNode;
+        const slot =
+          value.nodeType === "YulLiteral"
+            ? value.kind === "number"
+              ? normalize(value.value)
+              : undefined
+            : resolveDecl(ctx, byId.get(declarationAt(value.src)));
+        assigned.set(struct, [...(assigned.get(struct) ?? []), slot]);
+      }
+    });
+  }
+
+  return namespaces.map((namespace) => {
+    const expected = calculateERC7201StorageLocation(namespace.slice("erc7201:".length));
+    const slots = [...byId.values()]
+      .filter(
+        (n) =>
+          n.nodeType === "StructDefinition" &&
+          bases.has(n.scope as number) &&
+          getStorageLocationAnnotation(n as never) === namespace,
+      )
+      .flatMap((n) => assigned.get(n.id!) ?? []);
+    const known = [...new Set(slots.filter((s) => s !== undefined))];
+    if (known.length > 1) return { namespace, expected, status: "conflict" };
+    if (known.length === 0 || slots.includes(undefined)) {
+      return { namespace, expected, status: "unread" };
+    }
+    const actual = known[0];
+    return actual === expected
+      ? { namespace, expected, actual, status: "match" }
+      : { namespace, expected, actual, status: "mismatch" };
+  });
+}
+
+export interface NamespacePair {
+  old?: NamespaceSlot;
+  next?: NamespaceSlot;
+  /**
+   * Why this pair fails the check: `<new>` assigns several slots (`conflict`),
+   * leaves the old data behind (`moved`), or keeps the data in place under an
+   * annotation that does not match (`mismatch`). `unread`: a slot could not be
+   * read, so the pair could not be checked.
+   */
+  problem?: "conflict" | "moved" | "mismatch" | "unread";
+}
+
+export interface NamespaceCheck {
+  /**
+   * `old`'s layout with each paired namespace under its name in `<new>`, for
+   * `diffLayouts`: OpenZeppelin then compares the structs of the same storage.
+   * An unpaired namespace keeps its name, so one that is really gone is still
+   * reported as deleted.
+   */
+  layout: StorageLayout;
+  /** Every namespace of either side, old and new paired when they are the same storage. */
+  pairs: NamespacePair[];
+  /** `fail` when any pair has a problem other than `unread`; `unread` when a slot could not be read. */
+  result: "pass" | "fail" | "unread";
+}
+
+/**
+ * Checks ERC-7201 namespaces by the slot the code uses, not the annotation
+ * OpenZeppelin goes by. An old and a new namespace are the same storage when
+ * the code uses the same slot (under the same annotation first), failing that
+ * when they share an annotation, and failing that when the new annotation
+ * names the slot where the old data is.
+ * Pass `layout` to `diffLayouts` in place of `old.layout`.
+ */
+export function checkNamespaces(
+  old: { layout: StorageLayout; namespaces: NamespaceSlot[] },
+  next: { namespaces: NamespaceSlot[] },
+): NamespaceCheck {
+  const unpaired = new Set(old.namespaces);
+  const pairs: NamespacePair[] = next.namespaces.map((n) => ({ next: n }));
+  const sameSlot = (o: NamespaceSlot, n: NamespaceSlot) =>
+    o.actual !== undefined && n.actual !== undefined && same(o.actual, n.actual);
+  const rules: Array<(o: NamespaceSlot, n: NamespaceSlot) => boolean> = [
+    (o, n) => sameSlot(o, n) && o.namespace === n.namespace,
+    sameSlot,
+    (o, n) => o.namespace === n.namespace,
+    (o, n) => o.actual !== undefined && same(o.actual, n.expected),
+  ];
+  // Rule by rule over every namespace, so a weaker rule never takes a pair from a stronger one.
+  for (const rule of rules) {
+    for (const pair of pairs) {
+      const o = pair.old ?? [...unpaired].find((o) => rule(o, pair.next!));
+      if (o !== undefined && unpaired.delete(o)) pair.old = o;
+    }
+  }
+  for (const o of unpaired) pairs.push({ old: o });
+  for (const pair of pairs) pair.problem = problemOf(pair);
+
+  // Renamed all at once, so two namespaces can swap names.
+  const renames = new Map(
+    pairs.flatMap((p) =>
+      p.old !== undefined && p.next !== undefined ? [[p.old.namespace, p.next.namespace]] : [],
+    ),
+  );
+  const oldNames = Object.keys(old.layout.namespaces ?? {});
+  const renamed = oldNames.map((name) => renames.get(name) ?? name);
+  // On a clash (an old namespace that stays keeps the name another would take)
+  // nothing is renamed: OpenZeppelin then reports the moved one as deleted.
+  const layout =
+    new Set(renamed).size < renamed.length || renamed.every((to, i) => to === oldNames[i])
+      ? old.layout
+      : {
+          ...old.layout,
+          namespaces: Object.fromEntries(
+            oldNames.map((name, i) => [renamed[i], old.layout.namespaces![name]]),
+          ),
+        };
+
+  const problems = pairs.map((p) => p.problem);
+  return {
+    layout,
+    pairs,
+    result: problems.some((p) => p !== undefined && p !== "unread")
+      ? "fail"
+      : problems.includes("unread")
+        ? "unread"
+        : "pass",
+  };
+}
+
+function problemOf({ old, next }: NamespacePair): NamespacePair["problem"] {
+  if (next?.status === "conflict") return "conflict";
+  if (old?.actual !== undefined && next?.actual !== undefined && !same(old.actual, next.actual)) {
+    return "moved";
+  }
+  if (next?.status === "mismatch") return "mismatch";
+  if ((old !== undefined && old.actual === undefined) || next?.status === "unread") {
+    return "unread";
+  }
+  return undefined;
+}
+
+function same(a: string, b: string): boolean {
+  return BigInt(a) === BigInt(b);
+}
+
+// Visits every node; a visitor returning false skips the node's children.
+function walk(node: unknown, visit: (node: AstNode) => boolean | void): void {
+  if (Array.isArray(node)) {
+    for (const child of node) walk(child, visit);
+  } else if (typeof node === "object" && node !== null) {
+    if (visit(node as AstNode) === false) return;
+    for (const child of Object.values(node)) walk(child, visit);
+  }
+}
+
+interface Context {
+  byId: Map<number, AstNode>;
+  linearized: number[];
+  bases: Set<number>;
+  /** Declarations that Solidity code uses, or assembly assigns. */
+  touched: Set<number>;
+}
+
+/**
+ * The value of a constant, an immutable set where it is declared, or a local
+ * that only assembly reads. A state variable's initial value is not read: it
+ * lives in the implementation's storage, not the proxy's.
+ */
+function resolveDecl(ctx: Context, decl: AstNode | undefined, depth = 0): string | undefined {
+  if (decl === undefined) return undefined;
+  if (decl.stateVariable === true) {
+    if (decl.mutability !== "constant" && decl.mutability !== "immutable") return undefined;
+    return resolveExpr(ctx, decl.value as AstNode | undefined, depth);
+  }
+  if (ctx.touched.has(decl.id as number)) return undefined;
+  return resolveExpr(ctx, initialValue(ctx.byId, decl) as AstNode | undefined, depth);
+}
+
+/**
+ * The value of an expression: a reference to a constant or local, a call to a
+ * no-argument function that returns one (OpenZeppelin's Initializable reads
+ * its slot from `_initializableStorageSlot()`), the ERC-7201 formula, a
+ * number literal or `erc7201("id")`.
+ */
+function resolveExpr(ctx: Context, e: AstNode | undefined, depth: number): string | undefined {
+  if (e === undefined || depth > 8) return undefined;
+  if (e.nodeType === "Identifier") {
+    return resolveDecl(ctx, ctx.byId.get(e.referencedDeclaration as number), depth + 1);
+  }
+  if (e.nodeType === "FunctionCall" && e.kind === "functionCall") {
+    const callee = e.expression as AstNode;
+    const fn = ctx.byId.get(callee.referencedDeclaration as number);
+    if (callee.nodeType !== "Identifier" || fn?.nodeType !== "FunctionDefinition") return undefined;
+    if ((e.arguments as unknown[]).length > 0) return undefined;
+    return resolveExpr(ctx, returned(override(ctx, fn)), depth + 1);
+  }
+  const id = formulaId(e);
+  if (id !== undefined) return calculateERC7201StorageLocation(id);
+  // OpenZeppelin would read any other literal, such as `hex"..."`, as a number.
+  if (e.nodeType === "Literal" && e.kind !== "number") return undefined;
+  try {
+    return resolveBaseSlot(e as never);
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * The implementation an internal call to `fn` reaches: the most derived
+ * override of a virtual function in the bases, or `fn` itself (a free or
+ * library function, which nothing overrides).
+ */
+function override(ctx: Context, fn: AstNode): AstNode {
+  if (fn.virtual !== true || !ctx.bases.has(fn.scope as number)) return fn;
+  for (const contract of ctx.linearized) {
+    for (const node of ctx.byId.values()) {
+      if (
+        node.nodeType === "FunctionDefinition" &&
+        node.scope === contract &&
+        node.name === fn.name &&
+        (node.parameters as { parameters: unknown[] }).parameters.length === 0 &&
+        node.body
+      ) {
+        return node;
+      }
+    }
+  }
+  return fn;
+}
+
+// The expression of a function whose body is a single `return <expression>;`
+// and that has no modifier, which could skip it.
+function returned(fn: AstNode): AstNode | undefined {
+  if ((fn.modifiers as unknown[] | undefined)?.length) return undefined;
+  const statements = (fn.body as { statements?: AstNode[] } | null)?.statements;
+  return statements?.length === 1 && statements[0].nodeType === "Return"
+    ? (statements[0].expression as AstNode)
+    : undefined;
+}
+
+// A local variable's value is on the statement that declares it.
+function initialValue(byId: Map<number, AstNode>, decl: AstNode): unknown {
+  for (const node of byId.values()) {
+    if (node.nodeType !== "VariableDeclarationStatement") continue;
+    const declarations = node.declarations as Array<AstNode | null>;
+    if (declarations.length === 1 && declarations[0]?.id === decl.id) return node.initialValue;
+  }
+  return undefined;
+}
+
+/**
+ * The id in the ERC-7201 formula written out in Solidity,
+ * `keccak256(abi.encode(uint256(keccak256("id")) - 1)) & ~bytes32(uint256(0xff))`,
+ * with an optional `bytes("id")`. Anything else is not recognized.
+ */
+function formulaId(e: AstNode): string | undefined {
+  if (e.nodeType !== "BinaryOperation" || e.operator !== "&") return undefined;
+  const mask = e.rightExpression as AstNode;
+  const masked = arg(
+    arg(
+      mask.nodeType === "UnaryOperation" ? (mask.subExpression as AstNode) : undefined,
+      "bytes32",
+    ),
+    "uint256",
+  );
+  if (masked?.nodeType !== "Literal" || normalize(masked.value) !== toBytes32Hex(0xffn)) {
+    return undefined;
+  }
+  const minus = arg(arg(e.leftExpression as AstNode, "keccak256"), "abi.encode");
+  if (minus?.nodeType !== "BinaryOperation" || minus.operator !== "-") return undefined;
+  const one = minus.rightExpression as AstNode;
+  if (one.nodeType !== "Literal" || one.value !== "1") return undefined;
+  let id = arg(arg(minus.leftExpression as AstNode, "uint256"), "keccak256");
+  if (id?.nodeType === "FunctionCall") id = arg(id, "bytes");
+  return id?.nodeType === "Literal" && id.kind === "string" ? (id.value as string) : undefined;
+}
+
+// The single argument of a call to `name` (a function, `abi.encode`, or a type conversion).
+function arg(call: AstNode | undefined, name: string): AstNode | undefined {
+  if (call?.nodeType !== "FunctionCall") return undefined;
+  const callee = call.expression as AstNode;
+  const calleeName =
+    callee.nodeType === "Identifier"
+      ? callee.name
+      : callee.nodeType === "MemberAccess"
+        ? `${(callee.expression as AstNode).name}.${callee.memberName}`
+        : callee.nodeType === "ElementaryTypeNameExpression"
+          ? (callee.typeName as AstNode).name
+          : undefined;
+  const args = call.arguments as AstNode[];
+  return calleeName === name && args.length === 1 ? args[0] : undefined;
+}
+
+// A number literal as a slot, or undefined when it is not one.
+function normalize(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined;
+  try {
+    return normalizeUint256Literal(value);
+  } catch {
+    return undefined;
+  }
+}

package/src/errors.ts

@@ -22,3 +22,12 @@ export class LayoutIntegrityError extends Error {
     this.name = "LayoutIntegrityError";
   }
 }
+
+/**
+ * A network error's code (ECONNREFUSED, ENOTFOUND), never its message: fetch
+ * quotes the URL in some messages, and URLs carry API keys.
+ */
+export function errorCode(e: unknown): string {
+  const code = (e as { cause?: { code?: unknown } }).cause?.code;
+  return typeof code === "string" ? code : "network error";
+}

package/src/explorer.ts

@@ -8,7 +8,7 @@
  */
 
 import type { SolcInput } from "@openzeppelin/upgrades-core";
-import { LayoutUnavailableError } from "./errors.js";
+import { errorCode, LayoutUnavailableError } from "./errors.js";
 
 export const ETHERSCAN_V2_API_URL = "https://api.etherscan.io/v2/api";
 
@@ -87,7 +87,7 @@ async function requestWithRetry(url: string, fetchImpl: FetchLike): Promise<Sour
       res = await fetchImpl(url);
     } catch (e) {
       // Messages never include the URL, which carries the API key.
-      throw new LayoutUnavailableError(`Explorer unreachable: ${(e as Error).message}`);
+      throw new LayoutUnavailableError(`Explorer unreachable (${errorCode(e)}).`);
     }
 
     if (res.status === 429 && retry) {

package/src/index.ts

@@ -24,7 +24,24 @@ export {
   type VerifiedSource,
 } from "./explorer.js";
 export { getSolc, type SolcOptions, type SolcRunner } from "./solc.js";
-export { layoutFromSource } from "./reconstruct.js";
+export { findBuildInfo, type BuildInfoOptions, type BuildInfoContract } from "./build-info.js";
+export {
+  checkNamespaces,
+  type NamespaceCheck,
+  type NamespacePair,
+  type NamespaceSlot,
+} from "./erc7201.js";
+export {
+  layoutFromSource,
+  analyzeSource,
+  SAFETY_ERROR_KINDS,
+  type SourceAnalysis,
+  type SafetyOptions,
+  type SafetyReport,
+  type SafetyError,
+  type SafetyErrorKind,
+  type ProxyKind,
+} from "./reconstruct.js";
 export {
   compareDeployedBytecode,
   isProvingMatch,

package/src/reconstruct.ts

@@ -8,27 +8,35 @@
  */
 
 import {
+  getErrors,
   getStorageLayout,
+  inferProxyKind,
   isNamespaceSupported,
   makeNamespacedInput,
   solcInputOutputDecoder,
   trySanitizeNatSpec,
+  UpgradeableContractErrorReport,
   validate,
+  type ProxyDeployment,
   type SolcInput,
   type SolcOutput,
   type StorageLayout,
+  type ValidationRunData,
+  type Version,
 } from "@openzeppelin/upgrades-core";
+// Not exported from the package index; the package has no exports map.
+import { errorKinds, type ValidationError } from "@openzeppelin/upgrades-core/dist/validate/run.js";
 import { compareDeployedBytecode, isProvingMatch, type ProvingMatch } from "./bytecode.js";
+import { namespaceSlots, type NamespaceSlot } from "./erc7201.js";
 import { LayoutIntegrityError } from "./errors.js";
 import type { VerifiedSource } from "./explorer.js";
 import type { SolcRunner } from "./solc.js";
 
-export interface ReconstructedLayout {
+export interface ReconstructedLayout extends SourceAnalysis {
   /** Fully qualified name, `source.sol:Contract`. */
   contract: string;
   compiler: string;
   bytecodeMatch: ProvingMatch;
-  layout: StorageLayout;
 }
 
 // validate() reads evm.bytecode for every contract, so codegen is requested
@@ -68,7 +76,7 @@ export async function reconstructLayout(
     contract,
     compiler: source.solcLongVersion,
     bytecodeMatch,
-    layout: await extractLayout(input, output, solc, contract),
+    ...(await analyze(input, output, solc, contract)),
   };
 }
 
@@ -82,17 +90,109 @@ export async function layoutFromSource(
   solc: SolcRunner,
   contract: string,
 ): Promise<StorageLayout> {
+  return (await analyzeSource(input, solc, contract)).layout;
+}
+
+export type ProxyKind = ProxyDeployment["kind"];
+
+/**
+ * OpenZeppelin's safety error kinds, without the deprecated struct-definition
+ * and enum-definition, which the check never reports.
+ */
+export type SafetyErrorKind = Exclude<
+  ValidationError["kind"],
+  "struct-definition" | "enum-definition"
+>;
+
+export const SAFETY_ERROR_KINDS: readonly SafetyErrorKind[] = errorKinds.filter(
+  (k): k is SafetyErrorKind => k !== "struct-definition" && k !== "enum-definition",
+);
+
+export interface SafetyError {
+  /** OpenZeppelin's error kind, such as `constructor`. */
+  kind: SafetyErrorKind;
+  /** Where, as `file.sol:line`. */
+  src: string;
+}
+
+export interface SafetyOptions {
+  /**
+   * The proxy being upgraded; only `uups` requires an `upgradeToAndCall`.
+   * Required: the new contract's own `kind` would let a UUPS implementation
+   * that lost its upgrade function pass.
+   */
+  kind: ProxyKind;
+  /** Error kinds to accept anyway (OZ's `unsafeAllow`). Prefer NatSpec exceptions in the source. */
+  unsafeAllow?: SafetyErrorKind[];
+}
+
+export interface SafetyReport {
+  ok: boolean;
+  errors: SafetyError[];
+  /** OpenZeppelin's description of each error. */
+  explain(): string;
+}
+
+export interface SourceAnalysis {
+  layout: StorageLayout;
+  /** `uups` when the contract has `upgradeTo` or `upgradeToAndCall`, else `transparent`. */
+  kind: Exclude<ProxyKind, "beacon">;
+  /**
+   * The slot each ERC-7201 namespace really uses, read from the code
+   * (`$.slot := LOCATION`); OpenZeppelin trusts the annotation alone.
+   */
+  namespaces: NamespaceSlot[];
+  /**
+   * OpenZeppelin's safety check (constructors, `selfdestruct`,
+   * `delegatecall`, initial values, immutables, initializers), honoring
+   * `@custom:oz-upgrades-unsafe-allow` in the source.
+   */
+  safety(options: SafetyOptions): SafetyReport;
+}
+
+/** `layoutFromSource` plus OpenZeppelin's safety check, from one compile. */
+export async function analyzeSource(
+  input: SolcInput,
+  solc: SolcRunner,
+  contract: string,
+): Promise<SourceAnalysis> {
   const selected = withOutputSelection(input, FULL_SELECTION);
-  const output = await compileOrThrow(solc, selected, "source");
-  return extractLayout(selected, output, solc, contract);
+  return analyze(selected, await compileOrThrow(solc, selected, "source"), solc, contract);
 }
 
-async function extractLayout(
+async function analyze(
   input: SolcInput,
   output: SolcOutput,
   solc: SolcRunner,
   contract: string,
-): Promise<StorageLayout> {
+): Promise<SourceAnalysis> {
+  const { data, version } = await validateContract(input, output, solc, contract);
+  const layout = getStorageLayout(data, version);
+  return {
+    layout,
+    // Typed as any ProxyKind, but only ever uups or transparent.
+    kind: inferProxyKind(data, version) as SourceAnalysis["kind"],
+    namespaces: namespaceSlots(output, contract, Object.keys(layout.namespaces ?? {})),
+    safety({ kind, unsafeAllow = [] }) {
+      // A copy: OpenZeppelin appends to the array it is given.
+      const opts = { kind, unsafeAllow: [...unsafeAllow] };
+      // The deprecated kinds are never reported, so every error has a SafetyErrorKind.
+      const errors = getErrors(data, version, opts) as Array<ValidationError & SafetyError>;
+      return {
+        ok: errors.length === 0,
+        errors,
+        explain: () => new UpgradeableContractErrorReport(errors).explain(),
+      };
+    },
+  };
+}
+
+async function validateContract(
+  input: SolcInput,
+  output: SolcOutput,
+  solc: SolcRunner,
+  contract: string,
+): Promise<{ data: ValidationRunData; version: Version }> {
   const solcVersion = solc.longVersion.split("+")[0];
 
   let namespacedOutput: SolcOutput | undefined;
@@ -116,13 +216,14 @@ async function extractLayout(
   const version = runData[contract]?.version;
   if (version === undefined) {
     throw new LayoutIntegrityError(
-      `${contract} compiled to no bytecode; cannot derive its layout.`,
+      `${contract} compiled to no bytecode (an abstract contract or interface?); ` +
+        `cannot derive its layout.`,
     );
   }
   // OZ looks the contract up by bytecode version and takes the first match, so
   // two contracts with identical code (possible without a source hash) could
-  // swap layouts. Listing the target first makes the lookup land on it.
-  return getStorageLayout({ [contract]: runData[contract], ...runData }, version);
+  // swap layouts or safety errors. Listing the target first makes every lookup land on it.
+  return { data: { [contract]: runData[contract], ...runData }, version };
 }
 
 /**