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

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

@@ -12,43 +12,18 @@ import { BlacklistViolationError } from "../../errors.js";
  * 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.
+ * 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
@@ -64,13 +39,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.
  */
 export 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 = getChainAddresses(chainId);
+    }
+    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;
+        }
+        throw error;
+    }
+    const restrictedAddresses = new Set();
+    if (addresses.bundler3) {
+        for (const addr of Object.values(addresses.bundler3).filter(isDefined))
+            restrictedAddresses.add(getAddress(addr));
+    }
+    if (addresses.bundles) {
+        for (const addr of Object.values(addresses.bundles).filter(isDefined))
+            restrictedAddresses.add(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) => {
@@ -88,7 +111,7 @@ export 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 !== ethAddress)
@@ -103,15 +126,15 @@ export function assertNoBundlerRetention(params) {
     // of the `assetChanges` value already recorded for that address.
     const usesAssetChangeNative = (t, addr) => t.token === 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,
@@ -121,7 +144,7 @@ export function assertNoBundlerRetention(params) {
     }
     const retained = entries.filter((e) => e.netChange > DUST_THRESHOLD);
     if (retained.length > 0) {
-        throw new BlacklistViolationError("Simulation detected asset transfers retained by restricted bundler contracts", retained.map((e) => ({
+        throw new 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/esm/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/esm/simulate/pipeline/execute-simulation.js

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

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

@@ -1,3 +1,4 @@
+import { _try, getChainAddresses, UnsupportedChainIdError, } from "@morpho-org/blue-sdk";
 import { ExternalServiceError } from "../errors.js";
 import { parseTransfers } from "./parsing/index.js";
 import { assertNoBundlerRetention, buildSimulationTxs, executeSimulation, validateInput, } from "./pipeline/index.js";
@@ -6,8 +7,11 @@ import { assertNoBundlerRetention, buildSimulationTxs, executeSimulation, valida
  *
  * 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.
@@ -32,8 +36,9 @@ import { assertNoBundlerRetention, buildSimulationTxs, executeSimulation, valida
  *   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
@@ -64,17 +69,22 @@ import { assertNoBundlerRetention, buildSimulationTxs, executeSimulation, valida
  */
 export async function simulate(config, params) {
     validateInput(params);
+    const wNative = _try(() => getChainAddresses(params.chainId).wNative ?? null, UnsupportedChainIdError);
     const simulationTxs = buildSimulationTxs(params);
     const result = await executeSimulation({
         config,
         chainId: params.chainId,
         transactions: simulationTxs,
         blockNumber: params.blockNumber,
+        wNative,
     });
     if (result.calls.length !== simulationTxs.length) {
         throw new ExternalServiceError(`Backend returned ${result.calls.length} call result(s) for ${simulationTxs.length} transaction(s) — refusing to map transfers with mismatched lengths`);
     }
-    const transfers = parseTransfers(result.calls, config.logger);
+    const transfers = parseTransfers(result.calls, {
+        wNative,
+        logger: config.logger,
+    });
     assertNoBundlerRetention({
         chainId: params.chainId,
         transfers,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@morpho-org/evm-simulation",
   "description": "EVM simulation engine for Morpho transactions.",
-  "version": "4.1.4",
+  "version": "4.1.6-next.0",
   "author": "Morpho Association <contact@morpho.org>",
   "contributors": [
     "Rubilmax <rmilon@gmail.com>"
@@ -25,17 +25,17 @@
   ],
   "dependencies": {
     "zod": "^4.4.3",
-    "@morpho-org/blue-sdk": "^6.6.0",
-    "@morpho-org/morpho-ts": "^2.10.0"
+    "@morpho-org/blue-sdk": "^6.7.0",
+    "@morpho-org/morpho-ts": "^2.11.1"
   },
   "peerDependencies": {
     "viem": "^2.0.0"
   },
   "devDependencies": {
-    "typescript": "^7.0.2",
+    "typescript": "7.0.2",
     "viem": "^2.55.10",
     "vitest": "^4.1.10",
-    "@morpho-org/test": "^2.8.4"
+    "@morpho-org/test": "^2.10.0"
   },
   "scripts": {
     "prepublish": "$npm_execpath build",