@gearbox-protocol/sdk 14.11.3 → 14.12.0-next.2

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

@@ -0,0 +1,115 @@
+import type { Address } from "viem";
+/**
+ * ERC4626 `deposit` into a Gearbox pool.
+ *
+ * A deposit can reach the pool directly (an ERC4626 call sent straight to the
+ * pool contract) or through a zapper (e.g. RWA-default pools and classic zapper
+ * pools). When routed through a zapper, `zapper` is the call target and
+ * `tokenIn` is the zapper's input token rather than the pool underlying.
+ */
+export interface PoolDepositOperation {
+    /** ERC4626 operation kind. */
+    operation: "Deposit";
+    /** Destination pool the assets are deposited into. */
+    pool: Address;
+    /** Address credited with the minted pool shares. */
+    receiver: Address;
+    /** Amount of underlying assets supplied to the pool. */
+    assets: bigint;
+    /** Underlying token of the destination pool. */
+    underlying: Address;
+    /**
+     * Token actually supplied by the caller: the pool underlying for direct
+     * deposits, or the zapper's input token for zapper-routed deposits.
+     */
+    tokenIn: Address;
+    /** Zapper contract the call is sent to; `undefined` for direct deposits. */
+    zapper?: Address;
+    /** Referral code, present only for `depositWithReferral` calls. */
+    referralCode?: bigint;
+}
+/**
+ * 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 {
+    /** ERC4626 operation kind. */
+    operation: "Mint";
+    /** Destination pool the shares are minted from. */
+    pool: Address;
+    /** Address credited with the minted pool shares. */
+    receiver: Address;
+    /** Pool shares (diesel) minted to the receiver. */
+    shares: bigint;
+    /** Underlying token of the destination pool. */
+    underlying: Address;
+    /**
+     * Token actually supplied by the caller: the pool underlying for direct
+     * mints, or the zapper's input token for zapper-routed mints.
+     */
+    tokenIn: Address;
+    /** Zapper contract the call is sent to; `undefined` for direct mints. */
+    zapper?: 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 {
+    /** ERC4626 operation kind. */
+    operation: "Withdraw";
+    /** Source pool the assets are withdrawn from. */
+    pool: Address;
+    /** Address that receives the withdrawn tokens. */
+    receiver: Address;
+    /** Address whose pool shares are burned. */
+    owner: Address;
+    /** Underlying assets withdrawn to the receiver. */
+    assets: bigint;
+    /** Underlying token of the source pool. */
+    underlying: Address;
+    /**
+     * Token actually returned to the receiver: the pool underlying for direct
+     * withdrawals, or the zapper's output token for zapper-routed withdrawals.
+     */
+    tokenOut: Address;
+    /** Zapper contract the call is sent to; `undefined` for direct withdrawals. */
+    zapper?: Address;
+}
+/**
+ * ERC4626 `redeem` from a Gearbox pool.
+ *
+ * A redeem can reach the pool directly or through a zapper. When routed through
+ * a zapper, `zapper` is the call target and `tokenOut` is the zapper's output
+ * token rather than the pool underlying.
+ */
+export interface PoolRedeemOperation {
+    /** ERC4626 operation kind. */
+    operation: "Redeem";
+    /** Source pool the shares are redeemed from. */
+    pool: Address;
+    /** Address that receives the redeemed tokens. */
+    receiver: Address;
+    /** Address whose pool shares are burned. */
+    owner: Address;
+    /** Pool shares (diesel) burned. */
+    shares: bigint;
+    /** Underlying token of the source pool. */
+    underlying: Address;
+    /**
+     * Token actually returned to the receiver: the pool underlying for direct
+     * redeems, or the zapper's output token for zapper-routed redeems.
+     */
+    tokenOut: Address;
+    /** Zapper contract the call is sent to; `undefined` for direct redeems. */
+    zapper?: Address;
+}
+/**
+ * ERC4626 pool operations. Each operation may be sent directly to the pool
+ * contract or routed through a zapper (indicated by the optional `zapper`
+ * field).
+ */
+export type PoolOperation = PoolDepositOperation | PoolMintOperation | PoolWithdrawOperation | PoolRedeemOperation;

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

