@morpho-org/evm-simulation 1.0.0

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

@@ -0,0 +1,266 @@
+import { isAddress, isHex } from "viem";
+import { z } from "zod";
+import { ExternalServiceError, SimulationRevertedError } from "../../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 = z.custom((val) => typeof val === "string" && isAddress(val));
+const hexSchema = z.custom((val) => typeof val === "string" && isHex(val));
+const tenderlyRawResponseSchema = z
+    .object({
+    simulation: z
+        .object({
+        id: z.string().optional(),
+        status: z.boolean().optional(),
+        error_message: z.string().optional(),
+    })
+        .passthrough(),
+    transaction: z
+        .object({
+        error_message: z.string().optional(),
+        transaction_info: z
+            .object({
+            logs: z
+                .array(z
+                .object({
+                raw: z
+                    .object({
+                    address: addressSchema,
+                    topics: z.array(hexSchema).optional(),
+                    data: hexSchema.optional(),
+                })
+                    .passthrough()
+                    .optional(),
+            })
+                .passthrough())
+                .optional(),
+            asset_changes: z.unknown().optional(),
+        })
+            .passthrough(),
+    })
+        .passthrough(),
+})
+    .passthrough();
+const tenderlyBundleRawResponseSchema = z
+    .object({
+    simulation_results: 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).
+ */
+export 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 SimulationRevertedError)
+            throw error;
+        if (error instanceof ExternalServiceError)
+            throw error;
+        throw new 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 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 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 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/esm/simulate/index.d.ts

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

package/lib/esm/simulate/index.js

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

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

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

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

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

package/lib/esm/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/esm/simulate/parsing/transfers.js

