@morpho-org/evm-simulation 4.2.1 → 5.0.1

package/lib/esm/limits.d.ts

@@ -0,0 +1,112 @@
+import type { MarketId } from "@morpho-org/blue-sdk";
+import type { Address } from "viem";
+/** Every operation type; source of `OperationType`. */
+export declare const OPERATION_TYPES: readonly ["blueSupply", "blueWithdraw", "blueSupplyCollateral", "blueBorrow", "blueSupplyCollateralBorrow", "blueRepay", "blueWithdrawCollateral", "blueRepayWithdrawCollateral", "blueRefinance", "vaultV1Deposit", "vaultV2Deposit", "vaultV1Withdraw", "vaultV2Withdraw", "vaultV1Redeem", "vaultV2Redeem", "vaultV2ForceWithdraw", "vaultV2ForceRedeem", "vaultV1InKindRedeem", "vaultV2InKindRedeem", "vaultV1MigrateToV2"];
+/** Discriminator for operations and their limits. */
+export type OperationType = (typeof OPERATION_TYPES)[number];
+/** Operations acting on one Blue market; source of `BlueMarketOperationType`. */
+export declare const BLUE_MARKET_OPERATION_TYPES: readonly ["blueSupply", "blueWithdraw", "blueSupplyCollateral", "blueBorrow", "blueSupplyCollateralBorrow", "blueRepay", "blueWithdrawCollateral", "blueRepayWithdrawCollateral"];
+/** Operations acting on one Blue market. */
+export type BlueMarketOperationType = (typeof BLUE_MARKET_OPERATION_TYPES)[number];
+/** Operations acting on one vault (V1 or V2); source of `VaultOperationType`. */
+export declare const VAULT_OPERATION_TYPES: readonly ["vaultV1Deposit", "vaultV2Deposit", "vaultV1Withdraw", "vaultV2Withdraw", "vaultV1Redeem", "vaultV2Redeem", "vaultV2ForceWithdraw", "vaultV2ForceRedeem", "vaultV1InKindRedeem", "vaultV2InKindRedeem"];
+/** Operations acting on one vault (V1 or V2). */
+export type VaultOperationType = (typeof VAULT_OPERATION_TYPES)[number];
+/** Subject of an operation acting on one Blue market. */
+export interface BlueMarketOperationSubject {
+    readonly operation: BlueMarketOperationType;
+    /** Blue market the operation acts on. */
+    readonly marketId: MarketId;
+}
+/** Subject of a Blue refinance between two markets. */
+export interface BlueRefinanceSubject {
+    readonly operation: "blueRefinance";
+    /** Market the refinance closes. */
+    readonly sourceMarketId: MarketId;
+    /** Market the refinance opens. */
+    readonly targetMarketId: MarketId;
+}
+/** Subject of an operation acting on one vault (V1 or V2). */
+export interface VaultOperationSubject {
+    readonly operation: VaultOperationType;
+    /** Vault the operation acts on. */
+    readonly vault: Address;
+}
+/** Subject of a Vault V1 → V2 migration. */
+export interface VaultV1MigrateToV2Subject {
+    readonly operation: "vaultV1MigrateToV2";
+    /** Vault the migration exits. */
+    readonly sourceVault: Address;
+    /** Vault the migration enters. */
+    readonly targetVault: Address;
+}
+/** Protocol entity a limit's operation acts on, keyed by `operation`; shared by `SimulatedOperation` and the verification error context. */
+export type SimulationOperationSubject = BlueMarketOperationSubject | BlueRefinanceSubject | VaultOperationSubject | VaultV1MigrateToV2Subject;
+/** Caller-quoted net amounts in raw units over the whole bundle.
+ * Supply at least one amount. Unquoted amounts are not checked.
+ */
+export interface SlippageQuote {
+    /**
+     * Expected net assets credited to the receiver. For in-kind vault redemptions,
+     * this measures only the wallet balance of the vault asset, not Morpho positions.
+     */
+    readonly assetsReceived?: bigint;
+    /**
+     * Expected net shares added to the position. For debt shares, this is a
+     * maximum: minting more debt shares than quoted is adverse.
+     */
+    readonly sharesMinted?: bigint;
+    /** Expected net assets debited from the sender. */
+    readonly assetsPaid?: bigint;
+    /**
+     * Expected net shares removed from the position. For debt shares, this is a
+     * minimum: burning fewer debt shares than quoted is adverse.
+     */
+    readonly sharesBurned?: bigint;
+}
+/** Caller quote and permitted adverse percentage deviation. */
+export interface SlippageLimits {
+    readonly quote: SlippageQuote;
+    /** WAD-scaled fraction from 0 to 1e18 inclusive; 1e16 means 1%. No default. */
+    readonly slippageTolerance: bigint;
+}
+/** Caller-selected action and subject with the same quote/tolerance shape for every action.
+ * Measurements cover the entire bundle for the named subject, never an inferred
+ * individual transaction. Use separate simulations for per-transaction bounds.
+ */
+export type OperationLimit = SlippageLimits & {
+    /** Position/share owner; defaults to the transaction sender. */
+    readonly account?: Address;
+    /**
+     * Explicit asset paid; defaults to the action underlying. Use viem's
+     * `ethAddress` (`0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE`) for native ETH;
+     * sentinels such as `zeroAddress` are read as ERC-20 tokens.
+     */
+    readonly assetPaid?: Address;
+    /**
+     * Explicit asset received; defaults to the action underlying. Use viem's
+     * `ethAddress` (`0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE`) for native ETH;
+     * sentinels such as `zeroAddress` are read as ERC-20 tokens.
+     */
+    readonly assetReceived?: Address;
+    /** Asset receiver; defaults to the transaction sender. */
+    readonly receiver?: Address;
+} & ({
+    readonly type: BlueMarketOperationType;
+    readonly marketId: MarketId;
+} | {
+    readonly type: "blueRefinance";
+    readonly sourceMarketId: MarketId;
+    readonly targetMarketId: MarketId;
+} | {
+    readonly type: VaultOperationType;
+    readonly vault: Address;
+} | {
+    readonly type: "vaultV1MigrateToV2";
+    readonly sourceVault: Address;
+    readonly targetVault: Address;
+});
+/** Optional caller-selected checks. No action discovery or default bounds. */
+export interface SimulationLimits {
+    readonly operations?: readonly OperationLimit[];
+}

