@morpho-org/evm-simulation 4.2.1 → 5.0.1

package/lib/esm/simulate/result.d.ts

@@ -0,0 +1,19 @@
+import type { AuthorizationPreparation, SimulatedOperation, VerifiedSimulationResult } from "../result.js";
+import type { AccountAssetChanges, SimulationCall, Transfer } from "../types.js";
+import type { CheckContext } from "./context.js";
+import type { ParsedRequest } from "./request/parse-request.js";
+/**
+ * Assemble the public result from the checked pipeline. Only user
+ * transactions appear in `simulationTxs`/`calls`/`transfers` — preparation
+ * calls and state reads never get a public `txIdx`.
+ * @internal
+ */
+export declare function assembleResult(params: {
+    readonly ctx: CheckContext;
+    readonly request: ParsedRequest;
+    readonly operations: readonly SimulatedOperation[];
+    readonly authorizations: readonly AuthorizationPreparation[];
+    readonly userCalls: readonly SimulationCall[];
+    readonly transfers: readonly Transfer[];
+    readonly assetChanges: readonly AccountAssetChanges[];
+}): VerifiedSimulationResult;

package/lib/esm/simulate/result.js

@@ -0,0 +1,26 @@
+import { deepFreeze } from "@morpho-org/morpho-ts";
+/**
+ * Assemble the public result from the checked pipeline. Only user
+ * transactions appear in `simulationTxs`/`calls`/`transfers` — preparation
+ * calls and state reads never get a public `txIdx`.
+ * @internal
+ */
+export function assembleResult(params) {
+    const { ctx, request, operations, authorizations, userCalls, transfers, assetChanges, } = params;
+    const verification = {
+        mode: ctx.mode,
+        chainId: ctx.chainId,
+        blockNumber: ctx.block.blockNumber,
+        blockTimestamp: ctx.block.blockTimestamp,
+        limits: ctx.limits,
+        operations,
+        authorizations,
+    };
+    return deepFreeze({
+        simulationTxs: request.transactions,
+        calls: userCalls,
+        transfers,
+        assetChanges,
+        verification,
+    });
+}

package/lib/esm/simulate/run-simulation.d.ts

@@ -0,0 +1,18 @@
+import type { VerifiedSimulationResult } from "../result.js";
+import type { SimulationConfig } from "../types.js";
+import type { ParsedRequest } from "./request/parse-request.js";
+/**
+ * Run the verified simulation pipeline in a single `eth_simulateV1` call:
+ * resolve quoted assets → plan quoted observations → execution →
+ * slippage comparisons → bundle-retention assertion → result assembly.
+ *
+ * One `AbortSignal` (the request timeout) covers every RPC step.
+ *
+ * @internal
+ * @param params - The simulation config and the parsed caller request.
+ * @returns The deep-frozen {@link VerifiedSimulationResult}.
+ */
+export declare function runSimulation(params: {
+    readonly config: SimulationConfig;
+    readonly request: ParsedRequest;
+}): Promise<VerifiedSimulationResult>;

package/lib/esm/simulate/run-simulation.js

