@morpho-org/evm-simulation 1.0.0 → 2.0.1

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

@@ -16,30 +16,46 @@ const chainalysisEntitySchema = 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,
+ * });
+ * ```
  */
 export async function screenAddresses(params) {
     const { simulationTxs, transfers, chainalysisApiKey, signal, logger } = params;
@@ -100,7 +116,10 @@ export 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/esm/simulate/backends/eth-simulate-v1.js

@@ -1,4 +1,4 @@
-import { http, createPublicClient, getAddress, maxUint256, } from "viem";
+import { createPublicClient, getAddress, http, maxUint256, } from "viem";
 import { ExternalServiceError, SimulationRevertedError, SimulationValidationError, } from "../../errors.js";
 /**
  * Simulate transactions using eth_simulateV1 (viem simulateCalls).
@@ -51,17 +51,17 @@ export async function simulateV1(params) {
         if (failedResult) {
             throw new 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 SimulationRevertedError)

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

@@ -19,6 +19,7 @@ const tenderlyRawResponseSchema = z
     transaction: z
         .object({
         error_message: z.string().optional(),
+        gas_used: z.number(),
         transaction_info: z
             .object({
             logs: z
@@ -36,6 +37,11 @@ const tenderlyRawResponseSchema = z
                 .passthrough())
                 .optional(),
             asset_changes: z.unknown().optional(),
+            call_trace: z
+                .object({
+                output: hexSchema,
+            })
+                .passthrough(),
         })
             .passthrough(),
     })
@@ -98,6 +104,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),
@@ -129,19 +136,16 @@ async function simulateSingle(params) {
         throw new 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;
@@ -162,39 +166,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
@@ -233,7 +238,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 ||
@@ -255,12 +266,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/esm/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[];