@bananapus/nana-sdk-core 2.12.2 → 2.14.0

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

@@ -0,0 +1,38 @@
+import { type Address } from "viem";
+export type ReviewedWritePhase = "review" | "simulating" | "signing";
+export type ReviewedContractWriteOptions<TRequest extends {
+    chainId: number;
+}, TSimulated, THash> = {
+    request: TRequest;
+    expectedAccount: Address | undefined;
+    review: (request: TRequest) => Promise<unknown>;
+    switchChain: (chainId: number) => Promise<unknown>;
+    currentAccount: () => Address | undefined;
+    simulate: (request: TRequest) => Promise<TSimulated>;
+    reverify?: (request: TRequest) => Promise<unknown>;
+    /** Persist recovery intent after simulation, before a wallet can broadcast. */
+    beforeWrite?: () => unknown | Promise<unknown>;
+    /** The persisted intent was rejected by a final gate before write was invoked. */
+    onBeforeWriteAborted?: () => unknown | Promise<unknown>;
+    /** Clear that intent only when the wallet explicitly rejects the write. */
+    onWriteRejected?: () => unknown | Promise<unknown>;
+    write: (simulated: TSimulated) => Promise<THash>;
+    onPhase?: (phase: ReviewedWritePhase) => void;
+    accountChangedError?: string;
+    /**
+     * An app-specific gate run before anything else, such as refusing writes while
+     * the app is impersonating another account. It throws to stop the write.
+     */
+    guard?: () => void;
+};
+/**
+ * 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 declare function submitReviewedContractWrite<TRequest extends {
+    chainId: number;
+}, TSimulated, THash>({ request, expectedAccount, review, switchChain, currentAccount, simulate, reverify, beforeWrite, onBeforeWriteAborted, onWriteRejected, write, onPhase, accountChangedError, guard, }: ReviewedContractWriteOptions<TRequest, TSimulated, THash>): Promise<THash>;
+//# sourceMappingURL=contractWrite.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"contractWrite.d.ts","sourceRoot":"","sources":["../../../src/review/contractWrite.ts"],"names":[],"mappings":"AAAA,OAAO,EAAuC,KAAK,OAAO,EAAE,MAAM,MAAM,CAAC;AAEzE,MAAM,MAAM,kBAAkB,GAAG,QAAQ,GAAG,YAAY,GAAG,SAAS,CAAC;AAErE,MAAM,MAAM,4BAA4B,CACtC,QAAQ,SAAS;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,EACpC,UAAU,EACV,KAAK,IACH;IACF,OAAO,EAAE,QAAQ,CAAC;IAClB,eAAe,EAAE,OAAO,GAAG,SAAS,CAAC;IACrC,MAAM,EAAE,CAAC,OAAO,EAAE,QAAQ,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAChD,WAAW,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACnD,cAAc,EAAE,MAAM,OAAO,GAAG,SAAS,CAAC;IAC1C,QAAQ,EAAE,CAAC,OAAO,EAAE,QAAQ,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;IACrD,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,QAAQ,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACnD,+EAA+E;IAC/E,WAAW,CAAC,EAAE,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC/C,kFAAkF;IAClF,oBAAoB,CAAC,EAAE,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACxD,2EAA2E;IAC3E,eAAe,CAAC,EAAE,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACnD,KAAK,EAAE,CAAC,SAAS,EAAE,UAAU,KAAK,OAAO,CAAC,KAAK,CAAC,CAAC;IACjD,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,kBAAkB,KAAK,IAAI,CAAC;IAC9C,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,IAAI,CAAC;CACpB,CAAC;AAEF;;;;;;GAMG;AACH,wBAAsB,2BAA2B,CAC/C,QAAQ,SAAS;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,EACpC,UAAU,EACV,KAAK,EACL,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,mBAAgF,EAChF,KAAK,GACN,EAAE,4BAA4B,CAAC,QAAQ,EAAE,UAAU,EAAE,KAAK,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,CA+C5E"}

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,99 @@
+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;
+    /** The gas limit the wallet or forwarder signs, when it is fixed before review. */
+    gas?: bigint;
+    /** A Safe proposal's signed `safeTxGas`. At 0 the Safe transaction reverts if this call fails. */
+    safeTxGas?: 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;
+    gas?: bigint;
+    safeTxGas?: bigint;
+    account?: Address;
+};
+export type TransactionReviewOptions = Omit<TransactionReviewRequest, "calls"> & {
+    label?: string;
+    contractName?: string;
+};
+type TransactionReviewHandler = (request: TransactionReviewRequest) => Promise<boolean>;
+/** The person closed a review or a funding-chain choice. Nothing was sent; apps need not show an error. */
+export declare class TransactionReviewCancelledError extends Error {
+    constructor(message?: string);
+}
+export type FundingChainOption = {
+    chainId: number;
+    /** The chain and its quoted cost, from {@link fundingChainLabel}. */
+    label: string;
+};
+type FundingChainSelectionHandler = (options: readonly FundingChainOption[], 
+/** The option to preselect, or null when the person must pick one of several. */
+initialChainId: number | null) => Promise<number | null>;
+/** "Base (~0.000123 ETH)": a chain and the relay fee quoted on it. */
+export declare function fundingChainLabel(chainName: string, amountWei: bigint): string;
+export declare function registerFundingChainSelectionHandler(handler: FundingChainSelectionHandler): () => void;
+/**
+ * Asks where to pay a relay fee. The connected chain is preselected when it is
+ * quoted, and so is a lone quote; otherwise the person picks. The exact payment
+ * still gets its own review.
+ */
+export declare function requireFundingChainSelection(options: readonly FundingChainOption[], preferredChainId?: number): 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,219 @@
+"use client";
+import { encodeFunctionData, formatEther, } from "viem";
+const transactionReviewHandlers = [];
+/** The person closed a review or a funding-chain choice. Nothing was sent; apps need not show an error. */
+export class TransactionReviewCancelledError extends Error {
+    constructor(message = "Review closed. Nothing was sent.") {
+        super(message);
+        this.name = "TransactionReviewCancelledError";
+    }
+}
+/** "Base (~0.000123 ETH)": a chain and the relay fee quoted on it. */
+export function fundingChainLabel(chainName, amountWei) {
+    const exact = formatEther(amountWei);
+    const shown = new Intl.NumberFormat("en-US", {
+        maximumSignificantDigits: 3,
+    }).format(Number(exact));
+    return `${chainName} (${shown === exact ? "" : "~"}${shown} ETH)`;
+}
+const fundingChainSelectionHandlers = [];
+export function registerFundingChainSelectionHandler(handler) {
+    fundingChainSelectionHandlers.push(handler);
+    return () => {
+        const index = fundingChainSelectionHandlers.lastIndexOf(handler);
+        if (index >= 0)
+            fundingChainSelectionHandlers.splice(index, 1);
+    };
+}
+/**
+ * Asks where to pay a relay fee. The connected chain is preselected when it is
+ * quoted, and so is a lone quote; otherwise the person picks. The exact payment
+ * still gets its own review.
+ */
+export async function requireFundingChainSelection(options, preferredChainId) {
+    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 initialChainId = preferredChainId !== undefined && chainIds.has(preferredChainId)
+        ? preferredChainId
+        : snapshot.length === 1
+            ? snapshot[0].chainId
+            : null;
+    const selected = await handler(snapshot, initialChainId);
+    if (selected === null) {
+        throw new TransactionReviewCancelledError("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,
+        gas: call.gas,
+        safeTxGas: call.safeTxGas,
+        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.gas !== reviewed.gas ||
+            current.safeTxGas !== reviewed.safeTxGas ||
+            current.data !== reviewed.data) {
+            throw new Error("Transaction data changed after review. Nothing was sent; review it again.");
+        }
+        return true;
+    });
+}
+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)}`,
+        ...(call.gas === undefined ? {} : { gas: `0x${call.gas.toString(16)}` }),
+        ...(call.safeTxGas === undefined
+            ? {}
+            : { safeTxGas: `0x${call.safeTxGas.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 action in a 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`, calldata, and any `gas` or `safeTxGas` 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("6. For a Relayr or Safe authorization, separate what I sign now from the later onchain execution. A Safe `safeTxGas` of 0 makes the Safe transaction revert if the call fails; a nonzero value lets it execute and record the failure.");
+    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"}