@morpho-org/evm-simulation 4.2.0 → 5.0.0

package/README.md

@@ -22,13 +22,7 @@ import {
 
 const config: SimulationConfig = {
   chains: new Map([
-    [
-      1,
-      {
-        tenderlyRpc: { rpcUrl: process.env.TENDERLY_RPC_URL! },
-        simulateV1Url: process.env.MAINNET_RPC_URL,
-      },
-    ],
+    [1, { simulateV1Url: process.env.MAINNET_RPC_URL! }],
   ]),
   timeoutMs: 5000,
 };
@@ -38,35 +32,133 @@ try {
     config,
     {
       chainId: 1,
+      // mode: "final" (default) executes the signed calldata against actual
+      // permissions; mode: "preview" accepts typed authorization descriptors.
       transactions: [{ from: user, to: vault, data: encodedDeposit }],
-      authorizations: [{ type: "signature", token: usdc, spender: vault }],
+      // limits: { operations: [{ type: "vaultV1Deposit", vault, quote: { sharesMinted: 1000n }, slippageTolerance: 10_000000000000000n }] },
     },
   );
 } catch (err) {
   if (err instanceof SimulationRevertedError) {
-    // show err.reason to the user
+    // show err.reason to the user; err.reasonCode is currently always "UNKNOWN_REVERT"
   }
   throw err;
 }
 ```
 
-Each chain entry must declare at least one backend — `tenderlyRpc` (primary), `simulateV1Url` (fallback), or both. The type system enforces this.
+Every chain entry requires `simulateV1Url`, pointing to a JSON-RPC endpoint that supports `eth_simulateV1`. Execution uses the full `timeoutMs` budget (default 5000 ms), with no retries or provider fallback. RPC failures, timeouts and reverts throw typed errors. The optional logger still reports parsing and retention warnings.
+
+Native-ETH movements are observed through `traceTransfers` logs on the simulated calls — no `stateOverrides` or helper contracts are injected.
+
+This is the unreleased v5 integration stack. See the [v4 → v5 migration guide](../../docs/migrations/evm-simulation-v4-to-v5.md) for the backend cutover and remaining release gates.
 
 ### API surface
 
 All symbols below are re-exported from the package root.
 
 - `simulate(config, params)` — run a bundle through the simulation pipeline.
-- Config types: `SimulationConfig`, `TenderlyRpcConfig`, `ChainSimulationConfig`, `SimulationLogger`.
-- Input types: `SimulateParams`, `SimulationTransaction`, `SimulationAuthorization`.
+- Config types: `SimulationConfig`, `ChainSimulationConfig`, `SimulationLogger`.
+- Input types: `SimulateParams` (v5 shape: `mode`, `SimulationAuthorization` requests, `SimulationLimits`), `SimulationMode`, `SimulationTransaction`.
+- `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`.
+- 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`.
+- 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
+
+The caller chooses the action, subject, quote, and percentage tolerance. Each
+entry supplies `quote` with at least one raw-unit amount: `assetsReceived`,
+`sharesMinted`, `assetsPaid`, or `sharesBurned`, plus `slippageTolerance` as a
+WAD-scaled fraction (`10_000000000000000n` = 1%, `1e18` = 100%). Tolerance must
+be between 0 and 100% inclusive; it has no default. Omit `limits` to skip checks.
+Unquoted amounts stay unchecked. The simulator never decodes calldata or fetches
+a quote to infer constraints.
+Unknown input keys are rejected as `SimulationValidationError` rather than
+silently ignored.
+
+Non-empty `limits.operations` and preview authorizations require a Morpho Blue
+address registered in blue-sdk's `getChainAddresses`; otherwise
+`UnsupportedChainError` is thrown.
+
+Received assets and minted supply shares must be at least
+`ceil(quote * (1 - tolerance))`; paid assets and burned supply shares must be at
+most `floor(quote * (1 + tolerance))`. For debt shares, minting is capped at
+`floor(quote * (1 + tolerance))` and burning must be at least
+`ceil(quote * (1 - tolerance))`. Equality and favorable movement pass.
 
