slotdiff 0.0.0-stage → 0.1.0-alpha.1

package/dist/resolve.js

@@ -0,0 +1,80 @@
+/**
+ * Proven layouts of deployed code, as `LayoutRecord`s. Nothing here writes to
+ * disk; see `record.ts` for saving and loading records.
+ *
+ * Under lazy or queued (multisig) upgrades, a project's files describe its
+ * latest build while proxies keep running older implementations. Reading the
+ * implementation from the chain and proving its source against the deployed
+ * code gives the layout of what actually runs.
+ */
+import { compareDeployedBytecode, isProvingMatch, } from "./bytecode.js";
+import { codeSha256, readChainId, readCode, readProxy } from "./chain.js";
+import { LayoutUnavailableError } from "./errors.js";
+import { canQueryExplorer, fetchVerifiedSource } from "./explorer.js";
+import { reconstructLayout } from "./reconstruct.js";
+import { parseRecord } from "./record.js";
+import { getSolc } from "./solc.js";
+/**
+ * Rebuilds the layout of the code at `address` from its verified source and
+ * proves that source is the deployed code. Always fetches and compiles; check
+ * your own saved record first (`verifyRecord`) to skip that.
+ */
+export async function resolveLayout(provider, address, options) {
+    const lower = address.toLowerCase();
+    if (!canQueryExplorer(options.explorer)) {
+        throw new LayoutUnavailableError(`Cannot rebuild the layout of ${lower}: the explorer needs an apiKey or an apiUrl.`);
+    }
+    const code = await readCode(provider, lower);
+    const chainId = await readChainId(provider);
+    const source = await fetchVerifiedSource(chainId, lower, options.explorer);
+    const solc = await getSolc(source.solcLongVersion, options.solc);
+    const rebuilt = await reconstructLayout(source, solc, code);
+    return {
+        format: 1,
+        address: lower,
+        chainId,
+        codeSha256: codeSha256(code),
+        contract: rebuilt.contract,
+        compiler: rebuilt.compiler,
+        bytecodeMatch: rebuilt.bytecodeMatch,
+        source: "explorer",
+        recordedAt: new Date().toISOString(),
+        layout: rebuilt.layout,
+    };
+}
+/** `resolveLayout` for whatever implementation `proxy` runs right now (ERC-1967 or beacon). */
+export async function resolveProxyLayout(provider, proxy, options) {
+    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.`);
+    }
+    const record = await resolveLayout(provider, state.implementation, options);
+    return { ...state, record };
+}
+/**
+ * Makes a record from a local build of the code at `address`, but only after
+ * proving the chain runs that build. A `metadata-only` or `none` match gives
+ * no record, so a layout is never attributed to code that is not there.
+ */
+export async function proveLocalBuild(provider, address, build) {
+    const lower = address.toLowerCase();
+    const code = await readCode(provider, lower);
+    const bytecodeMatch = compareDeployedBytecode(code, build.deployedBytecode, build.immutableReferences);
+    if (!isProvingMatch(bytecodeMatch))
+        return { bytecodeMatch };
+    const record = {
+        format: 1,
+        address: lower,
+        chainId: await readChainId(provider),
+        codeSha256: codeSha256(code),
+        contract: build.contract,
+        ...(build.compiler !== undefined ? { compiler: build.compiler } : {}),
+        bytecodeMatch,
+        source: "local-compile",
+        recordedAt: new Date().toISOString(),
+        layout: build.layout,
+    };
+    // A record this returns must load back through parseRecord, so check it now.
+    return { bytecodeMatch, record: parseRecord(JSON.parse(JSON.stringify(record)), lower) };
+}
+//# sourceMappingURL=resolve.js.map

package/dist/resolve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.js","sourceRoot":"","sources":["../src/resolve.ts"],"names":[],"mappings":"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"}

package/dist/solc.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Native solc acquisition and invocation, independent of Hardhat's compiler
+ * manager so the core stays usable outside a Hardhat runtime.
+ *
+ * Lookup order: explicit override, our cache, Hardhat's compiler caches (v3
+ * then v2, so a project that already compiled with that version pays nothing),
+ * then a download from binaries.soliditylang.org verified against the
+ * published sha256.
+ *
+ * Takes a long version (`0.8.24+commit.e11b9ed9`) or a release version
+ * (`0.8.24`, which is what Foundry's build-info records); a release version
+ * resolves to that release's build, never a nightly.
+ */
+import type { SolcInput, SolcOutput } from "@openzeppelin/upgrades-core";
+export interface SolcRunner {
+    /**
+     * Resolved, e.g. `0.8.24+commit.e11b9ed9` even when asked for `0.8.24`. With
+     * `resolvePath`, the version as passed.
+     */
+    longVersion: string;
+    path: string;
+    compile(input: SolcInput): Promise<SolcOutput>;
+}
+export interface SolcOptions {
+    /** Where downloaded compilers are kept. Defaults to `<os cache>/slotdiff/compilers`. */
+    cacheDir?: string;
+    /** Explicit binary for a version (as passed to `getSolc`), e.g. on platforms with no official native build. */
+    resolvePath?: (version: string) => string | undefined;
+}
+type FetchBinary = (url: string) => Promise<{
+    ok: boolean;
+    status: number;
+    json(): Promise<unknown>;
+    arrayBuffer(): Promise<ArrayBuffer>;
+}>;
+export declare function getSolc(version: string, options?: SolcOptions, fetchImpl?: FetchBinary): Promise<SolcRunner>;
+export {};
+//# sourceMappingURL=solc.d.ts.map

package/dist/solc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"solc.d.ts","sourceRoot":"","sources":["../src/solc.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAQH,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAWzE,MAAM,WAAW,UAAU;IACzB;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;CAChD;AAED,MAAM,WAAW,WAAW;IAC1B,wFAAwF;IACxF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,+GAA+G;IAC/G,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;CACvD;AAED,KAAK,WAAW,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;IAC1C,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IACzB,WAAW,IAAI,OAAO,CAAC,WAAW,CAAC,CAAC;CACrC,CAAC,CAAC;AAEH,wBAAsB,OAAO,CAC3B,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,WAAgB,EACzB,SAAS,GAAE,WAAmB,GAC7B,OAAO,CAAC,UAAU,CAAC,CAGrB"}

package/dist/solc.js

@@ -0,0 +1,194 @@
+/**
+ * Native solc acquisition and invocation, independent of Hardhat's compiler
+ * manager so the core stays usable outside a Hardhat runtime.
+ *
+ * Lookup order: explicit override, our cache, Hardhat's compiler caches (v3
+ * then v2, so a project that already compiled with that version pays nothing),
+ * then a download from binaries.soliditylang.org verified against the
+ * published sha256.
+ *
+ * Takes a long version (`0.8.24+commit.e11b9ed9`) or a release version
+ * (`0.8.24`, which is what Foundry's build-info records); a release version
+ * resolves to that release's build, never a nightly.
+ */
+import { spawn } from "node:child_process";
+import { createHash, randomUUID } from "node:crypto";
+import { access, chmod, mkdir, readdir, rename, writeFile } from "node:fs/promises";
+import { constants } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { LayoutIntegrityError, LayoutUnavailableError } from "./errors.js";
+const BINARIES_URL = "https://binaries.soliditylang.org";
+const RELEASE_VERSION = /^\d+\.\d+\.\d+$/;
+// Validated before use: the version becomes part of a path that gets executed.
+const SOLC_VERSION = /^\d+\.\d+\.\d+(?:-nightly\.\d+\.\d+\.\d+|-pre\.\d+)?(?:\+commit\.[0-9a-f]+)?$/;
+const RELEASE_LONG_VERSION = /^\d+\.\d+\.\d+\+commit\.[0-9a-f]+$/;
+export async function getSolc(version, options = {}, fetchImpl = fetch) {
+    const { path, longVersion } = await locateSolc(version, options, fetchImpl);
+    return { longVersion, path, compile: (input) => runSolc(path, input) };
+}
+const downloads = new Map();
+async function locateSolc(version, options, fetchImpl) {
+    if (!SOLC_VERSION.test(version)) {
+        throw new LayoutUnavailableError(`"${version}" is not a solc version.`);
+    }
+    const explicit = options.resolvePath?.(version);
+    if (explicit !== undefined)
+        return { path: explicit, longVersion: version };
+    const platform = nativePlatform();
+    const cacheDir = options.cacheDir ?? join(osCacheDir(), "slotdiff", "compilers");
+    // Hardhat's cache follows env-paths, which adds a `Cache` folder on Windows.
+    const hardhatCache = process.platform === "win32"
+        ? join(osCacheDir(), "hardhat-nodejs", "Cache")
+        : join(osCacheDir(), "hardhat-nodejs");
+    const dirs = [
+        join(cacheDir, platform),
+        join(hardhatCache, "compilers-v3", platform),
+        join(hardhatCache, "compilers-v2", platform),
+    ];
+    for (const dir of dirs) {
+        const cached = await findCached(dir, platform, version);
+        if (cached !== undefined)
+            return cached;
+    }
+    const build = await findBuild(platform, version, fetchImpl);
+    const dest = join(cacheDir, platform, binaryName(platform, build.longVersion));
+    // Concurrent callers (one per proxy, say) share one download per binary.
+    let pending = downloads.get(dest);
+    if (pending === undefined) {
+        pending = download(platform, build, dest, fetchImpl).finally(() => downloads.delete(dest));
+        downloads.set(dest, pending);
+    }
+    await pending;
+    return { path: dest, longVersion: build.longVersion };
+}
+function binaryName(platform, longVersion) {
+    return `solc-${platform}-v${longVersion}${platform === "windows-amd64" ? ".exe" : ""}`;
+}
+async function findCached(dir, platform, version) {
+    if (!RELEASE_VERSION.test(version)) {
+        const path = join(dir, binaryName(platform, version));
+        return (await isExecutable(path)) ? { path, longVersion: version } : undefined;
+    }
+    let names;
+    try {
+        names = await readdir(dir);
+    }
+    catch {
+        return undefined;
+    }
+    // Only finished release binaries of this version: no nightlies (`0.8.24-nightly...`),
+    // no longer versions (`0.8.240`), no in-progress `.tmp` downloads.
+    const prefix = `solc-${platform}-v`;
+    const ext = platform === "windows-amd64" ? ".exe" : "";
+    for (const name of names.sort()) {
+        if (!name.startsWith(prefix) || !name.endsWith(ext))
+            continue;
+        const longVersion = name.slice(prefix.length, name.length - ext.length);
+        if (!RELEASE_LONG_VERSION.test(longVersion) || !longVersion.startsWith(`${version}+`))
+            continue;
+        const path = join(dir, name);
+        if (await isExecutable(path))
+            return { path, longVersion };
+    }
+    return undefined;
+}
+async function findBuild(platform, version, fetchImpl) {
+    // Failing to obtain a compiler means the layout cannot be rebuilt, not
+    // that it is wrong; only a checksum mismatch is an integrity problem.
+    const listRes = await fetchOrUnavailable(fetchImpl, `${BINARIES_URL}/${platform}/list.json`);
+    if (!listRes.ok) {
+        throw new LayoutUnavailableError(`Could not fetch the solc build list (HTTP ${listRes.status}).`);
+    }
+    const list = (await listRes.json());
+    const build = RELEASE_VERSION.test(version)
+        ? // A nightly reads `0.8.24-nightly...`, so only the release starts with `0.8.24+`.
+            list.builds.find((b) => b.longVersion.startsWith(`${version}+`))
+        : list.builds.find((b) => b.longVersion === version);
+    if (build === undefined) {
+        throw new LayoutUnavailableError(`solc ${version} has no native ${platform} build.`);
+    }
+    // Old Windows releases (up to 0.7.1) ship as zip archives, not executables.
+    if (build.path.endsWith(".zip")) {
+        throw new LayoutUnavailableError(`solc ${build.longVersion} for ${platform} ships as a zip archive; pass a compiler via solc.resolvePath.`);
+    }
+    return build;
+}
+async function download(platform, build, dest, fetchImpl) {
+    const binRes = await fetchOrUnavailable(fetchImpl, `${BINARIES_URL}/${platform}/${build.path}`);
+    if (!binRes.ok) {
+        throw new LayoutUnavailableError(`Could not download solc ${build.longVersion} (HTTP ${binRes.status}).`);
+    }
+    const bytes = Buffer.from(await binRes.arrayBuffer());
+    const actual = createHash("sha256").update(bytes).digest("hex");
+    if (`0x${actual}` !== build.sha256.toLowerCase()) {
+        throw new LayoutIntegrityError(`solc ${build.longVersion} download failed its sha256 check; refusing to run it.`);
+    }
+    await mkdir(join(dest, ".."), { recursive: true });
+    const tmp = `${dest}.${randomUUID()}.tmp`;
+    await writeFile(tmp, bytes);
+    await chmod(tmp, 0o755);
+    await rename(tmp, dest);
+}
+function runSolc(path, input) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(path, ["--standard-json"], { stdio: ["pipe", "pipe", "pipe"] });
+        const out = [];
+        const err = [];
+        child.stdout.on("data", (d) => out.push(d));
+        child.stderr.on("data", (d) => err.push(d));
+        child.on("error", reject);
+        // A compiler that exits before reading all input closes the pipe; reject
+        // instead of crashing the process with an unhandled EPIPE.
+        child.stdin.on("error", reject);
+        child.on("close", (code) => {
+            if (code !== 0) {
+                reject(new Error(`solc exited with code ${code}: ${Buffer.concat(err).toString()}`));
+                return;
+            }
+            try {
+                resolve(JSON.parse(Buffer.concat(out).toString()));
+            }
+            catch (e) {
+                reject(e);
+            }
+        });
+        child.stdin.end(JSON.stringify(input));
+    });
+}
+function nativePlatform() {
+    const { platform, arch } = process;
+    if (platform === "darwin")
+        return "macosx-amd64"; // universal binaries for recent versions
+    if (platform === "linux" && arch === "x64")
+        return "linux-amd64";
+    if (platform === "win32" && arch === "x64")
+        return "windows-amd64";
+    throw new LayoutUnavailableError(`No official native solc build for ${platform}/${arch}; pass a compiler path via solc.resolvePath.`);
+}
+async function fetchOrUnavailable(fetchImpl, url) {
+    try {
+        return await fetchImpl(url);
+    }
+    catch (e) {
+        throw new LayoutUnavailableError(`Could not reach ${BINARIES_URL}: ${e.message}`);
+    }
+}
+function osCacheDir() {
+    if (process.platform === "darwin")
+        return join(homedir(), "Library", "Caches");
+    if (process.platform === "win32") {
+        return process.env.LOCALAPPDATA ?? join(homedir(), "AppData", "Local");
+    }
+    return process.env.XDG_CACHE_HOME ?? join(homedir(), ".cache");
+}
+async function isExecutable(path) {
+    try {
+        await access(path, constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=solc.js.map

package/dist/solc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"solc.js","sourceRoot":"","sources":["../src/solc.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,72 @@
 {
   "name": "slotdiff",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-alpha.1",
+  "description": "Storage layout diff for upgradeable Solidity contracts: compare a local build or a live deployment against another",
+  "license": "MIT",
+  "author": "Rohit Solia (https://github.com/rokso)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rokso/slotdiff.git"
+  },
+  "homepage": "https://github.com/rokso/slotdiff#readme",
+  "bugs": {
+    "url": "https://github.com/rokso/slotdiff/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && tsc --project tsconfig.build.json",
+    "build:watch": "tsc --project tsconfig.build.json --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc",
+    "lint": "eslint . && prettier --check .",
+    "format": "prettier --write .",
+    "prepublishOnly": "pnpm lint && pnpm test",
+    "clean": "rm -rf dist",
+    "prepack": "pnpm build"
+  },
+  "packageManager": "pnpm@9.0.0",
+  "dependencies": {
+    "@openzeppelin/upgrades-core": "^1.46.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^22.0.0",
+    "eslint": "^10.2.0",
+    "eslint-config-prettier": "^10.1.8",
+    "globals": "^17.5.0",
+    "prettier": "^3.8.2",
+    "typescript": "^5.7.0",
+    "typescript-eslint": "^8.58.2",
+    "vitest": "^4.1.0"
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "keywords": [
+    "ethereum",
+    "solidity",
+    "upgradeable",
+    "proxy",
+    "storage-layout",
+    "upgrade-safety",
+    "foundry",
+    "hardhat"
+  ],
+  "sideEffects": false
+}

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");
+}

package/src/diff.ts

@@ -0,0 +1,31 @@
+import {
+  getStorageUpgradeReport,
+  withValidationDefaults,
+  type StorageLayout,
+} from "@openzeppelin/upgrades-core";
+
+/** OZ's storage comparison. `ok` is the verdict; `explain()` describes each problem. */
+export type LayoutReport = ReturnType<typeof getStorageUpgradeReport>;
+
+export interface DiffOptions {
+  /** Accept renamed variables without `@custom:oz-renamed-from` (OZ's `unsafeAllowRenames`). */
+  unsafeAllowRenames?: boolean;
+}
+
+/**
+ * Whether `after` can safely replace `before` behind a proxy, by OZ's rules:
+ * appends pass; inserts, removals, reorders and incompatible type changes
+ * fail, in regular and ERC-7201 namespaced storage. Renames and retypes pass
+ * when `after` approves them (`@custom:oz-renamed-from` / `oz-retyped-from`).
+ */
+export function diffLayouts(
+  before: StorageLayout,
+  after: StorageLayout,
+  options: DiffOptions = {},
+): LayoutReport {
+  return getStorageUpgradeReport(
+    before,
+    after,
+    withValidationDefaults({ unsafeAllowRenames: options.unsafeAllowRenames }),
+  );
+}