@morpho-org/evm-simulation 5.0.1 → 6.0.0

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

@@ -18,7 +18,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 →
@@ -43,7 +43,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
@@ -55,12 +55,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.
  */
 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 {
@@ -82,8 +82,8 @@ function assertNoBundlesRetention(params) {
         for (const addr of Object.values(addresses.bundles).filter(morpho_ts_1.isDefined))
             restrictedAddresses.add((0, viem_1.getAddress)(addr));
     }
-    if (addresses.midnightBundles) {
-        restrictedAddresses.add((0, viem_1.getAddress)(addresses.midnightBundles));
+    if (addresses.midnightBundlesV2) {
+        restrictedAddresses.add((0, viem_1.getAddress)(addresses.midnightBundlesV2));
     }
     if (restrictedAddresses.size === 0) {
         // blue-sdk knows the chain but cataloged no restricted intermediary for it.

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/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/cjs/simulate/request/parse-request.js

@@ -52,6 +52,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"],
@@ -570,6 +571,7 @@ function parseRequest(input) {
             "chainId",
             "transactions",
             "blockNumber",
+            "block",
             "mode",
             "authorizations",
             "limits",
@@ -652,6 +654,24 @@ 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 = [];
@@ -754,6 +774,7 @@ function parseRequest(input) {
         transactions,
         authorizations: mode === "preview" ? authorizations : [],
         ...(blockNumber !== undefined ? { blockNumber } : {}),
+        ...(block !== undefined ? { block } : {}),
         ...(normalizedLimits !== undefined ? { limits: normalizedLimits } : {}),
     });
 }

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

@@ -45,21 +45,16 @@ async function runSimulation(params) {
     if (requiresMorpho && addresses?.blue == null)
         throw new errors_js_1.UnsupportedChainError(request.chainId);
     const morpho = addresses?.blue ?? viem_1.zeroAddress;
-    await (0, index_js_1.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 === blue_sdk_1.ChainId.MonadMainnet;
-    const pinnedBlock = await (0, resolve_pinned_block_js_1.resolvePinnedBlock)({
-        client,
-        blockNumber: request.blockNumber ?? (monad ? "finalized" : undefined),
-        signal,
-    });
+    const pinnedBlock = request.block ??
+        (await (0, resolve_pinned_block_js_1.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.
@@ -85,12 +80,14 @@ 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 (0, index_js_1.executePlan)({
         client,
         plan,
         stateBlock: pinnedBlock,
         validation: monad,
+        blockGasLimit: chain.blockOverrides?.gasLimit,
+        parentHashCheck: chain.parentHashCheck ?? request.chainId !== blue_sdk_1.ChainId.StableMainnet,
     });
     const userCalls = execution.calls
         .filter((call) => call.planned.type === "transaction")

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

@@ -4,11 +4,11 @@ import type { SimulationConfig } from "../types.js";
 /**
  * Simulate a bundle of EVM transactions.
  *
- * Parses and normalizes the request → resolves the chain identity → resolves
- * a single pinned block → resolves quoted-asset metadata → plans state reads
- * and the execution → executes once through `eth_simulateV1` under the full
- * timeout budget (simulation with in-block state reads → response parsing →
- * reorg check) → derives ERC20/WETH9 transfers and net asset changes from the
+ * Parses and normalizes the request → resolves a single pinned block (skipped
+ * when `params.block` is supplied) → resolves quoted-asset metadata → plans
+ * state reads and the execution → executes once through `eth_simulateV1` under
+ * the full timeout budget (simulation with in-block state reads → response
+ * parsing) → derives ERC20/WETH9 transfers and net asset changes from the
  * user calls only → decodes quoted balances/positions → runs slippage checks
  * → asserts no funds are retained by standalone `bundles` periphery contracts
  * → returns the result. The caller reads whichever fields they need:
@@ -37,10 +37,13 @@ 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.chainId - Chain id the bundle targets. Sent on every call inside
+ *   `eth_simulateV1`, so nodes that check it reject a wrong-chain endpoint;
+ *   there is no separate `eth_chainId` lookup.
  * @param params.transactions - The bundle's transactions, in execution order.
  *   All must share the same `from`.
  * @param params.mode - `"final"` (default) or `"preview"`.
@@ -50,9 +53,16 @@ import type { SimulationConfig } from "../types.js";
  *   than `"pending"`.
  *   Defaults to `latest` (`finalized` on Monad, whose `latest` block is not
  *   final), resolved exactly once.
+ * @param params.block - Optional caller-supplied state block (`number`,
+ *   `hash`, `timestamp`). Skips the block lookup, so a simulation without
+ *   asset metadata reads makes a single `eth_simulateV1` request. Cannot be
+ *   combined with `blockNumber`.
  * @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 malformed `block` or one combined with `blockNumber`, 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,20 +76,21 @@ 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
- *   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
- *   endpoint whose `eth_chainId` differs from `params.chainId`; chain identity
- *   is checked before any block lookup).
+ *   `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, or a quoted balance/position read whose
+ *   non-empty return data cannot be decoded).
+ * @throws {InvalidChainIdError} when the node rejects the request `chainId`
+ *   because the endpoint serves another chain (a subclass of
+ *   `InvalidSimulationResponseError` sharing its `name`/`code`;
+ *   `instanceof InvalidChainIdError` tells them apart). Never bypassable.
  * @throws {BlacklistViolationError} when the simulation leaves value retained
  *   beyond the dust threshold by a `bundles` periphery contract
- *   (VaultExitBundlesV1, VaultBundlesV1, BlueBundlesV1, MidnightBundlesV1).
+ *   (VaultExitBundlesV1, VaultBundlesV1, BlueBundlesV1, MidnightBundlesV2).
  *   Never bypassable.
  * @throws {ExternalServiceError} when the RPC is unavailable within the
- *   timeout budget or returns a malformed JSON-RPC envelope. Chain-id
- *   mismatches and a state block without number/hash are reported as
- *   `InvalidSimulationResponseError`.
+ *   timeout budget or returns a malformed JSON-RPC envelope. A looked-up state
+ *   block without number/hash is reported as `InvalidSimulationResponseError`.
  * @returns A frozen {@link VerifiedSimulationResult} carrying the normalized
  *   `simulationTxs`, per-tx `calls` (aligned 1:1), parsed `transfers` (each
  *   stamped with `txIdx`), per-account net `assetChanges`, and per-operation

package/lib/cjs/simulate/simulate.js

@@ -6,11 +6,11 @@ const run_simulation_js_1 = require("./run-simulation.js");
 /**
  * Simulate a bundle of EVM transactions.
  *
- * Parses and normalizes the request → resolves the chain identity → resolves
- * a single pinned block → resolves quoted-asset metadata → plans state reads
- * and the execution → executes once through `eth_simulateV1` under the full
- * timeout budget (simulation with in-block state reads → response parsing →
- * reorg check) → derives ERC20/WETH9 transfers and net asset changes from the
+ * Parses and normalizes the request → resolves a single pinned block (skipped
+ * when `params.block` is supplied) → resolves quoted-asset metadata → plans
+ * state reads and the execution → executes once through `eth_simulateV1` under
+ * the full timeout budget (simulation with in-block state reads → response
+ * parsing) → derives ERC20/WETH9 transfers and net asset changes from the
  * user calls only → decodes quoted balances/positions → runs slippage checks
  * → asserts no funds are retained by standalone `bundles` periphery contracts
  * → returns the result. The caller reads whichever fields they need:
@@ -39,10 +39,13 @@ 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.chainId - Chain id the bundle targets. Sent on every call inside
+ *   `eth_simulateV1`, so nodes that check it reject a wrong-chain endpoint;
+ *   there is no separate `eth_chainId` lookup.
  * @param params.transactions - The bundle's transactions, in execution order.
  *   All must share the same `from`.
  * @param params.mode - `"final"` (default) or `"preview"`.
@@ -52,9 +55,16 @@ const run_simulation_js_1 = require("./run-simulation.js");
  *   than `"pending"`.
  *   Defaults to `latest` (`finalized` on Monad, whose `latest` block is not
  *   final), resolved exactly once.
+ * @param params.block - Optional caller-supplied state block (`number`,
+ *   `hash`, `timestamp`). Skips the block lookup, so a simulation without
+ *   asset metadata reads makes a single `eth_simulateV1` request. Cannot be
+ *   combined with `blockNumber`.
  * @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 malformed `block` or one combined with `blockNumber`, 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,20 +78,21 @@ 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
- *   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
- *   endpoint whose `eth_chainId` differs from `params.chainId`; chain identity
- *   is checked before any block lookup).
+ *   `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, or a quoted balance/position read whose
+ *   non-empty return data cannot be decoded).
+ * @throws {InvalidChainIdError} when the node rejects the request `chainId`
+ *   because the endpoint serves another chain (a subclass of
+ *   `InvalidSimulationResponseError` sharing its `name`/`code`;
+ *   `instanceof InvalidChainIdError` tells them apart). Never bypassable.
  * @throws {BlacklistViolationError} when the simulation leaves value retained
  *   beyond the dust threshold by a `bundles` periphery contract
- *   (VaultExitBundlesV1, VaultBundlesV1, BlueBundlesV1, MidnightBundlesV1).
+ *   (VaultExitBundlesV1, VaultBundlesV1, BlueBundlesV1, MidnightBundlesV2).
  *   Never bypassable.
  * @throws {ExternalServiceError} when the RPC is unavailable within the
- *   timeout budget or returns a malformed JSON-RPC envelope. Chain-id
- *   mismatches and a state block without number/hash are reported as
- *   `InvalidSimulationResponseError`.
+ *   timeout budget or returns a malformed JSON-RPC envelope. A looked-up state
+ *   block without number/hash is reported as `InvalidSimulationResponseError`.
  * @returns A frozen {@link VerifiedSimulationResult} carrying the normalized
  *   `simulationTxs`, per-tx `calls` (aligned 1:1), parsed `transfers` (each
  *   stamped with `txIdx`), per-account net `assetChanges`, and per-operation

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 and timestamp 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/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/esm/errors.js

@@ -60,7 +60,7 @@ export class SimulationRevertedError extends SimulationPackageError {
 }
 /**
  * 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 class BlacklistViolationError extends SimulationPackageError {
@@ -109,11 +109,26 @@ export class UnsupportedOperationError extends SimulationPackageError {
     name = "UnsupportedOperationError";
     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 class InvalidSimulationResponseError extends SimulationPackageError {
     name = "InvalidSimulationResponseError";
     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 class InvalidChainIdError extends InvalidSimulationResponseError {
+}
 /** State needed to verify an operation could not be fetched or derived. */
 export class MissingVerificationEvidenceError extends SimulationPackageError {
     name = "MissingVerificationEvidenceError";

package/lib/esm/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/esm/index.js

@@ -1,6 +1,6 @@
 // Public fns (via feature-folder barrels)
 // Errors (for instanceof checks by consumers)
-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 { BLUE_MARKET_OPERATION_TYPES, OPERATION_TYPES, VAULT_OPERATION_TYPES, } from "./limits.js";
 export { SIMULATION_MODES } from "./params.js";
 export { toSimulationAuthorizations } from "./requirements/index.js";

package/lib/esm/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/esm/requirements/requirements.js

@@ -130,6 +130,7 @@ export function toSimulationAuthorizations(params) {
         }
         if (isRequirementSignature(requirement)) {
             const { action } = requirement;
+            const actionType = action.type;
             switch (action.type) {
                 case "permit":
                     return toErc2612Permit(action, ctx);
@@ -138,7 +139,7 @@ export 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`);