@morpho-org/evm-simulation 2.0.2 → 4.0.0

package/lib/cjs/simulate/pipeline/execute-simulation.js

@@ -23,33 +23,27 @@ const FALLBACK_MIN_BUDGET_MS = 1500;
  *
  * 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).
  */
 async function executeSimulation(params) {
-    const { config, chainId, transactions, blockNumber, shareable } = params;
+    const { config, chainId, transactions, blockNumber } = params;
     const chain = (0, resolve_chain_js_1.resolveChain)(config, chainId);
     const timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
     const deadline = Date.now() + timeoutMs;
-    if (chain.tenderlySupported && config.tenderlyRest) {
+    if (chain.tenderlyRpc) {
         const tenderlyTimeout = Math.floor(timeoutMs * TENDERLY_BUDGET_RATIO);
         try {
-            return await (0, index_js_1.simulateTenderlyRest)({
-                config: config.tenderlyRest,
-                chainId,
+            return await (0, index_js_1.simulateTenderlyRpc)({
+                config: chain.tenderlyRpc,
                 transactions,
                 blockNumber,
-                shareable,
                 signal: AbortSignal.timeout(tenderlyTimeout),
-                logger: config.logger,
             });
         }
         catch (error) {
@@ -62,8 +56,6 @@ async function executeSimulation(params) {
             });
             if (!chain.simulateV1Url)
                 throw error;
-            // Give the fallback a reasonable minimum even if Tenderly consumed the
-            // whole budget — otherwise slow-Tenderly == total outage.
             const fallbackBudget = Math.max(deadline - Date.now(), FALLBACK_MIN_BUDGET_MS);
             return await (0, index_js_1.simulateV1)({
                 rpcUrl: chain.simulateV1Url,
@@ -74,6 +66,7 @@ async function executeSimulation(params) {
             });
         }
     }
+    /* v8 ignore next: resolveChain rejects this state before executeSimulation reaches the fallback path. */
     if (!chain.simulateV1Url) {
         throw new errors_js_1.UnsupportedChainError(chainId);
     }

package/lib/cjs/simulate/pipeline/resolve-chain.d.ts

@@ -1,14 +1,15 @@
-import type { SimulationConfig } from "../../types.js";
+import type { SimulationConfig, TenderlyRpcConfig } from "../../types.js";
 interface ChainCapability {
-    tenderlySupported: boolean;
+    tenderlyRpc?: TenderlyRpcConfig;
     simulateV1Url?: string;
 }
 /**
  * Stage 2 of the simulate() pipeline.
  *
- * Determines which backend(s) are available for a chainId. Throws
- * `UnsupportedChainError` when neither Tenderly nor `eth_simulateV1` is reachable
- * for the requested chain.
+ * Looks up the per-chain `ChainSimulationConfig` and exposes whichever
+ * backends were configured. Throws `UnsupportedChainError` when the chain is
+ * absent from the map or has neither backend wired (defensive — the type
+ * already enforces at least one at construction).
  */
 export declare function resolveChain(config: SimulationConfig, chainId: number): ChainCapability;
 export {};

package/lib/cjs/simulate/pipeline/resolve-chain.js

@@ -5,15 +5,18 @@ const errors_js_1 = require("../../errors.js");
 /**
  * Stage 2 of the simulate() pipeline.
  *
- * Determines which backend(s) are available for a chainId. Throws
- * `UnsupportedChainError` when neither Tenderly nor `eth_simulateV1` is reachable
- * for the requested chain.
+ * Looks up the per-chain `ChainSimulationConfig` and exposes whichever
+ * backends were configured. Throws `UnsupportedChainError` when the chain is
+ * absent from the map or has neither backend wired (defensive — the type
+ * already enforces at least one at construction).
  */
 function resolveChain(config, chainId) {
-    const tenderlySupported = config.tenderlyRest?.supportedChainIds.has(chainId) ?? false;
-    const simulateV1Url = config.chains.get(chainId)?.simulateV1Url;
-    if (!tenderlySupported && !simulateV1Url) {
+    const entry = config.chains.get(chainId);
+    if (!entry || (!entry.tenderlyRpc && !entry.simulateV1Url)) {
         throw new errors_js_1.UnsupportedChainError(chainId);
     }
-    return { tenderlySupported, simulateV1Url };
+    return {
+        tenderlyRpc: entry.tenderlyRpc,
+        simulateV1Url: entry.simulateV1Url,
+    };
 }

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

@@ -3,20 +3,21 @@ import type { SimulateParams, SimulationConfig, SimulationResult } from "../type
  * Simulate a bundle of EVM transactions.
  *
  * Validates input → resolves authorizations into prepended approve txs → runs the bundle
- * through Tenderly REST (primary) or `eth_simulateV1` (fallback) with a shared timeout
+ * through Tenderly RPC (primary) or `eth_simulateV1` (fallback) with a shared timeout
  * 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` → user-facing preview / server-side verification.
+ * - `simulationTxs` + `transfers` → server-side verification before broadcast.
+ * - `calls[i]` → per-tx raw backend output (`logs`, `status`, `returnData`, `gasUsed`).
+ *   Aligned 1:1 with `simulationTxs[i]`.
+ * - `assetChanges` → net per-asset balance changes grouped by account (sender and
+ *   counterparties) over the whole bundle, normalized to the same shape across backends.
  * - `transfers[k].txIdx` → index into `simulationTxs` of the tx that emitted the
  *   underlying log; consumers map back via `simulationTxs[transfer.txIdx]`.
  *
- * @param config - Backend configuration: Tenderly credentials, per-chain RPC URLs, optional
- *   logger, and the overall timeout budget.
+ * @param config - Backend configuration: per-chain Tenderly RPC and/or `eth_simulateV1`
+ *   URL, 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
@@ -24,10 +25,6 @@ import type { SimulateParams, SimulationConfig, SimulationResult } from "../type
  * @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.
@@ -39,14 +36,21 @@ import type { SimulateParams, SimulationConfig, SimulationResult } from "../type
  *   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`.
+ *   `calls` (aligned 1:1 with `simulationTxs`), parsed `transfers` (each stamped
+ *   with `txIdx`), and per-account net `assetChanges`.
  * @example
  * ```ts
  * import { simulate } from "@morpho-org/evm-simulation";
  *
  * const result = await simulate(
- *   { chains: new Map([[1, { simulateV1Url: rpcUrl }]]) },
+ *   {
+ *     chains: new Map([
+ *       [1, {
+ *         tenderlyRpc: { rpcUrl: process.env.TENDERLY_RPC_URL! },
+ *         simulateV1Url: process.env.MAINNET_RPC_URL,
+ *       }],
+ *     ]),
+ *   },
  *   {
  *     chainId: 1,
  *     transactions: [{ from: user, to: vaultAddress, data: encodedCalldata, value: 0n }],
@@ -55,11 +59,4 @@ import type { SimulateParams, SimulationConfig, SimulationResult } from "../type
  * // result satisfies SimulationResult
  * ```
  */
-export declare function simulate(config: SimulationConfig, params: SimulateParams, options?: {
-    /**
-     * When true, persist the simulation in Tenderly and return a shareable
-     * `tenderlyUrl` in the result. Only honored when the Tenderly backend runs
-     * (not the `eth_simulateV1` fallback). Defaults to `false`.
-     */
-    shareable?: boolean;
-}): Promise<SimulationResult>;
+export declare function simulate(config: SimulationConfig, params: SimulateParams): Promise<SimulationResult>;

package/lib/cjs/simulate/simulate.js

@@ -8,20 +8,21 @@ const index_js_2 = require("./pipeline/index.js");
  * Simulate a bundle of EVM transactions.
  *
  * Validates input → resolves authorizations into prepended approve txs → runs the bundle
- * through Tenderly REST (primary) or `eth_simulateV1` (fallback) with a shared timeout
+ * through Tenderly RPC (primary) or `eth_simulateV1` (fallback) with a shared timeout
  * 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` → user-facing preview / server-side verification.
+ * - `simulationTxs` + `transfers` → server-side verification before broadcast.
+ * - `calls[i]` → per-tx raw backend output (`logs`, `status`, `returnData`, `gasUsed`).
+ *   Aligned 1:1 with `simulationTxs[i]`.
+ * - `assetChanges` → net per-asset balance changes grouped by account (sender and
+ *   counterparties) over the whole bundle, normalized to the same shape across backends.
  * - `transfers[k].txIdx` → index into `simulationTxs` of the tx that emitted the
  *   underlying log; consumers map back via `simulationTxs[transfer.txIdx]`.
  *
- * @param config - Backend configuration: Tenderly credentials, per-chain RPC URLs, optional
- *   logger, and the overall timeout budget.
+ * @param config - Backend configuration: per-chain Tenderly RPC and/or `eth_simulateV1`
+ *   URL, 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
@@ -29,10 +30,6 @@ const index_js_2 = require("./pipeline/index.js");
  * @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.
@@ -44,14 +41,21 @@ const index_js_2 = require("./pipeline/index.js");
  *   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`.
+ *   `calls` (aligned 1:1 with `simulationTxs`), parsed `transfers` (each stamped
+ *   with `txIdx`), and per-account net `assetChanges`.
  * @example
  * ```ts
  * import { simulate } from "@morpho-org/evm-simulation";
  *
  * const result = await simulate(
- *   { chains: new Map([[1, { simulateV1Url: rpcUrl }]]) },
+ *   {
+ *     chains: new Map([
+ *       [1, {
+ *         tenderlyRpc: { rpcUrl: process.env.TENDERLY_RPC_URL! },
+ *         simulateV1Url: process.env.MAINNET_RPC_URL,
+ *       }],
+ *     ]),
+ *   },
  *   {
  *     chainId: 1,
  *     transactions: [{ from: user, to: vaultAddress, data: encodedCalldata, value: 0n }],
@@ -60,9 +64,7 @@ const index_js_2 = require("./pipeline/index.js");
  * // result satisfies SimulationResult
  * ```
  */
-// biome-ignore lint/complexity/useMaxParams: TODO refactor to ≤2 params
-async function simulate(config, params, options = {}) {
-    const { shareable = false } = options;
+async function simulate(config, params) {
     (0, index_js_2.validateInput)(params);
     const simulationTxs = (0, index_js_2.buildSimulationTxs)(params);
     const result = await (0, index_js_2.executeSimulation)({
@@ -70,7 +72,6 @@ async function simulate(config, params, options = {}) {
         chainId: params.chainId,
         transactions: simulationTxs,
         blockNumber: params.blockNumber,
-        shareable,
     });
     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`);
@@ -85,6 +86,6 @@ async function simulate(config, params, options = {}) {
         simulationTxs,
         calls: result.calls,
         transfers,
-        tenderlyUrl: result.tenderlyUrl,
+        assetChanges: result.assetChanges,
     };
 }

package/lib/cjs/types.d.ts

@@ -1,36 +1,34 @@
 import type { Address, BlockTag, Hex } from "viem";
 /**
- * Credentials and routing for the Tenderly REST simulation backend.
- * Omit from `SimulationConfig.tenderlyRest` to disable the Tenderly path entirely.
+ * Credentials for the Tenderly Node Web3 Gateway. The `rpcUrl` is the
+ * chain-specific gateway URL with the access key embedded in the path,
+ * e.g. `https://mainnet.gateway.tenderly.co/{ACCESS_KEY}`.
  */
-export interface TenderlyRestConfig {
-    /** e.g. "https://api.tenderly.co" */
-    apiBaseUrl: string;
-    accessToken: string;
-    accountSlug: string;
-    projectSlug: string;
-    /** Chain IDs that Tenderly supports for simulation */
-    supportedChainIds: Set<number>;
+export interface TenderlyRpcConfig {
+    rpcUrl: string;
 }
 /**
- * Per-chain capabilities. Stored as a `Map` value in
- * `SimulationConfig.chains`, keyed by chain ID.
+ * Per-chain backend capabilities. Exactly one configuration shape per chain;
+ * the discriminated union enforces that **at least one** of `tenderlyRpc`
+ * (primary) or `simulateV1Url` (fallback) is supplied.
  */
-export interface ChainSimulationConfig {
-    /** JSON-RPC URL supporting `eth_simulateV1`. undefined = not available for this chain. */
+export type ChainSimulationConfig = {
+    /** Tenderly RPC config — `tenderly_simulateTransaction` / `tenderly_simulateBundle`. */
+    tenderlyRpc: TenderlyRpcConfig;
+    /** JSON-RPC URL supporting `eth_simulateV1`. Optional when Tenderly is set. */
     simulateV1Url?: string;
-}
+} | {
+    tenderlyRpc?: TenderlyRpcConfig;
+    simulateV1Url: string;
+};
 /**
  * Top-level configuration for `simulate`.
  *
- * At least one backend must be reachable for a given chainId — either Tenderly
- * (via `tenderlyRest` with that chainId in `TenderlyRestConfig.supportedChainIds`)
- * or `ChainSimulationConfig.simulateV1Url` in the `chains` map. Otherwise the
- * orchestrator throws `UnsupportedChainError`.
+ * Every chain entry must declare at least one backend (Tenderly RPC primary,
+ * `eth_simulateV1` fallback, or both). Calling `simulate` for a `chainId`
+ * missing from `chains` throws `UnsupportedChainError`.
  */
 export interface SimulationConfig {
-    /** Tenderly REST API config. undefined = Tenderly not available. */
-    tenderlyRest?: TenderlyRestConfig;
     /** Per-chain simulation capabilities. */
     chains: Map<number, ChainSimulationConfig>;
     logger?: SimulationLogger;
@@ -66,6 +64,33 @@ export type SimulationAuthorization = {
     /** Defaults to maxUint256. Caller can set explicit amount for tokens that don't support max approval. */
     amount?: bigint;
 };
+/**
+ * Net balance change for a single asset (one token) within an account's entry.
+ * Native ETH uses viem's `ethAddress` sentinel as `token`. `symbol`/`decimals`
+ * are best-effort and may be absent, notably on the `eth_simulateV1` fallback.
+ */
+export interface AssetChange {
+    readonly token: Address;
+    readonly symbol?: string;
+    readonly decimals?: number;
+    /** Signed net change of the account's balance, in raw token units. */
+    readonly diff: bigint;
+}
+/**
+ * Net per-token balance changes for one account over the whole bundle. Returned
+ * for every account that nets a non-zero change, the sender and counterparties
+ * alike (the zero address is kept for mints/burns). Accounts and their `changes`
+ * are sorted by address for deterministic, cross-backend output.
+ *
+ * Native-ETH coverage differs by backend: Tenderly reports the full net ETH
+ * delta (including ETH moved via internal calls), while the `eth_simulateV1`
+ * fallback derives native ETH only from the top-level transaction `value`s —
+ * ETH moved internally (e.g. a `WETH.withdraw` refund) is not captured there.
+ */
+export interface AccountAssetChanges {
+    readonly account: Address;
+    readonly changes: readonly AssetChange[];
+}
 /**
  * A parsed ERC20 / WETH9 transfer extracted from simulation logs. Returned in
  * `SimulationResult.transfers`.
@@ -89,25 +114,25 @@ export interface Transfer {
  * - `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.
+ *   status, returnData/gasUsed.
+ * - `assetChanges` is the net per-asset balance change over the whole bundle,
+ *   grouped by account (sender and counterparties), normalized to the same
+ *   shape across backends — see `AccountAssetChanges`.
  * - `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). */
     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.
+     * `simulationTxs[i]`. Use this to read raw logs, status, return data, gas used.
      */
     readonly calls: readonly SimulationCall[];
     /** Parsed ERC-20 / WETH9 transfers from the simulation. */
     readonly transfers: readonly Transfer[];
-    /** Shareable Tenderly URL. Present only when `shareable: true` and Tenderly ran (not fallback). */
-    readonly tenderlyUrl?: string;
+    /** Net per-asset balance changes, grouped by account, over the whole bundle. */
+    readonly assetChanges: readonly AccountAssetChanges[];
 }
 /** Minimal structured logger the package calls for warnings and info. */
 export interface SimulationLogger {
@@ -128,15 +153,15 @@ export interface SimulateParams {
 /**
  * Internal raw result from a simulation adapter before normalization.
  * `calls[i]` corresponds 1:1 with the i-th transaction passed to the
- * backend.
+ * backend; `assetChanges` is the bundle-level aggregate grouped by account.
  */
 export interface RawSimulationResult {
     calls: RawCall[];
-    tenderlyUrl?: string;
+    assetChanges: AccountAssetChanges[];
 }
 /**
  * Normalized EVM log emitted by a single simulated call. The shape is the
- * common subset both backends (`eth_simulateV1` via viem and Tenderly REST)
+ * common subset both backends (`eth_simulateV1` via viem and Tenderly RPC)
  * produce after schema validation. Returned indirectly via
  * `SimulationCall.logs` and consumed by the SDK's transfer parser.
  */
@@ -156,15 +181,14 @@ export interface RawCall {
     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.
+ * return data, and gas used. Net asset changes are reported at the bundle
+ * level — see `SimulationResult.assetChanges`.
  */
 export interface SimulationCall {
     readonly logs: readonly RawLog[];
@@ -179,9 +203,4 @@ export interface SimulationCall {
     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

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

@@ -28,15 +28,6 @@ export class BlacklistViolationError extends SimulationPackageError {
         this.assetChanges = assetChanges;
     }
 }
-/** Sanctioned or compromised address detected. Never bypassable. */
-export class AddressScreeningError extends SimulationPackageError {
-    addresses;
-    code = "SCREENING_ERROR";
-    constructor(message, addresses) {
-        super(message);
-        this.addresses = addresses;
-    }
-}
 /** Tenderly or RPC service is down. Bypassable — user can proceed. */
 export class ExternalServiceError extends SimulationPackageError {
     code = "EXTERNAL_SERVICE_ERROR";

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

@@ -1,5 +1,4 @@
 // 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 { BlacklistViolationError, ExternalServiceError, SimulationPackageError, SimulationRevertedError, SimulationValidationError, UnsupportedChainError, } from "./errors.js";
 export { simulate } from "./simulate/index.js";

package/lib/esm/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/esm/simulate/asset-changes.js

@@ -0,0 +1,44 @@
+import { getAddress } from "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.
+ */
+export function groupAssetChanges(entries) {
+    const byAccount = new Map();
+    for (const entry of entries) {
+        if (entry.diff === 0n)
+            continue;
+        const account = 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/esm/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/esm/simulate/backends/eth-simulate-v1.js

@@ -1,10 +1,21 @@
-import { createPublicClient, getAddress, http, maxUint256, } from "viem";
+import { createPublicClient, ethAddress, getAddress, http, maxUint256, } from "viem";
 import { ExternalServiceError, SimulationRevertedError, SimulationValidationError, } from "../../errors.js";
+import { groupAssetChanges } from "../asset-changes.js";
+import { parseTransfers } from "../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.
  */
 export async function simulateV1(params) {
     const { rpcUrl, transactions, blockNumber, signal } = params;
@@ -61,7 +72,13 @@ export async function simulateV1(params) {
             returnData: r.data ?? "0x",
             gasUsed: r.gasUsed,
         }));
-        return { calls: rawCalls };
+        return {
+            calls: rawCalls,
+            assetChanges: toAssetChanges({
+                transfers: parseTransfers(rawCalls),
+                transactions,
+            }),
+        };
     }
     catch (error) {
         if (error instanceof SimulationRevertedError)
@@ -71,3 +88,24 @@ export async function simulateV1(params) {
         throw new 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: ethAddress, diff: -tx.value });
+        entries.push({ account: tx.to, token: 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 groupAssetChanges(entries);
+}

package/lib/esm/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";