@morpho-org/evm-simulation 2.0.2 → 4.0.0

package/README.md

@@ -2,8 +2,8 @@
 
 ## Overview
 
-EVM transaction simulation engine for Morpho — bundle execution preview,
-transfer parsing, and compliance screening.
+EVM transaction simulation engine for Morpho — bundle execution preview
+and transfer parsing.
 
 ## Installation
 
@@ -22,38 +22,29 @@ Add to the consuming app's `package.json`:
 ```ts
 import {
   simulate,
-  screenAddresses,
   type SimulationConfig,
   SimulationRevertedError
 } from "@morpho-org/evm-simulation";
 
 const config: SimulationConfig = {
-  tenderlyRest: {
-    apiBaseUrl: "https://api.tenderly.co",
-    accessToken: process.env.TENDERLY_ACCESS_TOKEN!,
-    accountSlug: "my-account",
-    projectSlug: "my-project",
-    supportedChainIds: new Set([1]),
-  },
-  chains: new Map([[1, { simulateV1Url: process.env.MAINNET_RPC_URL }]]),
+  chains: new Map([
+    [
+      1,
+      {
+        tenderlyRpc: { rpcUrl: process.env.TENDERLY_RPC_URL! },
+        simulateV1Url: process.env.MAINNET_RPC_URL,
+      },
+    ],
+  ]),
   timeoutMs: 5000,
 };
 
 try {
-  // Pass { shareable: true } when you want a shareable Tenderly URL (user-facing preview).
-  // Omit it for server-side verification — the same function, same return shape.
-  const { transfers, simulationTxs, tenderlyUrl } = await simulate(
-    config,
-    {
-      chainId: 1,
-      transactions: [{ from: user, to: vault, data: encodedDeposit }],
-      authorizations: [{ type: "signature", token: usdc, spender: vault }],
-    },
-    { shareable: true }
-  );
-
-  // For server-side flows, pipe into screenAddresses:
-  await screenAddresses({ simulationTxs, transfers });
+  const { transfers, simulationTxs } = 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
@@ -62,20 +53,21 @@ try {
 }
 ```
 
+Each chain entry must declare at least one backend — `tenderlyRpc` (primary), `simulateV1Url` (fallback), or both. The type system enforces this.
+
 ### API surface
 
 All symbols below are re-exported from the package root.
 
-- `simulate(config, params, options?)` — run a bundle through the simulation pipeline. Pass `{ shareable: true }` for a shareable Tenderly URL; omit for server-side verification.
-- `screenAddresses({ simulationTxs, transfers, chainalysisApiKey? })` — static sanctioned-set + optional Chainalysis screening.
-- Config types: `SimulationConfig`, `TenderlyRestConfig`, `ChainSimulationConfig`, `SimulationLogger`.
+- `simulate(config, params)` — run a bundle through the simulation pipeline.
+- Config types: `SimulationConfig`, `TenderlyRpcConfig`, `ChainSimulationConfig`, `SimulationLogger`.
 - Data types: `SimulationTransaction`, `SimulationAuthorization`, `Transfer`, `SimulateParams`, `SimulationResult`.
-- Errors: `SimulationPackageError` (abstract base — `instanceof` it to catch any package error), `SimulationRevertedError`, `BlacklistViolationError`, `AddressScreeningError`, `ExternalServiceError`, `SimulationValidationError`, `UnsupportedChainError`.
+- Errors: `SimulationPackageError` (abstract base — `instanceof` it to catch any package error), `SimulationRevertedError`, `BlacklistViolationError`, `ExternalServiceError`, `SimulationValidationError`, `UnsupportedChainError`.
 
 ### Deeper docs
 
 See [`CLAUDE.md`](./CLAUDE.md) in this directory for the execution flow diagram,
-backend tradeoffs, authorizations model, screening design, error-handling table,
+backend tradeoffs, authorizations model, error-handling table,
 and recipes for adding a chain or a new backend.
 
 ## Development

package/lib/cjs/errors.d.ts

@@ -25,12 +25,6 @@ export declare class BlacklistViolationError extends SimulationPackageError {
     readonly code = "BLACKLIST_ERROR";
     constructor(message: string, assetChanges?: RetainedAsset[] | undefined);
 }
