@morpho-org/evm-simulation 4.2.0 → 5.0.0

package/lib/esm/simulate/backends/resolve-assets.js

@@ -0,0 +1,108 @@
+import { blueAbi } from "@morpho-org/morpho-sdk/abis";
+import { BaseError, ContractFunctionRevertedError, ExecutionRevertedError, erc4626Abi, HttpRequestError, isAddressEqual, RpcError, RpcRequestError, TimeoutError, zeroAddress, } from "viem";
+import { readContract } from "viem/actions";
+import { ExternalServiceError, MissingVerificationEvidenceError, } from "../../errors.js";
+import { operationMeasurementPlan } from "../measurement-plan.js";
+/**
+ * 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 async function resolveAssets(params) {
+    const { client, morpho, operations, chainId, mode, blockNumber } = params;
+    const tokens = new Map();
+    const resolved = [];
+    for (const limit of operations) {
+        const plan = operationMeasurementPlan(limit);
+        const result = { limit };
+        for (const field of ["assetsPaid", "assetsReceived"]) {
+            if (limit.quote[field] === undefined)
+                continue;
+            const explicit = field === "assetsPaid" ? limit.assetPaid : limit.assetReceived;
+            if (explicit !== undefined) {
+                result[field] = explicit;
+                continue;
+            }
+            const source = plan[field];
+            const key = source.type === "market"
+                ? `market:${source.marketId.toLowerCase()}`
+                : `vault:${source.vault.toLowerCase()}`;
+            let pair = tokens.get(key);
+            if (pair === undefined) {
+                try {
+                    if (source.type === "market") {
+                        const values = await readContract(client, {
+                            address: morpho,
+                            abi: blueAbi,
+                            functionName: "idToMarketParams",
+                            args: [source.marketId],
+                            blockNumber,
+                        });
+                        pair = [values[0], values[1]];
+                    }
+                    else {
+                        const asset = await readContract(client, {
+                            address: source.vault,
+                            abi: erc4626Abi,
+                            functionName: "asset",
+                            blockNumber,
+                        });
+                        pair = [asset, asset];
+                    }
+                }
+                catch (cause) {
+                    const reverted = cause instanceof BaseError &&
+                        cause.walk((error) => error instanceof ContractFunctionRevertedError ||
+                            error instanceof ExecutionRevertedError) !== null;
+                    // Revert-shaped chains (code 3, or -32000 "execution reverted")
+                    // can nest an RpcRequestError, so a revert must win over the
+                    // transport match.
+                    if (!reverted &&
+                        ((cause instanceof BaseError &&
+                            cause.walk((error) => error instanceof HttpRequestError ||
+                                error instanceof TimeoutError ||
+                                error instanceof RpcRequestError ||
+                                error instanceof RpcError ||
+                                (error instanceof Error && error.name === "AbortError")) !== null) ||
+                            (cause instanceof Error && cause.name === "AbortError"))) {
+                        throw new ExternalServiceError("Cannot resolve the quoted asset because its metadata request failed. Check the RPC endpoint.", { cause });
+                    }
+                    throw new MissingVerificationEvidenceError(`Cannot resolve verification evidence for "${limit.type}" asset source "${key}".`, {
+                        cause,
+                        context: {
+                            stage: "verification",
+                            chainId,
+                            mode,
+                            blockNumber,
+                            ...plan.subject,
+                            field,
+                        },
+                    });
+                }
+                tokens.set(key, pair);
+            }
+            const token = source.type === "market"
+                ? pair[source.asset === "loan" ? 0 : 1]
+                : pair[0];
+            if (isAddressEqual(token, zeroAddress)) {
+                throw new MissingVerificationEvidenceError(`Cannot resolve verification evidence for "${limit.type}" asset source "${key}": the resolved token address is zero.`, {
+                    context: {
+                        stage: "verification",
+                        chainId,
+                        mode,
+                        blockNumber,
+                        ...plan.subject,
+                        field,
+                    },
+                });
+            }
+            result[field] = token;
+        }
+        resolved.push(result);
+    }
+    return resolved;
+}

package/lib/esm/simulate/backends/resolve-pinned-block.d.ts

@@ -0,0 +1,33 @@
+import type { BlockTag, Client, Hex } from "viem";
+/** One concrete canonical block: the state anchor for every pinned read. @internal */
+export interface PinnedBlock {
+    readonly number: bigint;
+    readonly hash: Hex;
+    readonly timestamp: bigint;
+}
+/**
+ * Resolve the requested state block exactly once so `latest` cannot drift.
+ *
+ * Every downstream read and the `eth_simulateV1` call pin this number; the
+ * execution boundary re-fetches the hash afterwards to detect a reorg that
+ * swapped the block mid-flight.
+ *
+ * @param params - Resolution parameters.
+ * @param params.client - Shared simulation client (created by
+ *   {@link createSimulationClient}).
+ * @param params.blockNumber - Requested block number or tag; defaults to
+ *   `latest`.
+ * @param params.signal - Optional pipeline abort signal; checked around the
+ *   request so an aborted pipeline never produces a pin.
+ * @returns The resolved {@link PinnedBlock}.
+ * @throws {ExternalServiceError} For transport failures, timeouts, or an
+ *   aborted signal.
+ * @throws {InvalidSimulationResponseError} When the node returns a block
+ *   without a number or hash.
+ * @internal
+ */
+export declare function resolvePinnedBlock(params: {
+    readonly client: Client;
+    readonly blockNumber?: bigint | BlockTag;
+    readonly signal?: AbortSignal;
+}): Promise<PinnedBlock>;

