slotdiff 0.0.0-stage → 0.2.0-alpha.1

package/src/reconstruct.ts

@@ -0,0 +1,329 @@
+/**
+ * Rebuilds the storage layout of deployed code from its verified source, and
+ * proves the source is the deployed code before trusting the layout.
+ *
+ * The layout comes out of the same oz-core pipeline the compile hook runs for
+ * the local build (full compile, namespaced second pass, `validate()`,
+ * `getStorageLayout`), so both sides of a comparison are extracted identically.
+ */
+
+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 extends SourceAnalysis {
+  /** Fully qualified name, `source.sol:Contract`. */
+  contract: string;
+  compiler: string;
+  bytecodeMatch: ProvingMatch;
+}
+
+// validate() reads evm.bytecode for every contract, so codegen is requested
+// for all of them. A verified input holds only the target's dependency graph.
+const FULL_SELECTION = {
+  "*": {
+    "*": [
+      "storageLayout",
+      "evm.bytecode.object",
+      "evm.bytecode.linkReferences",
+      "evm.deployedBytecode.object",
+      "evm.deployedBytecode.immutableReferences",
+    ],
+    "": ["ast"],
+  },
+};
+
+// The namespaced pass only needs layouts and ASTs; skipping codegen keeps it cheap.
+const LAYOUT_SELECTION = { "*": { "*": ["storageLayout"], "": ["ast"] } };
+
+export async function reconstructLayout(
+  source: VerifiedSource,
+  solc: SolcRunner,
+  onchainCode: string,
+): Promise<ReconstructedLayout> {
+  const input = withOutputSelection(source.input, FULL_SELECTION);
+  const output = await compileOrThrow(solc, input, "verified source");
+
+  const { contract, bytecodeMatch } = proveDeployedCode(
+    output,
+    source.contractName,
+    onchainCode,
+    embedsSourceHash(source.input),
+  );
+
+  return {
+    contract,
+    compiler: source.solcLongVersion,
+    bytecodeMatch,
+    ...(await analyze(input, output, solc, 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"];
+
+/**
+ * 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);
+  return analyze(selected, await compileOrThrow(solc, selected, "source"), solc, contract);
+}
+
+async function analyze(
+  input: SolcInput,
+  output: SolcOutput,
+  solc: SolcRunner,
+  contract: string,
+): 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;
+  if (isNamespaceSupported(solcVersion)) {
+    let namespacedInput = makeNamespacedInput(input, output, solcVersion);
+    namespacedInput = await trySanitizeNatSpec(namespacedInput, solcVersion);
+    namespacedOutput = await compileOrThrow(
+      solc,
+      withOutputSelection(namespacedInput, LAYOUT_SELECTION),
+      "namespaced pass",
+    );
+  }
+
+  const runData = 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 };
+}
+
+/**
+ * Finds the compiled contract that matches the deployed code. The verified
+ * name narrows the search, but two files may define a contract with the same
+ * name, so the bytecode decides, and the strongest match wins. Only a proving
+ * match is accepted: `metadata-only` can hide a different storage layout.
+ */
+function proveDeployedCode(
+  output: SolcOutput,
+  contractName: string,
+  onchainCode: string,
+  hashed: boolean,
+): { contract: string; bytecodeMatch: ProvingMatch } {
+  let candidates = 0;
+  let best: { contract: string; bytecodeMatch: ProvingMatch } | undefined;
+  let weak: "metadata-only" | "code-only" | undefined;
+  for (const [sourcePath, contracts] of Object.entries(output.contracts ?? {})) {
+    const compiled = contracts[contractName] as
+      | {
+          evm?: {
+            deployedBytecode?: {
+              object?: string;
+              immutableReferences?: Record<string, Array<{ start: number; length: number }>>;
+            };
+          };
+        }
+      | undefined;
+    const deployed = compiled?.evm?.deployedBytecode;
+    if (deployed?.object === undefined) continue;
+    candidates++;
+    const compared = compareDeployedBytecode(
+      onchainCode,
+      deployed.object,
+      deployed.immutableReferences,
+    );
+    const match = !hashed && isProvingMatch(compared) ? "code-only" : compared;
+    if (match === "metadata-only" || match === "code-only") weak ??= match;
+    if (!isProvingMatch(match)) continue;
+    if (best === undefined || (match === "exact" && best.bytecodeMatch !== "exact")) {
+      best = { contract: `${sourcePath}:${contractName}`, bytecodeMatch: match };
+    }
+  }
+  if (best !== undefined) return best;
+
+  if (candidates === 0) {
+    throw new LayoutIntegrityError(`Verified source has no contract named "${contractName}".`);
+  }
+  // Neither weak match proves the layout: unread variables and gap sizes never reach the bytecode.
+  throw new LayoutIntegrityError(
+    weak === "metadata-only"
+      ? `Verified source for "${contractName}" matches the deployed code only after stripping ` +
+          `metadata, so the compiler input differed. That does not prove the storage layout ` +
+          `(unread variables and gap sizes never reach the bytecode). Refusing to trust it.`
+      : weak === "code-only"
+        ? `Verified source for "${contractName}" compiles to the deployed code, but the build ` +
+          `embeds no source hash (bytecodeHash "none" or appendCBOR false), so the code does ` +
+          `not prove the source or its storage layout. Refusing to trust it.`
+        : `Verified source for "${contractName}" does not compile to the deployed code, ` +
+          `even with immutables masked. Refusing to trust its layout.`,
+  );
+}
+
+/**
+ * Whether the verified settings embed a metadata hash. The bytecode check alone
+ * can be fooled: without CBOR (`appendCBOR: false`) the code can end in a data
+ * literal shaped like solc's metadata. The settings cannot lie, since the code
+ * only matches when compiled with the settings that were really used.
+ */
+function embedsSourceHash(input: SolcInput): boolean {
+  const metadata = (
+    input.settings as { metadata?: { appendCBOR?: boolean; bytecodeHash?: string } }
+  ).metadata;
+  return metadata?.appendCBOR !== false && metadata?.bytecodeHash !== "none";
+}
+
+async function compileOrThrow(
+  solc: SolcRunner,
+  input: SolcInput,
+  what: string,
+): Promise<SolcOutput> {
+  const output = await solc.compile(input);
+  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}`,
+    );
+  }
+  return output;
+}
+
+// Only solc's standard-json keys: build tools add their own (Foundry's build-info
+// input carries `version`, `allowPaths`, `basePath`, `includePaths`), and solc
+// rejects any key it does not know.
+function withOutputSelection(input: SolcInput, outputSelection: unknown): SolcInput {
+  // upgrades-core's SolcInput type omits `language`, which standard json requires.
+  const { language } = input as SolcInput & { language?: string };
+  return {
+    language,
+    sources: input.sources,
+    settings: { ...input.settings, outputSelection },
+  } as SolcInput;
+}

package/src/record.ts

@@ -0,0 +1,127 @@
+/**
+ * Layout records: the proven storage layout of the code at one address on one
+ * chain. slotdiff never writes them anywhere. A record is plain JSON, so the
+ * caller saves it however it likes and loads it back through `parseRecord`
+ * (offline) or `verifyRecord` (against the chain):
+ *
+ *   await writeFile(path, JSON.stringify(record, null, 2));
+ *   const record = await verifyRecord(provider, address, JSON.parse(await readFile(path, "utf8")));
+ */
+
+import type { StorageLayout } from "@openzeppelin/upgrades-core";
+import { isProvingMatch, type ProvingMatch } from "./bytecode.js";
+import { codeSha256, readChainId, readCode, type EthProvider } from "./chain.js";
+import { LayoutIntegrityError, LayoutUnavailableError } from "./errors.js";
+
+/**
+ * Deployed code never changes, so a record cannot go stale for its chain and
+ * address. `codeSha256` binds it to the exact runtime code it was proven
+ * against; `verifyRecord` refuses it for any other code or chain.
+ */
+export interface LayoutRecord {
+  format: 1;
+  /** Lowercase. */
+  address: string;
+  chainId: number;
+  codeSha256: string;
+  /** Fully qualified name, `source.sol:Contract`. */
+  contract: string;
+  /** solc long version, when known. */
+  compiler?: string;
+  bytecodeMatch: ProvingMatch;
+  /** `explorer`: rebuilt from verified source. `local-compile`: proven against a local build. */
+  source: "explorer" | "local-compile";
+  recordedAt: string;
+  layout: StorageLayout;
+}
+
+const ADDRESS = /^0x[0-9a-f]{40}$/;
+const SHA256 = /^[0-9a-f]{64}$/;
+
+/**
+ * Checks a loaded record without touching the chain: its format, its shape,
+ * and that it rests on a match that proves a layout. Pass `address` to also
+ * require that it describes that address. Use `verifyRecord` whenever an RPC
+ * is available; this alone cannot tell that the code at the address changed
+ * or that the record came from another chain.
+ */
+export function parseRecord(value: unknown, address?: string): LayoutRecord {
+  if (typeof value !== "object" || value === null) {
+    throw new LayoutIntegrityError("A layout record must be a JSON object.");
+  }
+  const r = value as Partial<LayoutRecord>;
+  if (r.format !== 1) {
+    throw new Error(`Unsupported layout record format ${String(r.format)}; upgrade slotdiff.`);
+  }
+  const who = typeof r.address === "string" ? r.address : "an unknown address";
+  const malformed = (field: string) =>
+    new LayoutIntegrityError(`The layout record for ${who} has a missing or malformed ${field}.`);
+
+  if (typeof r.address !== "string" || !ADDRESS.test(r.address)) throw malformed("address");
+  if (!Number.isSafeInteger(r.chainId) || (r.chainId as number) <= 0) throw malformed("chainId");
+  if (typeof r.codeSha256 !== "string" || !SHA256.test(r.codeSha256)) {
+    throw malformed("codeSha256");
+  }
+  if (typeof r.contract !== "string" || !r.contract.includes(":")) throw malformed("contract");
+  if (r.compiler !== undefined && typeof r.compiler !== "string") throw malformed("compiler");
+  if (r.source !== "explorer" && r.source !== "local-compile") throw malformed("source");
+  if (typeof r.recordedAt !== "string") throw malformed("recordedAt");
+  if (
+    typeof r.layout !== "object" ||
+    r.layout === null ||
+    !Array.isArray(r.layout.storage) ||
+    typeof r.layout.types !== "object" ||
+    r.layout.types === null
+  ) {
+    throw malformed("layout");
+  }
+  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 ` +
+        `not prove a storage layout.`,
+    );
+  }
+  if (address !== undefined && r.address !== address.toLowerCase()) {
+    throw new LayoutIntegrityError(
+      `The layout record for ${r.address} was loaded for ${address.toLowerCase()}.`,
+    );
+  }
+  return r as LayoutRecord;
+}
+
+/**
+ * `parseRecord`, then checks the record against the chain: it must have been
+ * made on this chain, and the code at `address` must be the code it was
+ * proven against. Returns the record, ready to diff.
+ */
+export async function verifyRecord(
+  provider: EthProvider,
+  address: string,
+  value: unknown,
+): Promise<LayoutRecord> {
+  const record = parseRecord(value, address);
+  const chainId = await readChainId(provider);
+  if (record.chainId !== chainId) {
+    throw new LayoutIntegrityError(
+      `The layout record for ${record.address} was made on chain ${record.chainId}, not on ` +
+        `chain ${chainId}.`,
+    );
+  }
+  let code: string;
+  try {
+    code = await readCode(provider, record.address);
+  } catch (e) {
+    // The code the record was proven against is gone; never a reason to fall back.
+    if (!(e instanceof LayoutUnavailableError)) throw e;
+    throw new LayoutIntegrityError(
+      `The layout record for ${record.address} describes code that is no longer at that address.`,
+    );
+  }
+  if (codeSha256(code) !== record.codeSha256) {
+    throw new LayoutIntegrityError(
+      `The layout record for ${record.address} was proven against different code than this ` +
+        `chain has at that address.`,
+    );
+  }
+  return record;
+}

package/src/report.ts

@@ -0,0 +1,155 @@
+/**
+ * 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 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.
+ */
+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"),
+    )
+    .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.actual !== undefined ? fmt(s.actual) : "not read",
+    mark: {
+      match: "✓",
+      mismatch: "✗ annotation does not match code",
+      conflict: "✗ code uses more than one slot",
+      unread: "? slot in code not read",
+    }[s.status],
+    tone: ({ match: "green", mismatch: "red", conflict: "red", 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
+        ? "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 "unread":
+      return "The slot in code could not be read (computed at run time?), so this namespace could not be checked.";
+  }
+  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)}`;
+}