@bananapus/nana-sdk-core 2.12.2 → 2.13.0

package/dist/esm/review/contractWrite.js

@@ -0,0 +1,54 @@
+import { BaseError, UserRejectedRequestError } from "viem";
+/**
+ * Shared review-to-wallet boundary for direct contract writes.
+ *
+ * The exact request object accepted by review is also handed to simulation,
+ * and only the simulation result reaches the wallet writer. Account identity
+ * is checked after a chain switch and again immediately before signing.
+ */
+export async function submitReviewedContractWrite({ request, expectedAccount, review, switchChain, currentAccount, simulate, reverify, beforeWrite, onBeforeWriteAborted, onWriteRejected, write, onPhase, accountChangedError = "Connected account changed. Review the transaction again.", guard, }) {
+    guard?.();
+    if (!expectedAccount)
+        throw new Error("Connect a wallet first.");
+    onPhase?.("review");
+    await review(request);
+    onPhase?.("simulating");
+    await switchChain(request.chainId);
+    assertExpectedAccount(currentAccount(), expectedAccount, accountChangedError);
+    await reverify?.(request);
+    assertExpectedAccount(currentAccount(), expectedAccount, accountChangedError);
+    const simulated = await simulate(request);
+    assertExpectedAccount(currentAccount(), expectedAccount, accountChangedError);
+    if (beforeWrite) {
+        await beforeWrite();
+        try {
+            assertExpectedAccount(currentAccount(), expectedAccount, accountChangedError);
+        }
+        catch (error) {
+            // This is strictly before the wallet writer is invoked. An ambiguous
+            // write error must never reach this cleanup path.
+            await onBeforeWriteAborted?.();
+            throw error;
+        }
+    }
+    onPhase?.("signing");
+    try {
+        return await write(simulated);
+    }
+    catch (error) {
+        // The same-looking error from review/simulation never reaches this catch.
+        // An RPC timeout or ambiguous submission must preserve the recovery lock.
+        const rejected = error instanceof UserRejectedRequestError ||
+            (error instanceof BaseError &&
+                error.walk((cause) => cause instanceof UserRejectedRequestError) instanceof UserRejectedRequestError);
+        if (rejected)
+            await onWriteRejected?.();
+        throw error;
+    }
+}
+function assertExpectedAccount(current, expected, message) {
+    if (!current || current.toLowerCase() !== expected.toLowerCase()) {
+        throw new Error(message);
+    }
+}
+//# sourceMappingURL=contractWrite.js.map

package/dist/esm/review/contractWrite.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contractWrite.js","sourceRoot":"","sources":["../../../src/review/contractWrite.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,wBAAwB,EAAgB,MAAM,MAAM,CAAC;AAgCzE;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,2BAA2B,CAI/C,EACA,OAAO,EACP,eAAe,EACf,MAAM,EACN,WAAW,EACX,cAAc,EACd,QAAQ,EACR,QAAQ,EACR,WAAW,EACX,oBAAoB,EACpB,eAAe,EACf,KAAK,EACL,OAAO,EACP,mBAAmB,GAAG,0DAA0D,EAChF,KAAK,GACqD;IAC1D,KAAK,EAAE,EAAE,CAAC;IACV,IAAI,CAAC,eAAe;QAAE,MAAM,IAAI,KAAK,CAAC,yBAAyB,CAAC,CAAC;IAEjE,OAAO,EAAE,CAAC,QAAQ,CAAC,CAAC;IACpB,MAAM,MAAM,CAAC,OAAO,CAAC,CAAC;IAEtB,OAAO,EAAE,CAAC,YAAY,CAAC,CAAC;IACxB,MAAM,WAAW,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IACnC,qBAAqB,CAAC,cAAc,EAAE,EAAE,eAAe,EAAE,mBAAmB,CAAC,CAAC;IAC9E,MAAM,QAAQ,EAAE,CAAC,OAAO,CAAC,CAAC;IAC1B,qBAAqB,CAAC,cAAc,EAAE,EAAE,eAAe,EAAE,mBAAmB,CAAC,CAAC;IAE9E,MAAM,SAAS,GAAG,MAAM,QAAQ,CAAC,OAAO,CAAC,CAAC;IAC1C,qBAAqB,CAAC,cAAc,EAAE,EAAE,eAAe,EAAE,mBAAmB,CAAC,CAAC;IAE9E,IAAI,WAAW,EAAE,CAAC;QAChB,MAAM,WAAW,EAAE,CAAC;QACpB,IAAI,CAAC;YACH,qBAAqB,CACnB,cAAc,EAAE,EAChB,eAAe,EACf,mBAAmB,CACpB,CAAC;QACJ,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,qEAAqE;YACrE,kDAAkD;YAClD,MAAM,oBAAoB,EAAE,EAAE,CAAC;YAC/B,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;IAED,OAAO,EAAE,CAAC,SAAS,CAAC,CAAC;IACrB,IAAI,CAAC;QACH,OAAO,MAAM,KAAK,CAAC,SAAS,CAAC,CAAC;IAChC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,0EAA0E;QAC1E,0EAA0E;QAC1E,MAAM,QAAQ,GACZ,KAAK,YAAY,wBAAwB;YACzC,CAAC,KAAK,YAAY,SAAS;gBACzB,KAAK,CAAC,IAAI,CACR,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,YAAY,wBAAwB,CACrD,YAAY,wBAAwB,CAAC,CAAC;QAC3C,IAAI,QAAQ;YAAE,MAAM,eAAe,EAAE,EAAE,CAAC;QACxC,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC;AAED,SAAS,qBAAqB,CAC5B,OAA4B,EAC5B,QAAiB,EACjB,OAAe;IAEf,IAAI,CAAC,OAAO,IAAI,OAAO,CAAC,WAAW,EAAE,KAAK,QAAQ,CAAC,WAAW,EAAE,EAAE,CAAC;QACjE,MAAM,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC;IAC3B,CAAC;AACH,CAAC"}

