@morpho-org/evm-simulation 5.0.1 → 6.0.0

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

@@ -1,63 +1,53 @@
-import { type Client, type PublicClient } from "viem";
-import type { SimulationMode } from "../../params.js";
+import { type Client } from "viem";
+import type { StateBlock } 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";
+type RpcLabel = "eth_getBlock" | "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>;
 /**
  * Execute an {@link ExecutionPlan} through a single `eth_simulateV1` call and
- * collect the pinned execution.
+ * collect the pinned execution. This is the boundary's only RPC request.
  *
- * 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.
- *
- * The boundary performs these steps:
+ * The caller resolves (or supplies) the state block before this boundary.
  *
  * 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`
+ *    calls with their per-call `from` and `chainId`, `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.
+ *    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
- *    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
+ * 2. **Response validation** — 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.
+ * @param params - Shared simulation client, execution plan (its request
+ *   `chainId` is sent on every call), 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,
  *   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).
+ *   trusted (bad shape, call-count mismatch, block other than the state block
+ *   or its successor, a block timestamp earlier than the state block's, or a
+ *   per-call result that fails normalization).
+ * @throws {InvalidChainIdError} When the node rejects the request `chainId`
+ *   because it serves another chain (a subclass of
+ *   `InvalidSimulationResponseError` sharing its `name`/`code`;
+ *   `instanceof InvalidChainIdError` tells them apart).
  * @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
@@ -65,9 +55,11 @@ export declare function assertEndpointChain(params: {
  * @internal
  */
 export declare function executePlan(params: {
-    client: Client & Pick<PublicClient, "getBlock">;
+    client: Client;
     plan: ExecutionPlan;
-    stateBlock: PinnedBlock;
+    stateBlock: StateBlock;
     validation: boolean;
+    blockGasLimit?: bigint | undefined;
+    parentHashCheck: boolean;
 }): Promise<SimulationExecution>;
 export {};

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

