slotdiff 0.0.0-stage → 0.2.0-alpha.1

package/dist/build-info.js

@@ -0,0 +1,319 @@
+/**
+ * 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 { readFile, readdir, stat } from "node:fs/promises";
+import { isAbsolute, join, relative, resolve } from "node:path";
+// 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`.";
+/**
+ * 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, contract, options = {}) {
+    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;
+        try {
+            text = await readFile(file, "utf8");
+        }
+        catch (e) {
+            throw new Error(`Cannot read ${options.file} (${e.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 = [];
+    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 = [];
+    const stale = [];
+    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();
+    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]);
+}
+function parseTarget(contract) {
+    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) {
+    const files = [];
+    for (const dir of DIRS) {
+        let entries;
+        try {
+            entries = await readdir(resolve(root, dir));
+        }
+        catch (e) {
+            if (e.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, text) {
+    let info;
+    try {
+        info = JSON.parse(text);
+    }
+    catch (e) {
+        throw new Error(`${file} is not JSON: ${e.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")).output;
+        }
+        catch (e) {
+            if (e.code !== "ENOENT") {
+                throw new Error(`Cannot read ${outputFile}: ${e.message}`, { cause: e });
+            }
+        }
+    }
+    return info;
+}
+// Fully qualified names in `info` that match the target.
+function findContract(info, target) {
+    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, { info, contract }) {
+    const targetSource = sourceOf(contract);
+    let target;
+    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, source) {
+    // 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, info, source) {
+    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) {
+    for (const path of paths) {
+        try {
+            return await readFile(path, "utf8");
+        }
+        catch (e) {
+            const code = e.code;
+            if (code !== "ENOENT" && code !== "ENOTDIR")
+                throw e;
+        }
+    }
+    return undefined;
+}
+function buildKey(info) {
+    const settings = { ...info.input.settings };
+    delete settings.outputSelection;
+    return JSON.stringify([info.solcLongVersion, settings]);
+}
+function ambiguousName(contract, names) {
+    return new Error(`${contract} is ambiguous: ${names.join(", ")}. Use \`path/File.sol:Name\`.`);
+}
+function sourceOf(contract) {
+    return contract.slice(0, contract.lastIndexOf(":"));
+}
+function toResult({ file, info, contract }) {
+    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,
+    };
+}
+//# sourceMappingURL=build-info.js.map

package/dist/build-info.js.map

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

package/dist/bytecode.d.ts

@@ -0,0 +1,46 @@
+/**
+ * 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 declare function stripBytecodeMetadata(bytecode: string): string;
+/**
+ * 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 declare function isProvingMatch(match: DeployedBytecodeMatch): match is ProvingMatch;
+/**
+ * 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 declare function compareDeployedBytecode(onchain: string, compiled: string, immutableReferences?: ImmutableReferences): DeployedBytecodeMatch;
+//# sourceMappingURL=bytecode.d.ts.map

package/dist/bytecode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bytecode.d.ts","sourceRoot":"","sources":["../src/bytecode.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAK9D;AA8CD;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAAG,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC,CAAC;AAEnG;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,qBAAqB,GAC/B,OAAO,GAAG,iBAAiB,GAAG,eAAe,GAAG,WAAW,GAAG,MAAM,CAAC;AAEvE,qFAAqF;AACrF,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,iBAAiB,CAAC;AAEvD,wBAAgB,cAAc,CAAC,KAAK,EAAE,qBAAqB,GAAG,KAAK,IAAI,YAAY,CAElF;AAKD;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,mBAAmB,GAAE,mBAAwB,GAC5C,qBAAqB,CAoBvB"}

package/dist/bytecode.js

@@ -0,0 +1,101 @@
+/**
+ * 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) {
+    const buf = toBuffer(bytecode);
+    const start = cborStart(buf);
+    if (start === undefined)
+        return bytecode;
+    return "0x" + buf.subarray(0, start).toString("hex");
+}
+function toBuffer(bytecode) {
+    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) {
+    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) {
+    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) {
+    return s.toLowerCase().replace(/^0x/, "");
+}
+export function isProvingMatch(match) {
+    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, compiled, immutableReferences = {}) {
+    const live = normalize(onchain);
+    const built = normalize(compiled);
+    if (live === "" || built === "")
+        return "none";
+    if (live === built)
+        return hasSourceHash(built) ? "exact" : "code-only";
+    const spans = 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, spans) {
+    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");
+}
+//# sourceMappingURL=bytecode.js.map

package/dist/bytecode.js.map

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

package/dist/chain.d.ts

@@ -0,0 +1,20 @@
+/** 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 declare function readProxy(provider: EthProvider, address: string): Promise<ProxyState | undefined>;
+export declare function readImplementation(provider: EthProvider, proxy: string): Promise<string>;
+export declare function readCode(provider: EthProvider, address: string): Promise<string>;
+export declare function readChainId(provider: EthProvider): Promise<number>;
+export declare function codeSha256(code: string): string;
+//# sourceMappingURL=chain.d.ts.map

package/dist/chain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chain.d.ts","sourceRoot":"","sources":["../src/chain.ts"],"names":[],"mappings":"AAWA,qGAAqG;AACrG,MAAM,WAAW,WAAW;IAC1B,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC3D;AAED,MAAM,WAAW,UAAU;IACzB,cAAc,EAAE,MAAM,CAAC;IACvB,qEAAqE;IACrE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,wBAAsB,SAAS,CAC7B,QAAQ,EAAE,WAAW,EACrB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC,CAgBjC;AAED,wBAAsB,kBAAkB,CAAC,QAAQ,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAQ9F;AAED,wBAAsB,QAAQ,CAAC,QAAQ,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAMtF;AAED,wBAAsB,WAAW,CAAC,QAAQ,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,CAExE;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAI/C"}

package/dist/chain.js

@@ -0,0 +1,52 @@
+import { EIP1967BeaconNotFound, EIP1967ImplementationNotFound, getBeaconAddress, getImplementationAddress, getImplementationAddressFromBeacon, } from "@openzeppelin/upgrades-core";
+import { createHash } from "node:crypto";
+import { LayoutUnavailableError } from "./errors.js";
+/**
+ * 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, address) {
+    const oz = provider;
+    try {
+        return { implementation: (await getImplementationAddress(oz, address)).toLowerCase() };
+    }
+    catch (e) {
+        if (!(e instanceof EIP1967ImplementationNotFound))
+            throw e;
+    }
+    let beacon;
+    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, proxy) {
+    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, address) {
+    const code = (await provider.send("eth_getCode", [address, "latest"]));
+    if (code === "0x" || code === "") {
+        throw new LayoutUnavailableError(`No code at ${address} on this chain.`);
+    }
+    return code.toLowerCase();
+}
+export async function readChainId(provider) {
+    return Number(BigInt((await provider.send("eth_chainId", []))));
+}
+export function codeSha256(code) {
+    return createHash("sha256")
+        .update(Buffer.from(code.replace(/^0x/, ""), "hex"))
+        .digest("hex");
+}
+//# sourceMappingURL=chain.js.map

package/dist/chain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chain.js","sourceRoot":"","sources":["../src/chain.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,qBAAqB,EACrB,6BAA6B,EAC7B,gBAAgB,EAChB,wBAAwB,EACxB,kCAAkC,GAEnC,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAarD;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,QAAqB,EACrB,OAAe;IAEf,MAAM,EAAE,GAAG,QAAuC,CAAC;IACnD,IAAI,CAAC;QACH,OAAO,EAAE,cAAc,EAAE,CAAC,MAAM,wBAAwB,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC;IACzF,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,IAAI,CAAC,CAAC,CAAC,YAAY,6BAA6B,CAAC;YAAE,MAAM,CAAC,CAAC;IAC7D,CAAC;IACD,IAAI,MAAc,CAAC;IACnB,IAAI,CAAC;QACH,MAAM,GAAG,CAAC,MAAM,gBAAgB,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;IAC/D,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,IAAI,CAAC,YAAY,qBAAqB;YAAE,OAAO,SAAS,CAAC;QACzD,MAAM,CAAC,CAAC;IACV,CAAC;IACD,MAAM,cAAc,GAAG,CAAC,MAAM,kCAAkC,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;IAC5F,OAAO,EAAE,cAAc,EAAE,MAAM,EAAE,CAAC;AACpC,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,QAAqB,EAAE,KAAa;IAC3E,MAAM,KAAK,GAAG,MAAM,SAAS,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;IAC/C,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,MAAM,IAAI,sBAAsB,CAC9B,GAAG,KAAK,mEAAmE,CAC5E,CAAC;IACJ,CAAC;IACD,OAAO,KAAK,CAAC,cAAc,CAAC;AAC9B,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,QAAqB,EAAE,OAAe;IACnE,MAAM,IAAI,GAAG,CAAC,MAAM,QAAQ,CAAC,IAAI,CAAC,aAAa,EAAE,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAW,CAAC;IACjF,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,EAAE,EAAE,CAAC;QACjC,MAAM,IAAI,sBAAsB,CAAC,cAAc,OAAO,iBAAiB,CAAC,CAAC;IAC3E,CAAC;IACD,OAAO,IAAI,CAAC,WAAW,EAAE,CAAC;AAC5B,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,QAAqB;IACrD,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,MAAM,QAAQ,CAAC,IAAI,CAAC,aAAa,EAAE,EAAE,CAAC,CAAW,CAAC,CAAC,CAAC;AAC5E,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,IAAY;IACrC,OAAO,UAAU,CAAC,QAAQ,CAAC;SACxB,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,EAAE,KAAK,CAAC,CAAC;SACnD,MAAM,CAAC,KAAK,CAAC,CAAC;AACnB,CAAC"}

package/dist/cli.d.ts

@@ -0,0 +1,25 @@
+/**
+ * `slotdiff <old> <new>`: each side is a contract in the project's build info
+ * or an address: a proxy (read as the implementation it runs now) or an
+ * implementation.
+ *
+ * Exit codes: 0 every check ran and passed (or was skipped with --no-safety),
+ * 1 a check failed, 2 something could not be checked. Failing to check is
+ * never reported as compatible.
+ */
+type FetchLike = (url: string, init: RequestInit) => Promise<Response>;
+export interface CliIo {
+    stdout: (line: string) => void;
+    stderr: (line: string) => void;
+    cwd?: string;
+    env?: Record<string, string | undefined>;
+    fetch?: FetchLike;
+    /** stdout is an interactive terminal: show the banner. */
+    tty?: boolean;
+    /** stdout takes colors (Node's rules: a terminal, `NO_COLOR`, `FORCE_COLOR`). */
+    color?: boolean;
+}
+/** Runs the CLI and resolves to its exit code. */
+export declare function run(argv: string[], io: CliIo): Promise<number>;
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAoEH,KAAK,SAAS,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;AAEvE,MAAM,WAAW,KAAK;IACpB,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACzC,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,0DAA0D;IAC1D,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,iFAAiF;IACjF,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAUD,kDAAkD;AAClD,wBAAsB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,CAsPpE"}