package/dist/esm/review/gas.d.ts

@@ -0,0 +1,28 @@
+import type { Address, Hex, PublicClient } from "viem";
+/**
+ * Wallet gas limits are deliberately twice the latest RPC estimate.
+ *
+ * Some Juicebox terminal calls catch a failed internal fee payment and keep
+ * going. An RPC can therefore return an estimate for that cheaper recovery
+ * path even though the intended fee route needs more gas. Unused gas is not
+ * spent, so a 2x limit is a cheap guard against that under-estimation.
+ */
+export declare function gasWithHeadroom(estimate: bigint): bigint;
+/**
+ * The gas limit to send for a call that carries a reviewed cap.
+ *
+ * A cap bounds an `eth_call` against a target-controlled contract; it is not
+ * what the call costs. Wallets reject a transaction whose `gas * maxFeePerGas`
+ * exceeds the balance, so sending the cap itself turns a 1M-gas mainnet cap
+ * into a ~0.003 ETH balance requirement for a call that burns a tenth of that.
+ *
+ * Measurement stays bounded by the cap, and the cap survives when the node
+ * cannot measure.
+ */
+export declare function gasWithinCap(client: PublicClient, tx: {
+    account: Address;
+    to: Address;
+    data: Hex;
+    value?: bigint;
+}, cap?: bigint): Promise<bigint | undefined>;
+//# sourceMappingURL=gas.d.ts.map

package/dist/esm/review/gas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gas.d.ts","sourceRoot":"","sources":["../../../src/review/gas.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,YAAY,EAAE,MAAM,MAAM,CAAC;AAEvD;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAExD;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,YAAY,CAChC,MAAM,EAAE,YAAY,EACpB,EAAE,EAAE;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,EAAE,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,GAAG,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,EAChE,GAAG,CAAC,EAAE,MAAM,GACX,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAW7B"}

package/dist/esm/review/gas.js

@@ -0,0 +1,36 @@
+/**
+ * Wallet gas limits are deliberately twice the latest RPC estimate.
+ *
+ * Some Juicebox terminal calls catch a failed internal fee payment and keep
+ * going. An RPC can therefore return an estimate for that cheaper recovery
+ * path even though the intended fee route needs more gas. Unused gas is not
+ * spent, so a 2x limit is a cheap guard against that under-estimation.
+ */
+export function gasWithHeadroom(estimate) {
+    return estimate * 2n;
+}
+/**
+ * The gas limit to send for a call that carries a reviewed cap.
+ *
+ * A cap bounds an `eth_call` against a target-controlled contract; it is not
+ * what the call costs. Wallets reject a transaction whose `gas * maxFeePerGas`
+ * exceeds the balance, so sending the cap itself turns a 1M-gas mainnet cap
+ * into a ~0.003 ETH balance requirement for a call that burns a tenth of that.
+ *
+ * Measurement stays bounded by the cap, and the cap survives when the node
+ * cannot measure.
+ */
+export async function gasWithinCap(client, tx, cap) {
+    try {
+        const estimate = await client.estimateGas({
+            ...tx,
+            ...(cap === undefined ? {} : { gas: cap }),
+        });
+        const measured = gasWithHeadroom(estimate);
+        return cap !== undefined && cap < measured ? cap : measured;
+    }
+    catch {
+        return cap;
+    }
+}
+//# sourceMappingURL=gas.js.map

package/dist/esm/review/gas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gas.js","sourceRoot":"","sources":["../../../src/review/gas.ts"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAAC,QAAgB;IAC9C,OAAO,QAAQ,GAAG,EAAE,CAAC;AACvB,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,MAAoB,EACpB,EAAgE,EAChE,GAAY;IAEZ,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,WAAW,CAAC;YACxC,GAAG,EAAE;YACL,GAAG,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC;SAC3C,CAAC,CAAC;QACH,MAAM,QAAQ,GAAG,eAAe,CAAC,QAAQ,CAAC,CAAC;QAC3C,OAAO,GAAG,KAAK,SAAS,IAAI,GAAG,GAAG,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC;IAC9D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,GAAG,CAAC;IACb,CAAC;AACH,CAAC"}

package/dist/esm/review/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./contractWrite.js";
+export * from "./gas.js";
+export * from "./transactionReview.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/review/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/review/index.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC;AACnC,cAAc,UAAU,CAAC;AACzB,cAAc,wBAAwB,CAAC"}