package/lib/esm/simulate/backends/resolve-pinned-block.js

@@ -0,0 +1,43 @@
+import { getBlock } from "viem/actions";
+import { InvalidSimulationResponseError } from "../../errors.js";
+import { rpc } from "./eth-simulate-v1.js";
+/**
+ * Resolve the requested state block exactly once so `latest` cannot drift.
+ *
+ * Every downstream read and the `eth_simulateV1` call pin this number; the
+ * execution boundary re-fetches the hash afterwards to detect a reorg that
+ * swapped the block mid-flight.
+ *
+ * @param params - Resolution parameters.
+ * @param params.client - Shared simulation client (created by
+ *   {@link createSimulationClient}).
+ * @param params.blockNumber - Requested block number or tag; defaults to
+ *   `latest`.
+ * @param params.signal - Optional pipeline abort signal; checked around the
+ *   request so an aborted pipeline never produces a pin.
+ * @returns The resolved {@link PinnedBlock}.
+ * @throws {ExternalServiceError} For transport failures, timeouts, or an
+ *   aborted signal.
+ * @throws {InvalidSimulationResponseError} When the node returns a block
+ *   without a number or hash.
+ * @internal
+ */
+export async function resolvePinnedBlock(params) {
+    const { client, blockNumber, signal } = params;
+    const block = await rpc("eth_getBlock", async () => {
+        signal?.throwIfAborted();
+        const resolved = await getBlock(client, typeof blockNumber === "bigint"
+            ? { blockNumber }
+            : { blockTag: blockNumber ?? "latest" });
+        signal?.throwIfAborted();
+        return resolved;
+    });
+    if (block.number === null || block.hash === null) {
+        throw new InvalidSimulationResponseError("eth_getBlock returned a block without number or hash. Check that the endpoint resolved the requested state block.");
+    }
+    return {
+        number: block.number,
+        hash: block.hash,
+        timestamp: block.timestamp,
+    };
+}

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

@@ -0,0 +1,14 @@
+import type { Address } from "viem";
+import type { OperationLimit } from "../limits.js";
+import type { SimulationMode } from "../params.js";
+import type { ExecutionBlock } from "./backends/parse-response.js";
+/** Explicit simulation context shared by the checker and result assembly. @internal */
+export interface CheckContext {
+    readonly chainId: number;
+    readonly mode: SimulationMode;
+    readonly block: ExecutionBlock;
+    readonly owner: Address;
+    readonly limits: {
+        readonly operations: readonly OperationLimit[];
+    };
+}

package/lib/esm/simulate/context.js

@@ -0,0 +1 @@
+export {};

package/lib/esm/simulate/measurement-plan.d.ts

