slotdiff 0.1.0-alpha.1 → 0.3.0

package/src/report.ts

@@ -0,0 +1,186 @@
+/**
+ * The CLI's report: the ERC-7201 namespace grid and the check list. Pure
+ * functions from results to lines, so the layout is tested as text. Colors
+ * come from `paint`, applied after alignment so they never shift a column.
+ */
+
+import type { NamespacePair, NamespaceSlot } from "./erc7201.js";
+
+/** Node's `util.styleText`, or `plain` when colors are off. */
+export type Paint = (
+  format: Parameters<typeof import("node:util").styleText>[0],
+  text: string,
+) => string;
+
+export const plain: Paint = (_, text) => text;
+
+export type CheckStatus = "pass" | "fail" | "skip";
+
+export interface Check {
+  name: string;
+  status: CheckStatus;
+  summary: string;
+  /** Multi-line explanation shown under the check, such as OpenZeppelin's report. */
+  details?: string;
+}
+
+const MARK: Record<CheckStatus, string> = { pass: "✓", fail: "✗", skip: "-" };
+const TONE = { pass: "green", fail: "red", skip: "yellow" } as const;
+
+/** One line per check, names aligned, details indented under their check. */
+export function checkLines(checks: Check[], paint: Paint = plain): string[] {
+  const width = Math.max(...checks.map((c) => c.name.length));
+  return checks.flatMap((c) => [
+    `${paint(TONE[c.status], MARK[c.status])} ${paint("bold", c.name.padEnd(width))}   ${c.summary}`,
+    ...(c.details?.split("\n").map((line) => `    ${line}`) ?? []),
+  ]);
+}
+
+// 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, or that no
+ * code assigns on either side, are left out.
+ */
+export function namespaceLines(pairs: NamespacePair[], paint: Paint = plain): string[] {
+  const blocks = pairs
+    .filter((p) => !quiet(p))
+    .map((p) => {
+      const fmt = formatter([p.old, p.next]);
+      return {
+        rows: [
+          ...(p.old !== undefined ? [row("old", p.old, fmt)] : []),
+          ...(p.next !== undefined ? [row("new", p.next, fmt)] : []),
+        ],
+        meaning: meaning(p, fmt),
+        tone: (p.problem === undefined
+          ? "dim"
+          : p.problem === "unread"
+            ? "yellow"
+            : "red") as Row["tone"],
+      };
+    });
+  if (blocks.length === 0) return [];
+
+  const header = {
+    side: "",
+    id: "annotation",
+    implied: "slot from annotation",
+    inCode: "slot in code",
+    mark: "",
+    tone: "dim",
+  } as Row;
+  const all = [header, ...blocks.flatMap((b) => b.rows)];
+  const width = (key: "id" | "implied" | "inCode") => Math.max(...all.map((r) => r[key].length));
+  const cells = (r: Row) =>
+    `  ${r.side.padEnd(5)}${r.id.padEnd(width("id"))}   ${r.implied.padEnd(width("implied"))}   ` +
+    r.inCode.padEnd(width("inCode"));
+  const line = (r: Row) => `${cells(r)}   ${paint(r.tone, r.mark)}`;
+
+  return [
+    paint("bold", "ERC-7201 namespaces"),
+    paint("dim", cells(header).trimEnd()),
+    ...blocks.flatMap((b) => [...b.rows.map(line), `       ${paint(b.tone, b.meaning)}`]),
+  ];
+}
+
+interface Row {
+  side: string;
+  id: string;
+  implied: string;
+  inCode: string;
+  mark: string;
+  tone: "green" | "red" | "yellow" | "dim";
+}
+
+function row(side: string, s: NamespaceSlot, fmt: (slot: string) => string): Row {
+  return {
+    side,
+    id: s.namespace.slice("erc7201:".length),
+    implied: fmt(s.expected),
+    inCode:
+      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", unused: "dim", unread: "yellow" } as const
+    )[s.status],
+  };
+}
+
+function meaning({ old, next, problem }: NamespacePair, fmt: (slot: string) => string): string {
+  switch (problem) {
+    case "conflict":
+      return "The new code assigns more than one slot to this namespace; it must use one.";
+    case "moved":
+      return (
+        `The new code moves this namespace from ${fmt(old!.actual!)} to ${fmt(next!.actual!)}: ` +
+        "its data would be left behind. Keep the slot the deployed code uses, under an annotation that matches it."
+      );
+    case "mismatch":
+      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 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."
+    : "The deployed annotation does not match its code, and no namespace in the new code uses its slot.";
+}
+
+/**
+ * Short slots for a block, unless two different slots in it would then look
+ * the same: a hand-written constant can share both ends with another.
+ */
+function formatter(sides: Array<NamespaceSlot | undefined>): (slot: string) => string {
+  const slots = new Set(
+    sides.flatMap((s) => (s === undefined ? [] : [s.expected, s.actual ?? s.expected])),
+  );
+  const shorts = new Set([...slots].map(short));
+  return shorts.size === slots.size ? short : (slot) => slot;
+}
+
+/** `0x5ea2…5c00`: enough to tell slots apart; slotdiff does the comparing. */
+function short(slot: string): string {
+  return `${slot.slice(0, 6)}…${slot.slice(-4)}`;
+}

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 } 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";
 