-### Deeper docs
+```ts
+const result = await simulate(config, {
+  chainId: 1,
+  transactions,
+  limits: {
+    operations: [{
+      type: "vaultV1Deposit",
+      vault,
+      account: user, // Share/position owner; defaults to transaction sender.
+      receiver: user, // Asset recipient; defaults to transaction sender.
+      quote: { sharesMinted: 1_000n, assetsPaid: 1_000n },
+      slippageTolerance: 10_000000000000000n, // 1%
+    }],
+  },
+});
+// result.verification.operations[0].checkedLimits contains this quote and tolerance.
+```
 
-See [`CLAUDE.md`](./CLAUDE.md) in this directory for the execution flow diagram,
-backend tradeoffs, authorizations model, error-handling table,
-and recipes for adding a chain or a new backend.
+Measurements cover the named subject over the **whole bundle**. Entries do not
+attribute aggregate state changes to individual transactions. Use separate
+simulations for per-transaction limits. Asset bounds use net wallet balance
+changes (gas excluded). For native ETH, set `assetPaid` or `assetReceived` to
+viem's `ethAddress` (`0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE`); other
+sentinels such as `zeroAddress` are read as ERC-20 tokens. Share bounds use the
+selected account's vault shares or Blue position shares. Borrow/repay entries
+use debt shares; refinance selects
+source shares burned and target shares minted; migration selects source vault
+shares burned and target vault shares minted. Combined collateral/borrow actions
+measure collateral paid and loan assets received; repay/collateral-withdraw actions
+measure loan assets paid and collateral received.
+
+For `vaultV1InKindRedeem` and `vaultV2InKindRedeem`, `assetsReceived` measures
+only the receiver's wallet balance of the vault asset (the idle portion); it
+does not measure in-kind Morpho positions.
+
+Only slippage is checked; there are no separate refund or penalty checks.
+`sharesMinted` and `sharesBurned` quotes for `blueSupplyCollateral` and
+`blueWithdrawCollateral` are invalid and throw `SimulationValidationError`
+during request parsing. `MissingVerificationEvidenceError` reports runtime
+evidence gaps: a failed state read, native outgoing traces that do not cover
+value sent, or a metadata read that reverts or returns empty/invalid
+data. A quoted balance/position read whose non-empty return data cannot be
+decoded throws `InvalidSimulationResponseError`. Excessive slippage throws
+`ConsumerLimitViolationError`.
+
+Only quoted amounts are observed. ERC-20 assets and vault shares use `balanceOf`;
+Blue shares use `position`. Each distinct call runs before and after the bundle.
+Native amounts use the existing transfer traces. Without limits there are no
+slippage reads. Quotes with an asset amount resolve `asset()` or market parameters only
+when an explicit `assetPaid` or `assetReceived` was not supplied; share-only quotes need no metadata
+reads. No vault factories, full entities, allocations, risk metrics, allowances,
+or nonces are fetched for slippage.
+
+For example, a Vault V2 deposit quoting assets paid and shares minted makes four
+in-bundle view calls — the sender's asset balance and the `account`'s share balance, each before
+and after execution — plus one `asset()` read unless `assetPaid` is supplied. `verification.operations[].checkedLimits` records the quote
+and tolerance checked. The result does not include broad state snapshots or diffs;
+`transfers` and `assetChanges` remain available.
+
+The result's historical `VerifiedSimulationResult` name does not imply that
+unchecked outcomes are economically verified.
+
+Preview authorizations remain an adapter from `getRequirements()` through
+`toSimulationAuthorizations` into preparation calls. No permission or nonce
+read-back policy runs. Successful execution establishes success under the
+simulated permissions; it does not prove that a future signature is valid.
+Preparation and user-transaction failures still propagate. Final mode executes
+actual calldata without preparation. State reads and preparation calls do not
+receive public transaction indices.
+
+See [AGENTS.md](./AGENTS.md) for pipeline conventions and retention rules.
 
 ## Development
 

package/lib/cjs/authorizations.d.ts