@@ -0,0 +1,29 @@
+import type { MarketId } from "@morpho-org/blue-sdk";
+import type { Address } from "viem";
+import type { OperationLimit, SimulationOperationSubject } from "../limits.js";
+type AssetMeasurementSource = {
+    readonly type: "market";
+    readonly marketId: MarketId;
+    readonly asset: "loan" | "collateral";
+} | {
+    readonly type: "vault";
+    readonly vault: Address;
+};
+type ShareMeasurementSource = {
+    readonly type: "position";
+    readonly marketId: MarketId;
+    readonly shares: "supplyShares" | "borrowShares";
+} | {
+    readonly type: "balance";
+    readonly token: Address;
+};
+interface OperationMeasurementPlan {
+    readonly subject: SimulationOperationSubject;
+    readonly assetsPaid: AssetMeasurementSource;
+    readonly assetsReceived: AssetMeasurementSource;
+    readonly sharesMinted?: ShareMeasurementSource;
+    readonly sharesBurned?: ShareMeasurementSource;
+}
+/** Describe each quote field's evidence source with an exhaustive operation switch. @internal */
+export declare function operationMeasurementPlan(limit: OperationLimit): OperationMeasurementPlan;
+export {};

package/lib/esm/simulate/measurement-plan.js

@@ -0,0 +1,112 @@
+const market = (marketId, asset) => ({ type: "market", marketId, asset });
+const position = (marketId, shares) => ({ type: "position", marketId, shares });
+const balance = (token) => ({
+    type: "balance",
+    token,
+});
+const vault = (address) => ({
+    type: "vault",
+    vault: address,
+});
+/** Describe each quote field's evidence source with an exhaustive operation switch. @internal */
+export function operationMeasurementPlan(limit) {
+    switch (limit.type) {
+        case "blueSupply":
+        case "blueWithdraw": {
+            const shares = position(limit.marketId, "supplyShares");
+            return {
+                subject: { operation: limit.type, marketId: limit.marketId },
+                assetsPaid: market(limit.marketId, "loan"),
+                assetsReceived: market(limit.marketId, "loan"),
+                sharesMinted: shares,
+                sharesBurned: shares,
+            };
+        }
+        case "blueSupplyCollateral":
+        case "blueWithdrawCollateral":
+            return {
+                subject: { operation: limit.type, marketId: limit.marketId },
+                assetsPaid: market(limit.marketId, "collateral"),
+                assetsReceived: market(limit.marketId, "collateral"),
+            };
+        case "blueBorrow":
+        case "blueRepay": {
+            const shares = position(limit.marketId, "borrowShares");
+            return {
+                subject: { operation: limit.type, marketId: limit.marketId },
+                assetsPaid: market(limit.marketId, "loan"),
+                assetsReceived: market(limit.marketId, "loan"),
+                sharesMinted: shares,
+                sharesBurned: shares,
+            };
+        }
+        case "blueSupplyCollateralBorrow": {
+            const shares = position(limit.marketId, "borrowShares");
+            return {
+                subject: { operation: limit.type, marketId: limit.marketId },
+                assetsPaid: market(limit.marketId, "collateral"),
+                assetsReceived: market(limit.marketId, "loan"),
+                sharesMinted: shares,
+                sharesBurned: shares,
+            };
+        }
+        case "blueRepayWithdrawCollateral": {
+            const shares = position(limit.marketId, "borrowShares");
+            return {
+                subject: { operation: limit.type, marketId: limit.marketId },
+                assetsPaid: market(limit.marketId, "loan"),
+                assetsReceived: market(limit.marketId, "collateral"),
+                sharesMinted: shares,
+                sharesBurned: shares,
+            };
+        }
+        case "blueRefinance":
+            return {
+                subject: {
+                    operation: limit.type,
+                    sourceMarketId: limit.sourceMarketId,
+                    targetMarketId: limit.targetMarketId,
+                },
+                assetsPaid: market(limit.sourceMarketId, "loan"),
+                assetsReceived: market(limit.sourceMarketId, "loan"),
+                sharesMinted: position(limit.targetMarketId, "borrowShares"),
+                sharesBurned: position(limit.sourceMarketId, "borrowShares"),
+            };
+        case "vaultV1Deposit":
+        case "vaultV2Deposit":
+        case "vaultV1Withdraw":
+        case "vaultV2Withdraw":
+        case "vaultV1Redeem":
+        case "vaultV2Redeem":
+        case "vaultV2ForceWithdraw":
+        case "vaultV2ForceRedeem":
+        case "vaultV1InKindRedeem":
+        case "vaultV2InKindRedeem":
+            return {
+                subject: {
+                    operation: limit.type,
+                    vault: limit.vault,
+                },
+                assetsPaid: vault(limit.vault),
+                assetsReceived: vault(limit.vault),
+                sharesMinted: balance(limit.vault),
+                sharesBurned: balance(limit.vault),
+            };
+        case "vaultV1MigrateToV2":
+            return {
+                subject: {
+                    operation: limit.type,
+                    sourceVault: limit.sourceVault,
+                    targetVault: limit.targetVault,
+                },
+                assetsPaid: vault(limit.sourceVault),
+                assetsReceived: vault(limit.sourceVault),
+                sharesMinted: balance(limit.targetVault),
+                sharesBurned: balance(limit.sourceVault),
+            };
+        default: {
+            const exhaustive = limit;
+            return exhaustive;
+        }
+    }
+}

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