package/lib/esm/limits.js

@@ -0,0 +1,47 @@
+/** Every operation type; source of `OperationType`. */
+export const OPERATION_TYPES = [
+    "blueSupply",
+    "blueWithdraw",
+    "blueSupplyCollateral",
+    "blueBorrow",
+    "blueSupplyCollateralBorrow",
+    "blueRepay",
+    "blueWithdrawCollateral",
+    "blueRepayWithdrawCollateral",
+    "blueRefinance",
+    "vaultV1Deposit",
+    "vaultV2Deposit",
+    "vaultV1Withdraw",
+    "vaultV2Withdraw",
+    "vaultV1Redeem",
+    "vaultV2Redeem",
+    "vaultV2ForceWithdraw",
+    "vaultV2ForceRedeem",
+    "vaultV1InKindRedeem",
+    "vaultV2InKindRedeem",
+    "vaultV1MigrateToV2",
+];
+/** Operations acting on one Blue market; source of `BlueMarketOperationType`. */
+export const BLUE_MARKET_OPERATION_TYPES = [
+    "blueSupply",
+    "blueWithdraw",
+    "blueSupplyCollateral",
+    "blueBorrow",
+    "blueSupplyCollateralBorrow",
+    "blueRepay",
+    "blueWithdrawCollateral",
+    "blueRepayWithdrawCollateral",
+];
+/** Operations acting on one vault (V1 or V2); source of `VaultOperationType`. */
+export const VAULT_OPERATION_TYPES = [
+    "vaultV1Deposit",
+    "vaultV2Deposit",
+    "vaultV1Withdraw",
+    "vaultV2Withdraw",
+    "vaultV1Redeem",
+    "vaultV2Redeem",
+    "vaultV2ForceWithdraw",
+    "vaultV2ForceRedeem",
+    "vaultV1InKindRedeem",
+    "vaultV2InKindRedeem",
+];

package/lib/esm/params.d.ts

