@bananapus/nana-sdk-core 3.5.1 → 4.0.0

package/dist/esm/review/sign.js

@@ -0,0 +1,368 @@
+import { ReviewLineError } from "./lineError.js";
+import { encodeFunctionData, getAddress, hashTypedData, isAddress, } from "viem";
+import { multiSendCallsOf } from "../safe.js";
+import { isHexBytes, uint256 } from "../untrusted.js";
+import { SAFE_EXEC_ABI, SAFE_TX_TYPES, safeTransactionMessage, } from "../safeService.js";
+import { permit2TypedData, } from "../v6/permit2.js";
+import { promptReview } from "./confirm.js";
+import { isDefiniteWalletRejection, submitReviewedContractWrite, } from "./contractWrite.js";
+import { permit2Rows } from "./decode.js";
+import { decodeReviewCall } from "./decodeCall.js";
+import { buildReviewModel } from "./model.js";
+import { REVIEWED_PLAN_REFUSED_LINE, spendPlan, } from "./plan.js";
+import { FORWARD_REQUEST_TYPES, relayrForwarder, relayrForwarderDeadline, } from "./relayr.js";
+import { TransactionReviewCancelledError } from "./reviewQueue.js";
+import { unsupportedWalletRequest, walletReady, } from "./wallet.js";
+const REJECTED = "You rejected the signature. Nothing was sent.";
+function requireChainId(chainId) {
+    if (typeof chainId !== "number" ||
+        !Number.isSafeInteger(chainId) ||
+        chainId <= 0) {
+        throw new ReviewLineError("Invalid chain ID.");
+    }
+    return chainId;
+}
+function requireAddress(name, value) {
+    if (typeof value !== "string" || !isAddress(value)) {
+        throw new ReviewLineError(`Invalid ${name} address.`);
+    }
+    return getAddress(value);
+}
+/** An unsigned integer as a primitive, so nothing can change it after review. */
+function requireUint(name, value) {
+    const parsed = uint256(value);
+    if (parsed === null)
+        throw new ReviewLineError(`Invalid ${name}.`);
+    return parsed;
+}
+/** `value` and everything in it frozen. */
+function frozen(value) {
+    if (value && typeof value === "object" && !Object.isFrozen(value)) {
+        Object.freeze(value);
+        for (const inner of Object.values(value))
+            frozen(inner);
+    }
+    return value;
+}
+/**
+ * The prepared signature: `payload` is what the wallet signs and what the
+ * review shows, one frozen copy, so neither the inputs nor the shared type
+ * constants changing after review changes what is signed. Typed data must
+ * encode first, so viem checks every address and integer before the review
+ * opens.
+ */
+function prepared(kind, chainId, payload, shown = {}) {
+    const copy = frozen(structuredClone(payload));
+    const typedData = "typedData" in copy ? copy.typedData : null;
+    if (typedData)
+        hashTypedData(typedData);
+    return Object.freeze({
+        chainId,
+        typedData,
+        message: "message" in copy ? copy.message : null,
+        review: { kind, chainId, ...copy, ...shown },
+    });
+}
+/**
+ * `signature` as core signs and shows it, each field read once. Refuses any
+ * kind core does not know, a Safe transaction that DELEGATECALLs anything
+ * but a recognized MultiSendCallOnly, a forward request not from `account`,
+ * on a chain with no forwarder, or executable past
+ * {@link relayrForwarderDeadline}, and a message that is not text.
+ */
+export function prepareSignature(signature, account) {
+    const kind = signature?.kind;
+    switch (kind) {
+        case "safe-tx": {
+            const { chainId, safe, tx } = signature;
+            const id = requireChainId(chainId);
+            const verifyingContract = requireAddress("Safe", safe);
+            const given = tx?.safeTxHash;
+            const message = safeTransactionMessage(tx);
+            // A hash the caller holds for it must be the one signed.
+            if (given != null &&
+                (typeof given !== "string" ||
+                    given.toLowerCase() !==
+                        hashTypedData({
+                            domain: { chainId: id, verifyingContract },
+                            types: SAFE_TX_TYPES,
+                            primaryType: "SafeTx",
+                            message,
+                        })))
+                throw new ReviewLineError("This Safe transaction does not match its hash. Nothing was signed.");
+            const inner = multiSendCallsOf(message);
+            if (message.operation === 1 && !inner) {
+                throw new ReviewLineError("This Safe transaction DELEGATECALLs a contract other than MultiSendCallOnly. Nothing was signed.");
+            }
+            const args = [
+                message.to,
+                message.value,
+                message.data,
+                message.operation,
+                message.safeTxGas,
+                message.baseGas,
+                message.gasPrice,
+                message.gasToken,
+                message.refundReceiver,
+                "0x",
+            ];
+            return prepared(kind, id, {
+                typedData: {
+                    domain: { chainId: id, verifyingContract },
+                    types: SAFE_TX_TYPES,
+                    primaryType: "SafeTx",
+                    message,
+                },
+            }, {
+                // The Safe's own execution of it, with the MultiSend's calls inside.
+                calls: [
+                    {
+                        chainId: id,
+                        to: verifyingContract,
+                        data: encodeFunctionData({
+                            abi: SAFE_EXEC_ABI,
+                            functionName: "execTransaction",
+                            args,
+                        }),
+                        abi: SAFE_EXEC_ABI,
+                        functionName: "execTransaction",
+                        args,
+                        safeTxGas: message.safeTxGas,
+                        contractName: "Safe",
+                        ...(inner
+                            ? {
+                                calls: inner.map((call) => decodeReviewCall({
+                                    chainId: id,
+                                    from: verifyingContract,
+                                    ...call,
+                                })),
+                            }
+                            : {}),
+                    },
+                ],
+            });
+        }
+        case "forward-request": {
+            const { chainId, request } = signature;
+            const id = requireChainId(chainId);
+            const verifyingContract = relayrForwarder(id);
+            if (!verifyingContract) {
+                throw new ReviewLineError(`There is no Juicebox forwarder on chain ${id}. Nothing was signed.`);
+            }
+            const { from, to, value, gas, nonce, deadline, data } = request;
+            if (typeof from !== "string" ||
+                from.toLowerCase() !== account.toLowerCase()) {
+                throw new ReviewLineError("This request is not from the connected account. Nothing was signed.");
+            }
+            if (!Number.isSafeInteger(deadline) ||
+                deadline > relayrForwarderDeadline()) {
+                throw new ReviewLineError("This request stays executable longer than allowed. Nothing was signed.");
+            }
+            if (!isHexBytes(data))
+                throw new ReviewLineError("Invalid forwarded calldata.");
+            const message = {
+                from: requireAddress("sender", from),
+                to: requireAddress("destination", to),
+                value: requireUint("value", value),
+                gas: requireUint("gas", gas),
+                nonce: requireUint("nonce", nonce),
+                deadline,
+                data,
+            };
+            return prepared(kind, id, {
+                typedData: {
+                    domain: {
+                        name: "Juicebox",
+                        version: "1",
+                        chainId: id,
+                        verifyingContract,
+                    },
+                    types: FORWARD_REQUEST_TYPES,
+                    primaryType: "ForwardRequest",
+                    message,
+                },
+            }, {
+                calls: [
+                    decodeReviewCall({
+                        chainId: id,
+                        from: message.from,
+                        to: message.to,
+                        data,
+                        value: message.value,
+                        gas: message.gas,
+                    }),
+                ],
+            });
+        }
+        case "permit2": {
+            const { chainId, token, spender, amount, expiration, nonce, sigDeadline, } = signature.authorization;
+            const id = requireChainId(chainId);
+            const authorization = {
+                chainId: id,
+                token: requireAddress("token", token),
+                spender: requireAddress("spender", spender),
+                amount: requireUint("amount", amount),
+                expiration: Number(requireUint("expiration", expiration)),
+                nonce: Number(requireUint("nonce", nonce)),
+                sigDeadline: requireUint("signature deadline", sigDeadline),
+            };
+            return prepared(kind, id, { typedData: permit2TypedData(authorization) }, {
+                steps: [
+                    {
+                        title: "Permit2 allowance",
+                        rows: permit2Rows(id, authorization),
+                    },
+                ],
+            });
+        }
+        case "message": {
+            const { chainId, message, calls } = signature;
+            const id = requireChainId(chainId);
+            if (typeof message !== "string") {
+                throw new ReviewLineError("A message to sign must be text. Nothing was signed.");
+            }
+            if (calls === undefined)
+                return prepared(kind, id, { message });
+            return prepared(kind, id, { message }, {
+                calls: [...calls].map((call) => {
+                    const { chainId, to, data, value } = call;
+                    if (!isHexBytes(data))
+                        throw new ReviewLineError("Invalid call data.");
+                    return decodeReviewCall({
+                        chainId: requireChainId(chainId),
+                        to: requireAddress("call target", to),
+                        data,
+                        value: requireUint("call value", value ?? 0n),
+                    });
+                }),
+            });
+        }
+    }
+    throw new ReviewLineError("This signature is not one the app can review. Nothing was signed.");
+}
+/**
+ * Signs each prepared signature in order through the adapter, after the same
+ * account and chain checks as {@link submitReviewedContractWrite}: the
+ * connected account must stay `account`, and typed data is signed on its
+ * domain's chain. A message is chain-free, so the wallet is not asked to
+ * switch for one. A definite wallet rejection (EIP-1193 4001) returns no
+ * signature and throws {@link TransactionReviewCancelledError}.
+ */
+export async function signPrepared(prepared, account, adapter, 
+/** The caller's final gate before each signature; it throws to stop. */
+beforeSign, 
+/** The caller's async recheck before each signature, ahead of `beforeSign`. */
+reverify) {
+    const signatures = [];
+    for (const { chainId, typedData, message } of prepared) {
+        signatures.push(await submitReviewedContractWrite({
+            request: { chainId },
+            expectedAccount: account,
+            review: () => Promise.resolve(),
+            switchChain: async (id) => {
+                if (typedData && adapter.chainId() !== id) {
+                    await adapter.switchChain(id);
+                }
+            },
+            currentAccount: () => adapter.account(),
+            ...(reverify ? { reverify } : {}),
+            simulate: async () => undefined,
+            beforeSend: () => {
+                beforeSign?.();
+                if (typedData && adapter.chainId() !== chainId) {
+                    throw new ReviewLineError("Your wallet changed networks. Review the signature again.");
+                }
+                // Last, after every callback above could have run.
+                if (adapter.account()?.toLowerCase() !== account.toLowerCase()) {
+                    throw new ReviewLineError("The connected account changed. Review again.");
+                }
+            },
+            // Only the wallet's own answer can read as a rejection.
+            write: async () => {
+                try {
+                    return await (typedData
+                        ? adapter.signTypedData(typedData)
+                        : adapter.signMessage(message));
+                }
+                catch (error) {
+                    if (isDefiniteWalletRejection(error)) {
+                        throw new TransactionReviewCancelledError(REJECTED);
+                    }
+                    throw error;
+                }
+            },
+        }));
+    }
+    return signatures;
+}
+/**
+ * The calls a prepared signature lets someone run, as a plan matches them,
+ * read from the exact payload signed: a Safe transaction's CALL or
+ * MultiSendCallOnly calls, from the Safe, when it pays no refund and its
+ * safeTxGas is 0 (so a failed call reverts, not spends the nonce), or a
+ * forward request's call, from its signer. Any other signature is refused
+ * under a plan.
+ */
+export function plannedCallsOf({ chainId, typedData, }) {
+    const message = typedData?.message;
+    if (typedData?.primaryType === "SafeTx" && message) {
+        const { to, data, value, operation, safeTxGas, gasPrice } = message;
+        const safe = typedData.domain?.verifyingContract;
+        const inner = operation === 1
+            ? multiSendCallsOf({ to, data, operation })
+            : [{ to, data, value }];
+        if (safe && inner && safeTxGas === 0n && gasPrice === 0n)
+            return inner.map((call) => ({
+                chainId,
+                from: safe,
+                to: call.to,
+                data: call.data,
+                value: call.value,
+            }));
+    }
+    else if (typedData?.primaryType === "ForwardRequest" && message) {
+        const { from, to, data, value, gas } = message;
+        return [{ chainId, from, to, data, value, gas }];
+    }
+    throw new ReviewLineError(REVIEWED_PLAN_REFUSED_LINE);
+}
+/**
+ * Signs only what the person reviewed: one prompt for every signature, with
+ * the exact typed data or text and the calls each lets someone run, decoded.
+ * Nothing is signed unless the review handler returns core's confirmation
+ * ({@link registerReviewHandler}). The signatures come back in order.
+ *
+ * A self-reviewing adapter (Signa) is refused with EIP-1193 4200: it has no
+ * reviewed-signature path yet.
+ */
+export async function signReviewed(signatures, action, deps) {
+    const { adapter } = deps;
+    const { account } = action;
+    await walletReady(adapter);
+    if (adapter.kind === "self-reviewing")
+        throw unsupportedWalletRequest();
+    const connected = adapter.account();
+    if (!connected)
+        throw new ReviewLineError("Connect a wallet first.");
+    if (connected.toLowerCase() !== account.toLowerCase()) {
+        throw new ReviewLineError("The connected account changed. Review again.");
+    }
+    const prepared = [...signatures].map((signature) => prepareSignature(signature, account));
+    if (!prepared.length)
+        throw new ReviewLineError("There is nothing to sign.");
+    if (action.plan) {
+        spendPlan(action.plan, account, prepared.flatMap(plannedCallsOf));
+        return signPrepared(prepared, account, adapter, undefined, action.reverify);
+    }
+    const model = buildReviewModel({
+        calls: [],
+        signatures: prepared.map(({ review }) => review),
+        ...(action.title ? { title: action.title } : {}),
+        ...(action.description ? { description: action.description } : {}),
+        ...(action.context ? { context: action.context } : {}),
+    });
+    // Nothing is sent, so there is nothing to simulate.
+    await promptReview(model, Promise.resolve({ status: "passed" }), Promise.resolve(model), action.signal);
+    return signPrepared(prepared, account, adapter, undefined, action.reverify);
+}
+//# sourceMappingURL=sign.js.map

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

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

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

