@gearbox-protocol/sdk 13.3.2 → 13.3.4

package/dist/types/sdk/market/pricefeeds/types.d.ts

@@ -2,40 +2,100 @@ import type { Address, Hex, UnionOmit } from "viem";
 import type { IBaseContract, PriceFeedAnswer } from "../../base/index.js";
 import type { IPriceUpdateTx, PriceFeedStateHuman, RawTx } from "../../types/index.js";
 import type { PriceFeedRef } from "./PriceFeedRef.js";
+/**
+ * @internal
+ * Indicates whether a price feed is used as the primary ("Main") or
+ * fallback ("Reserve") oracle for a token. Gearbox uses dual-oracle
+ * pricing to protect against oracle manipulation.
+ **/
 export type PriceFeedUsageType = "Main" | "Reserve";
+/**
+ * Discriminator for the various on-chain price feed contract implementations
+ * (e.g. Curve LP, Balancer, Pyth, Redstone).
+ **/
 export type PriceFeedContractType = "PRICE_FEED::BALANCER_STABLE" | "PRICE_FEED::BALANCER_WEIGHTED" | "PRICE_FEED::BOUNDED" | "PRICE_FEED::COMPOSITE" | "PRICE_FEED::CONSTANT" | "PRICE_FEED::CURVE_CRYPTO" | "PRICE_FEED::CURVE_STABLE" | "PRICE_FEED::CURVE_USD" | "PRICE_FEED::ERC4626" | "PRICE_FEED::EXTERNAL" | "PRICE_FEED::MELLOW_LRT" | "PRICE_FEED::PENDLE_PT_TWAP" | "PRICE_FEED::PYTH" | "PRICE_FEED::REDSTONE" | "PRICE_FEED::WSTETH" | "PRICE_FEED::YEARN" | "PRICE_FEED::ZERO";
+/**
+ * Public interface for a single price feed contract.
+ *
+ * A price feed converts an on-chain or off-chain data source into a
+ * USD-denominated price with 8 decimals. Feeds are organized into trees:
+ * composite feeds may depend on several underlying feeds.
+ **/
 export interface IPriceFeedContract extends IBaseContract {
+    /**
+     * Whether this price feed enforces a lower-bound cap on its answer.
+     **/
     readonly hasLowerBoundCap: boolean;
+    /**
+     * Discriminator identifying gearbox price feed type
+     **/
     readonly priceFeedType: PriceFeedContractType;
+    /**
+     * Number of decimals in the price answer (typically 8).
+     **/
     readonly decimals: number;
     /**
-     * True if the contract deployed at this address implements IUpdatablePriceFeed interface
-     */
+     * `true` if the on-chain contract implements `IUpdatablePriceFeed`,
+     * meaning its price can be refreshed via an off-chain data push.
+     **/
     readonly updatable: boolean;
     /**
-     * It's possible to create PriceFeed with base params only.
-     * This flag idicates that all the price feed data (decimals, skip check, dependencies...) has been loaded from compressor
-     */
+     * @internal
+     * `true` once the full feed configuration (decimals, skip-check flag,
+     * dependencies, etc.) has been loaded. A feed created from base params
+     * alone will have `loaded === false`.
+     **/
     readonly loaded: boolean;
     /**
-     * Latest answer for this price feed
-     */
+     * Latest price answer for this feed.
+     **/
     readonly answer: PriceFeedAnswer;
+    /**
+     * Whether price feed implements its own safety and staleness checks
+     **/
     readonly skipCheck: boolean;
+    /**
+     * Immediate child feeds that this composite feed depends on.
+     **/
     readonly underlyingPriceFeeds: readonly PriceFeedRef[];
+    /**
+     * Replaces the cached answer with a new value.
+     * @param answer - New price answer to store.
+     **/
     updateAnswer: (answer: PriceFeedAnswer) => void;
+    /**
+     * Returns a human-readable snapshot of this feed's state.
+     * @param raw - When `true`, includes raw/unformatted values.
+     **/
     stateHuman: (raw?: boolean) => UnionOmit<PriceFeedStateHuman, "stalenessPeriod">;
     /**
-     * Returns all updatable depenedencies (uderlying price feeds) of this price feed, including price feed itself, if it's updatable
-     * @returns
-     */
+     * Collects all updatable feeds in this feed's dependency tree,
+     * including this feed itself when it is updatable.
+     **/
     updatableDependencies: () => IUpdatablePriceFeedContract[];
 }
