slotdiff 0.1.0-alpha.1 → 0.2.0-alpha.1

package/CHANGELOG.md

@@ -1,19 +1,26 @@
 # Changelog
 
+## 0.2.0-alpha.1
+
+- CLI: `slotdiff <old> <new>`, where each side is a contract in your build info or an address (a proxy, read as what it runs now, or an implementation; needs `--rpc` and `ETHERSCAN_API_KEY`). Checks the storage layout, the ERC-7201 slots and OpenZeppelin's safety rules for `<new>`, with the proxy kind taken from `<old>`'s implementation, so a UUPS implementation missing `upgradeToAndCall` fails. Exits 0 when every check passed, 1 when one failed, 2 when something could not be checked. `ETHERSCAN_API_KEY` is sent only to Etherscan, never to `--explorer-url`.
+- `findBuildInfo`: reads Foundry, Hardhat 2 and Hardhat 3 build info. The build is chosen by content: only one whose target and imports still match the files on disk, so the stale files Foundry keeps after each edit are never used. Its `input` holds only what the target imports.
+- ERC-7201 namespaces are compared by the slot the code really uses, not only the annotation: a namespace whose slot moves fails, whatever the annotations say, and a corrected annotation over an unchanged slot passes (`SourceAnalysis.namespaces`, `checkNamespaces`).
+- `analyzeSource`: `layoutFromSource` plus OpenZeppelin's safety check from one compile, as the CLI runs it; `safety({ kind })` takes the proxy kind being upgraded.
+- Explorer errors no longer repeat fetch's error text, which can quote the request URL and with it the API key.
+- CLI colors and a banner on an interactive terminal only (on runs, `--help` and `--version`); in a pipe or CI the output stays plain and `--version` prints just the version. `NO_COLOR` and `FORCE_COLOR` are honored. Built on Node's `util.styleText`, so no new dependency.
+- **Breaking:** Node 22.13+ (was 22.12+), for `util.styleText`'s terminal detection.
+- Releases are published from GitHub Actions through npm trusted publishing, staged for a maintainer's 2FA approval, with a provenance attestation linking each version to its commit.
+- `SECURITY.md`: how to report a vulnerability privately, and what slotdiff touches (network, processes, files, environment). The README and `--help` now say plainly that a pass is no guarantee and that slotdiff comes without warranty.
+
 ## 0.1.0-alpha.1
 
 First release.
 
-- `resolveProxyLayout` / `resolveLayout`: the storage layout of the code a proxy (ERC-1967 or
-  beacon) runs now, rebuilt from verified standard-json source on any Etherscan-compatible explorer
-  and proven against the deployed code.
+- `resolveProxyLayout` / `resolveLayout`: the storage layout of the code a proxy (ERC-1967 or beacon) runs now, rebuilt from verified standard-json source on any Etherscan-compatible explorer and proven against the deployed code.
 - `proveLocalBuild`: a layout record from your own build, only when it is the deployed build.
 - `diffLayouts`: OpenZeppelin's storage comparison, including ERC-7201 namespaced storage.
