slotdiff 0.1.0-alpha.1 → 0.3.0

package/src/explorer.ts

@@ -8,7 +8,7 @@
  */
 
 import type { SolcInput } from "@openzeppelin/upgrades-core";
-import { LayoutUnavailableError } from "./errors.js";
+import { errorCode, LayoutUnavailableError, printable } 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) {
@@ -115,8 +115,12 @@ async function requestWithRetry(url: string, fetchImpl: FetchLike): Promise<Sour
       return entry as SourceCodeEntry;
     }
 
-    const detail =
-      typeof body.result === "string" ? body.result : (body.message ?? "unknown error");
+    // One line: a line break could draw a verdict of its own under the error.
+    const detail = printable(
+      String(typeof body.result === "string" ? body.result : (body.message ?? "unknown error")),
+    )
+      .replace(/\s+/g, " ")
+      .slice(0, 300);
     // Before the key check: Etherscan's rate-limit message mentions the API key.
     if (RATE_LIMIT.test(detail)) {
       if (retry) {
@@ -134,6 +138,10 @@ function backoff(attempt: number): Promise<void> {
   return new Promise((r) => setTimeout(r, 1000 * attempt));
 }
 
+// Control characters other than tabs and line breaks (\v, \f and \r included).
+// eslint-disable-next-line no-control-regex
+const CONTROL = /[\u0000-\u0008\u000e-\u001f\u007f-\u009f]/;
+
 /** Exported for tests. */
 export function parseSourceCodeEntry(entry: SourceCodeEntry, address: string): VerifiedSource {
   const raw = entry.SourceCode ?? "";
@@ -144,7 +152,8 @@ export function parseSourceCodeEntry(entry: SourceCodeEntry, address: string): V
   const compilerVersion = entry.CompilerVersion ?? "";
   if (!compilerVersion.startsWith("v0.")) {
     throw new LayoutUnavailableError(
-      `Contract ${address} was verified with "${compilerVersion}"; only Solidity is supported.`,
+      `Contract ${address} was verified with "${printable(compilerVersion).slice(0, 80)}"; ` +
+        "only Solidity is supported.",
     );
   }
 
@@ -154,7 +163,8 @@ export function parseSourceCodeEntry(entry: SourceCodeEntry, address: string): V
     )
   ) {
     throw new LayoutUnavailableError(
-      `Contract ${address} reports an unrecognized compiler version "${compilerVersion}".`,
+      `Contract ${address} reports an unrecognized compiler version ` +
+        `"${printable(compilerVersion).slice(0, 80)}".`,
     );
   }
 
@@ -166,11 +176,30 @@ export function parseSourceCodeEntry(entry: SourceCodeEntry, address: string): V
     );
   }
 
-  return {
-    input,
-    solcLongVersion: compilerVersion.slice(1),
-    contractName: entry.ContractName ?? "",
-  };
+  // Names, paths and source text (annotations, quoted by solc) reach the
+  // screen; real source holds no control characters but tabs and line breaks.
+  const contractName = entry.ContractName ?? "";
+  const sources = Object.values(input.sources) as Array<{ content?: unknown }>;
+  // Every source inline: solc would fetch `urls` itself.
+  if (sources.some((s) => typeof s?.content !== "string")) {
+    throw new LayoutUnavailableError(
+      `Contract ${address} is verified with sources that are not inline (urls); only content is read.`,
+    );
+  }
+  const contents = sources.map((s) => s.content as string);
+  if (
+    // Names and paths are printed on one line: no whitespace but a space.
+    [contractName, ...Object.keys(input.sources)].some(
+      (s) => printable(s) !== s || /[^\S ]/.test(s),
+    ) ||
+    contents.some((s) => CONTROL.test(s))
+  ) {
+    throw new LayoutUnavailableError(
+      `Contract ${address} is verified with control characters in its name, paths or source.`,
+    );
+  }
+
+  return { input, solcLongVersion: compilerVersion.slice(1), contractName };
 }
 
 // Etherscan wraps standard-json in an extra pair of braces (`{{...}}`); some

package/src/index.ts

