@morpho-org/evm-simulation 5.0.0 → 5.0.1

package/README.md

@@ -46,11 +46,11 @@ try {
 }
 ```
 
-Every chain entry requires `simulateV1Url`, pointing to a JSON-RPC endpoint that supports `eth_simulateV1`. Execution uses the full `timeoutMs` budget (default 5000 ms), with no retries or provider fallback. RPC failures, timeouts and reverts throw typed errors. The optional logger still reports parsing and retention warnings.
+Every chain entry requires `simulateV1Url`, pointing to a JSON-RPC endpoint that supports `eth_simulateV1`. Requests send `validation: false` so gas is not charged. Monad (chain 143) is handled internally: its nodes reject `false`, so it sends `true` (its simulated block charges no gas either way), and it pins to the `finalized` block by default because its `latest` block is not final. On Monad, `gasUsed` reports the call's gas limit, not the gas consumed. Execution uses the full `timeoutMs` budget (default 5000 ms), with no retries or provider fallback. RPC failures, timeouts and reverts throw typed errors. The optional logger still reports parsing and retention warnings.
 
 Native-ETH movements are observed through `traceTransfers` logs on the simulated calls — no `stateOverrides` or helper contracts are injected.
 
-This is the unreleased v5 integration stack. See the [v4 → v5 migration guide](../../docs/migrations/evm-simulation-v4-to-v5.md) for the backend cutover and remaining release gates.
+Upgrading from v4? See the [v4 → v5 migration guide](../../docs/migrations/evm-simulation-v4-to-v5.md) for the backend cutover.
 
 ### API surface
 

package/lib/cjs/params.d.ts

@@ -17,7 +17,8 @@ export interface SimulateParams {
     readonly mode?: SimulationMode;
     /** Pending wallet requests, in order. Preview only; rejected in final. */
     readonly authorizations?: readonly SimulationAuthorization[];
-    /** Resolved once; defaults to "latest". Only canonical (mined) blocks can be
+    /** 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. */

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

@@ -26,9 +26,11 @@ export declare function assertEndpointChain(params: {
  *
  * 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
+ *    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
@@ -45,8 +47,8 @@ export declare function assertEndpointChain(params: {
  * 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.
+ * @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,
@@ -66,5 +68,6 @@ export declare function executePlan(params: {
     client: Client & Pick<PublicClient, "getBlock">;
     plan: ExecutionPlan;
     stateBlock: PinnedBlock;
+    validation: boolean;
 }): Promise<SimulationExecution>;
 export {};

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

@@ -89,9 +89,11 @@ async function assertEndpointChain(params) {
  *
  * 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
+ *    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
@@ -108,8 +110,8 @@ async function assertEndpointChain(params) {
  * 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.
+ * @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,
@@ -126,7 +128,7 @@ async function assertEndpointChain(params) {
  * @internal
  */
 async function executePlan(params) {
-    const { client, plan, stateBlock } = params;
+    const { client, plan, stateBlock, validation } = params;
     const response = await (0, exports.rpc)("eth_simulateV1", () => client.request({
         method: "eth_simulateV1",
         params: [
@@ -142,7 +144,7 @@ async function executePlan(params) {
                     },
                 ],
                 traceTransfers: true,
-                validation: false,
+                validation,
             },
             (0, viem_1.numberToHex)(stateBlock.number),
         ],

package/lib/cjs/simulate/run-simulation.js

@@ -51,9 +51,13 @@ async function runSimulation(params) {
         mode: request.mode,
         blockNumber: typeof request.blockNumber === "bigint" ? request.blockNumber : undefined,
     });
+    // Monad nodes reject `validation: false` and charge no gas in the simulated
+    // block either way. Its `latest` block is not final: simulating at its number
+    // runs on another parent, so default to `finalized`.
+    const monad = request.chainId === blue_sdk_1.ChainId.MonadMainnet;
     const pinnedBlock = await (0, resolve_pinned_block_js_1.resolvePinnedBlock)({
         client,
-        blockNumber: request.blockNumber,
+        blockNumber: request.blockNumber ?? (monad ? "finalized" : undefined),
         signal,
     });
     // With no calldata decoding, the caller's declared `limits.operations`
@@ -86,6 +90,7 @@ async function runSimulation(params) {
         client,
         plan,
         stateBlock: pinnedBlock,
+        validation: monad,
     });
     const userCalls = execution.calls
         .filter((call) => call.planned.type === "transaction")

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

@@ -34,7 +34,8 @@ import type { SimulationConfig } from "../types.js";
  * **Funding.** `value` transfers are funded by the sender's real native
  * balance — no balance inflation — so under-funded bundles revert exactly as
  * they would on-chain. `validation: false` keeps gas from being charged,
- * separating gas from economic effects.
+ * separating gas from economic effects. Monad nodes reject `false`, so Monad
+ * simulations send `true`; its simulated block charges no gas either way.
  *
  * @param config - Required per-chain `eth_simulateV1` URL, optional logger, and
  *   the overall timeout budget.
@@ -47,7 +48,8 @@ import type { SimulationConfig } from "../types.js";
  * @param params.limits - Optional quotes and percentage tolerances; unquoted amounts require no reads.
  * @param params.blockNumber - Optional pinned block number or `BlockTag` other
  *   than `"pending"`.
- *   Defaults to `latest`, resolved exactly once.
+ *   Defaults to `latest` (`finalized` on Monad, whose `latest` block is not
+ *   final), resolved exactly once.
  * @throws {SimulationValidationError} for invalid input (mixed senders, bad
  *   addresses, empty transactions, malformed authorizations, final-mode
  *   authorizations, malformed limits, unknown fields, a `"pending"` block tag, or share quotes for

package/lib/cjs/simulate/simulate.js

@@ -36,7 +36,8 @@ const run_simulation_js_1 = require("./run-simulation.js");
  * **Funding.** `value` transfers are funded by the sender's real native
  * balance — no balance inflation — so under-funded bundles revert exactly as
  * they would on-chain. `validation: false` keeps gas from being charged,
- * separating gas from economic effects.
+ * separating gas from economic effects. Monad nodes reject `false`, so Monad
+ * simulations send `true`; its simulated block charges no gas either way.
  *
  * @param config - Required per-chain `eth_simulateV1` URL, optional logger, and
  *   the overall timeout budget.
@@ -49,7 +50,8 @@ const run_simulation_js_1 = require("./run-simulation.js");
  * @param params.limits - Optional quotes and percentage tolerances; unquoted amounts require no reads.
  * @param params.blockNumber - Optional pinned block number or `BlockTag` other
  *   than `"pending"`.
- *   Defaults to `latest`, resolved exactly once.
+ *   Defaults to `latest` (`finalized` on Monad, whose `latest` block is not
+ *   final), resolved exactly once.
  * @throws {SimulationValidationError} for invalid input (mixed senders, bad
  *   addresses, empty transactions, malformed authorizations, final-mode
  *   authorizations, malformed limits, unknown fields, a `"pending"` block tag, or share quotes for

package/lib/cjs/types.d.ts

@@ -145,7 +145,8 @@ export interface SimulationCall {
      * Gas consumed by this call's root frame, not a safe gas limit. This is
      * post-refund consumption and does not account for EIP-150's 63/64 rule in
      * nested calls, so consumers deriving a limit must add their own headroom,
-     * larger than headroom derived from `eth_estimateGas`.
+     * larger than headroom derived from `eth_estimateGas`. On Monad it reports the
+     * call's gas limit (150M by default) instead of gas consumed.
      */
     readonly gasUsed: bigint;
 }

package/lib/esm/params.d.ts

@@ -17,7 +17,8 @@ export interface SimulateParams {
     readonly mode?: SimulationMode;
     /** Pending wallet requests, in order. Preview only; rejected in final. */
     readonly authorizations?: readonly SimulationAuthorization[];
-    /** Resolved once; defaults to "latest". Only canonical (mined) blocks can be
+    /** 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. */

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

@@ -26,9 +26,11 @@ export declare function assertEndpointChain(params: {
  *
  * 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
+ *    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
@@ -45,8 +47,8 @@ export declare function assertEndpointChain(params: {
  * 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.
+ * @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,
@@ -66,5 +68,6 @@ export declare function executePlan(params: {
     client: Client & Pick<PublicClient, "getBlock">;
     plan: ExecutionPlan;
     stateBlock: PinnedBlock;
+    validation: boolean;
 }): Promise<SimulationExecution>;
 export {};

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

@@ -83,9 +83,11 @@ export async function assertEndpointChain(params) {
  *
  * 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
+ *    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
@@ -102,8 +104,8 @@ export async function assertEndpointChain(params) {
  * 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.
+ * @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,
@@ -120,7 +122,7 @@ export async function assertEndpointChain(params) {
  * @internal
  */
 export async function executePlan(params) {
-    const { client, plan, stateBlock } = params;
+    const { client, plan, stateBlock, validation } = params;
     const response = await rpc("eth_simulateV1", () => client.request({
         method: "eth_simulateV1",
         params: [
@@ -136,7 +138,7 @@ export async function executePlan(params) {
                     },
                 ],
                 traceTransfers: true,
-                validation: false,
+                validation,
             },
             numberToHex(stateBlock.number),
         ],

package/lib/esm/simulate/run-simulation.js

@@ -1,4 +1,4 @@
-import { getChainAddresses, UnsupportedChainIdError, } from "@morpho-org/blue-sdk";
+import { ChainId, getChainAddresses, UnsupportedChainIdError, } from "@morpho-org/blue-sdk";
 import { _try } from "@morpho-org/morpho-ts";
 import { zeroAddress } from "viem";
 import { InvalidSimulationResponseError, UnsupportedChainError, } from "../errors.js";
@@ -48,9 +48,13 @@ export async function runSimulation(params) {
         mode: request.mode,
         blockNumber: typeof request.blockNumber === "bigint" ? request.blockNumber : undefined,
     });
+    // Monad nodes reject `validation: false` and charge no gas in the simulated
+    // block either way. Its `latest` block is not final: simulating at its number
+    // runs on another parent, so default to `finalized`.
+    const monad = request.chainId === ChainId.MonadMainnet;
     const pinnedBlock = await resolvePinnedBlock({
         client,
-        blockNumber: request.blockNumber,
+        blockNumber: request.blockNumber ?? (monad ? "finalized" : undefined),
         signal,
     });
     // With no calldata decoding, the caller's declared `limits.operations`
@@ -83,6 +87,7 @@ export async function runSimulation(params) {
         client,
         plan,
         stateBlock: pinnedBlock,
+        validation: monad,
     });
     const userCalls = execution.calls
         .filter((call) => call.planned.type === "transaction")

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

@@ -34,7 +34,8 @@ import type { SimulationConfig } from "../types.js";
  * **Funding.** `value` transfers are funded by the sender's real native
  * balance — no balance inflation — so under-funded bundles revert exactly as
  * they would on-chain. `validation: false` keeps gas from being charged,
- * separating gas from economic effects.
+ * separating gas from economic effects. Monad nodes reject `false`, so Monad
+ * simulations send `true`; its simulated block charges no gas either way.
  *
  * @param config - Required per-chain `eth_simulateV1` URL, optional logger, and
  *   the overall timeout budget.
@@ -47,7 +48,8 @@ import type { SimulationConfig } from "../types.js";
  * @param params.limits - Optional quotes and percentage tolerances; unquoted amounts require no reads.
  * @param params.blockNumber - Optional pinned block number or `BlockTag` other
  *   than `"pending"`.
- *   Defaults to `latest`, resolved exactly once.
+ *   Defaults to `latest` (`finalized` on Monad, whose `latest` block is not
+ *   final), resolved exactly once.
  * @throws {SimulationValidationError} for invalid input (mixed senders, bad
  *   addresses, empty transactions, malformed authorizations, final-mode
  *   authorizations, malformed limits, unknown fields, a `"pending"` block tag, or share quotes for

package/lib/esm/simulate/simulate.js

@@ -33,7 +33,8 @@ import { runSimulation } from "./run-simulation.js";
  * **Funding.** `value` transfers are funded by the sender's real native
  * balance — no balance inflation — so under-funded bundles revert exactly as
  * they would on-chain. `validation: false` keeps gas from being charged,
- * separating gas from economic effects.
+ * separating gas from economic effects. Monad nodes reject `false`, so Monad
+ * simulations send `true`; its simulated block charges no gas either way.
  *
  * @param config - Required per-chain `eth_simulateV1` URL, optional logger, and
  *   the overall timeout budget.
@@ -46,7 +47,8 @@ import { runSimulation } from "./run-simulation.js";
  * @param params.limits - Optional quotes and percentage tolerances; unquoted amounts require no reads.
  * @param params.blockNumber - Optional pinned block number or `BlockTag` other
  *   than `"pending"`.
- *   Defaults to `latest`, resolved exactly once.
+ *   Defaults to `latest` (`finalized` on Monad, whose `latest` block is not
+ *   final), resolved exactly once.
  * @throws {SimulationValidationError} for invalid input (mixed senders, bad
  *   addresses, empty transactions, malformed authorizations, final-mode
  *   authorizations, malformed limits, unknown fields, a `"pending"` block tag, or share quotes for

package/lib/esm/types.d.ts

@@ -145,7 +145,8 @@ export interface SimulationCall {
      * Gas consumed by this call's root frame, not a safe gas limit. This is
      * post-refund consumption and does not account for EIP-150's 63/64 rule in
      * nested calls, so consumers deriving a limit must add their own headroom,
-     * larger than headroom derived from `eth_estimateGas`.
+     * larger than headroom derived from `eth_estimateGas`. On Monad it reports the
+     * call's gas limit (150M by default) instead of gas consumed.
      */
     readonly gasUsed: bigint;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@morpho-org/evm-simulation",
   "description": "EVM simulation engine for Morpho transactions.",
-  "version": "5.0.0",
+  "version": "5.0.1",
   "author": "Morpho Association <contact@morpho.org>",
   "repository": {
     "type": "git",
@@ -22,14 +22,14 @@
   ],
   "dependencies": {
     "@morpho-org/blue-sdk": "^7.2.0",
-    "@morpho-org/morpho-sdk": "^6.5.0",
-    "@morpho-org/morpho-ts": "^3.2.0"
+    "@morpho-org/morpho-sdk": "^6.6.0",
+    "@morpho-org/morpho-ts": "^3.2.1"
   },
   "peerDependencies": {
     "viem": "^2.0.0"
   },
   "devDependencies": {
-    "@morpho-org/test": "^2.10.0",
+    "@morpho-org/test": "^2.10.1",
     "fast-check": "^4.9.0",
     "typescript": "7.0.2",
     "viem": "^2.55.10",