@gearbox-protocol/sdk 14.10.7 → 14.11.0-next.1

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

@@ -0,0 +1,23 @@
+import { isAddressEqual, parseEventLogs } from "viem";
+import { ierc20Abi } from "../../abi/iERC20.js";
+function extractERC20Transfers(logs, watch) {
+  const parsed = parseEventLogs({
+    abi: ierc20Abi,
+    eventName: "Transfer",
+    logs
+  });
+  const transfers = [];
+  for (const log of parsed) {
+    const { from, to, value } = log.args;
+    const involved = watch.some(
+      (address) => isAddressEqual(from, address) || isAddressEqual(to, address)
+    );
+    if (involved) {
+      transfers.push({ token: log.address, amount: value, from, to });
+    }
+  }
+  return transfers;
+}
+export {
+  extractERC20Transfers
+};

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

@@ -0,0 +1,4 @@
+export * from "./decodeSimulationError.js";
+export * from "./extractERC20Transfers.js";
+export * from "./simulatePoolOperation.js";
+export * from "./types.js";

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

@@ -0,0 +1,70 @@
+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))
+  );
+  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 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 {
+    status: "success",
+    transfers: extractERC20Transfers(txResult.logs ?? [], holders),
+    balanceChanges,
+    gasUsed: txResult.gasUsed
+  };
+}
+function readBalance(result) {
+  return result?.status === "success" ? result.result : 0n;
+}
+export {
+  simulatePoolOperation
+};

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

@@ -0,0 +1,3 @@
+export * from "./parse/index.js";
+export * from "./prerequisites/index.js";
+export * from "./simulate/index.js";

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

@@ -0,0 +1,21 @@
+import { type Address } from "viem";
+import type { InnerOperation } from "../../history/index.js";
+import type { OnchainSDK, ParsedCallV2 } from "../../sdk/index.js";
+export interface ClassifyInnerOperationsProps {
+    sdk: OnchainSDK;
+    /** Underlying token of the credit manager, used for debt operations. */
+    underlying: Address;
+}
+/**
+ * Calldata-only counterpart of the SDK's `classifyMulticallOperations`.
+ *
+ * Maps each inner multicall entry to an {@link InnerOperation}:
+ * - adapter targets become an `Execute` {@link AdapterOperation};
+ * - credit-facade self-calls map to the matching inner facade operation;
+ * - unknown targets fall back to a generic `Execute`.
+ *
+ * Since raw calldata has no execution trace, `transfers` is always empty and
+ * `legacy` is a zeroed placeholder; protocol-level fields mirror the adapter
+ * call.
+ */
+export declare function classifyInnerOperations(calls: ParsedCallV2[], props: ClassifyInnerOperationsProps): InnerOperation[];

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

@@ -0,0 +1,17 @@
+import type { Address } from "viem";
+/**
+ * Thrown when the target of a transaction is neither a known Gearbox pool nor a
+ * credit facade.
+ */
+export declare class UnsupportedTargetError extends Error {
+    readonly target: Address;
+    constructor(target: Address);
+}
+/**
+ * Thrown when a pool call uses a function other than ERC4626 `deposit`/`redeem`.
+ */
+export declare class UnsupportedPoolFunctionError extends Error {
+    readonly pool: Address;
+    readonly functionName: string;
+    constructor(pool: Address, functionName: string);
+}

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

@@ -0,0 +1,6 @@
+export * from "./classifyInnerOperations.js";
+export * from "./errors.js";
+export * from "./parseCreditFacadeOperation.js";
+export * from "./parsePoolOperation.js";
+export * from "./parseTransaction.js";
+export * from "./types.js";

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

