@morpho-org/evm-simulation 4.1.0 → 4.1.3

package/README.md

@@ -2,19 +2,13 @@
 
 ## Overview
 
-EVM transaction simulation engine for Morpho — bundle execution preview
-and transfer parsing.
+EVM transaction simulation engine for Morpho — bundle execution preview,
+transfer parsing, and net per-account balance changes.
 
 ## Installation
 
-Add to the consuming app's `package.json`:
-
-```jsonc
-{
-  "dependencies": {
-    "@morpho-org/evm-simulation": "workspace:*"
-  }
-}
+```bash
+pnpm add @morpho-org/evm-simulation
 ```
 
 ## Usage
@@ -40,11 +34,14 @@ const config: SimulationConfig = {
 };
 
 try {
-  const { transfers, simulationTxs } = await simulate(config, {
-    chainId: 1,
-    transactions: [{ from: user, to: vault, data: encodedDeposit }],
-    authorizations: [{ type: "signature", token: usdc, spender: vault }],
-  });
+  const { simulationTxs, calls, transfers, assetChanges } = await simulate(
+    config,
+    {
+      chainId: 1,
+      transactions: [{ from: user, to: vault, data: encodedDeposit }],
+      authorizations: [{ type: "signature", token: usdc, spender: vault }],
+    },
+  );
 } catch (err) {
   if (err instanceof SimulationRevertedError) {
     // show err.reason to the user
@@ -61,7 +58,8 @@ All symbols below are re-exported from the package root.
 
 - `simulate(config, params)` — run a bundle through the simulation pipeline.
 - Config types: `SimulationConfig`, `TenderlyRpcConfig`, `ChainSimulationConfig`, `SimulationLogger`.
-- Data types: `SimulationTransaction`, `SimulationAuthorization`, `Transfer`, `SimulateParams`, `SimulationResult`.
+- Input types: `SimulateParams`, `SimulationTransaction`, `SimulationAuthorization`.
+- Result types: `SimulationResult`, `SimulationCall`, `Transfer`, `AccountAssetChanges`, `AssetChange`, `RawLog`.
 - Errors: `SimulationPackageError` (abstract base — `instanceof` it to catch any package error), `SimulationRevertedError`, `BlacklistViolationError`, `ExternalServiceError`, `SimulationValidationError`, `UnsupportedChainError`.
 
 ### Deeper docs

package/lib/cjs/errors.d.ts

@@ -10,9 +10,9 @@ export declare abstract class SimulationPackageError extends Error {
 /** Transaction would revert on-chain. Not bypassable. */
 export declare class SimulationRevertedError extends SimulationPackageError {
     readonly reason: string | undefined;
-    readonly details?: unknown | undefined;
+    readonly details?: unknown;
     readonly code = "SIMULATION_REVERTED";
-    constructor(reason: string | undefined, details?: unknown | undefined);
+    constructor(reason: string | undefined, details?: unknown);
 }
 interface RetainedAsset {
     address: string | undefined;

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

@@ -1,7 +1,8 @@
-import type { SimulationLogger, Transfer } from "../../types.js";
+import type { AccountAssetChanges, SimulationLogger, Transfer } from "../../types.js";
 interface AssertNoBundlerRetentionParams {
     chainId: number;
     transfers: Transfer[];
+    assetChanges: readonly AccountAssetChanges[];
     logger?: SimulationLogger;
 }
 /**
@@ -10,10 +11,25 @@ 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 block positive
- * net flow above `DUST_THRESHOLD` — tokens stuck in a bundler address. Negative
+ * 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.
+ *
+ * **Two flow sources, one per asset class.** ERC20 / WETH9 retention is read
+ * from parsed `transfers` (log-derived, identical across backends). Native ETH
+ * emits no event log, so it can never appear in `transfers` on the Tenderly
+ * primary backend — Tenderly derives native moves into `assetChanges` instead.
+ * Native ETH is therefore read from `assetChanges`, the cross-backend source of
+ * truth for native value: Tenderly derives it from its trace, and
+ * `eth_simulateV1` derives it from the synthetic `traceTransfers` logs. Without
+ * this, native ETH stuck in bundler3 would pass the guard undetected on the
+ * Tenderly path (Cantina finding 1440).
+ *
+ * To avoid double-counting native ETH on `eth_simulateV1` — where the same
+ * 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.
  */
 export declare function assertNoBundlerRetention(params: AssertNoBundlerRetentionParams): void;
 export {};

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

@@ -48,13 +48,28 @@ 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 block positive
- * net flow above `DUST_THRESHOLD` — tokens stuck in a bundler address. Negative
+ * 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.
+ *
+ * **Two flow sources, one per asset class.** ERC20 / WETH9 retention is read
+ * from parsed `transfers` (log-derived, identical across backends). Native ETH
+ * emits no event log, so it can never appear in `transfers` on the Tenderly
+ * primary backend — Tenderly derives native moves into `assetChanges` instead.
+ * Native ETH is therefore read from `assetChanges`, the cross-backend source of
+ * truth for native value: Tenderly derives it from its trace, and
+ * `eth_simulateV1` derives it from the synthetic `traceTransfers` logs. Without
+ * this, native ETH stuck in bundler3 would pass the guard undetected on the
+ * Tenderly path (Cantina finding 1440).
+ *
+ * To avoid double-counting native ETH on `eth_simulateV1` — where the same
+ * 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.
  */
 function assertNoBundlerRetention(params) {
-    const { chainId, transfers, logger } = params;
+    const { chainId, transfers, assetChanges, logger } = params;
     const bundlerAddresses = getBundlerAddresses(chainId, logger);
     if (bundlerAddresses.size === 0)
         return;
@@ -71,10 +86,29 @@ function assertNoBundlerRetention(params) {
             flow.set(key, { address, token, netChange: delta });
         }
     };
+    // Native ETH from `assetChanges` (authoritative, cross-backend). Track which
+    // bundlers already have a native entry here so the transfer-log pass below
+    // 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))
+            continue;
+        for (const change of changes) {
+            if (change.token !== viem_1.ethAddress)
+                continue;
+            recordFlow(account, viem_1.ethAddress, change.diff);
+            nativeFromAssetChanges.add(account.toLowerCase());
+        }
+    }
+    // ERC20 / WETH9 retention from transfer logs. Native ETH transfers (the
+    // `eth_simulateV1` synthetic sentinel) only backfill a bundler endpoint that
+    // is absent from `nativeFromAssetChanges`, so native is never summed on top
+    // 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))
+        if (bundlerAddresses.has(t.to) && !usesAssetChangeNative(t, t.to))
             recordFlow(t.to, t.token, t.amount);
-        if (bundlerAddresses.has(t.from))
+        if (bundlerAddresses.has(t.from) && !usesAssetChangeNative(t, t.from))
             recordFlow(t.from, t.token, -t.amount);
     }
     const entries = [...flow.values()];

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

@@ -10,7 +10,8 @@ import type { SimulateParams, SimulationConfig, SimulationResult } from "../type
  * - `transfers` → user-facing preview / server-side verification.
  * - `simulationTxs` + `transfers` → server-side verification before broadcast.
  * - `calls[i]` → per-tx raw backend output (`logs`, `status`, `returnData`, `gasUsed`).
- *   Aligned 1:1 with `simulationTxs[i]`.
+ *   Aligned 1:1 with `simulationTxs[i]`. `gasUsed` is not a safe gas limit; consumers
+ *   deriving one must add their own headroom.
  * - `assetChanges` → net per-asset balance changes grouped by account (sender and
  *   counterparties) over the whole bundle, normalized to the same shape across backends.
  * - `transfers[k].txIdx` → index into `simulationTxs` of the tx that emitted the

package/lib/cjs/simulate/simulate.js

@@ -15,7 +15,8 @@ const index_js_2 = require("./pipeline/index.js");
  * - `transfers` → user-facing preview / server-side verification.
  * - `simulationTxs` + `transfers` → server-side verification before broadcast.
  * - `calls[i]` → per-tx raw backend output (`logs`, `status`, `returnData`, `gasUsed`).
- *   Aligned 1:1 with `simulationTxs[i]`.
+ *   Aligned 1:1 with `simulationTxs[i]`. `gasUsed` is not a safe gas limit; consumers
+ *   deriving one must add their own headroom.
  * - `assetChanges` → net per-asset balance changes grouped by account (sender and
  *   counterparties) over the whole bundle, normalized to the same shape across backends.
  * - `transfers[k].txIdx` → index into `simulationTxs` of the tx that emitted the
@@ -80,6 +81,7 @@ async function simulate(config, params) {
     (0, index_js_2.assertNoBundlerRetention)({
         chainId: params.chainId,
         transfers,
+        assetChanges: result.assetChanges,
         logger: config.logger,
     });
     return {

package/lib/cjs/types.d.ts

@@ -201,6 +201,11 @@ export interface SimulationCall {
     readonly status: boolean;
     /** Return data from the top-level call. */
     readonly returnData: Hex;
-    /** Gas used by this call (root frame). */
+    /**
+     * Gas consumed by this call's root frame, not a safe gas limit. This is
+     * post-refund consumption and does not account for EIP-150's 63/64 rule in
+     * nested calls, so consumers deriving a limit must add their own headroom,
+     * larger than headroom derived from `eth_estimateGas`.
+     */
     readonly gasUsed: bigint;
 }

package/lib/esm/errors.d.ts

@@ -10,9 +10,9 @@ export declare abstract class SimulationPackageError extends Error {
 /** Transaction would revert on-chain. Not bypassable. */
 export declare class SimulationRevertedError extends SimulationPackageError {
     readonly reason: string | undefined;
-    readonly details?: unknown | undefined;
+    readonly details?: unknown;
     readonly code = "SIMULATION_REVERTED";
-    constructor(reason: string | undefined, details?: unknown | undefined);
+    constructor(reason: string | undefined, details?: unknown);
 }
 interface RetainedAsset {
     address: string | undefined;

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

@@ -1,7 +1,8 @@
-import type { SimulationLogger, Transfer } from "../../types.js";
+import type { AccountAssetChanges, SimulationLogger, Transfer } from "../../types.js";
 interface AssertNoBundlerRetentionParams {
     chainId: number;
     transfers: Transfer[];
+    assetChanges: readonly AccountAssetChanges[];
     logger?: SimulationLogger;
 }
 /**
@@ -10,10 +11,25 @@ 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 block positive
- * net flow above `DUST_THRESHOLD` — tokens stuck in a bundler address. Negative
+ * 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.
+ *
+ * **Two flow sources, one per asset class.** ERC20 / WETH9 retention is read
+ * from parsed `transfers` (log-derived, identical across backends). Native ETH
+ * emits no event log, so it can never appear in `transfers` on the Tenderly
+ * primary backend — Tenderly derives native moves into `assetChanges` instead.
+ * Native ETH is therefore read from `assetChanges`, the cross-backend source of
+ * truth for native value: Tenderly derives it from its trace, and
+ * `eth_simulateV1` derives it from the synthetic `traceTransfers` logs. Without
+ * this, native ETH stuck in bundler3 would pass the guard undetected on the
+ * Tenderly path (Cantina finding 1440).
+ *
+ * To avoid double-counting native ETH on `eth_simulateV1` — where the same
+ * 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.
  */
 export declare function assertNoBundlerRetention(params: AssertNoBundlerRetentionParams): void;
 export {};

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

@@ -1,6 +1,6 @@
 import { getChainAddresses, UnsupportedChainIdError, } from "@morpho-org/blue-sdk";
 import { isDefined } from "@morpho-org/morpho-ts";
-import { getAddress } from "viem";
+import { ethAddress, getAddress } from "viem";
 import { BlacklistViolationError } from "../../errors.js";
 /**
  * Dust tolerance for bundler retention, in raw token units.
@@ -45,13 +45,28 @@ 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 block positive
- * net flow above `DUST_THRESHOLD` — tokens stuck in a bundler address. Negative
+ * 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.
+ *
+ * **Two flow sources, one per asset class.** ERC20 / WETH9 retention is read
+ * from parsed `transfers` (log-derived, identical across backends). Native ETH
+ * emits no event log, so it can never appear in `transfers` on the Tenderly
+ * primary backend — Tenderly derives native moves into `assetChanges` instead.
+ * Native ETH is therefore read from `assetChanges`, the cross-backend source of
+ * truth for native value: Tenderly derives it from its trace, and
+ * `eth_simulateV1` derives it from the synthetic `traceTransfers` logs. Without
+ * this, native ETH stuck in bundler3 would pass the guard undetected on the
+ * Tenderly path (Cantina finding 1440).
+ *
+ * To avoid double-counting native ETH on `eth_simulateV1` — where the same
+ * 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.
  */
 export function assertNoBundlerRetention(params) {
-    const { chainId, transfers, logger } = params;
+    const { chainId, transfers, assetChanges, logger } = params;
     const bundlerAddresses = getBundlerAddresses(chainId, logger);
     if (bundlerAddresses.size === 0)
         return;
@@ -68,10 +83,29 @@ export function assertNoBundlerRetention(params) {
             flow.set(key, { address, token, netChange: delta });
         }
     };
+    // Native ETH from `assetChanges` (authoritative, cross-backend). Track which
+    // bundlers already have a native entry here so the transfer-log pass below
+    // 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))
+            continue;
+        for (const change of changes) {
+            if (change.token !== ethAddress)
+                continue;
+            recordFlow(account, ethAddress, change.diff);
+            nativeFromAssetChanges.add(account.toLowerCase());
+        }
+    }
+    // ERC20 / WETH9 retention from transfer logs. Native ETH transfers (the
+    // `eth_simulateV1` synthetic sentinel) only backfill a bundler endpoint that
+    // is absent from `nativeFromAssetChanges`, so native is never summed on top
+    // 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))
+        if (bundlerAddresses.has(t.to) && !usesAssetChangeNative(t, t.to))
             recordFlow(t.to, t.token, t.amount);
-        if (bundlerAddresses.has(t.from))
+        if (bundlerAddresses.has(t.from) && !usesAssetChangeNative(t, t.from))
             recordFlow(t.from, t.token, -t.amount);
     }
     const entries = [...flow.values()];

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

@@ -10,7 +10,8 @@ import type { SimulateParams, SimulationConfig, SimulationResult } from "../type
  * - `transfers` → user-facing preview / server-side verification.
  * - `simulationTxs` + `transfers` → server-side verification before broadcast.
  * - `calls[i]` → per-tx raw backend output (`logs`, `status`, `returnData`, `gasUsed`).
- *   Aligned 1:1 with `simulationTxs[i]`.
+ *   Aligned 1:1 with `simulationTxs[i]`. `gasUsed` is not a safe gas limit; consumers
+ *   deriving one must add their own headroom.
  * - `assetChanges` → net per-asset balance changes grouped by account (sender and
  *   counterparties) over the whole bundle, normalized to the same shape across backends.
  * - `transfers[k].txIdx` → index into `simulationTxs` of the tx that emitted the

package/lib/esm/simulate/simulate.js

@@ -12,7 +12,8 @@ import { assertNoBundlerRetention, buildSimulationTxs, executeSimulation, valida
  * - `transfers` → user-facing preview / server-side verification.
  * - `simulationTxs` + `transfers` → server-side verification before broadcast.
  * - `calls[i]` → per-tx raw backend output (`logs`, `status`, `returnData`, `gasUsed`).
- *   Aligned 1:1 with `simulationTxs[i]`.
+ *   Aligned 1:1 with `simulationTxs[i]`. `gasUsed` is not a safe gas limit; consumers
+ *   deriving one must add their own headroom.
  * - `assetChanges` → net per-asset balance changes grouped by account (sender and
  *   counterparties) over the whole bundle, normalized to the same shape across backends.
  * - `transfers[k].txIdx` → index into `simulationTxs` of the tx that emitted the
@@ -77,6 +78,7 @@ export async function simulate(config, params) {
     assertNoBundlerRetention({
         chainId: params.chainId,
         transfers,
+        assetChanges: result.assetChanges,
         logger: config.logger,
     });
     return {

package/lib/esm/types.d.ts

@@ -201,6 +201,11 @@ export interface SimulationCall {
     readonly status: boolean;
     /** Return data from the top-level call. */
     readonly returnData: Hex;
-    /** Gas used by this call (root frame). */
+    /**
+     * Gas consumed by this call's root frame, not a safe gas limit. This is
+     * post-refund consumption and does not account for EIP-150's 63/64 rule in
+     * nested calls, so consumers deriving a limit must add their own headroom,
+     * larger than headroom derived from `eth_estimateGas`.
+     */
     readonly gasUsed: bigint;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@morpho-org/evm-simulation",
   "description": "EVM simulation engine for Morpho transactions.",
-  "version": "4.1.0",
+  "version": "4.1.3",
   "author": "Morpho Association <contact@morpho.org>",
   "contributors": [
     "Rubilmax <rmilon@gmail.com>"
@@ -19,23 +19,23 @@
   "license": "MIT",
   "type": "module",
   "sideEffects": false,
-  "main": "src/index.ts",
+  "main": "./lib/cjs/index.js",
   "files": [
     "lib"
   ],
   "dependencies": {
     "zod": "^4.4.3",
-    "@morpho-org/blue-sdk": "^6.3.0",
-    "@morpho-org/morpho-ts": "^2.7.0"
+    "@morpho-org/blue-sdk": "^6.5.0",
+    "@morpho-org/morpho-ts": "^2.9.0"
   },
   "peerDependencies": {
     "viem": "^2.0.0"
   },
   "devDependencies": {
-    "typescript": "^6.0.3",
-    "viem": "^2.54.2",
-    "vitest": "^4.1.9",
-    "@morpho-org/test": "^2.8.1"
+    "typescript": "^7.0.2",
+    "viem": "^2.55.10",
+    "vitest": "^4.1.10",
+    "@morpho-org/test": "^2.8.4"
   },
   "scripts": {
     "prepublish": "$npm_execpath build",
@@ -45,6 +45,7 @@
     "test": "vitest --root ../.. --project evm-simulation",
     "test:fork": "dotenv -- vitest --root ../.. --project evm-simulation-fork"
   },
+  "types": "./lib/esm/index.d.ts",
   "exports": {
     ".": {
       "types": "./lib/esm/index.d.ts",

package/src/index.ts

@@ -1,28 +0,0 @@
-// Public fns (via feature-folder barrels)
-
-// Errors (for instanceof checks by consumers)
-export {
-  BlacklistViolationError,
-  ExternalServiceError,
-  SimulationPackageError,
-  SimulationRevertedError,
-  SimulationValidationError,
-  UnsupportedChainError,
-} from "./errors.js";
-export { simulate } from "./simulate/index.js";
-// Types
-export type {
-  AccountAssetChanges,
-  AssetChange,
-  ChainSimulationConfig,
-  RawLog,
-  SimulateParams,
-  SimulationAuthorization,
-  SimulationCall,
-  SimulationConfig,
-  SimulationLogger,
-  SimulationResult,
-  SimulationTransaction,
-  TenderlyRpcConfig,
-  Transfer,
-} from "./types.js";