@morpho-org/evm-simulation 5.0.0 → 5.1.0

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. Set `blockOverrides.gasLimit` on a chain entry to send that gas limit as the simulated block's `blockOverrides.gasLimit`; without it, no block override is sent. Set `parentHashCheck` on a chain entry to turn on or off the check that the simulated block's `parentHash` is the pinned block hash. It defaults to off on Stable (chain 988), whose nodes report a `parentHash` that never matches the pinned block, and on for every other chain. The block number, timestamp and reorg checks always apply. 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,13 @@ 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. When `blockGasLimit` is set,
+ *    it is sent as the block's `blockOverrides.gasLimit`; otherwise no block
+ *    override is sent.
+ *    **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 +49,9 @@ 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, the `validation` flag to send, the optional simulated
+ *   block gas limit, and whether to check the successor `parentHash`.
  * @returns Deep-frozen {@link SimulationExecution} — per-transaction call
  *   results and the resolved {@link ExecutionBlock}.
  * @throws {ExternalServiceError} For transport failures, timeouts,
@@ -66,5 +71,8 @@ export declare function executePlan(params: {
     client: Client & Pick<PublicClient, "getBlock">;
     plan: ExecutionPlan;
     stateBlock: PinnedBlock;
+    validation: boolean;
+    blockGasLimit?: bigint | undefined;
+    parentHashCheck: boolean;
 }): Promise<SimulationExecution>;
 export {};

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

@@ -89,9 +89,13 @@ 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. When `blockGasLimit` is set,
+ *    it is sent as the block's `blockOverrides.gasLimit`; otherwise no block
+ *    override is sent.
+ *    **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 +112,9 @@ 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, the `validation` flag to send, the optional simulated
+ *   block gas limit, and whether to check the successor `parentHash`.
  * @returns Deep-frozen {@link SimulationExecution} — per-transaction call
  *   results and the resolved {@link ExecutionBlock}.
  * @throws {ExternalServiceError} For transport failures, timeouts,
