@morpho-org/evm-simulation 1.0.0 → 2.0.1

package/README.md

@@ -1,9 +1,11 @@
 # @morpho-org/evm-simulation
 
+## Overview
+
 EVM transaction simulation engine for Morpho — bundle execution preview,
 transfer parsing, and compliance screening.
 
-## Install
+## Installation
 
 Add to the consuming app's `package.json`:
 
@@ -15,7 +17,7 @@ Add to the consuming app's `package.json`:
 }
 ```
 
-## Quick start
+## Usage
 
 ```ts
 import {
@@ -60,7 +62,7 @@ try {
 }
 ```
 
-## API surface
+### API surface
 
 All symbols below are re-exported from the package root.
 
@@ -70,8 +72,16 @@ All symbols below are re-exported from the package root.
 - Data types: `SimulationTransaction`, `SimulationAuthorization`, `Transfer`, `SimulateParams`, `SimulationResult`.
 - Errors: `SimulationPackageError` (abstract base — `instanceof` it to catch any package error), `SimulationRevertedError`, `BlacklistViolationError`, `AddressScreeningError`, `ExternalServiceError`, `SimulationValidationError`, `UnsupportedChainError`.
 
-## Deeper docs
+### Deeper docs
 
 See [`CLAUDE.md`](./CLAUDE.md) in this directory for the execution flow diagram,
 backend tradeoffs, authorizations model, screening design, error-handling table,
 and recipes for adding a chain or a new backend.
+
+## Development
+
+Contribute from the monorepo root. See [CONTRIBUTING.md](../../CONTRIBUTING.md) for setup, checks, and package workflow. Report vulnerabilities through [SECURITY.md](../../SECURITY.md).
+
+## License
+
+MIT. See [LICENSE](./LICENSE).

package/lib/cjs/errors.d.ts

@@ -1,9 +1,9 @@
 /**
- * Base error for all simulation package errors.
- * Transport-agnostic — no HTTP status codes.
- * Consumers use try/catch + instanceof to handle specific error types.
+ * Base class for every error this package throws. Transport-agnostic — no HTTP status codes.
+ * Consumers pattern-match with `instanceof` on the concrete subclass.
  */
 export declare abstract class SimulationPackageError extends Error {
+    /** Stable string discriminator for log aggregation and external mapping. */
     abstract readonly code: string;
     constructor(message: string, options?: ErrorOptions);
 }

package/lib/cjs/errors.js

@@ -2,9 +2,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.UnsupportedChainError = exports.SimulationValidationError = exports.ExternalServiceError = exports.AddressScreeningError = exports.BlacklistViolationError = exports.SimulationRevertedError = exports.SimulationPackageError = void 0;
 /**
- * Base error for all simulation package errors.
- * Transport-agnostic — no HTTP status codes.
- * Consumers use try/catch + instanceof to handle specific error types.
+ * Base class for every error this package throws. Transport-agnostic — no HTTP status codes.
+ * Consumers pattern-match with `instanceof` on the concrete subclass.
  */
 class SimulationPackageError extends Error {
     constructor(message, options) {

package/lib/cjs/index.d.ts

@@ -1,4 +1,4 @@
+export { AddressScreeningError, BlacklistViolationError, ExternalServiceError, SimulationPackageError, SimulationRevertedError, SimulationValidationError, UnsupportedChainError, } from "./errors.js";
 export { screenAddresses } from "./screen-addresses/index.js";
 export { simulate } from "./simulate/index.js";
-export type { ChainSimulationConfig, SimulateParams, SimulationAuthorization, SimulationConfig, SimulationLogger, SimulationResult, SimulationTransaction, TenderlyRestConfig, Transfer, } from "./types.js";
-export { SimulationPackageError, SimulationRevertedError, BlacklistViolationError, AddressScreeningError, ExternalServiceError, SimulationValidationError, UnsupportedChainError, } from "./errors.js";
+export type { ChainSimulationConfig, RawLog, SimulateParams, SimulationAuthorization, SimulationCall, SimulationConfig, SimulationLogger, SimulationResult, SimulationTransaction, TenderlyRestConfig, Transfer, } from "./types.js";

package/lib/cjs/index.js

@@ -1,17 +1,17 @@
 "use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.UnsupportedChainError = exports.SimulationValidationError = exports.ExternalServiceError = exports.AddressScreeningError = exports.BlacklistViolationError = exports.SimulationRevertedError = exports.SimulationPackageError = exports.simulate = exports.screenAddresses = void 0;
 // Public fns (via feature-folder barrels)
-var index_js_1 = require("./screen-addresses/index.js");
-Object.defineProperty(exports, "screenAddresses", { enumerable: true, get: function () { return index_js_1.screenAddresses; } });
-var index_js_2 = require("./simulate/index.js");
-Object.defineProperty(exports, "simulate", { enumerable: true, get: function () { return index_js_2.simulate; } });
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.simulate = exports.screenAddresses = exports.UnsupportedChainError = exports.SimulationValidationError = exports.SimulationRevertedError = exports.SimulationPackageError = exports.ExternalServiceError = exports.BlacklistViolationError = exports.AddressScreeningError = void 0;
 // Errors (for instanceof checks by consumers)
 var errors_js_1 = require("./errors.js");
-Object.defineProperty(exports, "SimulationPackageError", { enumerable: true, get: function () { return errors_js_1.SimulationPackageError; } });
-Object.defineProperty(exports, "SimulationRevertedError", { enumerable: true, get: function () { return errors_js_1.SimulationRevertedError; } });
-Object.defineProperty(exports, "BlacklistViolationError", { enumerable: true, get: function () { return errors_js_1.BlacklistViolationError; } });
 Object.defineProperty(exports, "AddressScreeningError", { enumerable: true, get: function () { return errors_js_1.AddressScreeningError; } });
+Object.defineProperty(exports, "BlacklistViolationError", { enumerable: true, get: function () { return errors_js_1.BlacklistViolationError; } });
 Object.defineProperty(exports, "ExternalServiceError", { enumerable: true, get: function () { return errors_js_1.ExternalServiceError; } });
+Object.defineProperty(exports, "SimulationPackageError", { enumerable: true, get: function () { return errors_js_1.SimulationPackageError; } });
+Object.defineProperty(exports, "SimulationRevertedError", { enumerable: true, get: function () { return errors_js_1.SimulationRevertedError; } });
 Object.defineProperty(exports, "SimulationValidationError", { enumerable: true, get: function () { return errors_js_1.SimulationValidationError; } });
 Object.defineProperty(exports, "UnsupportedChainError", { enumerable: true, get: function () { return errors_js_1.UnsupportedChainError; } });
+var index_js_1 = require("./screen-addresses/index.js");
+Object.defineProperty(exports, "screenAddresses", { enumerable: true, get: function () { return index_js_1.screenAddresses; } });
+var index_js_2 = require("./simulate/index.js");
+Object.defineProperty(exports, "simulate", { enumerable: true, get: function () { return index_js_2.simulate; } });

package/lib/cjs/screen-addresses/screen-addresses.d.ts

@@ -1,29 +1,45 @@
 import type { SimulationLogger, SimulationTransaction, Transfer } from "../types.js";
 /**
- * Screen all relevant addresses from a simulation for sanctioned/compromised addresses.
+ * Screens every address that appears in a simulated bundle (transfer senders and recipients,
+ * plus tx `from` / `to`) against the static {@link sanctionedAddresses} list and, when
+ * configured, the Chainalysis Entity API.
  *
- * Screening targets (deduped, lowercased, zero-addr removed):
- * - Transfer senders and recipients from simulation result
- * - `from` and `to` of every tx in `simulationTxs` (catches native-value flows)
+ * Addresses are deduped and lowercased; the zero address is removed. Checks run in order:
  *
- * Checks run in order:
- * 1. Static {@link sanctionedAddresses} set (fast, no network, always on).
- * 2. Chainalysis Entity API — one lookup per address, lookups across addresses
- *    run in parallel. Only fires if `chainalysisApiKey` is provided.
- *    **Fail-open on transport errors before registration** (network / timeout /
- *    non-ok POST): the address is treated as clean, a warn is logged, and the
- *    simulation proceeds. This is the documented posture — a Chainalysis
- *    outage must not block all simulations.
- *    **Fail-closed on partial registration**: if the registration POST succeeded
- *    but the subsequent lookup GET fails, the address is treated as Severe.
- *    The data already persisted server-side, so failing open at this point
- *    would let a pass slip through based on a half-completed check.
- *    **Fail-closed on schema drift**: if Chainalysis returns an unknown risk
- *    tier or a body that doesn't parse, the address is treated as Severe so a
- *    future stricter tier isn't silently downgraded.
+ * 1. **Static sanctioned list** — always on, no network. Throws on the first hit.
+ * 2. **Chainalysis Entity API** — one lookup per address, lookups parallelized. Only runs when
+ *    `chainalysisApiKey` is provided.
+ *    - **Fail-open on transport errors before registration** (network / timeout / non-ok POST):
+ *      treat the address as clean and log a warn. A Chainalysis outage must not block all
+ *      simulations.
+ *    - **Fail-closed on partial registration**: if the registration POST succeeded but the
+ *      lookup GET fails, treat the address as Severe.
+ *    - **Fail-closed on schema drift**: an unknown risk tier or unparsed body is treated as
+ *      Severe so a future stricter tier is not silently downgraded.
  *
- * Throws `AddressScreeningError` on any Severe hit. Intended to be called after
- * `simulate`, passing the returned `simulationTxs` and `transfers`.
+ * Intended to be called after {@link simulate}, passing the returned `simulationTxs` and
+ * `transfers`.
+ *
+ * @param params.simulationTxs - The resolved transactions returned by `simulate()`.
+ * @param params.transfers - The parsed transfers returned by `simulate()`.
+ * @param params.chainalysisApiKey - Optional Chainalysis token. When absent, only the static
+ *   sanctioned list runs.
+ * @param params.signal - Optional `AbortSignal` propagated to every Chainalysis request.
+ * @param params.logger - Optional `SimulationLogger` for warn-level diagnostics.
+ * @returns Resolves to `void` on a clean screening; throws on any Severe hit.
+ * @throws {AddressScreeningError} when any address matches the static sanctioned list or
+ *   resolves to Severe via Chainalysis.
+ * @example
+ * ```ts
+ * import { screenAddresses, simulate } from "@morpho-org/evm-simulation";
+ *
+ * const result = await simulate(config, params);
+ * await screenAddresses({
+ *   simulationTxs: result.simulationTxs,
+ *   transfers: result.transfers,
+ *   chainalysisApiKey: process.env.CHAINALYSIS_API_KEY,
+ * });
+ * ```
  */
 export declare function screenAddresses(params: {
     simulationTxs: SimulationTransaction[];

package/lib/cjs/screen-addresses/screen-addresses.js

@@ -19,30 +19,46 @@ const chainalysisEntitySchema = zod_1.z
 })
     .passthrough();
 /**
- * Screen all relevant addresses from a simulation for sanctioned/compromised addresses.
+ * Screens every address that appears in a simulated bundle (transfer senders and recipients,
+ * plus tx `from` / `to`) against the static {@link sanctionedAddresses} list and, when
+ * configured, the Chainalysis Entity API.
  *
- * Screening targets (deduped, lowercased, zero-addr removed):
- * - Transfer senders and recipients from simulation result
- * - `from` and `to` of every tx in `simulationTxs` (catches native-value flows)
+ * Addresses are deduped and lowercased; the zero address is removed. Checks run in order:
  *
- * Checks run in order:
- * 1. Static {@link sanctionedAddresses} set (fast, no network, always on).
- * 2. Chainalysis Entity API — one lookup per address, lookups across addresses
- *    run in parallel. Only fires if `chainalysisApiKey` is provided.
- *    **Fail-open on transport errors before registration** (network / timeout /
- *    non-ok POST): the address is treated as clean, a warn is logged, and the
- *    simulation proceeds. This is the documented posture — a Chainalysis
- *    outage must not block all simulations.
- *    **Fail-closed on partial registration**: if the registration POST succeeded
- *    but the subsequent lookup GET fails, the address is treated as Severe.
- *    The data already persisted server-side, so failing open at this point
- *    would let a pass slip through based on a half-completed check.
- *    **Fail-closed on schema drift**: if Chainalysis returns an unknown risk
- *    tier or a body that doesn't parse, the address is treated as Severe so a
- *    future stricter tier isn't silently downgraded.
+ * 1. **Static sanctioned list** — always on, no network. Throws on the first hit.
+ * 2. **Chainalysis Entity API** — one lookup per address, lookups parallelized. Only runs when
+ *    `chainalysisApiKey` is provided.
+ *    - **Fail-open on transport errors before registration** (network / timeout / non-ok POST):
+ *      treat the address as clean and log a warn. A Chainalysis outage must not block all
+ *      simulations.
+ *    - **Fail-closed on partial registration**: if the registration POST succeeded but the
+ *      lookup GET fails, treat the address as Severe.
+ *    - **Fail-closed on schema drift**: an unknown risk tier or unparsed body is treated as
+ *      Severe so a future stricter tier is not silently downgraded.
  *
- * Throws `AddressScreeningError` on any Severe hit. Intended to be called after
- * `simulate`, passing the returned `simulationTxs` and `transfers`.
+ * Intended to be called after {@link simulate}, passing the returned `simulationTxs` and
+ * `transfers`.
+ *
+ * @param params.simulationTxs - The resolved transactions returned by `simulate()`.
+ * @param params.transfers - The parsed transfers returned by `simulate()`.
+ * @param params.chainalysisApiKey - Optional Chainalysis token. When absent, only the static
+ *   sanctioned list runs.
+ * @param params.signal - Optional `AbortSignal` propagated to every Chainalysis request.
+ * @param params.logger - Optional `SimulationLogger` for warn-level diagnostics.
+ * @returns Resolves to `void` on a clean screening; throws on any Severe hit.
+ * @throws {AddressScreeningError} when any address matches the static sanctioned list or
+ *   resolves to Severe via Chainalysis.
+ * @example
+ * ```ts
+ * import { screenAddresses, simulate } from "@morpho-org/evm-simulation";
+ *
+ * const result = await simulate(config, params);
+ * await screenAddresses({
+ *   simulationTxs: result.simulationTxs,
+ *   transfers: result.transfers,
+ *   chainalysisApiKey: process.env.CHAINALYSIS_API_KEY,
+ * });
+ * ```
  */
 async function screenAddresses(params) {
     const { simulationTxs, transfers, chainalysisApiKey, signal, logger } = params;
@@ -103,7 +119,10 @@ async function screenAddresses(params) {
  *
  * A SINGLE deadline covers both the POST and the GET, keeping the per-address
  * wall-time budget at `CHAINALYSIS_TIMEOUT_MS` (5 s) rather than doubling it.
+ *
+ * @internal
  */
+// biome-ignore lint/complexity/useMaxParams: TODO refactor to ≤2 params
 async function screenWithChainalysis(address, apiKey, parentSignal) {
     const headers = {
         "Content-Type": "application/json",

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

@@ -54,17 +54,17 @@ async function simulateV1(params) {
         if (failedResult) {
             throw new errors_js_1.SimulationRevertedError(failedResult.error?.message ?? "Simulation failed", results);
         }
-        const rawLogs = [];
-        for (const r of results) {
-            for (const log of r.logs ?? []) {
-                rawLogs.push({
-                    address: log.address,
-                    topics: [...log.topics],
-                    data: log.data ?? "0x",
-                });
-            }
-        }
-        return { logs: rawLogs };
+        const rawCalls = results.map((r) => ({
+            logs: (r.logs ?? []).map((log) => ({
+                address: log.address,
+                topics: [...log.topics],
+                data: log.data ?? "0x",
+            })),
+            status: r.status === "success",
+            returnData: r.data ?? "0x",
+            gasUsed: r.gasUsed,
+        }));
+        return { calls: rawCalls };
     }
     catch (error) {
         if (error instanceof errors_js_1.SimulationRevertedError)

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

@@ -22,6 +22,7 @@ const tenderlyRawResponseSchema = zod_1.z
     transaction: zod_1.z
         .object({
         error_message: zod_1.z.string().optional(),
+        gas_used: zod_1.z.number(),
         transaction_info: zod_1.z
             .object({
             logs: zod_1.z
@@ -39,6 +40,11 @@ const tenderlyRawResponseSchema = zod_1.z
                 .passthrough())
                 .optional(),
             asset_changes: zod_1.z.unknown().optional(),
+            call_trace: zod_1.z
+                .object({
+                output: hexSchema,
+            })
+                .passthrough(),
         })
             .passthrough(),
     })
@@ -101,6 +107,7 @@ function buildBaseUrl(config) {
     return `${config.apiBaseUrl}/api/v1/account/${account}/project/${project}`;
 }
 /** Build the `TenderlySimulateRequest` body for one transaction. Shared by single + bundle. */
+// biome-ignore lint/complexity/useMaxParams: TODO refactor to ≤2 params
 function buildTxBody(tx, chainId, shareable, blockNumber) {
     return {
         network_id: String(chainId),
@@ -132,19 +139,16 @@ async function simulateSingle(params) {
         throw new errors_js_1.ExternalServiceError(`Tenderly REST API returned ${response.status}: ${response.statusText}`);
     }
     const data = tenderlyRawResponseSchema.parse(await response.json());
-    const result = parseTenderlyResponse(data, shareable);
-    if (shareable && data.simulation.id) {
-        const shared = await shareSimulation({
-            baseUrl,
-            config,
-            simulationId: data.simulation.id,
-            signal,
-            logger,
-        });
-        if (!shared)
-            result.tenderlyUrl = undefined;
-    }
-    return result;
+    const call = parseTenderlyCall(data);
+    const tenderlyUrl = await resolveTenderlyUrl({
+        baseUrl,
+        config,
+        simulationId: data.simulation.id,
+        shareable,
+        signal,
+        logger,
+    });
+    return { calls: [call], tenderlyUrl };
 }
 async function simulateBundle(params) {
     const { baseUrl, config, chainId, transactions, blockNumber, shareable, signal, logger, } = params;
@@ -165,39 +169,40 @@ async function simulateBundle(params) {
     }
     const data = tenderlyBundleRawResponseSchema.parse(await response.json());
     const simulations = data.simulation_results;
-    // Collect logs from ALL steps (approvals + main tx) for complete bundler retention coverage.
-    // Only build the shareable URL from the last step; others parse with shareable=false.
-    const allLogs = [];
-    let lastResult;
-    let lastSimulationId;
-    for (let i = 0; i < simulations.length; i++) {
-        const sim = simulations[i];
-        const isLast = i === simulations.length - 1;
-        const parsed = parseTenderlyResponse(sim, isLast && shareable);
-        allLogs.push(...parsed.logs);
-        if (isLast) {
-            lastResult = parsed;
-            lastSimulationId = sim.simulation.id;
-        }
-    }
-    // Schema enforces `.min(1)` — lastResult is always defined after the loop.
-    let tenderlyUrl = lastResult.tenderlyUrl;
-    if (shareable && tenderlyUrl && lastSimulationId) {
-        const shared = await shareSimulation({
-            baseUrl,
-            config,
-            simulationId: lastSimulationId,
-            signal,
-            logger,
-        });
-        if (!shared)
-            tenderlyUrl = undefined;
-    }
-    return {
-        logs: allLogs,
-        tenderlyUrl,
-        rawAssetChanges: lastResult.rawAssetChanges,
-    };
+    const calls = simulations.map((sim) => parseTenderlyCall(sim));
+    const lastSim = simulations[simulations.length - 1];
+    const tenderlyUrl = await resolveTenderlyUrl({
+        baseUrl,
+        config,
+        simulationId: lastSim.simulation.id,
+        shareable,
+        signal,
+        logger,
+    });
+    return { calls, tenderlyUrl };
+}
+/**
+ * Build the shareable Tenderly dashboard URL for the given simulation, if
+ * `shareable=true` and `/share` succeeds. Returns `undefined` otherwise.
+ *
+ * Mirrors the legacy "build optimistically, clear on failure" pattern: the
+ * URL is constructed up-front and cleared if `shareSimulation` returns false.
+ */
+async function resolveTenderlyUrl(params) {
+    const { baseUrl, config, simulationId, shareable, signal, logger } = params;
+    if (!shareable || !simulationId)
+        return undefined;
+    let tenderlyUrl = `https://dashboard.tenderly.co/shared/simulation/${simulationId}`;
+    const shared = await shareSimulation({
+        baseUrl,
+        config,
+        simulationId,
+        signal,
+        logger,
+    });
+    if (!shared)
+        tenderlyUrl = undefined;
+    return tenderlyUrl;
 }
 /**
  * Try to make a simulation publicly shareable. Returns true iff Tenderly's
@@ -236,7 +241,13 @@ async function shareSimulation(params) {
         return false;
     }
 }
-function parseTenderlyResponse(data, shareable) {
+/**
+ * Parse one Tenderly simulation response into a `RawCall`. The caller
+ * (single-sim or bundle) assembles the `RawSimulationResult` around it.
+ *
+ * Throws `SimulationRevertedError` if `simulation.status !== true`.
+ */
+function parseTenderlyCall(data) {
     const { simulation, transaction } = data;
     if (simulation.status !== true) {
         const errorMessage = transaction.error_message ||
@@ -258,12 +269,11 @@ function parseTenderlyResponse(data, shareable) {
             });
         }
     }
