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

package/dist/erc7201.js

@@ -0,0 +1,340 @@
+/**
+ * ERC-7201 namespaces by the slot the code really uses.
+ *
+ * OpenZeppelin matches namespaces by their `@custom:storage-location
+ * erc7201:<id>` annotation and never checks the `bytes32` slot the code assigns
+ * (`assembly { $.slot := LOCATION }`). The two can disagree. A changed
+ * constant behind an unchanged annotation moves the storage while the layout
+ * check passes; a corrected annotation over an unchanged constant leaves the
+ * storage in place while the check reports a deleted namespace. Reading the
+ * slot from the AST catches the first and fixes the second.
+ */
+// Not exported from the package index; the package has no exports map, and
+// all exist since 1.46.0, the lowest version slotdiff accepts.
+import { getStorageLocationAnnotation } from "@openzeppelin/upgrades-core/dist/storage/namespace.js";
+import { calculateERC7201StorageLocation } from "@openzeppelin/upgrades-core/dist/utils/erc7201.js";
+import { resolveBaseSlot } from "@openzeppelin/upgrades-core/dist/utils/erc7201-builtin.js";
+import { normalizeUint256Literal, toBytes32Hex, } from "@openzeppelin/upgrades-core/dist/utils/integer-literals.js";
+/**
+ * How each of `namespaces` (`erc7201:<id>` keys of `contract`'s layout,
+ * `source.sol:Name`) is assigned in `output`. Only structs declared in the
+ * contract or its bases count, as for OpenZeppelin: a sibling contract in the
+ * same build (a V1 next to its V2, a test copy) may declare the same id.
+ */
+export function namespaceSlots(output, contract, namespaces) {
+    const colon = contract.lastIndexOf(":");
+    // Most derived first, as solc lists them: the order virtual calls resolve in.
+    let linearized = [];
+    walk(output.sources?.[contract.slice(0, colon)]?.ast, (node) => {
+        if (node.nodeType === "ContractDefinition" && node.name === contract.slice(colon + 1)) {
+            linearized = node.linearizedBaseContracts;
+        }
+    });
+    const bases = new Set(linearized);
+    // Only code the contract can run counts: its bases (minus the functions they
+    // override), libraries and free functions, not a sibling contract (a test
+    // harness) in the same files.
+    const byId = new Map();
+    const touched = new Set();
+    const overridden = new Set();
+    for (const source of Object.values(output.sources ?? {})) {
+        walk(source.ast, (node) => {
+            if (typeof node.id === "number")
+                byId.set(node.id, node);
+            // Any Solidity use of a local after its declaration, so a local is read
+            // only when nothing but assembly reads it.
+            if (node.nodeType === "Identifier")
+                touched.add(node.referencedDeclaration);
+            if (node.nodeType === "FunctionDefinition" && bases.has(node.scope)) {
+                for (const base of (node.baseFunctions ?? []))
+                    overridden.add(base);
+            }
+        });
+    }
+    const assemblies = [];
+    for (const source of Object.values(output.sources ?? {})) {
+        walk(source.ast, (node) => {
+            const sibling = node.nodeType === "ContractDefinition" &&
+                node.contractKind !== "library" &&
+                !bases.has(node.id);
+            if (sibling || overridden.has(node.id))
+                return false;
+            if (node.nodeType === "InlineAssembly")
+                assemblies.push(node);
+        });
+    }
+    const ctx = { byId, linearized, bases, touched };
+    // Struct id → every slot value assigned to a pointer of that struct (undefined: unreadable).
+    const assigned = new Map();
+    for (const assembly of assemblies) {
+        const refs = (assembly.externalReferences ?? []);
+        const declarationAt = (src) => refs.find((r) => r.src === src)?.declaration ?? -1;
+        walk(assembly.AST, (node) => {
+            if (node.nodeType !== "YulAssignment")
+                return;
+            for (const target of node.variableNames) {
+                if (typeof target.name !== "string")
+                    continue;
+                if (!target.name.endsWith(".slot")) {
+                    touched.add(declarationAt(target.src));
+                    continue;
+                }
+                const pointer = byId.get(declarationAt(target.src));
+                const struct = pointer?.typeName?.referencedDeclaration;
+                if (typeof struct !== "number")
+                    continue;
+                const value = node.value;
+                const slot = value.nodeType === "YulLiteral"
+                    ? value.kind === "number"
+                        ? normalize(value.value)
+                        : undefined
+                    : resolveDecl(ctx, byId.get(declarationAt(value.src)));
+                assigned.set(struct, [...(assigned.get(struct) ?? []), slot]);
+            }
+        });
+    }
+    return namespaces.map((namespace) => {
+        const expected = calculateERC7201StorageLocation(namespace.slice("erc7201:".length));
+        const slots = [...byId.values()]
+            .filter((n) => n.nodeType === "StructDefinition" &&
+            bases.has(n.scope) &&
+            getStorageLocationAnnotation(n) === namespace)
+            .flatMap((n) => assigned.get(n.id) ?? []);
+        const known = [...new Set(slots.filter((s) => s !== undefined))];
+        if (known.length > 1)
+            return { namespace, expected, status: "conflict" };
+        if (known.length === 0 || slots.includes(undefined)) {
+            return { namespace, expected, status: "unread" };
+        }
+        const actual = known[0];
+        return actual === expected
+            ? { namespace, expected, actual, status: "match" }
+            : { namespace, expected, actual, status: "mismatch" };
+    });
+}
+/**
+ * Checks ERC-7201 namespaces by the slot the code uses, not the annotation
+ * OpenZeppelin goes by. An old and a new namespace are the same storage when
+ * the code uses the same slot (under the same annotation first), failing that
+ * when they share an annotation, and failing that when the new annotation
+ * names the slot where the old data is.
+ * Pass `layout` to `diffLayouts` in place of `old.layout`.
+ */
+export function checkNamespaces(old, next) {
+    const unpaired = new Set(old.namespaces);
+    const pairs = next.namespaces.map((n) => ({ next: n }));
+    const sameSlot = (o, n) => o.actual !== undefined && n.actual !== undefined && same(o.actual, n.actual);
+    const rules = [
+        (o, n) => sameSlot(o, n) && o.namespace === n.namespace,
+        sameSlot,
+        (o, n) => o.namespace === n.namespace,
+        (o, n) => o.actual !== undefined && same(o.actual, n.expected),
+    ];
+    // Rule by rule over every namespace, so a weaker rule never takes a pair from a stronger one.
+    for (const rule of rules) {
+        for (const pair of pairs) {
+            const o = pair.old ?? [...unpaired].find((o) => rule(o, pair.next));
+            if (o !== undefined && unpaired.delete(o))
+                pair.old = o;
+        }
+    }
+    for (const o of unpaired)
+        pairs.push({ old: o });
+    for (const pair of pairs)
+        pair.problem = problemOf(pair);
+    // Renamed all at once, so two namespaces can swap names.
+    const renames = new Map(pairs.flatMap((p) => p.old !== undefined && p.next !== undefined ? [[p.old.namespace, p.next.namespace]] : []));
+    const oldNames = Object.keys(old.layout.namespaces ?? {});
+    const renamed = oldNames.map((name) => renames.get(name) ?? name);
+    // On a clash (an old namespace that stays keeps the name another would take)
+    // nothing is renamed: OpenZeppelin then reports the moved one as deleted.
+    const layout = new Set(renamed).size < renamed.length || renamed.every((to, i) => to === oldNames[i])
+        ? old.layout
+        : {
+            ...old.layout,
+            namespaces: Object.fromEntries(oldNames.map((name, i) => [renamed[i], old.layout.namespaces[name]])),
+        };
+    const problems = pairs.map((p) => p.problem);
+    return {
+        layout,
+        pairs,
+        result: problems.some((p) => p !== undefined && p !== "unread")
+            ? "fail"
+            : problems.includes("unread")
+                ? "unread"
+                : "pass",
+    };
+}
+function problemOf({ old, next }) {
+    if (next?.status === "conflict")
+        return "conflict";
+    if (old?.actual !== undefined && next?.actual !== undefined && !same(old.actual, next.actual)) {
+        return "moved";
+    }
+    if (next?.status === "mismatch")
+        return "mismatch";
+    if ((old !== undefined && old.actual === undefined) || next?.status === "unread") {
+        return "unread";
+    }
+    return undefined;
+}
+function same(a, b) {
+    return BigInt(a) === BigInt(b);
+}
+// Visits every node; a visitor returning false skips the node's children.
+function walk(node, visit) {
+    if (Array.isArray(node)) {
+        for (const child of node)
+            walk(child, visit);
+    }
+    else if (typeof node === "object" && node !== null) {
+        if (visit(node) === false)
+            return;
+        for (const child of Object.values(node))
+            walk(child, visit);
+    }
+}
+/**
+ * The value of a constant, an immutable set where it is declared, or a local
+ * that only assembly reads. A state variable's initial value is not read: it
+ * lives in the implementation's storage, not the proxy's.
+ */
+function resolveDecl(ctx, decl, depth = 0) {
+    if (decl === undefined)
+        return undefined;
+    if (decl.stateVariable === true) {
+        if (decl.mutability !== "constant" && decl.mutability !== "immutable")
+            return undefined;
+        return resolveExpr(ctx, decl.value, depth);
+    }
+    if (ctx.touched.has(decl.id))
+        return undefined;
+    return resolveExpr(ctx, initialValue(ctx.byId, decl), depth);
+}
+/**
+ * The value of an expression: a reference to a constant or local, a call to a
+ * no-argument function that returns one (OpenZeppelin's Initializable reads
+ * its slot from `_initializableStorageSlot()`), the ERC-7201 formula, a
+ * number literal or `erc7201("id")`.
+ */
+function resolveExpr(ctx, e, depth) {
+    if (e === undefined || depth > 8)
+        return undefined;
+    if (e.nodeType === "Identifier") {
+        return resolveDecl(ctx, ctx.byId.get(e.referencedDeclaration), depth + 1);
+    }
+    if (e.nodeType === "FunctionCall" && e.kind === "functionCall") {
+        const callee = e.expression;
+        const fn = ctx.byId.get(callee.referencedDeclaration);
+        if (callee.nodeType !== "Identifier" || fn?.nodeType !== "FunctionDefinition")
+            return undefined;
+        if (e.arguments.length > 0)
+            return undefined;
+        return resolveExpr(ctx, returned(override(ctx, fn)), depth + 1);
+    }
+    const id = formulaId(e);
+    if (id !== undefined)
+        return calculateERC7201StorageLocation(id);
+    // OpenZeppelin would read any other literal, such as `hex"..."`, as a number.
+    if (e.nodeType === "Literal" && e.kind !== "number")
+        return undefined;
+    try {
+        return resolveBaseSlot(e);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The implementation an internal call to `fn` reaches: the most derived
+ * override of a virtual function in the bases, or `fn` itself (a free or
+ * library function, which nothing overrides).
+ */
+function override(ctx, fn) {
+    if (fn.virtual !== true || !ctx.bases.has(fn.scope))
+        return fn;
+    for (const contract of ctx.linearized) {
+        for (const node of ctx.byId.values()) {
+            if (node.nodeType === "FunctionDefinition" &&
+                node.scope === contract &&
+                node.name === fn.name &&
+                node.parameters.parameters.length === 0 &&
+                node.body) {
+                return node;
+            }
+        }
+    }
+    return fn;
+}
+// The expression of a function whose body is a single `return <expression>;`
+// and that has no modifier, which could skip it.
+function returned(fn) {
+    if (fn.modifiers?.length)
+        return undefined;
+    const statements = fn.body?.statements;
+    return statements?.length === 1 && statements[0].nodeType === "Return"
+        ? statements[0].expression
+        : undefined;
+}
+// A local variable's value is on the statement that declares it.
+function initialValue(byId, decl) {
+    for (const node of byId.values()) {
+        if (node.nodeType !== "VariableDeclarationStatement")
+            continue;
+        const declarations = node.declarations;
+        if (declarations.length === 1 && declarations[0]?.id === decl.id)
+            return node.initialValue;
+    }
+    return undefined;
+}
+/**
+ * The id in the ERC-7201 formula written out in Solidity,
+ * `keccak256(abi.encode(uint256(keccak256("id")) - 1)) & ~bytes32(uint256(0xff))`,
+ * with an optional `bytes("id")`. Anything else is not recognized.
+ */
+function formulaId(e) {
+    if (e.nodeType !== "BinaryOperation" || e.operator !== "&")
+        return undefined;
+    const mask = e.rightExpression;
+    const masked = arg(arg(mask.nodeType === "UnaryOperation" ? mask.subExpression : undefined, "bytes32"), "uint256");
+    if (masked?.nodeType !== "Literal" || normalize(masked.value) !== toBytes32Hex(0xffn)) {
+        return undefined;
+    }
+    const minus = arg(arg(e.leftExpression, "keccak256"), "abi.encode");
+    if (minus?.nodeType !== "BinaryOperation" || minus.operator !== "-")
+        return undefined;
+    const one = minus.rightExpression;
+    if (one.nodeType !== "Literal" || one.value !== "1")
+        return undefined;
+    let id = arg(arg(minus.leftExpression, "uint256"), "keccak256");
+    if (id?.nodeType === "FunctionCall")
+        id = arg(id, "bytes");
+    return id?.nodeType === "Literal" && id.kind === "string" ? id.value : undefined;
+}
+// The single argument of a call to `name` (a function, `abi.encode`, or a type conversion).
+function arg(call, name) {
+    if (call?.nodeType !== "FunctionCall")
+        return undefined;
+    const callee = call.expression;
+    const calleeName = callee.nodeType === "Identifier"
+        ? callee.name
+        : callee.nodeType === "MemberAccess"
+            ? `${callee.expression.name}.${callee.memberName}`
+            : callee.nodeType === "ElementaryTypeNameExpression"
+                ? callee.typeName.name
+                : undefined;
+    const args = call.arguments;
+    return calleeName === name && args.length === 1 ? args[0] : undefined;
+}
+// A number literal as a slot, or undefined when it is not one.
+function normalize(value) {
+    if (typeof value !== "string")
+        return undefined;
+    try {
+        return normalizeUint256Literal(value);
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=erc7201.js.map

package/dist/erc7201.js.map

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

package/dist/errors.d.ts

@@ -15,4 +15,9 @@ export declare class LayoutUnavailableError extends Error {
 export declare class LayoutIntegrityError extends Error {
     constructor(message: string);
 }
+/**
+ * A network error's code (ECONNREFUSED, ENOTFOUND), never its message: fetch
+ * quotes the URL in some messages, and URLs carry API keys.
+ */
+export declare function errorCode(e: unknown): string;
 //# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;gBACnC,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;GAKG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;gBACjC,OAAO,EAAE,MAAM;CAI5B"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;gBACnC,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;GAKG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;gBACjC,OAAO,EAAE,MAAM;CAI5B;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,OAAO,GAAG,MAAM,CAG5C"}

package/dist/errors.js

@@ -21,4 +21,12 @@ export class LayoutIntegrityError extends Error {
         this.name = "LayoutIntegrityError";
     }
 }
+/**
+ * A network error's code (ECONNREFUSED, ENOTFOUND), never its message: fetch
+ * quotes the URL in some messages, and URLs carry API keys.
+ */
+export function errorCode(e) {
+    const code = e.cause?.code;
+    return typeof code === "string" ? code : "network error";
+}
 //# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,OAAO,sBAAuB,SAAQ,KAAK;IAC/C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;IACvC,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IAC7C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;IACrC,CAAC;CACF"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,OAAO,sBAAuB,SAAQ,KAAK;IAC/C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;IACvC,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IAC7C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;IACrC,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,UAAU,SAAS,CAAC,CAAU;IAClC,MAAM,IAAI,GAAI,CAAoC,CAAC,KAAK,EAAE,IAAI,CAAC;IAC/D,OAAO,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,eAAe,CAAC;AAC3D,CAAC"}

package/dist/explorer.js

@@ -6,7 +6,7 @@
  * rebuilding from them means guessing; the bytecode proof would reject a wrong
  * guess, but refusing up front gives a clearer error.
  */
-import { LayoutUnavailableError } from "./errors.js";
+import { errorCode, LayoutUnavailableError } from "./errors.js";
 export const ETHERSCAN_V2_API_URL = "https://api.etherscan.io/v2/api";
 const RATE_LIMIT = /rate limit/i;
 // Key problems are the user's to fix and must surface; anything else the
@@ -43,7 +43,7 @@ async function requestWithRetry(url, fetchImpl) {
         }
         catch (e) {
             // Messages never include the URL, which carries the API key.
-            throw new LayoutUnavailableError(`Explorer unreachable: ${e.message}`);
+            throw new LayoutUnavailableError(`Explorer unreachable (${errorCode(e)}).`);
         }
         if (res.status === 429 && retry) {
             await backoff(attempt);

package/dist/explorer.js.map

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

package/dist/index.d.ts

@@ -4,7 +4,9 @@ export { parseRecord, verifyRecord, type LayoutRecord } from "./record.js";
 export { readProxy, readImplementation, readCode, readChainId, type EthProvider, type ProxyState, } from "./chain.js";
 export { fetchVerifiedSource, ETHERSCAN_V2_API_URL, type ExplorerConfig, type VerifiedSource, } from "./explorer.js";
 export { getSolc, type SolcOptions, type SolcRunner } from "./solc.js";
-export { layoutFromSource } from "./reconstruct.js";
+export { findBuildInfo, type BuildInfoOptions, type BuildInfoContract } from "./build-info.js";
+export { checkNamespaces, type NamespaceCheck, type NamespacePair, type NamespaceSlot, } from "./erc7201.js";
+export { layoutFromSource, analyzeSource, SAFETY_ERROR_KINDS, type SourceAnalysis, type SafetyOptions, type SafetyReport, type SafetyError, type SafetyErrorKind, type ProxyKind, } from "./reconstruct.js";
 export { compareDeployedBytecode, isProvingMatch, type DeployedBytecodeMatch, type ProvingMatch, type ImmutableReferences, } from "./bytecode.js";
 export { LayoutIntegrityError, LayoutUnavailableError } from "./errors.js";
 export type { SolcInput, StorageLayout } from "@openzeppelin/upgrades-core";

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -4,7 +4,9 @@ export { parseRecord, verifyRecord } from "./record.js";
 export { readProxy, readImplementation, readCode, readChainId, } from "./chain.js";
 export { fetchVerifiedSource, ETHERSCAN_V2_API_URL, } from "./explorer.js";
 export { getSolc } from "./solc.js";
-export { layoutFromSource } from "./reconstruct.js";
+export { findBuildInfo } from "./build-info.js";
+export { checkNamespaces, } from "./erc7201.js";
+export { layoutFromSource, analyzeSource, SAFETY_ERROR_KINDS, } from "./reconstruct.js";
 export { compareDeployedBytecode, isProvingMatch, } from "./bytecode.js";
 export { LayoutIntegrityError, LayoutUnavailableError } from "./errors.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/reconstruct.d.ts

@@ -6,16 +6,17 @@
  * the local build (full compile, namespaced second pass, `validate()`,
  * `getStorageLayout`), so both sides of a comparison are extracted identically.
  */
-import { type SolcInput, type StorageLayout } from "@openzeppelin/upgrades-core";
+import { type ProxyDeployment, type SolcInput, type StorageLayout } from "@openzeppelin/upgrades-core";
+import { type ValidationError } from "@openzeppelin/upgrades-core/dist/validate/run.js";
 import { type ProvingMatch } from "./bytecode.js";
+import { type NamespaceSlot } from "./erc7201.js";
 import type { VerifiedSource } from "./explorer.js";
 import type { SolcRunner } from "./solc.js";
-export interface ReconstructedLayout {
+export interface ReconstructedLayout extends SourceAnalysis {
     /** Fully qualified name, `source.sol:Contract`. */
     contract: string;
     compiler: string;
     bytecodeMatch: ProvingMatch;
-    layout: StorageLayout;
 }
 export declare function reconstructLayout(source: VerifiedSource, solc: SolcRunner, onchainCode: string): Promise<ReconstructedLayout>;
 /**
@@ -24,4 +25,51 @@ export declare function reconstructLayout(source: VerifiedSource, solc: SolcRunn
  * project's own build-info.
  */
 export declare function layoutFromSource(input: SolcInput, solc: SolcRunner, contract: string): Promise<StorageLayout>;
+export type ProxyKind = ProxyDeployment["kind"];
+/**
+ * OpenZeppelin's safety error kinds, without the deprecated struct-definition
+ * and enum-definition, which the check never reports.
+ */
+export type SafetyErrorKind = Exclude<ValidationError["kind"], "struct-definition" | "enum-definition">;
+export declare const SAFETY_ERROR_KINDS: readonly SafetyErrorKind[];
+export interface SafetyError {
+    /** OpenZeppelin's error kind, such as `constructor`. */
+    kind: SafetyErrorKind;
+    /** Where, as `file.sol:line`. */
+    src: string;
+}
+export interface SafetyOptions {
+    /**
+     * The proxy being upgraded; only `uups` requires an `upgradeToAndCall`.
+     * Required: the new contract's own `kind` would let a UUPS implementation
+     * that lost its upgrade function pass.
+     */
+    kind: ProxyKind;
+    /** Error kinds to accept anyway (OZ's `unsafeAllow`). Prefer NatSpec exceptions in the source. */
+    unsafeAllow?: SafetyErrorKind[];
+}
+export interface SafetyReport {
+    ok: boolean;
+    errors: SafetyError[];
+    /** OpenZeppelin's description of each error. */
+    explain(): string;
+}
+export interface SourceAnalysis {
+    layout: StorageLayout;
+    /** `uups` when the contract has `upgradeTo` or `upgradeToAndCall`, else `transparent`. */
+    kind: Exclude<ProxyKind, "beacon">;
+    /**
+     * The slot each ERC-7201 namespace really uses, read from the code
+     * (`$.slot := LOCATION`); OpenZeppelin trusts the annotation alone.
+     */
+    namespaces: NamespaceSlot[];
+    /**
+     * OpenZeppelin's safety check (constructors, `selfdestruct`,
+     * `delegatecall`, initial values, immutables, initializers), honoring
+     * `@custom:oz-upgrades-unsafe-allow` in the source.
+     */
+    safety(options: SafetyOptions): SafetyReport;
+}
+/** `layoutFromSource` plus OpenZeppelin's safety check, from one compile. */
+export declare function analyzeSource(input: SolcInput, solc: SolcRunner, contract: string): Promise<SourceAnalysis>;
 //# sourceMappingURL=reconstruct.d.ts.map

package/dist/reconstruct.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"reconstruct.d.ts","sourceRoot":"","sources":["../src/reconstruct.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAOL,KAAK,SAAS,EAEd,KAAK,aAAa,EACnB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAA2C,KAAK,YAAY,EAAE,MAAM,eAAe,CAAC;AAE3F,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAE5C,MAAM,WAAW,mBAAmB;IAClC,mDAAmD;IACnD,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,YAAY,CAAC;IAC5B,MAAM,EAAE,aAAa,CAAC;CACvB;AAoBD,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,cAAc,EACtB,IAAI,EAAE,UAAU,EAChB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,mBAAmB,CAAC,CAiB9B;AAED;;;;GAIG;AACH,wBAAsB,gBAAgB,CACpC,KAAK,EAAE,SAAS,EAChB,IAAI,EAAE,UAAU,EAChB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,aAAa,CAAC,CAIxB"}
+{"version":3,"file":"reconstruct.d.ts","sourceRoot":"","sources":["../src/reconstruct.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAUL,KAAK,eAAe,EACpB,KAAK,SAAS,EAEd,KAAK,aAAa,EAGnB,MAAM,6BAA6B,CAAC;AAErC,OAAO,EAAc,KAAK,eAAe,EAAE,MAAM,kDAAkD,CAAC;AACpG,OAAO,EAA2C,KAAK,YAAY,EAAE,MAAM,eAAe,CAAC;AAC3F,OAAO,EAAkB,KAAK,aAAa,EAAE,MAAM,cAAc,CAAC;AAElE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAE5C,MAAM,WAAW,mBAAoB,SAAQ,cAAc;IACzD,mDAAmD;IACnD,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,YAAY,CAAC;CAC7B;AAoBD,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,cAAc,EACtB,IAAI,EAAE,UAAU,EAChB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,mBAAmB,CAAC,CAiB9B;AAED;;;;GAIG;AACH,wBAAsB,gBAAgB,CACpC,KAAK,EAAE,SAAS,EAChB,IAAI,EAAE,UAAU,EAChB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,aAAa,CAAC,CAExB;AAED,MAAM,MAAM,SAAS,GAAG,eAAe,CAAC,MAAM,CAAC,CAAC;AAEhD;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG,OAAO,CACnC,eAAe,CAAC,MAAM,CAAC,EACvB,mBAAmB,GAAG,iBAAiB,CACxC,CAAC;AAEF,eAAO,MAAM,kBAAkB,EAAE,SAAS,eAAe,EAExD,CAAC;AAEF,MAAM,WAAW,WAAW;IAC1B,wDAAwD;IACxD,IAAI,EAAE,eAAe,CAAC;IACtB,iCAAiC;IACjC,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,aAAa;IAC5B;;;;OAIG;IACH,IAAI,EAAE,SAAS,CAAC;IAChB,kGAAkG;IAClG,WAAW,CAAC,EAAE,eAAe,EAAE,CAAC;CACjC;AAED,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,gDAAgD;IAChD,OAAO,IAAI,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,aAAa,CAAC;IACtB,0FAA0F;IAC1F,IAAI,EAAE,OAAO,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;IACnC;;;OAGG;IACH,UAAU,EAAE,aAAa,EAAE,CAAC;IAC5B;;;;OAIG;IACH,MAAM,CAAC,OAAO,EAAE,aAAa,GAAG,YAAY,CAAC;CAC9C;AAED,6EAA6E;AAC7E,wBAAsB,aAAa,CACjC,KAAK,EAAE,SAAS,EAChB,IAAI,EAAE,UAAU,EAChB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,cAAc,CAAC,CAGzB"}

package/dist/reconstruct.js

@@ -6,8 +6,11 @@
  * the local build (full compile, namespaced second pass, `validate()`,
  * `getStorageLayout`), so both sides of a comparison are extracted identically.
  */
-import { getStorageLayout, isNamespaceSupported, makeNamespacedInput, solcInputOutputDecoder, trySanitizeNatSpec, validate, } from "@openzeppelin/upgrades-core";
+import { getErrors, getStorageLayout, inferProxyKind, isNamespaceSupported, makeNamespacedInput, solcInputOutputDecoder, trySanitizeNatSpec, UpgradeableContractErrorReport, validate, } from "@openzeppelin/upgrades-core";
+// Not exported from the package index; the package has no exports map.
+import { errorKinds } from "@openzeppelin/upgrades-core/dist/validate/run.js";
 import { compareDeployedBytecode, isProvingMatch } from "./bytecode.js";
+import { namespaceSlots } from "./erc7201.js";
 import { LayoutIntegrityError } from "./errors.js";
 // validate() reads evm.bytecode for every contract, so codegen is requested
 // for all of them. A verified input holds only the target's dependency graph.
@@ -33,7 +36,7 @@ export async function reconstructLayout(source, solc, onchainCode) {
         contract,
         compiler: source.solcLongVersion,
         bytecodeMatch,
-        layout: await extractLayout(input, output, solc, contract),
+        ...(await analyze(input, output, solc, contract)),
     };
 }
 /**
@@ -42,11 +45,36 @@ export async function reconstructLayout(source, solc, onchainCode) {
  * project's own build-info.
  */
 export async function layoutFromSource(input, solc, contract) {
+    return (await analyzeSource(input, solc, contract)).layout;
+}
+export const SAFETY_ERROR_KINDS = errorKinds.filter((k) => k !== "struct-definition" && k !== "enum-definition");
+/** `layoutFromSource` plus OpenZeppelin's safety check, from one compile. */
+export async function analyzeSource(input, solc, contract) {
     const selected = withOutputSelection(input, FULL_SELECTION);
-    const output = await compileOrThrow(solc, selected, "source");
-    return extractLayout(selected, output, solc, contract);
+    return analyze(selected, await compileOrThrow(solc, selected, "source"), solc, contract);
+}
+async function analyze(input, output, solc, contract) {
+    const { data, version } = await validateContract(input, output, solc, contract);
+    const layout = getStorageLayout(data, version);
+    return {
+        layout,
+        // Typed as any ProxyKind, but only ever uups or transparent.
+        kind: inferProxyKind(data, version),
+        namespaces: namespaceSlots(output, contract, Object.keys(layout.namespaces ?? {})),
+        safety({ kind, unsafeAllow = [] }) {
+            // A copy: OpenZeppelin appends to the array it is given.
+            const opts = { kind, unsafeAllow: [...unsafeAllow] };
+            // The deprecated kinds are never reported, so every error has a SafetyErrorKind.
+            const errors = getErrors(data, version, opts);
+            return {
+                ok: errors.length === 0,
+                errors,
+                explain: () => new UpgradeableContractErrorReport(errors).explain(),
+            };
+        },
+    };
 }
-async function extractLayout(input, output, solc, contract) {
+async function validateContract(input, output, solc, contract) {
     const solcVersion = solc.longVersion.split("+")[0];
     let namespacedOutput;
     if (isNamespaceSupported(solcVersion)) {
@@ -57,12 +85,13 @@ async function extractLayout(input, output, solc, contract) {
     const runData = validate(output, solcInputOutputDecoder(input, output), solcVersion, input, namespacedOutput);
     const version = runData[contract]?.version;
     if (version === undefined) {
-        throw new LayoutIntegrityError(`${contract} compiled to no bytecode; cannot derive its layout.`);
+        throw new LayoutIntegrityError(`${contract} compiled to no bytecode (an abstract contract or interface?); ` +
+            `cannot derive its layout.`);
     }
     // OZ looks the contract up by bytecode version and takes the first match, so
     // two contracts with identical code (possible without a source hash) could
-    // swap layouts. Listing the target first makes the lookup land on it.
-    return getStorageLayout({ [contract]: runData[contract], ...runData }, version);
+    // swap layouts or safety errors. Listing the target first makes every lookup land on it.
+    return { data: { [contract]: runData[contract], ...runData }, version };
 }
 /**
  * Finds the compiled contract that matches the deployed code. The verified