package/dist/esm/review/index.js

@@ -0,0 +1,4 @@
+export * from "./contractWrite.js";
+export * from "./gas.js";
+export * from "./transactionReview.js";
+//# sourceMappingURL=index.js.map

package/dist/esm/review/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/review/index.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC;AACnC,cAAc,UAAU,CAAC;AACzB,cAAc,wBAAwB,CAAC"}

package/dist/esm/review/transactionReview.d.ts

@@ -0,0 +1,81 @@
+import { type Abi, type Address, type Hex } from "viem";
+/**
+ * How review prompts name a chain and link its explorer. Apps pass their own
+ * chain display, which also keeps a chain table out of the review bundle.
+ */
+export type TransactionReviewDisplay = {
+    chainName: (chainId: number) => string;
+    explorerOrigin: (chainId: number) => string | null;
+};
+export type TransactionReviewCall = {
+    chainId: number;
+    to: Address;
+    data: Hex;
+    value?: bigint;
+    from?: Address;
+    abi?: Abi;
+    functionName?: string;
+    args?: readonly unknown[];
+    /** Plain-language action shown above the decoded call. */
+    label?: string;
+    /** Optional known contract name. The full address is always shown too. */
+    contractName?: string;
+    /** The calls a batching destination (MultiSend) makes in order, decoded by the caller. */
+    calls?: readonly TransactionReviewCall[];
+};
+export type TransactionReviewRequest = {
+    calls: readonly TransactionReviewCall[];
+    title?: string;
+    description?: string;
+    confirmLabel?: string;
+    /** Distinguishes a wallet transaction from an authorization which a relayer/Safe will submit. */
+    kind?: "transaction" | "authorization";
+    /** Exact typed data committed by a Safe/relayer signature, when applicable. */
+    authorization?: unknown;
+};
+export type ContractTransactionReviewCall = {
+    chainId: number;
+    address: Address;
+    abi: Abi;
+    functionName: string;
+    args?: readonly unknown[];
+    value?: bigint;
+    account?: Address;
+};
+export type TransactionReviewOptions = Omit<TransactionReviewRequest, "calls"> & {
+    label?: string;
+    contractName?: string;
+};
+type TransactionReviewHandler = (request: TransactionReviewRequest) => Promise<boolean>;
+export type FundingChainOption = {
+    chainId: number;
+    /** The chain name and quoted funding cost shown to the user. */
+    label: string;
+};
+type FundingChainSelectionHandler = (options: readonly FundingChainOption[]) => Promise<number | null>;
+export declare function registerFundingChainSelectionHandler(handler: FundingChainSelectionHandler): () => void;
+/** Funding always requires an explicit choice, even with one quoted option. */
+export declare function requireFundingChainSelection(options: readonly FundingChainOption[]): Promise<number>;
+/**
+ * The provider registers the only UI capable of approving a transaction.
+ * Keeping the entry point in a small client module lets non-React wallet
+ * helpers (Safe and Relayr) use the same mandatory review queue.
+ */
+export declare function registerTransactionReviewHandler(handler: TransactionReviewHandler): () => void;
+export declare function requestContractTransactionReview(call: ContractTransactionReviewCall, options?: TransactionReviewOptions): Promise<boolean>;
+export declare function requireTransactionReview(request: TransactionReviewRequest): Promise<void>;
+export declare function requireContractTransactionReview(call: ContractTransactionReviewCall, options?: TransactionReviewOptions): Promise<void>;
+export declare function transactionReviewJson(request: TransactionReviewRequest): string;
+/**
+ * The post-transaction counterpart of the review prompt: a mined tx the user
+ * wants explained (or diagnosed) from explorer evidence. Points at Etherscan's
+ * transaction-debugger skill when the reader's agent has it, and degrades to
+ * the explorer page when it doesn't.
+ */
+export declare function buildTransactionDebugPrompt(calls: {
+    chainId: number;
+    txHash: string;
+}[], { chainName: displayChainName, explorerOrigin }: TransactionReviewDisplay): string;
+export declare function buildTransactionReviewPrompt(request: TransactionReviewRequest, { explorerOrigin }: Pick<TransactionReviewDisplay, "explorerOrigin">): string;
+export {};
+//# sourceMappingURL=transactionReview.d.ts.map

package/dist/esm/review/transactionReview.d.ts.map

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

package/dist/esm/review/transactionReview.js