@@ -1,5 +1,5 @@
-import { BaseError, BlockNotFoundError, ExecutionRevertedError, InsufficientFundsError, numberToHex, } from "viem";
-import { ExternalServiceError, InvalidSimulationResponseError, SimulationPackageError, SimulationRevertedError, } from "../../errors.js";
+import { BaseError, ExecutionRevertedError, InsufficientFundsError, numberToHex, } from "viem";
+import { ExternalServiceError, InvalidChainIdError, SimulationPackageError, SimulationRevertedError, } from "../../errors.js";
 import { parseSimulationResponse } from "./parse-response.js";
 /**
  * Classify a node-level revert: viem's `ExecutionRevertedError`, or a raw
@@ -39,6 +39,15 @@ const toBoundaryError = (label, error) => {
         reverted.cause = error;
         return reverted;
     }
+    // A wrong-chain endpoint is misconfiguration, not an outage: callers must
+    // not bypass it like an `ExternalServiceError`. Each node words the per-call
+    // `chainId` rejection differently: geth "chainId does not match node's",
+    // Anvil "invalid chain id for signer", Monad "Invalid chain ID: expected …".
+    if (label === "eth_simulateV1" &&
+        error instanceof Error &&
+        /chainId does not match node's|invalid chain id/i.test(error.message)) {
+        return new InvalidChainIdError(`eth_simulateV1 endpoint rejected the request chainId: ${safeMessage(error)}. Point SimulationConfig.chains at an RPC URL for this chain.`, { cause: error });
+    }
     return new ExternalServiceError(`${label} error: ${safeMessage(error)}`, {
         cause: error,
     });
@@ -52,69 +61,48 @@ export const rpc = async (label, call) => {
         throw toBoundaryError(label, error);
     }
 };
-/** Validate the endpoint identity through the same URL-safe RPC boundary. @internal */
-export async function assertEndpointChain(params) {
-    const { client, chainId, mode, blockNumber } = params;
-    const rpcChainId = await rpc("eth_chainId", () => client.getChainId());
-    if (rpcChainId === chainId)
-        return;
-    throw new InvalidSimulationResponseError(`The RPC configured for chain ${chainId} reports chain ${rpcChainId}. Fix SimulationConfig.chains.`, {
-        ...(blockNumber !== undefined
-            ? {
-                context: {
-                    stage: "transport",
-                    chainId,
-                    mode,
-                    blockNumber,
-                },
-            }
-            : {}),
-    });
-}
 /**
  * Execute an {@link ExecutionPlan} through a single `eth_simulateV1` call and
- * collect the pinned execution.
- *
- * 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.
+ * collect the pinned execution. This is the boundary's only RPC request.
  *
- * The boundary performs these steps:
+ * The caller resolves (or supplies) the state block before this boundary.
  *
  * 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`
+ *    calls with their per-call `from` and `chainId`, `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.
+ *    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
- *    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
+ * 2. **Response validation** — 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.
+ * @param params - Shared simulation client, execution plan (its request
+ *   `chainId` is sent on every call), 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,
  *   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).
+ *   trusted (bad shape, call-count mismatch, block other than the state block
+ *   or its successor, a block timestamp earlier than the state block's, or a
+ *   per-call result that fails normalization).
+ * @throws {InvalidChainIdError} When the node rejects the request `chainId`
+ *   because it serves another chain (a subclass of
+ *   `InvalidSimulationResponseError` sharing its `name`/`code`;
+ *   `instanceof InvalidChainIdError` tells them apart).
  * @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
@@ -122,14 +110,18 @@ 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) => ({
+                            chainId: numberToHex(plan.request.chainId),
                             from: call.transaction.from,
                             to: call.transaction.to,
                             data: call.transaction.data,
@@ -143,42 +135,12 @@ export async function executePlan(params) {
             numberToHex(stateBlock.number),
         ],
     }));
-    // Response parsing is validation, not transport — it runs before the
-    // reorg re-fetch so evidence already in hand reaches the caller as
-    // InvalidSimulationResponseError / SimulationRevertedError instead of
-    // being downgraded to a bypassable ExternalServiceError by a failing
-    // re-fetch.
-    const execution = parseSimulationResponse({
+    return parseSimulationResponse({
         plan,
         blocks: response,
         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.
-    const stateBlockAfter = await rpc("eth_getBlock", () => client.getBlock({ blockNumber: stateBlock.number })).catch((error) => {
-        if (error instanceof ExternalServiceError &&
-            error.cause instanceof BlockNotFoundError)
-            return error;
-        throw error;
-    });
-    if (stateBlockAfter instanceof ExternalServiceError ||
-        stateBlockAfter.hash !== stateBlock.hash) {
-        const after = stateBlockAfter instanceof ExternalServiceError
-            ? "unavailable"
-            : stateBlockAfter.hash;
-        throw new InvalidSimulationResponseError(`State block ${stateBlock.number} hash changed during simulation (reorg): ${stateBlock.hash} became ${after}. Re-submit the simulation.`, {
-            context: {
-                stage: "transport",
-                chainId: plan.request.chainId,
-                mode: plan.request.mode,
-                blockNumber: stateBlock.number,
-            },
-            ...(stateBlockAfter instanceof ExternalServiceError && {
-                cause: stateBlockAfter.cause,
-            }),
-        });
-    }
-    return execution;
 }

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

@@ -1 +1 @@
-export { assertEndpointChain, executePlan } from "./eth-simulate-v1.js";
+export { executePlan } from "./eth-simulate-v1.js";

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

@@ -1 +1 @@
-export { assertEndpointChain, executePlan } from "./eth-simulate-v1.js";
+export { executePlan } from "./eth-simulate-v1.js";

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 and timestamp 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/backends/resolve-pinned-block.d.ts

@@ -1,16 +1,10 @@
-import type { BlockTag, Client, Hex } from "viem";
-/** One concrete canonical block: the state anchor for every pinned read. @internal */
-export interface PinnedBlock {
-    readonly number: bigint;
-    readonly hash: Hex;
-    readonly timestamp: bigint;
-}
+import type { BlockTag, Client } from "viem";
+import type { StateBlock } from "../../params.js";
 /**
  * Resolve the requested state block exactly once so `latest` cannot drift.
  *
- * Every downstream read and the `eth_simulateV1` call pin this number; the
- * execution boundary re-fetches the hash afterwards to detect a reorg that
- * swapped the block mid-flight.
+ * Every downstream read and the `eth_simulateV1` call pin this number. Skipped
+ * when the caller supplies `SimulateParams.block`.
  *
  * @param params - Resolution parameters.
  * @param params.client - Shared simulation client (created by
@@ -19,7 +13,7 @@ export interface PinnedBlock {
  *   `latest`.
  * @param params.signal - Optional pipeline abort signal; checked around the
  *   request so an aborted pipeline never produces a pin.
- * @returns The resolved {@link PinnedBlock}.
+ * @returns The resolved {@link StateBlock}.
  * @throws {ExternalServiceError} For transport failures, timeouts, or an
  *   aborted signal.
  * @throws {InvalidSimulationResponseError} When the node returns a block
@@ -30,4 +24,4 @@ export declare function resolvePinnedBlock(params: {
     readonly client: Client;
     readonly blockNumber?: bigint | BlockTag;
     readonly signal?: AbortSignal;
-}): Promise<PinnedBlock>;
+}): Promise<StateBlock>;

package/lib/esm/simulate/backends/resolve-pinned-block.js

@@ -4,9 +4,8 @@ import { rpc } from "./eth-simulate-v1.js";
 /**
  * Resolve the requested state block exactly once so `latest` cannot drift.
  *
- * Every downstream read and the `eth_simulateV1` call pin this number; the
- * execution boundary re-fetches the hash afterwards to detect a reorg that
- * swapped the block mid-flight.
+ * Every downstream read and the `eth_simulateV1` call pin this number. Skipped
+ * when the caller supplies `SimulateParams.block`.
  *
  * @param params - Resolution parameters.
  * @param params.client - Shared simulation client (created by
@@ -15,7 +14,7 @@ import { rpc } from "./eth-simulate-v1.js";
  *   `latest`.
  * @param params.signal - Optional pipeline abort signal; checked around the
  *   request so an aborted pipeline never produces a pin.
- * @returns The resolved {@link PinnedBlock}.
+ * @returns The resolved {@link StateBlock}.
  * @throws {ExternalServiceError} For transport failures, timeouts, or an
  *   aborted signal.
  * @throws {InvalidSimulationResponseError} When the node returns a block

package/lib/esm/simulate/pipeline/bundles-retention.d.ts

@@ -8,7 +8,7 @@ interface AssertNoBundlesRetentionParams {
 /**
  * Assert that no value is retained by standalone `bundles` periphery contracts
  * (`VaultExitBundlesV1`, `VaultBundlesV1`, `BlueBundlesV1`) or by
- * `MidnightBundlesV1` (`midnightBundles`).
+ * `MidnightBundlesV2` (`midnightBundlesV2`).
  *
  * Uses net flow (inbound minus outbound) per (restricted address, token) pair.
  * These contracts legitimately receive tokens as an intermediary (user →
@@ -33,7 +33,7 @@ interface AssertNoBundlesRetentionParams {
  *
  * @internal Internal pipeline stage, composed by `simulate`; not part of the
  *   package's public API (only re-exported from the internal pipeline barrel).
- * @param params.chainId - Chain whose blue-sdk `bundles` and `midnightBundles`
+ * @param params.chainId - Chain whose blue-sdk `bundles` and `midnightBundlesV2`
  *   registry entries define the restricted address set. Chains cataloging
  *   neither are skipped (a `logger.warn` records the skip).
  * @param params.transfers - Parsed ERC20 / WETH9 transfer flows (plus the
@@ -45,7 +45,7 @@ interface AssertNoBundlesRetentionParams {
  * @returns Nothing. Returns silently when no restricted contract retains value
  *   above `DUST_THRESHOLD`; otherwise throws.
  * @throws {BlacklistViolationError} when net inbound flow to a restricted
- *   `bundles` or `midnightBundles` contract exceeds `DUST_THRESHOLD` for any
+ *   `bundles` or `midnightBundlesV2` contract exceeds `DUST_THRESHOLD` for any
  *   token.
  */
 export declare function assertNoBundlesRetention(params: AssertNoBundlesRetentionParams): void;

