@morpho-org/evm-simulation 5.0.1 → 6.0.0

package/README.md

@@ -46,11 +46,13 @@ 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 call inside `eth_simulateV1`, including preparation calls and state reads, carries the request's `chainId` as a hex quantity, so nodes that check it (geth, Anvil, Monad and Stable do) reject an endpoint on another chain with `InvalidChainIdError`.
+
+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 — supply a finalized block when passing `block`. 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 and timestamp 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.
 
-Upgrading from v4? See the [v4 → v5 migration guide](../../docs/migrations/evm-simulation-v4-to-v5.md) for the backend cutover.
+Upgrading from v4? See the [v4 → v5 migration guide](../../docs/migrations/evm-simulation-v4-to-v5.md) for the backend cutover. Upgrading from v5? See the [v5 → v6 migration guide](../../docs/migrations/evm-simulation-v5-to-v6.md) for the retention-guard address change.
 
 ### API surface
 
@@ -58,12 +60,12 @@ All symbols below are re-exported from the package root.
 
 - `simulate(config, params)` — run a bundle through the simulation pipeline.
 - Config types: `SimulationConfig`, `ChainSimulationConfig`, `SimulationLogger`.
-- Input types: `SimulateParams` (v5 shape: `mode`, `SimulationAuthorization` requests, `SimulationLimits`), `SimulationMode`, `SimulationTransaction`.
+- Input types: `SimulateParams` (v5 shape: `mode`, `SimulationAuthorization` requests, `SimulationLimits`), `SimulationMode`, `SimulationTransaction`, `StateBlock` (the optional `SimulateParams.block`: `{ number, hash, timestamp }`).
 - `toSimulationAuthorizations({ chainId, mode, blockNumber, owner, requirements })` — map morpho-sdk `ActionRequirement[]` onto `SimulationAuthorization[]` straight from `action.args` — nothing is decoded or validated; validation happens in `simulate()`'s request parser.
 - Authorizations and limits: `SimulationAuthorization` and its members (`Erc20ApprovalAuthorization`, `Erc2612PermitAuthorization`, `Permit2TransferAuthorization`, `BlueAuthorization`, `BlueAuthorizationSignature`) with their EIP-712 payloads (`Eip712Domain`, `Eip712Field`, `Erc2612PermitTypedData`, `Permit2TransferTypedData`, `BlueAuthorizationTypedData`); `SimulationLimits`, `OperationLimit`, and the shared `SlippageLimits` and `SlippageQuote`.
 - Slippage-check result types: `VerifiedSimulationResult`, `SimulationVerification`, `SimulatedOperation`, `AuthorizationPreparation`.
 - Result types: `SimulationResult`, `SimulationCall`, `Transfer`, `AccountAssetChanges`, `AssetChange`, `RawLog`.
-- Errors: `SimulationPackageError` (abstract base — `instanceof` it to catch any package error), `SimulationRevertedError`, `BlacklistViolationError`, `ExternalServiceError`, `SimulationValidationError`, `UnsupportedChainError`, and the verification errors `UnsupportedOperationError`, `InvalidSimulationResponseError`, `MissingVerificationEvidenceError`, `AuthorizationRequestMismatchError`, `ConsumerLimitViolationError`, `UnexpectedSimulationError`.
+- Errors: `SimulationPackageError` (abstract base — `instanceof` it to catch any package error), `SimulationRevertedError`, `BlacklistViolationError`, `ExternalServiceError`, `SimulationValidationError`, `UnsupportedChainError`, and the verification errors `UnsupportedOperationError`, `InvalidSimulationResponseError`, `InvalidChainIdError`, `MissingVerificationEvidenceError`, `AuthorizationRequestMismatchError`, `ConsumerLimitViolationError`, `UnexpectedSimulationError`.
 - Error helpers: `SIMULATION_ERROR_CODES` / `SimulationErrorCode` (every `error.code`), `SimulationErrorContext` (frozen `error.context`; union of the per-stage `SimulationValidationContext`, `SimulationTransportContext`, `SimulationPreparationContext`, `SimulationExecutionContext`, `SimulationVerificationContext`), `SimulationStage`, `SimulationExecutionReason` (`SimulationRevertedError.reasonCode`), `isSimulationPackageError` (structural guard narrowing to `SimulationPackageError`), `RetainedAsset`.
 - Verification vocabulary: `SIMULATION_MODES` / `SimulationMode`, `OPERATION_TYPES` / `OperationType`, `BLUE_MARKET_OPERATION_TYPES` / `BlueMarketOperationType`, `VAULT_OPERATION_TYPES` / `VaultOperationType`, `SimulationOperationSubject` and its members `BlueMarketOperationSubject`, `BlueRefinanceSubject`, `VaultOperationSubject`, `VaultV1MigrateToV2Subject` (operation groups and the operation-keyed subject union that key limit-bound verification `SimulationErrorContext`s).
 ### Optional limits