@@ -0,0 +1,95 @@
+import type { Address, Hex } from "viem";
+/** EIP-712 domain separator fields of a signature payload. */
+export interface Eip712Domain {
+    readonly name?: string;
+    readonly version?: string;
+    readonly chainId: number | bigint;
+    readonly verifyingContract: Address;
+    readonly salt?: Hex;
+}
+/** One entry of an EIP-712 `types` field list. */
+export interface Eip712Field {
+    readonly name: string;
+    readonly type: string;
+}
+/** ERC-2612 `Permit` typed data; `domain.verifyingContract` is the token. */
+export interface Erc2612PermitTypedData {
+    readonly domain: Eip712Domain;
+    readonly primaryType: "Permit";
+    readonly types: {
+        readonly Permit: readonly Eip712Field[];
+    };
+    readonly message: {
+        readonly owner: Address;
+        readonly spender: Address;
+        readonly value: bigint;
+        readonly nonce: bigint;
+        readonly deadline: bigint;
+    };
+}
+/** Permit2 `PermitTransferFrom` typed data; the owner is not in the message. */
+export interface Permit2TransferTypedData {
+    readonly domain: Eip712Domain;
+    readonly primaryType: "PermitTransferFrom";
+    readonly types: {
+        readonly PermitTransferFrom: readonly Eip712Field[];
+        readonly TokenPermissions: readonly Eip712Field[];
+    };
+    readonly message: {
+        readonly permitted: {
+            readonly token: Address;
+            readonly amount: bigint;
+        };
+        readonly spender: Address;
+        readonly nonce: bigint;
+        readonly deadline: bigint;
+    };
+}
+/** Morpho `Authorization` typed data consumed by `setAuthorizationWithSig`. */
+export interface BlueAuthorizationTypedData {
+    readonly domain: Eip712Domain;
+    readonly primaryType: "Authorization";
+    readonly types: {
+        readonly Authorization: readonly Eip712Field[];
+    };
+    readonly message: {
+        readonly authorizer: Address;
+        readonly authorized: Address;
+        readonly isAuthorized: boolean;
+        readonly nonce: bigint;
+        readonly deadline: bigint;
+    };
+}
+/** Raw ERC-20 `approve` request. */
+export interface Erc20ApprovalAuthorization {
+    readonly type: "erc20Approval";
+    readonly token: Address;
+    readonly owner: Address;
+    readonly spender: Address;
+    readonly amount: bigint;
+}
+/** ERC-2612 permit request. */
+export interface Erc2612PermitAuthorization {
+    readonly type: "erc2612Permit";
+    readonly typedData: Erc2612PermitTypedData;
+}
+/** Permit2 signature transfer request. */
+export interface Permit2TransferAuthorization {
+    readonly type: "permit2SignatureTransfer";
+    readonly owner: Address;
+    readonly typedData: Permit2TransferTypedData;
+}
+/** Direct Morpho `setAuthorization` request. */
+export interface BlueAuthorization {
+    readonly type: "blueAuthorization";
+    readonly authorizer: Address;
+    readonly authorized: Address;
+    readonly isAuthorized: boolean;
+}
+/** Morpho `setAuthorizationWithSig` request. */
+export interface BlueAuthorizationSignature {
+    readonly type: "blueAuthorizationSignature";
+    readonly typedData: BlueAuthorizationTypedData;
+}
+/** A pending wallet request passed to `simulate()` — the five typed variants. */
+export type SimulationAuthorization = Erc20ApprovalAuthorization | Erc2612PermitAuthorization | Permit2TransferAuthorization | BlueAuthorization | BlueAuthorizationSignature;

package/lib/cjs/authorizations.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/cjs/errors.d.ts