@@ -37,6 +37,20 @@ export async function resolveLayout(
   address: string,
   options: ResolveOptions,
 ): Promise<LayoutRecord> {
+  return (await rebuild(provider, address, options)).record;
+}
+
+/**
+ * `resolveLayout` plus the analysis of the verified source: the proxy kind,
+ * inferred from the code as OpenZeppelin recommends (not from the admin slot,
+ * which a UUPS proxy can have set), the ERC-7201 slots and the safety check.
+ * Internal, for the CLI.
+ */
+export async function rebuild(
+  provider: EthProvider,
+  address: string,
+  options: ResolveOptions,
+): Promise<{ record: LayoutRecord; analysis: ReconstructedLayout }> {
   const lower = address.toLowerCase();
   if (!canQueryExplorer(options.explorer)) {
     throw new LayoutUnavailableError(
@@ -49,7 +63,7 @@ export async function resolveLayout(
   const solc = await getSolc(source.solcLongVersion, options.solc);
   const rebuilt = await reconstructLayout(source, solc, code);
 
-  return {
+  const record: LayoutRecord = {
     format: 1,
     address: lower,
     chainId,
@@ -60,7 +74,10 @@ export async function resolveLayout(
     source: "explorer",
     recordedAt: new Date().toISOString(),
     layout: rebuilt.layout,
+    kind: rebuilt.kind,
+    namespaces: rebuilt.namespaces,
   };
+  return { record, analysis: rebuilt };
 }
 
 export interface ProxyLayout {
@@ -68,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;
 }
 
@@ -84,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 {
@@ -94,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 {
@@ -132,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));

package/src/upgrade.ts

@@ -0,0 +1,91 @@
+/**
+ * The whole upgrade check in one call, as the CLI runs it: the storage layout,
+ * the ERC-7201 slots and OpenZeppelin's safety rules, with one verdict.
+ */
+
+import type { StorageLayout } from "@openzeppelin/upgrades-core";
+import { diffLayouts, type DiffOptions, type LayoutReport } from "./diff.js";
+import { checkNamespaces, type NamespaceCheck, type NamespaceSlot } from "./erc7201.js";
+import type { ProxyKind, SafetyErrorKind, SafetyReport, SourceAnalysis } from "./reconstruct.js";
+
+export interface UpgradeOptions extends DiffOptions {
+  /** Error kinds to accept anyway (OZ's `unsafeAllow`). Prefer NatSpec exceptions in the source. */
+  unsafeAllow?: SafetyErrorKind[];
+  /** Skip the safety rules; the layout and slots are still checked. */
+  skipSafety?: boolean;
+}
+
+/** A layout with the slot of each namespace, such as a `LayoutRecord` or a `SourceAnalysis`. */
+export interface UpgradeSide {
+  layout: StorageLayout;
+  /** Without them, the namespaces are unchecked. */
+  namespaces?: NamespaceSlot[];
+}
+
+export interface UpgradeCheck {
+  /** OpenZeppelin's comparison, with each namespace paired by the slot in code. */
+  layout: LayoutReport;
+  namespaces: NamespaceCheck;
+  /** Absent with `skipSafety`: then `pass` covers the layout and slots only. */
+  safety?: SafetyReport;
+  /**
+   * `fail`: a check failed. `unchecked`: none failed, but an ERC-7201 slot
+   * could not be read (`unread` in `namespaces`). `pass`: every check that ran passed.
+   */
+  result: "pass" | "fail" | "unchecked";
+}
+
+const PROXY_KINDS: readonly string[] = ["uups", "transparent", "beacon"];
+
+/**
+ * Whether `next` can replace `old` behind a proxy. `old.kind` is the kind of
+ * the proxy being upgraded (`beacon` when a beacon serves it): taking it from
+ * `next` would let a UUPS implementation that lost its upgrade function pass.
+ * `old` may be a `SourceAnalysis`, or a `LayoutRecord` with its `kind` given.
+ * With `skipSafety`, `next` may be a record too, and `old.kind` is not needed.
+ */
+export function checkUpgrade(
+  old: UpgradeSide & { kind: ProxyKind },
+  next: SourceAnalysis,
+  options?: UpgradeOptions,
+): UpgradeCheck;
+export function checkUpgrade(
+  old: UpgradeSide & { kind?: ProxyKind },
+  next: UpgradeSide,
+  options: UpgradeOptions & { skipSafety: true },
+): UpgradeCheck;
+export function checkUpgrade(
+  old: UpgradeSide & { kind?: ProxyKind },
+  next: UpgradeSide & { safety?: SourceAnalysis["safety"] },
+  options: UpgradeOptions = {},
+): UpgradeCheck {
+  if (!options.skipSafety) {
+    // Checked here for JavaScript callers: OpenZeppelin treats an unknown kind as uups.
+    if (!PROXY_KINDS.includes(old.kind as string)) {
+      throw new Error(
+        `checkUpgrade needs the kind of the proxy being upgraded (${PROXY_KINDS.join(", ")}), ` +
+          `got ${JSON.stringify(old.kind)}.`,
+      );
+    }
+    if (typeof next.safety !== "function") {
+      throw new Error("checkUpgrade needs an analysis of next (analyzeSource), or skipSafety.");
+    }
+  }
+  // OpenZeppelin matches namespaces by annotation; pairing them by slot first
+  // makes it compare the structs of the same storage.
+  const namespaces = checkNamespaces(old, next);
+  const layout = diffLayouts(namespaces.layout, next.layout, {
+    unsafeAllowRenames: options.unsafeAllowRenames,
+  });
+  const safety = options.skipSafety
+    ? undefined
+    : next.safety!({ kind: old.kind!, unsafeAllow: options.unsafeAllow });
+  // A failure outranks an unread slot, so a known problem is never reported as merely unchecked.
+  const result =
+    !layout.ok || namespaces.result === "fail" || safety?.ok === false
+      ? "fail"
+      : namespaces.result === "unchecked"
+        ? "unchecked"
+        : "pass";
+  return { layout, namespaces, ...(safety !== undefined ? { safety } : {}), result };
+}