@morpho-org/evm-simulation 4.2.1 → 5.0.0

package/lib/cjs/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/cjs/simulate/result.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assembleResult = assembleResult;
+const morpho_ts_1 = require("@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
+ */
+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 (0, morpho_ts_1.deepFreeze)({
+        simulationTxs: request.transactions,
+        calls: userCalls,
+        transfers,
+        assetChanges,
+        verification,
+    });
+}

package/lib/cjs/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/cjs/simulate/run-simulation.js

@@ -0,0 +1,151 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runSimulation = runSimulation;
+const blue_sdk_1 = require("@morpho-org/blue-sdk");
+const morpho_ts_1 = require("@morpho-org/morpho-ts");
+const viem_1 = require("viem");
+const errors_js_1 = require("../errors.js");
+const asset_changes_js_1 = require("./asset-changes.js");
+const client_js_1 = require("./backends/client.js");
+const index_js_1 = require("./backends/index.js");
+const resolve_assets_js_1 = require("./backends/resolve-assets.js");
+const resolve_pinned_block_js_1 = require("./backends/resolve-pinned-block.js");
+const index_js_2 = require("./parsing/index.js");
+const bundles_retention_js_1 = require("./pipeline/bundles-retention.js");
+const resolve_chain_js_1 = require("./pipeline/resolve-chain.js");
+const plan_execution_js_1 = require("./plan/plan-execution.js");
+const prepare_js_1 = require("./prepare.js");
+const result_js_1 = require("./result.js");
+const read_state_js_1 = require("./state/read-state.js");
+const verify_slippage_js_1 = require("./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}.
+ */
+async function runSimulation(params) {
+    const { config, request } = params;
+    const chain = (0, resolve_chain_js_1.resolveChain)(config, request.chainId);
+    const signal = AbortSignal.timeout(config.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+    const client = (0, client_js_1.createSimulationClient)(chain.simulateV1Url, signal);
+    const limits = { operations: request.limits?.operations ?? [] };
+    const preview = request.mode === "preview";
+    const owner = request.transactions[0].from;
+    const addresses = (0, morpho_ts_1._try)(() => (0, blue_sdk_1.getChainAddresses)(request.chainId), blue_sdk_1.UnsupportedChainIdError);
+    const requiresMorpho = limits.operations.length > 0 ||
+        (preview && request.authorizations.length > 0);
+    if (requiresMorpho && addresses?.blue == null)
+        throw new errors_js_1.UnsupportedChainError(request.chainId);
+    const morpho = addresses?.blue ?? viem_1.zeroAddress;
+    await (0, index_js_1.assertEndpointChain)({
+        client,
+        chainId: request.chainId,
+        mode: request.mode,
+        blockNumber: typeof request.blockNumber === "bigint" ? request.blockNumber : undefined,
+    });
+    const pinnedBlock = await (0, resolve_pinned_block_js_1.resolvePinnedBlock)({
+        client,
+        blockNumber: request.blockNumber,
+        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 (0, resolve_assets_js_1.resolveAssets)({
+        client,
+        morpho,
+        operations: limits.operations,
+        chainId: request.chainId,
+        mode: request.mode,
+        blockNumber: pinnedBlock.number,
+    });
+    const observations = (0, read_state_js_1.planStateReads)({ operations: resolved, owner, morpho });
+    const preparations = preview
+        ? (0, prepare_js_1.prepareAuthorizations)({
+            authorizations: request.authorizations,
+            owner,
+            morpho,
+        })
+        : [];
+    const plan = (0, plan_execution_js_1.planExecution)({
+        request,
+        owner,
+        preparations,
+        reads: observations.reads,
+    });
+    // Execute against the block resolved once above; the boundary rechecks its hash.
+    const execution = await (0, index_js_1.executePlan)({
+        client,
+        plan,
+        stateBlock: pinnedBlock,
+    });
+    const userCalls = execution.calls
+        .filter((call) => call.planned.type === "transaction")
+        .map((call) => call.result);
+    if (userCalls.length !== request.transactions.length)
+        throw new errors_js_1.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,
+        (0, read_state_js_1.decodeStateRead)(read.read, read.returnData, {
+            chainId: request.chainId,
+            mode: request.mode,
+            blockNumber: pinnedBlock.number,
+        }),
+    ]));
+    const transfers = (0, index_js_2.parseTransfers)(userCalls, {
+        wNative: addresses === undefined ? undefined : (addresses.wNative ?? null),
+        logger: config.logger,
+    });
+    const assetChanges = (0, asset_changes_js_1.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 = (0, verify_slippage_js_1.verifySlippage)({
+        ctx,
+        operations: observations.operations,
+        before: decodePhase("before"),
+        after: decodePhase("after"),
+        transfers,
+        requestTransactions: request.transactions,
+    });
+    (0, bundles_retention_js_1.assertNoBundlesRetention)({
+        chainId: request.chainId,
+        transfers,
+        assetChanges,
+        logger: config.logger,
+    });
+    return (0, result_js_1.assembleResult)({
+        ctx,
+        request,
+        operations: checked,
+        authorizations,
+        userCalls,
+        transfers,
+        assetChanges,
+    });
+}

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

@@ -1,68 +1,117 @@
-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.
+ *
+ * @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`, 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/cjs/simulate/simulate.js

@@ -1,104 +1,121 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.simulate = simulate;
-const blue_sdk_1 = require("@morpho-org/blue-sdk");
-const errors_js_1 = require("../errors.js");
-const index_js_1 = require("./parsing/index.js");
-const index_js_2 = require("./pipeline/index.js");
+const index_js_1 = require("./request/index.js");
+const run_simulation_js_1 = require("./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.
+ *
+ * @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`, 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
  * ```
  */
 async function simulate(config, params) {
-    (0, index_js_2.validateInput)(params);
-    const wNative = (0, blue_sdk_1._try)(() => (0, blue_sdk_1.getChainAddresses)(params.chainId).wNative ?? null, blue_sdk_1.UnsupportedChainIdError);
-    const simulationTxs = (0, index_js_2.buildSimulationTxs)(params);
-    const result = await (0, index_js_2.executeSimulation)({
-        config,
-        chainId: params.chainId,
-        transactions: simulationTxs,
-        blockNumber: params.blockNumber,
-        wNative,
-    });
-    if (result.calls.length !== simulationTxs.length) {
-        throw new errors_js_1.ExternalServiceError(`Backend returned ${result.calls.length} call result(s) for ${simulationTxs.length} transaction(s) — refusing to map transfers with mismatched lengths`);
-    }
-    const transfers = (0, index_js_1.parseTransfers)(result.calls, {
-        wNative,
-        logger: config.logger,
-    });
-    (0, index_js_2.assertNoBundlesRetention)({
-        chainId: params.chainId,
-        transfers,
-        assetChanges: result.assetChanges,
-        logger: config.logger,
-    });
-    return {
-        simulationTxs,
-        calls: result.calls,
-        transfers,
-        assetChanges: result.assetChanges,
-    };
+    return (0, run_simulation_js_1.runSimulation)({ config, request: (0, index_js_1.parseRequest)(params) });
 }

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