@@ -0,0 +1,26 @@
+import type { BlockTag } from "viem";
+import type { SimulationAuthorization } from "./authorizations.js";
+import type { SimulationLimits } from "./limits.js";
+import type { SimulationTransaction } from "./types.js";
+/** Every simulation mode; source of `SimulationMode`. */
+export declare const SIMULATION_MODES: readonly ["preview", "final"];
+/** Simulation mode: `"preview"` accepts pending authorizations, `"final"` does not. */
+export type SimulationMode = (typeof SIMULATION_MODES)[number];
+/**
+ * Input to `simulate()`. `authorizations` is accepted only in "preview";
+ * `mode` defaults to "final".
+ */
+export interface SimulateParams {
+    readonly chainId: number;
+    readonly transactions: readonly SimulationTransaction[];
+    /** Defaults to "final". */
+    readonly mode?: SimulationMode;
+    /** Pending wallet requests, in order. Preview only; rejected in final. */
+    readonly authorizations?: readonly SimulationAuthorization[];
+    /** Resolved once; defaults to "latest" ("finalized" on Monad, whose
+     * "latest" block is not final). Only canonical (mined) blocks can be
+     * pinned; `pending` has no stable hash and is rejected at runtime. */
+    readonly blockNumber?: bigint | Exclude<BlockTag, "pending">;
+    /** Caller-selected quotes and percentage tolerances. Omitted limits are unchecked. */
+    readonly limits?: SimulationLimits;
+}

package/lib/esm/params.js

@@ -0,0 +1,2 @@
+/** Every simulation mode; source of `SimulationMode`. */
+export const SIMULATION_MODES = ["preview", "final"];

package/lib/esm/requirements/index.d.ts

@@ -0,0 +1 @@
+export { toSimulationAuthorizations } from "./requirements.js";

package/lib/esm/requirements/index.js

@@ -0,0 +1 @@
+export { toSimulationAuthorizations } from "./requirements.js";

package/lib/esm/requirements/requirements.d.ts

@@ -0,0 +1,64 @@
+import type { ActionRequirement } from "@morpho-org/morpho-sdk";
+import type { Address } from "viem";
+import type { SimulationAuthorization } from "../authorizations.js";
+import type { SimulationMode } from "../params.js";
+/**
+ * Maps morpho-sdk action requirements, in order, onto simulation authorization descriptors.
+ *
+ * The adapter is a pure mapper — nothing is decoded or validated; `simulate()`'s request parser
+ * validates each authorization's shape and semantics when the request is parsed. Call requirements
+ * (`erc20Approval`, `blueAuthorization`) are mapped straight from `action.args` (the approval
+ * token is the requirement's `to`). Signature requirements (`permit`,
+ * `permit2SignatureTransfer`, `authorization`) carry their EIP-712 payload through unchanged; a
+ * missing payload throws {@link AuthorizationRequestMismatchError}. Any other requirement type
+ * throws {@link UnsupportedOperationError}.
+ *
+ * The function is pure and synchronous: no RPC reads, no clock, no signing.
+ *
+ * @param params - Mapping parameters.
+ * @param params.chainId - The chain the requirements were resolved on; carried into error contexts.
+ * @param params.mode - Simulation mode carried into error contexts (`"preview"` or `"final"`).
+ * @param params.blockNumber - Pinned block the simulation is verified against; carried into error contexts.
+ * @param params.owner - The account the requirements were resolved for (transaction sender).
+ * @param params.requirements - Requirements returned by `ActionOutput.getRequirements()`.
+ * @returns One {@link SimulationAuthorization} per input requirement, in the same order.
+ * @throws {AuthorizationRequestMismatchError} when a signature requirement carries no `typedData`.
+ * @throws {UnsupportedOperationError} when a requirement's action type is not a supported
+ *   authorization.
+ * @example
+ * ```ts
+ * import { toSimulationAuthorizations } from "@morpho-org/evm-simulation";
+ * import { morphoViemExtension } from "@morpho-org/morpho-sdk";
+ * import { vaults } from "@morpho-org/morpho-test";
+ * import { createPublicClient, http, type Address } from "viem";
+ * import { mainnet } from "viem/chains";
+ *
+ * async function prepare(userAddress: Address, blockNumber: bigint) {
+ *   const client = createPublicClient({ chain: mainnet, transport: http() })
+ *     .extend(morphoViemExtension());
+ *   const vault = client.morpho.vaultV1(
+ *     vaults[mainnet.id].steakUsdc.address,
+ *     mainnet.id,
+ *   );
+ *   const vaultData = await vault.getData();
+ *   const requirements = await vault
+ *     .deposit({ amount: 1_000_000n, userAddress, vaultData })
+ *     .getRequirements();
+ *   const authorizations = toSimulationAuthorizations({
+ *     chainId: mainnet.id,
+ *     mode: "final",
+ *     blockNumber,
+ *     owner: userAddress,
+ *     requirements,
+ *   });
+ *   return authorizations; // readonly SimulationAuthorization[], one entry per requirement
+ * }
+ * ```
+ */
+export declare function toSimulationAuthorizations(params: {
+    readonly chainId: number;
+    readonly mode: SimulationMode;
+    readonly blockNumber: bigint;
+    readonly owner: Address;
+    readonly requirements: readonly ActionRequirement[];
+}): readonly SimulationAuthorization[];