@@ -0,0 +1,44 @@
+import type { AdaptersPlugin } from "../../plugins/adapters/index.js";
+import type { OnchainSDK, PluginsMap } from "../../sdk/index.js";
+import type { OuterFacadeOperation } from "./types-facades.js";
+import type { PoolOperation } from "./types-pools.js";
+export * from "./types-adapters.js";
+export * from "./types-facades.js";
+export * from "./types-pools.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>;
+/**
+ * Result of decoding a single raw operation calldata: either a pool
+ * deposit/redeem or one of the credit-facade operations.
+ *
+ * Calldata-only parse produces base (descriptor) adapter operations, so the
+ * facade operations are used with the default `Ext = {}`.
+ */
+export type Operation = PoolOperation | OuterFacadeOperation;
+/**
+ * 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/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 { Operation } from "../parse/index.js";
+import type { AnyPrerequisite } from "./Prerequisite.js";
+import type { PrerequisiteContext } from "./types.js";
+/**
+ * Derives the on-chain prerequisites for a parsed operation: 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: Operation, ctx: PrerequisiteContext): AnyPrerequisite[];

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

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

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

@@ -0,0 +1,52 @@
+import { type Address, type Hex } from "viem";
+import type { AnyPrerequisiteResult } from "./types.js";
+/**
+ * A single transaction that satisfies a sender-actionable prerequisite.
+ *
+ * The shape is intentionally minimal (`to`/`data`/optional `value`) so it maps
+ * directly onto wallet send primitives (e.g. viem `sendTransaction`, wagmi
+ * `useSendTransaction`/`useWriteContract`). It is deliberately *not* the heavier
+ * {@link import("../../sdk/types/transactions.js").RawTx} used for Safe batches.
+ *
+ * The `kind` mirrors the prerequisite kind it remediates, so consumers can label
+ * the action (e.g. "Approve") without re-deriving it.
+ */
+export interface PrerequisiteAction {
+    /** Prerequisite kind this action remediates. */
+    kind: "allowance";
+    /** Contract the transaction is sent to (the ERC-20 token for allowances). */
+    to: Address;
+    /** Encoded calldata (e.g. `approve(spender, required)`). */
+    data: Hex;
+    /** Native value to send; omitted (treated as 0) for ERC-20 approvals. */
+    value?: bigint;
+}
+/**
+ * Builds the transaction that resolves an unsatisfied, sender-actionable
+ * prerequisite, or returns `null` when the prerequisite cannot be fixed with a
+ * single wallet transaction.
+ *
+ * Currently only `allowance` is actionable: it returns an ERC-20
+ * `approve(spender, required)` for the exact required amount. `balance`
+ * shortfalls (the user must acquire/free up funds) and errored reads are not
+ * actionable and return `null`. New actionable kinds (permits, native unwrap,
+ * approve-reset-to-zero for non-standard tokens, ...) should be encoded here so
+ * consumers do not have to special-case them.
+ *
+ * Operates on the serializable {@link AnyPrerequisiteResult} produced by
+ * `verifyPrerequisites` (not on {@link import("./Prerequisite.js").Prerequisite}
+ * instances), so it works against cached/persisted results.
+ *
+ * @param result - A verified prerequisite result.
+ * @returns The remediation transaction, or `null` if not auto-actionable.
+ */
+export declare function preparePrerequisiteAction(result: AnyPrerequisiteResult): PrerequisiteAction | null;
+/**
+ * Whether a prerequisite result represents something the sender can fix with a
+ * single wallet transaction (i.e. {@link preparePrerequisiteAction} returns a
+ * transaction for it).
+ *
+ * Useful for UIs that distinguish "approve to continue" (actionable) from hard
+ * blocks like an insufficient balance (not actionable).
+ */
+export declare function isActionablePrerequisite(result: AnyPrerequisiteResult): boolean;

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/errors.d.ts

@@ -0,0 +1,45 @@
+import { BaseError, type Hex } from "viem";
+/** Which simulation flow produced a failure. */
+export type SimulationFlowSource = "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 it fails. It wraps the flow's
+ * decoded revert reason (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;
+/** 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 multicall failure we need to decode. */
+export interface SimulationRevert {
+    error?: Error;
+    /** Raw revert return data, when present. */
+    data?: Hex;
+}
+/**
+ * Decodes a simulated call revert into a {@link SimulationError}.
+ *
+ * We first try to decode any 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

@@ -0,0 +1,8 @@
+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

@@ -0,0 +1,25 @@
+import type { Address, Hex } from "viem";
+import type { OnchainSDK } from "../../sdk/index.js";
+import type { OuterFacadeOperation } from "../parse/index.js";
+import type { OperationSimulationOptions, PoolOperationSimulation } from "./types.js";
+export interface SimulateFacadeOperationInput {
+    /** Only `client`/`networkType` are used, so any OnchainSDK works. */
+    sdk: OnchainSDK;
+    /** Parsed credit-facade operation to simulate. */
+    operation: OuterFacadeOperation;
+    /** Target contract the calldata is sent to (the credit facade). */
+    to: Address;
+    /** Raw credit-facade calldata to simulate. */
+    calldata: Hex;
+    /** Wallet whose balance changes and transfers we track. */
+    wallet: Address;
+}
+/**
+ * Simulates a credit-facade operation.
+ *
+ * Not yet implemented: credit-facade simulation requires multicall-aware
+ * balance/transfer accounting that the pool simulation does not cover. The
+ * signature mirrors {@link simulatePoolOperation} so the
+ * {@link simulateOperation} wrapper can delegate uniformly once implemented.
+ */
+export declare function simulateFacadeOperation(_input: SimulateFacadeOperationInput, _options?: OperationSimulationOptions): Promise<PoolOperationSimulation>;

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

