@morpho-org/evm-simulation 4.1.4 → 4.1.6-next.0

package/lib/cjs/errors.d.ts

@@ -19,7 +19,7 @@ interface RetainedAsset {
     token: string | undefined;
     netRetained: string;
 }
-/** Funds would flow to bundler3 contract addresses. Never bypassable. */
+/** Funds would flow to restricted bundler3 or bundles contract addresses. Never bypassable. */
 export declare class BlacklistViolationError extends SimulationPackageError {
     readonly assetChanges?: RetainedAsset[] | undefined;
     readonly code = "BLACKLIST_ERROR";

package/lib/cjs/errors.js

@@ -24,7 +24,7 @@ class SimulationRevertedError extends SimulationPackageError {
     }
 }
 exports.SimulationRevertedError = SimulationRevertedError;
-/** Funds would flow to bundler3 contract addresses. Never bypassable. */
+/** Funds would flow to restricted bundler3 or bundles contract addresses. Never bypassable. */
 class BlacklistViolationError extends SimulationPackageError {
     assetChanges;
     code = "BLACKLIST_ERROR";

package/lib/cjs/simulate/asset-changes.d.ts

@@ -1,4 +1,4 @@
-import { type Address } from "viem";
+import { type Address, type Hex } from "viem";
 import type { AccountAssetChanges } from "../types.js";
 /** A single signed contribution to one account's balance for one token. */
 export interface AssetChangeEntry {
@@ -8,6 +8,21 @@ export interface AssetChangeEntry {
     symbol?: string;
     decimals?: number;
 }
+/**
+ * Collapse the native-ETH sentinel to viem's lowercase `ethAddress`, checksumming
+ * any real token address. `eth_simulateV1` synthesizes native moves from the
+ * sentinel `0xeee…eee`, and Tenderly may echo it — in checksummed or any other
+ * case — as an asset change's `contractAddress`. Native ETH is keyed by the exact
+ * `ethAddress` constant here and in the bundler-retention guard, so a checksummed
+ * sentinel would land on a separate map key and silently escape retention checks.
+ * This is the single source of truth for token normalization shared by the
+ * transfer-log parser and the Tenderly asset-change mapper.
+ *
+ * @param address - Token address emitting a transfer or carried by an asset change.
+ * @returns `ethAddress` for the native sentinel, else the checksummed address.
+ * @internal
+ */
+export declare function normalizeAssetToken(address: Hex): Address;
 /**
  * Net signed per-(account, token) contributions into balance changes grouped by
  * account. Accounts and their `changes` are sorted by address for deterministic

package/lib/cjs/simulate/asset-changes.js

@@ -1,7 +1,27 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeAssetToken = normalizeAssetToken;
 exports.groupAssetChanges = groupAssetChanges;
 const viem_1 = require("viem");
+/**
+ * Collapse the native-ETH sentinel to viem's lowercase `ethAddress`, checksumming
+ * any real token address. `eth_simulateV1` synthesizes native moves from the
+ * sentinel `0xeee…eee`, and Tenderly may echo it — in checksummed or any other
+ * case — as an asset change's `contractAddress`. Native ETH is keyed by the exact
+ * `ethAddress` constant here and in the bundler-retention guard, so a checksummed
+ * sentinel would land on a separate map key and silently escape retention checks.
+ * This is the single source of truth for token normalization shared by the
+ * transfer-log parser and the Tenderly asset-change mapper.
+ *
+ * @param address - Token address emitting a transfer or carried by an asset change.
+ * @returns `ethAddress` for the native sentinel, else the checksummed address.
+ * @internal
+ */
+function normalizeAssetToken(address) {
+    return address.toLowerCase() === viem_1.ethAddress
+        ? viem_1.ethAddress
+        : (0, viem_1.getAddress)(address);
+}
 // Locale-independent byte-order compare on lowercased hex, matching `sortTransfers`.
 const compareAddress = (a, b) => {
     const al = a.toLowerCase();

package/lib/cjs/simulate/backends/eth-simulate-v1.d.ts

@@ -1,4 +1,4 @@
-import { type BlockTag } from "viem";
+import { type Address, type BlockTag } from "viem";
 import type { RawSimulationResult, SimulationTransaction } from "../../types.js";
 /**
  * Simulate transactions using eth_simulateV1 (viem simulateCalls).
@@ -19,5 +19,6 @@ export declare function simulateV1(params: {
     chainId: number;
     transactions: SimulationTransaction[];
     blockNumber?: bigint | BlockTag;
+    wNative?: Address | null;
     signal?: AbortSignal;
 }): Promise<RawSimulationResult>;

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

@@ -20,7 +20,7 @@ const index_js_1 = require("../parsing/index.js");
  * `traceTransfers` already logs it, so adding it would double-count.
  */
 async function simulateV1(params) {
-    const { rpcUrl, transactions, blockNumber, signal } = params;
+    const { rpcUrl, transactions, blockNumber, wNative, signal } = params;
     const client = (0, viem_1.createPublicClient)({
         transport: (0, viem_1.http)(rpcUrl, {
             fetchOptions: signal ? { signal } : undefined,
@@ -84,7 +84,7 @@ async function simulateV1(params) {
         }));
         return {
             calls: rawCalls,
-            assetChanges: toAssetChanges((0, index_js_1.parseTransfers)(rawCalls)),
+            assetChanges: toAssetChanges((0, index_js_1.parseTransfers)(rawCalls, { wNative })),
         };
     }
     catch (error) {

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

@@ -209,7 +209,7 @@ function toAssetChanges(results) {
         for (const change of result.assetChanges ?? []) {
             const amount = BigInt(change.rawAmount);
             const token = change.assetInfo.contractAddress
-                ? (0, viem_1.getAddress)(change.assetInfo.contractAddress)
+                ? (0, asset_changes_js_1.normalizeAssetToken)(change.assetInfo.contractAddress)
                 : viem_1.ethAddress;
             const { symbol, decimals } = change.assetInfo;
             if (change.to)

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

@@ -1,3 +1,4 @@
+import { type Address } from "viem";
 import type { RawCall, SimulationLogger, Transfer } from "../../types.js";
 export declare const TRANSFER_TOPIC = "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef";
 export declare const WITHDRAWAL_TOPIC = "0x7fcf532c15f0a6db0bd6d0e038bea71d30d808c7d98cb3bf7268a95bf5081b65";
@@ -9,10 +10,13 @@ export declare const DEPOSIT_TOPIC = "0xe1fffcc4923d04b559f4d29a8bfc6cda04eb5b0d
  * with the index of the originating call.
  *
  * **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.
+ * `Deposit(to, amount)` / `Withdrawal(from, amount)` from the registered
+ * wrapped-native token. Known chains without a wrapped-native token ignore
+ * WETH9 events and skip wrapped-native deduplication; chains without registry
+ * metadata retain legacy signature-based parsing. On enabled paths, paired
+ * mint/burn Transfer events are deduplicated. ERC721 and ERC1155 transfer
+ * events are **not** parsed — consumers with NFT flows will see an incomplete
+ * transfer list.
  *
  * **Native ETH (`eth_simulateV1` + `traceTransfers`).** When the backend runs
  * `eth_simulateV1` with `traceTransfers` enabled, native-ETH moves — including
@@ -23,26 +27,36 @@ export declare const DEPOSIT_TOPIC = "0xe1fffcc4923d04b559f4d29a8bfc6cda04eb5b0d
  * backends. Tenderly does not emit these synthetic logs (it derives native ETH
  * separately), so this path is inert there.
  *
- * **WETH9 dedup assumption — canonical atomic emission.** Dedup is scoped to
- * the same tx: a zero-address `Transfer` is suppressed only if its paired
- * `Deposit`/`Withdrawal` appears in the same `calls[txIdx].logs` slice. This
- * is correct for canonical WETH9, which always emits the `Deposit`/
+ * **WETH9 dedup assumption — canonical atomic emission.** Dedup for the
+ * registered wrapped-native token is scoped to the same tx: a zero-address
+ * `Transfer` is suppressed only if its paired `Deposit`/`Withdrawal` appears
+ * in the same `calls[txIdx].logs` slice. This is correct for canonical WETH9,
+ * which always emits the `Deposit`/
  * `Withdrawal` and the matching `Transfer(0x0, …)` / `Transfer(…, 0x0)`
  * atomically inside a single call frame. A **non-canonical wrapped-native**
  * that splits these emissions across two txs in the same bundle would leave
  * a phantom zero-address `Transfer` in the parsed output, which can be summed
  * by `assertNoBundlerRetention` and produce a false `BlacklistViolationError`.
- * When a zero-address `Transfer` misses same-tx dedup *and* its token has
- * emitted a `Deposit`/`Withdrawal` somewhere else in the bundle (i.e. it
- * looks wnative-shaped), the parser emits a `warn` so the assumption break
- * is observable before it reaches retention. None of `morpho-sdk`'s currently
- * supported chains require cross-tx dedup; the assumption is rechecked when
- * onboarding a new chain (see `evm-simulation/CLAUDE.md`).
+ * When its zero-address `Transfer` misses same-tx dedup, the parser emits a
+ * `warn` so the assumption break is observable before it reaches retention.
+ * None of `morpho-sdk`'s currently supported chains require cross-tx dedup;
+ * the assumption is rechecked when onboarding a new chain (see
+ * `evm-simulation/CLAUDE.md`).
  *
  * **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.
  *
  * Output is sorted canonically by token, from, to, amount for determinism.
  * `txIdx` is attached but does not influence sort order.
+ *
+ * @param calls - Per-transaction call results to parse.
+ * @param options - Wrapped-native metadata and optional logger. Pass `null` for
+ *   a known chain without a wrapped-native token; omit it for legacy parsing on
+ *   an unknown chain.
+ * @returns Canonically sorted transfers with their originating transaction index.
+ * @internal
  */
-export declare function parseTransfers(calls: readonly RawCall[], logger?: SimulationLogger): Transfer[];
+export declare function parseTransfers(calls: readonly RawCall[], options?: {
+    readonly wNative?: Address | null;
+    readonly logger?: SimulationLogger;
+}): Transfer[];

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

@@ -3,6 +3,7 @@ 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");
+const asset_changes_js_1 = require("../asset-changes.js");
 // keccak256("Transfer(address,address,uint256)") — ERC-20 transfer event
 exports.TRANSFER_TOPIC = "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef";
 // keccak256("Withdrawal(address,uint256)") — WETH9 unwrap event
@@ -18,10 +19,13 @@ const UINT256_HEX_LENGTH = 66; // "0x" + 32 bytes
  * with the index of the originating call.
  *
  * **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.
+ * `Deposit(to, amount)` / `Withdrawal(from, amount)` from the registered
+ * wrapped-native token. Known chains without a wrapped-native token ignore
+ * WETH9 events and skip wrapped-native deduplication; chains without registry
+ * metadata retain legacy signature-based parsing. On enabled paths, paired
+ * mint/burn Transfer events are deduplicated. ERC721 and ERC1155 transfer
+ * events are **not** parsed — consumers with NFT flows will see an incomplete
+ * transfer list.
  *
  * **Native ETH (`eth_simulateV1` + `traceTransfers`).** When the backend runs
  * `eth_simulateV1` with `traceTransfers` enabled, native-ETH moves — including
@@ -32,35 +36,41 @@ const UINT256_HEX_LENGTH = 66; // "0x" + 32 bytes
  * backends. Tenderly does not emit these synthetic logs (it derives native ETH
  * separately), so this path is inert there.
  *
- * **WETH9 dedup assumption — canonical atomic emission.** Dedup is scoped to
- * the same tx: a zero-address `Transfer` is suppressed only if its paired
- * `Deposit`/`Withdrawal` appears in the same `calls[txIdx].logs` slice. This
- * is correct for canonical WETH9, which always emits the `Deposit`/
+ * **WETH9 dedup assumption — canonical atomic emission.** Dedup for the
+ * registered wrapped-native token is scoped to the same tx: a zero-address
+ * `Transfer` is suppressed only if its paired `Deposit`/`Withdrawal` appears
+ * in the same `calls[txIdx].logs` slice. This is correct for canonical WETH9,
+ * which always emits the `Deposit`/
  * `Withdrawal` and the matching `Transfer(0x0, …)` / `Transfer(…, 0x0)`
  * atomically inside a single call frame. A **non-canonical wrapped-native**
  * that splits these emissions across two txs in the same bundle would leave
  * a phantom zero-address `Transfer` in the parsed output, which can be summed
  * by `assertNoBundlerRetention` and produce a false `BlacklistViolationError`.
- * When a zero-address `Transfer` misses same-tx dedup *and* its token has
- * emitted a `Deposit`/`Withdrawal` somewhere else in the bundle (i.e. it
- * looks wnative-shaped), the parser emits a `warn` so the assumption break
- * is observable before it reaches retention. None of `morpho-sdk`'s currently
- * supported chains require cross-tx dedup; the assumption is rechecked when
- * onboarding a new chain (see `evm-simulation/CLAUDE.md`).
+ * When its zero-address `Transfer` misses same-tx dedup, the parser emits a
+ * `warn` so the assumption break is observable before it reaches retention.
+ * None of `morpho-sdk`'s currently supported chains require cross-tx dedup;
+ * the assumption is rechecked when onboarding a new chain (see
+ * `evm-simulation/CLAUDE.md`).
  *
  * **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.
  *
  * Output is sorted canonically by token, from, to, amount for determinism.
  * `txIdx` is attached but does not influence sort order.
+ *
+ * @param calls - Per-transaction call results to parse.
+ * @param options - Wrapped-native metadata and optional logger. Pass `null` for
+ *   a known chain without a wrapped-native token; omit it for legacy parsing on
+ *   an unknown chain.
+ * @returns Canonically sorted transfers with their originating transaction index.
+ * @internal
  */
-function parseTransfers(calls, logger) {
+function parseTransfers(calls, options = {}) {
     const transfers = [];
-    // Tokens that emit `Deposit` or `Withdrawal` somewhere in the bundle look
-    // wnative-shaped. If a zero-address `Transfer` for one of these tokens
-    // misses same-tx dedup, the contract is likely emitting non-canonically
-    // (split across txs) and a phantom transfer would leak into retention.
+    const { logger, wNative } = options;
     const wnativeShapedTokens = collectWnativeShapedTokens(calls);
+    const acceptsWnativeEvent = (address) => wNative === undefined ||
+        (wNative !== null && (0, viem_1.isAddressEqual)(address, wNative));
     for (let txIdx = 0; txIdx < calls.length; txIdx++) {
         const logs = calls[txIdx].logs;
         for (const log of logs) {
@@ -70,6 +80,8 @@ function parseTransfers(calls, logger) {
                     continue;
                 switch (topic0) {
                     case exports.WITHDRAWAL_TOPIC: {
+                        if (!acceptsWnativeEvent(log.address))
+                            continue;
                         const fromTopic = log.topics[1];
                         if (!isTopicHex(fromTopic) || !isUint256Hex(log.data)) {
                             warnMalformed(logger, log, "WETH9 Withdrawal: bad topic[1] or data length");
@@ -85,6 +97,8 @@ function parseTransfers(calls, logger) {
                         continue;
                     }
                     case exports.DEPOSIT_TOPIC: {
+                        if (!acceptsWnativeEvent(log.address))
+                            continue;
                         const toTopic = log.topics[1];
                         if (!isTopicHex(toTopic) || !isUint256Hex(log.data)) {
                             warnMalformed(logger, log, "WETH9 Deposit: bad topic[1] or data length");
@@ -114,34 +128,36 @@ function parseTransfers(calls, logger) {
                         }
                         // WETH9 unwrap dedup: Transfer to zero paired with a Withdrawal of
                         // equal amount in the SAME tx.
-                        if (toTopic === viem_1.zeroHash) {
+                        if (toTopic === viem_1.zeroHash && acceptsWnativeEvent(log.address)) {
                             const paired = logs.some((other) => other.topics[0] === exports.WITHDRAWAL_TOPIC &&
-                                other.address === log.address &&
+                                (0, viem_1.isAddressEqual)(other.address, log.address) &&
                                 other.data === log.data &&
                                 other.topics.length === 2 &&
                                 other.topics[1] === fromTopic);
                             if (paired)
                                 continue;
-                            if (wnativeShapedTokens.has(log.address.toLowerCase())) {
+                            if (wNative !== undefined ||
+                                wnativeShapedTokens.has(log.address.toLowerCase())) {
                                 warnNonCanonicalWnative(logger, log, "burn", txIdx);
                             }
                         }
                         // WETH9 wrap dedup: Transfer from zero paired with a Deposit of
                         // equal amount in the SAME tx.
-                        if (fromTopic === viem_1.zeroHash) {
+                        if (fromTopic === viem_1.zeroHash && acceptsWnativeEvent(log.address)) {
                             const paired = logs.some((other) => other.topics[0] === exports.DEPOSIT_TOPIC &&
-                                other.address === log.address &&
+                                (0, viem_1.isAddressEqual)(other.address, log.address) &&
                                 other.data === log.data &&
                                 other.topics.length === 2 &&
                                 other.topics[1] === toTopic);
                             if (paired)
                                 continue;
-                            if (wnativeShapedTokens.has(log.address.toLowerCase())) {
+                            if (wNative !== undefined ||
+                                wnativeShapedTokens.has(log.address.toLowerCase())) {
                                 warnNonCanonicalWnative(logger, log, "mint", txIdx);
                             }
                         }
                         transfers.push({
-                            token: normalizeTransferToken(log.address),
+                            token: (0, asset_changes_js_1.normalizeAssetToken)(log.address),
                             from: (0, viem_1.getAddress)(`0x${fromTopic.slice(26)}`),
                             to: (0, viem_1.getAddress)(`0x${toTopic.slice(26)}`),
                             amount: BigInt(log.data),
@@ -162,21 +178,6 @@ function parseTransfers(calls, logger) {
     }
     return sortTransfers(transfers);
 }
-/**
- * Normalize a `Transfer` log's emitting address into a transfer `token`.
- *
- * `eth_simulateV1` with `traceTransfers` enabled synthesizes native-ETH moves
- * (including internal calls) as `Transfer` events emitted from the native
- * sentinel `0xeee…eee`. The rest of the SDK keys native ETH by viem's
- * `ethAddress` constant, so we collapse the sentinel to that exact value rather
- * than the checksummed form `getAddress` would produce — keeping native deltas
- * on a single map key across backends. Real ERC20 tokens are checksummed.
- */
-function normalizeTransferToken(address) {
-    return address.toLowerCase() === viem_1.ethAddress
-        ? viem_1.ethAddress
-        : (0, viem_1.getAddress)(address);
-}
 function isTopicHex(value) {
     return typeof value === "string" && value.length === TOPIC_HEX_LENGTH;
 }
@@ -191,24 +192,18 @@ function warnMalformed(logger, log, reason) {
         reason,
     });
 }
-/**
- * Collect token addresses (lowercased) that emit `Deposit` or `Withdrawal`
- * anywhere in the bundle. Used to detect when a zero-address `Transfer` that
- * misses same-tx dedup is on a wnative-shaped contract — a strong signal
- * that the contract is emitting non-canonically and a phantom transfer is
- * about to leak into bundler retention.
- */
+/** Collect contracts that emit WETH9-shaped events anywhere in the bundle. */
 function collectWnativeShapedTokens(calls) {
-    const set = new Set();
-    for (const c of calls) {
-        for (const l of c.logs) {
-            const t0 = l.topics[0];
-            if (t0 === exports.WITHDRAWAL_TOPIC || t0 === exports.DEPOSIT_TOPIC) {
-                set.add(l.address.toLowerCase());
+    const tokens = new Set();
+    for (const call of calls) {
+        for (const log of call.logs) {
+            const topic0 = log.topics[0];
+            if (topic0 === exports.WITHDRAWAL_TOPIC || topic0 === exports.DEPOSIT_TOPIC) {
+                tokens.add(log.address.toLowerCase());
             }
         }
     }
-    return set;
+    return tokens;
 }
 // biome-ignore lint/complexity/useMaxParams: structured warn with full context
 function warnNonCanonicalWnative(logger, log, kind, txIdx) {

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

@@ -6,15 +6,17 @@ interface AssertNoBundlerRetentionParams {
     logger?: SimulationLogger;
 }
 /**
- * Assert that no value is retained by bundler3 contract addresses.
+ * Assert that no value is retained by restricted contract addresses — the
+ * `bundler3` executor and adapters, plus the standalone `bundles` periphery
+ * contracts (`VaultExitBundlesV1`, `VaultBundlesV1`, `BlueBundlesV1`).
  *
- * 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 block positive
- * net flow above `DUST_THRESHOLD` — value stuck in a bundler address. Negative
- * net flow means the simulated bundle sweeps a pre-existing or state-overridden
- * bundler balance. That is useful telemetry, but not current-bundle retention,
- * so it is warned instead of raising a blacklist violation.
+ * Uses net flow (inbound minus outbound) per (restricted address, token) pair.
+ * These contracts legitimately receive tokens as an intermediary (user →
+ * bundler → vault), so gross inbound would fire false positives. We only block
+ * positive net flow above `DUST_THRESHOLD` — value stuck in a restricted
+ * address. Negative net flow means the simulated bundle sweeps a pre-existing or
+ * state-overridden balance. That is useful telemetry, but not current-bundle
+ * retention, so it is warned instead of raising a blacklist violation.
  *
  * **Two flow sources, one per asset class.** ERC20 / WETH9 retention is read
  * from parsed `transfers` (log-derived, identical across backends). Native ETH
@@ -30,6 +32,22 @@ interface AssertNoBundlerRetentionParams {
  * native move exists both as a synthetic `ethAddress` transfer log *and* in the
  * `assetChanges` derived from it — native transfer logs are only used as a
  * fallback for bundler addresses that carry no native `assetChanges` entry.
+ *
+ * @internal Internal pipeline stage, composed by `simulate`; not part of the
+ *   package's public API (only re-exported from the internal pipeline barrel).
+ * @param params.chainId - Chain whose blue-sdk `bundler3` and `bundles`
+ *   registries define the restricted address set. Chains cataloging neither are
+ *   skipped (a `logger.warn` records the skip).
+ * @param params.transfers - Parsed ERC20 / WETH9 transfer flows (plus the
+ *   `eth_simulateV1` synthetic native sentinel) scanned for net retention.
+ * @param params.assetChanges - Per-account native-ETH deltas, the cross-backend
+ *   source of truth for native value stuck in a restricted contract.
+ * @param params.logger - Optional logger. Receives retention-check skip warnings
+ *   and pre-existing-balance sweep telemetry (net-negative flow).
+ * @returns Nothing. Returns silently when no restricted contract retains value
+ *   above `DUST_THRESHOLD`; otherwise throws.
+ * @throws {BlacklistViolationError} when net inbound flow to a restricted
+ *   `bundler3` or `bundles` contract exceeds `DUST_THRESHOLD` for any token.
  */
 export declare function assertNoBundlerRetention(params: AssertNoBundlerRetentionParams): void;
 export {};

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

@@ -15,43 +15,18 @@ const errors_js_1 = require("../../errors.js");
  * acceptable retention amount.
  */
 const DUST_THRESHOLD = 100n;
-function getBundlerAddresses(chainId, logger) {
-    try {
-        const addresses = (0, blue_sdk_1.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(morpho_ts_1.isDefined)
-            .map((addr) => (0, viem_1.getAddress)(addr)));
-    }
-    catch (error) {
-        if (error instanceof blue_sdk_1.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.
+ * Assert that no value is retained by restricted contract addresses — the
+ * `bundler3` executor and adapters, plus the standalone `bundles` periphery
+ * contracts (`VaultExitBundlesV1`, `VaultBundlesV1`, `BlueBundlesV1`).
  *
- * 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 block positive
- * net flow above `DUST_THRESHOLD` — value stuck in a bundler address. Negative
- * net flow means the simulated bundle sweeps a pre-existing or state-overridden
- * bundler balance. That is useful telemetry, but not current-bundle retention,
- * so it is warned instead of raising a blacklist violation.
+ * Uses net flow (inbound minus outbound) per (restricted address, token) pair.
+ * These contracts legitimately receive tokens as an intermediary (user →
+ * bundler → vault), so gross inbound would fire false positives. We only block
+ * positive net flow above `DUST_THRESHOLD` — value stuck in a restricted
+ * address. Negative net flow means the simulated bundle sweeps a pre-existing or
+ * state-overridden balance. That is useful telemetry, but not current-bundle
+ * retention, so it is warned instead of raising a blacklist violation.
  *
  * **Two flow sources, one per asset class.** ERC20 / WETH9 retention is read
  * from parsed `transfers` (log-derived, identical across backends). Native ETH
@@ -67,13 +42,61 @@ function getBundlerAddresses(chainId, logger) {
  * native move exists both as a synthetic `ethAddress` transfer log *and* in the
  * `assetChanges` derived from it — native transfer logs are only used as a
  * fallback for bundler addresses that carry no native `assetChanges` entry.
+ *
+ * @internal Internal pipeline stage, composed by `simulate`; not part of the
+ *   package's public API (only re-exported from the internal pipeline barrel).
+ * @param params.chainId - Chain whose blue-sdk `bundler3` and `bundles`
+ *   registries define the restricted address set. Chains cataloging neither are
+ *   skipped (a `logger.warn` records the skip).
+ * @param params.transfers - Parsed ERC20 / WETH9 transfer flows (plus the
+ *   `eth_simulateV1` synthetic native sentinel) scanned for net retention.
+ * @param params.assetChanges - Per-account native-ETH deltas, the cross-backend
+ *   source of truth for native value stuck in a restricted contract.
+ * @param params.logger - Optional logger. Receives retention-check skip warnings
+ *   and pre-existing-balance sweep telemetry (net-negative flow).
+ * @returns Nothing. Returns silently when no restricted contract retains value
+ *   above `DUST_THRESHOLD`; otherwise throws.
+ * @throws {BlacklistViolationError} when net inbound flow to a restricted
+ *   `bundler3` or `bundles` contract exceeds `DUST_THRESHOLD` for any token.
  */
 function assertNoBundlerRetention(params) {
     const { chainId, transfers, assetChanges, logger } = params;
-    const bundlerAddresses = getBundlerAddresses(chainId, logger);
-    if (bundlerAddresses.size === 0)
+    // Restricted address set: the full `bundler3` sub-registry (executor + every
+    // adapter) plus the standalone `bundles` periphery contracts
+    // (`VaultExitBundlesV1`, `VaultBundlesV1`, `BlueBundlesV1`). Both families are
+    // transient intermediaries that route user value and must never retain it, so
+    // both are guarded identically.
+    let addresses;
+    try {
+        addresses = (0, blue_sdk_1.getChainAddresses)(chainId);
+    }
+    catch (error) {
+        if (error instanceof blue_sdk_1.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;
+        }
+        throw error;
+    }
+    const restrictedAddresses = new Set();
+    if (addresses.bundler3) {
+        for (const addr of Object.values(addresses.bundler3).filter(morpho_ts_1.isDefined))
+            restrictedAddresses.add((0, viem_1.getAddress)(addr));
+    }
+    if (addresses.bundles) {
+        for (const addr of Object.values(addresses.bundles).filter(morpho_ts_1.isDefined))
+            restrictedAddresses.add((0, viem_1.getAddress)(addr));
+    }
+    if (restrictedAddresses.size === 0) {
+        // blue-sdk knows the chain but cataloged neither bundler3 nor bundles for
+        // it. Treat the same as UnsupportedChainIdError — retention check skipped.
+        logger?.warn("Chain known to blue-sdk but has no bundler3 or bundles config, retention check skipped", { chainId });
         return;
-    // Map keyed by (bundler, token) → structured entry. Avoids string parse-back.
+    }
+    // Map keyed by (address, token) → structured entry. Avoids string parse-back.
     const flow = new Map();
     // biome-ignore lint/complexity/useMaxParams: TODO refactor to ≤2 params
     const recordFlow = (address, token, delta) => {
@@ -91,7 +114,7 @@ function assertNoBundlerRetention(params) {
     // does not re-add the same native move on `eth_simulateV1`.
     const nativeFromAssetChanges = new Set();
     for (const { account, changes } of assetChanges) {
-        if (!bundlerAddresses.has(account))
+        if (!restrictedAddresses.has(account))
             continue;
         for (const change of changes) {
             if (change.token !== viem_1.ethAddress)
@@ -106,15 +129,15 @@ function assertNoBundlerRetention(params) {
     // of the `assetChanges` value already recorded for that address.
     const usesAssetChangeNative = (t, addr) => t.token === viem_1.ethAddress && nativeFromAssetChanges.has(addr.toLowerCase());
     for (const t of transfers) {
-        if (bundlerAddresses.has(t.to) && !usesAssetChangeNative(t, t.to))
+        if (restrictedAddresses.has(t.to) && !usesAssetChangeNative(t, t.to))
             recordFlow(t.to, t.token, t.amount);
-        if (bundlerAddresses.has(t.from) && !usesAssetChangeNative(t, t.from))
+        if (restrictedAddresses.has(t.from) && !usesAssetChangeNative(t, t.from))
             recordFlow(t.from, t.token, -t.amount);
     }
     const entries = [...flow.values()];
     const drained = entries.filter((e) => e.netChange < -DUST_THRESHOLD);
     if (drained.length > 0) {
-        logger?.warn("Simulation detected pre-existing bundler balance being swept", {
+        logger?.warn("Simulation detected pre-existing balance being swept from a restricted bundler or bundles contract", {
             changes: drained.map((e) => ({
                 address: e.address,
                 token: e.token,
@@ -124,7 +147,7 @@ function assertNoBundlerRetention(params) {
     }
     const retained = entries.filter((e) => e.netChange > DUST_THRESHOLD);
     if (retained.length > 0) {
-        throw new errors_js_1.BlacklistViolationError("Simulation detected asset transfers retained by restricted bundler contracts", retained.map((e) => ({
+        throw new errors_js_1.BlacklistViolationError("Simulation detected asset transfers retained by restricted bundler or bundles contracts", retained.map((e) => ({
             address: e.address,
             token: e.token,
             netRetained: e.netChange.toString(),

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

@@ -1,4 +1,4 @@
-import type { BlockTag } from "viem";
+import type { Address, BlockTag } from "viem";
 import type { RawSimulationResult, SimulationConfig, SimulationTransaction } from "../../types.js";
 /**
  * Stage 4 of the simulate() pipeline.
@@ -18,4 +18,5 @@ export declare function executeSimulation(params: {
     chainId: number;
     transactions: SimulationTransaction[];
     blockNumber?: bigint | BlockTag;
+    wNative?: Address | null;
 }): Promise<RawSimulationResult>;

package/lib/cjs/simulate/pipeline/execute-simulation.js

@@ -32,7 +32,7 @@ const FALLBACK_MIN_BUDGET_MS = 1500;
  * - If only `eth_simulateV1` is configured, it gets the full timeout.
  */
 async function executeSimulation(params) {
-    const { config, chainId, transactions, blockNumber } = params;
+    const { config, chainId, transactions, blockNumber, wNative } = params;
     const chain = (0, resolve_chain_js_1.resolveChain)(config, chainId);
     const timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
     const deadline = Date.now() + timeoutMs;
@@ -62,6 +62,7 @@ async function executeSimulation(params) {
                 chainId,
                 transactions,
                 blockNumber,
+                wNative,
                 signal: AbortSignal.timeout(fallbackBudget),
             });
         }
@@ -75,6 +76,7 @@ async function executeSimulation(params) {
         chainId,
         transactions,
         blockNumber,
+        wNative,
         signal: AbortSignal.timeout(timeoutMs),
     });
 }