package/lib/esm/requirements/requirements.js

@@ -0,0 +1,146 @@
+import { isRequirementApproval, isRequirementBlueAuthorization, isRequirementSignature, } from "@morpho-org/morpho-sdk";
+import { AuthorizationRequestMismatchError, UnsupportedOperationError, } from "../errors.js";
+const mismatch = (ctx) => (message, options) => {
+    throw new AuthorizationRequestMismatchError(`${message}. Rebuild the wallet request from getRequirements()`, {
+        context: {
+            stage: "preparation",
+            chainId: ctx.chainId,
+            mode: ctx.mode,
+            blockNumber: ctx.blockNumber,
+            authorizationIndex: ctx.index,
+        },
+        ...options,
+    });
+};
+const unsupported = (ctx) => (message, options) => {
+    throw new UnsupportedOperationError(message, {
+        context: {
+            stage: "preparation",
+            chainId: ctx.chainId,
+            mode: ctx.mode,
+            blockNumber: ctx.blockNumber,
+            authorizationIndex: ctx.index,
+        },
+        ...options,
+    });
+};
+const toErc2612Permit = (action, ctx) => {
+    if (action.typedData == null) {
+        mismatch(ctx)("Permit requirement carries no typedData payload");
+    }
+    return {
+        type: "erc2612Permit",
+        typedData: action.typedData,
+    };
+};
+const toPermit2SignatureTransfer = (action, ctx) => {
+    if (action.typedData == null) {
+        mismatch(ctx)("Permit2 requirement carries no typedData payload");
+    }
+    return {
+        type: "permit2SignatureTransfer",
+        owner: ctx.owner,
+        typedData: action.typedData,
+    };
+};
+const toBlueAuthorizationSignature = (action, ctx) => {
+    if (action.typedData == null) {
+        mismatch(ctx)("Authorization requirement carries no typedData payload");
+    }
+    return {
+        type: "blueAuthorizationSignature",
+        typedData: action.typedData,
+    };
+};
+const toErc20Approval = (requirement, ctx) => ({
+    type: "erc20Approval",
+    token: requirement.to,
+    owner: ctx.owner,
+    spender: requirement.action.args.spender,
+    amount: requirement.action.args.amount,
+});
+const toBlueAuthorization = (requirement, ctx) => ({
+    type: "blueAuthorization",
+    authorizer: ctx.owner,
+    authorized: requirement.action.args.authorized,
+    isAuthorized: requirement.action.args.isAuthorized,
+});
+/**
+ * Maps morpho-sdk action requirements, in order, onto simulation authorization descriptors.
+ *
+ * The adapter is a pure mapper — nothing is decoded or validated; `simulate()`'s request parser
+ * validates each authorization's shape and semantics when the request is parsed. Call requirements
+ * (`erc20Approval`, `blueAuthorization`) are mapped straight from `action.args` (the approval
+ * token is the requirement's `to`). Signature requirements (`permit`,
+ * `permit2SignatureTransfer`, `authorization`) carry their EIP-712 payload through unchanged; a
+ * missing payload throws {@link AuthorizationRequestMismatchError}. Any other requirement type
+ * throws {@link UnsupportedOperationError}.
+ *
+ * The function is pure and synchronous: no RPC reads, no clock, no signing.
+ *
+ * @param params - Mapping parameters.
+ * @param params.chainId - The chain the requirements were resolved on; carried into error contexts.
+ * @param params.mode - Simulation mode carried into error contexts (`"preview"` or `"final"`).
+ * @param params.blockNumber - Pinned block the simulation is verified against; carried into error contexts.
+ * @param params.owner - The account the requirements were resolved for (transaction sender).
+ * @param params.requirements - Requirements returned by `ActionOutput.getRequirements()`.
+ * @returns One {@link SimulationAuthorization} per input requirement, in the same order.
+ * @throws {AuthorizationRequestMismatchError} when a signature requirement carries no `typedData`.
+ * @throws {UnsupportedOperationError} when a requirement's action type is not a supported
+ *   authorization.
+ * @example
+ * ```ts
+ * import { toSimulationAuthorizations } from "@morpho-org/evm-simulation";
+ * import { morphoViemExtension } from "@morpho-org/morpho-sdk";
+ * import { vaults } from "@morpho-org/morpho-test";
+ * import { createPublicClient, http, type Address } from "viem";
+ * import { mainnet } from "viem/chains";
+ *
+ * async function prepare(userAddress: Address, blockNumber: bigint) {
+ *   const client = createPublicClient({ chain: mainnet, transport: http() })
+ *     .extend(morphoViemExtension());
+ *   const vault = client.morpho.vaultV1(
+ *     vaults[mainnet.id].steakUsdc.address,
+ *     mainnet.id,
+ *   );
+ *   const vaultData = await vault.getData();
+ *   const requirements = await vault
+ *     .deposit({ amount: 1_000_000n, userAddress, vaultData })
+ *     .getRequirements();
+ *   const authorizations = toSimulationAuthorizations({
+ *     chainId: mainnet.id,
+ *     mode: "final",
+ *     blockNumber,
+ *     owner: userAddress,
+ *     requirements,
+ *   });
+ *   return authorizations; // readonly SimulationAuthorization[], one entry per requirement
+ * }
+ * ```
+ */
+export function toSimulationAuthorizations(params) {
+    const { chainId, mode, blockNumber, owner, requirements } = params;
+    return requirements.map((requirement, index) => {
+        const ctx = { chainId, mode, blockNumber, owner, index };
+        if (isRequirementApproval(requirement)) {
+            return toErc20Approval(requirement, ctx);
+        }
+        if (isRequirementBlueAuthorization(requirement)) {
+            return toBlueAuthorization(requirement, ctx);
+        }
+        if (isRequirementSignature(requirement)) {
+            const { action } = requirement;
+            switch (action.type) {
+                case "permit":
+                    return toErc2612Permit(action, ctx);
+                case "permit2SignatureTransfer":
+                    return toPermit2SignatureTransfer(action, ctx);
+                case "authorization":
+                    return toBlueAuthorizationSignature(action, ctx);
+                default:
+                    return unsupported(ctx)(`Signature requirement action type "${action.type}" is not supported. Only permit, permit2SignatureTransfer, and authorization signatures are supported`);
+            }
+        }
+        return unsupported(ctx)(`Requirement action type "${requirement.action.type}" is not supported. Only erc20Approval, blueAuthorization, permit, permit2SignatureTransfer, and authorization requirements are supported`);
+    });
+}

