@morpho-org/evm-simulation 4.0.0 → 4.1.0

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

@@ -6,14 +6,13 @@ import type { RawSimulationResult, SimulationTransaction } from "../../types.js"
  * Uses stateOverride to set the user's ETH balance high enough to avoid
  * false "insufficient balance for gas" reverts.
  *
- * Derives `assetChanges` (net per-token deltas grouped by account) from the
- * emitted transfer logs, plus native ETH from each transaction's top-level
- * `value` (payer debited, recipient credited, under viem's `ethAddress`).
- *
- * Coverage on this path is therefore narrower than the Tenderly backend:
- * native ETH moved through internal calls (e.g. a `WETH.withdraw` refund, a
- * swap that pays out ETH) emits no log and is not reflected in `value`, so it
- * is not captured. For full native-ETH accounting use Tenderly.
+ * Runs with `traceTransfers` enabled, so the node synthesizes native-ETH moves
+ * (the top-level `value` *and* ETH moved through internal calls — e.g. a
+ * `WETH.withdraw` refund or a swap that pays out ETH) as `Transfer` events from
+ * the native sentinel. Derives `assetChanges` (net per-token deltas grouped by
+ * account) entirely from the emitted transfer logs, with native ETH normalized
+ * to viem's `ethAddress`. Top-level `value` is intentionally *not* added on top:
+ * `traceTransfers` already logs it, so adding it would double-count.
  */
 export declare function simulateV1(params: {
     rpcUrl: string;

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

@@ -11,14 +11,13 @@ const index_js_1 = require("../parsing/index.js");
  * Uses stateOverride to set the user's ETH balance high enough to avoid
  * false "insufficient balance for gas" reverts.
  *
- * Derives `assetChanges` (net per-token deltas grouped by account) from the
- * emitted transfer logs, plus native ETH from each transaction's top-level
- * `value` (payer debited, recipient credited, under viem's `ethAddress`).
- *
- * Coverage on this path is therefore narrower than the Tenderly backend:
- * native ETH moved through internal calls (e.g. a `WETH.withdraw` refund, a
- * swap that pays out ETH) emits no log and is not reflected in `value`, so it
- * is not captured. For full native-ETH accounting use Tenderly.
+ * Runs with `traceTransfers` enabled, so the node synthesizes native-ETH moves
+ * (the top-level `value` *and* ETH moved through internal calls — e.g. a
+ * `WETH.withdraw` refund or a swap that pays out ETH) as `Transfer` events from
+ * the native sentinel. Derives `assetChanges` (net per-token deltas grouped by
+ * account) entirely from the emitted transfer logs, with native ETH normalized
+ * to viem's `ethAddress`. Top-level `value` is intentionally *not* added on top:
+ * `traceTransfers` already logs it, so adding it would double-count.
  */
 async function simulateV1(params) {
     const { rpcUrl, transactions, blockNumber, signal } = params;
@@ -53,9 +52,17 @@ async function simulateV1(params) {
             account: sender,
             calls,
             ...blockParam,
+            // Synthesize native-ETH moves (top-level value + internal calls) as
+            // Transfer logs from the native sentinel, so `parseTransfers` captures
+            // ETH that emits no real log (e.g. a WETH.withdraw refund).
+            traceTransfers: true,
             // Inflate sender ETH balance to prevent false "insufficient gas" reverts.
             // Without this, valid ERC20 flows fail when the sender has low ETH.
-            stateOverrides: [{ address: sender, balance: viem_1.maxUint256 }],
+            // Use half of uint256 (not the ceiling) so the override leaves headroom
+            // for inbound native ETH — e.g. a WETH.withdraw refund or a swap payout
+            // would overflow the recipient balance and revert the value transfer if
+            // the sender were pinned at maxUint256.
+            stateOverrides: [{ address: sender, balance: viem_1.maxUint256 / 2n }],
         });
         const results = simulationResult.results;
         if (!Array.isArray(results)) {
@@ -77,10 +84,7 @@ async function simulateV1(params) {
         }));
         return {
             calls: rawCalls,
-            assetChanges: toAssetChanges({
-                transfers: (0, index_js_1.parseTransfers)(rawCalls),
-                transactions,
-            }),
+            assetChanges: toAssetChanges((0, index_js_1.parseTransfers)(rawCalls)),
         };
     }
     catch (error) {
@@ -92,20 +96,13 @@ async function simulateV1(params) {
     }
 }
 /**
- * Reduce parsed transfer logs and top-level transaction values to net per-token
- * balance changes grouped by account. Native ETH is taken from the top-level
- * `value`s (payer debited, recipient credited — internal moves are not logged,
- * see `simulateV1` for the coverage caveat).
+ * Reduce parsed transfer logs to net per-token balance changes grouped by
+ * account. With `traceTransfers` enabled, native ETH (top-level and internal)
+ * arrives as transfer logs under viem's `ethAddress`, so no separate top-level
+ * `value` accounting is needed — doing so would double-count.
  */
-function toAssetChanges(params) {
-    const { transfers, transactions } = params;
+function toAssetChanges(transfers) {
     const entries = [];
-    for (const tx of transactions) {
-        if (!tx.value)
-            continue;
-        entries.push({ account: tx.from, token: viem_1.ethAddress, diff: -tx.value });
-        entries.push({ account: tx.to, token: viem_1.ethAddress, diff: tx.value });
-    }
     for (const { token, from, to, amount } of transfers) {
         entries.push({ account: to, token, diff: amount });
         entries.push({ account: from, token, diff: -amount });

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

@@ -156,7 +156,11 @@ function buildCall(tx) {
     };
 }
 function buildStateOverrides(sender) {
-    return { [sender]: { balance: (0, viem_1.numberToHex)(viem_1.maxUint256) } };
+    // Half of uint256 (not the ceiling) so the override leaves headroom for
+    // inbound native ETH — a WETH.withdraw refund or swap payout would overflow
+    // the recipient balance and revert the value transfer if the sender were
+    // pinned at maxUint256.
+    return { [sender]: { balance: (0, viem_1.numberToHex)(viem_1.maxUint256 / 2n) } };
 }
 function encodeBlock(blockNumber) {
     if (blockNumber === undefined)

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

@@ -14,6 +14,15 @@ export declare const DEPOSIT_TOPIC = "0xe1fffcc4923d04b559f4d29a8bfc6cda04eb5b0d
  * 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
+ * those made through internal calls (e.g. a `WETH.withdraw` refund) — are
+ * synthesized as `Transfer` events emitted from the native sentinel
+ * `0xeee…eee`. These are parsed like any ERC20 transfer, with `token`
+ * collapsed to viem's `ethAddress` so native deltas key consistently across
+ * 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

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

@@ -23,6 +23,15 @@ const UINT256_HEX_LENGTH = 66; // "0x" + 32 bytes
  * 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
+ * those made through internal calls (e.g. a `WETH.withdraw` refund) — are
+ * synthesized as `Transfer` events emitted from the native sentinel
+ * `0xeee…eee`. These are parsed like any ERC20 transfer, with `token`
+ * collapsed to viem's `ethAddress` so native deltas key consistently across
+ * 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
@@ -132,7 +141,7 @@ function parseTransfers(calls, logger) {
                             }
                         }
                         transfers.push({
-                            token: (0, viem_1.getAddress)(log.address),
+                            token: normalizeTransferToken(log.address),
                             from: (0, viem_1.getAddress)(`0x${fromTopic.slice(26)}`),
                             to: (0, viem_1.getAddress)(`0x${toTopic.slice(26)}`),
                             amount: BigInt(log.data),
@@ -153,6 +162,21 @@ 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;
 }

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

@@ -9,11 +9,11 @@ interface AssertNoBundlerRetentionParams {
  *
  * 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).
+ * vault), so gross inbound would fire false positives. We only block positive
+ * net flow above `DUST_THRESHOLD` — tokens 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.
  */
 export declare function assertNoBundlerRetention(params: AssertNoBundlerRetentionParams): void;
 export {};

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

@@ -47,11 +47,11 @@ function getBundlerAddresses(chainId, logger) {
  *
  * 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).
+ * vault), so gross inbound would fire false positives. We only block positive
+ * net flow above `DUST_THRESHOLD` — tokens 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.
  */
 function assertNoBundlerRetention(params) {
     const { chainId, transfers, logger } = params;
@@ -77,15 +77,23 @@ function assertNoBundlerRetention(params) {
         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 errors_js_1.BlacklistViolationError("Simulation detected asset transfers retained or drained by restricted bundler contracts", flagged.map((e) => ({
+    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", {
+            changes: drained.map((e) => ({
+                address: e.address,
+                token: e.token,
+                netSwept: (-e.netChange).toString(),
+            })),
+        });
+    }
+    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) => ({
             address: e.address,
             token: e.token,
             netRetained: e.netChange.toString(),
         })));
     }
 }
-function absBigInt(x) {
-    return x < 0n ? -x : x;
-}

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

@@ -29,8 +29,8 @@ 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 or
- *   drained from a `bundler3` address beyond the dust threshold.
+ * @throws {BlacklistViolationError} when the simulation leaves value retained by
+ *   a `bundler3` address beyond the dust threshold.
  * @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

@@ -34,8 +34,8 @@ 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 or
- *   drained from a `bundler3` address beyond the dust threshold.
+ * @throws {BlacklistViolationError} when the simulation leaves value retained by
+ *   a `bundler3` address beyond the dust threshold.
  * @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/types.d.ts

@@ -82,10 +82,10 @@ export interface AssetChange {
  * alike (the zero address is kept for mints/burns). Accounts and their `changes`
  * are sorted by address for deterministic, cross-backend output.
  *
- * Native-ETH coverage differs by backend: Tenderly reports the full net ETH
- * delta (including ETH moved via internal calls), while the `eth_simulateV1`
- * fallback derives native ETH only from the top-level transaction `value`s —
- * ETH moved internally (e.g. a `WETH.withdraw` refund) is not captured there.
+ * Both backends report the full net native-ETH delta, including ETH moved via
+ * internal calls (e.g. a `WETH.withdraw` refund): Tenderly derives it from its
+ * trace, and the `eth_simulateV1` fallback runs with `traceTransfers` so the
+ * node synthesizes native moves as transfer logs under viem's `ethAddress`.
  */
 export interface AccountAssetChanges {
     readonly account: Address;

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

@@ -6,14 +6,13 @@ import type { RawSimulationResult, SimulationTransaction } from "../../types.js"
  * Uses stateOverride to set the user's ETH balance high enough to avoid
  * false "insufficient balance for gas" reverts.
  *
- * Derives `assetChanges` (net per-token deltas grouped by account) from the
- * emitted transfer logs, plus native ETH from each transaction's top-level
- * `value` (payer debited, recipient credited, under viem's `ethAddress`).
- *
- * Coverage on this path is therefore narrower than the Tenderly backend:
- * native ETH moved through internal calls (e.g. a `WETH.withdraw` refund, a
- * swap that pays out ETH) emits no log and is not reflected in `value`, so it
- * is not captured. For full native-ETH accounting use Tenderly.
+ * Runs with `traceTransfers` enabled, so the node synthesizes native-ETH moves
+ * (the top-level `value` *and* ETH moved through internal calls — e.g. a
+ * `WETH.withdraw` refund or a swap that pays out ETH) as `Transfer` events from
+ * the native sentinel. Derives `assetChanges` (net per-token deltas grouped by
+ * account) entirely from the emitted transfer logs, with native ETH normalized
+ * to viem's `ethAddress`. Top-level `value` is intentionally *not* added on top:
+ * `traceTransfers` already logs it, so adding it would double-count.
  */
 export declare function simulateV1(params: {
     rpcUrl: string;

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

@@ -1,4 +1,4 @@
-import { createPublicClient, ethAddress, getAddress, http, maxUint256, } from "viem";
+import { createPublicClient, getAddress, http, maxUint256, } from "viem";
 import { ExternalServiceError, SimulationRevertedError, SimulationValidationError, } from "../../errors.js";
 import { groupAssetChanges } from "../asset-changes.js";
 import { parseTransfers } from "../parsing/index.js";
@@ -8,14 +8,13 @@ import { parseTransfers } from "../parsing/index.js";
  * Uses stateOverride to set the user's ETH balance high enough to avoid
  * false "insufficient balance for gas" reverts.
  *
- * Derives `assetChanges` (net per-token deltas grouped by account) from the
- * emitted transfer logs, plus native ETH from each transaction's top-level
- * `value` (payer debited, recipient credited, under viem's `ethAddress`).
- *
- * Coverage on this path is therefore narrower than the Tenderly backend:
- * native ETH moved through internal calls (e.g. a `WETH.withdraw` refund, a
- * swap that pays out ETH) emits no log and is not reflected in `value`, so it
- * is not captured. For full native-ETH accounting use Tenderly.
+ * Runs with `traceTransfers` enabled, so the node synthesizes native-ETH moves
+ * (the top-level `value` *and* ETH moved through internal calls — e.g. a
+ * `WETH.withdraw` refund or a swap that pays out ETH) as `Transfer` events from
+ * the native sentinel. Derives `assetChanges` (net per-token deltas grouped by
+ * account) entirely from the emitted transfer logs, with native ETH normalized
+ * to viem's `ethAddress`. Top-level `value` is intentionally *not* added on top:
+ * `traceTransfers` already logs it, so adding it would double-count.
  */
 export async function simulateV1(params) {
     const { rpcUrl, transactions, blockNumber, signal } = params;
@@ -50,9 +49,17 @@ export async function simulateV1(params) {
             account: sender,
             calls,
             ...blockParam,
+            // Synthesize native-ETH moves (top-level value + internal calls) as
+            // Transfer logs from the native sentinel, so `parseTransfers` captures
+            // ETH that emits no real log (e.g. a WETH.withdraw refund).
+            traceTransfers: true,
             // Inflate sender ETH balance to prevent false "insufficient gas" reverts.
             // Without this, valid ERC20 flows fail when the sender has low ETH.
-            stateOverrides: [{ address: sender, balance: maxUint256 }],
+            // Use half of uint256 (not the ceiling) so the override leaves headroom
+            // for inbound native ETH — e.g. a WETH.withdraw refund or a swap payout
+            // would overflow the recipient balance and revert the value transfer if
+            // the sender were pinned at maxUint256.
+            stateOverrides: [{ address: sender, balance: maxUint256 / 2n }],
         });
         const results = simulationResult.results;
         if (!Array.isArray(results)) {
@@ -74,10 +81,7 @@ export async function simulateV1(params) {
         }));
         return {
             calls: rawCalls,
-            assetChanges: toAssetChanges({
-                transfers: parseTransfers(rawCalls),
-                transactions,
-            }),
+            assetChanges: toAssetChanges(parseTransfers(rawCalls)),
         };
     }
     catch (error) {
@@ -89,20 +93,13 @@ export async function simulateV1(params) {
     }
 }
 /**
- * Reduce parsed transfer logs and top-level transaction values to net per-token
- * balance changes grouped by account. Native ETH is taken from the top-level
- * `value`s (payer debited, recipient credited — internal moves are not logged,
- * see `simulateV1` for the coverage caveat).
+ * Reduce parsed transfer logs to net per-token balance changes grouped by
+ * account. With `traceTransfers` enabled, native ETH (top-level and internal)
+ * arrives as transfer logs under viem's `ethAddress`, so no separate top-level
+ * `value` accounting is needed — doing so would double-count.
  */
-function toAssetChanges(params) {
-    const { transfers, transactions } = params;
+function toAssetChanges(transfers) {
     const entries = [];
-    for (const tx of transactions) {
-        if (!tx.value)
-            continue;
-        entries.push({ account: tx.from, token: ethAddress, diff: -tx.value });
-        entries.push({ account: tx.to, token: ethAddress, diff: tx.value });
-    }
     for (const { token, from, to, amount } of transfers) {
         entries.push({ account: to, token, diff: amount });
         entries.push({ account: from, token, diff: -amount });

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

@@ -153,7 +153,11 @@ function buildCall(tx) {
     };
 }
 function buildStateOverrides(sender) {
-    return { [sender]: { balance: numberToHex(maxUint256) } };
+    // Half of uint256 (not the ceiling) so the override leaves headroom for
+    // inbound native ETH — a WETH.withdraw refund or swap payout would overflow
+    // the recipient balance and revert the value transfer if the sender were
+    // pinned at maxUint256.
+    return { [sender]: { balance: numberToHex(maxUint256 / 2n) } };
 }
 function encodeBlock(blockNumber) {
     if (blockNumber === undefined)

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

@@ -14,6 +14,15 @@ export declare const DEPOSIT_TOPIC = "0xe1fffcc4923d04b559f4d29a8bfc6cda04eb5b0d
  * 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
+ * those made through internal calls (e.g. a `WETH.withdraw` refund) — are
+ * synthesized as `Transfer` events emitted from the native sentinel
+ * `0xeee…eee`. These are parsed like any ERC20 transfer, with `token`
+ * collapsed to viem's `ethAddress` so native deltas key consistently across
+ * 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

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

@@ -1,4 +1,4 @@
-import { getAddress, zeroAddress, zeroHash } from "viem";
+import { ethAddress, 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
@@ -19,6 +19,15 @@ const UINT256_HEX_LENGTH = 66; // "0x" + 32 bytes
  * 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
+ * those made through internal calls (e.g. a `WETH.withdraw` refund) — are
+ * synthesized as `Transfer` events emitted from the native sentinel
+ * `0xeee…eee`. These are parsed like any ERC20 transfer, with `token`
+ * collapsed to viem's `ethAddress` so native deltas key consistently across
+ * 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
@@ -128,7 +137,7 @@ export function parseTransfers(calls, logger) {
                             }
                         }
                         transfers.push({
-                            token: getAddress(log.address),
+                            token: normalizeTransferToken(log.address),
                             from: getAddress(`0x${fromTopic.slice(26)}`),
                             to: getAddress(`0x${toTopic.slice(26)}`),
                             amount: BigInt(log.data),
@@ -149,6 +158,21 @@ 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;
 }

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

@@ -9,11 +9,11 @@ interface AssertNoBundlerRetentionParams {
  *
  * 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).
+ * vault), so gross inbound would fire false positives. We only block positive
+ * net flow above `DUST_THRESHOLD` — tokens 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.
  */
 export declare function assertNoBundlerRetention(params: AssertNoBundlerRetentionParams): void;
 export {};

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

@@ -44,11 +44,11 @@ function getBundlerAddresses(chainId, logger) {
  *
  * 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).
+ * vault), so gross inbound would fire false positives. We only block positive
+ * net flow above `DUST_THRESHOLD` — tokens 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.
  */
 export function assertNoBundlerRetention(params) {
     const { chainId, transfers, logger } = params;
@@ -74,15 +74,23 @@ export function assertNoBundlerRetention(params) {
         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) => ({
+    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", {
+            changes: drained.map((e) => ({
+                address: e.address,
+                token: e.token,
+                netSwept: (-e.netChange).toString(),
+            })),
+        });
+    }
+    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) => ({
             address: e.address,
             token: e.token,
             netRetained: e.netChange.toString(),
         })));
     }
 }
-function absBigInt(x) {
-    return x < 0n ? -x : x;
-}

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

@@ -29,8 +29,8 @@ 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 or
- *   drained from a `bundler3` address beyond the dust threshold.
+ * @throws {BlacklistViolationError} when the simulation leaves value retained by
+ *   a `bundler3` address beyond the dust threshold.
  * @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

@@ -31,8 +31,8 @@ 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 or
- *   drained from a `bundler3` address beyond the dust threshold.
+ * @throws {BlacklistViolationError} when the simulation leaves value retained by
+ *   a `bundler3` address beyond the dust threshold.
  * @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/types.d.ts

@@ -82,10 +82,10 @@ export interface AssetChange {
  * alike (the zero address is kept for mints/burns). Accounts and their `changes`
  * are sorted by address for deterministic, cross-backend output.
  *
- * Native-ETH coverage differs by backend: Tenderly reports the full net ETH
- * delta (including ETH moved via internal calls), while the `eth_simulateV1`
- * fallback derives native ETH only from the top-level transaction `value`s —
- * ETH moved internally (e.g. a `WETH.withdraw` refund) is not captured there.
+ * Both backends report the full net native-ETH delta, including ETH moved via
+ * internal calls (e.g. a `WETH.withdraw` refund): Tenderly derives it from its
+ * trace, and the `eth_simulateV1` fallback runs with `traceTransfers` so the
+ * node synthesizes native moves as transfer logs under viem's `ethAddress`.
  */
 export interface AccountAssetChanges {
     readonly account: Address;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@morpho-org/evm-simulation",
   "description": "EVM simulation engine for Morpho transactions.",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "author": "Morpho Association <contact@morpho.org>",
   "contributors": [
     "Rubilmax <rmilon@gmail.com>"
@@ -25,16 +25,16 @@
   ],
   "dependencies": {
     "zod": "^4.4.3",
-    "@morpho-org/blue-sdk": "^6.1.0",
-    "@morpho-org/morpho-ts": "^2.6.0"
+    "@morpho-org/blue-sdk": "^6.3.0",
+    "@morpho-org/morpho-ts": "^2.7.0"
   },
   "peerDependencies": {
     "viem": "^2.0.0"
   },
   "devDependencies": {
     "typescript": "^6.0.3",
-    "viem": "^2.50.4",
-    "vitest": "^4.1.7",
+    "viem": "^2.54.2",
+    "vitest": "^4.1.9",
     "@morpho-org/test": "^2.8.1"
   },
   "scripts": {