@gearbox-protocol/sdk 14.11.0-next.5 → 14.11.0-next.7

package/dist/esm/preview/simulate/simulatePoolOpV1.js

@@ -0,0 +1,82 @@
+import { simulateCalls } from "viem/actions";
+import { ierc20Abi } from "../../abi/iERC20.js";
+import { decodeSimulationError, PreviewSimulationError } from "./errors.js";
+import { extractERC20Transfers } from "./extractERC20Transfers.js";
+import { watchedHolders } from "./holders.js";
+async function simulatePoolOpV1(input, options = {}) {
+  const { sdk, operation, to, calldata, wallet } = input;
+  const { blockNumber } = options;
+  const { underlying, pool } = operation;
+  const holders = watchedHolders(operation, wallet);
+  const tokens = [underlying, pool];
+  const balanceOf = (token, holder) => ({
+    to: token,
+    abi: ierc20Abi,
+    functionName: "balanceOf",
+    args: [holder]
+  });
+  const balanceCalls = holders.flatMap(
+    (holder) => tokens.map((token) => balanceOf(token, holder))
+  );
+  let results;
+  try {
+    ({ results } = await simulateCalls(sdk.client, {
+      account: wallet,
+      // `undefined` lets viem simulate at `latest`; `blockNumber` is only set
+      // for testnet forks pinned to a specific block.
+      blockNumber,
+      calls: [...balanceCalls, { to, data: calldata }, ...balanceCalls]
+    }));
+  } catch (cause) {
+    throw new PreviewSimulationError([
+      {
+        source: "eth_simulateV1",
+        detail: decodeSimulationError({
+          error: cause instanceof Error ? cause : new Error(String(cause))
+        })
+      }
+    ]);
+  }
+  const sim = results;
+  const txIndex = balanceCalls.length;
+  const afterOffset = txIndex + 1;
+  const txResult = sim[txIndex];
+  if (!txResult || txResult.status === "failure") {
+    throw new PreviewSimulationError([
+      {
+        source: "eth_simulateV1",
+        detail: decodeSimulationError({
+          error: txResult?.error,
+          data: txResult?.data
+        })
+      }
+    ]);
+  }
+  const balanceChanges = [];
+  for (const [holderIndex, address] of holders.entries()) {
+    const changes = [];
+    for (const [tokenIndex, token] of tokens.entries()) {
+      const slot = holderIndex * tokens.length + tokenIndex;
+      const before = readBalance(sim[slot]);
+      const after = readBalance(sim[afterOffset + slot]);
+      const delta = after - before;
+      const magnitude = delta >= 0n ? delta : -delta;
+      if (magnitude > 1n) {
+        changes.push({ token, before, after, delta });
+      }
+    }
+    if (changes.length > 0) {
+      balanceChanges.push({ address, changes });
+    }
+  }
+  return {
+    transfers: extractERC20Transfers(txResult.logs ?? [], holders),
+    balanceChanges
+  };
+}
+function readBalance(result) {
+  return result?.status === "success" ? result.result : 0n;
+}
+export {
+  simulatePoolOpV1
+};

package/dist/esm/preview/simulate/simulatePoolOperation.js