package/lib/esm/result.d.ts

@@ -0,0 +1,49 @@
+import type { Address } from "viem";
+import type { SimulationAuthorization } from "./authorizations.js";
+import type { SimulationLimits, SimulationOperationSubject, SlippageLimits } from "./limits.js";
+import type { SimulationMode } from "./params.js";
+import type { SimulationCall, SimulationResult, SimulationTransaction } from "./types.js";
+/** One operation described by the caller's `limits.operations`. */
+export type SimulatedOperation = {
+    /** Quote and percentage tolerance checked against the named subject over the whole bundle. */
+    readonly checkedLimits: SlippageLimits;
+    /** Resolved selector from the limit; defaults to the transaction sender. */
+    readonly account: Address;
+    /** Resolved selector from the limit; defaults to the transaction sender. */
+    readonly receiver: Address;
+} & SimulationOperationSubject;
+/** How a pending authorization was modeled in preview. */
+export interface AuthorizationPreparation {
+    readonly authorizationIndex: number;
+    readonly authorization: SimulationAuthorization;
+    /** Approval calls simulated before the user transactions. */
+    readonly calls: readonly {
+        readonly transaction: SimulationTransaction;
+        readonly result: SimulationCall;
+    }[];
+}
+/** Optional slippage checks; execution success does not imply economic verification. */
+export interface SimulationVerification {
+    readonly mode: SimulationMode;
+    readonly chainId: number;
+    /**
+     * Block `eth_simulateV1` executed in: the pinned state block or its
+     * successor, depending on the node. Not a pin to pass back as
+     * `SimulateParams.blockNumber`.
+     */
+    readonly blockNumber: bigint;
+    /**
+     * Timestamp (seconds) of the block `eth_simulateV1` executed in: the
+     * pinned state block or its successor, depending on the node.
+     */
+    readonly blockTimestamp: bigint;
+    /** Caller-supplied quotes and tolerances only; omitted limits remain unchecked. */
+    readonly limits: Required<SimulationLimits>;
+    readonly operations: readonly SimulatedOperation[];
+    /** Preview only; always empty in final. */
+    readonly authorizations: readonly AuthorizationPreparation[];
+}
+/** `simulationTxs` equals the caller's `transactions`; `txIdx` indexes only those. */
+export interface VerifiedSimulationResult extends SimulationResult {
+    readonly verification: SimulationVerification;
+}

