@morpho-org/evm-simulation 5.0.1 → 5.1.0

package/README.md

@@ -46,7 +46,7 @@ try {
 }
 ```
 
-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.
+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.
 

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

@@ -29,7 +29,9 @@ export declare function assertEndpointChain(params: {
  *    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.
+ *    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.
@@ -48,7 +50,8 @@ export declare function assertEndpointChain(params: {
  * no fallback backend.
  *
  * @param params - Shared simulation client, execution plan, already-pinned
- *   state block, and the `validation` flag to send.
+ *   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,
@@ -69,5 +72,7 @@ export declare function executePlan(params: {
     plan: ExecutionPlan;
     stateBlock: PinnedBlock;
     validation: boolean;
+    blockGasLimit?: bigint | undefined;
+    parentHashCheck: boolean;
 }): Promise<SimulationExecution>;
 export {};

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

@@ -92,7 +92,9 @@ async function assertEndpointChain(params) {
  *    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.
+ *    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.
@@ -111,7 +113,8 @@ async function assertEndpointChain(params) {
  * no fallback backend.
  *
  * @param params - Shared simulation client, execution plan, already-pinned
- *   state block, and the `validation` flag to send.
+ *   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,
@@ -128,13 +131,16 @@ async function assertEndpointChain(params) {
  * @internal
  */
 async function executePlan(params) {
-    const { client, plan, stateBlock, validation } = 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,
@@ -160,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

@@ -91,6 +91,8 @@ async function runSimulation(params) {
         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

@@ -37,8 +37,9 @@ import type { SimulationConfig } from "../types.js";
  * 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.
@@ -52,7 +53,9 @@ import type { SimulationConfig } from "../types.js";
  *   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 +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

@@ -39,8 +39,9 @@ const run_simulation_js_1 = require("./run-simulation.js");
  * 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.
@@ -54,7 +55,9 @@ const run_simulation_js_1 = require("./run-simulation.js");
  *   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.
@@ -68,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`.

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

@@ -29,7 +29,9 @@ export declare function assertEndpointChain(params: {
  *    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.
+ *    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.
@@ -48,7 +50,8 @@ export declare function assertEndpointChain(params: {
  * no fallback backend.
  *
  * @param params - Shared simulation client, execution plan, already-pinned
- *   state block, and the `validation` flag to send.
+ *   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,
@@ -69,5 +72,7 @@ export declare function executePlan(params: {
     plan: ExecutionPlan;
     stateBlock: PinnedBlock;
     validation: boolean;
+    blockGasLimit?: bigint | undefined;
+    parentHashCheck: boolean;
 }): Promise<SimulationExecution>;
 export {};

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

@@ -86,7 +86,9 @@ export async function assertEndpointChain(params) {
  *    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.
+ *    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.
@@ -105,7 +107,8 @@ export async function assertEndpointChain(params) {
  * no fallback backend.
  *
  * @param params - Shared simulation client, execution plan, already-pinned
- *   state block, and the `validation` flag to send.
+ *   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,
@@ -122,13 +125,16 @@ export async function assertEndpointChain(params) {
  * @internal
  */
 export async function executePlan(params) {
-    const { client, plan, stateBlock, validation } = 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,
@@ -154,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

@@ -88,6 +88,8 @@ export async function runSimulation(params) {
         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

@@ -37,8 +37,9 @@ import type { SimulationConfig } from "../types.js";
  * 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.
@@ -52,7 +53,9 @@ import type { SimulationConfig } from "../types.js";
  *   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 +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

@@ -36,8 +36,9 @@ import { runSimulation } from "./run-simulation.js";
  * 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.
@@ -51,7 +52,9 @@ import { runSimulation } from "./run-simulation.js";
  *   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.
@@ -65,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`.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@morpho-org/evm-simulation",
   "description": "EVM simulation engine for Morpho transactions.",
-  "version": "5.0.1",
+  "version": "5.1.0",
   "author": "Morpho Association <contact@morpho.org>",
   "repository": {
     "type": "git",