slotdiff 0.0.0-stage → 0.1.0-alpha.1

package/dist/explorer.js

@@ -0,0 +1,131 @@
+/**
+ * Verified-source lookup against an Etherscan-compatible explorer API.
+ *
+ * Only standard-json verifications are accepted. Flattened and multi-file
+ * verifications do not record every compiler setting (`viaIR` among them), so
+ * rebuilding from them means guessing; the bytecode proof would reject a wrong
+ * guess, but refusing up front gives a clearer error.
+ */
+import { LayoutUnavailableError } from "./errors.js";
+export const ETHERSCAN_V2_API_URL = "https://api.etherscan.io/v2/api";
+const RATE_LIMIT = /rate limit/i;
+// Key problems are the user's to fix and must surface; anything else the
+// explorer refuses (unsupported chain, outage) only means it cannot answer.
+const KEY_ERROR = /api.?key/i;
+const MAX_ATTEMPTS = 4;
+/**
+ * Etherscan needs a key; a custom Etherscan-compatible endpoint (e.g. a
+ * Blockscout instance) may not.
+ */
+export function canQueryExplorer(config) {
+    return Boolean(config.apiKey) || Boolean(config.apiUrl);
+}
+export async function fetchVerifiedSource(chainId, address, config, fetchImpl = fetch) {
+    if (!canQueryExplorer(config)) {
+        throw new LayoutUnavailableError(`No explorer API key configured for chain ${chainId}; cannot fetch verified source for ${address}.`);
+    }
+    const url = new URL(config.apiUrl ?? ETHERSCAN_V2_API_URL);
+    url.searchParams.set("chainid", String(chainId));
+    url.searchParams.set("module", "contract");
+    url.searchParams.set("action", "getsourcecode");
+    url.searchParams.set("address", address);
+    if (config.apiKey)
+        url.searchParams.set("apikey", config.apiKey);
+    const entry = await requestWithRetry(url.toString(), fetchImpl);
+    return parseSourceCodeEntry(entry, address);
+}
+async function requestWithRetry(url, fetchImpl) {
+    for (let attempt = 1;; attempt++) {
+        const retry = attempt < MAX_ATTEMPTS;
+        let res;
+        try {
+            res = await fetchImpl(url);
+        }
+        catch (e) {
+            // Messages never include the URL, which carries the API key.
+            throw new LayoutUnavailableError(`Explorer unreachable: ${e.message}`);
+        }
+        if (res.status === 429 && retry) {
+            await backoff(attempt);
+            continue;
+        }
+        if (!res.ok) {
+            throw new LayoutUnavailableError(`Explorer request failed with HTTP ${res.status}.`);
+        }
+        let body;
+        try {
+            body = (await res.json());
+        }
+        catch {
+            throw new LayoutUnavailableError("Explorer returned a response that is not JSON.");
+        }
+        if (typeof body !== "object" || body === null) {
+            throw new LayoutUnavailableError("Explorer returned an unexpected response.");
+        }
+        if (body.status === "1" && Array.isArray(body.result) && body.result.length > 0) {
+            const entry = body.result[0];
+            if (typeof entry !== "object" || entry === null) {
+                throw new LayoutUnavailableError("Explorer returned an unexpected source entry.");
+            }
+            return entry;
+        }
+        const detail = typeof body.result === "string" ? body.result : (body.message ?? "unknown error");
+        // Before the key check: Etherscan's rate-limit message mentions the API key.
+        if (RATE_LIMIT.test(detail)) {
+            if (retry) {
+                await backoff(attempt);
+                continue;
+            }
+            throw new LayoutUnavailableError(`Explorer kept rate-limiting the request: ${detail}`);
+        }
+        if (KEY_ERROR.test(detail))
+            throw new Error(`Explorer rejected the API key: ${detail}`);
+        throw new LayoutUnavailableError(`Explorer could not answer: ${detail}`);
+    }
+}
+function backoff(attempt) {
+    return new Promise((r) => setTimeout(r, 1000 * attempt));
+}
+/** Exported for tests. */
+export function parseSourceCodeEntry(entry, address) {
+    const raw = entry.SourceCode ?? "";
+    if (raw === "") {
+        throw new LayoutUnavailableError(`Contract ${address} is not verified on the explorer.`);
+    }
+    const compilerVersion = entry.CompilerVersion ?? "";
+    if (!compilerVersion.startsWith("v0.")) {
+        throw new LayoutUnavailableError(`Contract ${address} was verified with "${compilerVersion}"; only Solidity is supported.`);
+    }
+    if (!/^v\d+\.\d+\.\d+(?:-nightly\.\d+\.\d+\.\d+|-pre\.\d+)?\+commit\.[0-9a-f]+$/.test(compilerVersion)) {
+        throw new LayoutUnavailableError(`Contract ${address} reports an unrecognized compiler version "${compilerVersion}".`);
+    }
+    const input = parseStandardJson(raw);
+    if (input === undefined) {
+        throw new LayoutUnavailableError(`Contract ${address} is verified as flattened or multi-file source, not standard-json. ` +
+            `Its compiler settings cannot be reconstructed exactly.`);
+    }
+    return {
+        input,
+        solcLongVersion: compilerVersion.slice(1),
+        contractName: entry.ContractName ?? "",
+    };
+}
+// Etherscan wraps standard-json in an extra pair of braces (`{{...}}`); some
+// compatible explorers return it unwrapped.
+function parseStandardJson(raw) {
+    const text = raw.startsWith("{{") && raw.endsWith("}}") ? raw.slice(1, -1) : raw;
+    if (!text.startsWith("{"))
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+    const candidate = parsed;
+    if (candidate.language !== "Solidity" || typeof candidate.sources !== "object")
+        return undefined;
+    return candidate;
+}
+//# sourceMappingURL=explorer.js.map

