@morpho-org/evm-simulation 4.2.1 → 5.0.0

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

@@ -1,114 +1,188 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.simulateV1 = simulateV1;
+exports.rpc = void 0;
+exports.assertEndpointChain = assertEndpointChain;
+exports.executePlan = executePlan;
 const viem_1 = require("viem");
 const errors_js_1 = require("../../errors.js");
-const asset_changes_js_1 = require("../asset-changes.js");
-const index_js_1 = require("../parsing/index.js");
+const parse_response_js_1 = require("./parse-response.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.
- *
- * Runs with `traceTransfers` enabled, so the node synthesizes native-ETH moves
- * (the top-level `value` *and* ETH moved through internal calls — e.g. a
- * `WETH.withdraw` refund or a swap that pays out ETH) as `Transfer` events from
- * the native sentinel. Derives `assetChanges` (net per-token deltas grouped by
- * account) entirely from the emitted transfer logs, with native ETH normalized
- * to viem's `ethAddress`. Top-level `value` is intentionally *not* added on top:
- * `traceTransfers` already logs it, so adding it would double-count.
+ * Classify a node-level revert: viem's `ExecutionRevertedError`, or a raw
+ * JSON-RPC error — code 3 for "execution reverted", plus an "insufficient
+ * funds" message for an unfundable `value` transfer under real native
+ * funding (the numeric code varies by node, so the message is matched).
  */
-async function simulateV1(params) {
-    const { rpcUrl, transactions, blockNumber, wNative, signal } = params;
-    const client = (0, viem_1.createPublicClient)({
-        transport: (0, viem_1.http)(rpcUrl, {
-            fetchOptions: signal ? { signal } : undefined,
-        }),
-    });
-    const firstTx = transactions[0];
-    if (!firstTx) {
-        throw new errors_js_1.SimulationValidationError("At least one transaction is required", []);
-    }
-    const sender = (0, viem_1.getAddress)(firstTx.from);
-    // eth_simulateV1 executes all calls as the same account. Reject mixed senders
-    // to avoid silently simulating under the wrong address.
-    const mixedSender = transactions.find((tx) => (0, viem_1.getAddress)(tx.from) !== sender);
-    if (mixedSender) {
-        throw new errors_js_1.SimulationValidationError("All transactions must have the same from address for eth_simulateV1", [`expected ${sender}, got ${mixedSender.from}`]);
+const isNodeRevert = (error) => error instanceof viem_1.ExecutionRevertedError ||
+    error instanceof viem_1.InsufficientFundsError ||
+    (error instanceof Error &&
+        (("code" in error && error.code === 3) ||
+            /insufficient funds/i.test(error.message)));
+/**
+ * Trim a caught error to a safe message: viem's `shortMessage` drops the
+ * URL/request-body details its `message` embeds. The original error is always
+ * kept as `cause` for logging.
+ */
+const safeMessage = (error) => error instanceof viem_1.BaseError ? error.shortMessage : String(error);
+/** Map a caught error to the boundary's typed failure for `label`. */
+const toBoundaryError = (label, error) => {
+    if (error instanceof errors_js_1.SimulationPackageError)
+        return error;
+    // A node-level revert is a property of the bundle, not the backend. The
+    // execution-stage context requires an operation-keyed subject and a
+    // node-level revert precedes operation decoding, so no context attaches.
+    // `details` carries only the URL-free code/shortMessage; the raw viem
+    // error (which embeds the RPC URL) is kept as `cause` only.
+    if (label === "eth_simulateV1" && isNodeRevert(error)) {
+        const reverted = new errors_js_1.SimulationRevertedError(error instanceof viem_1.BaseError
+            ? error.details || error.shortMessage
+            : error.message, {
+            code: "code" in error && typeof error.code !== "undefined"
+                ? error.code
+                : undefined,
+            shortMessage: error instanceof viem_1.BaseError ? error.shortMessage : error.message,
+        }, "UNKNOWN_REVERT");
+        reverted.cause = error;
+        return reverted;
     }
-    const calls = transactions.map((tx) => ({
-        to: tx.to,
-        data: tx.data,
-        value: tx.value,
-    }));
-    const blockParam = typeof blockNumber === "bigint"
-        ? { blockNumber }
-        : blockNumber !== undefined
-            ? { blockTag: blockNumber }
-            : {};
+    return new errors_js_1.ExternalServiceError(`${label} error: ${safeMessage(error)}`, {
+        cause: error,
+    });
+};
+/** Run one RPC call; anything thrown becomes a typed boundary error. @internal */
+const rpc = async (label, call) => {
     try {
-        const simulationResult = await client.simulateCalls({
-            account: sender,
-            calls,
-            ...blockParam,
-            // Synthesize native-ETH moves (top-level value + internal calls) as
-            // Transfer logs from the native sentinel, so `parseTransfers` captures
-            // ETH that emits no real log (e.g. a WETH.withdraw refund).
-            traceTransfers: true,
-            // Inflate sender ETH balance to prevent false "insufficient gas" reverts.
-            // Without this, valid ERC20 flows fail when the sender has low ETH.
-            // Use half of uint256 (not the ceiling) so the override leaves headroom
-            // for inbound native ETH — e.g. a WETH.withdraw refund or a swap payout
-            // would overflow the recipient balance and revert the value transfer if
-            // the sender were pinned at maxUint256.
-            stateOverrides: [{ address: sender, balance: viem_1.maxUint256 / 2n }],
-        });
-        const results = simulationResult.results;
-        if (!Array.isArray(results)) {
-            throw new errors_js_1.ExternalServiceError("eth_simulateV1 returned unexpected response format");
-        }
-        const failedResult = results.find((r) => r.status !== "success");
-        if (failedResult) {
-            throw new errors_js_1.SimulationRevertedError(failedResult.error?.message ?? "Simulation failed", results);
-        }
-        const rawCalls = results.map((r) => ({
-            logs: (r.logs ?? []).map((log) => ({
-                address: log.address,
-                topics: [...log.topics],
-                data: log.data ?? "0x",
-            })),
-            status: r.status === "success",
-            returnData: r.data ?? "0x",
-            gasUsed: r.gasUsed,
-        }));
-        return {
-            calls: rawCalls,
-            assetChanges: toAssetChanges((0, index_js_1.parseTransfers)(rawCalls, { wNative })),
-        };
+        return await call();
     }
     catch (error) {
-        if (error instanceof errors_js_1.SimulationRevertedError)
-            throw error;
-        if (error instanceof errors_js_1.ExternalServiceError)
-            throw error;
-        // A node-level "execution reverted" is a property of the bundle, not the backend.
-        if (error instanceof viem_1.ExecutionRevertedError)
-            throw new errors_js_1.SimulationRevertedError(error.shortMessage, error);
-        throw new errors_js_1.ExternalServiceError(`eth_simulateV1 error: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+        throw toBoundaryError(label, error);
     }
+};
+exports.rpc = rpc;
+/** Validate the endpoint identity through the same URL-safe RPC boundary. @internal */
+async function assertEndpointChain(params) {
+    const { client, chainId, mode, blockNumber } = params;
+    const rpcChainId = await (0, exports.rpc)("eth_chainId", () => client.getChainId());
+    if (rpcChainId === chainId)
+        return;
+    throw new errors_js_1.InvalidSimulationResponseError(`The RPC configured for chain ${chainId} reports chain ${rpcChainId}. Fix SimulationConfig.chains.`, {
+        ...(blockNumber !== undefined
+            ? {
+                context: {
+                    stage: "transport",
+                    chainId,
+                    mode,
+                    blockNumber,
+                },
+            }
+            : {}),
+    });
 }
 /**
- * Reduce parsed transfer logs to net per-token balance changes grouped by
- * account. With `traceTransfers` enabled, native ETH (top-level and internal)
- * arrives as transfer logs under viem's `ethAddress`, so no separate top-level
- * `value` accounting is needed — doing so would double-count.
+ * Execute an {@link ExecutionPlan} through a single `eth_simulateV1` call and
+ * collect the pinned execution.
+ *
+ * The caller checks the endpoint chain identity and resolves the pinned state
+ * block before this boundary. This function uses that same block for the
+ * simulation and reorg check under the shared abort/timeout budget.
+ *
+ * The boundary performs these steps:
+ *
+ * 1. **`eth_simulateV1`** — one `blockStateCalls` entry carrying the planned
+ *    calls with their per-call `from`, `traceTransfers: true` so the node
+ *    synthesizes native-ETH moves as transfer logs, and
+ *    `validation: false`. Validation-off means gas is not charged, which is
+ *    how gas is separated from economic effects. **No balance override is
+ *    applied** — `value` transfers are funded by the sender's real native
+ *    balance.
+ * 2. **Response validation** — the response is parsed before the reorg
+ *    re-fetch so revert/mismatch evidence already in hand surfaces instead
+ *    of being downgraded to a bypassable {@link ExternalServiceError} by a
+ *    failing re-fetch. The simulated block must be exactly
+ *    `stateBlockNumber` or `stateBlockNumber + 1`: geth-style nodes report
+ *    the former's successor while Anvil reports the pinned block itself.
+ *    The result records whatever the node returns; consumers must read
+ *    {@link ExecutionBlock.blockNumber} and never assume +1.
+ * 3. **Reorg check** — the pinned state block is re-fetched last to detect a reorg
+ *    that swapped its hash mid-flight (`InvalidSimulationResponseError`).
+ *
+ * The endpoint must support `eth_simulateV1` with per-call `from`; there is
+ * no fallback backend.
+ *
+ * @param params - Shared simulation client, execution plan, and already-pinned
+ *   state block.
+ * @returns Deep-frozen {@link SimulationExecution} — per-transaction call
+ *   results and the resolved {@link ExecutionBlock}.
+ * @throws {ExternalServiceError} For transport failures, timeouts,
+ *   or malformed JSON-RPC envelopes.
+ * @throws {InvalidSimulationResponseError} For a response that cannot be
+ *   trusted (bad shape, call-count mismatch, block
+ *   other than the pinned state block or its successor, a block timestamp
+ *   earlier than the pinned block's, a per-call result that fails normalization,
+ *   or a state-block hash that changed or is no longer served mid-flight).
+ * @throws {MissingVerificationEvidenceError} When a planned state read fails.
+ * @throws {SimulationRevertedError} When a preparation or user transaction
+ *   reverts or the node reports a bundle-level revert (code 3 / insufficient
+ *   funds).
+ * @internal
  */
-function toAssetChanges(transfers) {
-    const entries = [];
-    for (const { token, from, to, amount } of transfers) {
-        entries.push({ account: to, token, diff: amount });
-        entries.push({ account: from, token, diff: -amount });
+async function executePlan(params) {
+    const { client, plan, stateBlock } = params;
+    const response = await (0, exports.rpc)("eth_simulateV1", () => client.request({
+        method: "eth_simulateV1",
+        params: [
+            {
+                blockStateCalls: [
+                    {
+                        calls: plan.calls.map((call) => ({
+                            from: call.transaction.from,
+                            to: call.transaction.to,
+                            data: call.transaction.data,
+                            value: (0, viem_1.numberToHex)(call.transaction.value),
+                        })),
+                    },
+                ],
+                traceTransfers: true,
+                validation: false,
+            },
+            (0, viem_1.numberToHex)(stateBlock.number),
+        ],
+    }));
+    // Response parsing is validation, not transport — it runs before the
+    // reorg re-fetch so evidence already in hand reaches the caller as
+    // InvalidSimulationResponseError / SimulationRevertedError instead of
+    // being downgraded to a bypassable ExternalServiceError by a failing
+    // re-fetch.
+    const execution = (0, parse_response_js_1.parseSimulationResponse)({
+        plan,
+        blocks: response,
+        stateBlockNumber: stateBlock.number,
+        stateBlockHash: stateBlock.hash,
+        stateBlockTimestamp: stateBlock.timestamp,
+    });
+    // Reorg window: the pinned state block must still carry the same hash
+    // after simulation, or the result may describe a different chain tip.
+    const stateBlockAfter = await (0, exports.rpc)("eth_getBlock", () => client.getBlock({ blockNumber: stateBlock.number })).catch((error) => {
+        if (error instanceof errors_js_1.ExternalServiceError &&
+            error.cause instanceof viem_1.BlockNotFoundError)
+            return error;
+        throw error;
+    });
+    if (stateBlockAfter instanceof errors_js_1.ExternalServiceError ||
+        stateBlockAfter.hash !== stateBlock.hash) {
+        const after = stateBlockAfter instanceof errors_js_1.ExternalServiceError
+            ? "unavailable"
+            : stateBlockAfter.hash;
+        throw new errors_js_1.InvalidSimulationResponseError(`State block ${stateBlock.number} hash changed during simulation (reorg): ${stateBlock.hash} became ${after}. Re-submit the simulation.`, {
+            context: {
+                stage: "transport",
+                chainId: plan.request.chainId,
+                mode: plan.request.mode,
+                blockNumber: stateBlock.number,
+            },
+            ...(stateBlockAfter instanceof errors_js_1.ExternalServiceError && {
+                cause: stateBlockAfter.cause,
+            }),
+        });
     }
-    return (0, asset_changes_js_1.groupAssetChanges)(entries);
+    return execution;
 }

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

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

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

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

package/lib/cjs/simulate/backends/parse-response.d.ts

@@ -0,0 +1,69 @@
+import { type Hex } from "viem";
+import type { SimulationCall } from "../../types.js";
+import type { ExecutionPlan, PlannedCall } from "../plan/plan-execution.js";
+import type { StateRead } from "../state/contract.js";
+/** The block coordinates a simulation was pinned to and executed under.
+ * @internal
+ */
+export interface ExecutionBlock {
+    readonly chainId: number;
+    readonly stateBlockNumber: bigint;
+    readonly stateBlockHash: Hex;
+    readonly stateBlockTimestamp: bigint;
+    readonly blockNumber: bigint;
+    readonly blockTimestamp: bigint;
+}
+/** A planned call and its normalized result. Only successful calls are carried.
+ * @internal
+ */
+interface ExecutedCall {
+    readonly planned: PlannedCall;
+    readonly result: SimulationCall;
+}
+/** One executed state read with its raw return data. @internal */
+interface ExecutedStateRead {
+    readonly phase: "before" | "after";
+    readonly read: StateRead;
+    readonly returnData: Hex;
+}
+/** The output of {@link parseSimulationResponse}: the plan, its block, successful calls and state reads.
+ * @internal
+ */
+export interface SimulationExecution {
+    readonly plan: ExecutionPlan;
+    readonly block: ExecutionBlock;
+    readonly calls: readonly ExecutedCall[];
+    /** Successful state reads, in plan order, tagged by phase. */
+    readonly stateReads: readonly ExecutedStateRead[];
+}
+/**
+ * Parse a raw `eth_simulateV1` result into a
+ * {@link SimulationExecution}.
+ *
+ * The response must be exactly one block at the pinned state block or its
+ * immediate successor. Block advancement is node-specific: geth-style nodes
+ * simulate on top of `base + 1` while Anvil reports the base block itself —
+ * this parser records whatever the node reports in {@link ExecutionBlock}
+ * and rejects any other height. Consumers must read
+ * `block.blockNumber`/`block.blockTimestamp` and never assume +1.
+ *
+ * @param params - The plan, the raw `eth_simulateV1` result, and the
+ *   resolved state block.
+ * @returns Deep-frozen execution: tagged calls plus one
+ *   {@link ExecutedStateRead} per planned state read.
+ * @throws {InvalidSimulationResponseError} When the result is not exactly one
+ *   block, on a call-count mismatch, a malformed per-call result, or on a
+ *   simulated block that is neither the pinned state block nor its immediate successor.
+ * @throws {SimulationRevertedError} When a preparation or user-transaction
+ *   call failed; the `details` payload carries tagged user call results only.
+ * @throws {MissingVerificationEvidenceError} When a planned state read fails.
+ * @internal
+ */
+export declare function parseSimulationResponse(params: {
+    readonly plan: ExecutionPlan;
+    readonly blocks: unknown;
+    readonly stateBlockNumber: bigint;
+    readonly stateBlockHash: Hex;
+    readonly stateBlockTimestamp: bigint;
+}): SimulationExecution;
+export {};

package/lib/cjs/simulate/backends/parse-response.js

@@ -0,0 +1,168 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseSimulationResponse = parseSimulationResponse;
+const morpho_ts_1 = require("@morpho-org/morpho-ts");
+const viem_1 = require("viem");
+const errors_js_1 = require("../../errors.js");
+const isQuantity = (value) => typeof value === "string" && /^0x[0-9a-fA-F]+$/.test(value);
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const readField = (object, key) => Reflect.get(object, key);
+const isSimulateV1Response = (value) => Array.isArray(value) &&
+    value.length === 1 &&
+    isObject(value[0]) &&
+    isQuantity(readField(value[0], "number")) &&
+    isQuantity(readField(value[0], "timestamp")) &&
+    (0, viem_1.isHex)(readField(value[0], "hash")) &&
+    Array.isArray(readField(value[0], "calls"));
+/**
+ * Parse a raw `eth_simulateV1` result into a
+ * {@link SimulationExecution}.
+ *
+ * The response must be exactly one block at the pinned state block or its
+ * immediate successor. Block advancement is node-specific: geth-style nodes
+ * simulate on top of `base + 1` while Anvil reports the base block itself —
+ * this parser records whatever the node reports in {@link ExecutionBlock}
+ * and rejects any other height. Consumers must read
+ * `block.blockNumber`/`block.blockTimestamp` and never assume +1.
+ *
+ * @param params - The plan, the raw `eth_simulateV1` result, and the
+ *   resolved state block.
+ * @returns Deep-frozen execution: tagged calls plus one
+ *   {@link ExecutedStateRead} per planned state read.
+ * @throws {InvalidSimulationResponseError} When the result is not exactly one
+ *   block, on a call-count mismatch, a malformed per-call result, or on a
+ *   simulated block that is neither the pinned state block nor its immediate successor.
+ * @throws {SimulationRevertedError} When a preparation or user-transaction
+ *   call failed; the `details` payload carries tagged user call results only.
+ * @throws {MissingVerificationEvidenceError} When a planned state read fails.
+ * @internal
+ */
+function parseSimulationResponse(params) {
+    const { plan, blocks } = params;
+    const errorContext = {
+        stage: "transport",
+        chainId: plan.request.chainId,
+        mode: plan.request.mode,
+        blockNumber: params.stateBlockNumber,
+    };
+    if (!isSimulateV1Response(blocks)) {
+        throw new errors_js_1.InvalidSimulationResponseError("eth_simulateV1 returned an unexpected response shape. Check that the configured endpoint implements eth_simulateV1.", { context: errorContext });
+    }
+    const block = blocks[0];
+    const blockNumber = BigInt(block.number);
+    const blockTimestamp = BigInt(block.timestamp);
+    if (blockNumber !== params.stateBlockNumber &&
+        blockNumber !== params.stateBlockNumber + 1n) {
+        throw new errors_js_1.InvalidSimulationResponseError(`eth_simulateV1 reported block ${blockNumber} but the pinned state block is ${params.stateBlockNumber}; the node did not honor the pinned block.`, { context: errorContext });
+    }
+    // Anvil re-hashes the pinned block, so only the geth-style successor can be
+    // pinned by hash: it must report a parentHash (geth always does) equal to
+    // the pinned state block hash.
+    if (blockNumber === params.stateBlockNumber + 1n &&
+        block.parentHash !== params.stateBlockHash) {
+        throw new errors_js_1.InvalidSimulationResponseError(`eth_simulateV1 reported block ${blockNumber} whose parent ${String(block.parentHash)} is not the pinned state block hash ${params.stateBlockHash}; the node did not simulate on top of the pinned block.`, { context: errorContext });
+    }
+    if (blockTimestamp < params.stateBlockTimestamp) {
+        throw new errors_js_1.InvalidSimulationResponseError(`eth_simulateV1 reported block timestamp ${blockTimestamp}, behind the pinned state block timestamp ${params.stateBlockTimestamp}. Check that the endpoint executes on top of the requested block.`, { context: errorContext });
+    }
+    if (block.calls.length !== plan.calls.length) {
+        throw new errors_js_1.InvalidSimulationResponseError(`eth_simulateV1 returned ${block.calls.length} call result(s) for ${plan.calls.length} planned call(s). Refusing to map the response with mismatched lengths.`, { context: errorContext });
+    }
+    const calls = block.calls.map((call, index) => {
+        const planned = plan.calls[index];
+        let result;
+        try {
+            if (!isObject(call) ||
+                (call.status !== "0x0" && call.status !== "0x1") ||
+                !(0, viem_1.isHex)(call.returnData) ||
+                !isQuantity(call.gasUsed) ||
+                (call.logs != null && !Array.isArray(call.logs)))
+                throw new errors_js_1.InvalidSimulationResponseError(`eth_simulateV1 returned a malformed call result at position ${index}.`, { context: errorContext });
+            result = {
+                logs: (call.logs ?? []).map((log) => {
+                    if (!(0, viem_1.isAddress)(log.address) ||
+                        !Array.isArray(log.topics) ||
+                        log.topics.some((topic) => !(0, viem_1.isHex)(topic)) ||
+                        (log.data !== undefined && !(0, viem_1.isHex)(log.data)))
+                        throw new errors_js_1.InvalidSimulationResponseError(`eth_simulateV1 returned a malformed log at call position ${index}.`, { context: errorContext });
+                    return {
+                        address: log.address,
+                        topics: log.topics,
+                        data: log.data ?? "0x",
+                    };
+                }),
+                status: call.status === "0x1",
+                returnData: call.returnData,
+                gasUsed: BigInt(call.gasUsed),
+            };
+        }
+        catch (cause) {
+            if (cause instanceof errors_js_1.InvalidSimulationResponseError)
+                throw cause;
+            throw new errors_js_1.InvalidSimulationResponseError(`eth_simulateV1 returned a malformed call result at position ${index}.`, { context: errorContext, cause });
+        }
+        return { planned, result, call };
+    });
+    // A preparation call that reverted did not produce its promised state —
+    // it is reported before user-transaction reverts it caused.
+    const failedPreparation = calls.find((entry) => entry.planned.type === "preparation" && !entry.result.status);
+    if (failedPreparation) {
+        const message = failedPreparation.call.error?.message;
+        throw new errors_js_1.SimulationRevertedError(`Authorization preparation call failed during simulation${message !== undefined ? `: ${message}` : ""}. Re-submit the bundle; if it persists, check that the endpoint executes preparation calls.`, undefined, "UNKNOWN_REVERT", {
+            stage: "preparation",
+            chainId: plan.request.chainId,
+            mode: plan.request.mode,
+            blockNumber: params.stateBlockNumber,
+            authorizationIndex: failedPreparation.planned.authorizationIndex,
+            preparationCallIndex: failedPreparation.planned.callIndex,
+        });
+    }
+    // A user-transaction revert belongs to the bundle, not the boundary.
+    const failedUserCall = calls.find(({ planned, result }) => planned.type === "transaction" && !result.status);
+    if (failedUserCall && failedUserCall.planned.type === "transaction") {
+        throw new errors_js_1.SimulationRevertedError(failedUserCall.call.error?.message ?? "Simulation failed", (0, morpho_ts_1.deepFreeze)(calls
+            .filter((entry) => entry.planned.type === "transaction")
+            .map(({ planned, result }) => ({
+            transactionIndex: planned.transactionIndex,
+            result,
+        }))), "UNKNOWN_REVERT");
+    }
+    const stateReads = [];
+    for (const { planned, result, call } of calls) {
+        if (planned.type !== "stateRead")
+            continue;
+        if (!result.status) {
+            const message = call.error?.message;
+            throw new errors_js_1.MissingVerificationEvidenceError(`State read "${planned.read.id}" failed during simulation${message !== undefined ? `: ${message}` : ""}. Re-submit the bundle; if it persists, check that the endpoint executes view calls in the same block.`, {
+                context: {
+                    stage: "verification",
+                    chainId: plan.request.chainId,
+                    mode: plan.request.mode,
+                    blockNumber: params.stateBlockNumber,
+                    field: planned.read.id,
+                },
+            });
+        }
+        stateReads.push({
+            phase: planned.phase,
+            read: planned.read,
+            returnData: call.returnData,
+        });
+    }
+    return (0, morpho_ts_1.deepFreeze)({
+        plan,
+        block: {
+            chainId: plan.request.chainId,
+            stateBlockNumber: params.stateBlockNumber,
+            stateBlockHash: params.stateBlockHash,
+            stateBlockTimestamp: params.stateBlockTimestamp,
+            blockNumber,
+            blockTimestamp,
+        },
+        // Every failure was classified above: only successful calls remain.
+        calls: calls
+            .filter((entry) => entry.result.status)
+            .map(({ planned, result }) => ({ planned, result })),
+        stateReads,
+    });
+}

package/lib/cjs/simulate/backends/resolve-assets.d.ts

@@ -0,0 +1,26 @@
+import { type Address, type Client } from "viem";
+import type { OperationLimit } from "../../limits.js";
+import type { SimulationMode } from "../../params.js";
+/** Caller-selected operation with only the quoted wallet assets resolved. @internal */
+export interface ResolvedSlippageOperation {
+    readonly limit: OperationLimit;
+    readonly assetsPaid?: Address;
+    readonly assetsReceived?: Address;
+}
+/**
+ * Resolve underlying tokens only when an asset quote lacks an explicit token.
+ * Share-only quotes need no RPC reads; vault versions and factories are not discovered.
+ * @param params - Caller operations, Morpho address, client, request context, and pinned state block.
+ * @returns Operations with the token addresses required by their asset quotes.
+ * @throws {ExternalServiceError} For transport failures during a required metadata read.
+ * @throws {MissingVerificationEvidenceError} For reverted, malformed, or empty metadata.
+ * @internal
+ */
+export declare function resolveAssets(params: {
+    readonly client: Client;
+    readonly morpho: Address;
+    readonly operations: readonly OperationLimit[];
+    readonly chainId: number;
+    readonly mode: SimulationMode;
+    readonly blockNumber: bigint;
+}): Promise<readonly ResolvedSlippageOperation[]>;