-    const tenderlyUrl = shareable && simulation.id
-        ? `https://dashboard.tenderly.co/shared/simulation/${simulation.id}`
-        : undefined;
     return {
         logs: rawLogs,
-        tenderlyUrl,
-        rawAssetChanges: transaction.transaction_info.asset_changes,
+        status: true,
+        returnData: transaction.transaction_info.call_trace.output,
+        gasUsed: BigInt(transaction.gas_used),
+        assetChanges: transaction.transaction_info.asset_changes,
     };
 }

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

@@ -1,27 +1,39 @@
-import type { RawLog, SimulationLogger, Transfer } from "../../types.js";
+import type { RawCall, SimulationLogger, Transfer } from "../../types.js";
 export declare const TRANSFER_TOPIC = "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef";
 export declare const WITHDRAWAL_TOPIC = "0x7fcf532c15f0a6db0bd6d0e038bea71d30d808c7d98cb3bf7268a95bf5081b65";
 export declare const DEPOSIT_TOPIC = "0xe1fffcc4923d04b559f4d29a8bfc6cda04eb5b0d3c460751c2402c5c5cc9109c";
 /**
  * Parse raw EVM logs into individual Transfer events.
  *
+ * Iterates over per-tx `calls` and stamps each emitted `Transfer.txIdx`
+ * 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.
  *
- * **WETH9-specific dedup:** matches Transfer-to/from zero against the
- * matching Deposit/Withdrawal event on the same contract with the same data
- * and withdrawer. Non-standard wrapped-native implementations (e.g., rebasing
- * or fee-on-withdraw wrappers) may escape the dedup and produce double-counts.
+ * **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`/
+ * `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`).
  *
  * **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.
- * The caller receives a possibly-incomplete transfer list. Upstream sources
- * (e.g., Tenderly response schemas) should validate log shape before calling
- * here to avoid silent drops.
  *
  * Output is sorted canonically by token, from, to, amount for determinism.
+ * `txIdx` is attached but does not influence sort order.
  */
-export declare function parseTransfers(logs: RawLog[], logger?: SimulationLogger): Transfer[];
+export declare function parseTransfers(calls: readonly RawCall[], logger?: SimulationLogger): Transfer[];