@morpho-org/evm-simulation 1.0.0 → 2.0.1

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

@@ -14,104 +14,139 @@ const UINT256_HEX_LENGTH = 66; // "0x" + 32 bytes
 /**
  * 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.
  */
-function parseTransfers(logs, logger) {
+function parseTransfers(calls, logger) {
     const transfers = [];
-    for (const log of logs) {
-        try {
-            const topic0 = log.topics[0];
-            if (topic0 === undefined)
-                continue;
-            switch (topic0) {
-                case exports.WITHDRAWAL_TOPIC: {
-                    const fromTopic = log.topics[1];
-                    if (!isTopicHex(fromTopic) || !isUint256Hex(log.data)) {
-                        warnMalformed(logger, log, "WETH9 Withdrawal: bad topic[1] or data length");
-                        continue;
-                    }
-                    transfers.push({
-                        token: (0, viem_1.getAddress)(log.address),
-                        from: (0, viem_1.getAddress)(`0x${fromTopic.slice(26)}`),
-                        to: viem_1.zeroAddress,
-                        amount: BigInt(log.data),
-                    });
+    // Tokens that emit `Deposit` or `Withdrawal` somewhere in the bundle look
+    // wnative-shaped. If a zero-address `Transfer` for one of these tokens
+    // misses same-tx dedup, the contract is likely emitting non-canonically
+    // (split across txs) and a phantom transfer would leak into retention.
+    const wnativeShapedTokens = collectWnativeShapedTokens(calls);
+    for (let txIdx = 0; txIdx < calls.length; txIdx++) {
+        const logs = calls[txIdx].logs;
+        for (const log of logs) {
+            try {
+                const topic0 = log.topics[0];
+                if (topic0 === undefined)
                     continue;
-                }
-                case exports.DEPOSIT_TOPIC: {
-                    const toTopic = log.topics[1];
-                    if (!isTopicHex(toTopic) || !isUint256Hex(log.data)) {
-                        warnMalformed(logger, log, "WETH9 Deposit: bad topic[1] or data length");
+                switch (topic0) {
+                    case exports.WITHDRAWAL_TOPIC: {
+                        const fromTopic = log.topics[1];
+                        if (!isTopicHex(fromTopic) || !isUint256Hex(log.data)) {
+                            warnMalformed(logger, log, "WETH9 Withdrawal: bad topic[1] or data length");
+                            continue;
+                        }
+                        transfers.push({
+                            token: (0, viem_1.getAddress)(log.address),
+                            from: (0, viem_1.getAddress)(`0x${fromTopic.slice(26)}`),
+                            to: viem_1.zeroAddress,
+                            amount: BigInt(log.data),
+                            txIdx,
+                        });
                         continue;
                     }
-                    transfers.push({
-                        token: (0, viem_1.getAddress)(log.address),
-                        from: viem_1.zeroAddress,
-                        to: (0, viem_1.getAddress)(`0x${toTopic.slice(26)}`),
-                        amount: BigInt(log.data),
-                    });
-                    continue;
-                }
-                case exports.TRANSFER_TOPIC: {
-                    // ERC-20 Transfer has 3 topics; ERC-721 Transfer has 4 (tokenId indexed).
-                    // ERC-721 flows are out of scope.
-                    if (log.topics.length !== 3)
-                        continue;
-                    const fromTopic = log.topics[1];
-                    const toTopic = log.topics[2];
-                    if (!isTopicHex(fromTopic) ||
-                        !isTopicHex(toTopic) ||
-                        !isUint256Hex(log.data)) {
-                        warnMalformed(logger, log, "ERC20 Transfer: bad topic/data length");
+                    case exports.DEPOSIT_TOPIC: {
+                        const toTopic = log.topics[1];
+                        if (!isTopicHex(toTopic) || !isUint256Hex(log.data)) {
+                            warnMalformed(logger, log, "WETH9 Deposit: bad topic[1] or data length");
+                            continue;
+                        }
+                        transfers.push({
+                            token: (0, viem_1.getAddress)(log.address),
+                            from: viem_1.zeroAddress,
+                            to: (0, viem_1.getAddress)(`0x${toTopic.slice(26)}`),
+                            amount: BigInt(log.data),
+                            txIdx,
+                        });
                         continue;
                     }
-                    // WETH9 unwrap dedup: Transfer to zero paired with a Withdrawal of equal amount.
-                    if (toTopic === viem_1.zeroHash &&
-                        logs.some((other) => other.topics[0] === exports.WITHDRAWAL_TOPIC &&
-                            other.address === log.address &&
-                            other.data === log.data &&
-                            other.topics.length === 2 &&
-                            other.topics[1] === fromTopic))
-                        continue;
-                    // WETH9 wrap dedup: Transfer from zero paired with a Deposit of equal amount.
-                    if (fromTopic === viem_1.zeroHash &&
-                        logs.some((other) => other.topics[0] === exports.DEPOSIT_TOPIC &&
-                            other.address === log.address &&
-                            other.data === log.data &&
-                            other.topics.length === 2 &&
-                            other.topics[1] === toTopic))
+                    case exports.TRANSFER_TOPIC: {
+                        // ERC-20 Transfer has 3 topics; ERC-721 Transfer has 4 (tokenId indexed).
+                        // ERC-721 flows are out of scope.
+                        if (log.topics.length !== 3)
+                            continue;
+                        const fromTopic = log.topics[1];
+                        const toTopic = log.topics[2];
+                        if (!isTopicHex(fromTopic) ||
+                            !isTopicHex(toTopic) ||
+                            !isUint256Hex(log.data)) {
+                            warnMalformed(logger, log, "ERC20 Transfer: bad topic/data length");
+                            continue;
+                        }
+                        // WETH9 unwrap dedup: Transfer to zero paired with a Withdrawal of
+                        // equal amount in the SAME tx.
+                        if (toTopic === viem_1.zeroHash) {
+                            const paired = logs.some((other) => other.topics[0] === exports.WITHDRAWAL_TOPIC &&
+                                other.address === log.address &&
+                                other.data === log.data &&
+                                other.topics.length === 2 &&
+                                other.topics[1] === fromTopic);
+                            if (paired)
+                                continue;
+                            if (wnativeShapedTokens.has(log.address.toLowerCase())) {
+                                warnNonCanonicalWnative(logger, log, "burn", txIdx);
+                            }
+                        }
+                        // WETH9 wrap dedup: Transfer from zero paired with a Deposit of
+                        // equal amount in the SAME tx.
+                        if (fromTopic === viem_1.zeroHash) {
+                            const paired = logs.some((other) => other.topics[0] === exports.DEPOSIT_TOPIC &&
+                                other.address === log.address &&
+                                other.data === log.data &&
+                                other.topics.length === 2 &&
+                                other.topics[1] === toTopic);
+                            if (paired)
+                                continue;
+                            if (wnativeShapedTokens.has(log.address.toLowerCase())) {
+                                warnNonCanonicalWnative(logger, log, "mint", txIdx);
+                            }
+                        }
+                        transfers.push({
+                            token: (0, viem_1.getAddress)(log.address),
+                            from: (0, viem_1.getAddress)(`0x${fromTopic.slice(26)}`),
+                            to: (0, viem_1.getAddress)(`0x${toTopic.slice(26)}`),
+                            amount: BigInt(log.data),
+                            txIdx,
+                        });
                         continue;
-                    transfers.push({
-                        token: (0, viem_1.getAddress)(log.address),
-                        from: (0, viem_1.getAddress)(`0x${fromTopic.slice(26)}`),
-                        to: (0, viem_1.getAddress)(`0x${toTopic.slice(26)}`),
-                        amount: BigInt(log.data),
-                    });
-                    continue;
+                    }
                 }
             }
-        }
-        catch (error) {
-            // Safety net for anything that slips past the length checks above
-            // (e.g., viem checksum throws on non-hex input). Loud enough to diagnose.
-            warnMalformed(logger, log, error instanceof Error ? error.message : String(error));
+            catch (error) {
+                // Safety net for anything that slips past the length checks above
+                // (e.g., viem checksum throws on non-hex input). Loud enough to diagnose.
+                warnMalformed(logger, log, error instanceof Error ? error.message : String(error));
+            }
         }
     }
     return sortTransfers(transfers);
@@ -122,6 +157,7 @@ function isTopicHex(value) {
 function isUint256Hex(value) {
     return typeof value === "string" && value.length === UINT256_HEX_LENGTH;
 }
+// biome-ignore lint/complexity/useMaxParams: TODO refactor to ≤2 params
 function warnMalformed(logger, log, reason) {
     logger?.warn("Skipping malformed log during transfer parsing", {
         address: log.address,
@@ -129,6 +165,34 @@ function warnMalformed(logger, log, reason) {
         reason,
     });
 }
+/**
+ * Collect token addresses (lowercased) that emit `Deposit` or `Withdrawal`
+ * anywhere in the bundle. Used to detect when a zero-address `Transfer` that
+ * misses same-tx dedup is on a wnative-shaped contract — a strong signal
+ * that the contract is emitting non-canonically and a phantom transfer is
+ * about to leak into bundler retention.
+ */
+function collectWnativeShapedTokens(calls) {
+    const set = new Set();
+    for (const c of calls) {
+        for (const l of c.logs) {
+            const t0 = l.topics[0];
+            if (t0 === exports.WITHDRAWAL_TOPIC || t0 === exports.DEPOSIT_TOPIC) {
+                set.add(l.address.toLowerCase());
+            }
+        }
+    }
+    return set;
+}
+// biome-ignore lint/complexity/useMaxParams: structured warn with full context
+function warnNonCanonicalWnative(logger, log, kind, txIdx) {
+    logger?.warn("WETH9 dedup miss: zero-address Transfer on wnative-shaped token without paired same-tx Deposit/Withdrawal — possible non-canonical wrapped-native, may cause bundler retention false positive", {
+        token: log.address,
+        kind,
+        txIdx,
+        data: log.data,
+    });
+}
 /**
  * Canonical sort: by lowercased token, from, to, then amount. Addresses are
  * pre-lowercased once to avoid redundant `.toLowerCase()` calls per comparison.

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

@@ -60,6 +60,7 @@ function assertNoBundlerRetention(params) {
         return;
     // Map keyed by (bundler, 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) => {
         const key = `${address.toLowerCase()}:${token.toLowerCase()}`;
         const existing = flow.get(key);

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

@@ -4,17 +4,56 @@ import type { SimulateParams, SimulationConfig, SimulationResult } from "../type
  *
  * Validates input → resolves authorizations into prepended approve txs → runs the bundle
  * through Tenderly REST (primary) or `eth_simulateV1` (fallback) with a shared timeout
- * budget → parses ERC20/WETH transfers from logs → asserts no funds are retained by
- * `bundler3` → returns the full result set. The caller reads whichever fields they need:
+ * 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:
  *
  * - `transfers` + `tenderlyUrl` → user-facing preview.
  * - `simulationTxs` + `transfers` → server-side verification before broadcast, then pass
  *   both to `screenAddresses` for compliance.
+ * - `calls[i]` → per-tx raw backend output (`logs`, `status`, `returnData`, `gasUsed`,
+ *   and Tenderly-only `assetChanges`). Aligned 1:1 with `simulationTxs[i]`.
+ * - `transfers[k].txIdx` → index into `simulationTxs` of the tx that emitted the
+ *   underlying log; consumers map back via `simulationTxs[transfer.txIdx]`.
  *
- * Throws `SimulationValidationError` for bad input, `UnsupportedChainError` when the chain
- * is not configured, `SimulationRevertedError` if the bundle reverts,
- * `BlacklistViolationError` if bundler retention is detected, or `ExternalServiceError` if
- * both backends are unavailable within the timeout budget.
+ * @param config - Backend configuration: Tenderly credentials, per-chain RPC URLs, optional
+ *   logger, and the overall timeout budget.
+ * @param params - Per-call simulation input.
+ * @param params.chainId - Chain id the bundle targets.
+ * @param params.transactions - The bundle's transactions, in execution order. All must share the
+ *   same `from`.
+ * @param params.authorizations - Optional token authorizations resolved into prepended approve
+ *   transactions before the main bundle runs.
+ * @param params.blockNumber - Optional pinned block number or `BlockTag`. Defaults to `latest`.
+ * @param options - Per-call simulation options.
+ * @param options.shareable - When `true`, persists the simulation in Tenderly and returns a
+ *   shareable `tenderlyUrl`. Honored only on the Tenderly backend, not on the `eth_simulateV1`
+ *   fallback. Defaults to `false`.
+ * @throws {SimulationValidationError} for invalid input (mixed senders, bad addresses,
+ *   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 {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
+ *   per-tx output.
+ * @returns A {@link SimulationResult} carrying the resolved `simulationTxs`, per-tx
+ *   `calls` (aligned 1:1 with `simulationTxs`), parsed `transfers` (each stamped with
+ *   `txIdx`), and the optional `tenderlyUrl`.
+ * @example
+ * ```ts
+ * import { simulate } from "@morpho-org/evm-simulation";
+ *
+ * const result = await simulate(
+ *   { chains: new Map([[1, { simulateV1Url: rpcUrl }]]) },
+ *   {
+ *     chainId: 1,
+ *     transactions: [{ from: user, to: vaultAddress, data: encodedCalldata, value: 0n }],
+ *   },
+ * );
+ * // result satisfies SimulationResult
+ * ```
  */
 export declare function simulate(config: SimulationConfig, params: SimulateParams, options?: {
     /**

package/lib/cjs/simulate/simulate.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.simulate = simulate;
+const errors_js_1 = require("../errors.js");
 const index_js_1 = require("./parsing/index.js");
 const index_js_2 = require("./pipeline/index.js");
 /**
@@ -8,18 +9,58 @@ const index_js_2 = require("./pipeline/index.js");
  *
  * Validates input → resolves authorizations into prepended approve txs → runs the bundle
  * through Tenderly REST (primary) or `eth_simulateV1` (fallback) with a shared timeout
- * budget → parses ERC20/WETH transfers from logs → asserts no funds are retained by
- * `bundler3` → returns the full result set. The caller reads whichever fields they need:
+ * 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:
  *
  * - `transfers` + `tenderlyUrl` → user-facing preview.
  * - `simulationTxs` + `transfers` → server-side verification before broadcast, then pass
  *   both to `screenAddresses` for compliance.
+ * - `calls[i]` → per-tx raw backend output (`logs`, `status`, `returnData`, `gasUsed`,
+ *   and Tenderly-only `assetChanges`). Aligned 1:1 with `simulationTxs[i]`.
+ * - `transfers[k].txIdx` → index into `simulationTxs` of the tx that emitted the
+ *   underlying log; consumers map back via `simulationTxs[transfer.txIdx]`.
  *
- * Throws `SimulationValidationError` for bad input, `UnsupportedChainError` when the chain
- * is not configured, `SimulationRevertedError` if the bundle reverts,
- * `BlacklistViolationError` if bundler retention is detected, or `ExternalServiceError` if
- * both backends are unavailable within the timeout budget.
+ * @param config - Backend configuration: Tenderly credentials, per-chain RPC URLs, optional
+ *   logger, and the overall timeout budget.
+ * @param params - Per-call simulation input.
+ * @param params.chainId - Chain id the bundle targets.
+ * @param params.transactions - The bundle's transactions, in execution order. All must share the
+ *   same `from`.
+ * @param params.authorizations - Optional token authorizations resolved into prepended approve
+ *   transactions before the main bundle runs.
+ * @param params.blockNumber - Optional pinned block number or `BlockTag`. Defaults to `latest`.
+ * @param options - Per-call simulation options.
+ * @param options.shareable - When `true`, persists the simulation in Tenderly and returns a
+ *   shareable `tenderlyUrl`. Honored only on the Tenderly backend, not on the `eth_simulateV1`
+ *   fallback. Defaults to `false`.
+ * @throws {SimulationValidationError} for invalid input (mixed senders, bad addresses,
+ *   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 {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
+ *   per-tx output.
+ * @returns A {@link SimulationResult} carrying the resolved `simulationTxs`, per-tx
+ *   `calls` (aligned 1:1 with `simulationTxs`), parsed `transfers` (each stamped with
+ *   `txIdx`), and the optional `tenderlyUrl`.
+ * @example
+ * ```ts
+ * import { simulate } from "@morpho-org/evm-simulation";
+ *
+ * const result = await simulate(
+ *   { chains: new Map([[1, { simulateV1Url: rpcUrl }]]) },
+ *   {
+ *     chainId: 1,
+ *     transactions: [{ from: user, to: vaultAddress, data: encodedCalldata, value: 0n }],
+ *   },
+ * );
+ * // result satisfies SimulationResult
+ * ```
  */
+// biome-ignore lint/complexity/useMaxParams: TODO refactor to ≤2 params
 async function simulate(config, params, options = {}) {
     const { shareable = false } = options;
     (0, index_js_2.validateInput)(params);
@@ -31,7 +72,10 @@ async function simulate(config, params, options = {}) {
         blockNumber: params.blockNumber,
         shareable,
     });
-    const transfers = (0, index_js_1.parseTransfers)(result.logs, config.logger);
+    if (result.calls.length !== simulationTxs.length) {
+        throw new errors_js_1.ExternalServiceError(`Backend returned ${result.calls.length} call result(s) for ${simulationTxs.length} transaction(s) — refusing to map transfers with mismatched lengths`);
+    }
+    const transfers = (0, index_js_1.parseTransfers)(result.calls, config.logger);
     (0, index_js_2.assertNoBundlerRetention)({
         chainId: params.chainId,
         transfers,
@@ -39,8 +83,8 @@ async function simulate(config, params, options = {}) {
     });
     return {
         simulationTxs,
+        calls: result.calls,
         transfers,
         tenderlyUrl: result.tenderlyUrl,
-        assetChanges: result.rawAssetChanges,
     };
 }

package/lib/cjs/types.d.ts

@@ -71,33 +71,43 @@ export type SimulationAuthorization = {
  * `SimulationResult.transfers`.
  */
 export interface Transfer {
-    token: Address;
-    from: Address;
-    to: Address;
-    amount: bigint;
+    readonly token: Address;
+    readonly from: Address;
+    readonly to: Address;
+    readonly amount: bigint;
+    /**
+     * Index into `SimulationResult.simulationTxs` of the transaction that
+     * emitted the underlying log. For bundles with prepended authorization
+     * approvals, indices `[0, simulationTxs.length - params.transactions.length)`
+     * are authorization txs; the remainder are caller-supplied.
+     */
+    readonly txIdx: number;
 }
 /**
- * Happy-path return of `simulate`. All failures throw typed errors. The same shape is
- * returned regardless of `options.shareable` — fields unused by your use case can be
- * ignored:
- *
- * - Preview (`shareable: true`): read `transfers` + `tenderlyUrl`.
- * - Verify (`shareable: false`, default): read `simulationTxs` + `transfers`, pass both
- *   to `screenAddresses`.
+ * Happy-path return of `simulate`. All failures throw typed errors.
  *
- * `tenderlyUrl` is set only when `shareable: true` AND the Tenderly backend ran
- * successfully (not the `eth_simulateV1` fallback). `assetChanges` is Tenderly-only
- * raw data.
+ * - `simulationTxs` is the full resolved transaction list (including
+ *   prepended authorization txs).
+ * - `calls[i]` corresponds 1:1 with `simulationTxs[i]` — read raw logs,
+ *   status, returnData/gasUsed, and (Tenderly only) assetChanges per tx.
+ * - `transfers[k].txIdx` indexes into `simulationTxs` to attribute each
+ *   transfer to its emitting transaction.
+ * - `tenderlyUrl` is set only when `shareable: true` AND the Tenderly backend
+ *   ran successfully (not the `eth_simulateV1` fallback).
  */
 export interface SimulationResult {
     /** The full resolved transaction list (including prepended authorization txs). */
-    simulationTxs: SimulationTransaction[];
+    readonly simulationTxs: readonly SimulationTransaction[];
+    /**
+     * Per-transaction normalized output. `calls[i]` corresponds 1:1 with
+     * `simulationTxs[i]`. Use this to read raw logs, status, return data, gas
+     * used, and (Tenderly only) asset changes per transaction.
+     */
+    readonly calls: readonly SimulationCall[];
     /** Parsed ERC-20 / WETH9 transfers from the simulation. */
-    transfers: Transfer[];
+    readonly transfers: readonly Transfer[];
     /** Shareable Tenderly URL. Present only when `shareable: true` and Tenderly ran (not fallback). */
-    tenderlyUrl?: string;
-    /** Raw Tenderly `asset_changes` payload. Opaque `unknown` — do not destructure without validation. */
-    assetChanges?: unknown;
+    readonly tenderlyUrl?: string;
 }
 /** Minimal structured logger the package calls for warnings and info. */
 export interface SimulationLogger {
@@ -117,15 +127,61 @@ export interface SimulateParams {
 }
 /**
  * Internal raw result from a simulation adapter before normalization.
- * Both Tenderly and simulateV1 produce this.
+ * `calls[i]` corresponds 1:1 with the i-th transaction passed to the
+ * backend.
  */
 export interface RawSimulationResult {
-    logs: RawLog[];
+    calls: RawCall[];
     tenderlyUrl?: string;
-    rawAssetChanges?: unknown;
 }
+/**
+ * Normalized EVM log emitted by a single simulated call. The shape is the
+ * common subset both backends (`eth_simulateV1` via viem and Tenderly REST)
+ * produce after schema validation. Returned indirectly via
+ * `SimulationCall.logs` and consumed by the SDK's transfer parser.
+ */
 export interface RawLog {
-    address: Address;
-    topics: Hex[];
-    data: Hex;
+    readonly address: Address;
+    readonly topics: readonly Hex[];
+    readonly data: Hex;
+}
+/**
+ * Internal mirror of `SimulationCall`, mutable during construction by the
+ * simulation backends.
+ *
+ * @internal
+ */
+export interface RawCall {
+    logs: RawLog[];
+    status: boolean;
+    returnData: Hex;
+    gasUsed: bigint;
+    /** Tenderly-only `asset_changes` payload. Absent on `eth_simulateV1`. */
+    assetChanges?: unknown;
+}
+/**
+ * Per-transaction normalized output from the simulation backend.
+ *
+ * `SimulationResult.calls[i]` corresponds 1:1 with
+ * `SimulationResult.simulationTxs[i]`. Use this to read raw logs, status,
+ * return data, gas used, and (Tenderly only) asset changes per transaction.
+ */
+export interface SimulationCall {
+    readonly logs: readonly RawLog[];
+    /**
+     * True iff the call succeeded. The bundle as a whole reverts via
+     * `SimulationRevertedError` before the result is returned, so on a
+     * successful `simulate()` every entry is `true` today. Field kept for
+     * forward-compatibility with backends that may surface per-call status.
+     */
+    readonly status: boolean;
+    /** Return data from the top-level call. */
+    readonly returnData: Hex;
+    /** Gas used by this call (root frame). */
+    readonly gasUsed: bigint;
+    /**
+     * Tenderly-only `asset_changes` payload for this tx. Opaque `unknown` —
+     * do not destructure without validation. Absent on `eth_simulateV1`.
+     */
+    readonly assetChanges?: unknown;
 }

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

@@ -1,7 +1,6 @@
 /**
- * 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 class SimulationPackageError extends Error {
     constructor(message, options) {

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

@@ -1,5 +1,5 @@
 // Public fns (via feature-folder barrels)
+// Errors (for instanceof checks by consumers)
+export { AddressScreeningError, BlacklistViolationError, ExternalServiceError, SimulationPackageError, SimulationRevertedError, SimulationValidationError, UnsupportedChainError, } from "./errors.js";
 export { screenAddresses } from "./screen-addresses/index.js";
 export { simulate } from "./simulate/index.js";
-// Errors (for instanceof checks by consumers)
-export { SimulationPackageError, SimulationRevertedError, BlacklistViolationError, AddressScreeningError, ExternalServiceError, SimulationValidationError, UnsupportedChainError, } from "./errors.js";