+/**
+ * Extended price feed interface for feeds whose price can be refreshed
+ * via an off-chain data push (e.g. Pyth or Redstone feeds).
+ **/
 export interface IUpdatablePriceFeedContract extends IPriceFeedContract {
+    /**
+     * Builds a raw transaction that pushes new price data to the on-chain feed.
+     * @param data - ABI-encoded update payload.
+     **/
     createPriceUpdateTx: (data: `0x${string}`) => RawTx;
 }
+/**
+ * Result of generating price-feed update transactions.
+ **/
 export interface UpdatePriceFeedsResult {
+    /**
+     * Transactions that push fresh prices to updatable feeds.
+     **/
     txs: IPriceUpdateTx[];
+    /**
+     * Latest timestamp among all fetched price updates (unix seconds).
+     **/
     timestamp: number;
 }
 export interface PriceUpdateV310 {

package/dist/types/sdk/options.d.ts

@@ -1,6 +1,9 @@
 import { z } from "zod/v4";
 import type { PluginsMap } from "./plugins/index.js";
 import type { ILogger } from "./types/index.js";
+/**
+ * Zod schema for validating {@link SDKOptions} at runtime.
+ **/
 export declare const SDKOptions: z.ZodObject<{
     addressProvider: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<`0x${string}`, string>>>;
     marketConfigurators: z.ZodOptional<z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<`0x${string}`, string>>>>;
@@ -25,13 +28,19 @@ export declare const SDKOptions: z.ZodObject<{
     }, z.core.$strip>>;
     gasLimit: z.ZodOptional<z.ZodNullable<z.ZodBigInt>>;
 }, z.core.$strip>;
+/**
+ * Configuration options accepted by {@link GearboxSDK.attach} and related
+ * factory methods.
+ *
+ * @typeParam Plugins - Map of plugin names to plugin instances.
+ **/
 export type SDKOptions<Plugins extends PluginsMap> = Omit<z.infer<typeof SDKOptions>, "logger" | "plugins"> & {
     /**
-     * Plugins to extends SDK functionality
-     */
+     * Plugins that extend SDK functionality.
+     **/
     plugins?: Plugins;
     /**
-     * Bring your own logger
-     */
+     * Custom logger implementation.
+     **/
     logger?: ILogger;
 };

package/dist/types/sdk/plugins/BasePlugin.d.ts

@@ -2,18 +2,57 @@ import type { Address, PublicClient } from "viem";
 import type { NetworkType } from "../chain/index.js";
 import type { GearboxSDK } from "../GearboxSDK.js";
 import type { ILogger } from "../index.js";
+/**
+ * Convenience base class for {@link IGearboxSDKPlugin} implementations.
+ *
+ * Handles the SDK attachment lifecycle, logger setup, and provides
+ * common accessors (`network`, `client`). Subclasses only need to
+ * implement {@link load} to supply their domain-specific state.
+ *
+ * @typeParam TState - Plugin-specific state shape.
+ **/
 export declare abstract class BasePlugin<TState extends Record<keyof TState, unknown> = {}> {
     #private;
     protected logger?: ILogger;
+    /**
+     * Plugin state version for hydration compatibility checks.
+     * @default 1
+     **/
     readonly version: number;
+    /**
+     * When `true`, state is fetched eagerly during the `attach` phase
+     * rather than waiting for an explicit `load` call.
+     **/
     readonly loadOnAttach: boolean;
     constructor(loadOnAttach?: boolean);
+    /**
+     * Reference to the parent SDK instance.
+     * @throws Error if the SDK has not been attached yet.
+     **/
     get sdk(): GearboxSDK<any>;
     set sdk(sdk: GearboxSDK<any>);
+    /**
+     * {@inheritDoc IGearboxSDKPlugin.attach}
+     **/
     attach(): Promise<void>;
+    /**
+     * {@inheritDoc IGearboxSDKPlugin.syncState}
+     **/
     syncState(): Promise<void>;
+    /**
+     * Loads or refreshes the plugin state.
+     *
+     * @param force - When `true`, re-fetch even if state is already loaded.
+     * @returns The loaded plugin state.
+     **/
     abstract load(force?: boolean): Promise<TState>;
+    /**
+     * Network type of the connected chain (e.g. `"Mainnet"`, `"Arbitrum"`).
+     **/
     get network(): NetworkType;
+    /**
+     * Viem public client for read-only chain interactions.
+     **/
     get client(): PublicClient;
     protected labelAddress(address: Address): string;
 }

package/dist/types/sdk/plugins/types.d.ts

@@ -1,5 +1,13 @@
 import type { BaseState, IBaseContract } from "../base/index.js";
 import type { GearboxSDK } from "../GearboxSDK.js";
+/**
+ * Serialisable snapshot of a plugin's state, used for hydration.
+ *
+ * When `loaded` is `false` only the `version` field is present;
+ * when `loaded` is `true` the full `State` payload is included.
+ *
+ * @typeParam State - Plugin-specific state shape.
+ **/
 export type IPluginState<State extends Record<keyof State, unknown> = {}> = {
     version: number;
 } & ({
@@ -7,77 +15,99 @@ export type IPluginState<State extends Record<keyof State, unknown> = {}> = {
 } | ({
     loaded: true;
 } & State));
+/**
+ * @internal
+ * Constructor signature that the SDK uses to instantiate a plugin.
+ *
+ * @typeParam TState  - Plugin-specific state shape.
+ * @typeParam TPlugin - Concrete plugin type produced by the constructor.
+ **/
 export type IGearboxSDKPluginConstructor<TState extends Record<keyof TState, unknown>, TPlugin extends IGearboxSDKPlugin<TState>> = new (sdk: GearboxSDK<any>) => TPlugin;
+/**
+ * Public contract every SDK plugin must satisfy.
+ *
+ * Plugins extend the SDK with domain-specific data and behaviour
+ * (e.g. farming rewards, zapper helpers). They participate in the
+ * SDK lifecycle: attach, hydrate, sync, and on-demand load.
+ *
+ * @typeParam TState - Plugin-specific state shape.
+ **/
 export interface IGearboxSDKPlugin<TState extends Record<keyof TState, unknown> = {}> {
     /**
-     * Plugin's SDK. Is set by SDK itself in SDK constructor
-     */
+     * Reference to the parent SDK instance.
+     * Set automatically by the SDK constructor.
+     **/
     sdk: GearboxSDK<any>;
     /**
-     * Plugin version, used to check if the plugin state is compatible with the plugin during hydration
-     */
+     * Plugin version, used to verify state compatibility during hydration.
+     **/
     version: number;
     /**
-     * Indicates that plugins state is ready to use
-     * It does not matter how this state was obtained, be it via attach, hydrate or on-demand load
-     */
+     * Whether the plugin's state is ready to use.
+     * `true` regardless of how the state was obtained (attach, hydrate, or on-demand load).
+     **/
     loaded: boolean;
     /**
-     * Plugin state, can be hydarted/dehydrated
-     */
+     * Plugin state, can be hydrated later.
+     **/
     state: TState;
     /**
-     * Loads state on demand
-     * If it's already loaded, does nothing and returns the same state, unless force is set to true
-     * @param force
-     * @returns
-     */
+     * Loads state on demand.
+     * If already loaded, returns the existing state unless `force` is `true`.
+     *
+     * @param force - Re-fetch even if state is already loaded.
+     * @returns The loaded plugin state.
+     **/
     load?: (force?: boolean) => Promise<TState>;
     /**
-     * Called after SDK is attached
-     * Plugins are not required to implement this. For example plugin can be stateless, or load state on demand only
-     * @param sdk
-     * @returns
-     */
+     * Called after SDK is attached to the chain.
+     * Plugins are not required to implement this — a plugin can be stateless
+     * or load state on demand only.
+     **/
     attach?: () => Promise<void>;
     /**
-     * Loads plugin state from dehydrated state
-     * @param state
-     * @returns
-     */
+     * Restores plugin state from a previously saved snapshot.
+     *
+     * @param state - state to restore from.
+     **/
     hydrate?: (state: TState) => void;
     /**
-     * Called after SDK state is already synced, meaning that block number and timestamp are accessible from SDK
-     *
-     * @param sdk
-     * @returns
-     */
+     * Hook to sync plugin state after sdk state is synced.
+     * Called after SDK state is already synced, meaning that block number
+     * and timestamp are accessible from the SDK.
+     **/
     syncState?: () => Promise<void>;
     /**
-     * Can be called by SDK to create some auxiliary contracts, such as zappers and adapters
-     * Otherwise they are created as BaseContract instances by sdk
-     * @param params
-     * @returns
-     */
+     * Factory hook called by the SDK to create auxiliary contracts
+     * (e.g. zappers, adapters). If not implemented, the SDK falls back to
+     * generic {@link BaseContract} instances.
+     *
+     * @param params - On-chain identification parameters for the contract.
+     * @returns A contract instance, or `undefined` to let the SDK use the default.
+     **/
     createContract?: (params: BaseState) => IBaseContract | undefined;
     /**
-     * Human readable state for diagnostics
-     * @param raw (print actual values in addition to human-friendly values, e.g. 1 ETH (1000000000000000000))
-     * @returns
-     */
+     * Human-readable state snapshot for diagnostics.
+     *
+     * @param raw - When `true`, include raw numeric values alongside formatted ones
+     *   (e.g. `1 ETH (1000000000000000000)`).
+     * @returns An untyped object suitable for logging or inspection.
+     **/
     stateHuman?: (raw?: boolean) => unknown;
 }
 /**
- * Helper type that extracts the state type from a plugin instance
- */
+ * Helper type that extracts the state type from a plugin instance.
+ **/
 export type PluginState<T> = T extends IGearboxSDKPlugin<infer TState> ? IPluginState<TState> : never;
 /**
- * Mapping between plugin name and plugin instance
- */
+ * @internal
+ * Mapping between plugin name and plugin instance.
+ **/
 export type PluginsMap = Record<string, IGearboxSDKPlugin<any>>;
 /**
- * Mapping that infers plugin states map from plugin instances map
- */
+ * @internal
+ * Mapping that infers plugin states from plugin instances.
+ **/
 export type PluginStatesMap<T extends PluginsMap> = {
     [K in keyof T]: PluginState<T[K]>;
 };

package/dist/types/sdk/pools/AbstractPoolService.d.ts

@@ -1,9 +1,21 @@
 import { SDKConstruct } from "../base/index.js";
 import type { GearboxSDK } from "../GearboxSDK.js";
 import type { AddLiquidityCall, AddLiquidityProps, RemoveLiquidityCall, RemoveLiquidityProps } from "./types.js";
+/**
+ * @internal
+ * Base implementation of {@link IPoolsService}.
+ *
+ * Used to generate data for write operations on LP side (deposit to/withdraw from pool)
+ **/
 export declare abstract class AbstractPoolService extends SDKConstruct {
     #private;
     constructor(sdk: GearboxSDK, version: number);
+    /**
+     * {@inheritDoc IPoolsService.addLiquidity}
+     **/
     addLiquidity({ collateral, pool, account, zapper, permit, nativeTokenAddress, referralCode, migrate, }: AddLiquidityProps): AddLiquidityCall;
+    /**
+     * {@inheritDoc IPoolsService.removeLiquidity}
+     **/
     removeLiquidity({ pool, amount, account, zapper, permit, }: RemoveLiquidityProps): RemoveLiquidityCall;
 }

package/dist/types/sdk/pools/types.d.ts

@@ -20,16 +20,54 @@ interface PermitResult {
     deadline: bigint;
     nonce: bigint;
 }
+/**
+ * Parameters for depositing liquidity into a Gearbox lending pool.
+ *
+ * When a `zapper` is provided, the deposit is routed through a zapper
+ * contract that handles token conversions (e.g. native ETH wrapping or
+ * ERC-20 permit-based approvals). Without a zapper, the deposit goes
+ * directly to the pool contract.
+ **/
 export interface AddLiquidityProps {
+    /**
+     * Token and amount to deposit.
+     **/
     collateral: Asset;
+    /**
+     * Address of the Gearbox lending pool.
+     **/
     pool: Address;
+    /**
+     * Recipient of the pool shares (diesel tokens).
+     **/
     account: Address;
+    /**
+     * Whether this deposit is part of a pool migration.
+     * When `true`, a zapper is required.
+     **/
     migrate: boolean;
+    /**
+     * Optional zapper to route the deposit through.
+     **/
     zapper: IZapper | undefined;
+    /**
+     * Optional ERC-2612 permit for gasless token approval.
+     **/
     permit: PermitResult | undefined;
+    /**
+     * Address of the chain's native-token wrapper (e.g. WETH).
+     **/
     nativeTokenAddress: Address;
+    /**
+     * Optional referral code for tracking the deposit source.
+     **/
     referralCode: bigint | undefined;
 }
+/**
+ * Tuple describing a single contract call to execute an add-liquidity
+ * operation. The exact variant depends on whether a zapper and/or
+ * permit is used.
+ **/
 export type AddLiquidityCall = [
     {
         target: Address;
@@ -54,13 +92,39 @@ export type AddLiquidityCall = [
         args: [bigint, Address, bigint];
     }
 ];
+/**
+ * Parameters for withdrawing liquidity from a Gearbox lending pool.
+ *
+ * Withdrawals are routed through a zapper that redeems pool shares
+ * (diesel tokens) for the underlying asset.
+ **/
 export interface RemoveLiquidityProps {
+    /**
+     * Address of the Gearbox lending pool.
+     **/
     pool: Address;
+    /**
+     * Amount of pool shares (diesel tokens) to redeem.
+     **/
     amount: bigint;
+    /**
+     * Recipient of the redeemed underlying tokens.
+     **/
     account: Address;
+    /**
+     * Optional ERC-2612 permit for gasless token approval.
+     **/
     permit: PermitResult | undefined;
+    /**
+     * Zapper to route the redemption through.
+     **/
     zapper: IZapper;
 }
+/**
+ * Tuple describing a single contract call to execute a remove-liquidity
+ * operation. The exact variant depends on whether a permit is used and
+ * whether the withdrawal goes through a zapper or directly to the pool.
+ **/
 export type RemoveLiquidityCall = [
     {
         target: Address;
@@ -79,18 +143,23 @@ export type RemoveLiquidityCall = [
         args: [bigint, Address, Address];
     }
 ];
+/**
+ * Service interface for pool liquidity operations.
+ **/
 export interface IPoolsService {
     /**
-     * Add liquidity to a pool
+     * Construct a call to add liquidity to a Gearbox lending pool.
+     *
      * @param props - {@link AddLiquidityProps}
-     * @returns - {@link AddLiquidityCall}
-     */
+     * @returns A single-element tuple with the encoded contract call.
+     **/
     addLiquidity(props: AddLiquidityProps): AddLiquidityCall;
     /**
-     * Remove liquidity from a pool
+     * Construct a call to remove liquidity from a Gearbox lending pool.
+     *
      * @param props - {@link RemoveLiquidityProps}
-     * @returns - {@link RemoveLiquidityCall}
-     */
+     * @returns A single-element tuple with the encoded contract call.
+     **/
     removeLiquidity(props: RemoveLiquidityProps): RemoveLiquidityCall;
 }
 export {};

package/dist/types/sdk/router/AbstractRouterContract.d.ts

@@ -3,19 +3,38 @@ import { BaseContract, type BaseContractArgs } from "../base/index.js";
 import type { GearboxSDK } from "../GearboxSDK.js";
 import type { IPriceOracleContract } from "../market/index.js";
 import { AddressMap, AddressSet } from "../utils/index.js";
-import type { Asset, ExpectedAndLeftoverOptions, RouterCASlice, RouterCMSlice } from "./types.js";
+import type { Asset, RouterCASlice, RouterCMSlice } from "./types.js";
+export interface ExpectedAndLeftoverOptions {
+    balances?: Leftovers;
+    keepAssets?: Address[];
+    debtOnly?: boolean;
+}
 export interface Leftovers {
     expectedBalances: AddressMap<Asset>;
     leftoverBalances: AddressMap<Asset>;
     tokensToClaim: AddressMap<Asset>;
 }
+/**
+ * @internal
+ * Base class for router contract wrappers.
+ *
+ * Provides helpers that classify credit-account token balances into
+ * "expected" (to be swapped) and "leftover" (to be kept) categories,
+ * which concrete router implementations use when building optimised
+ * multi-call swap paths.
+ *
+ * @typeParam abi - ABI type of the underlying router contract.
+ **/
 export declare abstract class AbstractRouterContract<abi extends Abi | readonly unknown[]> extends BaseContract<abi> {
+    /**
+     * Reference to the parent SDK instance.
+     **/
     readonly sdk: GearboxSDK;
     constructor(sdk: GearboxSDK, args: BaseContractArgs<abi>);
     protected getExpectedAndLeftover(ca: RouterCASlice, cm: RouterCMSlice, options?: ExpectedAndLeftoverOptions): Leftovers;
     protected getDefaultExpectedAndLeftover(ca: RouterCASlice, keepAssets?: Address[], debtOnly?: boolean): Leftovers;
     /**
-     * Tries to sell just enought of most valuable token to cover debt
+     * Tries to sell just enough of the most valuable token to cover debt.
      * @param ca
      * @param keepAssets
      * @returns

package/dist/types/sdk/router/RouterV310Contract.d.ts

@@ -884,35 +884,47 @@ declare const abi: readonly [{
     }];
 }];
 type abi = typeof abi;
+/**
+ * V3.10 implementation of the {@link IRouterContract} interface.
+ *
+ * Uses the on-chain Gearbox router to find optimal multi-hop swap
+ * paths, splitting large positions across multiple routes to reduce
+ * price impact.
+ **/
 export declare class RouterV310Contract extends AbstractRouterContract<abi> implements IRouterContract {
     #private;
     constructor(sdk: GearboxSDK, address: Address, version: number);
     /**
-     * Implements {@link IRouterContract.findOneTokenPath}
-     */
+     * {@inheritDoc IRouterContract.findOneTokenPath}
+     **/
     findOneTokenPath(props: FindOneTokenPathProps): Promise<RouterResult>;
     /**
-     * Implements {@link IRouterContract.findOpenStrategyPath}
-     */
+     * {@inheritDoc IRouterContract.findOpenStrategyPath}
+     **/
     findOpenStrategyPath(props: FindOpenStrategyPathProps): Promise<OpenStrategyResult>;
     /**
-     * Implements {@link IRouterContract.findClaimAllRewards}
-     */
+     * {@inheritDoc IRouterContract.findClaimAllRewards}
+     **/
     findClaimAllRewards(props: FindClaimAllRewardsProps): Promise<RouterRewardsResult>;
     /**
-     * Implements {@link IRouterContract.findBestClosePath}
-     */
+     * {@inheritDoc IRouterContract.findBestClosePath}
+     **/
     findBestClosePath(props: FindBestClosePathProps): Promise<RouterCloseResult>;
     /**
-     * v310-specific method to set explicitly number of splits for a token
-     * @param token
-     * @param numSplits
-     */
+     * Override the number of route splits used when swapping a specific token.
+     *
+     * @param token - Token address to configure.
+     * @param numSplits - Number of parallel route splits.
+     * @internal
+     **/
     setNumSplits(token: Address, numSplits: bigint): void;
     /**
-     * v310-specific method to set default number of splits for a token
-     * @param numSplits
-     */
+     * Set the default number of route splits applied to the highest-value
+     * token in each swap.
+     *
+     * @param numSplits - Default number of parallel route splits.
+     * @internal
+     **/
     setDefaultNumSplits(numSplits: bigint): void;
 }
 export {};