@@ -1,44 +1,238 @@
+import type { Address, Hash } from "viem";
+import type { SimulationOperationSubject } from "./limits.js";
+import type { SimulationMode } from "./params.js";
+/** Stable error codes thrown by this package, part of the public API. */
+export declare const SIMULATION_ERROR_CODES: readonly ["VALIDATION_ERROR", "UNSUPPORTED_CHAIN", "EXTERNAL_SERVICE_ERROR", "SIMULATION_REVERTED", "BLACKLIST_ERROR", "UNSUPPORTED_OPERATION", "INVALID_SIMULATION_RESPONSE", "MISSING_VERIFICATION_EVIDENCE", "AUTHORIZATION_REQUEST_MISMATCH", "CONSUMER_LIMIT_VIOLATION", "UNEXPECTED_SIMULATION_ERROR"];
+/** Stable string discriminator for log aggregation and external mapping. */
+export type SimulationErrorCode = (typeof SIMULATION_ERROR_CODES)[number];
+/**
+ * Machine-readable cause of an execution failure (ADR-2026-09-18 §Errors).
+ * `UNKNOWN_REVERT` is used when the revert maps to no known Morpho condition;
+ * consumers branch on it and never parse `reason`.
+ */
+export type SimulationExecutionReason = "INSUFFICIENT_BALANCE" | "INSUFFICIENT_ALLOWANCE" | "INSUFFICIENT_LIQUIDITY" | "POSITION_UNHEALTHY" | "SLIPPAGE_EXCEEDED" | "SIGNATURE_EXPIRED" | "SIGNATURE_INVALID" | "NONCE_ALREADY_USED" | "CAP_EXCEEDED" | "ACCESS_RESTRICTED" | "UNKNOWN_REVERT";
+declare const SIMULATION_STAGES: readonly ["validation", "preparation", "execution", "verification", "transport"];
+/** Pipeline stage a failure belongs to; `transport` covers RPC and response failures. */
+export type SimulationStage = (typeof SIMULATION_STAGES)[number];
+interface SimulationContextBase {
+    /** Request mode the failure happened in. */
+    readonly mode: SimulationMode;
+    /** Chain the request targeted. */
+    readonly chainId: number;
+    /** Block the simulation was pinned to. */
+    readonly blockNumber: bigint;
+}
+interface SimulationCheckContext extends SimulationContextBase {
+    /** Token whose balance, allowance or transfer was checked. */
+    readonly token?: Address;
+    /** Account whose position, balance or authorization was checked (usually the sender). */
+    readonly account?: Address;
+    /** Spender or operator granted by the checked permission. */
+    readonly spender?: Address;
+    /**
+     * Name of the checked field (e.g. `"assetsReceived"`). Unbound verification
+     * contexts instead carry the failed state read's id
+     * (`balance:<token>:<account>` or `position:<marketId>:<account>`).
+     */
+    readonly field?: string;
+    /** Bound or value `field` was checked against; 32-byte hashes only, never calldata or signatures. */
+    readonly expected?: bigint | boolean | Address | Hash;
+    /** Value observed in the simulation, same domain as `expected`. */
+    readonly observed?: bigint | boolean | Address | Hash;
+    /**
+     * Reserved; not populated for caller-transaction reverts, whose index is on
+     * `SimulationRevertedError.details[].transactionIndex`.
+     */
+    readonly failedTransactionIndex?: number;
+}
+/** Context of a failure while validating the request. */
+export type SimulationValidationContext = SimulationContextBase & {
+    readonly stage: "validation";
+};
+/** Context of a failure while reaching the `eth_simulateV1` backend. */
+export type SimulationTransportContext = SimulationContextBase & {
+    readonly stage: "transport";
+};
+/** Context of a failure while preparing a preview authorization. */
+export type SimulationPreparationContext = SimulationContextBase & {
+    readonly stage: "preparation";
+    /** Index into `authorizations`. */
+    readonly authorizationIndex: number;
+    /** Index into that authorization's preparation calls. */
+    readonly preparationCallIndex?: number;
+};
+/**
+ * Reserved execution-stage context; `SimulationRevertedError` carries none for
+ * caller-transaction or node reverts (see `details[].transactionIndex`).
+ */
+export type SimulationExecutionContext = SimulationCheckContext & SimulationOperationSubject & {
+    readonly stage: "execution";
+};
+/** Context of a verification check that did not hold. */
+export type SimulationVerificationContext = SimulationCheckContext & SimulationOperationSubject & {
+    readonly stage: "verification";
+};
+/**
+ * Where and why a simulation failed, keyed by `stage`
+ * (ADR-2026-10-01-evm-simulation-quoted-slippage-limits).
+ * Every stage carries `mode`, `chainId` and `blockNumber`. Preparation
+ * contexts carry `authorizationIndex` and `preparationCallIndex`. Verification
+ * contexts bound to a limit take `operation` and the subject fields
+ * (`marketId`, `sourceMarketId`/`targetMarketId`, `vault`,
+ * `sourceVault`/`targetVault`) from that `OperationLimit`, not
+ * from decoded calldata; unbound ones carry only a `field` string naming the
+ * failed state read (`balance:<token>:<account>` or
+ * `position:<marketId>:<account>`).
+ * `"execution"` stays in the union, but `SimulationRevertedError` carries no
+ * `context` for caller-transaction or node reverts — the failing
+ * `transactionIndex` is reported on the error's `details`. Never contains
+ * signatures, RPC URLs, credentials, raw calldata or raw causes (`cause`
+ * stays on the error).
+ */
+export type SimulationErrorContext = SimulationValidationContext | SimulationTransportContext | SimulationPreparationContext | SimulationExecutionContext | SimulationVerificationContext | (SimulationCheckContext & {
+    readonly stage: "verification";
+    readonly field: string;
+    readonly operation?: never;
+});
 /**
  * Base class for every error this package throws. Transport-agnostic — no HTTP status codes.
  * Consumers pattern-match with `instanceof` on the concrete subclass.
  */
 export declare abstract class SimulationPackageError extends Error {
     /** Stable string discriminator for log aggregation and external mapping. */
-    abstract readonly code: string;
-    constructor(message: string, options?: ErrorOptions);
+    abstract readonly code: SimulationErrorCode;
+    /** Frozen copy of the failure context, when one was supplied. */
+    readonly context?: SimulationErrorContext;
+    constructor(message: string, options?: ErrorOptions & {
+        context?: SimulationErrorContext;
+    });
 }
 /** Transaction would revert on-chain. Not bypassable. */
 export declare class SimulationRevertedError extends SimulationPackageError {
+    /** Raw revert string as reported by the backend, when any. */
     readonly reason: string | undefined;
     readonly details?: unknown;
+    /** Machine-readable cause; `UNKNOWN_REVERT` when the revert maps to no known Morpho condition. */
+    readonly reasonCode: SimulationExecutionReason;
+    readonly name = "SimulationRevertedError";
     readonly code = "SIMULATION_REVERTED";
-    constructor(reason: string | undefined, details?: unknown);
+    readonly context?: SimulationPreparationContext | SimulationExecutionContext;
+    constructor(
+    /** Raw revert string as reported by the backend, when any. */
+    reason: string | undefined, details?: unknown, 
+    /** Machine-readable cause; `UNKNOWN_REVERT` when the revert maps to no known Morpho condition. */
+    reasonCode?: SimulationExecutionReason, 
+    /** Which transaction/authorization reverted and the operation it belonged to. */
+    context?: SimulationPreparationContext | SimulationExecutionContext);
 }