-- `LayoutRecord`s are plain JSON that slotdiff never writes. Load them back with `verifyRecord`
-  (checked against the chain id and deployed code) or `parseRecord` (offline).
-- A match proves a layout only when the build embeds solc's metadata hash. Builds with
-  `bytecodeHash: "none"` or `appendCBOR: false` are reported as `code-only` and refused.
-- `getSolc`: native solc from a cache (Hardhat's included) or a checksum-verified download.
-  Accepts release versions such as `0.8.24`, as Foundry's build info records them.
+- `LayoutRecord`s are plain JSON that slotdiff never writes. Load them back with `verifyRecord` (checked against the chain id and deployed code) or `parseRecord` (offline).
+- A match proves a layout only when the build embeds solc's metadata hash. Builds with `bytecodeHash: "none"` or `appendCBOR: false` are reported as `code-only` and refused.
+- `getSolc`: native solc from a cache (Hardhat's included) or a checksum-verified download. Accepts release versions such as `0.8.24`, as Foundry's build info records them.
 - `layoutFromSource` accepts build-info input from Foundry and Hardhat.
 - Loads from ESM and CommonJS. Node 22.12+.

package/README.md

@@ -1,30 +1,39 @@
 # slotdiff
 
-Storage layout diff for upgradeable Solidity contracts, where either side can be a local build or
-the code a proxy actually runs on chain.
+[![npm](https://img.shields.io/npm/v/slotdiff)](https://www.npmjs.com/package/slotdiff) [![CI](https://github.com/rokso/slotdiff/actions/workflows/ci.yml/badge.svg)](https://github.com/rokso/slotdiff/actions/workflows/ci.yml) [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/rokso/slotdiff/badge)](https://scorecard.dev/viewer/?uri=github.com/rokso/slotdiff) [![License: MIT](https://img.shields.io/npm/l/slotdiff)](LICENSE)
+
+Storage layout diff for upgradeable Solidity contracts, where either side can be a local build or the code a proxy actually runs on chain.
+
+```sh
+npx slotdiff 0xProxy src/Vault.sol:Vault --rpc $RPC_URL   # what the proxy runs vs your build
+```
+
+For example, two local versions:
 
-```ts
-const live = await resolveProxyLayout(provider, proxy, { explorer: { apiKey } });
-const report = diffLayouts(
-  live.record.layout,
-  await layoutFromSource(input, solc, "src/Vault.sol:Vault"),
-);
-if (!report.ok) console.log(report.explain());
+```
+$ npx slotdiff src/Vault.sol:Vault src/VaultBad.sol:VaultBad
+old  src/Vault.sol:Vault
+     out/build-info/90f317b6c0a81633.json
+new  src/VaultBad.sol:VaultBad
+     out/build-info/90f317b6c0a81633.json
+
+✗ Storage layout   incompatible
+    src/VaultBad.sol:4: Inserted `inserted`
+      > New variables should be placed after all existing inherited variables
+✓ Safety rules     no problems found (transparent proxy)
+
+Not safe to upgrade: the storage layout is incompatible.
 ```
 
 ## Why
 
-An upgrade is only safe relative to what the proxy runs **now**. Under lazy or multisig-queued
-upgrades that is often not your latest build, and the tools you have compare the wrong thing:
+An upgrade is only safe relative to what the proxy runs **now**. Under lazy or multisig-queued upgrades that is often not your latest build, and the tools you have compare the wrong thing:
 
 - OpenZeppelin's `validate` compares two local builds. It has no way to know what is live.
 - `cast storage <address>` prints a live layout but does not compare it with anything.
 - Deployment artifacts describe the last build you deployed, not necessarily what the proxy runs.
 
-slotdiff reads the implementation behind the proxy, rebuilds its layout from verified source, and
-**proves** that source compiles to the deployed code before trusting it. It then compares with
-OpenZeppelin's own rules, including ERC-7201 namespaced storage. Framework-agnostic: Foundry,
-Hardhat 2 and 3, or a plain script.
+slotdiff reads the implementation behind the proxy, rebuilds its layout from verified source, and **proves** that source compiles to the deployed code before trusting it. It then compares with OpenZeppelin's own rules, including ERC-7201 namespaced storage. Framework-agnostic: Foundry, Hardhat 2 and 3, or a plain script.
 
 ## Install
 
@@ -32,16 +41,94 @@ Hardhat 2 and 3, or a plain script.
 npm install slotdiff
 ```
 
-Node 22.12+. Works from ESM and CommonJS.
+Node 22.13+. Works from ESM and CommonJS.
+
+## Command line
+
+```sh
+slotdiff <old> <new> [--rpc <url>]
+```
+
+Each side is a contract in your build info (`src/Vault.sol:Vault`, or just `Vault` when only one contract has that name) or an address: a proxy, read as the implementation it runs now, or an implementation, such as one waiting in a multisig queue. Any mix works. An address needs `--rpc` and `ETHERSCAN_API_KEY` (or `--explorer-url` for another explorer), since its source comes from the explorer. The RPC is a flag because it picks the chain for each run; the key lives in the environment because one Etherscan key covers every chain. It is sent only to Etherscan: with `--explorer-url`, put that explorer's own key in the URL's query if it needs one.
+
+A local side is read from the build info your tool already wrote; slotdiff does not compile your project. Build first, from the project root or with `--root`. Foundry writes build info only with `build_info = true` in `foundry.toml` or `forge build --build-info`. A build older than the sources on disk is refused, never used. `--build-info <file>` names one build-info file to use as is, such as a CI artifact from another checkout; the output then says it was not compared with the sources on disk.
+
+Three checks run:
+
+- **Storage layout**, by OpenZeppelin's rules, as above, with ERC-7201 namespaces matched by the slot the code really uses.
+- **ERC-7201 slots**: each namespace keeps its data in place and `<new>`'s annotations match its code (see below).
+- **Safety rules** for `<new>`, OpenZeppelin's checks that it can run behind a proxy: constructors, `selfdestruct`, `delegatecall`, initial values, immutables and initializers (an initializer order problem is only a warning, as in OpenZeppelin). Source exceptions (`@custom:oz-upgrades-unsafe-allow`) are honored, and `--unsafe-allow <kinds>` accepts more. For an address, the verified source is checked. `--no-safety` skips it.
+
+OpenZeppelin matches ERC-7201 namespaces by their `@custom:storage-location erc7201:<id>` annotation alone. slotdiff also reads the slot the code assigns (`assembly { $.slot := LOCATION }`, with `LOCATION` a hex constant, the ERC-7201 formula, or `erc7201("id")`) and compares namespaces by that slot. The check fails when `<new>` would read a namespace from another slot than the deployed code wrote it to, whatever the annotations say, and when an annotation in `<new>` disagrees with its code. In `<old>`, already deployed, a disagreement is reported and the namespace is matched by its real slot, so correcting a wrong annotation is not reported as a deleted namespace. A slot slotdiff cannot read (computed at run time, say) means the upgrade could not be checked: exit code 2.
+
+For example, after correcting an annotation that never matched the deployed code:
+
+```
+ERC-7201 namespaces
+       annotation           slot from annotation   slot in code
+  old  example.vault        0xd192…a100            0x0d90…d100    ✗ annotation does not match code
+  new  example.vault.real   0x0d90…d100            0x0d90…d100    ✓
+       Same slot in code on both sides: the storage did not move. Compared as one namespace.
+
+✓ Storage layout   compatible
+✓ ERC-7201 slots   compared by the slot in code (see above)
+✓ Safety rules     no problems found (transparent proxy)
+
+Safe to upgrade.
+```
+
+Changing the constant to match the wrong annotation instead would move the data:
+
+```
+ERC-7201 namespaces
+       annotation      slot from annotation   slot in code
+  old  example.vault   0xd192…a100            0x0d90…d100    ✗ annotation does not match code
+  new  example.vault   0xd192…a100            0xd192…a100    ✓
+       The new code moves this namespace from 0x0d90…d100 to 0xd192…a100: its data would be left behind. Keep the slot the deployed code uses, under an annotation that matches it.
+
+✓ Storage layout   compatible
+✗ ERC-7201 slots   problems found in <new> (see above)
+✓ Safety rules     no problems found (transparent proxy)
+
+Not safe to upgrade: an ERC-7201 namespace fails the slot check.
+```
+
+The proxy kind comes from `<old>`'s implementation: UUPS when it has `upgradeTo` or `upgradeToAndCall`, beacon for a beacon proxy, transparent otherwise. So a UUPS implementation that lost its upgrade function, which would leave the proxy unable to upgrade again, is caught:
+
+```
+$ npx slotdiff src/UupsV1.sol:UupsV1 src/UupsV2Lost.sol:UupsV2Lost
+old  src/UupsV1.sol:UupsV1
+     out/build-info/fb5d5362dc531baa.json
+new  src/UupsV2Lost.sol:UupsV2Lost
+     out/build-info/fb5d5362dc531baa.json
+
+✓ Storage layout   compatible
+✗ Safety rules     problems found (uups proxy)
+    src/UupsV2Lost.sol:3: Implementation is missing a public `upgradeTo(address)` or `upgradeToAndCall(address,bytes)` function
+        Inherit UUPSUpgradeable to include one or both of these functions in your contract
+        @openzeppelin/contracts-upgradeable/proxy/utils/UUPSUpgradeable.sol
+        https://zpl.in/upgrades/error-008
+
+Not safe to upgrade: <new> breaks the safety rules.
+```
+
+Exit codes: `0` every check ran and passed (or was skipped with `--no-safety`), `1` a check failed, `2` something could not be checked (never reported as compatible). `slotdiff --help` lists every option.
+
+Colors and the banner appear only on an interactive terminal, never in a pipe, a log or CI. `NO_COLOR` turns colors off; `FORCE_COLOR` turns them on, for CI logs that render them.
 
 ## Usage
 
 ### Live proxy vs a local build
 
 ```ts
-import { readFileSync } from "node:fs";
 import { JsonRpcProvider } from "ethers";
-import { diffLayouts, getSolc, layoutFromSource, resolveProxyLayout } from "slotdiff";
+import {
+  diffLayouts,
+  findBuildInfo,
+  getSolc,
+  layoutFromSource,
+  resolveProxyLayout,
+} from "slotdiff";
 
 // Any object with send(method, params): an ethers JsonRpcProvider or Hardhat's network provider.
 const provider = new JsonRpcProvider(process.env.RPC_URL);
@@ -50,10 +137,10 @@ const apiKey = process.env.ETHERSCAN_API_KEY;
 // 1. The layout of whatever the proxy runs now, proven against its deployed code.
 const live = await resolveProxyLayout(provider, "0xProxy", { explorer: { apiKey } });
 
-// 2. The layout of the new version, from your build info (see below for each tool).
-const buildInfo = JSON.parse(readFileSync("out/build-info/<id>.json", "utf8"));
-const solc = await getSolc(buildInfo.solcLongVersion);
-const next = await layoutFromSource(buildInfo.input, solc, "src/Vault.sol:Vault");
+// 2. The layout of the new version, from your build info (Foundry, Hardhat 2 or 3).
+const build = await findBuildInfo(process.cwd(), "src/Vault.sol:Vault");
+const solc = await getSolc(build.solcVersion);
+const next = await layoutFromSource(build.input, solc, build.contract);
 
 // 3. Compare.
 const report = diffLayouts(live.record.layout, next);
@@ -63,15 +150,15 @@ if (!report.ok) {
 }
 ```
 
-Where the build info lives:
+`findBuildInfo` picks the build whose sources still match the files on disk, so the stale build info Foundry keeps after each edit is never used, and its `input` holds only the target and what it imports. Pass `{ file }` to use one file as is (for example a CI artifact). Where the build info lives:
 
-| Tool      | Build info                                                                                             | Contract name                       |
-| --------- | ------------------------------------------------------------------------------------------------------ | ----------------------------------- |
-| Foundry   | `out/build-info/*.json`, only with `build_info = true` in `foundry.toml` or `forge build --build-info` | `src/Vault.sol:Vault`               |
-| Hardhat 2 | `artifacts/build-info/*.json`                                                                          | `contracts/Vault.sol:Vault`         |
-| Hardhat 3 | `artifacts/build-info/<id>.json`; the compiler output is in `<id>.output.json` next to it              | `project/contracts/Vault.sol:Vault` |
+| Tool | Build info | Contract name |
+| --- | --- | --- |
+| Foundry | `out/build-info/*.json`, only with `build_info = true` in `foundry.toml` or `forge build --build-info` | `src/Vault.sol:Vault` |
+| Hardhat 2 | `artifacts/build-info/*.json` | `contracts/Vault.sol:Vault` |
+| Hardhat 3 | `artifacts/build-info/<id>.json`; the compiler output is in `<id>.output.json` next to it | `project/contracts/Vault.sol:Vault` |
 
-Each holds `input` and `solcLongVersion`. Use the source name exactly as it appears in `input.sources`.
+With `findBuildInfo`, Hardhat 3's `project/` prefix is optional.
 
 `explain()` gives OpenZeppelin's report, for example:
 
@@ -80,14 +167,36 @@ src/Vault.sol:7: Inserted `inserted`
   > New variables should be placed after all existing inherited variables
 ```
 
-The explorer defaults to Etherscan's v2 API, where one key covers every chain it indexes. For another
-Etherscan-compatible explorer, such as Blockscout, pass `{ apiUrl }` (a key is optional there).
+The explorer defaults to Etherscan's v2 API, where one key covers every chain it indexes. For another Etherscan-compatible explorer, such as Blockscout, pass `{ apiUrl }` (a key is optional there).
+
+### Safety rules and ERC-7201 slots too
+
+`analyzeSource` is `layoutFromSource` plus OpenZeppelin's safety check and the slot each ERC-7201 namespace really uses, from one compile, as the command line runs them. Pass the kind of the proxy being upgraded, not the new contract's own: a UUPS implementation that lost its upgrade function would otherwise look transparent and pass.
+
+```ts
+import { analyzeSource, checkNamespaces, diffLayouts, findBuildInfo, getSolc } from "slotdiff";
+
+async function analyze(contract: string) {
+  const build = await findBuildInfo(process.cwd(), contract);
+  return analyzeSource(build.input, await getSolc(build.solcVersion), build.contract);
+}
+const old = await analyze("src/Vault.sol:Vault");
+const next = await analyze("src/VaultV2.sol:VaultV2");
+
+// Pair ERC-7201 namespaces by the slot the code uses, as the command line does.
+const slots = checkNamespaces(old, next); // result: "pass", "fail" or "unread"
+const layout = diffLayouts(slots.layout, next.layout);
+const safety = next.safety({ kind: old.kind }); // the kind of the proxy being upgraded
+if (!layout.ok || slots.result !== "pass" || !safety.ok) {
+  console.error(layout.explain(), slots.pairs, safety.explain());
+}
+```
+
+`safety` also takes `unsafeAllow` (error kinds to accept, listed in `SAFETY_ERROR_KINDS`), on top of `@custom:oz-upgrades-unsafe-allow` in the source.
 
 ### Keep records, skip the rebuild next time
 
-Rebuilding means fetching source and compiling. A `LayoutRecord` is plain JSON: store it wherever
-suits you (committed next to your deployments, a CI cache) and load it back with `verifyRecord`,
-which refuses it unless this chain still runs the exact code it was proven against.
+Rebuilding means fetching source and compiling. A `LayoutRecord` is plain JSON: store it wherever suits you (committed next to your deployments, a CI cache) and load it back with `verifyRecord`, which refuses it unless this chain still runs the exact code it was proven against.
 
 ```ts
 import { readFileSync, writeFileSync } from "node:fs";
@@ -105,109 +214,91 @@ try {
 }
 ```
 
-Key records by **implementation**, and read the implementation from the proxy every time. A record
-for an old implementation still verifies after the proxy is upgraded, because that code is still
-deployed at its own address.
+Key records by **implementation**, and read the implementation from the proxy every time. A record for an old implementation still verifies after the proxy is upgraded, because that code is still deployed at its own address.
 
-Without an RPC, `parseRecord(value, address)` checks a record's shape and proof offline. It cannot
-tell whether the proxy has moved on, so prefer `verifyRecord` whenever you can reach the chain.
+Without an RPC, `parseRecord(value, address)` checks a record's shape and proof offline. It cannot tell whether the proxy has moved on, so prefer `verifyRecord` whenever you can reach the chain.
 
-A record is bound to the deployed code, not to its own `layout` field: an edited layout in a saved
-record still verifies. Treat saved records as trusted input and review changes to them like code.
+A record is bound to the deployed code, not to its own `layout` field: an edited layout in a saved record still verifies. Treat saved records as trusted input and review changes to them like code.
 
 ### No explorer: prove your own build
 
-If you deployed it yourself, your build can serve as the source. `proveLocalBuild` compares the
-deployed code with your compiler output and returns a record only when they prove to be the same
-build.
+If you deployed it yourself, your build can serve as the source. `proveLocalBuild` compares the deployed code with your compiler output and returns a record only when they prove to be the same build.
 
 ```ts
-import { proveLocalBuild } from "slotdiff";
+import { findBuildInfo, getSolc, layoutFromSource, proveLocalBuild } from "slotdiff";
 
-// Hardhat 3: read `output` from `<id>.output.json` instead.
-const compiled = buildInfo.output.contracts["src/Vault.sol"].Vault.evm.deployedBytecode;
+const build = await findBuildInfo(process.cwd(), "src/Vault.sol:Vault");
+const solc = await getSolc(build.solcVersion);
 const { bytecodeMatch, record } = await proveLocalBuild(provider, impl, {
-  contract: "src/Vault.sol:Vault",
+  contract: build.contract,
   compiler: solc.longVersion,
-  layout: await layoutFromSource(buildInfo.input, solc, "src/Vault.sol:Vault"),
-  deployedBytecode: compiled.object,
-  immutableReferences: compiled.immutableReferences,
+  layout: await layoutFromSource(build.input, solc, build.contract),
+  deployedBytecode: build.deployedBytecode!,
+  immutableReferences: build.immutableReferences,
 });
 if (record === undefined) throw new Error(`Not the deployed build (${bytecodeMatch})`);
 ```
 
 ## What counts as proof
 
-A layout is only trusted when the compiled code matches the deployed code as `exact` or
-`immutables-only` (identical once immutables and library addresses are masked), **and** the build
-embeds solc's metadata hash. That hash covers every source file and setting, so matching code then
-means matching source.
+A layout is only trusted when the compiled code matches the deployed code as `exact` or `immutables-only` (identical once immutables and library addresses are masked), **and** the build embeds solc's metadata hash. That hash covers every source file and setting, so matching code then means matching source.
 
-Anything weaker is refused, because variables no code reads, retyped fields and gap sizes never
-reach the bytecode, so a different layout can compile to the same code:
+Anything weaker is refused, because variables no code reads, retyped fields and gap sizes never reach the bytecode, so a different layout can compile to the same code:
 
-| Match             | Meaning                                                                 | Proof? |
-| ----------------- | ----------------------------------------------------------------------- | ------ |
-| `exact`           | Byte-identical                                                          | Yes    |
-| `immutables-only` | Identical once immutables and library links are masked                  | Yes    |
-| `metadata-only`   | Identical only after stripping metadata: the source differed            | No     |
-| `code-only`       | Identical, but built with `bytecodeHash: "none"` or `appendCBOR: false` | No     |
-| `none`            | Different code                                                          | No     |
+| Match | Meaning | Proof? |
+| --- | --- | --- |
+| `exact` | Byte-identical | Yes |
+| `immutables-only` | Identical once immutables and library links are masked | Yes |
+| `metadata-only` | Identical only after stripping metadata: the source differed | No |
+| `code-only` | Identical, but built with `bytecodeHash: "none"` or `appendCBOR: false` | No |
+| `none` | Different code | No |
 
-Contracts built without a metadata hash (common for deterministic CREATE2 deployments) therefore
-cannot be proven. For explorer source, the verified compiler settings are checked as well, so a
-build without a hash is refused even if its code happens to end in bytes shaped like one. With
-`proveLocalBuild`, the hash is read from your own compiler output.
+Contracts built without a metadata hash (common for deterministic CREATE2 deployments) therefore cannot be proven. For explorer source, the verified compiler settings are checked as well, so a build without a hash is refused even if its code happens to end in bytes shaped like one. With `proveLocalBuild`, the hash is read from your own compiler output.
 
 ## Errors
 
 slotdiff fails closed: it never treats "could not check" as "safe".
 
-- `LayoutUnavailableError`: no answer. Not a proxy, unverified source, explorer outage or rate
-  limit, no compiler for the platform. Falling back to another source is reasonable.
-- `LayoutIntegrityError`: an answer that cannot be trusted. Source that does not compile to the
-  deployed code, a weak match, a record from another chain or for other code. Never fall back on
-  this one.
+- `LayoutUnavailableError`: no answer. Not a proxy, unverified source, explorer outage or rate limit, no compiler for the platform. Falling back to another source is reasonable.
+- `LayoutIntegrityError`: an answer that cannot be trusted. Source that does not compile to the deployed code, a weak match, a record from another chain or for other code. Never fall back on this one.
 
-A few problems that are yours to fix throw a plain `Error`: a rejected explorer API key, a compiler
-binary that fails to run (for example the wrong architecture), and a record in a format from a
-newer slotdiff.
+A few problems that are yours to fix throw a plain `Error`: a rejected explorer API key, a compiler binary that fails to run (for example the wrong architecture), and a record in a format from a newer slotdiff.
 
 ## API
 
-| Export                                                       | Purpose                                                                  |
-| ------------------------------------------------------------ | ------------------------------------------------------------------------ |
-| `diffLayouts(before, after, { unsafeAllowRenames? })`        | OpenZeppelin's storage comparison. `ok` and `explain()`                  |
-| `resolveProxyLayout(provider, proxy, options)`               | Proven layout of what a proxy (ERC-1967 or beacon) runs now              |
-| `resolveLayout(provider, address, options)`                  | Proven layout of the code at an implementation address                   |
-| `proveLocalBuild(provider, address, build)`                  | A record from your own build, only when it is the deployed build         |
-| `verifyRecord(provider, address, value)`                     | Load a saved record, checked against the chain                           |
-| `parseRecord(value, address?)`                               | Load a saved record, checked offline                                     |
-| `layoutFromSource(input, solc, "file.sol:Name")`             | Layout from standard-json input, including ERC-7201 namespaces. No proof |
-| `getSolc(version)`                                           | Native solc, from a cache or downloaded and checksum-verified            |
-| `readProxy`, `readImplementation`, `readCode`, `readChainId` | Chain reads                                                              |
-| `fetchVerifiedSource(chainId, address, explorer)`            | Verified standard-json source from an Etherscan-compatible explorer      |
-| `compareDeployedBytecode`, `isProvingMatch`                  | The match classification above                                           |
-
-`getSolc` takes a long (`0.8.24+commit.e11b9ed9`) or release (`0.8.24`) version. Compilers are
-cached under your OS cache directory (`slotdiff/compilers`, or `cacheDir`), and Hardhat's compiler
-cache is reused when present.
-
-Renames and retypes follow OpenZeppelin's NatSpec tags, `@custom:oz-renamed-from` and
-`@custom:oz-retyped-from`.
+| Export | Purpose |
+| --- | --- |
+| `diffLayouts(before, after, { unsafeAllowRenames? })` | OpenZeppelin's storage comparison. `ok` and `explain()` |
+| `resolveProxyLayout(provider, proxy, options)` | Proven layout of what a proxy (ERC-1967 or beacon) runs now |
+| `resolveLayout(provider, address, options)` | Proven layout of the code at an implementation address |
+| `proveLocalBuild(provider, address, build)` | A record from your own build, only when it is the deployed build |
+| `verifyRecord(provider, address, value)` | Load a saved record, checked against the chain |
+| `parseRecord(value, address?)` | Load a saved record, checked offline |
+| `layoutFromSource(input, solc, "file.sol:Name")` | Layout from standard-json input, including ERC-7201 namespaces. No proof |
+| `analyzeSource(input, solc, "file.sol:Name")` | The layout, proxy `kind`, ERC-7201 `namespaces` and `safety({ kind })` |
+| `checkNamespaces(old, next)` | ERC-7201 namespaces paired by real slot; a moved one fails |
+| `findBuildInfo(root, contract, { file? })` | Your build info for a contract: input, compiler version, deployed code |
+| `getSolc(version)` | Native solc, from a cache or downloaded and checksum-verified |
+| `readProxy`, `readImplementation`, `readCode`, `readChainId` | Chain reads |
+| `fetchVerifiedSource(chainId, address, explorer)` | Verified standard-json source from an Etherscan-compatible explorer |
+| `compareDeployedBytecode`, `isProvingMatch` | The match classification above |
+
+`getSolc` takes a long (`0.8.24+commit.e11b9ed9`) or release (`0.8.24`) version. Compilers are cached under your OS cache directory (`slotdiff/compilers`, or `cacheDir`), and Hardhat's compiler cache is reused when present.
+
+Renames and retypes follow OpenZeppelin's NatSpec tags, `@custom:oz-renamed-from` and `@custom:oz-retyped-from`.
 
 ## Limitations
 
-- Explorer source must be verified as standard-json. Flattened and multi-file verifications do not
-  record every compiler setting, so they are refused.
+- Explorer source must be verified as standard-json. Flattened and multi-file verifications do not record every compiler setting, so they are refused.
 - Solidity only.
-- Struct members cannot be renamed or retyped: Solidity has no NatSpec on struct members, so
-  OpenZeppelin's tags cannot reach them.
-- ERC-7201 namespaces are located by their `@custom:storage-location erc7201:<id>` annotation, as
-  OpenZeppelin does. The `bytes32` slot constant your code actually uses is not checked against
-  it, so moving the constant while leaving the annotation unchanged is not detected. Keep the two in
-  sync, for example by deriving the constant with the ERC-7201 formula in a test.
-- Library only for now. A CLI is planned.
+- Struct members cannot be renamed or retyped: Solidity has no NatSpec on struct members, so OpenZeppelin's tags cannot reach them.
+- An ERC-7201 slot is read only from a `$.slot := ...` assignment whose value is a constant (a hex literal, the ERC-7201 formula, or `erc7201("id")`), directly or through a local variable set once or a function with no arguments that returns one. Any other slot (computed at run time, a library's constant) is not read, and the upgrade is reported as not checked.
+
+## No guarantee
+
+slotdiff is provided as is, without warranty of any kind (see [LICENSE](LICENSE)). It checks what its rules and OpenZeppelin's can check. "Safe to upgrade" means those checks found no problem, not that the upgrade is safe in every way. It does not replace review, a test upgrade on a fork, or an audit. The authors accept no liability for any loss, including lost or locked funds, arising from using slotdiff or relying on its results.
+
+To report a security problem, or to see what slotdiff touches on your machine (network, processes, files, environment), read [SECURITY.md](SECURITY.md).
 
 ## License
 

package/dist/bin.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=bin.d.ts.map

package/dist/bin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.d.ts","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":""}

package/dist/bin.js

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+import { styleText } from "node:util";
+import { run } from "./cli.js";
+// A reader that stops early, such as `| head`, is not an error.
+process.stdout.on("error", (e) => {
+    if (e.code !== "EPIPE")
+        throw e;
+    process.exit();
+});
+run(process.argv.slice(2), {
+    stdout: (line) => console.log(line),
+    stderr: (line) => console.error(line),
+    tty: process.stdout.isTTY === true,
+    // Node's own rules for color: a terminal that has them, NO_COLOR, FORCE_COLOR.
+    color: styleText("red", "x", { stream: process.stdout }) !== "x",
+}).then((code) => {
+    process.exitCode = code;
+}, (e) => {
+    console.error(e);
+    process.exitCode = 2;
+});
+//# sourceMappingURL=bin.js.map

package/dist/bin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.js","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAE/B,gEAAgE;AAChE,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,CAAwB,EAAE,EAAE;IACtD,IAAI,CAAC,CAAC,IAAI,KAAK,OAAO;QAAE,MAAM,CAAC,CAAC;IAChC,OAAO,CAAC,IAAI,EAAE,CAAC;AACjB,CAAC,CAAC,CAAC;AAEH,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE;IACzB,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC;IACnC,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC;IACrC,GAAG,EAAE,OAAO,CAAC,MAAM,CAAC,KAAK,KAAK,IAAI;IAClC,+EAA+E;IAC/E,KAAK,EAAE,SAAS,CAAC,KAAK,EAAE,GAAG,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,KAAK,GAAG;CACjE,CAAC,CAAC,IAAI,CACL,CAAC,IAAI,EAAE,EAAE;IACP,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;AAC1B,CAAC,EACD,CAAC,CAAU,EAAE,EAAE;IACb,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IACjB,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;AACvB,CAAC,CACF,CAAC"}

package/dist/build-info.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Reads a project's own build info: Foundry, Hardhat 2 and Hardhat 3.
+ *
+ * The build is chosen by content, never by modification time or file count.
+ * Foundry keeps every build-info file it ever wrote, so after a few edits
+ * several hold the target, most of them describing older sources. Only a build
+ * whose sources still match the files on disk is used.
+ */
+import type { SolcInput } from "@openzeppelin/upgrades-core";
+import type { ImmutableReferences } from "./bytecode.js";
+export interface BuildInfoOptions {
+    /**
+     * One build-info file to use as is, relative to the project root. Its
+     * sources are not compared with the files on disk, so it may come from
+     * another checkout, such as a CI artifact.
+     */
+    file?: string;
+}
+export interface BuildInfoContract {
+    /** The build-info file it was read from. */
+    file: string;
+    /**
+     * Fully qualified name as solc saw it, `source.sol:Name`. Hardhat 3 prefixes
+     * project sources with `project/`.
+     */
+    contract: string;
+    /** As recorded: a long version, or a release version for Foundry. Both work with `getSolc`. */
+    solcVersion: string;
+    /**
+     * The compiler input, reduced to the target and what it imports, so that a
+     * layout compiles only those sources rather than the whole project.
+     */
+    input: SolcInput;
+    /** Absent when the build info holds no compiler output. */
+    deployedBytecode?: string;
+    immutableReferences?: ImmutableReferences;
+}
+/**
+ * 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 declare function findBuildInfo(root: string, contract: string, options?: BuildInfoOptions): Promise<BuildInfoContract>;
+//# sourceMappingURL=build-info.d.ts.map

package/dist/build-info.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-info.d.ts","sourceRoot":"","sources":["../src/build-info.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,6BAA6B,CAAC;AAG7D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAEzD,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,iBAAiB;IAChC,4CAA4C;IAC5C,IAAI,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB,+FAA+F;IAC/F,WAAW,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,KAAK,EAAE,SAAS,CAAC;IACjB,2DAA2D;IAC3D,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,mBAAmB,CAAC,EAAE,mBAAmB,CAAC;CAC3C;AAkCD;;;;;GAKG;AACH,wBAAsB,aAAa,CACjC,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,iBAAiB,CAAC,CAgH5B"}