-/** Sanctioned or compromised address detected. Never bypassable. */
-export declare class AddressScreeningError extends SimulationPackageError {
-    readonly addresses: string[];
-    readonly code = "SCREENING_ERROR";
-    constructor(message: string, addresses: string[]);
-}
 /** Tenderly or RPC service is down. Bypassable — user can proceed. */
 export declare class ExternalServiceError extends SimulationPackageError {
     readonly code = "EXTERNAL_SERVICE_ERROR";

package/lib/cjs/errors.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.UnsupportedChainError = exports.SimulationValidationError = exports.ExternalServiceError = exports.AddressScreeningError = exports.BlacklistViolationError = exports.SimulationRevertedError = exports.SimulationPackageError = void 0;
+exports.UnsupportedChainError = exports.SimulationValidationError = exports.ExternalServiceError = exports.BlacklistViolationError = exports.SimulationRevertedError = exports.SimulationPackageError = void 0;
 /**
  * Base class for every error this package throws. Transport-agnostic — no HTTP status codes.
  * Consumers pattern-match with `instanceof` on the concrete subclass.
@@ -34,16 +34,6 @@ class BlacklistViolationError extends SimulationPackageError {
     }
 }
 exports.BlacklistViolationError = BlacklistViolationError;
-/** Sanctioned or compromised address detected. Never bypassable. */
-class AddressScreeningError extends SimulationPackageError {
-    addresses;
-    code = "SCREENING_ERROR";
-    constructor(message, addresses) {
-        super(message);
-        this.addresses = addresses;
-    }
-}
-exports.AddressScreeningError = AddressScreeningError;
 /** Tenderly or RPC service is down. Bypassable — user can proceed. */
 class ExternalServiceError extends SimulationPackageError {
     code = "EXTERNAL_SERVICE_ERROR";

package/lib/cjs/index.d.ts

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

package/lib/cjs/index.js

@@ -1,17 +1,14 @@
 "use strict";
 // Public fns (via feature-folder barrels)
 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;
+exports.simulate = exports.UnsupportedChainError = exports.SimulationValidationError = exports.SimulationRevertedError = exports.SimulationPackageError = exports.ExternalServiceError = exports.BlacklistViolationError = void 0;
 // Errors (for instanceof checks by consumers)
 var errors_js_1 = require("./errors.js");
-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; } });
+var index_js_1 = require("./simulate/index.js");
+Object.defineProperty(exports, "simulate", { enumerable: true, get: function () { return index_js_1.simulate; } });

package/lib/cjs/simulate/asset-changes.d.ts

@@ -0,0 +1,19 @@
+import { type Address } from "viem";
+import type { AccountAssetChanges } from "../types.js";
+/** A single signed contribution to one account's balance for one token. */
+export interface AssetChangeEntry {
+    account: Address;
+    token: Address;
+    diff: bigint;
+    symbol?: string;
+    decimals?: number;
+}
+/**
+ * Net signed per-(account, token) contributions into balance changes grouped by
+ * account. Accounts and their `changes` are sorted by address for deterministic
+ * output; zero-net tokens and accounts are dropped.
+ *
+ * @param entries - Signed contributions; `diff` is added per (account, token).
+ * @returns One {@link AccountAssetChanges} per account with a non-zero change.
+ */
+export declare function groupAssetChanges(entries: AssetChangeEntry[]): AccountAssetChanges[];

