@morpho-org/evm-simulation 1.0.0

package/lib/cjs/simulate/backends/eth-simulate-v1.js

@@ -0,0 +1,76 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.simulateV1 = simulateV1;
+const viem_1 = require("viem");
+const errors_js_1 = require("../../errors.js");
+/**
+ * Simulate transactions using eth_simulateV1 (viem simulateCalls).
+ *
+ * Uses stateOverride to set the user's ETH balance high enough to avoid
+ * false "insufficient balance for gas" reverts.
+ */
+async function simulateV1(params) {
+    const { rpcUrl, transactions, blockNumber, signal } = params;
+    const client = (0, viem_1.createPublicClient)({
+        transport: (0, viem_1.http)(rpcUrl, {
+            fetchOptions: signal ? { signal } : undefined,
+        }),
+    });
+    const firstTx = transactions[0];
+    if (!firstTx) {
+        throw new errors_js_1.SimulationValidationError("At least one transaction is required", []);
+    }
+    const sender = (0, viem_1.getAddress)(firstTx.from);
+    // eth_simulateV1 executes all calls as the same account. Reject mixed senders
+    // to avoid silently simulating under the wrong address.
+    const mixedSender = transactions.find((tx) => (0, viem_1.getAddress)(tx.from) !== sender);
+    if (mixedSender) {
+        throw new errors_js_1.SimulationValidationError("All transactions must have the same from address for eth_simulateV1", [`expected ${sender}, got ${mixedSender.from}`]);
+    }
+    const calls = transactions.map((tx) => ({
+        to: tx.to,
+        data: tx.data,
+        value: tx.value,
+    }));
+    const blockParam = typeof blockNumber === "bigint"
+        ? { blockNumber }
+        : blockNumber !== undefined
+            ? { blockTag: blockNumber }
+            : {};
+    try {
+        const simulationResult = await client.simulateCalls({
+            account: sender,
+            calls,
+            ...blockParam,
+            // Inflate sender ETH balance to prevent false "insufficient gas" reverts.
+            // Without this, valid ERC20 flows fail when the sender has low ETH.
+            stateOverrides: [{ address: sender, balance: viem_1.maxUint256 }],
+        });
+        const results = simulationResult.results;
+        if (!Array.isArray(results)) {
+            throw new errors_js_1.ExternalServiceError("eth_simulateV1 returned unexpected response format");
+        }
+        const failedResult = results.find((r) => r.status !== "success");
+        if (failedResult) {
+            throw new errors_js_1.SimulationRevertedError(failedResult.error?.message ?? "Simulation failed", results);
+        }
+        const rawLogs = [];
+        for (const r of results) {
+            for (const log of r.logs ?? []) {
+                rawLogs.push({
+                    address: log.address,
+                    topics: [...log.topics],
+                    data: log.data ?? "0x",
+                });
+            }
+        }
+        return { logs: rawLogs };
+    }
+    catch (error) {
+        if (error instanceof errors_js_1.SimulationRevertedError)
+            throw error;
+        if (error instanceof errors_js_1.ExternalServiceError)
+            throw error;
+        throw new errors_js_1.ExternalServiceError(`eth_simulateV1 error: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+    }
+}

package/lib/cjs/simulate/backends/index.d.ts

@@ -0,0 +1,2 @@
+export { simulateV1 } from "./eth-simulate-v1.js";
+export { simulateTenderlyRest } from "./tenderly-rest.js";

package/lib/cjs/simulate/backends/index.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.simulateTenderlyRest = exports.simulateV1 = void 0;
+var eth_simulate_v1_js_1 = require("./eth-simulate-v1.js");
+Object.defineProperty(exports, "simulateV1", { enumerable: true, get: function () { return eth_simulate_v1_js_1.simulateV1; } });
+var tenderly_rest_js_1 = require("./tenderly-rest.js");
+Object.defineProperty(exports, "simulateTenderlyRest", { enumerable: true, get: function () { return tenderly_rest_js_1.simulateTenderlyRest; } });

package/lib/cjs/simulate/backends/tenderly-rest.d.ts

@@ -0,0 +1,20 @@
+import { type BlockTag } from "viem";
+import type { RawSimulationResult, SimulationLogger, SimulationTransaction, TenderlyRestConfig } from "../../types.js";
+/**
+ * Simulate transactions using Tenderly REST API.
+ *
+ * @param shareable - true persists the simulation in Tenderly and returns a shareable URL;
+ *   false runs ephemerally with no URL. Translates to Tenderly's `save` wire field
+ *   (`save_if_fails` is also set to `shareable` — so failed preview simulations are
+ *   ALSO persisted and shareable. Callers that preview sensitive calldata should be
+ *   aware this persists in Tenderly's dashboard regardless of success/failure).
+ */
+export declare function simulateTenderlyRest(params: {
+    config: TenderlyRestConfig;
+    chainId: number;
+    transactions: SimulationTransaction[];
+    blockNumber?: bigint | BlockTag;
+    shareable: boolean;
+    signal?: AbortSignal;
+    logger?: SimulationLogger;
+}): Promise<RawSimulationResult>;

package/lib/cjs/simulate/backends/tenderly-rest.js

@@ -0,0 +1,269 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.simulateTenderlyRest = simulateTenderlyRest;
+const viem_1 = require("viem");
+const zod_1 = require("zod");
+const errors_js_1 = require("../../errors.js");
+// Zod validators for the subset of Tenderly responses we consume.
+// Addresses must be 40-hex-digit `0x...` (not just any string); topics and
+// data must be `0x`-prefixed hex so downstream `getAddress()` / `BigInt()`
+// calls don't throw inside `parseTransfers`, silently dropping transfers.
+const addressSchema = zod_1.z.custom((val) => typeof val === "string" && (0, viem_1.isAddress)(val));
+const hexSchema = zod_1.z.custom((val) => typeof val === "string" && (0, viem_1.isHex)(val));
+const tenderlyRawResponseSchema = zod_1.z
+    .object({
+    simulation: zod_1.z
+        .object({
+        id: zod_1.z.string().optional(),
+        status: zod_1.z.boolean().optional(),
+        error_message: zod_1.z.string().optional(),
+    })
+        .passthrough(),
+    transaction: zod_1.z
+        .object({
+        error_message: zod_1.z.string().optional(),
+        transaction_info: zod_1.z
+            .object({
+            logs: zod_1.z
+                .array(zod_1.z
+                .object({
+                raw: zod_1.z
+                    .object({
+                    address: addressSchema,
+                    topics: zod_1.z.array(hexSchema).optional(),
+                    data: hexSchema.optional(),
+                })
+                    .passthrough()
+                    .optional(),
+            })
+                .passthrough())
+                .optional(),
+            asset_changes: zod_1.z.unknown().optional(),
+        })
+            .passthrough(),
+    })
+        .passthrough(),
+})
+    .passthrough();
+const tenderlyBundleRawResponseSchema = zod_1.z
+    .object({
+    simulation_results: zod_1.z.array(tenderlyRawResponseSchema).min(1),
+})
+    .passthrough();
+/**
+ * Simulate transactions using Tenderly REST API.
+ *
+ * @param shareable - true persists the simulation in Tenderly and returns a shareable URL;
+ *   false runs ephemerally with no URL. Translates to Tenderly's `save` wire field
+ *   (`save_if_fails` is also set to `shareable` — so failed preview simulations are
+ *   ALSO persisted and shareable. Callers that preview sensitive calldata should be
+ *   aware this persists in Tenderly's dashboard regardless of success/failure).
+ */
+async function simulateTenderlyRest(params) {
+    const { config, chainId, transactions, blockNumber, shareable, signal, logger, } = params;
+    const baseUrl = buildBaseUrl(config);
+    try {
+        if (transactions.length === 1) {
+            return await simulateSingle({
+                baseUrl,
+                config,
+                chainId,
+                tx: transactions[0],
+                blockNumber,
+                shareable,
+                signal,
+                logger,
+            });
+        }
+        return await simulateBundle({
+            baseUrl,
+            config,
+            chainId,
+            transactions,
+            blockNumber,
+            shareable,
+            signal,
+            logger,
+        });
+    }
+    catch (error) {
+        if (error instanceof errors_js_1.SimulationRevertedError)
+            throw error;
+        if (error instanceof errors_js_1.ExternalServiceError)
+            throw error;
+        throw new errors_js_1.ExternalServiceError(`Tenderly REST API error: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+    }
+}
+/** URL-encode the path-segment config values so `/`, `?`, `#` can't retarget the request. */
+function buildBaseUrl(config) {
+    const account = encodeURIComponent(config.accountSlug);
+    const project = encodeURIComponent(config.projectSlug);
+    return `${config.apiBaseUrl}/api/v1/account/${account}/project/${project}`;
+}
+/** Build the `TenderlySimulateRequest` body for one transaction. Shared by single + bundle. */
+function buildTxBody(tx, chainId, shareable, blockNumber) {
+    return {
+        network_id: String(chainId),
+        from: tx.from,
+        to: tx.to,
+        input: tx.data,
+        value: String(tx.value ?? 0n),
+        save: shareable,
+        save_if_fails: shareable,
+        simulation_type: "full",
+        ...(blockNumber !== undefined && {
+            block_number: typeof blockNumber === "bigint" ? String(blockNumber) : blockNumber,
+        }),
+    };
+}
+async function simulateSingle(params) {
+    const { baseUrl, config, chainId, tx, blockNumber, shareable, signal, logger, } = params;
+    const body = buildTxBody(tx, chainId, shareable, blockNumber);
+    const response = await fetch(`${baseUrl}/simulate`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            "X-Access-Key": config.accessToken,
+        },
+        body: JSON.stringify(body),
+        signal,
+    });
+    if (!response.ok) {
+        throw new errors_js_1.ExternalServiceError(`Tenderly REST API returned ${response.status}: ${response.statusText}`);
+    }
+    const data = tenderlyRawResponseSchema.parse(await response.json());
+    const result = parseTenderlyResponse(data, shareable);
+    if (shareable && data.simulation.id) {
+        const shared = await shareSimulation({
+            baseUrl,
+            config,
+            simulationId: data.simulation.id,
+            signal,
+            logger,
+        });
+        if (!shared)
+            result.tenderlyUrl = undefined;
+    }
+    return result;
+}
+async function simulateBundle(params) {
+    const { baseUrl, config, chainId, transactions, blockNumber, shareable, signal, logger, } = params;
+    const body = {
+        simulations: transactions.map((tx) => buildTxBody(tx, chainId, shareable, blockNumber)),
+    };
+    const response = await fetch(`${baseUrl}/simulate-bundle`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            "X-Access-Key": config.accessToken,
+        },
+        body: JSON.stringify(body),
+        signal,
+    });
+    if (!response.ok) {
+        throw new errors_js_1.ExternalServiceError(`Tenderly REST API returned ${response.status}: ${response.statusText}`);
+    }
+    const data = tenderlyBundleRawResponseSchema.parse(await response.json());
+    const simulations = data.simulation_results;
+    // Collect logs from ALL steps (approvals + main tx) for complete bundler retention coverage.
+    // Only build the shareable URL from the last step; others parse with shareable=false.
+    const allLogs = [];
+    let lastResult;
+    let lastSimulationId;
+    for (let i = 0; i < simulations.length; i++) {
+        const sim = simulations[i];
+        const isLast = i === simulations.length - 1;
+        const parsed = parseTenderlyResponse(sim, isLast && shareable);
+        allLogs.push(...parsed.logs);
+        if (isLast) {
+            lastResult = parsed;
+            lastSimulationId = sim.simulation.id;
+        }
+    }
+    // Schema enforces `.min(1)` — lastResult is always defined after the loop.
+    let tenderlyUrl = lastResult.tenderlyUrl;
+    if (shareable && tenderlyUrl && lastSimulationId) {
+        const shared = await shareSimulation({
+            baseUrl,
+            config,
+            simulationId: lastSimulationId,
+            signal,
+            logger,
+        });
+        if (!shared)
+            tenderlyUrl = undefined;
+    }
+    return {
+        logs: allLogs,
+        tenderlyUrl,
+        rawAssetChanges: lastResult.rawAssetChanges,
+    };
+}
+/**
+ * Try to make a simulation publicly shareable. Returns true iff Tenderly's
+ * `/share` endpoint responded 2xx. On any other outcome (non-ok response,
+ * abort, network error), logs via `logger` and returns false — the caller
+ * then clears `tenderlyUrl`. `AbortError` is re-thrown so cancellation
+ * propagates cleanly instead of silently downgrading to "no URL".
+ */
+async function shareSimulation(params) {
+    const { baseUrl, config, simulationId, signal, logger } = params;
+    const safeId = encodeURIComponent(simulationId);
+    try {
+        const response = await fetch(`${baseUrl}/simulations/${safeId}/share`, {
+            method: "POST",
+            headers: { "X-Access-Key": config.accessToken },
+            signal,
+        });
+        if (!response.ok) {
+            logger?.warn("Tenderly /share returned non-ok; tenderlyUrl will be cleared", {
+                simulationId,
+                status: response.status,
+                statusText: response.statusText,
+            });
+            return false;
+        }
+        return true;
+    }
+    catch (error) {
+        // Propagate cancellation; swallow only genuine fetch-layer failures.
+        if (error instanceof Error && error.name === "AbortError")
+            throw error;
+        logger?.warn("Tenderly /share fetch failed; tenderlyUrl will be cleared", {
+            simulationId,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return false;
+    }
+}
+function parseTenderlyResponse(data, shareable) {
+    const { simulation, transaction } = data;
+    if (simulation.status !== true) {
+        const errorMessage = transaction.error_message ||
+            simulation.error_message ||
+            "Transaction simulation reverted";
+        // NOTE: `data` includes the full Tenderly response (request body, calldata,
+        // asset changes). Callers that log `error.details` should redact — see
+        // `errors.ts` doc for `SimulationRevertedError.details`.
+        throw new errors_js_1.SimulationRevertedError(errorMessage, data);
+    }
+    const rawLogs = [];
+    const logs = transaction.transaction_info.logs ?? [];
+    for (const log of logs) {
+        if (log.raw) {
+            rawLogs.push({
+                address: log.raw.address,
+                topics: log.raw.topics ?? [],
+                data: log.raw.data ?? "0x",
+            });
+        }
+    }
+    const tenderlyUrl = shareable && simulation.id
+        ? `https://dashboard.tenderly.co/shared/simulation/${simulation.id}`
+        : undefined;
+    return {
+        logs: rawLogs,
+        tenderlyUrl,
+        rawAssetChanges: transaction.transaction_info.asset_changes,
+    };
+}

package/lib/cjs/simulate/index.d.ts

@@ -0,0 +1 @@
+export { simulate } from "./simulate.js";

package/lib/cjs/simulate/index.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.simulate = void 0;
+var simulate_js_1 = require("./simulate.js");
+Object.defineProperty(exports, "simulate", { enumerable: true, get: function () { return simulate_js_1.simulate; } });

package/lib/cjs/simulate/parsing/index.d.ts

@@ -0,0 +1 @@
+export { parseTransfers } from "./transfers.js";

package/lib/cjs/simulate/parsing/index.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseTransfers = void 0;
+var transfers_js_1 = require("./transfers.js");
+Object.defineProperty(exports, "parseTransfers", { enumerable: true, get: function () { return transfers_js_1.parseTransfers; } });

package/lib/cjs/simulate/parsing/transfers.d.ts

@@ -0,0 +1,27 @@
+import type { RawLog, SimulationLogger, Transfer } from "../../types.js";
+export declare const TRANSFER_TOPIC = "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef";
+export declare const WITHDRAWAL_TOPIC = "0x7fcf532c15f0a6db0bd6d0e038bea71d30d808c7d98cb3bf7268a95bf5081b65";
+export declare const DEPOSIT_TOPIC = "0xe1fffcc4923d04b559f4d29a8bfc6cda04eb5b0d3c460751c2402c5c5cc9109c";
+/**
+ * Parse raw EVM logs into individual Transfer events.
+ *
+ * **Supported event types:** ERC20 `Transfer(from, to, amount)` and WETH9
+ * `Deposit(to, amount)` / `Withdrawal(from, amount)`. WETH9 mint/burn Transfer
+ * events paired with their Deposit/Withdrawal are deduplicated. ERC721 and
+ * ERC1155 transfer events are **not** parsed — consumers with NFT flows will
+ * see an incomplete transfer list.
+ *
+ * **WETH9-specific dedup:** matches Transfer-to/from zero against the
+ * matching Deposit/Withdrawal event on the same contract with the same data
+ * and withdrawer. Non-standard wrapped-native implementations (e.g., rebasing
+ * or fee-on-withdraw wrappers) may escape the dedup and produce double-counts.
+ *
+ * **Failure mode:** on a per-log parse failure (malformed topic length,
+ * non-hex data), the log is skipped and a `warn` is emitted via the logger.
+ * The caller receives a possibly-incomplete transfer list. Upstream sources
+ * (e.g., Tenderly response schemas) should validate log shape before calling
+ * here to avoid silent drops.
+ *
+ * Output is sorted canonically by token, from, to, amount for determinism.
+ */
+export declare function parseTransfers(logs: RawLog[], logger?: SimulationLogger): Transfer[];

package/lib/cjs/simulate/parsing/transfers.js

@@ -0,0 +1,153 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEPOSIT_TOPIC = exports.WITHDRAWAL_TOPIC = exports.TRANSFER_TOPIC = void 0;
+exports.parseTransfers = parseTransfers;
+const viem_1 = require("viem");
+// keccak256("Transfer(address,address,uint256)") — ERC-20 transfer event
+exports.TRANSFER_TOPIC = "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef";
+// keccak256("Withdrawal(address,uint256)") — WETH9 unwrap event
+exports.WITHDRAWAL_TOPIC = "0x7fcf532c15f0a6db0bd6d0e038bea71d30d808c7d98cb3bf7268a95bf5081b65";
+// keccak256("Deposit(address,uint256)") — WETH9 wrap event
+exports.DEPOSIT_TOPIC = "0xe1fffcc4923d04b559f4d29a8bfc6cda04eb5b0d3c460751c2402c5c5cc9109c";
+const TOPIC_HEX_LENGTH = 66; // "0x" + 32 bytes
+const UINT256_HEX_LENGTH = 66; // "0x" + 32 bytes
+/**
+ * Parse raw EVM logs into individual Transfer events.
+ *
+ * **Supported event types:** ERC20 `Transfer(from, to, amount)` and WETH9
+ * `Deposit(to, amount)` / `Withdrawal(from, amount)`. WETH9 mint/burn Transfer
+ * events paired with their Deposit/Withdrawal are deduplicated. ERC721 and
+ * ERC1155 transfer events are **not** parsed — consumers with NFT flows will
+ * see an incomplete transfer list.
+ *
+ * **WETH9-specific dedup:** matches Transfer-to/from zero against the
+ * matching Deposit/Withdrawal event on the same contract with the same data
+ * and withdrawer. Non-standard wrapped-native implementations (e.g., rebasing
+ * or fee-on-withdraw wrappers) may escape the dedup and produce double-counts.
+ *
+ * **Failure mode:** on a per-log parse failure (malformed topic length,
+ * non-hex data), the log is skipped and a `warn` is emitted via the logger.
+ * The caller receives a possibly-incomplete transfer list. Upstream sources
+ * (e.g., Tenderly response schemas) should validate log shape before calling
+ * here to avoid silent drops.
+ *
+ * Output is sorted canonically by token, from, to, amount for determinism.
+ */
+function parseTransfers(logs, logger) {
+    const transfers = [];
+    for (const log of logs) {
+        try {
+            const topic0 = log.topics[0];
+            if (topic0 === undefined)
+                continue;
+            switch (topic0) {
+                case exports.WITHDRAWAL_TOPIC: {
+                    const fromTopic = log.topics[1];
+                    if (!isTopicHex(fromTopic) || !isUint256Hex(log.data)) {
+                        warnMalformed(logger, log, "WETH9 Withdrawal: bad topic[1] or data length");
+                        continue;
+                    }
+                    transfers.push({
+                        token: (0, viem_1.getAddress)(log.address),
+                        from: (0, viem_1.getAddress)(`0x${fromTopic.slice(26)}`),
+                        to: viem_1.zeroAddress,
+                        amount: BigInt(log.data),
+                    });
+                    continue;
+                }
+                case exports.DEPOSIT_TOPIC: {
+                    const toTopic = log.topics[1];
+                    if (!isTopicHex(toTopic) || !isUint256Hex(log.data)) {
+                        warnMalformed(logger, log, "WETH9 Deposit: bad topic[1] or data length");
+                        continue;
+                    }
+                    transfers.push({
+                        token: (0, viem_1.getAddress)(log.address),
+                        from: viem_1.zeroAddress,
+                        to: (0, viem_1.getAddress)(`0x${toTopic.slice(26)}`),
+                        amount: BigInt(log.data),
+                    });
+                    continue;
+                }
+                case exports.TRANSFER_TOPIC: {
+                    // ERC-20 Transfer has 3 topics; ERC-721 Transfer has 4 (tokenId indexed).
+                    // ERC-721 flows are out of scope.
+                    if (log.topics.length !== 3)
+                        continue;
+                    const fromTopic = log.topics[1];
+                    const toTopic = log.topics[2];
+                    if (!isTopicHex(fromTopic) ||
+                        !isTopicHex(toTopic) ||
+                        !isUint256Hex(log.data)) {
+                        warnMalformed(logger, log, "ERC20 Transfer: bad topic/data length");
+                        continue;
+                    }
+                    // WETH9 unwrap dedup: Transfer to zero paired with a Withdrawal of equal amount.
+                    if (toTopic === viem_1.zeroHash &&
+                        logs.some((other) => other.topics[0] === exports.WITHDRAWAL_TOPIC &&
+                            other.address === log.address &&
+                            other.data === log.data &&
+                            other.topics.length === 2 &&
+                            other.topics[1] === fromTopic))
+                        continue;
+                    // WETH9 wrap dedup: Transfer from zero paired with a Deposit of equal amount.
+                    if (fromTopic === viem_1.zeroHash &&
+                        logs.some((other) => other.topics[0] === exports.DEPOSIT_TOPIC &&
+                            other.address === log.address &&
+                            other.data === log.data &&
+                            other.topics.length === 2 &&
+                            other.topics[1] === toTopic))
+                        continue;
+                    transfers.push({
+                        token: (0, viem_1.getAddress)(log.address),
+                        from: (0, viem_1.getAddress)(`0x${fromTopic.slice(26)}`),
+                        to: (0, viem_1.getAddress)(`0x${toTopic.slice(26)}`),
+                        amount: BigInt(log.data),
+                    });
+                    continue;
+                }
+            }
+        }
+        catch (error) {
+            // Safety net for anything that slips past the length checks above
+            // (e.g., viem checksum throws on non-hex input). Loud enough to diagnose.
+            warnMalformed(logger, log, error instanceof Error ? error.message : String(error));
+        }
+    }
+    return sortTransfers(transfers);
+}
+function isTopicHex(value) {
+    return typeof value === "string" && value.length === TOPIC_HEX_LENGTH;
+}
+function isUint256Hex(value) {
+    return typeof value === "string" && value.length === UINT256_HEX_LENGTH;
+}
+function warnMalformed(logger, log, reason) {
+    logger?.warn("Skipping malformed log during transfer parsing", {
+        address: log.address,
+        topics: log.topics,
+        reason,
+    });
+}
+/**
+ * Canonical sort: by lowercased token, from, to, then amount. Addresses are
+ * pre-lowercased once to avoid redundant `.toLowerCase()` calls per comparison.
+ */
+function sortTransfers(transfers) {
+    const decorated = transfers.map((t) => ({
+        t,
+        tokenLc: t.token.toLowerCase(),
+        fromLc: t.from.toLowerCase(),
+        toLc: t.to.toLowerCase(),
+    }));
+    decorated.sort((a, b) => {
+        if (a.tokenLc !== b.tokenLc)
+            return a.tokenLc < b.tokenLc ? -1 : 1;
+        if (a.fromLc !== b.fromLc)
+            return a.fromLc < b.fromLc ? -1 : 1;
+        if (a.toLc !== b.toLc)
+            return a.toLc < b.toLc ? -1 : 1;
+        return a.t.amount < b.t.amount ? -1 : a.t.amount > b.t.amount ? 1 : 0;
+    });
+    return decorated.map((d) => d.t);
+}

package/lib/cjs/simulate/pipeline/build-simulation-txs.d.ts

@@ -0,0 +1,17 @@
+import type { SimulateParams, SimulationTransaction } from "../../types.js";
+/**
+ * Stage 3 of the simulate() pipeline.
+ *
+ * Prepends any resolved authorizations (e.g. ERC20 `approve` calls generated from
+ * `{ type: 'signature' }` entries) to the user's transactions. If no authorizations
+ * were supplied, returns the user's transactions unchanged.
+ *
+ * Defense-in-depth: after prepending, verifies EVERY resolved tx shares the user
+ * sender. This catches an `{ type: 'approval', transaction }` auth where the
+ * caller-provided `transaction.from` does not match the bundle sender — the
+ * `approval` variant otherwise passes through without validation. Rejecting here
+ * keeps the "all simulationTxs share one `from`" invariant the downstream
+ * backends (eth_simulateV1) assume, and prevents a malicious or buggy caller
+ * from prepending a tx on behalf of an unexpected address.
+ */
+export declare function buildSimulationTxs(params: SimulateParams): SimulationTransaction[];

package/lib/cjs/simulate/pipeline/build-simulation-txs.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildSimulationTxs = buildSimulationTxs;
+const viem_1 = require("viem");
+const errors_js_1 = require("../../errors.js");
+const index_js_1 = require("../authorizations/index.js");
+/**
+ * Stage 3 of the simulate() pipeline.
+ *
+ * Prepends any resolved authorizations (e.g. ERC20 `approve` calls generated from
+ * `{ type: 'signature' }` entries) to the user's transactions. If no authorizations
+ * were supplied, returns the user's transactions unchanged.
+ *
+ * Defense-in-depth: after prepending, verifies EVERY resolved tx shares the user
+ * sender. This catches an `{ type: 'approval', transaction }` auth where the
+ * caller-provided `transaction.from` does not match the bundle sender — the
+ * `approval` variant otherwise passes through without validation. Rejecting here
+ * keeps the "all simulationTxs share one `from`" invariant the downstream
+ * backends (eth_simulateV1) assume, and prevents a malicious or buggy caller
+ * from prepending a tx on behalf of an unexpected address.
+ */
+function buildSimulationTxs(params) {
+    const { transactions, authorizations } = params;
+    if (!authorizations || authorizations.length === 0) {
+        return transactions;
+    }
+    const sender = transactions[0].from;
+    const resolved = (0, index_js_1.resolveAuthorizations)(authorizations, sender);
+    const simulationTxs = [...resolved, ...transactions];
+    const senderChecksum = (0, viem_1.getAddress)(sender);
+    const mismatches = [];
+    for (let i = 0; i < simulationTxs.length; i++) {
+        const tx = simulationTxs[i];
+        let txFromChecksum;
+        try {
+            txFromChecksum = (0, viem_1.getAddress)(tx.from);
+        }
+        catch {
+            mismatches.push(`simulationTxs[${i}].from: not a valid address (${tx.from})`);
+            continue;
+        }
+        if (txFromChecksum !== senderChecksum) {
+            mismatches.push(`simulationTxs[${i}].from: expected ${senderChecksum}, got ${txFromChecksum}`);
+        }
+    }
+    if (mismatches.length > 0) {
+        throw new errors_js_1.SimulationValidationError("Authorization transaction(s) must share the user sender", mismatches);
+    }
+    return simulationTxs;
+}

package/lib/cjs/simulate/pipeline/bundler-retention.d.ts

@@ -0,0 +1,19 @@
+import type { SimulationLogger, Transfer } from "../../types.js";
+interface AssertNoBundlerRetentionParams {
+    chainId: number;
+    transfers: Transfer[];
+    logger?: SimulationLogger;
+}
+/**
+ * Assert that no value is retained by bundler3 contract addresses.
+ *
+ * Uses net flow (inbound minus outbound) per (bundler address, token) pair.
+ * Bundler3 legitimately receives tokens as an intermediary (user → bundler3 →
+ * vault), so gross inbound would fire false positives. We only flag when
+ * `|net| > DUST_THRESHOLD` — catching both **retention** (tokens stuck in
+ * bundler, positive net) and **drain** (bundler sending more than it received
+ * in this bundle, negative net — which implies a pre-existing or state-override
+ * balance is being drawn down, a red flag for pre-broadcast integrity).
+ */
+export declare function assertNoBundlerRetention(params: AssertNoBundlerRetentionParams): void;
+export {};