@@ -0,0 +1,192 @@
+"use client";
+import { encodeFunctionData } from "viem";
+const transactionReviewHandlers = [];
+const fundingChainSelectionHandlers = [];
+export function registerFundingChainSelectionHandler(handler) {
+    fundingChainSelectionHandlers.push(handler);
+    return () => {
+        const index = fundingChainSelectionHandlers.lastIndexOf(handler);
+        if (index >= 0)
+            fundingChainSelectionHandlers.splice(index, 1);
+    };
+}
+/** Funding always requires an explicit choice, even with one quoted option. */
+export async function requireFundingChainSelection(options) {
+    const snapshot = options.map((option) => ({ ...option }));
+    const chainIds = new Set(snapshot.map((option) => option.chainId));
+    if (!snapshot.length ||
+        chainIds.size !== snapshot.length ||
+        snapshot.some((option) => !Number.isSafeInteger(option.chainId) ||
+            option.chainId <= 0 ||
+            !option.label.trim())) {
+        throw new Error("No valid funding chain choices are available. Request a new quote.");
+    }
+    const handler = fundingChainSelectionHandlers[fundingChainSelectionHandlers.length - 1];
+    if (!handler) {
+        throw new Error("Funding chain selection is unavailable. Reload the page before continuing.");
+    }
+    const selected = await handler(snapshot);
+    if (selected === null) {
+        throw new Error("Funding chain selection cancelled. Nothing was sent.");
+    }
+    if (!chainIds.has(selected)) {
+        throw new Error("The selected funding chain is not available in this quote.");
+    }
+    return selected;
+}
+/**
+ * The provider registers the only UI capable of approving a transaction.
+ * Keeping the entry point in a small client module lets non-React wallet
+ * helpers (Safe and Relayr) use the same mandatory review queue.
+ */
+export function registerTransactionReviewHandler(handler) {
+    transactionReviewHandlers.push(handler);
+    return () => {
+        const index = transactionReviewHandlers.lastIndexOf(handler);
+        if (index >= 0)
+            transactionReviewHandlers.splice(index, 1);
+    };
+}
+async function requestTransactionReview(request) {
+    if (!request.calls.length && !request.authorization) {
+        throw new Error("There is no transaction to review.");
+    }
+    const transactionReviewHandler = transactionReviewHandlers[transactionReviewHandlers.length - 1];
+    if (!transactionReviewHandler) {
+        throw new Error("Transaction review is unavailable. Reload the page before continuing.");
+    }
+    return transactionReviewHandler(request);
+}
+/** Encode once for review using the same ABI/function/args passed to wagmi. */
+function contractCallForReview(call, options = {}) {
+    const data = encodeFunctionData({
+        abi: call.abi,
+        functionName: call.functionName,
+        args: call.args,
+    });
+    return {
+        chainId: call.chainId,
+        to: call.address,
+        data,
+        value: call.value,
+        from: call.account,
+        abi: call.abi,
+        functionName: call.functionName,
+        args: call.args,
+        label: options.label,
+        contractName: options.contractName,
+    };
+}
+export function requestContractTransactionReview(call, options = {}) {
+    const { label, contractName, ...requestOptions } = options;
+    const reviewed = contractCallForReview(call, { label, contractName });
+    return requestTransactionReview({
+        ...requestOptions,
+        calls: [reviewed],
+    }).then((approved) => {
+        if (!approved)
+            return false;
+        const current = contractCallForReview(call, { label, contractName });
+        if (current.chainId !== reviewed.chainId ||
+            current.to.toLowerCase() !== reviewed.to.toLowerCase() ||
+            (current.value ?? 0n) !== (reviewed.value ?? 0n) ||
+            current.data !== reviewed.data) {
+            throw new Error("Transaction data changed after review. Nothing was sent; review it again.");
+        }
+        return true;
+    });
+}
+class TransactionReviewCancelledError extends Error {
+    constructor() {
+        super("Review closed. Nothing was sent.");
+        this.name = "TransactionReviewCancelledError";
+    }
+}
+export async function requireTransactionReview(request) {
+    if (!(await requestTransactionReview(request))) {
+        throw new TransactionReviewCancelledError();
+    }
+}
+export async function requireContractTransactionReview(call, options = {}) {
+    if (!(await requestContractTransactionReview(call, options))) {
+        throw new TransactionReviewCancelledError();
+    }
+}
+export function transactionReviewJson(request) {
+    const transactions = request.calls.map((call) => ({
+        chainId: call.chainId,
+        from: call.from,
+        to: call.to,
+        value: `0x${(call.value ?? 0n).toString(16)}`,
+        data: call.data,
+    }));
+    const calls = transactions.length === 1 ? transactions[0] : { transactions };
+    const payload = request.authorization
+        ? transactions.length > 0
+            ? { authorization: request.authorization, resultingCall: calls }
+            : { authorization: request.authorization }
+        : calls;
+    return JSON.stringify(payload, (_, value) => (typeof value === "bigint" ? value.toString() : value), 2);
+}
+/** A website/-style prompt which keeps the exact reviewed RPC call intact. */
+const ETHERSCAN_SKILL_LINE = "If your agent has Etherscan's skills installed (`npx skills add etherscan/skills`), run `etherscan-contract-review` on each target address to pull its verified source, proxy roles, and privileged controls before decoding. Otherwise work from the explorer pages.";
+/**
+ * The post-transaction counterpart of the review prompt: a mined tx the user
+ * wants explained (or diagnosed) from explorer evidence. Points at Etherscan's
+ * transaction-debugger skill when the reader's agent has it, and degrades to
+ * the explorer page when it doesn't.
+ */
+export function buildTransactionDebugPrompt(calls, { chainName: displayChainName, explorerOrigin }) {
+    const lines = [
+        "A Juicebox V6 transaction (the nana V6 / revnet V6 protocol release, not an older Juicebox version) was mined. Explain what happened in it and whether it did what a Juicebox user would expect.",
+        "",
+    ];
+    calls.forEach((call) => {
+        const explorer = explorerOrigin(call.chainId);
+        lines.push(`- ${displayChainName(call.chainId)} (chain ${call.chainId}): ${explorer ? `${explorer}/tx/${call.txHash}` : call.txHash}`);
+    });
+    lines.push("", "If your agent has Etherscan's skills installed (`npx skills add etherscan/skills`), use `etherscan-transaction-debugger` in security mode on each hash. Otherwise work from the explorer page: receipt status, decoded input, event logs, and internal transactions.", "", "Verify contract source only against the Juicebox V6 repositories: https://github.com/Bananapus/version-6 (repositories ending in `-v6`; same-named repositories without that suffix are older versions).", "", "Report the decoded method and arguments, every native and token movement with its recipient, every permission, ownership, or ruleset change, and, if it reverted, the narrowest root cause the evidence supports. Mark each claim observed, derived, or inferred. Never invent a function name, amount, or revert reason. End with one line: what the transaction did in plain English, and anything that looks wrong.");
+    return lines.join("\n");
+}
+export function buildTransactionReviewPrompt(request, { explorerOrigin }) {
+    const lines = [
+        "I'm about to authorize a blockchain transaction in the Juicebox V6 app (the nana V6 / revnet V6 protocol release, not an older Juicebox version). Act as a careful security reviewer. Independently verify the payload against the deployed contracts and V6 source, confirm it matches my intent, and give a go/no-go. Assume the UI could be spoofed; trust the onchain call and verified V6 source over the page.",
+        "",
+        "Exact app-controlled transaction payload:",
+        "```json",
+        transactionReviewJson(request),
+        "```",
+        "",
+    ];
+    if (typeof window !== "undefined") {
+        lines.push("Audit the app build I am using:");
+        lines.push(`- Page: ${window.location.href}`);
+        lines.push("- Confirm this page builds exactly the destination, native value, and calldata above, with no hidden or substituted call.");
+        lines.push("");
+    }
+    lines.push("Verify the contracts and protocol version:");
+    lines.push("- Juicebox V6 ecosystem source: https://github.com/Bananapus/version-6");
+    lines.push("- Use only V6 repositories (normally ending in `-v6`); same-named repositories without that suffix may be older and incompatible.");
+    lines.push(`- ${ETHERSCAN_SKILL_LINE}`);
+    request.calls.forEach((call, index) => {
+        // Apps pass their one explorer registry; a second copy once drifted on OP mainnet.
+        const explorer = explorerOrigin(call.chainId);
+        const prefix = request.calls.length > 1 ? `Transaction ${index + 1}` : "Target";
+        lines.push(explorer
+            ? `- ${prefix} onchain: ${explorer}/address/${call.to}`
+            : `- ${prefix}: chain ${call.chainId}, address ${call.to}`);
+    });
+    lines.push("");
+    lines.push("Check specifically:");
+    lines.push("1. Decode the calldata selector and every argument. Explain in plain English what state, permissions, ownership, tokens, or funds can change.");
+    lines.push("2. Verify the chain ID, `to` address, native `value`, and calldata exactly. Flag any unexpected non-zero value or unknown target.");
+    lines.push("3. Identify every beneficiary, recipient, spender, operator, owner, hook, terminal, and permission-bearing address in the decoded arguments.");
+    lines.push("4. Warn about unlimited approvals, arbitrary-call capability, delegatecalls, ownership transfers, permission grants, upgradeability, or drain paths.");
+    lines.push("5. For multiple chains, confirm the intended change is consistent and that no extra chain or call was added.");
+    lines.push("");
+    lines.push("Before your verdict, quiz me with 2–4 short plain-English questions about what I expect to happen (what changes, who receives or controls what, how much value moves, and on which chain). Wait for my answers, compare them with the decoded payload, and flag every mismatch.");
+    lines.push("");
+    lines.push("End with one verdict: SAFE TO SIGN / DO NOT SIGN / NEEDS MORE INFO, followed by the most important reasons. If the target is not a recognizable verified Juicebox V6 deployment, say so explicitly.");
+    return lines.join("\n");
+}
+//# sourceMappingURL=transactionReview.js.map