@@ -13,7 +13,7 @@ export declare const TRANSACTION_SIMULATION_MAX_RETURN_BYTES = 4096;
  * `blockNumber` to simulate on the block a prerequisite (an approval, say) was
  * mined in, instead of `latest` on a node that may lag behind it.
  */
-export declare function simulateStateChangingTransaction(client: Pick<PublicClient, "request">, { from, to, data, value, gas, blockNumber, maxReturnBytes, }: {
+export declare function simulateStateChangingTransaction(client: Pick<PublicClient, "request">, { from, to, data, value, gas, blockNumber, maxReturnBytes, balance, }: {
     from: Address;
     to: Address;
     data: Hex;
@@ -21,17 +21,54 @@ export declare function simulateStateChangingTransaction(client: Pick<PublicClie
     gas?: bigint;
     blockNumber?: bigint;
     maxReturnBytes?: number;
+    /** `from`'s balance for the simulation, in place of its own. */
+    balance?: bigint;
 }): Promise<Hex>;
 /** One call of an ordered sequence, such as a Safe MultiSend batch. */
 export type SimulatedSequenceCall = {
     to: Address;
     data: Hex;
     value?: bigint;
+    /** The exact gas limit the call is sent with, when the app fixed it. */
+    gas?: bigint;
     /** Names the call in a failure message. */
     label: string;
     /** Needs an earlier call's effect (an allowance, a hook), so it cannot run alone. */
     dependsOnPrior?: boolean;
+    /** Its value is paid for the sender (by Relayr): run alone, it gets the sequence's `balance`. */
+    funded?: boolean;
 };
+/** The line for a revert whose reason the SDK does not know. */
+export declare const REVERT_UNKNOWN_LINE = "This transaction would fail. Check the amounts and try again.";
+/** The line for a simulation the node did not answer. */
+export declare const SIMULATION_NO_ANSWER_LINE = "The node did not answer the simulation.";
+/**
+ * Why a call reverted, when the SDK knows the revert: a payment revert's
+ * plain line ({@link decodePayFailure}). Null otherwise. Error text (viem's
+ * `shortMessage`, a node's message) is never read: it can quote a request or
+ * its URL.
+ */
+export declare function revertReason(error: unknown): string | null;
+/**
+ * A failed simulation's one-line reason: {@link revertReason}, or a fixed
+ * line, {@link REVERT_UNKNOWN_LINE} for a revert and
+ * {@link SIMULATION_NO_ANSWER_LINE} otherwise. Never the error's own text.
+ */
+export declare function revertDetail(error: unknown): string;
+/**
+ * Whether a failed simulation is the call reverting, not the node failing:
+ * EIP-1474 code 3, viem's contract-revert errors, or the node's own text
+ * saying it reverted, in the error's first eight causes. A viem error is read
+ * by its `details`, since its `message` quotes the request.
+ */
+export declare function isRevert(error: unknown): boolean;
+/**
+ * The error a failed simulation throws, with the answer as its cause: the
+ * SDK's own line (a {@link ReviewLineError}) for a revert, decoded or not; a
+ * plain error, which `errorLine` shows as the network line, for a node that
+ * did not answer.
+ */
+export declare function simulationFailure(text: string, cause: unknown): Error;
 /**
  * Prove a whole sequence from `from` before anything is signed. `eth_simulateV1`
  * runs the calls in order against one state. Where a node lacks it, each call
@@ -39,9 +76,11 @@ export type SimulatedSequenceCall = {
  * {@link simulateStateChangingTransaction}; the dependent ones are left to the
  * executing wallet's own simulation. `chainName` names the chain in errors.
  */
-export declare function simulateCallSequence(client: Pick<PublicClient, "request" | "simulateCalls">, { from, calls, chainName, }: {
+export declare function simulateCallSequence(client: Pick<PublicClient, "request" | "simulateCalls">, { from, calls, chainName, balance, }: {
     from: Address;
     calls: readonly SimulatedSequenceCall[];
     chainName: string;
+    /** `from`'s balance for the sequence, in place of its own; a call run alone gets it only when `funded`. */
+    balance?: bigint;
 }): Promise<void>;
 //# sourceMappingURL=simulation.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"simulation.d.ts","sourceRoot":"","sources":["../../../src/review/simulation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAe,KAAK,OAAO,EAAE,KAAK,GAAG,EAAE,KAAK,YAAY,EAAE,MAAM,MAAM,CAAC;AAE9E,+EAA+E;AAC/E,eAAO,MAAM,0BAA0B,YAAc,CAAC;AAEtD,+EAA+E;AAC/E,eAAO,MAAM,uCAAuC,OAAQ,CAAC;AAE7D;;;;;;;;;GASG;AACH,wBAAsB,gCAAgC,CACpD,MAAM,EAAE,IAAI,CAAC,YAAY,EAAE,SAAS,CAAC,EACrC,EACE,IAAI,EACJ,EAAE,EACF,IAAI,EACJ,KAAU,EACV,GAAgC,EAChC,WAAW,EACX,cAAwD,GACzD,EAAE;IACD,IAAI,EAAE,OAAO,CAAC;IACd,EAAE,EAAE,OAAO,CAAC;IACZ,IAAI,EAAE,GAAG,CAAC;IACV,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,GACA,OAAO,CAAC,GAAG,CAAC,CA6Bd;AAED,uEAAuE;AACvE,MAAM,MAAM,qBAAqB,GAAG;IAClC,EAAE,EAAE,OAAO,CAAC;IACZ,IAAI,EAAE,GAAG,CAAC;IACV,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,2CAA2C;IAC3C,KAAK,EAAE,MAAM,CAAC;IACd,qFAAqF;IACrF,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B,CAAC;AA+DF;;;;;;GAMG;AACH,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,IAAI,CAAC,YAAY,EAAE,SAAS,GAAG,eAAe,CAAC,EACvD,EACE,IAAI,EACJ,KAAK,EACL,SAAS,GACV,EAAE;IACD,IAAI,EAAE,OAAO,CAAC;IACd,KAAK,EAAE,SAAS,qBAAqB,EAAE,CAAC;IACxC,SAAS,EAAE,MAAM,CAAC;CACnB,GACA,OAAO,CAAC,IAAI,CAAC,CA8Cf"}
+{"version":3,"file":"simulation.d.ts","sourceRoot":"","sources":["../../../src/review/simulation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAe,KAAK,OAAO,EAAE,KAAK,GAAG,EAAE,KAAK,YAAY,EAAE,MAAM,MAAM,CAAC;AAI9E,+EAA+E;AAC/E,eAAO,MAAM,0BAA0B,YAAc,CAAC;AAEtD,+EAA+E;AAC/E,eAAO,MAAM,uCAAuC,OAAQ,CAAC;AAE7D;;;;;;;;;GASG;AACH,wBAAsB,gCAAgC,CACpD,MAAM,EAAE,IAAI,CAAC,YAAY,EAAE,SAAS,CAAC,EACrC,EACE,IAAI,EACJ,EAAE,EACF,IAAI,EACJ,KAAU,EACV,GAAgC,EAChC,WAAW,EACX,cAAwD,EACxD,OAAO,GACR,EAAE;IACD,IAAI,EAAE,OAAO,CAAC;IACd,EAAE,EAAE,OAAO,CAAC;IACZ,IAAI,EAAE,GAAG,CAAC;IACV,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,gEAAgE;IAChE,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,GACA,OAAO,CAAC,GAAG,CAAC,CAmCd;AAED,uEAAuE;AACvE,MAAM,MAAM,qBAAqB,GAAG;IAClC,EAAE,EAAE,OAAO,CAAC;IACZ,IAAI,EAAE,GAAG,CAAC;IACV,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,wEAAwE;IACxE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,2CAA2C;IAC3C,KAAK,EAAE,MAAM,CAAC;IACd,qFAAqF;IACrF,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,iGAAiG;IACjG,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB,CAAC;AAEF,gEAAgE;AAChE,eAAO,MAAM,mBAAmB,kEACiC,CAAC;AAElE,yDAAyD;AACzD,eAAO,MAAM,yBAAyB,4CACK,CAAC;AAE5C;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAE1D;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAKnD;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAsChD;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,KAAK,CAMrE;AAkDD;;;;;;GAMG;AACH,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,IAAI,CAAC,YAAY,EAAE,SAAS,GAAG,eAAe,CAAC,EACvD,EACE,IAAI,EACJ,KAAK,EACL,SAAS,EACT,OAAO,GACR,EAAE;IACD,IAAI,EAAE,OAAO,CAAC;IACd,KAAK,EAAE,SAAS,qBAAqB,EAAE,CAAC;IACxC,SAAS,EAAE,MAAM,CAAC;IAClB,2GAA2G;IAC3G,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,GACA,OAAO,CAAC,IAAI,CAAC,CA2Df"}

package/dist/esm/review/simulation.js

@@ -1,4 +1,6 @@
 import { numberToHex } from "viem";
+import { decodePayFailure } from "../v6/executionErrors.js";
+import { ReviewLineError } from "./lineError.js";
 /** A generous explicit gas ceiling for a reviewed state-changing preflight. */
 export const TRANSACTION_SIMULATION_GAS = 10000000n;
 /** The most return data a preflight hands back to a caller that decodes it. */
@@ -13,45 +15,99 @@ export const TRANSACTION_SIMULATION_MAX_RETURN_BYTES = 4_096;
  * `blockNumber` to simulate on the block a prerequisite (an approval, say) was
  * mined in, instead of `latest` on a node that may lag behind it.
  */
-export async function simulateStateChangingTransaction(client, { from, to, data, value = 0n, gas = TRANSACTION_SIMULATION_GAS, blockNumber, maxReturnBytes = TRANSACTION_SIMULATION_MAX_RETURN_BYTES, }) {
+export async function simulateStateChangingTransaction(client, { from, to, data, value = 0n, gas = TRANSACTION_SIMULATION_GAS, blockNumber, maxReturnBytes = TRANSACTION_SIMULATION_MAX_RETURN_BYTES, balance, }) {
     if (gas <= 0n) {
-        throw new Error("Transaction simulation gas must be positive.");
+        throw new ReviewLineError("Transaction simulation gas must be positive.");
     }
     if (!Number.isSafeInteger(maxReturnBytes) || maxReturnBytes < 0) {
-        throw new Error("Transaction simulation needs a return data limit.");
+        throw new ReviewLineError("Transaction simulation needs a return data limit.");
     }
     // A raw request bypasses call()/simulateContract(), whose behavior can
     // inherit a client-level CCIP-read policy.
+    const call = {
+        from,
+        to,
+        data,
+        value: numberToHex(value),
+        gas: numberToHex(gas),
+    };
+    const block = blockNumber === undefined ? "latest" : numberToHex(blockNumber);
     const result = await client.request({
         method: "eth_call",
-        params: [
-            {
-                from,
-                to,
-                data,
-                value: numberToHex(value),
-                gas: numberToHex(gas),
-            },
-            blockNumber === undefined ? "latest" : numberToHex(blockNumber),
-        ],
+        params: balance === undefined
+            ? [call, block]
+            : [call, block, { [from]: { balance: numberToHex(balance) } }],
     });
     if (typeof result !== "string" || !/^0x(?:[0-9a-f]{2})*$/iu.test(result)) {
-        throw new Error("Transaction simulation returned malformed data.");
+        throw new ReviewLineError("Transaction simulation returned malformed data.");
     }
     if ((result.length - 2) / 2 > maxReturnBytes) {
-        throw new Error("Transaction simulation returned too much data.");
+        throw new ReviewLineError("Transaction simulation returned too much data.");
     }
     return result;
 }
-function revertDetail(error) {
-    if (error instanceof Error &&
-        "shortMessage" in error &&
-        typeof error.shortMessage === "string") {
-        return error.shortMessage;
+/** The line for a revert whose reason the SDK does not know. */
+export const REVERT_UNKNOWN_LINE = "This transaction would fail. Check the amounts and try again.";
+/** The line for a simulation the node did not answer. */
+export const SIMULATION_NO_ANSWER_LINE = "The node did not answer the simulation.";
+/**
+ * Why a call reverted, when the SDK knows the revert: a payment revert's
+ * plain line ({@link decodePayFailure}). Null otherwise. Error text (viem's
+ * `shortMessage`, a node's message) is never read: it can quote a request or
+ * its URL.
+ */
+export function revertReason(error) {
+    return decodePayFailure(error)?.message ?? null;
+}
+/**
+ * A failed simulation's one-line reason: {@link revertReason}, or a fixed
+ * line, {@link REVERT_UNKNOWN_LINE} for a revert and
+ * {@link SIMULATION_NO_ANSWER_LINE} otherwise. Never the error's own text.
+ */
+export function revertDetail(error) {
+    return (revertReason(error) ??
+        (isRevert(error) ? REVERT_UNKNOWN_LINE : SIMULATION_NO_ANSWER_LINE));
+}
+/**
+ * Whether a failed simulation is the call reverting, not the node failing:
+ * EIP-1474 code 3, viem's contract-revert errors, or the node's own text
+ * saying it reverted, in the error's first eight causes. A viem error is read
+ * by its `details`, since its `message` quotes the request.
+ */
+export function isRevert(error) {
+    let current = error;
+    for (let depth = 0; depth < 8 && current && typeof current === "object"; depth += 1) {
+        const item = current;
+        if (item.code === 3 ||
+            item.name === "ContractFunctionRevertedError" ||
+            item.name === "RawContractError" ||
+            item.name === "ExecutionRevertedError" ||
+            // A failed call that returned no revert data.
+            item.name === "ContractFunctionZeroDataError" ||
+            item.name === "AbiDecodingZeroDataError") {
+            return true;
+        }
+        // A wrapper that carries its cause (simulateCallSequence's, which names
+        // the call) is read through that cause, never by its own text.
+        const text = typeof item.details === "string"
+            ? item.details
+            : typeof item.shortMessage === "string" || "cause" in item
+                ? undefined
+                : item.message;
+        if (typeof text === "string" && /revert/i.test(text))
+            return true;
+        current = item.cause;
     }
-    return error instanceof Error
-        ? error.message.split("\n")[0]
-        : "The call would revert.";
+    return false;
+}
+/**
+ * The error a failed simulation throws, with the answer as its cause: the
+ * SDK's own line (a {@link ReviewLineError}) for a revert, decoded or not; a
+ * plain error, which `errorLine` shows as the network line, for a node that
+ * did not answer.
+ */
+export function simulationFailure(text, cause) {
+    return Object.defineProperty(isRevert(cause) ? new ReviewLineError(text) : new Error(text), "cause", { value: cause, configurable: true, writable: true });
 }
 /** Node text saying the method itself is missing: "method not found", "Unsupported method: eth_simulateV1". */
 function namesMissingMethod(text) {
@@ -93,12 +149,20 @@ function simulationUnsupported(error) {
  * {@link simulateStateChangingTransaction}; the dependent ones are left to the
  * executing wallet's own simulation. `chainName` names the chain in errors.
  */
-export async function simulateCallSequence(client, { from, calls, chainName, }) {
+export async function simulateCallSequence(client, { from, calls, chainName, balance, }) {
     let sequence;
     try {
         const simulated = await client.simulateCalls({
             account: from,
-            calls: calls.map(({ to, data, value }) => ({ to, data, value })),
+            calls: calls.map(({ to, data, value, gas }) => ({
+                to,
+                data,
+                value,
+                ...(gas === undefined ? {} : { gas }),
+            })),
+            ...(balance === undefined
+                ? {}
+                : { stateOverrides: [{ address: from, balance }] }),
         });
         sequence = simulated.results.map((result) => result.status === "failure"
             ? { status: "failure", error: result.error }
@@ -106,7 +170,7 @@ export async function simulateCallSequence(client, { from, calls, chainName, })
     }
     catch (error) {
         if (!simulationUnsupported(error)) {
-            throw new Error(`The batch could not be simulated on ${chainName}: ${revertDetail(error)}`);
+            throw simulationFailure(`The batch could not be simulated on ${chainName}: ${revertDetail(error)}`, error);
         }
         sequence = null;
     }
@@ -115,9 +179,9 @@ export async function simulateCallSequence(client, { from, calls, chainName, })
             const result = sequence[index];
             if (result?.status === "success")
                 continue;
-            throw new Error(`${call.label} cannot run on ${chainName}: ${result?.status === "failure"
+            throw simulationFailure(`${call.label} cannot run on ${chainName}: ${result?.status === "failure"
                 ? revertDetail(result.error)
-                : "The call would revert."}`);
+                : SIMULATION_NO_ANSWER_LINE}`, result?.error);
         }
         if (call.dependsOnPrior)
             continue;
@@ -127,10 +191,12 @@ export async function simulateCallSequence(client, { from, calls, chainName, })
                 to: call.to,
                 data: call.data,
                 value: call.value,
+                gas: call.gas,
+                ...(balance === undefined || !call.funded ? {} : { balance }),
             });
         }
         catch (error) {
-            throw new Error(`${call.label} cannot run on ${chainName}: ${revertDetail(error)}`);
+            throw simulationFailure(`${call.label} cannot run on ${chainName}: ${revertDetail(error)}`, error);
         }
     }
 }