@@ -1,7 +1,10 @@
 import { type Address } from "viem";
 import type { RawCall, SimulationLogger, Transfer } from "../../types.js";
+/** `keccak256("Transfer(address,address,uint256)")` — ERC-20 Transfer event topic. @internal */
 export declare const TRANSFER_TOPIC = "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef";
+/** `keccak256("Withdrawal(address,uint256)")` — WETH9 Withdrawal event topic. @internal */
 export declare const WITHDRAWAL_TOPIC = "0x7fcf532c15f0a6db0bd6d0e038bea71d30d808c7d98cb3bf7268a95bf5081b65";
+/** `keccak256("Deposit(address,uint256)")` — WETH9 Deposit event topic. @internal */
 export declare const DEPOSIT_TOPIC = "0xe1fffcc4923d04b559f4d29a8bfc6cda04eb5b0d3c460751c2402c5c5cc9109c";
 /**
  * Parse raw EVM logs into individual Transfer events.
@@ -23,9 +26,7 @@ export declare const DEPOSIT_TOPIC = "0xe1fffcc4923d04b559f4d29a8bfc6cda04eb5b0d
  * those made through internal calls (e.g. a `WETH.withdraw` refund) — are
  * synthesized as `Transfer` events emitted from the native sentinel
  * `0xeee…eee`. These are parsed like any ERC20 transfer, with `token`
- * collapsed to viem's `ethAddress` so native deltas key consistently across
- * backends. Tenderly does not emit these synthetic logs (it derives native ETH
- * separately), so this path is inert there.
+ * collapsed to viem's `ethAddress` so native deltas key consistently.
  *
  * **WETH9 dedup assumption — canonical atomic emission.** Dedup for the
  * registered wrapped-native token is scoped to the same tx: a zero-address

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

@@ -1,10 +1,10 @@
 import { getAddress, isAddressEqual, zeroAddress, zeroHash, } from "viem";
 import { normalizeAssetToken } from "../asset-changes.js";
-// keccak256("Transfer(address,address,uint256)") — ERC-20 transfer event
+/** `keccak256("Transfer(address,address,uint256)")` — ERC-20 Transfer event topic. @internal */
 export const TRANSFER_TOPIC = "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef";
-// keccak256("Withdrawal(address,uint256)") — WETH9 unwrap event
+/** `keccak256("Withdrawal(address,uint256)")` — WETH9 Withdrawal event topic. @internal */
 export const WITHDRAWAL_TOPIC = "0x7fcf532c15f0a6db0bd6d0e038bea71d30d808c7d98cb3bf7268a95bf5081b65";
-// keccak256("Deposit(address,uint256)") — WETH9 wrap event
+/** `keccak256("Deposit(address,uint256)")` — WETH9 Deposit event topic. @internal */
 export const DEPOSIT_TOPIC = "0xe1fffcc4923d04b559f4d29a8bfc6cda04eb5b0d3c460751c2402c5c5cc9109c";
 const TOPIC_HEX_LENGTH = 66; // "0x" + 32 bytes
 const UINT256_HEX_LENGTH = 66; // "0x" + 32 bytes