package/dist/esm/review/transactionReview.js.map

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

package/dist/esm/safeService.d.ts

@@ -0,0 +1,36 @@
+import type { Address, Hex } from "viem";
+/**
+ * Safe's per-chain app URL prefix. Wider than {@link SAFE_SERVICE_PREFIX}:
+ * Safe app links work on chains without a hosted transaction service.
+ */
+export declare const SAFE_PREFIX: Partial<Record<number, string>>;
+/**
+ * Chains with a HOSTED Safe Transaction Service — a smaller set than the
+ * chains Safe app links work on: `api.safe.global/tx-service/{opsepolia,
+ * arb1-sep}` both 404, while `basesep` is live. Probed against
+ * `/api/v1/about/`. This split from {@link SAFE_PREFIX} is DELIBERATE:
+ * conflating the two maps is what made service calls fire at chains with
+ * none. Every tx-service URL must come from here, never from `SAFE_PREFIX`.
+ */
+export declare const SAFE_SERVICE_PREFIX: Partial<Record<number, string>>;
+/** The Safe Transaction Service base URL for a chain, honoring the
+ *  `jb-safe-tx-base` localStorage override; null when the chain has none. */
+export declare function safeServiceBase(chainId: number): string | null;
+export declare const SAFE_NONCE_GUIDANCE = "On Safe\u2019s confirmation screen, Nonce defaults to the next available value. Open its dropdown to see queued nonces and replace one if desired.";
+/** The unix deadline for a swap/liquidity transaction proposed now. */
+export declare function swapDeadline(isSafe: boolean, nowMs?: number): bigint;
+export declare function safeQueueUrl(chainId: number, safe: Address): string | null;
+/**
+ * Resolve a Safe proposal identifier to its actual onchain execution hash.
+ * A safeTxHash is not a transaction hash and must never be receipt-polled.
+ *
+ * The polling URL comes from {@link safeServiceBase} (the hosted-service
+ * map), NOT `SAFE_PREFIX`: OP Sepolia and Arbitrum Sepolia have Safe app
+ * URLs but no hosted transaction service, and polling a nonexistent service
+ * left every Safe write there pending forever.
+ */
+export declare function waitForSafeExecutionHash(chainId: number, safeTxHash: Hex, options?: {
+    pollingIntervalMs?: number;
+    signal?: AbortSignal;
+}): Promise<Hex>;
+//# sourceMappingURL=safeService.d.ts.map

