slotdiff 0.0.0-stage → 0.2.0-alpha.1

package/src/build-info.ts

@@ -0,0 +1,405 @@
+/**
+ * Reads a project's own build info: Foundry, Hardhat 2 and Hardhat 3.
+ *
+ * The build is chosen by content, never by modification time or file count.
+ * Foundry keeps every build-info file it ever wrote, so after a few edits
+ * several hold the target, most of them describing older sources. Only a build
+ * whose sources still match the files on disk is used.
+ */
+
+import type { SolcInput } from "@openzeppelin/upgrades-core";
+import { readFile, readdir, stat } from "node:fs/promises";
+import { isAbsolute, join, relative, resolve } from "node:path";
+import type { ImmutableReferences } from "./bytecode.js";
+
+export interface BuildInfoOptions {
+  /**
+   * One build-info file to use as is, relative to the project root. Its
+   * sources are not compared with the files on disk, so it may come from
+   * another checkout, such as a CI artifact.
+   */
+  file?: string;
+}
+
+export interface BuildInfoContract {
+  /** The build-info file it was read from. */
+  file: string;
+  /**
+   * Fully qualified name as solc saw it, `source.sol:Name`. Hardhat 3 prefixes
+   * project sources with `project/`.
+   */
+  contract: string;
+  /** As recorded: a long version, or a release version for Foundry. Both work with `getSolc`. */
+  solcVersion: string;
+  /**
+   * The compiler input, reduced to the target and what it imports, so that a
+   * layout compiles only those sources rather than the whole project.
+   */
+  input: SolcInput;
+  /** Absent when the build info holds no compiler output. */
+  deployedBytecode?: string;
+  immutableReferences?: ImmutableReferences;
+}
+
+// Foundry, then Hardhat.
+const DIRS = ["out/build-info", "artifacts/build-info"];
+
+const NO_INPUT_HINT =
+  " Foundry writes the compiler input only with `build_info = true` in foundry.toml or " +
+  "`forge build --build-info`.";
+
+interface RawBuildInfo {
+  _format?: string;
+  solcLongVersion?: string;
+  input?: SolcInput & { sources?: Record<string, { content?: string }> };
+  output?: {
+    contracts?: Record<string, Record<string, CompiledContract>>;
+    sources?: Record<
+      string,
+      { ast?: { nodes?: Array<{ nodeType?: string; absolutePath?: string }> } }
+    >;
+  };
+  userSourceNameMap?: Record<string, string>;
+  source_id_to_path?: unknown;
+}
+
+interface CompiledContract {
+  evm?: { deployedBytecode?: { object?: string; immutableReferences?: ImmutableReferences } };
+}
+
+interface Candidate {
+  file: string;
+  info: RawBuildInfo;
+  contract: string;
+}
+
+/**
+ * Finds `contract` in the build info under `root` and returns what a layout
+ * or a bytecode proof needs. `contract` is `path/File.sol:Name`, with the path
+ * as written in the project (Hardhat 3's `project/` prefix is optional), or a
+ * bare `Name` when only one contract has it.
+ */
+export async function findBuildInfo(
+  root: string,
+  contract: string,
+  options: BuildInfoOptions = {},
+): Promise<BuildInfoContract> {
+  const target = parseTarget(contract);
+  if (target.path !== undefined && isAbsolute(target.path)) {
+    target.path = relative(root, target.path);
+  }
+
+  if (options.file !== undefined) {
+    const file = resolve(root, options.file);
+    let text: string;
+    try {
+      text = await readFile(file, "utf8");
+    } catch (e) {
+      throw new Error(`Cannot read ${options.file} (${(e as NodeJS.ErrnoException).code}).`, {
+        cause: e,
+      });
+    }
+    const info = await readBuildInfo(file, text);
+    if (info === undefined)
+      throw new Error(`${options.file} holds no compiler input.${NO_INPUT_HINT}`);
+    const matches = findContract(info, target);
+    if (matches.length === 0) throw new Error(`${options.file} has no contract ${contract}.`);
+    if (matches.length > 1) throw ambiguousName(contract, matches);
+    return toResult({ file, info, contract: matches[0] });
+  }
+
+  const files = await listBuildInfoFiles(root);
+  if (files.length === 0) {
+    const isDir = await stat(root).then(
+      (st) => st.isDirectory(),
+      () => false,
+    );
+    if (!isDir) throw new Error(`The project root ${root} is not a directory.`);
+    throw new Error(
+      `No build info found in ${DIRS.join(" or ")} under ${root}. Run from the project root ` +
+        `(or pass its path as the root), after a build.${NO_INPUT_HINT}`,
+    );
+  }
+
+  const holding: Candidate[] = [];
+  let withoutInput = false;
+  for (const file of files) {
+    // Cheap text check first: build-info files can be large, and most do not hold the target.
+    const text = await readFile(file, "utf8");
+    if (target.path !== undefined && !text.includes(`${target.path}"`)) continue;
+    const info = await readBuildInfo(file, text);
+    if (info === undefined) {
+      withoutInput = true;
+      continue;
+    }
+    for (const name of findContract(info, target)) holding.push({ file, info, contract: name });
+  }
+  if (holding.length === 0) {
+    throw new Error(
+      `No build info holds ${contract}. ` +
+        (withoutInput
+          ? `Some hold no compiler input.${NO_INPUT_HINT}`
+          : "Check the name (it is case-sensitive) and give the source path as the compiler " +
+            "saw it (for a remapped import, the path under lib/), or just the contract name. " +
+            "Or build first."),
+    );
+  }
+
+  // A build is fresh when the target's file exists and nothing it imports has changed.
+  const fresh: Candidate[] = [];
+  const stale: Array<{ candidate: Candidate; target: string | undefined }> = [];
+  for (const candidate of holding) {
+    const disk = await checkDisk(root, candidate);
+    if (disk === "gone") continue;
+    if (disk.fresh) fresh.push(candidate);
+    else stale.push({ candidate, target: disk.target });
+  }
+
+  // A bare name is ambiguous across every build that holds it, not only the
+  // fresh ones: an incremental build holds just the files it recompiled, so the
+  // freshest build can miss a second definition. A stale definition counts only
+  // while its file still declares the name (it may have been renamed since).
+  const name = target.name.replace(/\$/g, "\\$");
+  const declares = new RegExp(`\\b(?:contract|interface|library)\\s+${name}(?![\\w$])`);
+  const present = [
+    ...fresh,
+    ...stale
+      .filter(({ target }) => target === undefined || declares.test(target))
+      .map(({ candidate }) => candidate),
+  ];
+  const names = [...new Set(present.map((c) => c.contract))];
+  if (names.length > 1) throw ambiguousName(contract, names);
+
+  if (fresh.length === 0) {
+    throw new Error(
+      stale.length > 0
+        ? `Every build info holding ${contract} is older than the sources on disk. Build again.`
+        : `${contract} is no longer on disk (moved or deleted). Build again.`,
+    );
+  }
+
+  // Several fresh builds of the same sources are interchangeable only when the
+  // compiler and its settings agree (Foundry profiles can differ in both).
+  const byBuild = new Map<string, Candidate>();
+  for (const candidate of fresh.sort((a, b) => a.file.localeCompare(b.file))) {
+    const key = buildKey(candidate.info);
+    if (!byBuild.has(key)) byBuild.set(key, candidate);
+  }
+  if (byBuild.size > 1) {
+    const files = [...byBuild.values()].map((c) => relative(root, c.file));
+    throw new Error(
+      `${contract} was built with different compilers or settings in ${files.join(", ")} ` +
+        `(a project with several solc versions compiles shared files once per version). ` +
+        `Pick one with the \`file\` option (\`--build-info\` on the command line); ` +
+        `\`forge clean\` drops leftover builds.`,
+    );
+  }
+  return toResult([...byBuild.values()][0]);
+}
+
+interface Target {
+  /** Source path as given, without Hardhat 3's `project/` prefix. */
+  path?: string;
+  name: string;
+}
+
+function parseTarget(contract: string): Target {
+  const colon = contract.lastIndexOf(":");
+  const name = contract.slice(colon + 1);
+  if (!/^[A-Za-z_$][\w$]*$/.test(name)) {
+    // Not quoted: a URL passed here by mistake can carry an API key.
+    throw new Error("Expected a contract name or `path/File.sol:Name`.");
+  }
+  if (colon === -1) return { name };
+  const path = contract.slice(0, colon).replace(/^\.\//, "");
+  return { path: path.replace(/^project\//, ""), name };
+}
+
+async function listBuildInfoFiles(root: string): Promise<string[]> {
+  const files: string[] = [];
+  for (const dir of DIRS) {
+    let entries: string[];
+    try {
+      entries = await readdir(resolve(root, dir));
+    } catch (e) {
+      if ((e as NodeJS.ErrnoException).code === "ENOENT") continue;
+      throw e;
+    }
+    for (const entry of entries.sort()) {
+      // Hardhat 3 keeps the compiler output next to the build info, in `<id>.output.json`.
+      if (entry.endsWith(".json") && !entry.endsWith(".output.json")) {
+        files.push(join(resolve(root, dir), entry));
+      }
+    }
+  }
+  return files;
+}
+
+/**
+ * Undefined for a file with no compiler input: Foundry writes one per build
+ * (only `id` and `source_id_to_path`) unless asked for full build info.
+ */
+async function readBuildInfo(file: string, text: string): Promise<RawBuildInfo | undefined> {
+  let info: RawBuildInfo;
+  try {
+    info = JSON.parse(text) as RawBuildInfo;
+  } catch (e) {
+    throw new Error(`${file} is not JSON: ${(e as Error).message}`, { cause: e });
+  }
+  if (info?.input === undefined && info?.source_id_to_path !== undefined) return undefined;
+  if (
+    typeof info?.solcLongVersion !== "string" ||
+    typeof info.input?.sources !== "object" ||
+    info.input.sources === null
+  ) {
+    throw new Error(`${file} is not a build-info file (no solcLongVersion or input sources).`);
+  }
+  if (info.output === undefined) {
+    const outputFile = file.replace(/\.json$/, ".output.json");
+    try {
+      info.output = (JSON.parse(await readFile(outputFile, "utf8")) as RawBuildInfo).output;
+    } catch (e) {
+      if ((e as NodeJS.ErrnoException).code !== "ENOENT") {
+        throw new Error(`Cannot read ${outputFile}: ${(e as Error).message}`, { cause: e });
+      }
+    }
+  }
+  return info;
+}
+
+// Fully qualified names in `info` that match the target.
+function findContract(info: RawBuildInfo, target: Target): string[] {
+  const sources = Object.keys(info.input!.sources);
+  if (target.path !== undefined) {
+    const path = target.path;
+    const source = sources.find((s) => s === path || s === `project/${path}`);
+    if (source === undefined) return [];
+    const compiled = info.output?.contracts?.[source];
+    // Without output the name cannot be checked here; solc checks it when the layout is built.
+    if (compiled !== undefined && !Object.hasOwn(compiled, target.name)) return [];
+    return [`${source}:${target.name}`];
+  }
+  if (info.output?.contracts === undefined) return [];
+  return Object.entries(info.output.contracts)
+    .filter(([, contracts]) => Object.hasOwn(contracts, target.name))
+    .map(([source]) => `${source}:${target.name}`);
+}
+
+/**
+ * Compares the target and every source it imports, directly or not, with the
+ * disk. A changed base contract changes the target's layout; a changed
+ * unrelated file does not, and must not make a build stale: an incremental
+ * build holds only the files it recompiled, so the build that holds the target
+ * is often older than files the target never imports. `gone` when the target's
+ * file no longer exists; a dependency not found on disk (hoisted node_modules,
+ * say) is not checked. `target` is the target's text on disk, when found.
+ */
+async function checkDisk(
+  root: string,
+  { info, contract }: Candidate,
+): Promise<"gone" | { fresh: boolean; target: string | undefined }> {
+  const targetSource = sourceOf(contract);
+  let target: string | undefined;
+  let fresh = true;
+  // The target comes first.
+  for (const source of dependencies(info, targetSource)) {
+    const onDisk = await readSource(root, info, source);
+    if (source === targetSource) {
+      if (onDisk === null) return "gone";
+      target = onDisk;
+    }
+    const content = info.input!.sources[source]?.content;
+    if (typeof onDisk === "string" && typeof content === "string" && onDisk !== content) {
+      fresh = false;
+    }
+  }
+  return { fresh, target };
+}
+
+/**
+ * `source` and everything it imports, from the import directives in the
+ * output's ASTs. Without them, every source in the build (the cautious answer).
+ */
+function dependencies(info: RawBuildInfo, source: string): string[] {
+  // The target first, as checkDisk expects.
+  const all = [source, ...Object.keys(info.input!.sources).filter((s) => s !== source)];
+  const asts = info.output?.sources;
+  const seen = new Set([source]);
+  const queue = [source];
+  while (queue.length > 0) {
+    const nodes = asts?.[queue.pop()!]?.ast?.nodes;
+    if (nodes === undefined) return all;
+    for (const node of nodes) {
+      const imported = node.nodeType === "ImportDirective" ? node.absolutePath : undefined;
+      if (imported !== undefined && !seen.has(imported)) {
+        seen.add(imported);
+        queue.push(imported);
+      }
+    }
+  }
+  return [...seen];
+}
+
+/**
+ * The file on disk behind a build's source name: undefined when it cannot be
+ * located by name (Hardhat 3's versioned `npm/` paths), null when it should be
+ * there and is not.
+ */
+async function readSource(
+  root: string,
+  info: RawBuildInfo,
+  source: string,
+): Promise<string | null | undefined> {
+  const user = Object.entries(info.userSourceNameMap ?? {}).find(([, s]) => s === source)?.[0];
+  if (user === undefined && source.startsWith("npm/")) return undefined;
+  const names =
+    user !== undefined
+      ? [user]
+      : [source, ...(source.startsWith("project/") ? [source.slice("project/".length)] : [])];
+  const paths = names.flatMap((name) => [resolve(root, name), resolve(root, "node_modules", name)]);
+  return (await readFirst(paths)) ?? null;
+}
+
+async function readFirst(paths: string[]): Promise<string | undefined> {
+  for (const path of paths) {
+    try {
+      return await readFile(path, "utf8");
+    } catch (e) {
+      const code = (e as NodeJS.ErrnoException).code;
+      if (code !== "ENOENT" && code !== "ENOTDIR") throw e;
+    }
+  }
+  return undefined;
+}
+
+function buildKey(info: RawBuildInfo): string {
+  const settings = { ...(info.input!.settings as Record<string, unknown> | undefined) };
+  delete settings.outputSelection;
+  return JSON.stringify([info.solcLongVersion, settings]);
+}
+
+function ambiguousName(contract: string, names: string[]): Error {
+  return new Error(`${contract} is ambiguous: ${names.join(", ")}. Use \`path/File.sol:Name\`.`);
+}
+
+function sourceOf(contract: string): string {
+  return contract.slice(0, contract.lastIndexOf(":"));
+}
+
+function toResult({ file, info, contract }: Candidate): BuildInfoContract {
+  const source = sourceOf(contract);
+  const deployed =
+    info.output?.contracts?.[source]?.[contract.slice(source.length + 1)]?.evm?.deployedBytecode;
+  const sources = info.input!.sources;
+  return {
+    file,
+    contract,
+    solcVersion: info.solcLongVersion!,
+    input: {
+      ...info.input!,
+      sources: Object.fromEntries(dependencies(info, source).map((s) => [s, sources[s]])),
+    },
+    deployedBytecode: deployed?.object,
+    immutableReferences: deployed?.immutableReferences,
+  };
+}

package/src/bytecode.ts

@@ -0,0 +1,141 @@
+/**
+ * Bytecode comparison utilities.
+ *
+ * Solidity appends a CBOR-encoded metadata hash to the end of every compiled
+ * contract's bytecode. The last two bytes encode the length of that metadata
+ * section. Stripping it allows comparing contracts that are logically identical
+ * but were compiled in different environments (different metadata).
+ */
+
+export function stripBytecodeMetadata(bytecode: string): string {
+  const buf = toBuffer(bytecode);
+  const start = cborStart(buf);
+  if (start === undefined) return bytecode;
+  return "0x" + buf.subarray(0, start).toString("hex");
+}
+
+function toBuffer(bytecode: string): Buffer {
+  return Buffer.from(bytecode.startsWith("0x") ? bytecode.slice(2) : bytecode, "hex");
+}
+
+// Where solc's CBOR metadata starts, or undefined when the tail is not CBOR.
+function cborStart(buf: Buffer): number | undefined {
+  if (buf.length < 2) return undefined;
+  const metadataLength = buf.readUInt16BE(buf.length - 2);
+  if (metadataLength === 0 || metadataLength + 2 > buf.length) return undefined;
+  // solc's metadata is a CBOR map (major type 5). Without that marker the
+  // tail is code (e.g. compiled with appendCBOR: false), and stripping it
+  // would hide real differences.
+  const start = buf.length - 2 - metadataLength;
+  return buf[start] >> 5 === 5 ? start : undefined;
+}
+
+// The CBOR keys solc uses for the metadata hash, each with its byte-string header.
+const SOURCE_HASH_KEYS = [
+  Buffer.from("6469706673" + "5822", "hex"), // "ipfs", 34 bytes
+  Buffer.from("65627a7a7230" + "5820", "hex"), // "bzzr0", 32 bytes
+  Buffer.from("65627a7a7231" + "5820", "hex"), // "bzzr1", 32 bytes
+];
+
+/**
+ * Whether compiled code embeds the hash of its metadata, which covers every
+ * source file and the settings. Only then does matching code also mean
+ * matching source. `bytecodeHash: "none"` and `appendCBOR: false` drop it.
+ */
+function hasSourceHash(bytecode: string): boolean {
+  const buf = toBuffer(bytecode);
+  const start = cborStart(buf);
+  if (start === undefined) return false;
+  const cbor = buf.subarray(start, buf.length - 2);
+  return SOURCE_HASH_KEYS.some((key) => cbor.includes(key));
+}
+
+function normalize(s: string): string {
+  return s.toLowerCase().replace(/^0x/, "");
+}
+
+// ---------------------------------------------------------------------------
+// Compiled-vs-on-chain comparison
+// ---------------------------------------------------------------------------
+
+/**
+ * solc's `evm.deployedBytecode.immutableReferences`: AST id to the byte spans
+ * (relative to the deployed bytecode) that the constructor fills in.
+ */
+export type ImmutableReferences = Record<string, ReadonlyArray<{ start: number; length: number }>>;
+
+/**
+ * - `exact`: byte-identical.
+ * - `immutables-only`: identical once immutable (and library-link) spans are
+ *   masked. Same code, deployment-specific values. Every UUPS implementation
+ *   lands here because `UUPSUpgradeable.__self` is immutable.
+ * - `metadata-only`: identical after masking and stripping the CBOR metadata,
+ *   so the compiler input was not byte-identical (source hashes or settings).
+ *   NOT proof of storage layout: variables no code reads, gap sizes and field
+ *   names do not reach the bytecode, so different layouts can share code.
+ * - `code-only`: identical (exactly or once masked), but the build embeds no
+ *   source hash (`bytecodeHash: "none"` or `appendCBOR: false`), so nothing
+ *   ties the code to its source. NOT proof of layout, for the same reason.
+ * - `none`: different code.
+ *
+ * `exact` and `immutables-only` therefore always mean the source is proven too.
+ */
+export type DeployedBytecodeMatch =
+  "exact" | "immutables-only" | "metadata-only" | "code-only" | "none";
+
+/** The matches that prove a source is the deployed code, and so prove its layout. */
+export type ProvingMatch = "exact" | "immutables-only";
+
+export function isProvingMatch(match: DeployedBytecodeMatch): match is ProvingMatch {
+  return match === "exact" || match === "immutables-only";
+}
+
+// solc leaves `__$<34 hex>$__` (20 bytes) where an external library address is linked.
+const LINK_PLACEHOLDER = /__\$[0-9a-fA-F]{34}\$__/g;
+
+/**
+ * Compares runtime code read with `eth_getCode` against compiler output.
+ *
+ * On-chain code has immutables filled in while compiler output has them
+ * zeroed, and the difference sits in the code body where metadata stripping
+ * cannot reach, so the spans are zeroed on both sides before comparing.
+ */
+export function compareDeployedBytecode(
+  onchain: string,
+  compiled: string,
+  immutableReferences: ImmutableReferences = {},
+): DeployedBytecodeMatch {
+  const live = normalize(onchain);
+  const built = normalize(compiled);
+  if (live === "" || built === "") return "none";
+  if (live === built) return hasSourceHash(built) ? "exact" : "code-only";
+
+  const spans: Array<{ start: number; length: number }> = Object.values(immutableReferences).flat();
+  for (const m of built.matchAll(LINK_PLACEHOLDER)) {
+    spans.push({ start: m.index / 2, length: 20 });
+  }
+  const builtHex = built.replace(LINK_PLACEHOLDER, "0".repeat(40));
+
+  const liveMasked = maskSpans(live, spans);
+  const builtMasked = maskSpans(builtHex, spans);
+  if (liveMasked === undefined || builtMasked === undefined) return "none";
+  if (liveMasked === builtMasked) return hasSourceHash(builtHex) ? "immutables-only" : "code-only";
+  if (stripBytecodeMetadata(liveMasked) === stripBytecodeMetadata(builtMasked)) {
+    return "metadata-only";
+  }
+  return "none";
+}
+
+// Returns undefined when the hex is malformed or a span falls outside the code.
+function maskSpans(
+  hex: string,
+  spans: ReadonlyArray<{ start: number; length: number }>,
+): string | undefined {
+  const buf = Buffer.from(hex, "hex");
+  if (buf.length * 2 !== hex.length) return undefined;
+  for (const { start, length } of spans) {
+    if (start + length > buf.length) return undefined;
+    buf.fill(0, start, start + length);
+  }
+  return buf.toString("hex");
+}

package/src/chain.ts

@@ -0,0 +1,75 @@
+import {
+  EIP1967BeaconNotFound,
+  EIP1967ImplementationNotFound,
+  getBeaconAddress,
+  getImplementationAddress,
+  getImplementationAddressFromBeacon,
+  type EthereumProvider,
+} from "@openzeppelin/upgrades-core";
+import { createHash } from "node:crypto";
+import { LayoutUnavailableError } from "./errors.js";
+
+/** The one JSON-RPC method used; Hardhat's network provider and ethers' JsonRpcProvider both fit. */
+export interface EthProvider {
+  send(method: string, params: unknown[]): Promise<unknown>;
+}
+
+export interface ProxyState {
+  implementation: string;
+  /** Set for a beacon proxy; `implementation` is then the beacon's. */
+  beacon?: string;
+}
+
+/**
+ * Reads what a proxy runs right now: the ERC-1967 implementation slot, or the
+ * beacon's implementation for a beacon proxy. Undefined when neither slot is
+ * set, i.e. the address is not a proxy this tool understands.
+ */
+export async function readProxy(
+  provider: EthProvider,
+  address: string,
+): Promise<ProxyState | undefined> {
+  const oz = provider as unknown as EthereumProvider;
+  try {
+    return { implementation: (await getImplementationAddress(oz, address)).toLowerCase() };
+  } catch (e) {
+    if (!(e instanceof EIP1967ImplementationNotFound)) throw e;
+  }
+  let beacon: string;
+  try {
+    beacon = (await getBeaconAddress(oz, address)).toLowerCase();
+  } catch (e) {
+    if (e instanceof EIP1967BeaconNotFound) return undefined;
+    throw e;
+  }
+  const implementation = (await getImplementationAddressFromBeacon(oz, beacon)).toLowerCase();
+  return { implementation, beacon };
+}
+
+export async function readImplementation(provider: EthProvider, proxy: string): Promise<string> {
+  const state = await readProxy(provider, proxy);
+  if (state === undefined) {
+    throw new LayoutUnavailableError(
+      `${proxy} has no ERC-1967 implementation or beacon slot set on this chain.`,
+    );
+  }
+  return state.implementation;
+}
+
+export async function readCode(provider: EthProvider, address: string): Promise<string> {
+  const code = (await provider.send("eth_getCode", [address, "latest"])) as string;
+  if (code === "0x" || code === "") {
+    throw new LayoutUnavailableError(`No code at ${address} on this chain.`);
+  }
+  return code.toLowerCase();
+}
+
+export async function readChainId(provider: EthProvider): Promise<number> {
+  return Number(BigInt((await provider.send("eth_chainId", [])) as string));
+}
+
+export function codeSha256(code: string): string {
+  return createHash("sha256")
+    .update(Buffer.from(code.replace(/^0x/, ""), "hex"))
+    .digest("hex");
+}