@@ -126,13 +131,16 @@ async function assertEndpointChain(params) {
  * @internal
  */
 async function executePlan(params) {
-    const { client, plan, stateBlock } = params;
+    const { client, plan, stateBlock, validation, blockGasLimit, parentHashCheck, } = params;
     const response = await (0, exports.rpc)("eth_simulateV1", () => client.request({
         method: "eth_simulateV1",
         params: [
             {
                 blockStateCalls: [
                     {
+                        ...(blockGasLimit !== undefined && {
+                            blockOverrides: { gasLimit: (0, viem_1.numberToHex)(blockGasLimit) },
+                        }),
                         calls: plan.calls.map((call) => ({
                             from: call.transaction.from,
                             to: call.transaction.to,
@@ -142,7 +150,7 @@ async function executePlan(params) {
                     },
                 ],
                 traceTransfers: true,
-                validation: false,
+                validation,
             },
             (0, viem_1.numberToHex)(stateBlock.number),
         ],
@@ -158,6 +166,7 @@ async function executePlan(params) {
         stateBlockNumber: stateBlock.number,
         stateBlockHash: stateBlock.hash,
         stateBlockTimestamp: stateBlock.timestamp,
+        parentHashCheck,
     });
     // Reorg window: the pinned state block must still carry the same hash
     // after simulation, or the result may describe a different chain tip.

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

@@ -65,5 +65,6 @@ export declare function parseSimulationResponse(params: {
     readonly stateBlockNumber: bigint;
     readonly stateBlockHash: Hex;
     readonly stateBlockTimestamp: bigint;
+    readonly parentHashCheck: boolean;
 }): SimulationExecution;
 export {};

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

@@ -57,8 +57,10 @@ function parseSimulationResponse(params) {
     }
     // Anvil re-hashes the pinned block, so only the geth-style successor can be
     // pinned by hash: it must report a parentHash (geth always does) equal to
-    // the pinned state block hash.
-    if (blockNumber === params.stateBlockNumber + 1n &&
+    // the pinned state block hash. With `parentHashCheck` off (Stable by
+    // default) the block number, timestamp and reorg checks still apply.
+    if (params.parentHashCheck &&
+        blockNumber === params.stateBlockNumber + 1n &&
         block.parentHash !== params.stateBlockHash) {
         throw new errors_js_1.InvalidSimulationResponseError(`eth_simulateV1 reported block ${blockNumber} whose parent ${String(block.parentHash)} is not the pinned state block hash ${params.stateBlockHash}; the node did not simulate on top of the pinned block.`, { context: errorContext });
     }

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

@@ -4,6 +4,10 @@ import type { ChainSimulationConfig, SimulationConfig } from "../../types.js";
  *
  * 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).
+ * the type already requires it at construction). Throws
+ * `SimulationValidationError` when `blockOverrides.gasLimit` is set but is
+ * not a positive bigint, or `parentHashCheck` is set but is not a boolean, so a
+ * misconfiguration never surfaces as a bypassable
+ * `ExternalServiceError`.
  */
 export declare function resolveChain(config: SimulationConfig, chainId: number): ChainSimulationConfig;

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

@@ -7,11 +7,22 @@ const errors_js_1 = require("../../errors.js");
  *
  * 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).
+ * the type already requires it at construction). Throws
+ * `SimulationValidationError` when `blockOverrides.gasLimit` is set but is
+ * not a positive bigint, or `parentHashCheck` is set but is not a boolean, so a
+ * misconfiguration never surfaces as a bypassable
+ * `ExternalServiceError`.
  */
 function resolveChain(config, chainId) {
     const entry = config.chains.get(chainId);
     if (!entry?.simulateV1Url)
         throw new errors_js_1.UnsupportedChainError(chainId);
+    const gasLimit = entry.blockOverrides?.gasLimit;
+    if (gasLimit !== undefined &&
+        (typeof gasLimit !== "bigint" || gasLimit <= 0n))
+        throw new errors_js_1.SimulationValidationError(`Chain ${chainId} blockOverrides.gasLimit must be a positive bigint, got "${String(gasLimit)}" (${typeof gasLimit}). Pass a bigint greater than 0n or omit gasLimit.`, ["blockOverrides.gasLimit: must be a positive bigint"]);
+    const parentHashCheck = entry.parentHashCheck;
+    if (parentHashCheck !== undefined && typeof parentHashCheck !== "boolean")
+        throw new errors_js_1.SimulationValidationError(`Chain ${chainId} parentHashCheck must be a boolean, got "${String(parentHashCheck)}" (${typeof parentHashCheck}). Pass true or false, or omit parentHashCheck.`, ["parentHashCheck: must be a boolean"]);
     return entry;
 }

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,9 @@ async function runSimulation(params) {
         client,
         plan,
         stateBlock: pinnedBlock,
+        validation: monad,
+        blockGasLimit: chain.blockOverrides?.gasLimit,
+        parentHashCheck: chain.parentHashCheck ?? request.chainId !== blue_sdk_1.ChainId.StableMainnet,
     });
     const userCalls = execution.calls
         .filter((call) => call.planned.type === "transaction")

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

@@ -34,10 +34,12 @@ 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.
+ * @param config - Required per-chain `eth_simulateV1` URL, optional per-chain
+ *   `blockOverrides.gasLimit` and `parentHashCheck`, optional logger, and the
+ *   overall timeout budget.
  * @param params - Per-call simulation input.
  * @param params.chainId - Chain id the bundle targets; must match the endpoint.
  * @param params.transactions - The bundle's transactions, in execution order.
@@ -47,10 +49,13 @@ 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
+ *   authorizations, malformed limits, unknown fields, a `"pending"` block tag, a
+ *   `blockOverrides.gasLimit` that is not a positive bigint, a `parentHashCheck`
+ *   that is not a boolean, or share quotes for
  *   `blueSupplyCollateral` / `blueWithdrawCollateral`).
  * @throws {ConsumerLimitViolationError} when a declared `limits` bound is
  *   violated by the observed effects.
@@ -64,7 +69,7 @@ import type { SimulationConfig } from "../types.js";
  * @throws {InvalidSimulationResponseError} when the node response cannot be
  *   trusted (bad shape, call-count mismatch, block that is neither the pinned
  *   state block nor its immediate successor, a successor with a mismatched
- *   `parentHash`, a block timestamp earlier than the pinned block's, a
+ *   `parentHash` (unless `parentHashCheck` is off; off by default on Stable, chain 988), a block timestamp earlier than the pinned block's, a
  *   malformed per-call result, a quoted balance/position read whose non-empty
  *   return data cannot be decoded, a state-block hash that changed or a pinned
  *   block that vanished mid-flight, or an

package/lib/cjs/simulate/simulate.js

@@ -36,10 +36,12 @@ 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.
+ * @param config - Required per-chain `eth_simulateV1` URL, optional per-chain
+ *   `blockOverrides.gasLimit` and `parentHashCheck`, optional logger, and the
+ *   overall timeout budget.
  * @param params - Per-call simulation input.
  * @param params.chainId - Chain id the bundle targets; must match the endpoint.
  * @param params.transactions - The bundle's transactions, in execution order.
@@ -49,10 +51,13 @@ 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
+ *   authorizations, malformed limits, unknown fields, a `"pending"` block tag, a
+ *   `blockOverrides.gasLimit` that is not a positive bigint, a `parentHashCheck`
+ *   that is not a boolean, or share quotes for
  *   `blueSupplyCollateral` / `blueWithdrawCollateral`).
  * @throws {ConsumerLimitViolationError} when a declared `limits` bound is
  *   violated by the observed effects.
@@ -66,7 +71,7 @@ const run_simulation_js_1 = require("./run-simulation.js");
  * @throws {InvalidSimulationResponseError} when the node response cannot be
  *   trusted (bad shape, call-count mismatch, block that is neither the pinned
  *   state block nor its immediate successor, a successor with a mismatched
- *   `parentHash`, a block timestamp earlier than the pinned block's, a
+ *   `parentHash` (unless `parentHashCheck` is off; off by default on Stable, chain 988), a block timestamp earlier than the pinned block's, a
  *   malformed per-call result, a quoted balance/position read whose non-empty
  *   return data cannot be decoded, a state-block hash that changed or a pinned
  *   block that vanished mid-flight, or an

package/lib/cjs/types.d.ts

@@ -3,6 +3,21 @@ import type { Address, Hex } from "viem";
 export interface ChainSimulationConfig {
     /** JSON-RPC URL supporting `eth_simulateV1`. Required for every configured chain. */
     readonly simulateV1Url: string;
+    /**
+     * Block overrides forwarded to `eth_simulateV1` as the simulated block's
+     * `blockOverrides`. Omitted fields leave the node's defaults untouched.
+     */
+    readonly blockOverrides?: {
+        /** Gas limit of the simulated block. Omitted: no gas limit override is sent. */
+        readonly gasLimit?: bigint;
+    };
+    /**
+     * Whether a simulated successor block's `parentHash` must equal the pinned
+     * state block hash. Block number, timestamp and reorg checks always run.
+     * Omitted: on everywhere except Stable (988), whose nodes report a
+     * `parentHash` that never matches the pinned block.
+     */
+    readonly parentHashCheck?: boolean;
 }
 /**
  * Top-level configuration for `simulate`.
@@ -145,7 +160,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,13 @@ 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. When `blockGasLimit` is set,
+ *    it is sent as the block's `blockOverrides.gasLimit`; otherwise no block
+ *    override is sent.
+ *    **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 +49,9 @@ 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, the `validation` flag to send, the optional simulated
+ *   block gas limit, and whether to check the successor `parentHash`.
  * @returns Deep-frozen {@link SimulationExecution} — per-transaction call
  *   results and the resolved {@link ExecutionBlock}.
  * @throws {ExternalServiceError} For transport failures, timeouts,
@@ -66,5 +71,8 @@ export declare function executePlan(params: {
     client: Client & Pick<PublicClient, "getBlock">;
     plan: ExecutionPlan;
     stateBlock: PinnedBlock;
+    validation: boolean;
+    blockGasLimit?: bigint | undefined;
+    parentHashCheck: boolean;
 }): Promise<SimulationExecution>;
 export {};

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

@@ -83,9 +83,13 @@ 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. When `blockGasLimit` is set,
+ *    it is sent as the block's `blockOverrides.gasLimit`; otherwise no block
+ *    override is sent.
+ *    **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 +106,9 @@ 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, the `validation` flag to send, the optional simulated
+ *   block gas limit, and whether to check the successor `parentHash`.
  * @returns Deep-frozen {@link SimulationExecution} — per-transaction call
  *   results and the resolved {@link ExecutionBlock}.
  * @throws {ExternalServiceError} For transport failures, timeouts,
@@ -120,13 +125,16 @@ export async function assertEndpointChain(params) {
  * @internal
  */
 export async function executePlan(params) {
-    const { client, plan, stateBlock } = params;
+    const { client, plan, stateBlock, validation, blockGasLimit, parentHashCheck, } = params;
     const response = await rpc("eth_simulateV1", () => client.request({
         method: "eth_simulateV1",
         params: [
             {
                 blockStateCalls: [
                     {
+                        ...(blockGasLimit !== undefined && {
+                            blockOverrides: { gasLimit: numberToHex(blockGasLimit) },
+                        }),
                         calls: plan.calls.map((call) => ({
                             from: call.transaction.from,
                             to: call.transaction.to,
@@ -136,7 +144,7 @@ export async function executePlan(params) {
                     },
                 ],
                 traceTransfers: true,
-                validation: false,
+                validation,
             },
             numberToHex(stateBlock.number),
         ],
@@ -152,6 +160,7 @@ export async function executePlan(params) {
         stateBlockNumber: stateBlock.number,
         stateBlockHash: stateBlock.hash,
         stateBlockTimestamp: stateBlock.timestamp,
+        parentHashCheck,
     });
     // Reorg window: the pinned state block must still carry the same hash
     // after simulation, or the result may describe a different chain tip.

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

@@ -65,5 +65,6 @@ export declare function parseSimulationResponse(params: {
     readonly stateBlockNumber: bigint;
     readonly stateBlockHash: Hex;
     readonly stateBlockTimestamp: bigint;
+    readonly parentHashCheck: boolean;
 }): SimulationExecution;
 export {};

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

@@ -54,8 +54,10 @@ export function parseSimulationResponse(params) {
     }
     // Anvil re-hashes the pinned block, so only the geth-style successor can be
     // pinned by hash: it must report a parentHash (geth always does) equal to
-    // the pinned state block hash.
-    if (blockNumber === params.stateBlockNumber + 1n &&
+    // the pinned state block hash. With `parentHashCheck` off (Stable by
+    // default) the block number, timestamp and reorg checks still apply.
+    if (params.parentHashCheck &&
+        blockNumber === params.stateBlockNumber + 1n &&
         block.parentHash !== params.stateBlockHash) {
         throw new InvalidSimulationResponseError(`eth_simulateV1 reported block ${blockNumber} whose parent ${String(block.parentHash)} is not the pinned state block hash ${params.stateBlockHash}; the node did not simulate on top of the pinned block.`, { context: errorContext });
     }

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

@@ -4,6 +4,10 @@ import type { ChainSimulationConfig, SimulationConfig } from "../../types.js";
  *
  * 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).
+ * the type already requires it at construction). Throws
+ * `SimulationValidationError` when `blockOverrides.gasLimit` is set but is
+ * not a positive bigint, or `parentHashCheck` is set but is not a boolean, so a
+ * misconfiguration never surfaces as a bypassable
+ * `ExternalServiceError`.
  */
 export declare function resolveChain(config: SimulationConfig, chainId: number): ChainSimulationConfig;

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

@@ -1,14 +1,25 @@
-import { UnsupportedChainError } from "../../errors.js";
+import { SimulationValidationError, UnsupportedChainError, } from "../../errors.js";
 /**
  * Stage 2 of the simulate() pipeline.
  *
  * 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).
+ * the type already requires it at construction). Throws
+ * `SimulationValidationError` when `blockOverrides.gasLimit` is set but is
+ * not a positive bigint, or `parentHashCheck` is set but is not a boolean, so a
+ * misconfiguration never surfaces as a bypassable
+ * `ExternalServiceError`.
  */
 export function resolveChain(config, chainId) {
     const entry = config.chains.get(chainId);
     if (!entry?.simulateV1Url)
         throw new UnsupportedChainError(chainId);
+    const gasLimit = entry.blockOverrides?.gasLimit;
+    if (gasLimit !== undefined &&
+        (typeof gasLimit !== "bigint" || gasLimit <= 0n))
+        throw new SimulationValidationError(`Chain ${chainId} blockOverrides.gasLimit must be a positive bigint, got "${String(gasLimit)}" (${typeof gasLimit}). Pass a bigint greater than 0n or omit gasLimit.`, ["blockOverrides.gasLimit: must be a positive bigint"]);
+    const parentHashCheck = entry.parentHashCheck;
+    if (parentHashCheck !== undefined && typeof parentHashCheck !== "boolean")
+        throw new SimulationValidationError(`Chain ${chainId} parentHashCheck must be a boolean, got "${String(parentHashCheck)}" (${typeof parentHashCheck}). Pass true or false, or omit parentHashCheck.`, ["parentHashCheck: must be a boolean"]);
     return entry;
 }

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,9 @@ export async function runSimulation(params) {
         client,
         plan,
         stateBlock: pinnedBlock,
+        validation: monad,
+        blockGasLimit: chain.blockOverrides?.gasLimit,
+        parentHashCheck: chain.parentHashCheck ?? request.chainId !== ChainId.StableMainnet,
     });
     const userCalls = execution.calls
         .filter((call) => call.planned.type === "transaction")

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

@@ -34,10 +34,12 @@ 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.
+ * @param config - Required per-chain `eth_simulateV1` URL, optional per-chain
+ *   `blockOverrides.gasLimit` and `parentHashCheck`, optional logger, and the
+ *   overall timeout budget.
  * @param params - Per-call simulation input.
  * @param params.chainId - Chain id the bundle targets; must match the endpoint.
  * @param params.transactions - The bundle's transactions, in execution order.
@@ -47,10 +49,13 @@ 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
+ *   authorizations, malformed limits, unknown fields, a `"pending"` block tag, a
+ *   `blockOverrides.gasLimit` that is not a positive bigint, a `parentHashCheck`
+ *   that is not a boolean, or share quotes for
  *   `blueSupplyCollateral` / `blueWithdrawCollateral`).
  * @throws {ConsumerLimitViolationError} when a declared `limits` bound is
  *   violated by the observed effects.
@@ -64,7 +69,7 @@ import type { SimulationConfig } from "../types.js";
  * @throws {InvalidSimulationResponseError} when the node response cannot be
  *   trusted (bad shape, call-count mismatch, block that is neither the pinned
  *   state block nor its immediate successor, a successor with a mismatched
- *   `parentHash`, a block timestamp earlier than the pinned block's, a
+ *   `parentHash` (unless `parentHashCheck` is off; off by default on Stable, chain 988), a block timestamp earlier than the pinned block's, a
  *   malformed per-call result, a quoted balance/position read whose non-empty
  *   return data cannot be decoded, a state-block hash that changed or a pinned
  *   block that vanished mid-flight, or an

package/lib/esm/simulate/simulate.js

@@ -33,10 +33,12 @@ 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.
+ * @param config - Required per-chain `eth_simulateV1` URL, optional per-chain
+ *   `blockOverrides.gasLimit` and `parentHashCheck`, optional logger, and the
+ *   overall timeout budget.
  * @param params - Per-call simulation input.
  * @param params.chainId - Chain id the bundle targets; must match the endpoint.
  * @param params.transactions - The bundle's transactions, in execution order.
@@ -46,10 +48,13 @@ 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
+ *   authorizations, malformed limits, unknown fields, a `"pending"` block tag, a
+ *   `blockOverrides.gasLimit` that is not a positive bigint, a `parentHashCheck`
+ *   that is not a boolean, or share quotes for
  *   `blueSupplyCollateral` / `blueWithdrawCollateral`).
  * @throws {ConsumerLimitViolationError} when a declared `limits` bound is
  *   violated by the observed effects.
@@ -63,7 +68,7 @@ import { runSimulation } from "./run-simulation.js";
  * @throws {InvalidSimulationResponseError} when the node response cannot be
  *   trusted (bad shape, call-count mismatch, block that is neither the pinned
  *   state block nor its immediate successor, a successor with a mismatched
- *   `parentHash`, a block timestamp earlier than the pinned block's, a
+ *   `parentHash` (unless `parentHashCheck` is off; off by default on Stable, chain 988), a block timestamp earlier than the pinned block's, a
  *   malformed per-call result, a quoted balance/position read whose non-empty
  *   return data cannot be decoded, a state-block hash that changed or a pinned
  *   block that vanished mid-flight, or an

package/lib/esm/types.d.ts

@@ -3,6 +3,21 @@ import type { Address, Hex } from "viem";
 export interface ChainSimulationConfig {
     /** JSON-RPC URL supporting `eth_simulateV1`. Required for every configured chain. */
     readonly simulateV1Url: string;
+    /**
+     * Block overrides forwarded to `eth_simulateV1` as the simulated block's
+     * `blockOverrides`. Omitted fields leave the node's defaults untouched.
+     */
+    readonly blockOverrides?: {
+        /** Gas limit of the simulated block. Omitted: no gas limit override is sent. */
+        readonly gasLimit?: bigint;
+    };
+    /**
+     * Whether a simulated successor block's `parentHash` must equal the pinned
+     * state block hash. Block number, timestamp and reorg checks always run.
+     * Omitted: on everywhere except Stable (988), whose nodes report a
+     * `parentHash` that never matches the pinned block.
+     */
+    readonly parentHashCheck?: boolean;
 }
 /**
  * Top-level configuration for `simulate`.
@@ -145,7 +160,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.1.0",
   "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",