@@ -0,0 +1,149 @@
+import { getAddress, zeroAddress, zeroHash } from "viem";
+// keccak256("Transfer(address,address,uint256)") — ERC-20 transfer event
+export const TRANSFER_TOPIC = "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef";
+// keccak256("Withdrawal(address,uint256)") — WETH9 unwrap event
+export const WITHDRAWAL_TOPIC = "0x7fcf532c15f0a6db0bd6d0e038bea71d30d808c7d98cb3bf7268a95bf5081b65";
+// keccak256("Deposit(address,uint256)") — WETH9 wrap event
+export const 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.
+ */
+export function parseTransfers(logs, logger) {
+    const transfers = [];
+    for (const log of logs) {
+        try {
+            const topic0 = log.topics[0];
+            if (topic0 === undefined)
+                continue;
+            switch (topic0) {
+                case 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: getAddress(log.address),
+                        from: getAddress(`0x${fromTopic.slice(26)}`),
+                        to: zeroAddress,
+                        amount: BigInt(log.data),
+                    });
+                    continue;
+                }
+                case 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: getAddress(log.address),
+                        from: zeroAddress,
+                        to: getAddress(`0x${toTopic.slice(26)}`),
+                        amount: BigInt(log.data),
+                    });
+                    continue;
+                }
+                case 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 === zeroHash &&
+                        logs.some((other) => other.topics[0] === 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 === zeroHash &&
+                        logs.some((other) => other.topics[0] === DEPOSIT_TOPIC &&
+                            other.address === log.address &&
+                            other.data === log.data &&
+                            other.topics.length === 2 &&
+                            other.topics[1] === toTopic))
+                        continue;
+                    transfers.push({
+                        token: getAddress(log.address),
+                        from: getAddress(`0x${fromTopic.slice(26)}`),
+                        to: 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/esm/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/esm/simulate/pipeline/build-simulation-txs.js

@@ -0,0 +1,47 @@
+import { getAddress } from "viem";
+import { SimulationValidationError } from "../../errors.js";
+import { resolveAuthorizations } from "../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.
+ */
+export function buildSimulationTxs(params) {
+    const { transactions, authorizations } = params;
+    if (!authorizations || authorizations.length === 0) {
+        return transactions;
+    }
+    const sender = transactions[0].from;
+    const resolved = resolveAuthorizations(authorizations, sender);
+    const simulationTxs = [...resolved, ...transactions];
+    const senderChecksum = getAddress(sender);
+    const mismatches = [];
+    for (let i = 0; i < simulationTxs.length; i++) {
+        const tx = simulationTxs[i];
+        let txFromChecksum;
+        try {
+            txFromChecksum = 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 SimulationValidationError("Authorization transaction(s) must share the user sender", mismatches);
+    }
+    return simulationTxs;
+}

package/lib/esm/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 {};

package/lib/esm/simulate/pipeline/bundler-retention.js

@@ -0,0 +1,87 @@
+import { UnsupportedChainIdError, getChainAddresses, } from "@morpho-org/blue-sdk";
+import { isDefined } from "@morpho-org/morpho-ts";
+import { getAddress } from "viem";
+import { BlacklistViolationError } from "../../errors.js";
+/**
+ * Dust tolerance for bundler retention, in raw token units.
+ *
+ * 100 units is negligible for 18-decimal tokens (~1e-16). For low-decimal
+ * tokens (e.g., 2-decimal stablecoins) this represents ~1.00 token — worth
+ * keeping in mind. The threshold is intentionally token-agnostic: its purpose
+ * is to absorb rounding noise from bundler3 routing, not to define an
+ * acceptable retention amount.
+ */
+const DUST_THRESHOLD = 100n;
+function getBundlerAddresses(chainId, logger) {
+    try {
+        const addresses = getChainAddresses(chainId);
+        if (!addresses.bundler3) {
+            // blue-sdk knows the chain but didn't catalog a bundler3 for it.
+            // Treat the same as UnsupportedChainIdError — retention check skipped.
+            logger?.warn("Chain known to blue-sdk but has no bundler3 config, retention check skipped", {
+                chainId,
+            });
+            return new Set();
+        }
+        return new Set(Object.values(addresses.bundler3)
+            .filter(isDefined)
+            .map((addr) => getAddress(addr)));
+    }
+    catch (error) {
+        if (error instanceof UnsupportedChainIdError) {
+            // Loud warn: this disables a "never bypassable" check for the chain.
+            // Consumers relying on the guarantee must handle this signal.
+            logger?.warn("Chain not supported by blue-sdk, retention check skipped", {
+                chainId,
+            });
+            return new Set();
+        }
+        throw error;
+    }
+}
+/**
+ * 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 function assertNoBundlerRetention(params) {
+    const { chainId, transfers, logger } = params;
+    const bundlerAddresses = getBundlerAddresses(chainId, logger);
+    if (bundlerAddresses.size === 0)
+        return;
+    // Map keyed by (bundler, token) → structured entry. Avoids string parse-back.
+    const flow = new Map();
+    const recordFlow = (address, token, delta) => {
+        const key = `${address.toLowerCase()}:${token.toLowerCase()}`;
+        const existing = flow.get(key);
+        if (existing) {
+            existing.netChange += delta;
+        }
+        else {
+            flow.set(key, { address, token, netChange: delta });
+        }
+    };
+    for (const t of transfers) {
+        if (bundlerAddresses.has(t.to))
+            recordFlow(t.to, t.token, t.amount);
+        if (bundlerAddresses.has(t.from))
+            recordFlow(t.from, t.token, -t.amount);
+    }
+    const flagged = [...flow.values()].filter((e) => absBigInt(e.netChange) > DUST_THRESHOLD);
+    if (flagged.length > 0) {
+        throw new BlacklistViolationError("Simulation detected asset transfers retained or drained by restricted bundler contracts", flagged.map((e) => ({
+            address: e.address,
+            token: e.token,
+            netRetained: e.netChange.toString(),
+        })));
+    }
+}
+function absBigInt(x) {
+    return x < 0n ? -x : x;
+}

package/lib/esm/simulate/pipeline/execute-simulation.d.ts

@@ -0,0 +1,25 @@
+import type { BlockTag } from "viem";
+import type { RawSimulationResult, SimulationConfig, SimulationTransaction } from "../../types.js";
+/**
+ * Stage 4 of the simulate() pipeline.
+ *
+ * Dispatches the transaction bundle to the available backend with a shared timeout
+ * budget:
+ * - If Tenderly is configured for the chain, it gets `TENDERLY_BUDGET_RATIO` (60%) of
+ *   the timeout. On `ExternalServiceError`, falls back to `eth_simulateV1` with
+ *   `max(remaining, FALLBACK_MIN_BUDGET_MS)` so the fallback still has a viable
+ *   window when Tenderly eats its full slice. `SimulationRevertedError` (contract
+ *   revert) propagates immediately without retry — a revert is a property of the
+ *   bundle, not the backend.
+ * - If only `eth_simulateV1` is configured, it gets the full timeout.
+ *
+ * `shareable` is Tenderly-only: when true, the backend persists the simulation and
+ * returns a shareable URL. `eth_simulateV1` ignores it (no persistence concept).
+ */
+export declare function executeSimulation(params: {
+    config: SimulationConfig;
+    chainId: number;
+    transactions: SimulationTransaction[];
+    blockNumber?: bigint | BlockTag;
+    shareable: boolean;
+}): Promise<RawSimulationResult>;