slotdiff 0.1.0-alpha.1 → 0.3.0

package/CHANGELOG.md

@@ -1,19 +1,60 @@
 # Changelog
 
+## 0.3.0
+
+### Fixed
+
+These were in 0.2.0 (the solc one since 0.1.0); upgrade if you rely on the CLI or check verified source.
+
+- CLI: an `<old>` address that is not an ERC-1967 or beacon proxy was taken as an implementation, so a proxy of another kind (a custom slot, a diamond) was compared as its own, nearly empty, code and could pass. It is now refused (exit 2) unless `--old-implementation` says it is an implementation.
+- Storage placed at a fixed slot through a struct that is not an ERC-7201 namespace of the contract or its bases (a namespace declared in a library, as in the diamond and Solidstate pattern, or a struct with no annotation) is left out of OpenZeppelin's layout with only a warning, so a change to it passed. It now stops the analysis with `LayoutUnavailableError` (exit 2).
+- solc ran in the caller's directory, so verified source could `import` a file under it (an `.env`, say) and solc would quote its first line in the compile error. It now runs in a new empty directory, and verified source given by `urls` instead of inline `content` is refused.
+- Text from an explorer or from verified source could move the cursor, recolor the terminal or draw lines of its own (a fake "Safe to upgrade." under the error). Control characters are stripped from solc's errors, explorer messages are kept on one line, and verified source with control characters in its name, paths or text (tabs and line breaks in text aside), or any whitespace but a space in its name and paths, is refused (`LayoutUnavailableError`).
+
+### Breaking
+
+- CLI: an `<old>` implementation address needs `--old-implementation` (above).
+- `layoutFromSource` is removed: use `(await analyzeSource(input, solc, contract)).layout`, at the same cost.
+- `NamespaceCheck.result` says `"unchecked"` (was `"unread"`), as `UpgradeCheck.result` does. New union members: `NamespaceSlot.status` `"unused"` (such namespaces were `unread`), `NamespacePair.problem` `"dropped"`.
+- `checkNamespaces`: `next` needs its `layout`.
+- Plain `Error` (was `LayoutIntegrityError`), as wrong arguments: a contract missing from the compiler input, an input source without `content`. `safety()` throws on an unknown `unsafeAllow` kind (OpenZeppelin ignored it).
+
+### Added
+
+- `checkUpgrade(old, next, options?)`: layout, ERC-7201 slots and safety rules in one verdict (`pass`, `fail` or `unchecked`), as the CLI runs them. The proxy kind comes from `old`.
+- `analyzeBuild(input, output, compiler)`: `analyzeSource` for a build already compiled (a build tool's), with no second full compile; one namespaced pass serves every contract. Its `metadata` must prove the output was compiled from those sources by that compiler (`LayoutIntegrityError` otherwise); incomplete output throws the new `IncompleteBuildError`.
+- Layout records keep the proxy `kind` and each namespace's slot (`namespaces`), so a saved record can stand in for `old`; `proveLocalBuild` takes both. Optional: older records still load, their namespaces unchecked.
+- `resolveProxyLayout` returns the proxy's `kind`; `SafetyReport.explain(color?)` and `NamespaceCheck.explain(color?)` (the CLI's namespace grid). New types: `SolcOutput`, `UpgradeSide`, `UpgradeOptions`, `UpgradeCheck`, `BuildAnalysis`, `BuildCompiler`.
+
+### Changed
+
+- ERC-7201: a namespace with no `$.slot :=` assignment (kept reserved) is `unused` and compared by its annotation (unless the code places a mapping or an array pointer), so such upgrades exit 0 where 0.2.0 exited 2. Dropping the last assignment of a namespace whose deployed annotation is wrong fails (`dropped`), while the real slot is still known.
+- CLI: unassigned namespaces with no problem are left out of the grid and counted in the summary ("N not assigned in code, compared by annotation"); an unread slot says which side could not be read.
+- Stricter input: `analyzeSource` checks its own compile as `analyzeBuild` does (a compiler whose version differs from the one the metadata names is a `LayoutIntegrityError`); `parseRecord` refuses a namespace key not of the form `<formula>:<id>` and a malformed `kind` or `namespaces`; `checkNamespaces` refuses slots that do not fit the layout (`LayoutIntegrityError`); `getSolc` refuses a malformed entry in solc's build list.
+- `SAFETY_ERROR_KINDS` and `SafetyErrorKind` are slotdiff's own list (a test compares it with OpenZeppelin's), so the published types no longer import an OpenZeppelin internal file.
+- Releases: the publish workflow installs dependencies without their install scripts; a weekly workflow tests against the newest OpenZeppelin upgrades-core 1.x.
+
+## 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,62 +41,166 @@ 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 (ERC-1967 or beacon), read as the implementation it runs now, or for `<new>` an implementation, such as one waiting in a multisig queue. Any mix works. An `<old>` address that is not such a proxy is refused, since a proxy of another kind (a diamond, a custom slot) would be compared as its own code: pass `--old-implementation` when `<old>` is an implementation, or give such a proxy by its implementation's address. 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 (each file the contract imports is compared, except a dependency slotdiff cannot find from the root, such as one hoisted to a monorepo's top `node_modules`). `--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 namespace with no `$.slot := ...` assignment (one kept reserved, as OpenZeppelin advises for a struct no longer used) is compared by its annotation, as OpenZeppelin does. Dropping the last assignment of a namespace whose deployed annotation does not match its data fails: correct the annotation first, since later versions would be compared by it (correcting it and dropping the assignment in the same upgrade fails too). A slot slotdiff cannot read (set from a value it does not evaluate, such as one computed at run time) 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 { analyzeSource, checkUpgrade, findBuildInfo, getSolc, 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);
 const apiKey = process.env.ETHERSCAN_API_KEY;
 