package/lib/esm/result.js

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

package/lib/esm/simulate/asset-changes.d.ts

@@ -5,18 +5,20 @@ export interface AssetChangeEntry {
     account: Address;
     token: Address;
     diff: bigint;
+    /** Not populated by `eth_simulateV1`; kept for forward compatibility. */
     symbol?: string;
     decimals?: number;
 }
 /**
  * Collapse the native-ETH sentinel to viem's lowercase `ethAddress`, checksumming
  * any real token address. `eth_simulateV1` synthesizes native moves from the
- * sentinel `0xeee…eee`, and Tenderly may echo it — in checksummed or any other
- * case — as an asset change's `contractAddress`. Native ETH is keyed by the exact
- * `ethAddress` constant here and in the bundles-retention guard, so a checksummed
+ * sentinel `0xeee…eee`, possibly in checksummed or any other case. Native ETH
+ * is keyed by the exact `ethAddress` constant here and in the bundles-retention
+ * guard, so a checksummed
  * sentinel would land on a separate map key and silently escape retention checks.
- * This is the single source of truth for token normalization shared by the
- * transfer-log parser and the Tenderly asset-change mapper.
+ * This is the single source of truth for token normalization, applied by the
+ * transfer-log parser; asset-change aggregation and the bundler-retention guard
+ * rely on its `ethAddress` keying.
  *
  * @param address - Token address emitting a transfer or carried by an asset change.
  * @returns `ethAddress` for the native sentinel, else the checksummed address.

package/lib/esm/simulate/asset-changes.js

@@ -2,12 +2,13 @@ import { ethAddress, getAddress } from "viem";
 /**
  * Collapse the native-ETH sentinel to viem's lowercase `ethAddress`, checksumming
  * any real token address. `eth_simulateV1` synthesizes native moves from the
- * sentinel `0xeee…eee`, and Tenderly may echo it — in checksummed or any other
- * case — as an asset change's `contractAddress`. Native ETH is keyed by the exact
- * `ethAddress` constant here and in the bundles-retention guard, so a checksummed
+ * sentinel `0xeee…eee`, possibly in checksummed or any other case. Native ETH
+ * is keyed by the exact `ethAddress` constant here and in the bundles-retention
+ * guard, so a checksummed
  * sentinel would land on a separate map key and silently escape retention checks.
- * This is the single source of truth for token normalization shared by the
- * transfer-log parser and the Tenderly asset-change mapper.
+ * This is the single source of truth for token normalization, applied by the
+ * transfer-log parser; asset-change aggregation and the bundler-retention guard
+ * rely on its `ethAddress` keying.
  *
  * @param address - Token address emitting a transfer or carried by an asset change.
  * @returns `ethAddress` for the native sentinel, else the checksummed address.

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

@@ -0,0 +1,16 @@
+import { type PublicClient } from "viem";
+/**
+ * Create the viem public client shared by every simulation backend stage
+ * (pinned block resolution, binding/pinned reads, `eth_simulateV1`).
+ *
+ * A supplied abort signal is bound into the transport: a failed or aborted
+ * request must not consume another attempt or a fresh budget, and the pipeline
+ * abort signal owns the overall execution deadline, so the client sends zero
+ * retries and disables viem's own timeout when a signal is present.
+ *
+ * @param rpcUrl - Endpoint URL; each caller supplies the transport it trusts.
+ * @param signal - Optional pipeline abort signal shared by every request.
+ * @returns A viem {@link PublicClient} honoring the shared abort/timeout budget.
+ * @internal
+ */
+export declare function createSimulationClient(rpcUrl: string, signal?: AbortSignal): PublicClient;