package/lib/cjs/simulate/asset-changes.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.groupAssetChanges = groupAssetChanges;
+const viem_1 = require("viem");
+// Locale-independent byte-order compare on lowercased hex, matching `sortTransfers`.
+const compareAddress = (a, b) => {
+    const al = a.toLowerCase();
+    const bl = b.toLowerCase();
+    return al < bl ? -1 : al > bl ? 1 : 0;
+};
+/**
+ * Net signed per-(account, token) contributions into balance changes grouped by
+ * account. Accounts and their `changes` are sorted by address for deterministic
+ * output; zero-net tokens and accounts are dropped.
+ *
+ * @param entries - Signed contributions; `diff` is added per (account, token).
+ * @returns One {@link AccountAssetChanges} per account with a non-zero change.
+ */
+function groupAssetChanges(entries) {
+    const byAccount = new Map();
+    for (const entry of entries) {
+        if (entry.diff === 0n)
+            continue;
+        const account = (0, viem_1.getAddress)(entry.account);
+        // `token` is normalized by callers (checksummed contract or `ethAddress`).
+        const token = entry.token;
+        let tokens = byAccount.get(account);
+        if (!tokens)
+            byAccount.set(account, (tokens = new Map()));
+        const prev = tokens.get(token);
+        tokens.set(token, {
+            token,
+            symbol: prev?.symbol ?? entry.symbol,
+            decimals: prev?.decimals ?? entry.decimals,
+            diff: (prev?.diff ?? 0n) + entry.diff,
+        });
+    }
+    return [...byAccount]
+        .map(([account, tokens]) => ({
+        account,
+        changes: [...tokens.values()]
+            .filter((c) => c.diff !== 0n)
+            .sort((x, y) => compareAddress(x.token, y.token)),
+    }))
+        .filter((a) => a.changes.length > 0)
+        .sort((a, b) => compareAddress(a.account, b.account));
+}

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

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

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

@@ -3,11 +3,22 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.simulateV1 = simulateV1;
 const viem_1 = require("viem");
 const errors_js_1 = require("../../errors.js");
+const asset_changes_js_1 = require("../asset-changes.js");
+const index_js_1 = require("../parsing/index.js");
 /**
  * Simulate transactions using eth_simulateV1 (viem simulateCalls).
  *
  * Uses stateOverride to set the user's ETH balance high enough to avoid
  * false "insufficient balance for gas" reverts.
+ *
+ * Derives `assetChanges` (net per-token deltas grouped by account) from the
+ * emitted transfer logs, plus native ETH from each transaction's top-level
+ * `value` (payer debited, recipient credited, under viem's `ethAddress`).
+ *
+ * Coverage on this path is therefore narrower than the Tenderly backend:
+ * native ETH moved through internal calls (e.g. a `WETH.withdraw` refund, a
+ * swap that pays out ETH) emits no log and is not reflected in `value`, so it
+ * is not captured. For full native-ETH accounting use Tenderly.
  */
 async function simulateV1(params) {
     const { rpcUrl, transactions, blockNumber, signal } = params;
@@ -64,7 +75,13 @@ async function simulateV1(params) {
             returnData: r.data ?? "0x",
             gasUsed: r.gasUsed,
         }));
