slotdiff 0.2.0-alpha.1 → 0.3.1

package/src/reconstruct.ts

@@ -10,6 +10,7 @@
 import {
   getErrors,
   getStorageLayout,
+  hashBytecode,
   inferProxyKind,
   isNamespaceSupported,
   makeNamespacedInput,
@@ -22,13 +23,10 @@ import {
   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 { IncompleteBuildError, LayoutIntegrityError, printable } from "./errors.js";
 import type { VerifiedSource } from "./explorer.js";
 import type { SolcRunner } from "./solc.js";
 
@@ -49,6 +47,7 @@ const FULL_SELECTION = {
       "evm.bytecode.linkReferences",
       "evm.deployedBytecode.object",
       "evm.deployedBytecode.immutableReferences",
+      "metadata",
     ],
     "": ["ast"],
   },
@@ -76,37 +75,36 @@ export async function reconstructLayout(
     contract,
     compiler: source.solcLongVersion,
     bytecodeMatch,
-    ...(await analyze(input, output, solc, contract)),
+    ...(await analyzeBuild(input, output, solc)).contract(contract),
   };
 }
 
-/**
- * The layout of `contract` (`source.sol:Name`) in `input`, with no bytecode
- * proof. Only for sources whose provenance is already known, such as a
- * project's own build-info.
- */
-export async function layoutFromSource(
-  input: SolcInput,
-  solc: SolcRunner,
-  contract: string,
-): Promise<StorageLayout> {
-  return (await analyzeSource(input, solc, contract)).layout;
-}
-
 export type ProxyKind = ProxyDeployment["kind"];
 
+type ValidationError = ReturnType<typeof getErrors>[number];
+
 /**
  * OpenZeppelin's safety error kinds, without the deprecated struct-definition
- * and enum-definition, which the check never reports.
+ * and enum-definition, which the check never reports. Listed here, not taken
+ * from OpenZeppelin, so its releases cannot change this API unseen; a test
+ * compares the two.
  */
-export type SafetyErrorKind = Exclude<
-  ValidationError["kind"],
-  "struct-definition" | "enum-definition"
->;
+export const SAFETY_ERROR_KINDS = [
+  "state-variable-assignment",
+  "state-variable-immutable",
+  "external-library-linking",
+  "constructor",
+  "delegatecall",
+  "selfdestruct",
+  "missing-public-upgradeto",
+  "internal-function-storage",
+  "missing-initializer",
+  "missing-initializer-call",
+  "duplicate-initializer-call",
+  "incorrect-initializer-order",
+] as const;
 