@@ -28,9 +28,7 @@ const UINT256_HEX_LENGTH = 66; // "0x" + 32 bytes
  * those made through internal calls (e.g. a `WETH.withdraw` refund) — are
  * synthesized as `Transfer` events emitted from the native sentinel
  * `0xeee…eee`. These are parsed like any ERC20 transfer, with `token`
- * collapsed to viem's `ethAddress` so native deltas key consistently across
- * backends. Tenderly does not emit these synthetic logs (it derives native ETH
- * separately), so this path is inert there.
+ * collapsed to viem's `ethAddress` so native deltas key consistently.
  *
  * **WETH9 dedup assumption — canonical atomic emission.** Dedup for the
  * registered wrapped-native token is scoped to the same tx: a zero-address

package/lib/esm/simulate/pipeline/bundles-retention.d.ts

@@ -20,14 +20,11 @@ interface AssertNoBundlesRetentionParams {
  * violation.
  *
  * **Two flow sources, one per asset class.** ERC20 / WETH9 retention is read
- * from parsed `transfers` (log-derived, identical across backends). Native ETH
- * emits no event log, so it can never appear in `transfers` on the Tenderly
- * primary backend — Tenderly derives native moves into `assetChanges` instead.
- * Native ETH is therefore read from `assetChanges`, the cross-backend source of
- * truth for native value: Tenderly derives it from its trace, and
- * `eth_simulateV1` derives it from the synthetic `traceTransfers` logs. Without
- * this, native ETH stuck in a bundles contract would pass the guard undetected
- * on the Tenderly path (Cantina finding 1440).
+ * from parsed `transfers` (log-derived). Native ETH emits no event log of its
+ * own, so it is read from `assetChanges`, the source of truth for native value,
+ * which `eth_simulateV1` derives from the synthetic `traceTransfers` logs.
+ * Without this, native ETH stuck in a bundles contract would pass the guard
+ * undetected (Cantina finding 1440).
  *
  * To avoid double-counting native ETH on `eth_simulateV1` — where the same
  * native move exists both as a synthetic `ethAddress` transfer log *and* in the
@@ -41,8 +38,8 @@ interface AssertNoBundlesRetentionParams {
  *   neither are skipped (a `logger.warn` records the skip).
  * @param params.transfers - Parsed ERC20 / WETH9 transfer flows (plus the
  *   `eth_simulateV1` synthetic native sentinel) scanned for net retention.
- * @param params.assetChanges - Per-account native-ETH deltas, the cross-backend
- *   source of truth for native value stuck in a restricted contract.
+ * @param params.assetChanges - Per-account native-ETH deltas, the source of
+ *   truth for native value stuck in a restricted contract.
  * @param params.logger - Optional logger. Receives retention-check skip warnings
  *   and pre-existing-balance sweep telemetry (net-negative flow).
  * @returns Nothing. Returns silently when no restricted contract retains value

package/lib/esm/simulate/pipeline/bundles-retention.js

@@ -27,14 +27,11 @@ const DUST_THRESHOLD = 100n;
  * violation.
  *
  * **Two flow sources, one per asset class.** ERC20 / WETH9 retention is read
- * from parsed `transfers` (log-derived, identical across backends). Native ETH
- * emits no event log, so it can never appear in `transfers` on the Tenderly
- * primary backend — Tenderly derives native moves into `assetChanges` instead.
- * Native ETH is therefore read from `assetChanges`, the cross-backend source of
- * truth for native value: Tenderly derives it from its trace, and
- * `eth_simulateV1` derives it from the synthetic `traceTransfers` logs. Without
- * this, native ETH stuck in a bundles contract would pass the guard undetected
- * on the Tenderly path (Cantina finding 1440).
+ * from parsed `transfers` (log-derived). Native ETH emits no event log of its
+ * own, so it is read from `assetChanges`, the source of truth for native value,
+ * which `eth_simulateV1` derives from the synthetic `traceTransfers` logs.
+ * Without this, native ETH stuck in a bundles contract would pass the guard
+ * undetected (Cantina finding 1440).
  *
  * To avoid double-counting native ETH on `eth_simulateV1` — where the same
  * native move exists both as a synthetic `ethAddress` transfer log *and* in the
@@ -48,8 +45,8 @@ const DUST_THRESHOLD = 100n;
  *   neither are skipped (a `logger.warn` records the skip).
  * @param params.transfers - Parsed ERC20 / WETH9 transfer flows (plus the
  *   `eth_simulateV1` synthetic native sentinel) scanned for net retention.
- * @param params.assetChanges - Per-account native-ETH deltas, the cross-backend
- *   source of truth for native value stuck in a restricted contract.
+ * @param params.assetChanges - Per-account native-ETH deltas, the source of
+ *   truth for native value stuck in a restricted contract.
  * @param params.logger - Optional logger. Receives retention-check skip warnings
  *   and pre-existing-balance sweep telemetry (net-negative flow).
  * @returns Nothing. Returns silently when no restricted contract retains value
@@ -104,9 +101,9 @@ export function assertNoBundlesRetention(params) {
             flow.set(key, { address, token, netChange: delta });
         }
     };
-    // Native ETH from `assetChanges` (authoritative, cross-backend). Track which
-    // restricted contracts already have a native entry here so the transfer-log
-    // pass below does not re-add the same native move on `eth_simulateV1`.
+    // Native ETH from `assetChanges` (authoritative). Track which restricted
+    // contracts already have a native entry here so the transfer-log pass below
+    // does not re-add the same native move on `eth_simulateV1`.
     const nativeFromAssetChanges = new Set();
     for (const { account, changes } of assetChanges) {
         if (!restrictedAddresses.has(account))
@@ -145,7 +142,7 @@ export function assertNoBundlesRetention(params) {
         throw new BlacklistViolationError("Simulation detected asset transfers retained by restricted bundles contracts", retained.map((e) => ({
             address: e.address,
             token: e.token,
-            netRetained: e.netChange.toString(),
+            netRetained: e.netChange,
         })));
     }
 }

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

@@ -1,15 +1,9 @@
-import type { SimulationConfig, TenderlyRpcConfig } from "../../types.js";
-interface ChainCapability {
-    tenderlyRpc?: TenderlyRpcConfig;
-    simulateV1Url?: string;
-}
+import type { ChainSimulationConfig, SimulationConfig } from "../../types.js";
 /**
  * Stage 2 of the simulate() pipeline.
  *
- * Looks up the per-chain `ChainSimulationConfig` and exposes whichever
- * backends were configured. Throws `UnsupportedChainError` when the chain is
- * absent from the map or has neither backend wired (defensive — the type
- * already enforces at least one at construction).
+ * Looks up the per-chain `ChainSimulationConfig`. Throws `UnsupportedChainError`
+ * when the chain is absent from the map or has no `simulateV1Url` (defensive —
+ * the type already requires it at construction).
  */
-export declare function resolveChain(config: SimulationConfig, chainId: number): ChainCapability;
-export {};
+export declare function resolveChain(config: SimulationConfig, chainId: number): ChainSimulationConfig;

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

@@ -2,18 +2,13 @@ import { UnsupportedChainError } from "../../errors.js";
 /**
  * Stage 2 of the simulate() pipeline.
  *
- * Looks up the per-chain `ChainSimulationConfig` and exposes whichever
- * backends were configured. Throws `UnsupportedChainError` when the chain is
- * absent from the map or has neither backend wired (defensive — the type
- * already enforces at least one at construction).
+ * Looks up the per-chain `ChainSimulationConfig`. Throws `UnsupportedChainError`
+ * when the chain is absent from the map or has no `simulateV1Url` (defensive —
+ * the type already requires it at construction).
  */
 export function resolveChain(config, chainId) {
     const entry = config.chains.get(chainId);
-    if (!entry || (!entry.tenderlyRpc && !entry.simulateV1Url)) {
+    if (!entry?.simulateV1Url)
         throw new UnsupportedChainError(chainId);
-    }
-    return {
-        tenderlyRpc: entry.tenderlyRpc,
-        simulateV1Url: entry.simulateV1Url,
-    };
+    return entry;
 }

package/lib/esm/simulate/plan/plan-execution.d.ts

@@ -0,0 +1,58 @@
+import type { Address } from "viem";
+import type { SimulationTransaction } from "../../types.js";
+import type { ParsedRequest } from "../request/parse-request.js";
+import type { ReadPhase, StateRead } from "../state/contract.js";
+/** One call planned inside the single `eth_simulateV1` run. @internal */
+export type PlannedCall = {
+    /** What the call carries on the wire. */
+    readonly transaction: SimulationTransaction & {
+        readonly value: bigint;
+    };
+} & ({
+    /** A caller transaction. */
+    readonly type: "transaction";
+    readonly transactionIndex: number;
+} | {
+    /** A preview-authorization preparation call. */
+    readonly type: "preparation";
+    readonly authorizationIndex: number;
+    readonly callIndex: number;
+} | {
+    /** A state read-back call at the `before`/`after` phase. */
+    readonly type: "stateRead";
+    readonly phase: ReadPhase;
+    readonly read: StateRead;
+});
+/** The ordered call plan for one simulation. @internal */
+export interface ExecutionPlan {
+    readonly request: ParsedRequest;
+    readonly calls: readonly PlannedCall[];
+}
+/**
+ * Plan the execution of a request as ordered `eth_simulateV1` calls.
+ *
+ * Sequence (design §plan order): every `before` state read → preparation
+ * calls → every user transaction → every `after` state read.
+ *
+ * Preparation calls run `from` the owner; state reads run `from`
+ * `zeroAddress` and never receive a public `txIdx`.
+ *
+ * @param request - The parsed request.
+ * @param owner - The bundle owner; sender of preparation calls.
+ * @param preparations - Ordered authorization preparations to simulate.
+ * @param reads - The full state-read list, replayed at `before` and `after`.
+ * @returns A deep-frozen {@link ExecutionPlan}; pure — equal inputs produce
+ *   structurally equal plans.
+ * @internal
+ */
+export declare function planExecution(params: {
+    readonly request: ParsedRequest;
+    readonly owner: Address;
+    readonly preparations: readonly {
+        readonly authorizationIndex: number;
+        readonly calls: readonly (SimulationTransaction & {
+            readonly value: bigint;
+        })[];
+    }[];
+    readonly reads: readonly StateRead[];
+}): ExecutionPlan;

package/lib/esm/simulate/plan/plan-execution.js

@@ -0,0 +1,72 @@
+import { deepFreeze } from "@morpho-org/morpho-ts";
+import { zeroAddress } from "viem";
+/**
+ * Plan the execution of a request as ordered `eth_simulateV1` calls.
+ *
+ * Sequence (design §plan order): every `before` state read → preparation
+ * calls → every user transaction → every `after` state read.
+ *
+ * Preparation calls run `from` the owner; state reads run `from`
+ * `zeroAddress` and never receive a public `txIdx`.
+ *
+ * @param request - The parsed request.
+ * @param owner - The bundle owner; sender of preparation calls.
+ * @param preparations - Ordered authorization preparations to simulate.
+ * @param reads - The full state-read list, replayed at `before` and `after`.
+ * @returns A deep-frozen {@link ExecutionPlan}; pure — equal inputs produce
+ *   structurally equal plans.
+ * @internal
+ */
+export function planExecution(params) {
+    const { request, owner, preparations, reads } = params;
+    const calls = [];
+    for (const read of reads) {
+        calls.push({
+            type: "stateRead",
+            phase: "before",
+            read,
+            transaction: {
+                from: zeroAddress,
+                to: read.to,
+                data: read.data,
+                value: 0n,
+            },
+        });
+    }
+    for (const preparation of preparations) {
+        preparation.calls.forEach((transaction, callIndex) => {
+            calls.push({
+                type: "preparation",
+                authorizationIndex: preparation.authorizationIndex,
+                callIndex,
+                transaction: { ...transaction, from: owner },
+            });
+        });
+    }
+    request.transactions.forEach((transaction, i) => {
+        calls.push({
+            type: "transaction",
+            transactionIndex: i,
+            transaction: {
+                from: transaction.from,
+                to: transaction.to,
+                data: transaction.data,
+                value: transaction.value ?? 0n,
+            },
+        });
+    });
+    for (const read of reads) {
+        calls.push({
+            type: "stateRead",
+            phase: "after",
+            read,
+            transaction: {
+                from: zeroAddress,
+                to: read.to,
+                data: read.data,
+                value: 0n,
+            },
+        });
+    }
+    return deepFreeze({ request, calls });
+}