package/lib/esm/simulate/pipeline/bundles-retention.js

@@ -15,7 +15,7 @@ const DUST_THRESHOLD = 100n;
 /**
  * Assert that no value is retained by standalone `bundles` periphery contracts
  * (`VaultExitBundlesV1`, `VaultBundlesV1`, `BlueBundlesV1`) or by
- * `MidnightBundlesV1` (`midnightBundles`).
+ * `MidnightBundlesV2` (`midnightBundlesV2`).
  *
  * Uses net flow (inbound minus outbound) per (restricted address, token) pair.
  * These contracts legitimately receive tokens as an intermediary (user →
@@ -40,7 +40,7 @@ const DUST_THRESHOLD = 100n;
  *
  * @internal Internal pipeline stage, composed by `simulate`; not part of the
  *   package's public API (only re-exported from the internal pipeline barrel).
- * @param params.chainId - Chain whose blue-sdk `bundles` and `midnightBundles`
+ * @param params.chainId - Chain whose blue-sdk `bundles` and `midnightBundlesV2`
  *   registry entries define the restricted address set. Chains cataloging
  *   neither are skipped (a `logger.warn` records the skip).
  * @param params.transfers - Parsed ERC20 / WETH9 transfer flows (plus the
@@ -52,12 +52,12 @@ const DUST_THRESHOLD = 100n;
  * @returns Nothing. Returns silently when no restricted contract retains value
  *   above `DUST_THRESHOLD`; otherwise throws.
  * @throws {BlacklistViolationError} when net inbound flow to a restricted
- *   `bundles` or `midnightBundles` contract exceeds `DUST_THRESHOLD` for any
+ *   `bundles` or `midnightBundlesV2` contract exceeds `DUST_THRESHOLD` for any
  *   token.
  */
 export function assertNoBundlesRetention(params) {
     const { chainId, transfers, assetChanges, logger } = params;
-    // Standalone bundles contracts and `MidnightBundlesV1` are transient
+    // Standalone bundles contracts and `MidnightBundlesV2` are transient
     // intermediaries that route user value and must never retain it.
     let addresses;
     try {
@@ -79,8 +79,8 @@ export function assertNoBundlesRetention(params) {
         for (const addr of Object.values(addresses.bundles).filter(isDefined))
             restrictedAddresses.add(getAddress(addr));
     }
-    if (addresses.midnightBundles) {
-        restrictedAddresses.add(getAddress(addresses.midnightBundles));
+    if (addresses.midnightBundlesV2) {
+        restrictedAddresses.add(getAddress(addresses.midnightBundlesV2));
     }
     if (restrictedAddresses.size === 0) {
         // blue-sdk knows the chain but cataloged no restricted intermediary for it.

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/request/parse-request.d.ts

@@ -1,7 +1,7 @@
 import { type Address, type BlockTag, type Hex } from "viem";
 import type { SimulationAuthorization } from "../../authorizations.js";
 import type { SimulationLimits } from "../../limits.js";
-import { type SimulateParams, type SimulationMode } from "../../params.js";
+import { type SimulateParams, type SimulationMode, type StateBlock } from "../../params.js";
 /** A normalized user transaction: checksummed addresses, `value` defaulted to `0n`.
  * @internal
  */
@@ -21,6 +21,7 @@ export interface ParsedRequest {
     /** Always empty in final mode. */
     readonly authorizations: readonly SimulationAuthorization[];
     readonly blockNumber?: bigint | Exclude<BlockTag, "pending">;
+    readonly block?: StateBlock;
     readonly limits?: SimulationLimits;
 }
 /**

package/lib/esm/simulate/request/parse-request.js

@@ -49,6 +49,7 @@ const PERMIT2_MESSAGE_KEYS = PERMIT2_TRANSFER_FIELDS.map((field) => field.name);
 const PERMIT2_PERMITTED_KEYS = ["token", "amount"];
 const BLUE_AUTHORIZATION_MESSAGE_KEYS = BLUE_AUTHORIZATION_FIELDS.map((field) => field.name);
 const TRANSACTION_KEYS = ["from", "to", "data", "value"];
+const BLOCK_KEYS = ["number", "hash", "timestamp"];
 const LIMITS_KEYS = ["operations"];
 const AUTHORIZATION_KEYS = {
     erc20Approval: ["type", "token", "owner", "spender", "amount"],
@@ -567,6 +568,7 @@ export function parseRequest(input) {
             "chainId",
             "transactions",
             "blockNumber",
+            "block",
             "mode",
             "authorizations",
             "limits",
@@ -649,6 +651,24 @@ export function parseRequest(input) {
             }
         }
     }
+    // block
+    const rawBlock = input.block;
+    let block;
+    if (rawBlock !== undefined) {
+        if (!isRecord(rawBlock)) {
+            fieldErrors.push("block: must be an object");
+        }
+        else {
+            check.keys(rawBlock, { allow: BLOCK_KEYS, path: "block" });
+            const number = check.uint256(readField(rawBlock, "number"), "block.number");
+            const hash = check.bytes32(readField(rawBlock, "hash"), "block.hash");
+            const timestamp = check.uint256(readField(rawBlock, "timestamp"), "block.timestamp");
+            if (number !== undefined && hash !== undefined && timestamp !== undefined)
+                block = { number, hash: hash.toLowerCase(), timestamp };
+        }
+        if (rawBlockNumber !== undefined)
+            fieldErrors.push("block: cannot be combined with blockNumber");
+    }
     // authorizations
     const rawAuthorizations = input.authorizations;
     const authorizations = [];
@@ -751,6 +771,7 @@ export function parseRequest(input) {
         transactions,
         authorizations: mode === "preview" ? authorizations : [],
         ...(blockNumber !== undefined ? { blockNumber } : {}),
+        ...(block !== undefined ? { block } : {}),
         ...(normalizedLimits !== undefined ? { limits: normalizedLimits } : {}),
     });
 }

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

@@ -4,7 +4,7 @@ import { zeroAddress } from "viem";
 import { InvalidSimulationResponseError, UnsupportedChainError, } from "../errors.js";
 import { groupAssetChanges } from "./asset-changes.js";
 import { createSimulationClient } from "./backends/client.js";
-import { assertEndpointChain, executePlan } from "./backends/index.js";
+import { executePlan } from "./backends/index.js";
 import { resolveAssets } from "./backends/resolve-assets.js";
 import { resolvePinnedBlock } from "./backends/resolve-pinned-block.js";
 import { parseTransfers } from "./parsing/index.js";
@@ -42,21 +42,16 @@ export async function runSimulation(params) {
     if (requiresMorpho && addresses?.blue == null)
         throw new UnsupportedChainError(request.chainId);
     const morpho = addresses?.blue ?? zeroAddress;
-    await assertEndpointChain({
-        client,
-        chainId: request.chainId,
-        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 ?? (monad ? "finalized" : undefined),
-        signal,
-    });
+    const pinnedBlock = request.block ??
+        (await resolvePinnedBlock({
+            client,
+            blockNumber: request.blockNumber ?? (monad ? "finalized" : undefined),
+            signal,
+        }));
     // With no calldata decoding, the caller's declared `limits.operations`
     // entries are the operations: subjects for state reads and per-operation
     // checks come straight from the limit list.
@@ -82,12 +77,14 @@ export async function runSimulation(params) {
         preparations,
         reads: observations.reads,
     });
-    // Execute against the block resolved once above; the boundary rechecks its hash.
+    // Execute against the block resolved once above.
     const execution = await executePlan({
         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")