package/lib/cjs/errors.d.ts

@@ -136,7 +136,7 @@ export interface RetainedAsset {
 }
 /**
  * Thrown when net value above the dust threshold is retained by a restricted bundles contract
- * (VaultExitBundlesV1, VaultBundlesV1, BlueBundlesV1 or MidnightBundlesV1) after simulation;
+ * (VaultExitBundlesV1, VaultBundlesV1, BlueBundlesV1 or MidnightBundlesV2) after simulation;
  * pass-through flows and net outflows are allowed. Never bypassable.
  */
 export declare class BlacklistViolationError extends SimulationPackageError {
@@ -175,11 +175,26 @@ export declare class UnsupportedOperationError extends SimulationPackageError {
     readonly name = "UnsupportedOperationError";
     readonly code = "UNSUPPORTED_OPERATION";
 }
-/** The simulation backend returned a response that cannot be parsed. */
+/**
+ * The simulation backend returned a response that cannot be parsed.
+ * {@link InvalidChainIdError} subclasses this class and shares its `name`
+ * and `code`; check `instanceof InvalidChainIdError` first to tell the two
+ * apart.
+ */
 export declare class InvalidSimulationResponseError extends SimulationPackageError {
     readonly name = "InvalidSimulationResponseError";
     readonly code = "INVALID_SIMULATION_RESPONSE";
 }
+/**
+ * The node rejected the request `chainId`: the endpoint is on a different
+ * chain than configured. This is misconfiguration, not an outage, so unlike
+ * {@link ExternalServiceError} callers must not bypass it.
+ * Extends {@link InvalidSimulationResponseError} and shares its `name` and
+ * `code`, so v5 callers that match on either still catch it;
+ * `instanceof InvalidChainIdError` is how to tell the two apart.
+ */
+export declare class InvalidChainIdError extends InvalidSimulationResponseError {
+}
 /** State needed to verify an operation could not be fetched or derived. */
 export declare class MissingVerificationEvidenceError extends SimulationPackageError {
     readonly name = "MissingVerificationEvidenceError";

package/lib/cjs/errors.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.UnexpectedSimulationError = exports.ConsumerLimitViolationError = exports.AuthorizationRequestMismatchError = exports.MissingVerificationEvidenceError = exports.InvalidSimulationResponseError = exports.UnsupportedOperationError = exports.UnsupportedChainError = exports.SimulationValidationError = exports.ExternalServiceError = exports.BlacklistViolationError = exports.SimulationRevertedError = exports.SimulationPackageError = exports.SIMULATION_ERROR_CODES = void 0;
+exports.UnexpectedSimulationError = exports.ConsumerLimitViolationError = exports.AuthorizationRequestMismatchError = exports.MissingVerificationEvidenceError = exports.InvalidChainIdError = exports.InvalidSimulationResponseError = exports.UnsupportedOperationError = exports.UnsupportedChainError = exports.SimulationValidationError = exports.ExternalServiceError = exports.BlacklistViolationError = exports.SimulationRevertedError = exports.SimulationPackageError = exports.SIMULATION_ERROR_CODES = void 0;
 exports.isSimulationPackageError = isSimulationPackageError;
 const limits_js_1 = require("./limits.js");
 const params_js_1 = require("./params.js");
@@ -66,7 +66,7 @@ class SimulationRevertedError extends SimulationPackageError {
 exports.SimulationRevertedError = SimulationRevertedError;
 /**
  * Thrown when net value above the dust threshold is retained by a restricted bundles contract
- * (VaultExitBundlesV1, VaultBundlesV1, BlueBundlesV1 or MidnightBundlesV1) after simulation;
+ * (VaultExitBundlesV1, VaultBundlesV1, BlueBundlesV1 or MidnightBundlesV2) after simulation;
  * pass-through flows and net outflows are allowed. Never bypassable.
  */
 class BlacklistViolationError extends SimulationPackageError {
@@ -120,12 +120,28 @@ class UnsupportedOperationError extends SimulationPackageError {
     code = "UNSUPPORTED_OPERATION";
 }
 exports.UnsupportedOperationError = UnsupportedOperationError;
-/** The simulation backend returned a response that cannot be parsed. */
+/**
+ * The simulation backend returned a response that cannot be parsed.
+ * {@link InvalidChainIdError} subclasses this class and shares its `name`
+ * and `code`; check `instanceof InvalidChainIdError` first to tell the two
+ * apart.
+ */
 class InvalidSimulationResponseError extends SimulationPackageError {
     name = "InvalidSimulationResponseError";
     code = "INVALID_SIMULATION_RESPONSE";
 }
 exports.InvalidSimulationResponseError = InvalidSimulationResponseError;
+/**
+ * The node rejected the request `chainId`: the endpoint is on a different
+ * chain than configured. This is misconfiguration, not an outage, so unlike
+ * {@link ExternalServiceError} callers must not bypass it.
+ * Extends {@link InvalidSimulationResponseError} and shares its `name` and
+ * `code`, so v5 callers that match on either still catch it;
+ * `instanceof InvalidChainIdError` is how to tell the two apart.
+ */
+class InvalidChainIdError extends InvalidSimulationResponseError {
+}
+exports.InvalidChainIdError = InvalidChainIdError;
 /** State needed to verify an operation could not be fetched or derived. */
 class MissingVerificationEvidenceError extends SimulationPackageError {
     name = "MissingVerificationEvidenceError";

package/lib/cjs/index.d.ts

@@ -1,9 +1,9 @@
 export type { BlueAuthorization, BlueAuthorizationSignature, BlueAuthorizationTypedData, Eip712Domain, Eip712Field, Erc20ApprovalAuthorization, Erc2612PermitAuthorization, Erc2612PermitTypedData, Permit2TransferAuthorization, Permit2TransferTypedData, SimulationAuthorization, } from "./authorizations.js";
 export type { RetainedAsset, SimulationErrorCode, SimulationErrorContext, SimulationExecutionContext, SimulationExecutionReason, SimulationPreparationContext, SimulationStage, SimulationTransportContext, SimulationValidationContext, SimulationVerificationContext, } from "./errors.js";
-export { AuthorizationRequestMismatchError, BlacklistViolationError, ConsumerLimitViolationError, ExternalServiceError, InvalidSimulationResponseError, isSimulationPackageError, MissingVerificationEvidenceError, SIMULATION_ERROR_CODES, SimulationPackageError, SimulationRevertedError, SimulationValidationError, UnexpectedSimulationError, UnsupportedChainError, UnsupportedOperationError, } from "./errors.js";
+export { AuthorizationRequestMismatchError, BlacklistViolationError, ConsumerLimitViolationError, ExternalServiceError, InvalidChainIdError, InvalidSimulationResponseError, isSimulationPackageError, MissingVerificationEvidenceError, SIMULATION_ERROR_CODES, SimulationPackageError, SimulationRevertedError, SimulationValidationError, UnexpectedSimulationError, UnsupportedChainError, UnsupportedOperationError, } from "./errors.js";
 export type { BlueMarketOperationSubject, BlueMarketOperationType, BlueRefinanceSubject, OperationLimit, OperationType, SimulationLimits, SimulationOperationSubject, SlippageLimits, SlippageQuote, VaultOperationSubject, VaultOperationType, VaultV1MigrateToV2Subject, } from "./limits.js";
 export { BLUE_MARKET_OPERATION_TYPES, OPERATION_TYPES, VAULT_OPERATION_TYPES, } from "./limits.js";
-export type { SimulateParams, SimulationMode, } from "./params.js";
+export type { SimulateParams, SimulationMode, StateBlock, } from "./params.js";
 export { SIMULATION_MODES } from "./params.js";
 export { toSimulationAuthorizations } from "./requirements/index.js";
 export type { AuthorizationPreparation, SimulatedOperation, SimulationVerification, VerifiedSimulationResult, } from "./result.js";

package/lib/cjs/index.js

@@ -1,13 +1,14 @@
 "use strict";
 // Public fns (via feature-folder barrels)
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.simulate = exports.toSimulationAuthorizations = exports.SIMULATION_MODES = exports.VAULT_OPERATION_TYPES = exports.OPERATION_TYPES = exports.BLUE_MARKET_OPERATION_TYPES = exports.UnsupportedOperationError = exports.UnsupportedChainError = exports.UnexpectedSimulationError = exports.SimulationValidationError = exports.SimulationRevertedError = exports.SimulationPackageError = exports.SIMULATION_ERROR_CODES = exports.MissingVerificationEvidenceError = exports.isSimulationPackageError = exports.InvalidSimulationResponseError = exports.ExternalServiceError = exports.ConsumerLimitViolationError = exports.BlacklistViolationError = exports.AuthorizationRequestMismatchError = void 0;
+exports.simulate = exports.toSimulationAuthorizations = exports.SIMULATION_MODES = exports.VAULT_OPERATION_TYPES = exports.OPERATION_TYPES = exports.BLUE_MARKET_OPERATION_TYPES = exports.UnsupportedOperationError = exports.UnsupportedChainError = exports.UnexpectedSimulationError = exports.SimulationValidationError = exports.SimulationRevertedError = exports.SimulationPackageError = exports.SIMULATION_ERROR_CODES = exports.MissingVerificationEvidenceError = exports.isSimulationPackageError = exports.InvalidSimulationResponseError = exports.InvalidChainIdError = exports.ExternalServiceError = exports.ConsumerLimitViolationError = exports.BlacklistViolationError = exports.AuthorizationRequestMismatchError = void 0;
 // Errors (for instanceof checks by consumers)
 var errors_js_1 = require("./errors.js");
 Object.defineProperty(exports, "AuthorizationRequestMismatchError", { enumerable: true, get: function () { return errors_js_1.AuthorizationRequestMismatchError; } });
 Object.defineProperty(exports, "BlacklistViolationError", { enumerable: true, get: function () { return errors_js_1.BlacklistViolationError; } });
 Object.defineProperty(exports, "ConsumerLimitViolationError", { enumerable: true, get: function () { return errors_js_1.ConsumerLimitViolationError; } });
 Object.defineProperty(exports, "ExternalServiceError", { enumerable: true, get: function () { return errors_js_1.ExternalServiceError; } });
+Object.defineProperty(exports, "InvalidChainIdError", { enumerable: true, get: function () { return errors_js_1.InvalidChainIdError; } });
 Object.defineProperty(exports, "InvalidSimulationResponseError", { enumerable: true, get: function () { return errors_js_1.InvalidSimulationResponseError; } });
 Object.defineProperty(exports, "isSimulationPackageError", { enumerable: true, get: function () { return errors_js_1.isSimulationPackageError; } });
 Object.defineProperty(exports, "MissingVerificationEvidenceError", { enumerable: true, get: function () { return errors_js_1.MissingVerificationEvidenceError; } });

package/lib/cjs/params.d.ts

@@ -1,4 +1,4 @@
-import type { BlockTag } from "viem";
+import type { BlockTag, Hex } from "viem";
 import type { SimulationAuthorization } from "./authorizations.js";
 import type { SimulationLimits } from "./limits.js";
 import type { SimulationTransaction } from "./types.js";
@@ -6,6 +6,15 @@ import type { SimulationTransaction } from "./types.js";
 export declare const SIMULATION_MODES: readonly ["preview", "final"];
 /** Simulation mode: `"preview"` accepts pending authorizations, `"final"` does not. */
 export type SimulationMode = (typeof SIMULATION_MODES)[number];
+/** A mined block the simulation runs on top of. */
+export interface StateBlock {
+    /** Block number the simulation runs on top of. */
+    readonly number: bigint;
+    /** Hash of that block; compared to the next block's `parentHash`. */
+    readonly hash: Hex;
+    /** Block timestamp in Unix seconds; the simulated block must not be earlier. */
+    readonly timestamp: bigint;
+}
 /**
  * Input to `simulate()`. `authorizations` is accepted only in "preview";
  * `mode` defaults to "final".
@@ -21,6 +30,16 @@ export interface SimulateParams {
      * "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">;
+    /** State block supplied by the caller, so `simulate()` skips the block
+     * lookup; with no asset metadata reads it then sends only `eth_simulateV1`.
+     * Cannot be combined with `blockNumber`.
+     * Not checked against the endpoint: `hash` is compared only when the node
+     * reports the next block (its `parentHash`) and `parentHashCheck` is on (off
+     * by default on Stable, 988), and `timestamp` only bounds the simulated
+     * block's timestamp. On Monad (143), supply a finalized block: `latest` is
+     * not final there, so the block at that number can change and fail the
+     * `parentHash` check. */
+    readonly block?: StateBlock;
     /** Caller-selected quotes and percentage tolerances. Omitted limits are unchecked. */
     readonly limits?: SimulationLimits;
 }

package/lib/cjs/requirements/requirements.js

@@ -133,6 +133,7 @@ function toSimulationAuthorizations(params) {
         }
         if ((0, morpho_sdk_1.isRequirementSignature)(requirement)) {
             const { action } = requirement;
+            const actionType = action.type;
             switch (action.type) {
                 case "permit":
                     return toErc2612Permit(action, ctx);
@@ -141,7 +142,7 @@ function toSimulationAuthorizations(params) {
                 case "authorization":
                     return toBlueAuthorizationSignature(action, ctx);
                 default:
-                    return unsupported(ctx)(`Signature requirement action type "${action.type}" is not supported. Only permit, permit2SignatureTransfer, and authorization signatures are supported`);
+                    return unsupported(ctx)(`Signature requirement action type "${actionType}" is not supported. Only permit, permit2SignatureTransfer, and authorization signatures are supported`);
             }
         }
         return unsupported(ctx)(`Requirement action type "${requirement.action.type}" is not supported. Only erc20Approval, blueAuthorization, permit, permit2SignatureTransfer, and authorization requirements are supported`);

package/lib/cjs/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/cjs/simulate/backends/eth-simulate-v1.js

@@ -1,7 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.rpc = void 0;
-exports.assertEndpointChain = assertEndpointChain;
 exports.executePlan = executePlan;
 const viem_1 = require("viem");
 const errors_js_1 = require("../../errors.js");
@@ -44,6 +43,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 errors_js_1.InvalidChainIdError(`eth_simulateV1 endpoint rejected the request chainId: ${safeMessage(error)}. Point SimulationConfig.chains at an RPC URL for this chain.`, { cause: error });
+    }
     return new errors_js_1.ExternalServiceError(`${label} error: ${safeMessage(error)}`, {
         cause: error,
     });
@@ -58,69 +66,48 @@ const rpc = async (label, call) => {
     }
 };
 exports.rpc = rpc;
-/** Validate the endpoint identity through the same URL-safe RPC boundary. @internal */
-async function assertEndpointChain(params) {
-    const { client, chainId, mode, blockNumber } = params;
-    const rpcChainId = await (0, exports.rpc)("eth_chainId", () => client.getChainId());
-    if (rpcChainId === chainId)
-        return;
-    throw new errors_js_1.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
@@ -128,14 +115,18 @@ 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) => ({
+                            chainId: (0, viem_1.numberToHex)(plan.request.chainId),
                             from: call.transaction.from,
                             to: call.transaction.to,
                             data: call.transaction.data,
@@ -149,42 +140,12 @@ async function executePlan(params) {
             (0, viem_1.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 = (0, parse_response_js_1.parseSimulationResponse)({
+    return (0, parse_response_js_1.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 (0, exports.rpc)("eth_getBlock", () => client.getBlock({ blockNumber: stateBlock.number })).catch((error) => {
-        if (error instanceof errors_js_1.ExternalServiceError &&
-            error.cause instanceof viem_1.BlockNotFoundError)
-            return error;
-        throw error;
-    });
-    if (stateBlockAfter instanceof errors_js_1.ExternalServiceError ||
-        stateBlockAfter.hash !== stateBlock.hash) {
-        const after = stateBlockAfter instanceof errors_js_1.ExternalServiceError
-            ? "unavailable"
-            : stateBlockAfter.hash;
-        throw new errors_js_1.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 errors_js_1.ExternalServiceError && {
-                cause: stateBlockAfter.cause,
-            }),
-        });
-    }
-    return execution;
 }

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

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

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

@@ -1,6 +1,5 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.executePlan = exports.assertEndpointChain = void 0;
+exports.executePlan = void 0;
 var eth_simulate_v1_js_1 = require("./eth-simulate-v1.js");
-Object.defineProperty(exports, "assertEndpointChain", { enumerable: true, get: function () { return eth_simulate_v1_js_1.assertEndpointChain; } });
 Object.defineProperty(exports, "executePlan", { enumerable: true, get: function () { return eth_simulate_v1_js_1.executePlan; } });

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 and timestamp 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/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/cjs/simulate/backends/resolve-pinned-block.js

@@ -7,9 +7,8 @@ const eth_simulate_v1_js_1 = require("./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
@@ -18,7 +17,7 @@ const eth_simulate_v1_js_1 = require("./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/cjs/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;