-// 1. The layout of whatever the proxy runs now, proven against its deployed code.
+// 1. Whatever the proxy runs now: its layout and ERC-7201 slots, 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 new version, from your build info (Foundry, Hardhat 2 or 3).
+const build = await findBuildInfo(process.cwd(), "src/VaultV2.sol:VaultV2");
+const next = await analyzeSource(build.input, await getSolc(build.solcVersion), build.contract);
 
-// 3. Compare.
-const report = diffLayouts(live.record.layout, next);
-if (!report.ok) {
-  console.error(report.explain());
+// 3. The layout, the ERC-7201 slots and the safety rules, with the proxy's own kind.
+const check = checkUpgrade({ ...live.record, kind: live.kind }, next);
+if (check.result !== "pass") {
+  // "fail", or "unchecked" when an ERC-7201 slot could not be read: neither is a pass.
+  console.error(check.layout.explain(), check.namespaces.explain(), check.safety?.explain());
   process.exit(1);
 }
 ```
 
-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:
+`check.layout.explain()` gives OpenZeppelin's report, for example:
 
 ```
 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).
+
+### Two local builds
+
+`analyzeSource` gives a contract's layout, the slot each ERC-7201 namespace really uses and OpenZeppelin's safety check, from one compile. `checkUpgrade` runs all three checks on two analyses, or a record and an analysis, and gives one verdict, as the command line does.
+
+```ts
+import { analyzeSource, checkUpgrade, 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");
+
+const check = checkUpgrade(old, next); // result: "pass", "fail" or "unchecked"
+if (check.result !== "pass") {
+  console.error(check.layout.explain(), check.namespaces.explain(), check.safety?.explain());
+}
+```
+
+The safety rules take the proxy kind from `old`, the proxy being upgraded, never from `next`: a UUPS implementation that lost its upgrade function would otherwise look transparent and pass. For a beacon proxy, pass `{ ...old, kind: "beacon" }`. `checkUpgrade` also takes `unsafeAllowRenames`, `unsafeAllow` (error kinds to accept, listed in `SAFETY_ERROR_KINDS`, on top of `@custom:oz-upgrades-unsafe-allow` in the source) and `skipSafety`. `unchecked` means nothing failed but an ERC-7201 slot could not be read (`check.namespaces.result` is `unchecked` too, and that pair's `problem` is `unread`). With `skipSafety`, `pass` covers the layout and slots only, and `check.safety` is absent. The pieces are there too: `checkNamespaces`, `diffLayouts` and the analysis's own `safety({ kind })`.
+
+### Reuse a build you already compiled
+
+A build tool has just compiled the project, so compiling it again only to analyze it is wasted time. `analyzeBuild` takes that compiler input and output and analyzes every contract in it from one more, much lighter pass (OpenZeppelin's namespaced layouts). The output needs every source's `ast` and each contract's `metadata`, `storageLayout` and `evm.bytecode` (`object`, `linkReferences`); an interface or library may lack a `storageLayout`. Ask for them in `outputSelection` (Hardhat 3 leaves out `metadata` and `storageLayout` by default, Hardhat 2 `storageLayout`; Foundry needs `extra_output = ["storageLayout"]`). Output missing any of these throws `IncompleteBuildError`, so a build tool can ask for a fresh compile. The metadata proves the output was compiled from these sources by this compiler version (not that it used the input's settings, so pass the input the build tool compiled): an output from an earlier build is refused, never half analyzed. Hardhat 3 wraps the output in `<id>.output.json`; pass its `output` field.
+
+```ts
+import { analyzeBuild, checkUpgrade, getSolc } from "slotdiff";
+
+const build = await analyzeBuild(input, output, await getSolc(solcLongVersion));
+const check = checkUpgrade(old, build.contract("project/contracts/Vault.sol:Vault"));
+```
+
+The third argument runs that pass: a `getSolc` compiler, or your build tool's own, as `{ longVersion, compile(input) }`.
 
 ### 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 +218,104 @@ 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.
+
+A record also keeps the proxy `kind` its code implies and the slot each ERC-7201 namespace really uses (`namespaces`), so it can stand in for `old` in `checkUpgrade`. Pass the proxy's own kind when you know it: `resolveProxyLayout` returns it as `kind` (`beacon` behind a beacon). Otherwise fall back to `"uups"`, never `"transparent"`: `"uups"` only adds the requirement that `next` keeps its upgrade function, so at worst it fails a transparent proxy's upgrade, while `"transparent"` would pass a UUPS implementation that lost it.
+
+```ts
+const check = checkUpgrade({ ...record, kind: record.kind ?? "uups" }, next);
+```
+
+Older records have neither field, and their namespaces come out unchecked rather than trusted by annotation. To compare two records, as a deploy step might, pass `{ skipSafety: true }`: `next` then needs no analysis and `old` no kind.
 
-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 what it says about that code: an edited `layout`, `kind` or `namespaces` in a saved record still verifies. Each changes the verdict (an edited `kind` of `"transparent"` drops the check that a UUPS implementation keeps its upgrade function). 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 { analyzeSource, findBuildInfo, getSolc, 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 { layout, kind, namespaces } = await analyzeSource(build.input, solc, build.contract);
 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,
+  kind, // so the record can stand in for `old` in checkUpgrade
+  namespaces,
+  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, a record or analysis that contradicts itself (namespace slots that do not fit its layout). 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.
+Problems that are yours to fix throw a plain `Error`, or `IncompleteBuildError` (an `Error`) for a build missing output `analyzeBuild` needs: a rejected explorer API key, a compiler binary that fails to run (for example the wrong architecture), a record in a format from a newer slotdiff, and wrong arguments, such as a contract that is not in the compiler input, an unknown proxy kind given to `checkUpgrade`, an unknown `unsafeAllow` kind, or `checkUpgrade` asked for the safety rules without an analysis of `next`.
 
 ## 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 |
+| `analyzeSource(input, solc, "file.sol:Name")` | The layout, proxy `kind`, ERC-7201 `namespaces` and `safety({ kind })` |
+| `analyzeBuild(input, output, compiler)` | The same for every contract of a build already compiled, with no second full compile |
+| `checkUpgrade(old, next, options?)` | Layout, ERC-7201 slots and safety rules in one verdict: `pass`, `fail` or `unchecked` |
+| `checkNamespaces(old, next)` | ERC-7201 namespaces paired by real slot; a moved one fails. `explain()` |
+| `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.
+- Storage placed at a fixed slot through a struct that is not an ERC-7201 namespace of the contract or its bases (a namespace declared in a library, as in the diamond pattern, or a struct with no annotation) is not in OpenZeppelin's layout, so slotdiff cannot compare it and stops (exit 2) rather than pass it.
+- 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. A namespace with no `$.slot := ...` assignment is compared by its annotation alone, as with OpenZeppelin, unless the code places a mapping or an array pointer anywhere: its data may live there, so the upgrade is reported as not checked. Data an even older version left at another slot, or data reached another way (raw `sload` and `sstore`, or a pointer whose slot is passed in, as OpenZeppelin's `StorageSlot` takes it), goes unnoticed.
+
+## 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"}