@@ -1,69 +1,37 @@
-import { isAddressEqual } from "viem";
-import { simulateCalls } from "viem/actions";
-import { ierc20Abi } from "../../abi/iERC20.js";
-import { decodeSimulationError } from "./decodeSimulationError.js";
-import { extractERC20Transfers } from "./extractERC20Transfers.js";
-async function simulatePoolOperation(input) {
-  const { sdk, operation, to, calldata, wallet, blockNumber } = input;
-  const { underlying, pool } = operation;
-  const receiverIsWallet = isAddressEqual(operation.receiver, wallet);
-  const holders = receiverIsWallet ? [wallet] : [wallet, operation.receiver];
-  const tokens = [underlying, pool];
-  const balanceOf = (token, holder) => ({
-    to: token,
-    abi: ierc20Abi,
-    functionName: "balanceOf",
-    args: [holder]
-  });
-  const balanceCalls = holders.flatMap(
-    (holder) => tokens.map((token) => balanceOf(token, holder))
+import {
+  asPreviewSimulationError,
+  combinePreviewSimulationErrors
+} from "./errors.js";
+import { simulatePoolOpMulticall } from "./simulatePoolOpMulticall.js";
+import { simulatePoolOpV1 } from "./simulatePoolOpV1.js";
+async function simulatePoolOperation(input, options = {}) {
+  const { logger, useSimulateV1 } = options;
+  logger?.debug(
+    { wallet: input.wallet, to: input.to },
+    "simulating pool operation"
   );
-  const { results } = await simulateCalls(sdk.client, {
-    account: wallet,
-    // `undefined` lets viem simulate at `latest`; `blockNumber` is only set for
-    // testnet forks pinned to a specific block.
-    blockNumber,
-    calls: [...balanceCalls, { to, data: calldata }, ...balanceCalls]
-  });
-  const sim = results;
-  const txIndex = balanceCalls.length;
-  const afterOffset = txIndex + 1;
-  const txResult = sim[txIndex];
-  if (!txResult || txResult.status === "failure") {
-    return {
-      status: "failure",
-      error: decodeSimulationError({
-        error: txResult?.error,
-        data: txResult?.data
-      })
-    };
+  const [v1, multicall] = await Promise.allSettled([
+    useSimulateV1 ? simulatePoolOpV1(input, options) : void 0,
+    simulatePoolOpMulticall(input, options)
+  ]);
+  if (v1.status === "fulfilled" && v1.value) {
+    return { status: "success", ...v1.value };
   }
-  const balanceChanges = [];
-  for (const [holderIndex, address] of holders.entries()) {
-    const changes = [];
-    for (const [tokenIndex, token] of tokens.entries()) {
-      const slot = holderIndex * tokens.length + tokenIndex;
-      const before = readBalance(sim[slot]);
-      const after = readBalance(sim[afterOffset + slot]);
-      const delta = after - before;
-      const magnitude = delta >= 0n ? delta : -delta;
-      if (magnitude > 1n) {
-        changes.push({ token, before, after, delta });
-      }
-    }
-    if (changes.length > 0) {
-      balanceChanges.push({ address, changes });
+  if (multicall.status === "fulfilled") {
+    if (v1.status === "rejected") {
+      logger?.debug(
+        asPreviewSimulationError(v1.reason, "eth_simulateV1"),
+        "eth_simulateV1 flow failed; falling back to multicall result"
+      );
     }
+    return { status: "success", ...multicall.value };
   }
-  return {
-    status: "success",
-    transfers: extractERC20Transfers(txResult.logs ?? [], holders),
-    balanceChanges,
-    gasUsed: txResult.gasUsed
-  };
-}
-function readBalance(result) {
-  return result?.status === "success" ? result.result : 0n;
+  const error = combinePreviewSimulationErrors(
+    v1.status === "rejected" ? asPreviewSimulationError(v1.reason, "eth_simulateV1") : void 0,
+    asPreviewSimulationError(multicall.reason, "multicall")
+  );
+  logger?.error(error, "pool operation simulation failed");
+  return { status: "failure", error };
 }
 export {
   simulatePoolOperation

package/dist/types/history/types.d.ts

@@ -18,10 +18,10 @@ export type HistoryAdapterExt = TraceAdapterExt & {
 export type HistoryFacadeMetadata = FacadeOperationMetadata & OperationMetadata;
 export type AdapterOperation = BaseAdapterOperation<HistoryAdapterExt>;
 export type InnerOperation = BaseInnerOperation<HistoryAdapterExt>;
-export type MulticallOperation = BaseMulticallOperation<HistoryAdapterExt> & OperationMetadata;
-export type OpenCreditAccountOperation = BaseOpenCreditAccountOperation<HistoryAdapterExt> & OperationMetadata;
-export type CloseCreditAccountOperation = BaseCloseCreditAccountOperation<HistoryAdapterExt> & OperationMetadata;
-export type LiquidateCreditAccountOperation = BaseLiquidateCreditAccountOperation<HistoryAdapterExt> & OperationMetadata;
+export type MulticallOperation = Omit<BaseMulticallOperation<HistoryAdapterExt>, "expectedBalanceChanges"> & OperationMetadata;
+export type OpenCreditAccountOperation = Omit<BaseOpenCreditAccountOperation<HistoryAdapterExt>, "expectedBalanceChanges"> & OperationMetadata;
+export type CloseCreditAccountOperation = Omit<BaseCloseCreditAccountOperation<HistoryAdapterExt>, "expectedBalanceChanges"> & OperationMetadata;
+export type LiquidateCreditAccountOperation = Omit<BaseLiquidateCreditAccountOperation<HistoryAdapterExt>, "expectedBalanceChanges"> & OperationMetadata;
 export type PartialLiquidationOperation = BasePartialLiquidationOperation & OperationMetadata;
 export type DirectTokenTransferOperation = BaseDirectTokenTransferOperation & OperationMetadata;
 export type OuterFacadeOperation = MulticallOperation | OpenCreditAccountOperation | CloseCreditAccountOperation | LiquidateCreditAccountOperation | PartialLiquidationOperation;

package/dist/types/preview/parse/extractExpectedBalanceChanges.d.ts

@@ -0,0 +1,22 @@
+import type { ParsedCallV2 } from "../../sdk/index.js";
+import type { ExpectedBalanceChange } from "./types.js";
+/**
+ * Recovers the potential balance changes declared by a router-generated
+ * `storeExpectedBalances`/`compareBalances` pair inside a credit-facade
+ * multicall.
+ *
+ * The detection is intentionally limited to the router shape:
+ * - `onDemandPriceUpdates` calls are dropped first (they may only appear at the
+ *   front of a multicall);
+ * - the remaining calls must start with `storeExpectedBalances` and end with
+ *   `compareBalances`.
+ *
+ * When the multicall does not match this shape, `undefined` is returned. On a
+ * match, the `BalanceDelta[]` argument of `storeExpectedBalances` is decoded
+ * into {@link ExpectedBalanceChange}[] (the `amount` is the signed `int256`
+ * delta and may be negative).
+ *
+ * @param innerCalls - Raw (already-decoded) inner multicall calls.
+ * @returns The declared balance changes, or `undefined` when not router-shaped.
+ */
+export declare function extractExpectedBalanceChanges(innerCalls: ParsedCallV2[]): ExpectedBalanceChange[] | undefined;

package/dist/types/preview/parse/index.d.ts

@@ -1,5 +1,6 @@
 export * from "./classifyInnerOperations.js";
 export * from "./errors.js";
+export * from "./extractExpectedBalanceChanges.js";
 export * from "./parseFacadeOperationCalldata.js";
 export * from "./parseOperationCalldata.js";
 export * from "./parsePoolOperationCalldata.js";

package/dist/types/preview/parse/parsePoolOperationCalldata.d.ts

@@ -8,8 +8,10 @@ export interface ParsePoolOperationCalldataProps {
     calldata: Hex;
 }
 /**
- * Decodes ERC4626 `deposit`/`depositWithReferral`/`redeem` calldata on a
- * Gearbox pool into a {@link PoolOperation}. Any other selector throws
+ * Decodes ERC4626 pool calldata into a {@link PoolOperation}. Supports every
+ * deposit/mint/withdraw/redeem variant of `IPoolV3` (and the `IERC4626` base it
+ * extends): `deposit`/`depositWithReferral`, `mint`/`mintWithReferral`,
+ * `withdraw` and `redeem`. Any other selector throws
  * {@link UnsupportedPoolFunctionError}.
  */
 export declare function parsePoolOperationCalldata(props: ParsePoolOperationCalldataProps): PoolOperation;

package/dist/types/preview/parse/types-facades.d.ts

@@ -71,10 +71,25 @@ export interface FacadeOperationMetadata {
     creditManager: Address;
     creditFacade: Address;
 }
+/**
+ * Signed token balance delta recovered from a router-generated
+ * `storeExpectedBalances` call (the `BalanceDelta` struct). `amount` is the
+ * signed `int256` delta, so it may be negative.
+ */
+export interface ExpectedBalanceChange {
+    token: Address;
+    delta: bigint;
+}
 export interface MulticallOperation<Ext extends object = {}> extends FacadeOperationMetadata {
     operation: "MultiCall" | "BotMulticall";
     creditAccount: Address;
     multicall: InnerOperation<Ext>[];
+    /**
+     * Potential balance changes declared by a router-generated
+     * `storeExpectedBalances`/`compareBalances` pair, or `undefined` when the
+     * multicall is not router-shaped. See {@link ExpectedBalanceChange}.
+     */
+    expectedBalanceChanges?: ExpectedBalanceChange[];
 }
 export interface OpenCreditAccountOperation<Ext extends object = {}> extends FacadeOperationMetadata {
     operation: "OpenCreditAccount";
@@ -82,11 +97,23 @@ export interface OpenCreditAccountOperation<Ext extends object = {}> extends Fac
     onBehalfOf: Address;
     referralCode: bigint;
     multicall: InnerOperation<Ext>[];
+    /**
+     * Potential balance changes declared by a router-generated
+     * `storeExpectedBalances`/`compareBalances` pair, or `undefined` when the
+     * multicall is not router-shaped. See {@link ExpectedBalanceChange}.
+     */
+    expectedBalanceChanges?: ExpectedBalanceChange[];
 }
 export interface CloseCreditAccountOperation<Ext extends object = {}> extends FacadeOperationMetadata {
     operation: "CloseCreditAccount";
     creditAccount: Address;
     multicall: InnerOperation<Ext>[];
+    /**
+     * Potential balance changes declared by a router-generated
+     * `storeExpectedBalances`/`compareBalances` pair, or `undefined` when the
+     * multicall is not router-shaped. See {@link ExpectedBalanceChange}.
+     */
+    expectedBalanceChanges?: ExpectedBalanceChange[];
 }
 export interface LiquidateCreditAccountOperation<Ext extends object = {}> extends FacadeOperationMetadata {
     operation: "LiquidateCreditAccount";
@@ -95,6 +122,12 @@ export interface LiquidateCreditAccountOperation<Ext extends object = {}> extend
     token: Address;
     remainingFunds: bigint;
     multicall: InnerOperation<Ext>[];
+    /**
+     * Potential balance changes declared by a router-generated
+     * `storeExpectedBalances`/`compareBalances` pair, or `undefined` when the
+     * multicall is not router-shaped. See {@link ExpectedBalanceChange}.
+     */
+    expectedBalanceChanges?: ExpectedBalanceChange[];
 }
 export interface PartialLiquidationOperation extends FacadeOperationMetadata {
     operation: "PartiallyLiquidateCreditAccount";

package/dist/types/preview/parse/types-pools.d.ts

@@ -1,9 +1,6 @@
 import type { Address } from "viem";
-import type { TokenTransfer } from "./types-adapters.js";
 /**
  * ERC4626 `deposit` into a Gearbox pool.
- * Token metadata (symbol/decimals) is intentionally omitted: consumers resolve
- * it from `sdk.tokensMeta` using the token addresses below.
  */
 export interface PoolDepositOperation {
     operation: "Deposit";
@@ -14,16 +11,37 @@ export interface PoolDepositOperation {
     underlying: Address;
     /** Referral code, present only for `depositWithReferral` calls. */
     referralCode?: bigint;
-    /**
-     * ERC-20 transfers involving the wallet, recovered by simulating the call.
-     * Empty for the calldata-only parse; populated by the simulation stage.
-     */
-    transfers: TokenTransfer[];
+}
+/**
+ * ERC4626 `mint` into a Gearbox pool. Unlike `deposit`, the caller specifies the
+ * amount of shares to mint; the assets pulled are resolved by the pool.
+ */
+export interface PoolMintOperation {
+    operation: "Mint";
+    pool: Address;
+    receiver: Address;
+    /** Pool shares (diesel) minted to the receiver. */
+    shares: bigint;
+    underlying: Address;
+    /** Referral code, present only for `mintWithReferral` calls. */
+    referralCode?: bigint;
+}
+/**
+ * ERC4626 `withdraw` from a Gearbox pool. Unlike `redeem`, the caller specifies
+ * the amount of underlying assets to withdraw; the shares burned are resolved by
+ * the pool.
+ */
+export interface PoolWithdrawOperation {
+    operation: "Withdraw";
+    pool: Address;
+    receiver: Address;
+    owner: Address;
+    /** Underlying assets withdrawn to the receiver. */
+    assets: bigint;
+    underlying: Address;
 }
 /**
  * ERC4626 `redeem` from a Gearbox pool.
- * Token metadata (symbol/decimals) is intentionally omitted: consumers resolve
- * it from `sdk.tokensMeta` using the token addresses below.
  */
 export interface PoolRedeemOperation {
     operation: "Redeem";
@@ -33,10 +51,5 @@ export interface PoolRedeemOperation {
     /** Pool shares (diesel) burned. */
     shares: bigint;
     underlying: Address;
-    /**
-     * ERC-20 transfers involving the wallet, recovered by simulating the call.
-     * Empty for the calldata-only parse; populated by the simulation stage.
-     */
-    transfers: TokenTransfer[];
 }
-export type PoolOperation = PoolDepositOperation | PoolRedeemOperation;
+export type PoolOperation = PoolDepositOperation | PoolMintOperation | PoolWithdrawOperation | PoolRedeemOperation;

package/dist/types/preview/parse/types.d.ts

@@ -37,8 +37,8 @@ export type SdkWithAdapters<P extends PluginsMap = PluginsMap> = OnchainSDK<P> &
  */
 export type Operation = PoolOperation | OuterFacadeOperation;
 /**
- * Narrows an {@link Operation} to a {@link PoolOperation} (deposit or redeem).
- * Used by the UI to decide whether a custom view exists for the parsed result;
- * everything else falls back to the raw JSON view.
+ * Narrows an {@link Operation} to a {@link PoolOperation} (deposit, mint,
+ * withdraw or redeem). Used by the UI to decide whether a custom view exists for
+ * the parsed result; everything else falls back to the raw JSON view.
  */
 export declare function isPoolOperation(tx: Operation): tx is PoolOperation;

package/dist/types/preview/simulate/constants.d.ts

@@ -0,0 +1,6 @@
+import type { NetworkType } from "../../sdk/chain/index.js";
+/**
+ * Networks where the `eth_simulateV1` JSON-RPC method is available and usable
+ * for pool or credit account operation simulation.
+ **/
+export declare const ETH_SIMULATE_V1_NETWORKS: ReadonlySet<NetworkType>;

package/dist/types/preview/simulate/errors.d.ts

@@ -0,0 +1,51 @@
+import { BaseError, type Hex } from "viem";
+/** Which simulation flow produced a failure. */
+export type SimulationFlowSource = "eth_simulateV1" | "multicall" | "unknown";
+/** A single flow failure with its decoded revert detail. */
+export interface SimulationFlowFailure {
+    source: SimulationFlowSource;
+    detail: SimulationError;
+}
+/**
+ * Error returned by the pool simulation when all attempted flows fail.
+ *
+ * On a single-flow failure it wraps that flow's decoded revert reason; when both
+ * the `eth_simulateV1` and multicall flows fail, it carries the details of both
+ * (see {@link failures}).
+ */
+export declare class PreviewSimulationError extends BaseError {
+    name: string;
+    /** Per-flow decoded failures behind this error. */
+    readonly failures: SimulationFlowFailure[];
+    constructor(failures: SimulationFlowFailure[]);
+}
+/**
+ * Normalises an unknown rejection reason into a {@link PreviewSimulationError}.
+ * Pass-through when it already is one; otherwise decodes it under `source`.
+ */
+export declare function asPreviewSimulationError(reason: unknown, source: SimulationFlowSource): PreviewSimulationError;
+/** Merges several {@link PreviewSimulationError}s into one carrying all failures. */
+export declare function combinePreviewSimulationErrors(...errors: (PreviewSimulationError | undefined)[]): PreviewSimulationError;
+/** Decoded revert of the simulated transaction. */
+export interface SimulationError {
+    /** Human-readable revert reason / error name. */
+    reason: string;
+    /** Original error, kept for debugging. */
+    cause?: unknown;
+}
+/** Per-call slice of a `simulateCalls` failure we need to decode. */
+export interface SimulationRevert {
+    error?: Error;
+    /** Raw revert return data, when present. */
+    data?: Hex;
+}
+/**
+ * Decodes a simulated transaction revert into a {@link SimulationError}.
+ *
+ * The simulated call is raw calldata (no ABI), so viem cannot decode the revert
+ * itself. We first try to decode the raw return bytes against the SDK's
+ * {@link errorAbis} (Gearbox protocol exceptions plus standard ERC-20 custom
+ * errors); failing that, we walk viem's error chain for a
+ * {@link ContractFunctionRevertedError} (covers `Error(string)` / `Panic`).
+ */
+export declare function decodeSimulationError(revert: SimulationRevert): SimulationError;

package/dist/types/preview/simulate/holders.d.ts

@@ -0,0 +1,7 @@
+import type { Address } from "viem";
+import type { PoolOperation } from "../parse/index.js";
+/**
+ * Distinct addresses whose balances change during the operation: the funds
+ * source (payer or share owner) and the receiver.
+ */
+export declare function watchedHolders(operation: PoolOperation, wallet: Address): Address[];

package/dist/types/preview/simulate/index.d.ts

@@ -1,6 +1,9 @@
-export * from "./decodeSimulationError.js";
-export * from "./extractERC20Transfers.js";
-export * from "./simulateFacadeOperation.js";
-export * from "./simulateOperation.js";
-export * from "./simulatePoolOperation.js";
-export * from "./types.js";
+export { ETH_SIMULATE_V1_NETWORKS } from "./constants.js";
+export type { SimulationError, SimulationFlowFailure, SimulationFlowSource, } from "./errors.js";
+export { PreviewSimulationError } from "./errors.js";
+export type { SimulateFacadeOperationInput } from "./simulateFacadeOperation.js";
+export { simulateFacadeOperation } from "./simulateFacadeOperation.js";
+export type { SimulateOperationInput } from "./simulateOperation.js";
+export { simulateOperation } from "./simulateOperation.js";
+export { simulatePoolOperation } from "./simulatePoolOperation.js";
+export type { AddressBalanceChanges, OperationSimulationOptions, PoolOperationSimulation, PoolOperationSimulationInput, PoolOperationSimulationResult, TokenBalanceChange, } from "./types.js";

package/dist/types/preview/simulate/simulateFacadeOperation.d.ts

@@ -1,9 +1,9 @@
 import type { Address, Hex } from "viem";
 import type { OnchainSDK } from "../../sdk/index.js";
 import type { OuterFacadeOperation } from "../parse/index.js";
-import type { PoolSimulationResult } from "./types.js";
+import type { OperationSimulationOptions, PoolOperationSimulation } from "./types.js";
 export interface SimulateFacadeOperationInput {
-    /** Only `client` is used, so any OnchainSDK works. */
+    /** Only `client`/`networkType` are used, so any OnchainSDK works. */
     sdk: OnchainSDK;
     /** Parsed credit-facade operation to simulate. */
     operation: OuterFacadeOperation;
@@ -13,8 +13,6 @@ export interface SimulateFacadeOperationInput {
     calldata: Hex;
     /** Wallet whose balance changes and transfers we track. */
     wallet: Address;
-    /** Block to simulate at; defaults to latest. Only set for testnet forks. */
-    blockNumber?: bigint;
 }
 /**
  * Simulates a credit-facade operation.
@@ -24,4 +22,4 @@ export interface SimulateFacadeOperationInput {
  * signature mirrors {@link simulatePoolOperation} so the
  * {@link simulateOperation} wrapper can delegate uniformly once implemented.
  */
-export declare function simulateFacadeOperation(_input: SimulateFacadeOperationInput): Promise<PoolSimulationResult>;
+export declare function simulateFacadeOperation(_input: SimulateFacadeOperationInput, _options?: OperationSimulationOptions): Promise<PoolOperationSimulation>;

package/dist/types/preview/simulate/simulateOperation.d.ts

@@ -1,11 +1,11 @@
 import type { Address, Hex } from "viem";
 import type { OnchainSDK } from "../../sdk/index.js";
 import { type Operation } from "../parse/index.js";
-import type { PoolSimulationResult } from "./types.js";
+import type { OperationSimulationOptions, PoolOperationSimulation } from "./types.js";
 export interface SimulateOperationInput {
-    /** Only `client` is used, so any OnchainSDK works. */
+    /** Gearbox SDK instance. */
     sdk: OnchainSDK;
-    /** Parsed operation, used to route to the matching simulation. */
+    /** Parsed pool or credit account operation */
     operation: Operation;
     /** Target contract the calldata is sent to. */
     to: Address;
@@ -13,14 +13,8 @@ export interface SimulateOperationInput {
     calldata: Hex;
     /** Wallet whose balance changes and transfers we track. */
     wallet: Address;
-    /** Block to simulate at; defaults to latest. Only set for testnet forks. */
-    blockNumber?: bigint;
 }
 /**
- * Simulates a parsed {@link Operation} by delegating to the matching simulator:
- * pool deposit/redeem operations go to {@link simulatePoolOperation}, and
- * credit-facade operations go to {@link simulateFacadeOperation} (currently a
- * stub). Returns the recovered transfers, balance changes and gas on success,
- * or a decoded revert on failure.
+ * Simulates a parsed pool or credit account operation {@link Operation}
  */
-export declare function simulateOperation(input: SimulateOperationInput): Promise<PoolSimulationResult>;
+export declare function simulateOperation(input: SimulateOperationInput, options?: OperationSimulationOptions): Promise<PoolOperationSimulation>;

package/dist/types/preview/simulate/simulatePoolOpMulticall.d.ts

@@ -0,0 +1,28 @@
+import type { Address } from "viem";
+import type { PoolOperation } from "../parse/index.js";
+import type { AddressBalanceChanges, OperationSimulationOptions, PoolOperationSimulationInput, PoolOperationSimulationResult } from "./types.js";
+/** Reads a watched holder's "before" balance of a token. */
+export type BalanceLookup = (token: Address, holder: Address) => bigint;
+/**
+ * Multicall pool-operation flow, used where `eth_simulateV1` is unavailable or
+ * as a fallback alongside it.
+ *
+ * Reads the watched holders' "before" balances together with the matching
+ * ERC4626 preview (`previewDeposit`/`previewMint`/`previewWithdraw`/
+ * `previewRedeem`) in a single multicall, then computes the theoretical balance
+ * changes via {@link computePoolOpBalanceChanges}.
+ *
+ * Unlike the `eth_simulateV1` flow it does not execute the calldata, so it
+ * cannot recover ERC-20 transfers (`transfers` is always `undefined`) and it
+ * ignores balance/allowance prerequisites (preview reads succeed regardless).
+ *
+ * @throws {@link PreviewSimulationError} when the multicall round-trip throws or
+ * any call (a balance read or the preview read) reverts.
+ */
+export declare function simulatePoolOpMulticall(input: PoolOperationSimulationInput, options?: OperationSimulationOptions): Promise<PoolOperationSimulationResult>;
+/**
+ * Pure computation of {@link AddressBalanceChanges} for a pool operation from
+ * its ERC4626 preview result and the watched holders' "before" balances. Legs
+ * sharing the same address are grouped together.
+ */
+export declare function computePoolOpBalanceChanges(operation: PoolOperation, wallet: Address, previewAmount: bigint, before: BalanceLookup): AddressBalanceChanges[];

package/dist/types/preview/simulate/simulatePoolOpV1.d.ts

@@ -0,0 +1,14 @@
+import type { OperationSimulationOptions, PoolOperationSimulationInput, PoolOperationSimulationResult } from "./types.js";
+/**
+ * `eth_simulateV1` pool-operation flow.
+ *
+ * Sandwiches the raw calldata between `balanceOf` reads of the underlying and
+ * pool (share) tokens for every watched holder, then derives the balance changes
+ * from the before/after diff and the wallet-relevant ERC-20 transfers from the
+ * emitted logs. Simulation runs against real chain state (no overrides), so an
+ * unmet prerequisite surfaces here as a revert.
+ *
+ * @throws {@link PreviewSimulationError} when the round-trip throws or the
+ * simulated transaction reverts.
+ */
+export declare function simulatePoolOpV1(input: PoolOperationSimulationInput, options?: OperationSimulationOptions): Promise<PoolOperationSimulationResult>;

package/dist/types/preview/simulate/simulatePoolOperation.d.ts

@@ -1,30 +1,8 @@
-import { type Address, type Hex } from "viem";
-import type { OnchainSDK } from "../../sdk/index.js";
-import type { PoolOperation } from "../parse/index.js";
-import type { PoolSimulationResult } from "./types.js";
-export interface SimulatePoolOperationInput {
-    /** Only `client` is used, so any OnchainSDK works. */
-    sdk: OnchainSDK;
-    /** Parsed operation, used to resolve the underlying and pool tokens. */
-    operation: PoolOperation;
-    /** Target contract the calldata is sent to (the pool). */
-    to: Address;
-    /** Raw deposit/redeem calldata to simulate. */
-    calldata: Hex;
-    /** Wallet whose balance changes and transfers we track. */
-    wallet: Address;
-    /** Block to simulate at; defaults to latest. Only set for testnet forks. */
-    blockNumber?: bigint;
-}
+import type { OperationSimulationOptions, PoolOperationSimulation, PoolOperationSimulationInput } from "./types.js";
 /**
- * Simulates a pool deposit/redeem by sandwiching the raw calldata between
- * `balanceOf(wallet)` reads of the underlying and pool (share) tokens.
+ * Simulates a pool deposit/mint/withdraw/redeem and returns the resulting
+ * balance changes (and, when available, ERC-20 transfers), or a decoded failure.
  *
- * On success, returns the ERC-20 transfers emitted by the call that involve the
- * wallet or the operation recipient (for merging into the parsed operation) and
- * the balance changes grouped by watched address (wallet, plus the recipient
- * when distinct); on revert, returns the decoded reason. Simulation runs against
- * real chain state (no overrides), so an unmet prerequisite surfaces here as a
- * failure.
+ * @throws {@link PreviewSimulationError} when the simulation fails.
  */
-export declare function simulatePoolOperation(input: SimulatePoolOperationInput): Promise<PoolSimulationResult>;
+export declare function simulatePoolOperation(input: PoolOperationSimulationInput, options?: OperationSimulationOptions): Promise<PoolOperationSimulation>;