-interface RetainedAsset {
-    address: string | undefined;
-    token: string | undefined;
-    netRetained: string;
+/** Per-asset net retained amount keyed by restricted contract and token. */
+export interface RetainedAsset {
+    /** Restricted bundles contract that ended up holding the token. */
+    readonly address: Address;
+    /** Token retained (native ETH uses viem's `ethAddress`). */
+    readonly token: Address;
+    /** Net balance increase in the token's base units; always positive. */
+    readonly netRetained: bigint;
 }
-/** Funds would flow to restricted standalone bundles contract addresses. Never bypassable. */
+/**
+ * Thrown when net value above the dust threshold is retained by a restricted bundles contract
+ * (VaultExitBundlesV1, VaultBundlesV1, BlueBundlesV1 or MidnightBundlesV1) after simulation;
+ * pass-through flows and net outflows are allowed. Never bypassable.
+ */
 export declare class BlacklistViolationError extends SimulationPackageError {
-    readonly assetChanges?: RetainedAsset[] | undefined;
+    /** Per-asset net retained amounts keyed by restricted contract and token. */
+    readonly assetChanges?: readonly RetainedAsset[] | undefined;
+    readonly name = "BlacklistViolationError";
     readonly code = "BLACKLIST_ERROR";
-    constructor(message: string, assetChanges?: RetainedAsset[] | undefined);
+    constructor(message: string, 
+    /** Per-asset net retained amounts keyed by restricted contract and token. */
+    assetChanges?: readonly RetainedAsset[] | undefined, context?: SimulationErrorContext);
 }
-/** Tenderly or RPC service is down. Bypassable — user can proceed. */
+/** RPC service is down or unreachable. Bypassable — user can proceed. */
 export declare class ExternalServiceError extends SimulationPackageError {
+    readonly name = "ExternalServiceError";
     readonly code = "EXTERNAL_SERVICE_ERROR";
 }
 /** Bad input to the simulation functions. Not bypassable. */
 export declare class SimulationValidationError extends SimulationPackageError {
     readonly fieldErrors?: string[] | undefined;
+    readonly name = "SimulationValidationError";
     readonly code = "VALIDATION_ERROR";
-    constructor(message: string, fieldErrors?: string[] | undefined);
+    constructor(message: string, fieldErrors?: string[] | undefined, context?: SimulationErrorContext);
 }
 /** Chain ID not configured for any simulation method. Not bypassable. */
 export declare class UnsupportedChainError extends SimulationPackageError {
     readonly chainId: number;
+    readonly name = "UnsupportedChainError";
     readonly code = "UNSUPPORTED_CHAIN";
-    constructor(chainId: number);
+    constructor(chainId: number, context?: SimulationErrorContext);
 }
+/**
+ * An SDK requirement passed to `toSimulationAuthorizations` cannot be
+ * converted into a simulation authorization.
+ */
+export declare class UnsupportedOperationError extends SimulationPackageError {
+    readonly name = "UnsupportedOperationError";
+    readonly code = "UNSUPPORTED_OPERATION";
+}
+/** The simulation backend returned a response that cannot be parsed. */
+export declare class InvalidSimulationResponseError extends SimulationPackageError {
+    readonly name = "InvalidSimulationResponseError";
+    readonly code = "INVALID_SIMULATION_RESPONSE";
+}
+/** State needed to verify an operation could not be fetched or derived. */
+export declare class MissingVerificationEvidenceError extends SimulationPackageError {
+    readonly name = "MissingVerificationEvidenceError";
+    readonly code = "MISSING_VERIFICATION_EVIDENCE";
+}
+/** A pending authorization does not match the request it was prepared for. */
+export declare class AuthorizationRequestMismatchError extends SimulationPackageError {
+    readonly name = "AuthorizationRequestMismatchError";
+    readonly code = "AUTHORIZATION_REQUEST_MISMATCH";
+}
+/** A consumer-supplied limit was violated. */
+export declare class ConsumerLimitViolationError extends SimulationPackageError {
+    readonly name = "ConsumerLimitViolationError";
+    readonly code = "CONSUMER_LIMIT_VIOLATION";
+}
+/** The simulation failed for a reason that fits no other code. */
+export declare class UnexpectedSimulationError extends SimulationPackageError {
+    readonly name = "UnexpectedSimulationError";
+    readonly code = "UNEXPECTED_SIMULATION_ERROR";
+}
+/**
+ * Structural guard for consumers where `instanceof` fails across bundles.
+ *
+ * @param value - Anything caught.
+ * @returns `true` for `SimulationPackageError` instances and for objects
+ *   carrying a `message` string, a known `code`, the `name` of the class
+ *   owning that `code`, and an absent or
+ *   well-formed `context` (known `stage`, `mode`, numeric `chainId`,
+ *   `bigint` `blockNumber`, `authorizationIndex` for `preparation`, and a
+ *   known `operation` with its subject fields for `execution`/`verification`,
+ *   or a verification `field` string with no `operation`).
+ * @example
+ * ```ts
+ * import { isSimulationPackageError, simulate } from "@morpho-org/evm-simulation";
+ * import type { Address, Hex } from "viem";
+ *
+ * declare const user: Address;
+ * declare const vault: Address;
+ * declare const encodedDeposit: Hex;
+ * const config = {
+ *   chains: new Map([[1, { simulateV1Url: "https://rpc.example" }]]),
+ * };
+ * try {
+ *   await simulate(config, {
+ *     chainId: 1,
+ *     transactions: [{ from: user, to: vault, data: encodedDeposit }],
+ *   });
+ * } catch (e) {
+ *   if (!isSimulationPackageError(e)) throw e;
+ *   if (e.code !== "SIMULATION_REVERTED") throw e;
+ *   console.log(e.context?.stage, e.message);
+ * }
+ * ```
+ */
+export declare function isSimulationPackageError(value: unknown): value is SimulationPackageError;
 export {};