@gearbox-protocol/sdk 13.3.3 → 13.4.0-beta.2

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

@@ -5,44 +5,78 @@ import type { GearboxSDK } from "../../GearboxSDK.js";
 import type { RawTx } from "../../types/index.js";
 import type { IHooks } from "../../utils/internal/index.js";
 import { type PartialPriceFeedTreeNode } from "./AbstractPriceFeed.js";
-import type { IPriceFeedContract, PriceUpdateV310, UpdatePriceFeedsResult } from "./types.js";
-import type { IPriceUpdater, IPriceUpdateTask, PythOptions, RedstoneOptions } from "./updates/index.js";
+import type { IPriceFeedContract, PriceUpdate, UpdatePriceFeedsResult } from "./types.js";
+import type { IPriceUpdateTask, PythOptions, RedstoneOptions } from "./updates/index.js";
 export type PriceFeedRegisterHooks = {
     /**
      * Emitted when transactions to update price feeds have been generated, but before they're used anywhere
      */
     updatesGenerated: [UpdatePriceFeedsResult];
 };
+/**
+ * Configuration for external price-update providers supported by the register.
+ **/
 export interface PriceFeedRegisterOptions {
+    /**
+     * Redstone price-update provider options.
+     **/
     redstone?: RedstoneOptions;
+    /**
+     * Pyth price-update provider options.
+     **/
     pyth?: PythOptions;
 }
+/**
+ * @internal
+ * Diagnostic snapshot of the most recent price-update round.
+ **/
 export interface LatestUpdate {
+    /**
+     * Unix timestamp (seconds) of the most recent update.
+     **/
     timestamp: number;
+    /**
+     * Individual update tasks that were executed.
+     **/
     updates: IPriceUpdateTask[];
 }
 /**
- * PriceFeedRegister acts as a chain-level cache to avoid creating multiple contract instances.
- * It's reused by PriceOracles belonging to different markets
+ * Chain-level cache of price feed contract instances.
  *
+ * All {@link IPriceOracleContract}s across different markets share a single
+ * `PriceFeedRegister`, avoiding duplicate contract wrappers for the same
+ * on-chain feed. The register also orchestrates off-chain price updates
+ * (Pyth, Redstone, etc.).
  **/
 export declare class PriceFeedRegister extends SDKConstruct implements IHooks<PriceFeedRegisterHooks> {
     #private;
-    readonly updaters: IPriceUpdater[];
     constructor(sdk: GearboxSDK, opts?: PriceFeedRegisterOptions);
+    /**
+     * @internal
+     * Registers a callback for price-feed register lifecycle events.
+     * @param event - Event name.
+     * @param handler - Callback to invoke.
+     **/
     addHook: <K extends "updatesGenerated">(hookName: K, fn: (...args: PriceFeedRegisterHooks[K]) => void | Promise<void>) => void;
+    /**
+     * @internal
+     * Removes a previously registered hook.
+     * @param event - Event name.
+     * @param handler - Callback to remove.
+     **/
     removeHook: <K extends "updatesGenerated">(hookName: K, fn: (...args: PriceFeedRegisterHooks[K]) => void | Promise<void>) => void;
     /**
      * Returns all price feeds known to sdk
      */
     get feeds(): readonly IPriceFeedContract[];
     /**
-     * Returns RawTxs to update price feeds
-     * @param priceFeeds Array oftop-level price feeds, actual updatable price feeds will be derived.
-     * Or filter criteria, that will gather all main or reserve price feeds from all oracles
-     * If not provided will use all price feeds that are attached
-     * @returns
-     */
+     * Generates transactions to push fresh off-chain prices to updatable feeds.
+     *
+     * @param priceFeeds - Top-level price feeds whose updatable dependencies
+     *   will be resolved, or a filter (`{ main: true }` / `{ reserve: true }`)
+     *   to gather feeds from all oracles. When omitted, all registered feeds
+     *   are used.
+     **/
     generatePriceFeedsUpdateTxs(priceFeeds?: IPriceFeedContract[] | {
         main: true;
     } | {
@@ -57,7 +91,7 @@ export declare class PriceFeedRegister extends SDKConstruct implements IHooks<Pr
         main: true;
     } | {
         reserve: true;
-    }): Promise<PriceUpdateV310[]>;
+    }): Promise<PriceUpdate[]>;
     /**
      * Similar to {@link generatePriceFeedsUpdates}, but returns raw transaction to PriceFeedStore.updatePrices
      * @param priceFeeds
@@ -69,7 +103,7 @@ export declare class PriceFeedRegister extends SDKConstruct implements IHooks<Pr
         reserve: true;
     }): Promise<RawTx>;
     /**
-     * Similar to {@link generatePriceFeedsUpdateTxs}, but will generate necessary price update transactions for external price feeds
+     * Similar to {@link generatePriceFeedsUpdateTxs}, but will generate necessary price update transactions for external price feeds (not known to sdk)
      * This does not add feeds to this register, so they won't be implicitly included in future generatePriceFeedsUpdateTxs calls
      * @param feeds
      * @param block
@@ -90,18 +124,48 @@ export declare class PriceFeedRegister extends SDKConstruct implements IHooks<Pr
         blockNumber: bigint;
     } | {
         blockTag: BlockTag;
-    }): Promise<PriceUpdateV310[]>;
+    }): Promise<PriceUpdate[]>;
+    /**
+     * Checks whether a price feed is already registered at the given address.
+     * @param address - On-chain address to look up.
+     **/
     has(address: Address): boolean;