@@ -0,0 +1,153 @@
+import { ChainId, getChainAddresses, UnsupportedChainIdError, } from "@morpho-org/blue-sdk";
+import { _try } from "@morpho-org/morpho-ts";
+import { zeroAddress } from "viem";
+import { InvalidSimulationResponseError, UnsupportedChainError, } from "../errors.js";
+import { groupAssetChanges } from "./asset-changes.js";
+import { createSimulationClient } from "./backends/client.js";
+import { assertEndpointChain, executePlan } from "./backends/index.js";
+import { resolveAssets } from "./backends/resolve-assets.js";
+import { resolvePinnedBlock } from "./backends/resolve-pinned-block.js";
+import { parseTransfers } from "./parsing/index.js";
+import { assertNoBundlesRetention } from "./pipeline/bundles-retention.js";
+import { resolveChain } from "./pipeline/resolve-chain.js";
+import { planExecution } from "./plan/plan-execution.js";
+import { prepareAuthorizations } from "./prepare.js";
+import { assembleResult } from "./result.js";
+import { decodeStateRead, planStateReads } from "./state/read-state.js";
+import { verifySlippage } from "./verify-slippage.js";
+/** Total execution budget for a single `simulate()` call. */
+const DEFAULT_TIMEOUT_MS = 5000;
+/**
+ * Run the verified simulation pipeline in a single `eth_simulateV1` call:
+ * resolve quoted assets → plan quoted observations → execution →
+ * slippage comparisons → bundle-retention assertion → result assembly.
+ *
+ * One `AbortSignal` (the request timeout) covers every RPC step.
+ *
+ * @internal
+ * @param params - The simulation config and the parsed caller request.
+ * @returns The deep-frozen {@link VerifiedSimulationResult}.
+ */
+export async function runSimulation(params) {
+    const { config, request } = params;
+    const chain = resolveChain(config, request.chainId);
+    const signal = AbortSignal.timeout(config.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+    const client = createSimulationClient(chain.simulateV1Url, signal);
+    const limits = { operations: request.limits?.operations ?? [] };
+    const preview = request.mode === "preview";
+    const owner = request.transactions[0].from;
+    const addresses = _try(() => getChainAddresses(request.chainId), UnsupportedChainIdError);
+    const requiresMorpho = limits.operations.length > 0 ||
+        (preview && request.authorizations.length > 0);
+    if (requiresMorpho && addresses?.blue == null)
+        throw new UnsupportedChainError(request.chainId);
+    const morpho = addresses?.blue ?? zeroAddress;
+    await assertEndpointChain({
+        client,
+        chainId: request.chainId,
+        mode: request.mode,
+        blockNumber: typeof request.blockNumber === "bigint" ? request.blockNumber : undefined,
+    });
+    // Monad nodes reject `validation: false` and charge no gas in the simulated
+    // block either way. Its `latest` block is not final: simulating at its number
+    // runs on another parent, so default to `finalized`.
+    const monad = request.chainId === ChainId.MonadMainnet;
+    const pinnedBlock = await resolvePinnedBlock({
+        client,
+        blockNumber: request.blockNumber ?? (monad ? "finalized" : undefined),
+        signal,
+    });
+    // With no calldata decoding, the caller's declared `limits.operations`
+    // entries are the operations: subjects for state reads and per-operation
+    // checks come straight from the limit list.
+    const resolved = await resolveAssets({
+        client,
+        morpho,
+        operations: limits.operations,
+        chainId: request.chainId,
+        mode: request.mode,
+        blockNumber: pinnedBlock.number,
+    });
+    const observations = planStateReads({ operations: resolved, owner, morpho });
+    const preparations = preview
+        ? prepareAuthorizations({
+            authorizations: request.authorizations,
+            owner,
+            morpho,
+        })
+        : [];
+    const plan = planExecution({
+        request,
+        owner,
+        preparations,
+        reads: observations.reads,
+    });
+    // Execute against the block resolved once above; the boundary rechecks its hash.
+    const execution = await executePlan({
+        client,
+        plan,
+        stateBlock: pinnedBlock,
+        validation: monad,
+    });
+    const userCalls = execution.calls
+        .filter((call) => call.planned.type === "transaction")
+        .map((call) => call.result);
+    if (userCalls.length !== request.transactions.length)
+        throw new InvalidSimulationResponseError(`Execution returned ${userCalls.length} user call result(s) for ${request.transactions.length} transaction(s)`);
+    const decodePhase = (phase) => new Map(execution.stateReads
+        .filter((read) => read.phase === phase)
+        .map((read) => [
+        read.read.id,
+        decodeStateRead(read.read, read.returnData, {
+            chainId: request.chainId,
+            mode: request.mode,
+            blockNumber: pinnedBlock.number,
+        }),
+    ]));
+    const transfers = parseTransfers(userCalls, {
+        wNative: addresses === undefined ? undefined : (addresses.wNative ?? null),
+        logger: config.logger,
+    });
+    const assetChanges = groupAssetChanges(transfers.flatMap(({ token, from, to, amount }) => [
+        { account: to, token, diff: amount },
+        { account: from, token, diff: -amount },
+    ]));
+    const ctx = {
+        chainId: request.chainId,
+        mode: request.mode,
+        block: execution.block,
+        owner,
+        limits,
+    };
+    const authorizations = request.authorizations.map((authorization, authorizationIndex) => ({
+        authorizationIndex,
+        authorization,
+        calls: execution.calls.flatMap(({ planned, result }) => planned.type === "preparation" &&
+            planned.authorizationIndex === authorizationIndex
+            ? [{ transaction: planned.transaction, result }]
+            : []),
+    }));
+    const checked = verifySlippage({
+        ctx,
+        operations: observations.operations,
+        before: decodePhase("before"),
+        after: decodePhase("after"),
+        transfers,
+        requestTransactions: request.transactions,
+    });
+    assertNoBundlesRetention({
+        chainId: request.chainId,
+        transfers,
+        assetChanges,
+        logger: config.logger,
+    });
+    return assembleResult({
+        ctx,
+        request,
+        operations: checked,
+        authorizations,
+        userCalls,
+        transfers,
+        assetChanges,
+    });
+}

package/lib/esm/simulate/simulate.d.ts

@@ -1,68 +1,119 @@
-import type { SimulateParams, SimulationConfig, SimulationResult } from "../types.js";
+import type { SimulateParams } from "../params.js";
+import type { VerifiedSimulationResult } from "../result.js";
+import type { SimulationConfig } from "../types.js";
 /**
  * Simulate a bundle of EVM transactions.
  *
- * Validates input → resolves authorizations into prepended approve txs → runs the bundle
- * through Tenderly RPC (primary) or `eth_simulateV1` (fallback) with a shared timeout
- * budget → parses ERC20 transfers and WETH9 events from per-tx logs, restricting WETH9
- * events to the registered wrapped-native token, rejecting them on known tokenless chains,
- * and retaining signature-based parsing for unknown chains → asserts no funds are retained
- * by the restricted standalone bundles contracts (VaultExitBundlesV1, VaultBundlesV1,
- * BlueBundlesV1, MidnightBundlesV1) → returns the full result
- * set. The caller reads whichever fields they need:
+ * Parses and normalizes the request → resolves the chain identity → resolves
+ * a single pinned block → resolves quoted-asset metadata → plans state reads
+ * and the execution → executes once through `eth_simulateV1` under the full
+ * timeout budget (simulation with in-block state reads → response parsing →
+ * reorg check) → derives ERC20/WETH9 transfers and net asset changes from the
+ * user calls only → decodes quoted balances/positions → runs slippage checks
+ * → asserts no funds are retained by standalone `bundles` periphery contracts
+ * → returns the result. The caller reads whichever fields they need:
  *
- * - `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]`. `gasUsed` is not a safe gas limit; consumers
- *   deriving one must add their own headroom.
- * - `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]`.
+ * - `simulationTxs` → exactly the caller's ordered transactions, normalized
+ *   (checksummed addresses, `value` defaulted to `0n`). Internal state reads are
+ *   never exposed.
+ * - `calls[i]` → per-tx raw backend output (`logs`, `status`, `returnData`,
+ *   `gasUsed`), aligned 1:1 with `simulationTxs[i]`. `gasUsed` is not a safe
+ *   gas limit; consumers deriving one must add their own headroom.
+ * - `transfers` → user-facing preview / server-side verification; each
+ *   transfer's `txIdx` indexes into `simulationTxs`.
+ * - `assetChanges` → net per-asset balance changes grouped by account (sender
+ *   and counterparties) over the whole bundle.
  *
- * @param config - Backend configuration: per-chain Tenderly RPC and/or `eth_simulateV1`
- *   URL, optional logger, and the overall timeout budget.
+ * **Modes.** `mode` defaults to `"final"`, which executes the signed calldata
+ * against actual permissions and accepts no `authorizations`. `mode:
+ * "preview"` accepts typed authorization descriptors, which the pipeline
+ * prepares as simulated approval calls. No authorization read-back checks run.
+ * `limits` are optional caller-supplied quotes and percentage tolerances;
+ * violations throw `ConsumerLimitViolationError`.
+ *
+ * **Funding.** `value` transfers are funded by the sender's real native
+ * balance — no balance inflation — so under-funded bundles revert exactly as
+ * they would on-chain. `validation: false` keeps gas from being charged,
+ * separating gas from economic effects. Monad nodes reject `false`, so Monad
+ * simulations send `true`; its simulated block charges no gas either way.
+ *
+ * @param config - Required per-chain `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
- *   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`.
- * @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 beyond
- *   the dust threshold by a `bundles` periphery contract (VaultExitBundlesV1,
- *   VaultBundlesV1, BlueBundlesV1, MidnightBundlesV1). Never bypassable.
- * @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 per-account net `assetChanges`.
+ * @param params.chainId - Chain id the bundle targets; must match the endpoint.
+ * @param params.transactions - The bundle's transactions, in execution order.
+ *   All must share the same `from`.
+ * @param params.mode - `"final"` (default) or `"preview"`.
+ * @param params.authorizations - Preview-only typed authorization descriptors.
+ * @param params.limits - Optional quotes and percentage tolerances; unquoted amounts require no reads.
+ * @param params.blockNumber - Optional pinned block number or `BlockTag` other
+ *   than `"pending"`.
+ *   Defaults to `latest` (`finalized` on Monad, whose `latest` block is not
+ *   final), resolved exactly once.
+ * @throws {SimulationValidationError} for invalid input (mixed senders, bad
+ *   addresses, empty transactions, malformed authorizations, final-mode
+ *   authorizations, malformed limits, unknown fields, a `"pending"` block tag, or share quotes for
+ *   `blueSupplyCollateral` / `blueWithdrawCollateral`).
+ * @throws {ConsumerLimitViolationError} when a declared `limits` bound is
+ *   violated by the observed effects.
+ * @throws {UnsupportedChainError} when the chain has no `eth_simulateV1`
+ *   endpoint configured, or limits/preview authorizations require a Morpho
+ *   Blue address absent from blue-sdk's `getChainAddresses`.
+ * @throws {SimulationRevertedError} when a preparation or user transaction reverts.
+ * @throws {MissingVerificationEvidenceError} when a planned state read fails
+ *   or returns empty data, native outgoing traces do not cover value
+ *   sent, or required metadata reverts or returns empty/invalid data.
+ * @throws {InvalidSimulationResponseError} when the node response cannot be
+ *   trusted (bad shape, call-count mismatch, block that is neither the pinned
+ *   state block nor its immediate successor, a successor with a mismatched
+ *   `parentHash`, a block timestamp earlier than the pinned block's, a
+ *   malformed per-call result, a quoted balance/position read whose non-empty
+ *   return data cannot be decoded, a state-block hash that changed or a pinned
+ *   block that vanished mid-flight, or an
+ *   endpoint whose `eth_chainId` differs from `params.chainId`; chain identity
+ *   is checked before any block lookup).
+ * @throws {BlacklistViolationError} when the simulation leaves value retained
+ *   beyond the dust threshold by a `bundles` periphery contract
+ *   (VaultExitBundlesV1, VaultBundlesV1, BlueBundlesV1, MidnightBundlesV1).
+ *   Never bypassable.
+ * @throws {ExternalServiceError} when the RPC is unavailable within the
+ *   timeout budget or returns a malformed JSON-RPC envelope. Chain-id
+ *   mismatches and a state block without number/hash are reported as
+ *   `InvalidSimulationResponseError`.
+ * @returns A frozen {@link VerifiedSimulationResult} carrying the normalized
+ *   `simulationTxs`, per-tx `calls` (aligned 1:1), parsed `transfers` (each
+ *   stamped with `txIdx`), per-account net `assetChanges`, and per-operation
+ *   verification outcomes and preparations. Each `verification.operations[i]`
+ *   mirrors the `limits.operations[i]` entry it verified. Only the amounts
+ *   quoted in each entry are checked; `checkedLimits` identifies precisely
+ *   what was checked. Measurements are scoped to the whole bundle.
  * @example
  * ```ts
  * import { simulate } from "@morpho-org/evm-simulation";
+ * import { type Address, encodeFunctionData, erc20Abi, getAddress } from "viem";
+ *
+ * const rpcUrl = "https://rpc.example";
+ * const user: Address = getAddress("0x1111111111111111111111111111111111111111");
+ * const usdc: Address = getAddress("0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48");
+ * const recipient: Address = getAddress("0x2222222222222222222222222222222222222222");
  *
  * const result = await simulate(
- *   {
- *     chains: new Map([
- *       [1, {
- *         tenderlyRpc: { rpcUrl: process.env.TENDERLY_RPC_URL! },
- *         simulateV1Url: process.env.MAINNET_RPC_URL,
- *       }],
- *     ]),
- *   },
+ *   { chains: new Map([[1, { simulateV1Url: rpcUrl }]]) },
  *   {
  *     chainId: 1,
- *     transactions: [{ from: user, to: vaultAddress, data: encodedCalldata, value: 0n }],
+ *     transactions: [
+ *       {
+ *         from: user,
+ *         to: usdc,
+ *         data: encodeFunctionData({
+ *           abi: erc20Abi,
+ *           functionName: "transfer",
+ *           args: [recipient, 1_000_000n],
+ *         }),
+ *       },
+ *     ],
  *   },
  * );
- * // result satisfies SimulationResult
  * ```
  */
-export declare function simulate(config: SimulationConfig, params: SimulateParams): Promise<SimulationResult>;
+export declare function simulate(config: SimulationConfig, params: SimulateParams): Promise<VerifiedSimulationResult>;

package/lib/esm/simulate/simulate.js

@@ -1,101 +1,120 @@
-import { _try, getChainAddresses, UnsupportedChainIdError, } from "@morpho-org/blue-sdk";
-import { ExternalServiceError } from "../errors.js";
-import { parseTransfers } from "./parsing/index.js";
-import { assertNoBundlesRetention, buildSimulationTxs, executeSimulation, validateInput, } from "./pipeline/index.js";
+import { parseRequest } from "./request/index.js";
+import { runSimulation } from "./run-simulation.js";
 /**
  * Simulate a bundle of EVM transactions.
  *
- * Validates input → resolves authorizations into prepended approve txs → runs the bundle
- * through Tenderly RPC (primary) or `eth_simulateV1` (fallback) with a shared timeout
- * budget → parses ERC20 transfers and WETH9 events from per-tx logs, restricting WETH9
- * events to the registered wrapped-native token, rejecting them on known tokenless chains,
- * and retaining signature-based parsing for unknown chains → asserts no funds are retained
- * by the restricted standalone bundles contracts (VaultExitBundlesV1, VaultBundlesV1,
- * BlueBundlesV1, MidnightBundlesV1) → returns the full result
- * set. The caller reads whichever fields they need:
+ * Parses and normalizes the request → resolves the chain identity → resolves
+ * a single pinned block → resolves quoted-asset metadata → plans state reads
+ * and the execution → executes once through `eth_simulateV1` under the full
+ * timeout budget (simulation with in-block state reads → response parsing →
+ * reorg check) → derives ERC20/WETH9 transfers and net asset changes from the
+ * user calls only → decodes quoted balances/positions → runs slippage checks
+ * → asserts no funds are retained by standalone `bundles` periphery contracts
+ * → returns the result. The caller reads whichever fields they need:
  *
- * - `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]`. `gasUsed` is not a safe gas limit; consumers
- *   deriving one must add their own headroom.
- * - `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]`.
+ * - `simulationTxs` → exactly the caller's ordered transactions, normalized
+ *   (checksummed addresses, `value` defaulted to `0n`). Internal state reads are
+ *   never exposed.
+ * - `calls[i]` → per-tx raw backend output (`logs`, `status`, `returnData`,
+ *   `gasUsed`), aligned 1:1 with `simulationTxs[i]`. `gasUsed` is not a safe
+ *   gas limit; consumers deriving one must add their own headroom.
+ * - `transfers` → user-facing preview / server-side verification; each
+ *   transfer's `txIdx` indexes into `simulationTxs`.
+ * - `assetChanges` → net per-asset balance changes grouped by account (sender
+ *   and counterparties) over the whole bundle.
  *
- * @param config - Backend configuration: per-chain Tenderly RPC and/or `eth_simulateV1`
- *   URL, optional logger, and the overall timeout budget.
+ * **Modes.** `mode` defaults to `"final"`, which executes the signed calldata
+ * against actual permissions and accepts no `authorizations`. `mode:
+ * "preview"` accepts typed authorization descriptors, which the pipeline
+ * prepares as simulated approval calls. No authorization read-back checks run.
+ * `limits` are optional caller-supplied quotes and percentage tolerances;
+ * violations throw `ConsumerLimitViolationError`.
+ *
+ * **Funding.** `value` transfers are funded by the sender's real native
+ * balance — no balance inflation — so under-funded bundles revert exactly as
+ * they would on-chain. `validation: false` keeps gas from being charged,
+ * separating gas from economic effects. Monad nodes reject `false`, so Monad
+ * simulations send `true`; its simulated block charges no gas either way.
+ *
+ * @param config - Required per-chain `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
- *   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`.
- * @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 beyond
- *   the dust threshold by a `bundles` periphery contract (VaultExitBundlesV1,
- *   VaultBundlesV1, BlueBundlesV1, MidnightBundlesV1). Never bypassable.
- * @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 per-account net `assetChanges`.
+ * @param params.chainId - Chain id the bundle targets; must match the endpoint.
+ * @param params.transactions - The bundle's transactions, in execution order.
+ *   All must share the same `from`.
+ * @param params.mode - `"final"` (default) or `"preview"`.
+ * @param params.authorizations - Preview-only typed authorization descriptors.
+ * @param params.limits - Optional quotes and percentage tolerances; unquoted amounts require no reads.
+ * @param params.blockNumber - Optional pinned block number or `BlockTag` other
+ *   than `"pending"`.
+ *   Defaults to `latest` (`finalized` on Monad, whose `latest` block is not
+ *   final), resolved exactly once.
+ * @throws {SimulationValidationError} for invalid input (mixed senders, bad
+ *   addresses, empty transactions, malformed authorizations, final-mode
+ *   authorizations, malformed limits, unknown fields, a `"pending"` block tag, or share quotes for
+ *   `blueSupplyCollateral` / `blueWithdrawCollateral`).
+ * @throws {ConsumerLimitViolationError} when a declared `limits` bound is
+ *   violated by the observed effects.
+ * @throws {UnsupportedChainError} when the chain has no `eth_simulateV1`
+ *   endpoint configured, or limits/preview authorizations require a Morpho
+ *   Blue address absent from blue-sdk's `getChainAddresses`.
+ * @throws {SimulationRevertedError} when a preparation or user transaction reverts.
+ * @throws {MissingVerificationEvidenceError} when a planned state read fails
+ *   or returns empty data, native outgoing traces do not cover value
+ *   sent, or required metadata reverts or returns empty/invalid data.
+ * @throws {InvalidSimulationResponseError} when the node response cannot be
+ *   trusted (bad shape, call-count mismatch, block that is neither the pinned
+ *   state block nor its immediate successor, a successor with a mismatched
+ *   `parentHash`, a block timestamp earlier than the pinned block's, a
+ *   malformed per-call result, a quoted balance/position read whose non-empty
+ *   return data cannot be decoded, a state-block hash that changed or a pinned
+ *   block that vanished mid-flight, or an
+ *   endpoint whose `eth_chainId` differs from `params.chainId`; chain identity
+ *   is checked before any block lookup).
+ * @throws {BlacklistViolationError} when the simulation leaves value retained
+ *   beyond the dust threshold by a `bundles` periphery contract
+ *   (VaultExitBundlesV1, VaultBundlesV1, BlueBundlesV1, MidnightBundlesV1).
+ *   Never bypassable.
+ * @throws {ExternalServiceError} when the RPC is unavailable within the
+ *   timeout budget or returns a malformed JSON-RPC envelope. Chain-id
+ *   mismatches and a state block without number/hash are reported as
+ *   `InvalidSimulationResponseError`.
+ * @returns A frozen {@link VerifiedSimulationResult} carrying the normalized
+ *   `simulationTxs`, per-tx `calls` (aligned 1:1), parsed `transfers` (each
+ *   stamped with `txIdx`), per-account net `assetChanges`, and per-operation
+ *   verification outcomes and preparations. Each `verification.operations[i]`
+ *   mirrors the `limits.operations[i]` entry it verified. Only the amounts
+ *   quoted in each entry are checked; `checkedLimits` identifies precisely
+ *   what was checked. Measurements are scoped to the whole bundle.
  * @example
  * ```ts
  * import { simulate } from "@morpho-org/evm-simulation";
+ * import { type Address, encodeFunctionData, erc20Abi, getAddress } from "viem";
+ *
+ * const rpcUrl = "https://rpc.example";
+ * const user: Address = getAddress("0x1111111111111111111111111111111111111111");
+ * const usdc: Address = getAddress("0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48");
+ * const recipient: Address = getAddress("0x2222222222222222222222222222222222222222");
  *
  * const result = await simulate(
- *   {
- *     chains: new Map([
- *       [1, {
- *         tenderlyRpc: { rpcUrl: process.env.TENDERLY_RPC_URL! },
- *         simulateV1Url: process.env.MAINNET_RPC_URL,
- *       }],
- *     ]),
- *   },
+ *   { chains: new Map([[1, { simulateV1Url: rpcUrl }]]) },
  *   {
  *     chainId: 1,
- *     transactions: [{ from: user, to: vaultAddress, data: encodedCalldata, value: 0n }],
+ *     transactions: [
+ *       {
+ *         from: user,
+ *         to: usdc,
+ *         data: encodeFunctionData({
+ *           abi: erc20Abi,
+ *           functionName: "transfer",
+ *           args: [recipient, 1_000_000n],
+ *         }),
+ *       },
+ *     ],
  *   },
  * );
- * // result satisfies SimulationResult
  * ```
  */
 export async function simulate(config, params) {
-    validateInput(params);
-    const wNative = _try(() => getChainAddresses(params.chainId).wNative ?? null, UnsupportedChainIdError);
-    const simulationTxs = buildSimulationTxs(params);
-    const result = await executeSimulation({
-        config,
-        chainId: params.chainId,
-        transactions: simulationTxs,
-        blockNumber: params.blockNumber,
-        wNative,
-    });
-    if (result.calls.length !== simulationTxs.length) {
-        throw new ExternalServiceError(`Backend returned ${result.calls.length} call result(s) for ${simulationTxs.length} transaction(s) — refusing to map transfers with mismatched lengths`);
-    }
-    const transfers = parseTransfers(result.calls, {
-        wNative,
-        logger: config.logger,
-    });
-    assertNoBundlesRetention({
-        chainId: params.chainId,
-        transfers,
-        assetChanges: result.assetChanges,
-        logger: config.logger,
-    });
-    return {
-        simulationTxs,
-        calls: result.calls,
-        transfers,
-        assetChanges: result.assetChanges,
-    };
+    return runSimulation({ config, request: parseRequest(params) });
 }

package/lib/esm/simulate/slippage.d.ts

@@ -0,0 +1,18 @@
+import { type SimulationVerificationContext } from "../errors.js";
+import type { SlippageLimits, SlippageQuote } from "../limits.js";
+/**
+ * Compare observed amounts against the caller's quote and percentage tolerance.
+ * Minimum outputs round up and maximum inputs round down, so rounding never
+ * permits a deviation greater than the requested percentage.
+ * @param params - Parsed quote/tolerance, matching observations, and error context.
+ * @returns The checked quote and tolerance, deep-frozen.
+ * @throws {ConsumerLimitViolationError} When adverse slippage exceeds tolerance.
+ * @throws {MissingVerificationEvidenceError} When a quoted amount has no observation.
+ * @internal
+ */
+export declare function checkSlippage(params: {
+    readonly limits: SlippageLimits;
+    readonly observed: SlippageQuote;
+    readonly context: SimulationVerificationContext;
+    readonly debtShares?: boolean;
+}): SlippageLimits;