package/dist/esm/safeService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"safeService.d.ts","sourceRoot":"","sources":["../../src/safeService.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,MAAM,CAAC;AAEzC;;;GAGG;AACH,eAAO,MAAM,WAAW,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CASvD,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAO/D,CAAC;AAEF;6EAC6E;AAC7E,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAW9D;AAED,eAAO,MAAM,mBAAmB,uJACiH,CAAC;AAUlJ,uEAAuE;AACvE,wBAAgB,YAAY,CAC1B,MAAM,EAAE,OAAO,EACf,KAAK,GAAE,MAAmB,GACzB,MAAM,CAKR;AAED,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAK1E;AAWD;;;;;;;;GAQG;AACH,wBAAsB,wBAAwB,CAC5C,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,GAAG,EACf,OAAO,GAAE;IAAE,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,WAAW,CAAA;CAAO,GACjE,OAAO,CAAC,GAAG,CAAC,CAiEd"}

package/dist/esm/safeService.js

@@ -0,0 +1,135 @@
+/**
+ * Safe's per-chain app URL prefix. Wider than {@link SAFE_SERVICE_PREFIX}:
+ * Safe app links work on chains without a hosted transaction service.
+ */
+export const SAFE_PREFIX = {
+    1: "eth",
+    10: "oeth",
+    8453: "base",
+    42161: "arb1",
+    11155111: "sep",
+    11155420: "opsepolia",
+    84532: "basesep",
+    421614: "arb1-sep",
+};
+/**
+ * Chains with a HOSTED Safe Transaction Service — a smaller set than the
+ * chains Safe app links work on: `api.safe.global/tx-service/{opsepolia,
+ * arb1-sep}` both 404, while `basesep` is live. Probed against
+ * `/api/v1/about/`. This split from {@link SAFE_PREFIX} is DELIBERATE:
+ * conflating the two maps is what made service calls fire at chains with
+ * none. Every tx-service URL must come from here, never from `SAFE_PREFIX`.
+ */
+export const SAFE_SERVICE_PREFIX = {
+    1: "eth",
+    10: "oeth",
+    8453: "base",
+    42161: "arb1",
+    11155111: "sep",
+    84532: "basesep",
+};
+/** The Safe Transaction Service base URL for a chain, honoring the
+ *  `jb-safe-tx-base` localStorage override; null when the chain has none. */
+export function safeServiceBase(chainId) {
+    try {
+        const custom = JSON.parse(globalThis.localStorage?.getItem("jb-safe-tx-base") ?? "null");
+        if (custom?.[chainId])
+            return custom[chainId].replace(/\/$/, "");
+    }
+    catch {
+        // Local overrides are optional.
+    }
+    const prefix = SAFE_SERVICE_PREFIX[chainId];
+    return prefix ? `https://api.safe.global/tx-service/${prefix}` : null;
+}
+export const SAFE_NONCE_GUIDANCE = "On Safe’s confirmation screen, Nonce defaults to the next available value. Open its dropdown to see queued nonces and replace one if desired.";
+/** Swap/mint execution deadline seconds: 20 minutes for an EOA, whose review
+ *  and signature are one sitting. */
+const SWAP_DEADLINE_SECONDS = 20 * 60;
+/** Safe deadline seconds: co-signer collection routinely outlives 20 minutes,
+ *  so match the 30-day Permit2 approval windows. The longer window widens MEV
+ *  exposure only within the swap's already-frozen slippage floor. */
+const SAFE_SWAP_DEADLINE_SECONDS = 30 * 24 * 60 * 60;
+/** The unix deadline for a swap/liquidity transaction proposed now. */
+export function swapDeadline(isSafe, nowMs = Date.now()) {
+    return BigInt(Math.floor(nowMs / 1000) +
+        (isSafe ? SAFE_SWAP_DEADLINE_SECONDS : SWAP_DEADLINE_SECONDS));
+}
+export function safeQueueUrl(chainId, safe) {
+    const prefix = SAFE_PREFIX[chainId];
+    return prefix
+        ? `https://app.safe.global/transactions/queue?safe=${prefix}:${safe}`
+        : null;
+}
+/**
+ * Consecutive 404s from the transaction service before the wait gives up. The
+ * service can lag a just-created proposal briefly, but a sustained 404 means
+ * it will never report this proposal (wrong network or an unhosted chain that
+ * slipped through) — polling forever just strands the flow at "pending".
+ * At the default 5s interval this is about a minute of patience.
+ */
+const SAFE_EXECUTION_NOT_FOUND_LIMIT = 12;
+/**
+ * Resolve a Safe proposal identifier to its actual onchain execution hash.
+ * A safeTxHash is not a transaction hash and must never be receipt-polled.
+ *
+ * The polling URL comes from {@link safeServiceBase} (the hosted-service
+ * map), NOT `SAFE_PREFIX`: OP Sepolia and Arbitrum Sepolia have Safe app
+ * URLs but no hosted transaction service, and polling a nonexistent service
+ * left every Safe write there pending forever.
+ */
+export async function waitForSafeExecutionHash(chainId, safeTxHash, options = {}) {
+    const base = safeServiceBase(chainId);
+    if (!base) {
+        throw new Error(`Safe does not host a transaction service on chain ${chainId}, so this proposal cannot be tracked here. Execute it from the Safe app; the action takes effect once it is executed there.`);
+    }
+    const interval = options.pollingIntervalMs ?? 5_000;
+    const endpoint = `${base}/api/v1/multisig-transactions/${safeTxHash}/`;
+    let consecutiveNotFound = 0;
+    for (;;) {
+        if (options.signal?.aborted) {
+            throw new DOMException("Safe execution wait aborted", "AbortError");
+        }
+        try {
+            const response = await fetch(endpoint);
+            if (response.ok) {
+                consecutiveNotFound = 0;
+                const transaction = (await response.json());
+                if (transaction.isExecuted && transaction.isSuccessful === false) {
+                    throw new Error("Safe executed the proposal, but the onchain transaction failed.");
+                }
+                if (transaction.isExecuted && transaction.transactionHash) {
+                    return transaction.transactionHash;
+                }
+            }
+            else if (response.status === 404) {
+                consecutiveNotFound += 1;
+                if (consecutiveNotFound >= SAFE_EXECUTION_NOT_FOUND_LIMIT) {
+                    throw new Error("Safe’s transaction service has no record of this proposal. Tracking cannot continue here — check the proposal in the Safe app; if it exists there, it will still take effect once executed.");
+                }
+            }
+        }
+        catch (error) {
+            if (error instanceof Error &&
+                /executed the proposal.*failed|no record of this proposal/i.test(error.message)) {
+                throw error;
+            }
+            // Other service/network failures are transient. Keep the already-created
+            // proposal pending instead of inviting a duplicate submission.
+        }
+        await new Promise((resolve, reject) => {
+            function onAbort() {
+                clearTimeout(timer);
+                reject(new DOMException("Safe execution wait aborted", "AbortError"));
+            }
+            const timer = setTimeout(() => {
+                options.signal?.removeEventListener("abort", onAbort);
+                resolve();
+            }, interval);
+            options.signal?.addEventListener("abort", onAbort, { once: true });
+            if (options.signal?.aborted)
+                onAbort();
+        });
+    }
+}
+//# sourceMappingURL=safeService.js.map

