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

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

@@ -4,8 +4,11 @@ import type { SimulateParams, SimulationConfig, SimulationResult } from "../type
  *
  * Validates input → resolves authorizations into prepended approve txs → runs the bundle
  * through Tenderly RPC (primary) or `eth_simulateV1` (fallback) with a shared timeout
- * budget → parses ERC20/WETH transfers from per-tx logs → asserts no funds are retained
- * by `bundler3` → returns the full result set. The caller reads whichever fields they need:
+ * budget → parses ERC20 transfers and WETH9 events from per-tx logs, restricting WETH9
+ * events to the registered wrapped-native token, rejecting them on known tokenless chains,
+ * and retaining signature-based parsing for unknown chains → asserts no funds are retained
+ * by `bundler3` or the standalone `bundles` periphery contracts → returns the full result
+ * set. The caller reads whichever fields they need:
  *
  * - `transfers` → user-facing preview / server-side verification.
  * - `simulationTxs` + `transfers` → server-side verification before broadcast.
@@ -30,8 +33,9 @@ import type { SimulateParams, SimulationConfig, SimulationResult } from "../type
  *   empty transactions, malformed authorizations).
  * @throws {UnsupportedChainError} when the chain is not configured for any backend.
  * @throws {SimulationRevertedError} when the bundle reverts on either backend.
- * @throws {BlacklistViolationError} when the simulation leaves value retained by
- *   a `bundler3` address beyond the dust threshold.
+ * @throws {BlacklistViolationError} when the simulation leaves value retained beyond
+ *   the dust threshold by a restricted `bundler3` address or a `bundles` periphery
+ *   contract (VaultExitBundlesV1, VaultBundlesV1, BlueBundlesV1). Never bypassable.
  * @throws {ExternalServiceError} (a) when both backends are unavailable within the
  *   timeout budget, or (b) when a backend returns a `calls` array whose length does
  *   not match the resolved `simulationTxs` — refusing to map transfers with mismatched

package/lib/cjs/simulate/simulate.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.simulate = simulate;
+const blue_sdk_1 = require("@morpho-org/blue-sdk");
 const errors_js_1 = require("../errors.js");
 const index_js_1 = require("./parsing/index.js");
 const index_js_2 = require("./pipeline/index.js");
@@ -9,8 +10,11 @@ const index_js_2 = require("./pipeline/index.js");
  *
  * Validates input → resolves authorizations into prepended approve txs → runs the bundle
  * through Tenderly RPC (primary) or `eth_simulateV1` (fallback) with a shared timeout
- * budget → parses ERC20/WETH transfers from per-tx logs → asserts no funds are retained
- * by `bundler3` → returns the full result set. The caller reads whichever fields they need:
+ * budget → parses ERC20 transfers and WETH9 events from per-tx logs, restricting WETH9
+ * events to the registered wrapped-native token, rejecting them on known tokenless chains,
+ * and retaining signature-based parsing for unknown chains → asserts no funds are retained
+ * by `bundler3` or the standalone `bundles` periphery contracts → returns the full result
+ * set. The caller reads whichever fields they need:
  *
  * - `transfers` → user-facing preview / server-side verification.
  * - `simulationTxs` + `transfers` → server-side verification before broadcast.
@@ -35,8 +39,9 @@ const index_js_2 = require("./pipeline/index.js");
  *   empty transactions, malformed authorizations).
  * @throws {UnsupportedChainError} when the chain is not configured for any backend.
  * @throws {SimulationRevertedError} when the bundle reverts on either backend.
- * @throws {BlacklistViolationError} when the simulation leaves value retained by
- *   a `bundler3` address beyond the dust threshold.
+ * @throws {BlacklistViolationError} when the simulation leaves value retained beyond
+ *   the dust threshold by a restricted `bundler3` address or a `bundles` periphery
+ *   contract (VaultExitBundlesV1, VaultBundlesV1, BlueBundlesV1). Never bypassable.
  * @throws {ExternalServiceError} (a) when both backends are unavailable within the
  *   timeout budget, or (b) when a backend returns a `calls` array whose length does
  *   not match the resolved `simulationTxs` — refusing to map transfers with mismatched