package/dist/explorer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"explorer.js","sourceRoot":"","sources":["../src/explorer.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAErD,MAAM,CAAC,MAAM,oBAAoB,GAAG,iCAAiC,CAAC;AAgCtE,MAAM,UAAU,GAAG,aAAa,CAAC;AACjC,yEAAyE;AACzE,4EAA4E;AAC5E,MAAM,SAAS,GAAG,WAAW,CAAC;AAC9B,MAAM,YAAY,GAAG,CAAC,CAAC;AAEvB;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAsB;IACrD,OAAO,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;AAC1D,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,OAAe,EACf,OAAe,EACf,MAAsB,EACtB,YAAuB,KAAK;IAE5B,IAAI,CAAC,gBAAgB,CAAC,MAAM,CAAC,EAAE,CAAC;QAC9B,MAAM,IAAI,sBAAsB,CAC9B,4CAA4C,OAAO,sCAAsC,OAAO,GAAG,CACpG,CAAC;IACJ,CAAC;IAED,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,MAAM,IAAI,oBAAoB,CAAC,CAAC;IAC3D,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,SAAS,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC;IACjD,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;IAC3C,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,QAAQ,EAAE,eAAe,CAAC,CAAC;IAChD,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;IACzC,IAAI,MAAM,CAAC,MAAM;QAAE,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;IAEjE,MAAM,KAAK,GAAG,MAAM,gBAAgB,CAAC,GAAG,CAAC,QAAQ,EAAE,EAAE,SAAS,CAAC,CAAC;IAChE,OAAO,oBAAoB,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;AAC9C,CAAC;AAED,KAAK,UAAU,gBAAgB,CAAC,GAAW,EAAE,SAAoB;IAC/D,KAAK,IAAI,OAAO,GAAG,CAAC,GAAI,OAAO,EAAE,EAAE,CAAC;QAClC,MAAM,KAAK,GAAG,OAAO,GAAG,YAAY,CAAC;QACrC,IAAI,GAAmC,CAAC;QACxC,IAAI,CAAC;YACH,GAAG,GAAG,MAAM,SAAS,CAAC,GAAG,CAAC,CAAC;QAC7B,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,6DAA6D;YAC7D,MAAM,IAAI,sBAAsB,CAAC,yBAA0B,CAAW,CAAC,OAAO,EAAE,CAAC,CAAC;QACpF,CAAC;QAED,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG,IAAI,KAAK,EAAE,CAAC;YAChC,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;YACvB,SAAS;QACX,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;YACZ,MAAM,IAAI,sBAAsB,CAAC,qCAAqC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC;QACvF,CAAC;QACD,IAAI,IAAsB,CAAC;QAC3B,IAAI,CAAC;YACH,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAqB,CAAC;QAChD,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,IAAI,sBAAsB,CAAC,gDAAgD,CAAC,CAAC;QACrF,CAAC;QACD,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;YAC9C,MAAM,IAAI,sBAAsB,CAAC,2CAA2C,CAAC,CAAC;QAChF,CAAC;QAED,IAAI,IAAI,CAAC,MAAM,KAAK,GAAG,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAChF,MAAM,KAAK,GAAY,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;YACtC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;gBAChD,MAAM,IAAI,sBAAsB,CAAC,+CAA+C,CAAC,CAAC;YACpF,CAAC;YACD,OAAO,KAAwB,CAAC;QAClC,CAAC;QAED,MAAM,MAAM,GACV,OAAO,IAAI,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,IAAI,eAAe,CAAC,CAAC;QACpF,6EAA6E;QAC7E,IAAI,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;YAC5B,IAAI,KAAK,EAAE,CAAC;gBACV,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;gBACvB,SAAS;YACX,CAAC;YACD,MAAM,IAAI,sBAAsB,CAAC,4CAA4C,MAAM,EAAE,CAAC,CAAC;QACzF,CAAC;QACD,IAAI,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,kCAAkC,MAAM,EAAE,CAAC,CAAC;QACxF,MAAM,IAAI,sBAAsB,CAAC,8BAA8B,MAAM,EAAE,CAAC,CAAC;IAC3E,CAAC;AACH,CAAC;AAED,SAAS,OAAO,CAAC,OAAe;IAC9B,OAAO,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,IAAI,GAAG,OAAO,CAAC,CAAC,CAAC;AAC3D,CAAC;AAED,0BAA0B;AAC1B,MAAM,UAAU,oBAAoB,CAAC,KAAsB,EAAE,OAAe;IAC1E,MAAM,GAAG,GAAG,KAAK,CAAC,UAAU,IAAI,EAAE,CAAC;IACnC,IAAI,GAAG,KAAK,EAAE,EAAE,CAAC;QACf,MAAM,IAAI,sBAAsB,CAAC,YAAY,OAAO,mCAAmC,CAAC,CAAC;IAC3F,CAAC;IAED,MAAM,eAAe,GAAG,KAAK,CAAC,eAAe,IAAI,EAAE,CAAC;IACpD,IAAI,CAAC,eAAe,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;QACvC,MAAM,IAAI,sBAAsB,CAC9B,YAAY,OAAO,uBAAuB,eAAe,gCAAgC,CAC1F,CAAC;IACJ,CAAC;IAED,IACE,CAAC,2EAA2E,CAAC,IAAI,CAC/E,eAAe,CAChB,EACD,CAAC;QACD,MAAM,IAAI,sBAAsB,CAC9B,YAAY,OAAO,8CAA8C,eAAe,IAAI,CACrF,CAAC;IACJ,CAAC;IAED,MAAM,KAAK,GAAG,iBAAiB,CAAC,GAAG,CAAC,CAAC;IACrC,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,MAAM,IAAI,sBAAsB,CAC9B,YAAY,OAAO,qEAAqE;YACtF,wDAAwD,CAC3D,CAAC;IACJ,CAAC;IAED,OAAO;QACL,KAAK;QACL,eAAe,EAAE,eAAe,CAAC,KAAK,CAAC,CAAC,CAAC;QACzC,YAAY,EAAE,KAAK,CAAC,YAAY,IAAI,EAAE;KACvC,CAAC;AACJ,CAAC;AAED,6EAA6E;AAC7E,4CAA4C;AAC5C,SAAS,iBAAiB,CAAC,GAAW;IACpC,MAAM,IAAI,GAAG,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;IACjF,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,OAAO,SAAS,CAAC;IAC5C,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC5B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,MAAM,SAAS,GAAG,MAAoD,CAAC;IACvE,IAAI,SAAS,CAAC,QAAQ,KAAK,UAAU,IAAI,OAAO,SAAS,CAAC,OAAO,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IACjG,OAAO,SAAsB,CAAC;AAChC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export { diffLayouts, type DiffOptions, type LayoutReport } from "./diff.js";
+export { resolveLayout, resolveProxyLayout, proveLocalBuild, type ResolveOptions, type ProxyLayout, type LocalBuild, type LocalBuildResult, } from "./resolve.js";
+export { parseRecord, verifyRecord, type LayoutRecord } from "./record.js";
+export { readProxy, readImplementation, readCode, readChainId, type EthProvider, type ProxyState, } from "./chain.js";
+export { fetchVerifiedSource, ETHERSCAN_V2_API_URL, type ExplorerConfig, type VerifiedSource, } from "./explorer.js";
+export { getSolc, type SolcOptions, type SolcRunner } from "./solc.js";
+export { layoutFromSource } from "./reconstruct.js";
+export { compareDeployedBytecode, isProvingMatch, type DeployedBytecodeMatch, type ProvingMatch, type ImmutableReferences, } from "./bytecode.js";
+export { LayoutIntegrityError, LayoutUnavailableError } from "./errors.js";
+export type { SolcInput, StorageLayout } from "@openzeppelin/upgrades-core";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,KAAK,WAAW,EAAE,KAAK,YAAY,EAAE,MAAM,WAAW,CAAC;AAC7E,OAAO,EACL,aAAa,EACb,kBAAkB,EAClB,eAAe,EACf,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,gBAAgB,GACtB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,KAAK,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3E,OAAO,EACL,SAAS,EACT,kBAAkB,EAClB,QAAQ,EACR,WAAW,EACX,KAAK,WAAW,EAChB,KAAK,UAAU,GAChB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,mBAAmB,EACnB,oBAAoB,EACpB,KAAK,cAAc,EACnB,KAAK,cAAc,GACpB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,UAAU,EAAE,MAAM,WAAW,CAAC;AACvE,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EACL,uBAAuB,EACvB,cAAc,EACd,KAAK,qBAAqB,EAC1B,KAAK,YAAY,EACjB,KAAK,mBAAmB,GACzB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,oBAAoB,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAC3E,YAAY,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC"}

package/dist/index.js

@@ -0,0 +1,10 @@
+export { diffLayouts } from "./diff.js";
+export { resolveLayout, resolveProxyLayout, proveLocalBuild, } from "./resolve.js";
+export { parseRecord, verifyRecord } from "./record.js";
+export { readProxy, readImplementation, readCode, readChainId, } from "./chain.js";
+export { fetchVerifiedSource, ETHERSCAN_V2_API_URL, } from "./explorer.js";
+export { getSolc } from "./solc.js";
+export { layoutFromSource } from "./reconstruct.js";
+export { compareDeployedBytecode, isProvingMatch, } from "./bytecode.js";
+export { LayoutIntegrityError, LayoutUnavailableError } from "./errors.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAuC,MAAM,WAAW,CAAC;AAC7E,OAAO,EACL,aAAa,EACb,kBAAkB,EAClB,eAAe,GAKhB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,WAAW,EAAE,YAAY,EAAqB,MAAM,aAAa,CAAC;AAC3E,OAAO,EACL,SAAS,EACT,kBAAkB,EAClB,QAAQ,EACR,WAAW,GAGZ,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,mBAAmB,EACnB,oBAAoB,GAGrB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,OAAO,EAAqC,MAAM,WAAW,CAAC;AACvE,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EACL,uBAAuB,EACvB,cAAc,GAIf,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,oBAAoB,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC"}