package/dist/esm/safeService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"safeService.js","sourceRoot":"","sources":["../../src/safeService.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,MAAM,CAAC,MAAM,WAAW,GAAoC;IAC1D,CAAC,EAAE,KAAK;IACR,EAAE,EAAE,MAAM;IACV,IAAI,EAAE,MAAM;IACZ,KAAK,EAAE,MAAM;IACb,QAAQ,EAAE,KAAK;IACf,QAAQ,EAAE,WAAW;IACrB,KAAK,EAAE,SAAS;IAChB,MAAM,EAAE,UAAU;CACnB,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAoC;IAClE,CAAC,EAAE,KAAK;IACR,EAAE,EAAE,MAAM;IACV,IAAI,EAAE,MAAM;IACZ,KAAK,EAAE,MAAM;IACb,QAAQ,EAAE,KAAK;IACf,KAAK,EAAE,SAAS;CACjB,CAAC;AAEF;6EAC6E;AAC7E,MAAM,UAAU,eAAe,CAAC,OAAe;IAC7C,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CACvB,UAAU,CAAC,YAAY,EAAE,OAAO,CAAC,iBAAiB,CAAC,IAAI,MAAM,CAC7B,CAAC;QACnC,IAAI,MAAM,EAAE,CAAC,OAAO,CAAC;YAAE,OAAO,MAAM,CAAC,OAAO,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IACnE,CAAC;IAAC,MAAM,CAAC;QACP,gCAAgC;IAClC,CAAC;IACD,MAAM,MAAM,GAAG,mBAAmB,CAAC,OAAO,CAAC,CAAC;IAC5C,OAAO,MAAM,CAAC,CAAC,CAAC,sCAAsC,MAAM,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;AACxE,CAAC;AAED,MAAM,CAAC,MAAM,mBAAmB,GAC9B,+IAA+I,CAAC;AAElJ;qCACqC;AACrC,MAAM,qBAAqB,GAAG,EAAE,GAAG,EAAE,CAAC;AACtC;;qEAEqE;AACrE,MAAM,0BAA0B,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC;AAErD,uEAAuE;AACvE,MAAM,UAAU,YAAY,CAC1B,MAAe,EACf,QAAgB,IAAI,CAAC,GAAG,EAAE;IAE1B,OAAO,MAAM,CACX,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,IAAI,CAAC;QACtB,CAAC,MAAM,CAAC,CAAC,CAAC,0BAA0B,CAAC,CAAC,CAAC,qBAAqB,CAAC,CAChE,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,OAAe,EAAE,IAAa;IACzD,MAAM,MAAM,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC;IACpC,OAAO,MAAM;QACX,CAAC,CAAC,mDAAmD,MAAM,IAAI,IAAI,EAAE;QACrE,CAAC,CAAC,IAAI,CAAC;AACX,CAAC;AAED;;;;;;GAMG;AACH,MAAM,8BAA8B,GAAG,EAAE,CAAC;AAE1C;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAC5C,OAAe,EACf,UAAe,EACf,UAAgE,EAAE;IAElE,MAAM,IAAI,GAAG,eAAe,CAAC,OAAO,CAAC,CAAC;IACtC,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,MAAM,IAAI,KAAK,CACb,qDAAqD,OAAO,6HAA6H,CAC1L,CAAC;IACJ,CAAC;IACD,MAAM,QAAQ,GAAG,OAAO,CAAC,iBAAiB,IAAI,KAAK,CAAC;IACpD,MAAM,QAAQ,GAAG,GAAG,IAAI,iCAAiC,UAAU,GAAG,CAAC;IACvE,IAAI,mBAAmB,GAAG,CAAC,CAAC;IAE5B,SAAS,CAAC;QACR,IAAI,OAAO,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC;YAC5B,MAAM,IAAI,YAAY,CAAC,6BAA6B,EAAE,YAAY,CAAC,CAAC;QACtE,CAAC;QACD,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,QAAQ,CAAC,CAAC;YACvC,IAAI,QAAQ,CAAC,EAAE,EAAE,CAAC;gBAChB,mBAAmB,GAAG,CAAC,CAAC;gBACxB,MAAM,WAAW,GAAG,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAIzC,CAAC;gBACF,IAAI,WAAW,CAAC,UAAU,IAAI,WAAW,CAAC,YAAY,KAAK,KAAK,EAAE,CAAC;oBACjE,MAAM,IAAI,KAAK,CACb,iEAAiE,CAClE,CAAC;gBACJ,CAAC;gBACD,IAAI,WAAW,CAAC,UAAU,IAAI,WAAW,CAAC,eAAe,EAAE,CAAC;oBAC1D,OAAO,WAAW,CAAC,eAAe,CAAC;gBACrC,CAAC;YACH,CAAC;iBAAM,IAAI,QAAQ,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;gBACnC,mBAAmB,IAAI,CAAC,CAAC;gBACzB,IAAI,mBAAmB,IAAI,8BAA8B,EAAE,CAAC;oBAC1D,MAAM,IAAI,KAAK,CACb,6LAA6L,CAC9L,CAAC;gBACJ,CAAC;YACH,CAAC;QACH,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IACE,KAAK,YAAY,KAAK;gBACtB,2DAA2D,CAAC,IAAI,CAC9D,KAAK,CAAC,OAAO,CACd,EACD,CAAC;gBACD,MAAM,KAAK,CAAC;YACd,CAAC;YACD,yEAAyE;YACzE,+DAA+D;QACjE,CAAC;QACD,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YAC1C,SAAS,OAAO;gBACd,YAAY,CAAC,KAAK,CAAC,CAAC;gBACpB,MAAM,CAAC,IAAI,YAAY,CAAC,6BAA6B,EAAE,YAAY,CAAC,CAAC,CAAC;YACxE,CAAC;YACD,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;gBAC5B,OAAO,CAAC,MAAM,EAAE,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;gBACtD,OAAO,EAAE,CAAC;YACZ,CAAC,EAAE,QAAQ,CAAC,CAAC;YACb,OAAO,CAAC,MAAM,EAAE,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;YACnE,IAAI,OAAO,CAAC,MAAM,EAAE,OAAO;gBAAE,OAAO,EAAE,CAAC;QACzC,CAAC,CAAC,CAAC;IACL,CAAC;AACH,CAAC"}