@@ -0,0 +1,18 @@
+import { type Hex } from "viem";
+import type { OuterFacadeOperation } from "../../history/index.js";
+import type { CreditFacadeV310Contract, OnchainSDK } from "../../sdk/index.js";
+export interface ParseCreditFacadeOperationProps {
+    sdk: OnchainSDK;
+    /** Resolved credit facade contract for the transaction target. */
+    facade: CreditFacadeV310Contract;
+    calldata: Hex;
+}
+/**
+ * Decodes a credit-facade entry-point call into the matching
+ * {@link OuterFacadeOperation}.
+ *
+ * Metadata is partial: `txHash` is `zeroHash` and `timestamp` is `0` because
+ * those are only known once the transaction is mined. `creditAccount` is
+ * `zeroAddress` for `openCreditAccount` (the address is assigned on-chain).
+ */
+export declare function parseCreditFacadeOperation(props: ParseCreditFacadeOperationProps): OuterFacadeOperation;

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

@@ -0,0 +1,15 @@
+import type { Hex } from "viem";
+import type { OnchainSDK, PoolV310Contract } from "../../sdk/index.js";
+import type { PoolOperation } from "./types.js";
+export interface ParsePoolOperationProps {
+    sdk: OnchainSDK;
+    /** Resolved pool contract for the transaction target. */
+    pool: PoolV310Contract;
+    calldata: Hex;
+}
+/**
+ * Decodes ERC4626 `deposit`/`depositWithReferral`/`redeem` calldata on a
+ * Gearbox pool into a {@link PoolOperation}. Any other selector throws
+ * {@link UnsupportedPoolFunctionError}.
+ */
+export declare function parsePoolOperation(props: ParsePoolOperationProps): PoolOperation;

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

@@ -0,0 +1,23 @@
+import type { Address, Hex } from "viem";
+import { type PluginsMap } from "../../sdk/index.js";
+import type { ParsedTransaction, SdkWithAdapters } from "./types.js";
+export interface ParseTransactionInput<P extends PluginsMap = PluginsMap> {
+    /**
+     * Already-attached SDK; chain, RPC and block are baked in at attach time.
+     * Must be created with the adapters plugin (enforced at compile time) so
+     * adapter contracts resolve during multicall classification.
+     */
+    sdk: SdkWithAdapters<P>;
+    to: Address;
+    calldata: Hex;
+    /** Transaction sender, contextual only. */
+    sender: Address;
+}
+/**
+ * Decodes raw transaction calldata into a {@link ParsedTransaction}.
+ *
+ * Routes by the resolved contract at `to`: a pool yields a deposit/redeem
+ * operation, a credit facade yields one facade operation. Anything else throws
+ * {@link UnsupportedTargetError}.
+ */
+export declare function parseTransaction<P extends PluginsMap>(input: ParseTransactionInput<P>): ParsedTransaction;

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