package/lib/esm/simulate/backends/client.js

@@ -0,0 +1,24 @@
+import { createPublicClient, http } from "viem";
+/**
+ * Create the viem public client shared by every simulation backend stage
+ * (pinned block resolution, binding/pinned reads, `eth_simulateV1`).
+ *
+ * A supplied abort signal is bound into the transport: a failed or aborted
+ * request must not consume another attempt or a fresh budget, and the pipeline
+ * abort signal owns the overall execution deadline, so the client sends zero
+ * retries and disables viem's own timeout when a signal is present.
+ *
+ * @param rpcUrl - Endpoint URL; each caller supplies the transport it trusts.
+ * @param signal - Optional pipeline abort signal shared by every request.
+ * @returns A viem {@link PublicClient} honoring the shared abort/timeout budget.
+ * @internal
+ */
+export function createSimulationClient(rpcUrl, signal) {
+    return createPublicClient({
+        transport: http(rpcUrl, {
+            fetchOptions: signal ? { signal } : undefined,
+            retryCount: 0,
+            timeout: signal ? 0 : undefined,
+        }),
+    });
+}

package/lib/esm/simulate/backends/eth-simulate-v1.d.ts

@@ -1,24 +1,73 @@
-import { type Address, type BlockTag } from "viem";
-import type { RawSimulationResult, SimulationTransaction } from "../../types.js";
+import { type Client, type PublicClient } from "viem";
+import type { SimulationMode } from "../../params.js";
+import type { ExecutionPlan } from "../plan/plan-execution.js";
+import type { SimulationExecution } from "./parse-response.js";
+import type { PinnedBlock } from "./resolve-pinned-block.js";
+/** The JSON-RPC methods this boundary calls. */
+type RpcLabel = "eth_getBlock" | "eth_chainId" | "eth_simulateV1";
+/** Run one RPC call; anything thrown becomes a typed boundary error. @internal */
+export declare const rpc: <T>(label: RpcLabel, call: () => Promise<T>) => Promise<T>;
+/** Validate the endpoint identity through the same URL-safe RPC boundary. @internal */
+export declare function assertEndpointChain(params: {
+    readonly client: Pick<PublicClient, "getChainId">;
+    readonly chainId: number;
+    readonly mode: SimulationMode;
+    readonly blockNumber?: bigint;
+}): Promise<void>;
 /**
- * Simulate transactions using eth_simulateV1 (viem simulateCalls).
+ * Execute an {@link ExecutionPlan} through a single `eth_simulateV1` call and
+ * collect the pinned execution.
  *
- * Uses stateOverride to set the user's ETH balance high enough to avoid
- * false "insufficient balance for gas" reverts.
+ * 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.
  *
- * 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.
+ * 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`
+ *    (`true` on Monad, whose nodes reject `false` and charge no gas in the
+ *    simulated block). 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, already-pinned
+ *   state block, and the `validation` flag to send.
+ * @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
  */
-export declare function simulateV1(params: {
-    rpcUrl: string;
-    chainId: number;
-    transactions: SimulationTransaction[];
-    blockNumber?: bigint | BlockTag;
-    wNative?: Address | null;
-    signal?: AbortSignal;
-}): Promise<RawSimulationResult>;
+export declare function executePlan(params: {
+    client: Client & Pick<PublicClient, "getBlock">;
+    plan: ExecutionPlan;
+    stateBlock: PinnedBlock;
+    validation: boolean;
+}): Promise<SimulationExecution>;
+export {};