@@ -0,0 +1,20 @@
+import type { Address, Hex } from "viem";
+import type { OnchainSDK } from "../../sdk/index.js";
+import { type Operation } from "../parse/index.js";
+import type { OperationSimulationOptions, PoolOperationSimulation } from "./types.js";
+export interface SimulateOperationInput {
+    /** Gearbox SDK instance. */
+    sdk: OnchainSDK;
+    /** Parsed pool or credit account operation */
+    operation: Operation;
+    /** Target contract the calldata is sent to. */
+    to: Address;
+    /** Raw operation calldata to simulate. */
+    calldata: Hex;
+    /** Wallet whose balance changes and transfers we track. */
+    wallet: Address;
+}
+/**
+ * Simulates a parsed pool or credit account operation {@link Operation}
+ */
+export declare function simulateOperation(input: SimulateOperationInput, options?: OperationSimulationOptions): Promise<PoolOperationSimulation>;

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

@@ -0,0 +1,26 @@
+import type { Address } from "viem";
+import type { PoolOperation } from "../parse/index.js";
+import type { AddressBalanceChanges, OperationSimulationOptions, PoolOperationSimulation, PoolOperationSimulationInput } from "./types.js";
+/** Reads a watched holder's "before" balance of a token. */
+export type BalanceLookup = (token: Address, holder: Address) => bigint;
+/**
+ * Simulates a pool deposit/mint/withdraw/redeem (direct or zapper-routed) and
+ * returns the resulting balance changes, or a decoded failure.
+ *
+ * Reads the watched holders' "before" balances together with the matching
+ * preview (the pool's ERC4626 `previewDeposit`/`previewMint`/`previewWithdraw`/
+ * `previewRedeem`, or the zapper's `previewDeposit`/`previewRedeem`) in a single
+ * multicall, then computes the theoretical balance changes via
+ * {@link computePoolOpBalanceChanges}. It works on every network the SDK
+ * supports.
+ *
+ * It does not execute the calldata, so it ignores balance/allowance
+ * prerequisites (preview reads succeed regardless).
+ */
+export declare function simulatePoolOperation(input: PoolOperationSimulationInput, options?: OperationSimulationOptions): Promise<PoolOperationSimulation>;
+/**
+ * Pure computation of {@link AddressBalanceChanges} for a pool operation from
+ * its 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/types.d.ts

@@ -0,0 +1,66 @@
+import type { Address, Hex } from "viem";
+import type { OnchainSDK } from "../../sdk/index.js";
+import type { ILogger } from "../../sdk/types/logger.js";
+import type { PoolOperation } from "../parse/index.js";
+import type { PreviewSimulationError } from "./errors.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[];
+}
+export interface PoolOperationSimulationInput {
+    /** Only `client`/`networkType` are 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/mint/withdraw/redeem calldata to simulate. */
+    calldata: Hex;
+    /** Wallet whose balance changes and transfers we track. */
+    wallet: Address;
+}
+export interface OperationSimulationOptions {
+    /** Block to simulate at; defaults to latest. */
+    blockNumber?: bigint;
+    /**
+     * Optional logger.
+     **/
+    logger?: ILogger;
+}
+/**
+ * Successful simulation of a pool operation: the balance changes grouped by
+ * watched address. This is the success payload of
+ * {@link PoolOperationSimulation} without the `status` discriminant.
+ */
+export interface PoolOperationSimulationResult {
+    /**
+     * Balance changes grouped by watched address (wallet, recipient, owner).
+     **/
+    balanceChanges: AddressBalanceChanges[];
+}
+/**
+ * Outcome of simulating a pool operation. On success it carries a
+ * {@link PoolOperationSimulationResult}; on failure it carries a
+ * {@link PreviewSimulationError}.
+ */
+export type PoolOperationSimulation = ({
+    status: "success";
+} & PoolOperationSimulationResult) | {
+    status: "failure";
+    error: PreviewSimulationError;
+};