@@ -67,17 +72,22 @@ const index_js_2 = require("./pipeline/index.js");
  */
 async function simulate(config, params) {
     (0, index_js_2.validateInput)(params);
+    const wNative = (0, blue_sdk_1._try)(() => (0, blue_sdk_1.getChainAddresses)(params.chainId).wNative ?? null, blue_sdk_1.UnsupportedChainIdError);
     const simulationTxs = (0, index_js_2.buildSimulationTxs)(params);
     const result = await (0, index_js_2.executeSimulation)({
         config,
         chainId: params.chainId,
         transactions: simulationTxs,
         blockNumber: params.blockNumber,
+        wNative,
     });
     if (result.calls.length !== simulationTxs.length) {
         throw new errors_js_1.ExternalServiceError(`Backend returned ${result.calls.length} call result(s) for ${simulationTxs.length} transaction(s) — refusing to map transfers with mismatched lengths`);
     }
-    const transfers = (0, index_js_1.parseTransfers)(result.calls, config.logger);
+    const transfers = (0, index_js_1.parseTransfers)(result.calls, {
+        wNative,
+        logger: config.logger,
+    });
     (0, index_js_2.assertNoBundlerRetention)({
         chainId: params.chainId,
         transfers,

package/lib/esm/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/esm/errors.js

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

package/lib/esm/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/esm/simulate/asset-changes.js

@@ -1,4 +1,23 @@
-import { getAddress } from "viem";
+import { ethAddress, getAddress } from "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
+ */
+export function normalizeAssetToken(address) {
+    return address.toLowerCase() === ethAddress
+        ? ethAddress
+        : getAddress(address);
+}
 // Locale-independent byte-order compare on lowercased hex, matching `sortTransfers`.
 const compareAddress = (a, b) => {
     const al = a.toLowerCase();

package/lib/esm/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/esm/simulate/backends/eth-simulate-v1.js

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

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

@@ -1,7 +1,7 @@
-import { ethAddress, getAddress, isAddress, isHex, maxUint256, numberToHex, } from "viem";
+import { ethAddress, isAddress, isHex, maxUint256, numberToHex, } from "viem";
 import { z } from "zod";
 import { ExternalServiceError, SimulationRevertedError, SimulationValidationError, } from "../../errors.js";
-import { groupAssetChanges } from "../asset-changes.js";
+import { groupAssetChanges, normalizeAssetToken, } from "../asset-changes.js";
 const addressSchema = z.custom((val) => typeof val === "string" && isAddress(val));
 const hexSchema = z.custom((val) => typeof val === "string" && isHex(val));
 const traceFrameSchema = z
@@ -206,7 +206,7 @@ function toAssetChanges(results) {
         for (const change of result.assetChanges ?? []) {
             const amount = BigInt(change.rawAmount);
             const token = change.assetInfo.contractAddress
-                ? getAddress(change.assetInfo.contractAddress)
+                ? normalizeAssetToken(change.assetInfo.contractAddress)
                 : ethAddress;
             const { symbol, decimals } = change.assetInfo;
             if (change.to)

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

@@ -1,4 +1,5 @@
-import { ethAddress, getAddress, zeroAddress, zeroHash, } from "viem";
+import { getAddress, isAddressEqual, zeroAddress, zeroHash, } from "viem";
+import { normalizeAssetToken } from "../asset-changes.js";
 // keccak256("Transfer(address,address,uint256)") — ERC-20 transfer event
 export const TRANSFER_TOPIC = "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef";
 // keccak256("Withdrawal(address,uint256)") — WETH9 unwrap event
@@ -14,10 +15,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
@@ -28,35 +32,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
  */
-export function parseTransfers(calls, logger) {
+export 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 && isAddressEqual(address, wNative));
     for (let txIdx = 0; txIdx < calls.length; txIdx++) {
         const logs = calls[txIdx].logs;
         for (const log of logs) {
@@ -66,6 +76,8 @@ export function parseTransfers(calls, logger) {
                     continue;
                 switch (topic0) {
                     case 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");
@@ -81,6 +93,8 @@ export function parseTransfers(calls, logger) {
                         continue;
                     }
                     case 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");
@@ -110,34 +124,36 @@ export function parseTransfers(calls, logger) {
                         }
                         // WETH9 unwrap dedup: Transfer to zero paired with a Withdrawal of
                         // equal amount in the SAME tx.
-                        if (toTopic === zeroHash) {
+                        if (toTopic === zeroHash && acceptsWnativeEvent(log.address)) {
                             const paired = logs.some((other) => other.topics[0] === WITHDRAWAL_TOPIC &&
-                                other.address === log.address &&
+                                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 === zeroHash) {
+                        if (fromTopic === zeroHash && acceptsWnativeEvent(log.address)) {
                             const paired = logs.some((other) => other.topics[0] === DEPOSIT_TOPIC &&
-                                other.address === log.address &&
+                                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: normalizeAssetToken(log.address),
                             from: getAddress(`0x${fromTopic.slice(26)}`),
                             to: getAddress(`0x${toTopic.slice(26)}`),
                             amount: BigInt(log.data),
@@ -158,21 +174,6 @@ export 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() === ethAddress
-        ? ethAddress
-        : getAddress(address);
-}
 function isTopicHex(value) {
     return typeof value === "string" && value.length === TOPIC_HEX_LENGTH;
 }
@@ -187,24 +188,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 === WITHDRAWAL_TOPIC || t0 === 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 === WITHDRAWAL_TOPIC || topic0 === 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/esm/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 {};