-        return { calls: rawCalls };
+        return {
+            calls: rawCalls,
+            assetChanges: toAssetChanges({
+                transfers: (0, index_js_1.parseTransfers)(rawCalls),
+                transactions,
+            }),
+        };
     }
     catch (error) {
         if (error instanceof errors_js_1.SimulationRevertedError)
@@ -74,3 +91,24 @@ async function simulateV1(params) {
         throw new errors_js_1.ExternalServiceError(`eth_simulateV1 error: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
     }
 }
+/**
+ * Reduce parsed transfer logs and top-level transaction values to net per-token
+ * balance changes grouped by account. Native ETH is taken from the top-level
+ * `value`s (payer debited, recipient credited — internal moves are not logged,
+ * see `simulateV1` for the coverage caveat).
+ */
+function toAssetChanges(params) {
+    const { transfers, transactions } = params;
+    const entries = [];
+    for (const tx of transactions) {
+        if (!tx.value)
+            continue;
+        entries.push({ account: tx.from, token: viem_1.ethAddress, diff: -tx.value });
+        entries.push({ account: tx.to, token: viem_1.ethAddress, diff: tx.value });
+    }
+    for (const { token, from, to, amount } of transfers) {
+        entries.push({ account: to, token, diff: amount });
+        entries.push({ account: from, token, diff: -amount });
+    }
+    return (0, asset_changes_js_1.groupAssetChanges)(entries);
+}

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

@@ -1,2 +1,2 @@
 export { simulateV1 } from "./eth-simulate-v1.js";
-export { simulateTenderlyRest } from "./tenderly-rest.js";
+export { simulateTenderlyRpc } from "./tenderly-rpc.js";

package/lib/cjs/simulate/backends/index.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.simulateTenderlyRest = exports.simulateV1 = void 0;
+exports.simulateTenderlyRpc = exports.simulateV1 = void 0;
 var eth_simulate_v1_js_1 = require("./eth-simulate-v1.js");
 Object.defineProperty(exports, "simulateV1", { enumerable: true, get: function () { return eth_simulate_v1_js_1.simulateV1; } });
-var tenderly_rest_js_1 = require("./tenderly-rest.js");
-Object.defineProperty(exports, "simulateTenderlyRest", { enumerable: true, get: function () { return tenderly_rest_js_1.simulateTenderlyRest; } });
+var tenderly_rpc_js_1 = require("./tenderly-rpc.js");
+Object.defineProperty(exports, "simulateTenderlyRpc", { enumerable: true, get: function () { return tenderly_rpc_js_1.simulateTenderlyRpc; } });

package/lib/cjs/simulate/backends/tenderly-rpc.d.ts

@@ -0,0 +1,23 @@
+import { type BlockTag } from "viem";
+import type { RawSimulationResult, SimulationTransaction, TenderlyRpcConfig } from "../../types.js";
+/**
+ * Simulate one or more transactions via Tenderly's Node Web3 Gateway.
+ * Dispatches to `tenderly_simulateTransaction` for a single call and
+ * `tenderly_simulateBundle` for a multi-call bundle.
+ *
+ * @param params.config - Tenderly RPC config (URL with access key embedded).
+ * @param params.transactions - Bundle to simulate, in execution order.
+ * @param params.blockNumber - Optional pinned block number or `BlockTag`. Defaults to `latest`.
+ * @param params.signal - Optional `AbortSignal` for cancellation / timeout.
+ * @returns A {@link RawSimulationResult} with one `RawCall` per input transaction.
+ * @throws {SimulationValidationError} when `transactions` is empty.
+ * @throws {SimulationRevertedError} when any simulated tx reports `status: false`.
+ * @throws {ExternalServiceError} on non-2xx response, JSON-RPC envelope error,
+ *   schema-validation failure, or fetch-layer failure.
+ */
+export declare function simulateTenderlyRpc(params: {
+    config: TenderlyRpcConfig;
+    transactions: SimulationTransaction[];
+    blockNumber?: bigint | BlockTag;
+    signal?: AbortSignal;
+}): Promise<RawSimulationResult>;

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

@@ -0,0 +1,230 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.simulateTenderlyRpc = simulateTenderlyRpc;
+const viem_1 = require("viem");
+const zod_1 = require("zod");
+const errors_js_1 = require("../../errors.js");
+const asset_changes_js_1 = require("../asset-changes.js");
+const addressSchema = zod_1.z.custom((val) => typeof val === "string" && (0, viem_1.isAddress)(val));
+const hexSchema = zod_1.z.custom((val) => typeof val === "string" && (0, viem_1.isHex)(val));
+const traceFrameSchema = zod_1.z
+    .object({
+    output: hexSchema.optional(),
+    error: zod_1.z.string().optional(),
+    errorReason: zod_1.z.string().optional(),
+})
+    .passthrough();
+const logSchema = zod_1.z
+    .object({
+    raw: zod_1.z
+        .object({
+        address: addressSchema,
+        topics: zod_1.z.array(hexSchema).optional(),
+        data: hexSchema.optional(),
+    })
+        .passthrough()
+        .optional(),
+})
+    .passthrough();
+const assetChangeSchema = zod_1.z
+    .object({
+    assetInfo: zod_1.z
+        .object({
+        contractAddress: addressSchema.optional(),
+        symbol: zod_1.z.string().optional(),
+        decimals: zod_1.z.number().optional(),
+    })
+        .passthrough(),
+    from: addressSchema.optional(),
+    to: addressSchema.optional(),
+    rawAmount: hexSchema,
+})
+    .passthrough();
+const simResultSchema = zod_1.z
+    .object({
+    status: zod_1.z.boolean(),
+    gasUsed: hexSchema,
+    logs: zod_1.z.array(logSchema).optional(),
+    trace: zod_1.z.array(traceFrameSchema).optional(),
+    assetChanges: zod_1.z.array(assetChangeSchema).optional(),
+    error: zod_1.z.string().optional(),
+    errorMessage: zod_1.z.string().optional(),
+})
+    .passthrough();
+const rpcErrorSchema = zod_1.z
+    .object({
+    code: zod_1.z.number().optional(),
+    message: zod_1.z.string(),
+    data: zod_1.z.unknown().optional(),
+})
+    .passthrough();
+function rpcEnvelope(result) {
+    return zod_1.z
+        .object({ result: result.optional(), error: rpcErrorSchema.optional() })
+        .passthrough();
+}
+const singleEnvelope = rpcEnvelope(simResultSchema);
+const bundleEnvelope = rpcEnvelope(zod_1.z.array(simResultSchema).min(1));
+/**
+ * Simulate one or more transactions via Tenderly's Node Web3 Gateway.
+ * Dispatches to `tenderly_simulateTransaction` for a single call and
+ * `tenderly_simulateBundle` for a multi-call bundle.
+ *
+ * @param params.config - Tenderly RPC config (URL with access key embedded).
+ * @param params.transactions - Bundle to simulate, in execution order.
+ * @param params.blockNumber - Optional pinned block number or `BlockTag`. Defaults to `latest`.
+ * @param params.signal - Optional `AbortSignal` for cancellation / timeout.
+ * @returns A {@link RawSimulationResult} with one `RawCall` per input transaction.
+ * @throws {SimulationValidationError} when `transactions` is empty.
+ * @throws {SimulationRevertedError} when any simulated tx reports `status: false`.
+ * @throws {ExternalServiceError} on non-2xx response, JSON-RPC envelope error,
+ *   schema-validation failure, or fetch-layer failure.
+ */
+async function simulateTenderlyRpc(params) {
+    const { config, transactions, blockNumber, signal } = params;
+    const firstTx = transactions[0];
+    if (!firstTx) {
+        throw new errors_js_1.SimulationValidationError("At least one transaction is required", []);
+    }
+    const block = encodeBlock(blockNumber);
+    // Inflate sender ETH balance to avoid false "insufficient funds for gas"
+    // reverts on wallets low on native gas token — mirrors simulateV1.
+    const stateOverrides = buildStateOverrides(firstTx.from);
+    try {
+        if (transactions.length === 1) {
+            const json = await rpcRequest({
+                rpcUrl: config.rpcUrl,
+                method: "tenderly_simulateTransaction",
+                params: [buildCall(firstTx), block, stateOverrides],
+                signal,
+            });
+            const result = unwrapResult(singleEnvelope.parse(json));
+            return {
+                calls: [toRawCall(result)],
+                assetChanges: toAssetChanges([result]),
+            };
+        }
+        const json = await rpcRequest({
+            rpcUrl: config.rpcUrl,
+            method: "tenderly_simulateBundle",
+            params: [transactions.map(buildCall), block, stateOverrides],
+            signal,
+        });
+        const results = unwrapResult(bundleEnvelope.parse(json));
+        return {
+            calls: results.map(toRawCall),
+            assetChanges: toAssetChanges(results),
+        };
+    }
+    catch (error) {
+        if (error instanceof errors_js_1.SimulationRevertedError)
+            throw error;
+        if (error instanceof errors_js_1.ExternalServiceError)
+            throw error;
+        throw new errors_js_1.ExternalServiceError(`Tenderly RPC error: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+    }
+}
+async function rpcRequest(params) {
+    const { rpcUrl, method, params: rpcParams, signal } = params;
+    const response = await fetch(rpcUrl, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ jsonrpc: "2.0", id: 1, method, params: rpcParams }),
+        signal,
+    });
+    if (!response.ok) {
+        throw new errors_js_1.ExternalServiceError(`Tenderly RPC returned ${response.status}: ${response.statusText}`);
+    }
+    return await response.json();
+}
+function unwrapResult(envelope) {
+    if (envelope.error) {
+        throw new errors_js_1.ExternalServiceError(`Tenderly RPC error: ${envelope.error.message}`);
+    }
+    if (envelope.result === undefined) {
+        throw new errors_js_1.ExternalServiceError("Tenderly RPC returned no result");
+    }
+    return envelope.result;
+}
+function buildCall(tx) {
+    return {
+        from: tx.from,
+        to: tx.to,
+        input: tx.data,
+        data: tx.data,
+        value: (0, viem_1.numberToHex)(tx.value ?? 0n),
+    };
+}
+function buildStateOverrides(sender) {
+    return { [sender]: { balance: (0, viem_1.numberToHex)(viem_1.maxUint256) } };
+}
+function encodeBlock(blockNumber) {
+    if (blockNumber === undefined)
+        return "latest";
+    return typeof blockNumber === "bigint"
+        ? (0, viem_1.numberToHex)(blockNumber)
+        : blockNumber;
+}
+function toRawCall(data) {
+    if (data.status !== true) {
+        // Tenderly RPC surfaces the revert reason on the trace frame; the
+        // top-level fields are checked as a defensive fallback.
+        const traceError = data.trace?.find((f) => f.errorReason || f.error);
+        const message = traceError?.errorReason ||
+            traceError?.error ||
+            data.errorMessage ||
+            data.error ||
+            "Transaction simulation reverted";
+        throw new errors_js_1.SimulationRevertedError(message, data);
+    }
+    const logs = [];
+    for (const log of data.logs ?? []) {
+        if (log.raw) {
+            logs.push({
+                address: log.raw.address,
+                topics: log.raw.topics ?? [],
+                data: log.raw.data ?? "0x",
+            });
+        }
+    }
+    return {
+        logs,
+        status: true,
+        returnData: data.trace?.[0]?.output ?? "0x",
+        gasUsed: BigInt(data.gasUsed),
+    };
+}
+/**
+ * Reduce Tenderly's per-transfer asset changes to net per-token balance changes
+ * grouped by account. Both endpoints of each transfer are accounted (sender,
+ * counterparties, and the zero address for mints/burns).
+ */
+function toAssetChanges(results) {
+    const entries = [];
+    for (const result of results) {
+        for (const change of result.assetChanges ?? []) {
+            const amount = BigInt(change.rawAmount);
+            const token = change.assetInfo.contractAddress
+                ? (0, viem_1.getAddress)(change.assetInfo.contractAddress)
+                : viem_1.ethAddress;
+            const { symbol, decimals } = change.assetInfo;
+            if (change.to)
+                entries.push({
+                    account: change.to,
+                    token,
+                    diff: amount,
+                    symbol,
+                    decimals,
+                });
+            if (change.from)
+                entries.push({
+                    account: change.from,
+                    token,
+                    diff: -amount,
+                    symbol,
+                    decimals,
+                });
+        }
+    }
+    return (0, asset_changes_js_1.groupAssetChanges)(entries);
+}

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