-export const SAFETY_ERROR_KINDS: readonly SafetyErrorKind[] = errorKinds.filter(
-  (k): k is SafetyErrorKind => k !== "struct-definition" && k !== "enum-definition",
-);
+export type SafetyErrorKind = (typeof SAFETY_ERROR_KINDS)[number];
 
 export interface SafetyError {
   /** OpenZeppelin's error kind, such as `constructor`. */
@@ -129,8 +127,8 @@ export interface SafetyOptions {
 export interface SafetyReport {
   ok: boolean;
   errors: SafetyError[];
-  /** OpenZeppelin's description of each error. */
-  explain(): string;
+  /** OpenZeppelin's description of each error; `color` (default true) adds terminal colors. */
+  explain(color?: boolean): string;
 }
 
 export interface SourceAnalysis {
@@ -150,30 +148,193 @@ export interface SourceAnalysis {
   safety(options: SafetyOptions): SafetyReport;
 }
 
-/** `layoutFromSource` plus OpenZeppelin's safety check, from one compile. */
+/**
+ * The layout of `contract` (`source.sol:Name`) in `input`, its ERC-7201 slots
+ * and OpenZeppelin's safety check, from one compile. No bytecode proof: only
+ * for sources whose provenance is already known, such as a project's own build info.
+ */
 export async function analyzeSource(
   input: SolcInput,
-  solc: SolcRunner,
+  solc: BuildCompiler,
   contract: string,
 ): Promise<SourceAnalysis> {
   const selected = withOutputSelection(input, FULL_SELECTION);
-  return analyze(selected, await compileOrThrow(solc, selected, "source"), solc, contract);
+  const output = await compileOrThrow(solc, selected, "source");
+  return (await analyzeBuild(selected, output, solc)).contract(contract);
+}
+
+/** The compiler for OpenZeppelin's namespaced pass: a `SolcRunner`, or a build tool's. */
+export type BuildCompiler = Pick<SolcRunner, "longVersion" | "compile">;
+
+export interface BuildAnalysis {
+  /** The analysis of one contract in the build, `source.sol:Name`. */
+  contract(contract: string): SourceAnalysis;
 }
 
-async function analyze(
+/**
+ * `analyzeSource` for a build you already compiled, such as a build tool's,
+ * without compiling it again: one namespaced pass and one validation serve
+ * every contract in it. `output` must hold every source's `ast` and, for each
+ * contract, its `metadata`, `storageLayout` (an interface or library may lack
+ * it) and `evm.bytecode` (`object`, `linkReferences`); without them it throws
+ * `IncompleteBuildError`. The metadata proves `output` was compiled from
+ * `input`'s sources by `compiler`'s version (not with its settings).
+ */
+export async function analyzeBuild(
   input: SolcInput,
   output: SolcOutput,
-  solc: SolcRunner,
+  compiler: BuildCompiler,
+): Promise<BuildAnalysis> {
+  checkBuild(input, output, compiler.longVersion);
+  const runData = await validateBuild(input, output, compiler);
+  return { contract: (contract) => analyzeContract(runData, output, contract) };
+}
+
+interface AstNode {
+  nodeType?: string;
+  name?: unknown;
+  contractKind?: unknown;
+}
+
+interface CompiledContract {
+  metadata?: unknown;
+  storageLayout?: unknown;
+  evm?: { bytecode?: { object?: unknown; linkReferences?: unknown } };
+}
+
+/**
+ * The analysis reads layouts from `output` and edits `input` at the offsets in
+ * `output`'s ASTs, so the two must be one build, complete: an output from other
+ * sources could pass a changed layout, and one without an AST would leave every
+ * namespace unassigned, compared by annotation alone. Anything else is refused.
+ */
+function checkBuild(input: SolcInput, output: SolcOutput, longVersion: string): void {
+  if (output.sources === undefined && Object.hasOwn(output, "_format")) {
+    throw new Error(
+      "The compiler output is wrapped in a build info file; pass its output field " +
+        "(Hardhat 3 writes { _format, output } to <id>.output.json).",
+    );
+  }
+  const paths = Object.keys(input.sources);
+  const outputPaths = Object.keys(output.sources ?? {});
+  if (
+    paths.length !== outputPaths.length ||
+    paths.some((path) => !Object.hasOwn(output.sources, path))
+  ) {
+    throw new Error("The compiler output does not hold the same sources as the input.");
+  }
+  for (const path of paths) {
+    if (typeof (input.sources[path] as { content?: unknown }).content !== "string") {
+      throw new Error(`The compiler input has no content for ${path}.`);
+    }
+    const ast = output.sources[path].ast as { nodes?: AstNode[] } | undefined;
+    if (ast === undefined) {
+      throw new IncompleteBuildError(
+        `The compiler output has no ast for ${path}; it needs every source's ast.`,
+      );
+    }
+    for (const node of ast.nodes ?? []) {
+      if (node.nodeType !== "ContractDefinition") continue;
+      const name = `${path}:${String(node.name)}`;
+      const c = output.contracts?.[path]?.[String(node.name)] as CompiledContract | undefined;
+      if (c === undefined)
+        throw new IncompleteBuildError(`The compiler output has no contract output for ${name}.`);
+      // Neither can hold state, and some tools (Foundry) leave their layout out.
+      const stateless = node.contractKind === "interface" || node.contractKind === "library";
+      if (
+        typeof c.metadata !== "string" ||
+        (c.storageLayout === undefined && !stateless) ||
+        typeof c.evm?.bytecode?.object !== "string" ||
+        typeof c.evm.bytecode.linkReferences !== "object"
+      ) {
+        throw new IncompleteBuildError(
+          `The compiler output for ${name} lacks metadata, storageLayout or evm.bytecode ` +
+            `(object, linkReferences); compile with them in outputSelection.`,
+        );
+      }
+      proveSameBuild(input, path, name, c.metadata, longVersion);
+    }
+  }
+}
+
+function proveSameBuild(
+  input: SolcInput,
+  path: string,
+  name: string,
+  metadata: string,
+  longVersion: string,
+) {
+  let parsed: {
+    compiler?: { version?: unknown };
+    sources?: Record<string, { keccak256?: unknown }>;
+  };
+  try {
+    parsed = JSON.parse(metadata);
+  } catch {
+    throw new LayoutIntegrityError(`The metadata for ${name} is not JSON.`);
+  }
+  const [version, commit] = String(parsed.compiler?.version).split("+");
+  const [wanted, wantedCommit] = longVersion.split("+");
+  if (
+    version !== wanted ||
+    (commit !== undefined && wantedCommit !== undefined && commit !== wantedCommit)
+  ) {
+    throw new LayoutIntegrityError(
+      `${name} was compiled by solc ${String(parsed.compiler?.version)}, not ${longVersion}.`,
+    );
+  }
+  // Its own source at least: metadata that lists none would prove nothing.
+  const sources: Record<string, { keccak256?: unknown }> = { [path]: {}, ...parsed.sources };
+  for (const [source, { keccak256 }] of Object.entries(sources)) {
+    const content = (input.sources[source] as { content?: string } | undefined)?.content;
+    const hash =
+      content === undefined ? undefined : "0x" + hashBytecode(Buffer.from(content).toString("hex"));
+    if (hash !== keccak256) {
+      throw new LayoutIntegrityError(
+        `The compiler output for ${name} was not compiled from this input (${source} differs).`,
+      );
+    }
+  }
+}
+
+function analyzeContract(
+  runData: ValidationRunData,
+  output: SolcOutput,
   contract: string,
-): Promise<SourceAnalysis> {
-  const { data, version } = await validateContract(input, output, solc, contract);
-  const layout = getStorageLayout(data, version);
+): SourceAnalysis {
+  const colon = contract.lastIndexOf(":");
+  if (output.contracts?.[contract.slice(0, colon)]?.[contract.slice(colon + 1)] === undefined) {
+    throw new Error(
+      `${contract} is not in the compiler input. Name it as source.sol:Contract, with the ` +
+        `source path exactly as the input has it (Hardhat 3 starts it with project/).`,
+    );
+  }
+  const version = runData[contract]?.version;
+  if (version === undefined) {
+    throw new LayoutIntegrityError(
+      `${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 or safety errors. Listing the target first makes every lookup land on it.
+  const data: ValidationRunData = { [contract]: runData[contract], ...runData };
+  // A copy: OpenZeppelin's layout points into the run data that every call shares.
+  const layout = structuredClone(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 = [] }) {
+      // OpenZeppelin ignores a kind it does not know, so a typo would accept nothing silently.
+      const unknown = unsafeAllow.find((k) => !SAFETY_ERROR_KINDS.includes(k));
+      if (unknown !== undefined) {
+        throw new Error(
+          `Unknown unsafeAllow error kind "${String(unknown)}". Known: ${SAFETY_ERROR_KINDS.join(", ")}.`,
+        );
+      }
       // 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.
@@ -181,49 +342,37 @@ async function analyze(
       return {
         ok: errors.length === 0,
         errors,
-        explain: () => new UpgradeableContractErrorReport(errors).explain(),
+        explain: (color?: boolean) => new UpgradeableContractErrorReport(errors).explain(color),
       };
     },
   };
 }
 
-async function validateContract(
+async function validateBuild(
   input: SolcInput,
   output: SolcOutput,
-  solc: SolcRunner,
-  contract: string,
-): Promise<{ data: ValidationRunData; version: Version }> {
-  const solcVersion = solc.longVersion.split("+")[0];
+  compiler: BuildCompiler,
+): Promise<ValidationRunData> {
+  const solcVersion = compiler.longVersion.split("+")[0];
 
   let namespacedOutput: SolcOutput | undefined;
   if (isNamespaceSupported(solcVersion)) {
     let namespacedInput = makeNamespacedInput(input, output, solcVersion);
     namespacedInput = await trySanitizeNatSpec(namespacedInput, solcVersion);
     namespacedOutput = await compileOrThrow(
-      solc,
+      compiler,
       withOutputSelection(namespacedInput, LAYOUT_SELECTION),
       "namespaced pass",
     );
   }
 
-  const runData = validate(
+  return validate(
     output,
     solcInputOutputDecoder(input, output),
     solcVersion,
     input,
     namespacedOutput,
   );
-  const version = runData[contract]?.version;
-  if (version === undefined) {
-    throw new LayoutIntegrityError(
-      `${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 or safety errors. Listing the target first makes every lookup land on it.
-  return { data: { [contract]: runData[contract], ...runData }, version };
 }
 
 /**
@@ -301,7 +450,7 @@ function embedsSourceHash(input: SolcInput): boolean {
 }
 
 async function compileOrThrow(
-  solc: SolcRunner,
+  solc: BuildCompiler,
   input: SolcInput,
   what: string,
 ): Promise<SolcOutput> {
@@ -309,7 +458,7 @@ async function compileOrThrow(
   const errors = (output.errors ?? []).filter((e) => e.severity === "error");
   if (errors.length > 0) {
     throw new LayoutIntegrityError(
-      `solc ${solc.longVersion} failed to compile the ${what}: ${errors[0].formattedMessage}`,
+      `solc ${solc.longVersion} failed to compile the ${what}: ${printable(String(errors[0].formattedMessage))}`,
     );
   }
   return output;

package/src/record.ts

@@ -11,6 +11,8 @@
 import type { StorageLayout } from "@openzeppelin/upgrades-core";
 import { isProvingMatch, type ProvingMatch } from "./bytecode.js";
 import { codeSha256, readChainId, readCode, type EthProvider } from "./chain.js";
+import { slotsMisfit, type NamespaceSlot } from "./erc7201.js";
+import type { SourceAnalysis } from "./reconstruct.js";
 import { LayoutIntegrityError, LayoutUnavailableError } from "./errors.js";
 
 /**
@@ -33,6 +35,17 @@ export interface LayoutRecord {
   source: "explorer" | "local-compile";
   recordedAt: string;
   layout: StorageLayout;
+  /**
+   * The proxy kind this code implies: `uups` when it has `upgradeTo` or
+   * `upgradeToAndCall`, else `transparent`. Pass `beacon` to the safety check
+   * instead when a beacon serves it. Absent in older records.
+   */
+  kind?: SourceAnalysis["kind"];
+  /**
+   * The slot each ERC-7201 namespace in `layout` really uses. Without it,
+   * `checkNamespaces` reports the record's namespaces as unread.
+   */
+  namespaces?: NamespaceSlot[];
 }
 
 const ADDRESS = /^0x[0-9a-f]{40}$/;
@@ -75,6 +88,11 @@ export function parseRecord(value: unknown, address?: string): LayoutRecord {
   ) {
     throw malformed("layout");
   }
+  if (r.kind !== undefined && r.kind !== "uups" && r.kind !== "transparent") {
+    throw malformed("kind");
+  }
+  if (slotsMisfit(r.layout, undefined) !== undefined) throw malformed("layout");
+  if (slotsMisfit(r.layout, r.namespaces) !== undefined) throw malformed("namespaces");
   if (typeof r.bytecodeMatch !== "string" || !isProvingMatch(r.bytecodeMatch)) {
     throw new LayoutIntegrityError(
       `The layout record for ${who} rests on a "${String(r.bytecodeMatch)}" match, which does ` +

package/src/report.ts

@@ -36,19 +36,31 @@ export function checkLines(checks: Check[], paint: Paint = plain): string[] {
   ]);
 }
 
+// A pair with nothing in question: no problem, and each side matches its
+// annotation or is not assigned at all, except data the new code stops assigning.
+// A side that is absent is not a problem here; OpenZeppelin reports a deleted namespace.
+function quiet({ old, next, problem }: NamespacePair): boolean {
+  const plain = (s?: NamespaceSlot) =>
+    s === undefined || s.status === "match" || s.status === "unused";
+  const dropped = old?.actual !== undefined && next?.status === "unused";
+  return problem === undefined && plain(old) && plain(next) && !dropped;
+}
+
+/** How many namespaces are compared by annotation alone because no code assigns them. */
+export function unassignedCount(pairs: NamespacePair[]): number {
+  return pairs.filter((p) => quiet(p) && [p.old, p.next].some((s) => s?.status === "unused"))
+    .length;
+}
+
 /**
  * A grid for each namespace whose slot is in question on either side: the
  * annotation, the slot it implies and the slot the code uses, for old and new,
- * with a sentence saying what that means. Namespaces that line up are left out.
+ * with a sentence saying what that means. Namespaces that line up, or that no
+ * code assigns on either side, are left out.
  */
 export function namespaceLines(pairs: NamespacePair[], paint: Paint = plain): string[] {
   const blocks = pairs
-    // A side that is absent is not a problem here; OpenZeppelin reports a deleted namespace.
-    .filter(
-      (p) =>
-        p.problem !== undefined ||
-        [p.old, p.next].some((s) => s !== undefined && s.status !== "match"),
-    )
+    .filter((p) => !quiet(p))
     .map((p) => {
       const fmt = formatter([p.old, p.next]);
       return {
@@ -103,16 +115,23 @@ function row(side: string, s: NamespaceSlot, fmt: (slot: string) => string): Row
     id: s.namespace.slice("erc7201:".length),
     implied: fmt(s.expected),
     inCode:
-      s.status === "conflict" ? "several" : s.actual !== undefined ? fmt(s.actual) : "not read",
+      s.status === "conflict"
+        ? "several"
+        : s.status === "unused"
+          ? "none"
+          : s.actual !== undefined
+            ? fmt(s.actual)
+            : "not read",
     mark: {
       match: "✓",
       mismatch: "✗ annotation does not match code",
       conflict: "✗ code uses more than one slot",
+      unused: "· not assigned in code",
       unread: "? slot in code not read",
     }[s.status],
-    tone: ({ match: "green", mismatch: "red", conflict: "red", unread: "yellow" } as const)[
-      s.status
-    ],
+    tone: (
+      { match: "green", mismatch: "red", conflict: "red", unused: "dim", unread: "yellow" } as const
+    )[s.status],
   };
 }
 
@@ -126,11 +145,23 @@ function meaning({ old, next, problem }: NamespacePair, fmt: (slot: string) => s
         "its data would be left behind. Keep the slot the deployed code uses, under an annotation that matches it."
       );
     case "mismatch":
-      return old === undefined
+      return old === undefined || old.status === "unused"
         ? "The new code keeps this namespace in a different slot than its annotation says. Fix one of the two before deploying."
         : "The storage did not move, but the new annotation does not match its code. Fix it before deploying.";
+    case "dropped":
+      return (
+        `The new code stops assigning this namespace while its data is at ${fmt(old!.actual!)}, ` +
+        `not at ${fmt(old!.expected)} where its annotation points: a later version that follows ` +
+        "the annotation would miss it. Correct the annotation to match the data first."
+      );
     case "unread":
-      return "The slot in code could not be read (computed at run time?), so this namespace could not be checked.";
+      return old !== undefined && old.actual === undefined && old.status !== "unused"
+        ? "The old slot is not known (not read from its code, or missing from an older record), so this namespace could not be checked."
+        : "The slot in the new code could not be read (set from a value slotdiff does not evaluate), so this namespace could not be checked.";
+  }
+  // The only unused case shown without a problem: the new code stops assigning old data.
+  if (next?.status === "unused" && old?.actual !== undefined) {
+    return `The new code no longer assigns this namespace; its data stays at ${fmt(old.actual)}.`;
   }
   return next !== undefined
     ? "Same slot in code on both sides: the storage did not move. Compared as one namespace."

package/src/resolve.ts

@@ -18,7 +18,7 @@ import {
 import { codeSha256, readChainId, readCode, readProxy, type EthProvider } from "./chain.js";
 import { LayoutUnavailableError } from "./errors.js";
 import { canQueryExplorer, fetchVerifiedSource, type ExplorerConfig } from "./explorer.js";
-import { reconstructLayout, type ReconstructedLayout } from "./reconstruct.js";
+import { reconstructLayout, type ProxyKind, type ReconstructedLayout } from "./reconstruct.js";
 import { parseRecord, type LayoutRecord } from "./record.js";
 import { getSolc, type SolcOptions } from "./solc.js";
 
@@ -74,6 +74,8 @@ export async function rebuild(
     source: "explorer",
     recordedAt: new Date().toISOString(),
     layout: rebuilt.layout,
+    kind: rebuilt.kind,
+    namespaces: rebuilt.namespaces,
   };
   return { record, analysis: rebuilt };
 }
@@ -83,6 +85,8 @@ export interface ProxyLayout {
   implementation: string;
   /** Set for a beacon proxy. */
   beacon?: string;
+  /** The proxy's kind, for `checkUpgrade`: `beacon` behind a beacon, else the record's. */
+  kind: ProxyKind;
   record: LayoutRecord;
 }
 
@@ -99,7 +103,8 @@ export async function resolveProxyLayout(
     );
   }
   const record = await resolveLayout(provider, state.implementation, options);
-  return { ...state, record };
+  // A rebuilt record always has its kind.
+  return { ...state, kind: state.beacon !== undefined ? "beacon" : record.kind!, record };
 }
 
 export interface LocalBuild {
@@ -109,6 +114,9 @@ export interface LocalBuild {
   layout: StorageLayout;
   deployedBytecode: string;
   immutableReferences?: ImmutableReferences;
+  /** From `analyzeSource`, so the record carries them (see `LayoutRecord`). */
+  kind?: LayoutRecord["kind"];
+  namespaces?: LayoutRecord["namespaces"];
 }
 
 export interface LocalBuildResult {
@@ -147,6 +155,8 @@ export async function proveLocalBuild(
     source: "local-compile",
     recordedAt: new Date().toISOString(),
     layout: build.layout,
+    ...(build.kind !== undefined ? { kind: build.kind } : {}),
+    ...(build.namespaces !== undefined ? { namespaces: build.namespaces } : {}),
   };
   // A record this returns must load back through parseRecord, so check it now.
   return { bytecodeMatch, record: parseRecord(JSON.parse(JSON.stringify(record)), lower) };

package/src/solc.ts

@@ -14,9 +14,9 @@
 
 import { spawn } from "node:child_process";
 import { createHash, randomUUID } from "node:crypto";
-import { access, chmod, mkdir, readdir, rename, writeFile } from "node:fs/promises";
+import { access, chmod, mkdir, mkdtemp, readdir, rename, rm, writeFile } from "node:fs/promises";
 import { constants } from "node:fs";
-import { homedir } from "node:os";
+import { homedir, tmpdir } from "node:os";
 import { join } from "node:path";
 import type { SolcInput, SolcOutput } from "@openzeppelin/upgrades-core";
 import { LayoutIntegrityError, LayoutUnavailableError } from "./errors.js";
@@ -169,6 +169,10 @@ async function findBuild(
   if (build === undefined) {
     throw new LayoutUnavailableError(`solc ${version} has no native ${platform} build.`);
   }
+  // Both become paths: a release is matched by prefix, so its long version comes from the list.
+  if (!SOLC_VERSION.test(build.longVersion) || !/^[\w.+-]+$/.test(build.path)) {
+    throw new LayoutUnavailableError(`The solc build list has a malformed entry for ${version}.`);
+  }
   // Old Windows releases (up to 0.7.1) ship as zip archives, not executables.
   if (build.path.endsWith(".zip")) {
     throw new LayoutUnavailableError(
@@ -206,9 +210,21 @@ async function download(
   await rename(tmp, dest);
 }
 
-function runSolc(path: string, input: SolcInput): Promise<SolcOutput> {
+// solc reads imports it is not given from its working directory, so it runs in
+// an empty one: verified source could otherwise import, and quote in an error,
+// any file under the caller's (an .env, say).
+async function runSolc(path: string, input: SolcInput): Promise<SolcOutput> {
+  const cwd = await mkdtemp(join(tmpdir(), "slotdiff-solc-"));
+  try {
+    return await runSolcIn(cwd, path, input);
+  } finally {
+    await rm(cwd, { recursive: true, force: true });
+  }
+}
+
+function runSolcIn(cwd: string, path: string, input: SolcInput): Promise<SolcOutput> {
   return new Promise((resolve, reject) => {
-    const child = spawn(path, ["--standard-json"], { stdio: ["pipe", "pipe", "pipe"] });
+    const child = spawn(path, ["--standard-json"], { cwd, stdio: ["pipe", "pipe", "pipe"] });
     const out: Buffer[] = [];
     const err: Buffer[] = [];
     child.stdout.on("data", (d: Buffer) => out.push(d));