package/dist/reconstruct.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 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 { type SolcInput, type StorageLayout } from "@openzeppelin/upgrades-core";
+import { type ProvingMatch } from "./bytecode.js";
+import type { VerifiedSource } from "./explorer.js";
+import type { SolcRunner } from "./solc.js";
+export interface ReconstructedLayout {
+    /** Fully qualified name, `source.sol:Contract`. */
+    contract: string;
+    compiler: string;
+    bytecodeMatch: ProvingMatch;
+    layout: StorageLayout;
+}
+export declare function reconstructLayout(source: VerifiedSource, solc: SolcRunner, onchainCode: string): Promise<ReconstructedLayout>;
+/**
+ * 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 declare function layoutFromSource(input: SolcInput, solc: SolcRunner, contract: string): Promise<StorageLayout>;
+//# sourceMappingURL=reconstruct.d.ts.map

package/dist/reconstruct.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reconstruct.d.ts","sourceRoot":"","sources":["../src/reconstruct.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAOL,KAAK,SAAS,EAEd,KAAK,aAAa,EACnB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAA2C,KAAK,YAAY,EAAE,MAAM,eAAe,CAAC;AAE3F,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAE5C,MAAM,WAAW,mBAAmB;IAClC,mDAAmD;IACnD,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,YAAY,CAAC;IAC5B,MAAM,EAAE,aAAa,CAAC;CACvB;AAoBD,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,cAAc,EACtB,IAAI,EAAE,UAAU,EAChB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,mBAAmB,CAAC,CAiB9B;AAED;;;;GAIG;AACH,wBAAsB,gBAAgB,CACpC,KAAK,EAAE,SAAS,EAChB,IAAI,EAAE,UAAU,EAChB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,aAAa,CAAC,CAIxB"}

package/dist/reconstruct.js

@@ -0,0 +1,140 @@
+/**
+ * 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 { getStorageLayout, isNamespaceSupported, makeNamespacedInput, solcInputOutputDecoder, trySanitizeNatSpec, validate, } from "@openzeppelin/upgrades-core";
+import { compareDeployedBytecode, isProvingMatch } from "./bytecode.js";
+import { LayoutIntegrityError } from "./errors.js";
+// 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, solc, onchainCode) {
+    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,
+        layout: await extractLayout(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, solc, contract) {
+    const selected = withOutputSelection(input, FULL_SELECTION);
+    const output = await compileOrThrow(solc, selected, "source");
+    return extractLayout(selected, output, solc, contract);
+}
+async function extractLayout(input, output, solc, contract) {
+    const solcVersion = solc.longVersion.split("+")[0];
+    let namespacedOutput;
+    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; 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);
+}
+/**
+ * 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, contractName, onchainCode, hashed) {
+    let candidates = 0;
+    let best;
+    let weak;
+    for (const [sourcePath, contracts] of Object.entries(output.contracts ?? {})) {
+        const compiled = contracts[contractName];
+        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) {
+    const metadata = input.settings.metadata;
+    return metadata?.appendCBOR !== false && metadata?.bytecodeHash !== "none";
+}
+async function compileOrThrow(solc, input, what) {
+    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, outputSelection) {
+    // upgrades-core's SolcInput type omits `language`, which standard json requires.
+    const { language } = input;
+    return {
+        language,
+        sources: input.sources,
+        settings: { ...input.settings, outputSelection },
+    };
+}
+//# sourceMappingURL=reconstruct.js.map

package/dist/reconstruct.js.map

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

package/dist/record.d.ts

@@ -0,0 +1,48 @@
+/**
+ * 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 { type ProvingMatch } from "./bytecode.js";
+import { type EthProvider } from "./chain.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;
+}
+/**
+ * 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 declare function parseRecord(value: unknown, address?: string): 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 declare function verifyRecord(provider: EthProvider, address: string, value: unknown): Promise<LayoutRecord>;
+//# sourceMappingURL=record.d.ts.map

package/dist/record.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"record.d.ts","sourceRoot":"","sources":["../src/record.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AACjE,OAAO,EAAkB,KAAK,YAAY,EAAE,MAAM,eAAe,CAAC;AAClE,OAAO,EAAqC,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AAGjF;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,CAAC,CAAC;IACV,iBAAiB;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,mDAAmD;IACnD,QAAQ,EAAE,MAAM,CAAC;IACjB,qCAAqC;IACrC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,YAAY,CAAC;IAC5B,+FAA+F;IAC/F,MAAM,EAAE,UAAU,GAAG,eAAe,CAAC;IACrC,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,aAAa,CAAC;CACvB;AAKD;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,YAAY,CA0C1E;AAED;;;;GAIG;AACH,wBAAsB,YAAY,CAChC,QAAQ,EAAE,WAAW,EACrB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,OAAO,GACb,OAAO,CAAC,YAAY,CAAC,CA0BvB"}

package/dist/record.js

@@ -0,0 +1,91 @@
+/**
+ * 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 { isProvingMatch } from "./bytecode.js";
+import { codeSha256, readChainId, readCode } from "./chain.js";
+import { LayoutIntegrityError, LayoutUnavailableError } from "./errors.js";
+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, address) {
+    if (typeof value !== "object" || value === null) {
+        throw new LayoutIntegrityError("A layout record must be a JSON object.");
+    }
+    const r = value;
+    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) => 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 <= 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;
+}
+/**
+ * `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, address, value) {
+    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;
+    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;
+}
+//# sourceMappingURL=record.js.map

package/dist/record.js.map

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

package/dist/resolve.d.ts

@@ -0,0 +1,54 @@
+/**
+ * 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 type { StorageLayout } from "@openzeppelin/upgrades-core";
+import { type DeployedBytecodeMatch, type ImmutableReferences } from "./bytecode.js";
+import { type EthProvider } from "./chain.js";
+import { type ExplorerConfig } from "./explorer.js";
+import { type LayoutRecord } from "./record.js";
+import { type SolcOptions } from "./solc.js";
+export interface ResolveOptions {
+    explorer: ExplorerConfig;
+    solc?: SolcOptions;
+}
+/**
+ * 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 declare function resolveLayout(provider: EthProvider, address: string, options: ResolveOptions): Promise<LayoutRecord>;
+export interface ProxyLayout {
+    /** The implementation the proxy runs now. */
+    implementation: string;
+    /** Set for a beacon proxy. */
+    beacon?: string;
+    record: LayoutRecord;
+}
+/** `resolveLayout` for whatever implementation `proxy` runs right now (ERC-1967 or beacon). */
+export declare function resolveProxyLayout(provider: EthProvider, proxy: string, options: ResolveOptions): Promise<ProxyLayout>;
+export interface LocalBuild {
+    /** Fully qualified name, `source.sol:Contract`. */
+    contract: string;
+    compiler?: string;
+    layout: StorageLayout;
+    deployedBytecode: string;
+    immutableReferences?: ImmutableReferences;
+}
+export interface LocalBuildResult {
+    bytecodeMatch: DeployedBytecodeMatch;
+    /** Set only when the match proves the layout (`exact` or `immutables-only`). */
+    record?: LayoutRecord;
+}
+/**
+ * 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 declare function proveLocalBuild(provider: EthProvider, address: string, build: LocalBuild): Promise<LocalBuildResult>;
+//# sourceMappingURL=resolve.d.ts.map

package/dist/resolve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../src/resolve.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AACjE,OAAO,EAGL,KAAK,qBAAqB,EAC1B,KAAK,mBAAmB,EACzB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAgD,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AAE5F,OAAO,EAAyC,KAAK,cAAc,EAAE,MAAM,eAAe,CAAC;AAE3F,OAAO,EAAe,KAAK,YAAY,EAAE,MAAM,aAAa,CAAC;AAC7D,OAAO,EAAW,KAAK,WAAW,EAAE,MAAM,WAAW,CAAC;AAEtD,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,cAAc,CAAC;IACzB,IAAI,CAAC,EAAE,WAAW,CAAC;CACpB;AAED;;;;GAIG;AACH,wBAAsB,aAAa,CACjC,QAAQ,EAAE,WAAW,EACrB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,YAAY,CAAC,CAyBvB;AAED,MAAM,WAAW,WAAW;IAC1B,6CAA6C;IAC7C,cAAc,EAAE,MAAM,CAAC;IACvB,8BAA8B;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,YAAY,CAAC;CACtB;AAED,+FAA+F;AAC/F,wBAAsB,kBAAkB,CACtC,QAAQ,EAAE,WAAW,EACrB,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,WAAW,CAAC,CAStB;AAED,MAAM,WAAW,UAAU;IACzB,mDAAmD;IACnD,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,aAAa,CAAC;IACtB,gBAAgB,EAAE,MAAM,CAAC;IACzB,mBAAmB,CAAC,EAAE,mBAAmB,CAAC;CAC3C;AAED,MAAM,WAAW,gBAAgB;IAC/B,aAAa,EAAE,qBAAqB,CAAC;IACrC,gFAAgF;IAChF,MAAM,CAAC,EAAE,YAAY,CAAC;CACvB;AAED;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,QAAQ,EAAE,WAAW,EACrB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,UAAU,GAChB,OAAO,CAAC,gBAAgB,CAAC,CAwB3B"}