@@ -145,7 +145,9 @@ function parseTransfers(calls, logger) {
             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));
+                warnMalformed(logger, log, 
+                /* v8 ignore next: parser paths throw Error instances for valid RawLog shapes. */
+                error instanceof Error ? error.message : String(error));
             }
         }
     }

package/lib/cjs/simulate/pipeline/execute-simulation.d.ts

@@ -5,21 +5,17 @@ import type { RawSimulationResult, SimulationConfig, SimulationTransaction } fro
  *
  * Dispatches the transaction bundle to the available backend with a shared timeout
  * budget:
- * - If Tenderly is configured for the chain, it gets `TENDERLY_BUDGET_RATIO` (60%) of
- *   the timeout. On `ExternalServiceError`, falls back to `eth_simulateV1` with
- *   `max(remaining, FALLBACK_MIN_BUDGET_MS)` so the fallback still has a viable
- *   window when Tenderly eats its full slice. `SimulationRevertedError` (contract
- *   revert) propagates immediately without retry — a revert is a property of the
- *   bundle, not the backend.
+ * - If a Tenderly RPC URL is configured for the chain, it gets
+ *   `TENDERLY_BUDGET_RATIO` (60%) of the timeout. On `ExternalServiceError`,
+ *   falls back to `eth_simulateV1` with `max(remaining, FALLBACK_MIN_BUDGET_MS)`
+ *   so the fallback still has a viable window when Tenderly eats its full slice.
+ *   `SimulationRevertedError` (contract revert) propagates immediately without
+ *   retry — a revert is a property of the bundle, not the backend.
  * - If only `eth_simulateV1` is configured, it gets the full timeout.
- *
- * `shareable` is Tenderly-only: when true, the backend persists the simulation and
- * returns a shareable URL. `eth_simulateV1` ignores it (no persistence concept).
  */
 export declare function executeSimulation(params: {
     config: SimulationConfig;
     chainId: number;
     transactions: SimulationTransaction[];
     blockNumber?: bigint | BlockTag;
-    shareable: boolean;
 }): Promise<RawSimulationResult>;