@@ -0,0 +1,78 @@
+import type { Address } from "viem";
+import type { OuterFacadeOperation } from "../../history/index.js";
+import type { AdaptersPlugin, TokenTransfer } from "../../plugins/adapters/index.js";
+import type { OnchainSDK, PluginsMap } from "../../sdk/index.js";
+/**
+ * True when the plugin map `P` contains the {@link AdaptersPlugin} under any
+ * key. Matched nominally (the plugin's private fields make it non-structural),
+ * so unrelated plugins never satisfy it.
+ */
+export type HasAdaptersPlugin<P extends PluginsMap> = Extract<P[keyof P], AdaptersPlugin> extends never ? false : true;
+/**
+ * Compile-time guard for the adapters plugin. Resolves to a no-op (`unknown`)
+ * when `P` includes the {@link AdaptersPlugin}, otherwise to an error-shaped
+ * type that makes the surrounding call fail to type-check.
+ *
+ * Intended to be intersected with a function argument so callers must pass an
+ * SDK whose adapter contracts are registered (required for multicall
+ * classification).
+ */
+export type RequireAdaptersPlugin<P extends PluginsMap> = HasAdaptersPlugin<P> extends true ? unknown : {
+    "OnchainSDK must be created with the AdaptersPlugin": never;
+};
+/**
+ * {@link OnchainSDK} whose plugin map is guaranteed at compile time to include
+ * the {@link AdaptersPlugin}.
+ */
+export type SdkWithAdapters<P extends PluginsMap = PluginsMap> = OnchainSDK<P> & RequireAdaptersPlugin<P>;
+/**
+ * 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";
+    pool: Address;
+    receiver: Address;
+    /** Underlying assets supplied to the pool. */
+    assets: bigint;
+    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 `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";
+    pool: Address;
+    receiver: Address;
+    owner: Address;
+    /** 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;
+/**
+ * Narrows a {@link ParsedTransaction} 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.
+ */
+export declare function isPoolOperation(tx: ParsedTransaction): tx is PoolOperation;
+/**
+ * Result of decoding a single raw transaction calldata: either a pool
+ * deposit/redeem or one of the credit-facade operations from `sdk/history`.
+ */
+export type ParsedTransaction = PoolOperation | OuterFacadeOperation;

package/dist/types/preview/prerequisites/AllowancePrerequisite.d.ts

@@ -0,0 +1,24 @@
+import { type Address, type ContractFunctionParameters } from "viem";
+import { type MulticallCallResult, Prerequisite } from "./Prerequisite.js";
+import type { PrerequisiteDetail, PrerequisiteResult } from "./types.js";
+export interface AllowancePrerequisiteProps {
+    token: Address;
+    owner: Address;
+    spender: Address;
+    required: bigint;
+    title?: string;
+    id?: string;
+}
+/** Checks that `owner` granted `spender` an ERC-20 allowance >= `required`. */
+export declare class AllowancePrerequisite extends Prerequisite<"allowance"> {
+    private readonly _id;
+    private readonly _title;
+    private readonly _detail;
+    constructor(props: AllowancePrerequisiteProps);
+    get id(): string;
+    get kind(): "allowance";
+    get title(): string;
+    get detail(): PrerequisiteDetail<"allowance">;
+    calls(): ContractFunctionParameters[];
+    resolve(slice: MulticallCallResult[]): PrerequisiteResult<"allowance">;
+}

package/dist/types/preview/prerequisites/BalancePrerequisite.d.ts

@@ -0,0 +1,23 @@
+import { type Address, type ContractFunctionParameters } from "viem";
+import { type MulticallCallResult, Prerequisite } from "./Prerequisite.js";
+import type { PrerequisiteDetail, PrerequisiteResult } from "./types.js";
+export interface BalancePrerequisiteProps {
+    token: Address;
+    owner: Address;
+    required: bigint;
+    title?: string;
+    id?: string;
+}
+/** Checks that `owner` holds an ERC-20 balance >= `required`. */
+export declare class BalancePrerequisite extends Prerequisite<"balance"> {
+    private readonly _id;
+    private readonly _title;
+    private readonly _detail;
+    constructor(props: BalancePrerequisiteProps);
+    get id(): string;
+    get kind(): "balance";
+    get title(): string;
+    get detail(): PrerequisiteDetail<"balance">;
+    calls(): ContractFunctionParameters[];
+    resolve(slice: MulticallCallResult[]): PrerequisiteResult<"balance">;
+}

package/dist/types/preview/prerequisites/Prerequisite.d.ts

@@ -0,0 +1,60 @@
+import { type ContractFunctionParameters } from "viem";
+import type { PrerequisiteContext, PrerequisiteDetail, PrerequisiteError, PrerequisiteKind, PrerequisiteResult } from "./types.js";
+/**
+ * One entry of a viem `multicall({ allowFailure: true })` response: either a
+ * decoded `result` or the `error` that the call reverted with.
+ */
+export type MulticallCallResult = {
+    status: "success";
+    result: unknown;
+    error?: undefined;
+} | {
+    status: "failure";
+    result?: undefined;
+    error: Error;
+};
+/**
+ * Decodes an unknown error into a {@link PrerequisiteError} with a
+ * human-readable revert reason. Mirrors the SDK's `extractCallError`: walk the
+ * viem error chain for a {@link ContractFunctionRevertedError} and use its
+ * `errorName`, otherwise fall back to the error's short message / name.
+ */
+export declare function toPrerequisiteError(cause: unknown): PrerequisiteError;
+/**
+ * A single verifiable prerequisite for a transaction. Subclasses describe the
+ * on-chain reads they need ({@link calls}) and how to turn the multicall slice
+ * into a {@link PrerequisiteResult} ({@link resolve}).
+ *
+ * Identity (`id`, `kind`, `title`) and build-time `detail` are exposed as
+ * read-only accessors; subclasses back them with private fields. The shared
+ * {@link satisfiedResult}/{@link errorResult} helpers are `protected` so each
+ * subclass builds results consistently.
+ *
+ * The same instance can be verified standalone via {@link verify} or batched
+ * together with others by `verifyPrerequisites`.
+ */
+export declare abstract class Prerequisite<K extends PrerequisiteKind> {
+    /** Stable identifier, used as a React key and for deduplication. */
+    abstract get id(): string;
+    /** Discriminant tying this check to its detail payload. */
+    abstract get kind(): K;
+    /** Human-readable label shown in the UI. */
+    abstract get title(): string;
+    /** Inputs known before reading the chain (no `actual` yet). */
+    abstract get detail(): PrerequisiteDetail<K>;
+    /** Contract reads this check needs (usually one). */
+    abstract calls(ctx: PrerequisiteContext): ContractFunctionParameters[];
+    /** Maps this check's slice of the multicall response into a result. */
+    abstract resolve(slice: MulticallCallResult[]): PrerequisiteResult<K>;
+    /**
+     * Verifies this prerequisite on its own using an `allowFailure` multicall.
+     * Prefer `verifyPrerequisites` to batch several checks into one round-trip.
+     */
+    verify(ctx: PrerequisiteContext): Promise<PrerequisiteResult<K>>;
+    /** Builds a successful result; `detail` carries the on-chain `actual`. */
+    protected satisfiedResult(satisfied: boolean, detail: PrerequisiteDetail<K>): PrerequisiteResult<K>;
+    /** Builds a failed result from a decoded read error. */
+    protected errorResult(error: PrerequisiteError): PrerequisiteResult<K>;
+}
+/** Any prerequisite regardless of its kind, used for heterogeneous lists. */
+export type AnyPrerequisite = Prerequisite<PrerequisiteKind>;

package/dist/types/preview/prerequisites/buildPrerequisites.d.ts

@@ -0,0 +1,16 @@
+import type { ParsedTransaction } from "../parse/index.js";
+import type { AnyPrerequisite } from "./Prerequisite.js";
+import type { PrerequisiteContext } from "./types.js";
+/**
+ * Derives the on-chain prerequisites for a parsed transaction: the conditions
+ * that must hold for the call not to revert and that we can verify with the
+ * SDK (token approvals, wallet balances).
+ *
+ * Only *sender-actionable* prerequisites belong here: conditions the LP
+ * provider or borrower can fix themselves before retrying (e.g. approve a
+ * token, top up a balance). Non-actionable protocol/admin state (pool pause,
+ * available pool liquidity, health factor, liquidatability, degen NFT gating,
+ * bot permissions) is intentionally out of scope, since the user cannot
+ * resolve it. New {@link AnyPrerequisite} subclasses must follow the same rule.
+ */
+export declare function buildPrerequisites(tx: ParsedTransaction, ctx: PrerequisiteContext): AnyPrerequisite[];

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

@@ -0,0 +1,6 @@
+export * from "./AllowancePrerequisite.js";
+export * from "./BalancePrerequisite.js";
+export * from "./buildPrerequisites.js";
+export * from "./Prerequisite.js";
+export * from "./runPrerequisites.js";
+export * from "./types.js";

package/dist/types/preview/prerequisites/runPrerequisites.d.ts

@@ -0,0 +1,12 @@
+import type { AnyPrerequisite } from "./Prerequisite.js";
+import type { AnyPrerequisiteResult, PrerequisiteContext } from "./types.js";
+/**
+ * Verifies all prerequisites in a single resilient multicall.
+ *
+ * Every prereq contributes its reads to one `multicall({ allowFailure: true })`
+ * batch, then resolves its own slice of the response. A read that reverts
+ * isolates to that prerequisite (an `error` result) without affecting the
+ * others; if the whole round-trip fails (RPC/network), every prerequisite
+ * resolves to an `error` carrying that reason.
+ */
+export declare function verifyPrerequisites(prereqs: AnyPrerequisite[], ctx: PrerequisiteContext): Promise<AnyPrerequisiteResult[]>;

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

@@ -0,0 +1,78 @@
+import type { Address } from "viem";
+import type { OnchainSDK } from "../../sdk/index.js";
+/**
+ * Extension point that ties each prerequisite kind to its detail payload.
+ *
+ * Adding a new prerequisite kind only requires a new entry here: the generic
+ * machinery below and the UI renderer registry both key off this map, so TS
+ * forces every consumer to handle the new kind.
+ *
+ * IMPORTANT: only add prerequisites that are *actionable by the transaction
+ * sender* (the LP provider or borrower). A valid prerequisite is one the user
+ * can resolve themselves before retrying, e.g. approve a token (`allowance`)
+ * or acquire/free up funds (`balance`). Do NOT add protocol- or admin-level
+ * state the user cannot change, such as pool pause status or available pool
+ * liquidity; those are not actionable and must not be listed as prerequisites.
+ */
+export interface PrerequisiteDetailMap {
+    /** ERC-20 allowance from `owner` to `spender` must cover `required`. */
+    allowance: {
+        token: Address;
+        owner: Address;
+        spender: Address;
+        required: bigint;
+        /** On-chain allowance read; only present when the read succeeded. */
+        actual?: bigint;
+    };
+    /** ERC-20 balance of `owner` must cover `required`. */
+    balance: {
+        token: Address;
+        owner: Address;
+        required: bigint;
+        /** On-chain balance read; only present when the read succeeded. */
+        actual?: bigint;
+    };
+}
+export type PrerequisiteKind = keyof PrerequisiteDetailMap;
+export type PrerequisiteDetail<K extends PrerequisiteKind = PrerequisiteKind> = PrerequisiteDetailMap[K];
+/** Failure of the underlying on-chain read (revert, decode error, RPC error). */
+export interface PrerequisiteError {
+    /** Decoded revert reason / error name, human-readable. */
+    reason: string;
+    /** Original error, kept for debugging. */
+    cause?: unknown;
+}
+export interface PrerequisiteBase<K extends PrerequisiteKind> {
+    id: string;
+    kind: K;
+    title: string;
+    detail: PrerequisiteDetail<K>;
+}
+/**
+ * Outcome of verifying a single prerequisite: either the read succeeded (a
+ * `satisfied` boolean) or it reverted/failed (an `error` with the revert
+ * reason). The two variants are mutually exclusive.
+ */
+export type PrerequisiteResult<K extends PrerequisiteKind = PrerequisiteKind> = PrerequisiteBase<K> & ({
+    satisfied: boolean;
+    error?: undefined;
+} | {
+    satisfied?: undefined;
+    error: PrerequisiteError;
+});
+/**
+ * Discriminated union over every prerequisite kind. Switching on `kind`
+ * narrows `detail` to the matching payload, so React components can render
+ * kind-specific details with full type safety.
+ */
+export type AnyPrerequisiteResult = {
+    [K in PrerequisiteKind]: PrerequisiteResult<K>;
+}[PrerequisiteKind];
+/** Shared inputs for building and verifying prerequisites. */
+export interface PrerequisiteContext {
+    sdk: OnchainSDK;
+    /** Address whose balances/allowances are checked (the tx sender). */
+    wallet: Address;
+    /** Block to read at; defaults to latest. Only set for testnet forks. */
+    blockNumber?: bigint;
+}

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

@@ -0,0 +1,18 @@
+import { type Hex } from "viem";
+import type { SimulationError } from "./types.js";
+/** 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/extractERC20Transfers.d.ts

@@ -0,0 +1,11 @@
+import { type Address, type Log } from "viem";
+import type { TokenTransfer } from "../../plugins/adapters/index.js";
+/**
+ * Parses ERC-20 `Transfer` logs and keeps only those involving one of the
+ * watched addresses (as sender or receiver). A log that touches several watched
+ * addresses is still emitted once.
+ *
+ * @param logs - raw logs from the simulated call
+ * @param watch - addresses whose transfers we care about (e.g. wallet + recipient)
+ */
+export declare function extractERC20Transfers(logs: Log[], watch: Address[]): TokenTransfer[];

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

@@ -0,0 +1,4 @@
+export * from "./decodeSimulationError.js";
+export * from "./extractERC20Transfers.js";
+export * from "./simulatePoolOperation.js";
+export * from "./types.js";

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

@@ -0,0 +1,30 @@
+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;
+}
+/**
+ * Simulates a pool deposit/redeem by sandwiching the raw calldata between
+ * `balanceOf(wallet)` reads of the underlying and pool (share) tokens.
+ *
+ * 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.
+ */
+export declare function simulatePoolOperation(input: SimulatePoolOperationInput): Promise<PoolSimulationResult>;

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

@@ -0,0 +1,43 @@
+import type { Address } from "viem";
+import type { TokenTransfer } from "../../plugins/adapters/index.js";
+/**
+ * Change in an address's balance of a single token over the simulated call.
+ * `delta` is `after - before` (negative when the address spent the token).
+ */
+export interface TokenBalanceChange {
+    token: Address;
+    before: bigint;
+    after: bigint;
+    delta: bigint;
+}
+/**
+ * Balance changes for a single watched address (e.g. the wallet or the
+ * operation recipient). Keyed purely by address; UI labeling is resolved
+ * separately by the presentation layer.
+ */
+export interface AddressBalanceChanges {
+    address: Address;
+    changes: TokenBalanceChange[];
+}
+/** Decoded revert of the simulated transaction. */
+export interface SimulationError {
+    /** Human-readable revert reason / error name. */
+    reason: string;
+    /** Original error, kept for debugging. */
+    cause?: unknown;
+}
+/**
+ * Outcome of simulating a pool operation. On success it carries the
+ * wallet-filtered ERC-20 transfers (to merge into the parsed operation) and the
+ * balance changes grouped by watched address; on failure it carries the decoded
+ * revert reason.
+ */
+export type PoolSimulationResult = {
+    status: "success";
+    transfers: TokenTransfer[];
+    balanceChanges: AddressBalanceChanges[];
+    gasUsed: bigint;
+} | {
+    status: "failure";
+    error: SimulationError;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gearbox-protocol/sdk",
-  "version": "14.10.7",
+  "version": "14.11.0-next.1",
   "description": "Gearbox SDK",
   "license": "MIT",
   "repository": {
@@ -44,6 +44,11 @@
       "import": "./dist/esm/permissionless/index.js",
       "default": "./dist/cjs/permissionless/index.js"
     },
+    "./preview": {
+      "types": "./dist/types/preview/index.d.ts",
+      "import": "./dist/esm/preview/index.js",
+      "default": "./dist/cjs/preview/index.js"
+    },
     "./common-utils": {
       "types": "./dist/types/common-utils/index.d.ts",
       "import": "./dist/esm/common-utils/index.js",