+    /**
+     * Returns the cached price feed contract at the given address.
+     * @param address - On-chain address to look up.
+     * @throws If no feed is registered at that address.
+     **/
     mustGet(address: Address): IPriceFeedContract;
+    /**
+     * Inserts or updates a price feed from a full tree node.
+     *
+     * If a fully loaded feed already exists at the same address, only the
+     * answer is refreshed. Otherwise a new contract wrapper is created and
+     * cached.
+     *
+     * @param data - Full price feed tree node from the compressor.
+     * @returns The cached (or newly created) feed instance.
+     * @throws If the created feed is only partially initialized.
+     **/
     upsert(data: PriceFeedTreeNode): IPriceFeedContract;
     /**
      * Loads PARTIAL information about all updatable price feeds from MarketCompressor
      * Discovered price feeds are not saved anywhere in PriceFeedRegister, and can later be used to load price feed updates
      */
     getPartialUpdatablePriceFeeds(configurators: Address[], pools?: Address[]): Promise<IPriceFeedContract[]>;
+    /**
+     * Instantiates the appropriate price feed contract wrapper based on
+     * the `contractType` discriminator in the node's base params.
+     *
+     * @param data - Partial or full price feed tree node.
+     * @returns A new (uncached) feed contract instance.
+     * @throws If the contract type is unsupported and strict mode is enabled.
+     **/
     create(data: PartialPriceFeedTreeNode): IPriceFeedContract;
     /**
-     * Information update latest update of updatable price feeds, for diagnostic purposes
-     */
+     * @internal
+     * Diagnostic snapshot of the most recent price-update round, or
+     * `undefined` if no updates have been generated yet.
+     **/
     get latestUpdate(): LatestUpdate | undefined;
 }

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

@@ -1,2 +1,2 @@
-import type { PriceUpdateV310, UpdatePriceFeedsResult } from "./types.js";
-export declare function getRawPriceUpdates(updates: UpdatePriceFeedsResult): PriceUpdateV310[];
+import type { PriceUpdate, UpdatePriceFeedsResult } from "./types.js";
+export declare function getRawPriceUpdates(updates: UpdatePriceFeedsResult): PriceUpdate[];

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

@@ -2,43 +2,107 @@ 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 {
+/**
+ * Pair: updatable price feed address and
+ * data can be passed to IUpdatablePriceFeed.updatePrice
+ */
+export interface PriceUpdate {
     /**
      * IUpdatablePriceFeed contract address
      */

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;
 }