@@ -24,7 +24,32 @@ 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 {
+  checkUpgrade,
+  type UpgradeCheck,
+  type UpgradeOptions,
+  type UpgradeSide,
+} from "./upgrade.js";
+export {
+  analyzeSource,
+  analyzeBuild,
+  type BuildAnalysis,
+  type BuildCompiler,
+  SAFETY_ERROR_KINDS,
+  type SourceAnalysis,
+  type SafetyOptions,
+  type SafetyReport,
+  type SafetyError,
+  type SafetyErrorKind,
+  type ProxyKind,
+} from "./reconstruct.js";
 export {
   compareDeployedBytecode,
   isProvingMatch,
@@ -32,5 +57,5 @@ export {
   type ProvingMatch,
   type ImmutableReferences,
 } from "./bytecode.js";
-export { LayoutIntegrityError, LayoutUnavailableError } from "./errors.js";
-export type { SolcInput, StorageLayout } from "@openzeppelin/upgrades-core";
+export { IncompleteBuildError, LayoutIntegrityError, LayoutUnavailableError } from "./errors.js";
+export type { SolcInput, SolcOutput, StorageLayout } from "@openzeppelin/upgrades-core";

package/src/reconstruct.ts

@@ -8,27 +8,33 @@
  */
 
 import {
+  getErrors,
   getStorageLayout,
+  hashBytecode,
+  inferProxyKind,
   isNamespaceSupported,
   makeNamespacedInput,
   solcInputOutputDecoder,
   trySanitizeNatSpec,
+  UpgradeableContractErrorReport,
   validate,
+  type ProxyDeployment,
   type SolcInput,
   type SolcOutput,
   type StorageLayout,
+  type ValidationRunData,
 } from "@openzeppelin/upgrades-core";
 import { compareDeployedBytecode, isProvingMatch, type ProvingMatch } from "./bytecode.js";
-import { LayoutIntegrityError } from "./errors.js";
+import { namespaceSlots, type NamespaceSlot } from "./erc7201.js";
+import { IncompleteBuildError, LayoutIntegrityError, printable } 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
@@ -41,6 +47,7 @@ const FULL_SELECTION = {
       "evm.bytecode.linkReferences",
       "evm.deployedBytecode.object",
       "evm.deployedBytecode.immutableReferences",
+      "metadata",
     ],
     "": ["ast"],
   },
@@ -68,61 +75,304 @@ export async function reconstructLayout(
     contract,
     compiler: source.solcLongVersion,
     bytecodeMatch,
-    layout: await extractLayout(input, output, solc, contract),
+    ...(await analyzeBuild(input, output, solc)).contract(contract),
   };
 }
 
+export type ProxyKind = ProxyDeployment["kind"];
+
+type ValidationError = ReturnType<typeof getErrors>[number];
+
 /**
- * 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.
+ * OpenZeppelin's safety error kinds, without the deprecated struct-definition
+ * 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 async function layoutFromSource(
+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 type SafetyErrorKind = (typeof SAFETY_ERROR_KINDS)[number];
+
+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; `color` (default true) adds terminal colors. */
+  explain(color?: boolean): 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;
+}
+
+/**
+ * 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<StorageLayout> {
+): Promise<SourceAnalysis> {
   const selected = withOutputSelection(input, FULL_SELECTION);
   const output = await compileOrThrow(solc, selected, "source");
-  return extractLayout(selected, output, solc, contract);
+  return (await analyzeBuild(selected, output, solc)).contract(contract);
 }
 
-async function extractLayout(
+/** 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;
+}
+
+/**
+ * `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<StorageLayout> {
-  const solcVersion = solc.longVersion.split("+")[0];
+): 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.
+      const errors = getErrors(data, version, opts) as Array<ValidationError & SafetyError>;
+      return {
+        ok: errors.length === 0,
+        errors,
+        explain: (color?: boolean) => new UpgradeableContractErrorReport(errors).explain(color),
+      };
+    },
+  };
+}
+
+async function validateBuild(
+  input: SolcInput,
+  output: SolcOutput,
+  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; 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);
 }
 
 /**
@@ -200,7 +450,7 @@ function embedsSourceHash(input: SolcInput): boolean {
 }
 
 async function compileOrThrow(
-  solc: SolcRunner,
+  solc: BuildCompiler,
   input: SolcInput,
   what: string,
 ): Promise<SolcOutput> {
@@ -208,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 ` +