@morpho-org/evm-simulation 4.2.1 → 5.0.1

package/lib/cjs/requirements/requirements.js

@@ -0,0 +1,149 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toSimulationAuthorizations = toSimulationAuthorizations;
+const morpho_sdk_1 = require("@morpho-org/morpho-sdk");
+const errors_js_1 = require("../errors.js");
+const mismatch = (ctx) => (message, options) => {
+    throw new errors_js_1.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 errors_js_1.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
+ * }
+ * ```
+ */
+function toSimulationAuthorizations(params) {
+    const { chainId, mode, blockNumber, owner, requirements } = params;
+    return requirements.map((requirement, index) => {
+        const ctx = { chainId, mode, blockNumber, owner, index };
+        if ((0, morpho_sdk_1.isRequirementApproval)(requirement)) {
+            return toErc20Approval(requirement, ctx);
+        }
+        if ((0, morpho_sdk_1.isRequirementBlueAuthorization)(requirement)) {
+            return toBlueAuthorization(requirement, ctx);
+        }
+        if ((0, morpho_sdk_1.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/cjs/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/cjs/result.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

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

@@ -6,12 +6,13 @@ const viem_1 = require("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/cjs/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/cjs/simulate/backends/client.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSimulationClient = createSimulationClient;
+const viem_1 = require("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
+ */
+function createSimulationClient(rpcUrl, signal) {
+    return (0, viem_1.createPublicClient)({
+        transport: (0, viem_1.http)(rpcUrl, {
+            fetchOptions: signal ? { signal } : undefined,
+            retryCount: 0,
+            timeout: signal ? 0 : undefined,
+        }),
+    });
+}

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