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

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

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

@@ -1,14 +1,14 @@
 import type { Address } from "viem";
 import type { CreditAccountData, IBaseContract } from "../base/index.js";
 import type { MultiCall } from "../types/index.js";
-import type { Leftovers } from "./AbstractRouterContract.js";
+/**
+ * Type of swap the router should perform.
+ *
+ * - `"EXACT_INPUT"` — swap an exact amount of the input token.
+ * - `"EXACT_INPUT_ALL"` — swap the entire balance of the input token.
+ * - `"EXACT_OUTPUT"` — swap to receive an exact amount of the output token (no longer supported by the router).
+ **/
 export type SwapOperation = "EXACT_INPUT" | "EXACT_INPUT_ALL" | "EXACT_OUTPUT";
-export interface PathOption {
-    target: Address;
-    option: number;
-    totalOptions: number;
-}
-export type PathOptionSerie = Array<PathOption>;
 /**
  * Result returned from router contract
  */
@@ -65,8 +65,18 @@ export interface RouterCloseResult extends RouterResult {
      */
     underlyingBalance: bigint;
 }
+/**
+ * A token address paired with a balance, used throughout the router to
+ * represent holdings, collateral inputs, and leftover targets.
+ **/
 export interface Asset {
+    /**
+     * ERC-20 token address.
+     **/
     token: Address;
+    /**
+     * Token amount in the token's native decimals.
+     **/
     balance: bigint;
 }
 /**
@@ -78,50 +88,9 @@ export interface RouterCMSlice {
     collateralTokens: Array<Address>;
 }
 /**
- * Slice of credit account data required for router operations
- */
+ * Minimal slice of credit-account data required by router operations.
+ **/
 export type RouterCASlice = Pick<CreditAccountData, "tokens" | "enabledTokensMask" | "underlying" | "creditAccount" | "creditFacade" | "debt" | "totalDebtUSD" | "creditManager">;
-export type CreditAccountTokensSlice = Pick<CreditAccountData, "creditAccount" | "tokens" | "enabledTokensMask">;
-export interface FindAllSwapsProps {
-    /**
-     * Minimal credit account data on which operation is performed
-     */
-    creditAccount: RouterCASlice;
-    /**
-     * Minimal credit manager data on which operation is performed
-     */
-    creditManager: RouterCMSlice;
-    /**
-     * {@link SwapOperation} = "EXACT_INPUT" | "EXACT_INPUT_ALL" | "EXACT_OUTPUT"; however router stopped to support EXACT_OUTPUT
-     */
-    swapOperation: SwapOperation;
-    /**
-     * Address of input token
-     */
-    tokenIn: Address;
-    /**
-     * Address of target token
-     */
-    tokenOut: Address;
-    /**
-     * Incoming amount of tokenIn to swap
-     */
-    amount: bigint;
-    /**
-     * Amount that should be left on account after swap; technically equals to 0 in the most of the cases
-     */
-    leftoverAmount: bigint;
-    /**
-     * Slippage in PERCENTAGE_FORMAT (100% = 10_000) per operation
-     */
-    slippage: number | bigint;
-}
-export interface FindClosePathInput {
-    pathOptions: Array<PathOptionSerie>;
-    expected: Array<Asset>;
-    leftover: Array<Asset>;
-    connectors: Array<Address>;
-}
 export interface FindOneTokenPathProps {
     /**
      * Minimal credit account data on which operation is performed
@@ -136,7 +105,7 @@ export interface FindOneTokenPathProps {
      */
     tokenIn: Address;
     /**
-     * Adddress of target token
+     * Address of target token
      */
     tokenOut: Address;
     /**
@@ -206,7 +175,7 @@ export interface FindBestClosePathProps {
      */
     keepAssets?: Address[];
     /**
-     * Debt only mode - will try to sell just enought of most valuable token to cover debt
+     * Debt only mode - will try to sell just enough of most valuable token to cover debt
      */
     debtOnly?: boolean;
 }
@@ -228,35 +197,43 @@ export interface ClosePathBalances {
      */
     tokensToClaim?: Array<Asset>;
 }
-export interface ExpectedAndLeftoverOptions {
-    balances?: Leftovers;
-    keepAssets?: Address[];
-    debtOnly?: boolean;
-}
+/**
+ * On-chain router contract that finds optimal multi-hop swap paths
+ * for credit-account operations: single-token swaps, open-strategy
+ * collateral conversion, reward claiming, and full account closure.
+ **/
 export interface IRouterContract extends IBaseContract {
     /**
-     * Find the best path to swap token A to token B (target token).
+     * Find the best path to swap one token into another.
+     *
      * @param props - {@link FindOneTokenPathProps}
-     * @return result - {@link RouterResult}
-     */
+     * @returns The optimal swap result including amount, slippage-adjusted
+     *   minimum, and the multi-call sequence to execute.
+     **/
     findOneTokenPath: (props: FindOneTokenPathProps) => Promise<RouterResult>;
     /**
-     * Finds the best path for opening Credit Account; converts all expectedBalances besides leftoverBalances into target token
+     * Find the best path for opening a credit account by converting all
+     * collateral (except leftovers) into a single target token.
+     *
      * @param props - {@link FindOpenStrategyPathProps}
-     * @returns result - {@link OpenStrategyResult}
-     */
+     * @returns Swap result with projected post-open balances.
+     **/
     findOpenStrategyPath: (props: FindOpenStrategyPathProps) => Promise<OpenStrategyResult>;
     /**
-     * Constructs calls to claim all rewards for Credit Account
+     * Construct calls to claim all pending rewards on a credit account
+     * and swap them to the underlying token.
+     *
      * @param props - {@link FindClaimAllRewardsProps}
-     * @returns result - {@link RouterRewardsResult}
-     */
+     * @returns Multi-call sequence for claiming and swapping rewards.
+     **/
     findClaimAllRewards: (props: FindClaimAllRewardsProps) => Promise<RouterRewardsResult>;
     /**
-     * Finds the path to swap / withdraw all assets from CreditAccount into underlying asset
-     * Can be used for closing Credit Account and for liquidations as well.
+     * Find the best path to swap all credit-account assets into the
+     * underlying token. Used for account closure and liquidation.
+     *
      * @param props - {@link FindBestClosePathProps}
-     * @return result - {@link RouterCloseResult}
-     */
+     * @returns Swap result including the total underlying balance
+     *   after all swaps.
+     **/
     findBestClosePath: (props: FindBestClosePathProps) => Promise<RouterCloseResult>;
 }

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

@@ -2,17 +2,46 @@ import type { MarketData } from "../base/index.js";
 import type { NetworkType } from "../chain/chains.js";
 import type { AddressProviderState } from "../core/index.js";
 import type { PluginStatesMap, PluginsMap } from "../plugins/index.js";
+/**
+ * Complete serialisable snapshot of the Gearbox SDK state.
+ *
+ * Produced by {@link GearboxSDK.state} and consumed by
+ * {@link GearboxSDK.hydrate} for instant offline restoration.
+ *
+ * @typeParam Plugins - Map of plugin names to plugin instances.
+ **/
 export interface GearboxState<Plugins extends PluginsMap = {}> {
     /**
-     * State version, checked duryng hydration
-     * This is not the same as @gearbox-protocol/sdk package version
-     */
+     * State format version, checked during hydration.
+     * This is *not* the `@gearbox-protocol/sdk` package version.
+     **/
     version: number;
+    /**
+     * Gearbox network type the snapshot was taken from.
+     **/
     network: NetworkType;
+    /**
+     * EVM chain ID the snapshot was taken from.
+     **/
     chainId: number;
+    /**
+     * Block number the snapshot corresponds to.
+     **/
     currentBlock: bigint;
+    /**
+     * Block timestamp (Unix epoch seconds).
+     **/
     timestamp: bigint;
+    /**
+     * Address provider contract state.
+     **/
     addressProvider: AddressProviderState;
+    /**
+     * All loaded market data.
+     **/
     markets: MarketData[];
+    /**
+     * Per-plugin serialised state.
+     **/
     plugins: PluginStatesMap<Plugins>;
 }

package/dist/types/sdk/utils/AddressMap.d.ts

@@ -1,50 +1,94 @@
 import type { Address } from "viem";
+/**
+ * Case-insensitive map keyed by EVM addresses.
+ *
+ * All keys are checksummed via viem's {@link getAddress} on insertion and
+ * lookup, so `0xabc...` and `0xABC...` resolve to the same entry.
+ *
+ * @typeParam T - Type of values stored in the map.
+ */
 export declare class AddressMap<T> {
     #private;
+    /**
+     * @param entries - Optional initial key-value pairs. Address strings are checksummed automatically.
+     * @param name - Optional label used in error messages when a lookup fails.
+     */
     constructor(entries?: Array<[string, T]>, name?: string);
     /**
-     * Adds or updates value, undefined removes value
-     * @param address
-     * @param value
+     * Adds or updates a value. Passing `undefined` removes the entry.
+     * @param address - EVM address (checksummed automatically).
+     * @param value - Value to store, or `undefined` to delete the entry.
+     * @throws If the map has been {@link freeze | frozen}.
      */
     upsert(address: string, value: T | undefined): void;
     /**
-     * Adds value, throws if this address is already used
-     * @param address
-     * @param value
+     * Inserts a value, throwing if the address is already present.
+     * @param address - EVM address (checksummed automatically).
+     * @param value - Value to store.
+     * @throws If the map has been {@link freeze | frozen} or if `address` already exists.
      */
     insert(address: string, value: T): void;
     /**
-     * Checks if address is present in map
-     * @param address
-     * @returns
+     * Checks whether an address is present in the map.
+     * @param address - EVM address (case-insensitive).
      */
     has(address: string): boolean;
     /**
-     * Returns value, or undefined if the address is not in map
-     * @param address
-     * @returns
+     * Looks up a value by EVM address (case-insensitive).
+     * @param address - EVM address to look up.
+     * @returns The stored value, or `undefined` if not present.
      */
     get(address: string): T | undefined;
     /**
-     * Gets address from map, throws if not found
-     * @param address
-     * @returns
+     * Looks up a value by EVM address, throwing if the address is absent.
+     * @param address - EVM address to look up.
+     * @throws If `address` is not in the map.
      */
     mustGet(address: string): T;
     /**
-     * Deletes address from map
-     * @param address
+     * Removes an entry by address. No-op if the address is absent.
+     * @param address - EVM address to remove.
      */
     delete(address: string): void;
+    /**
+     * Removes all entries from the map.
+     **/
     clear(): void;
+    /**
+     * Returns all entries as an array of `[checksummedAddress, value]` tuples.
+     **/
     entries(): Array<[Address, T]>;
+    /**
+     * Returns all values in insertion order.
+     **/
     values(): T[];
+    /**
+     * Returns all checksummed addresses in insertion order.
+     **/
     keys(): Address[];
+    /**
+     * Converts the map to a plain `Record<Address, T>` object.
+     **/
     asRecord(): Record<Address, T>;
+    /**
+     * Number of entries in the map.
+     **/
     get size(): number;
+    /**
+     * Prevents further mutations. Any subsequent call to {@link upsert},
+     * {@link insert}, or {@link delete} will throw.
+     */
     freeze(): void;
     protected get name(): string | undefined;
+    /**
+     * Creates an `AddressMap` from a plain record object.
+     * @param record - Object whose keys are EVM addresses.
+     */
     static fromRecord<T>(record: Record<Address, T>): AddressMap<T>;
+    /**
+     * Creates an `AddressMap` by extracting an address from each array element.
+     * @param array - Source items.
+     * @param mapFn - Function that returns the address key for a given item.
+     */
     static fromMappedArray<T>(array: T[], mapFn: (item: T) => Address): AddressMap<T>;
 }

package/dist/types/sdk/utils/AddressSet.d.ts

@@ -1,9 +1,24 @@
 import { type Address } from "viem";
+/**
+ * Case-insensitive set of EVM addresses.
+ *
+ * All addresses are checksummed via viem's {@link getAddress} on insertion and
+ * lookup, so `0xabc...` and `0xABC...` are treated as the same entry.
+ */
 export declare class AddressSet extends Set<Address> {
+    /**
+     * @param entries - Optional initial addresses. Each is checksummed automatically.
+     */
     constructor(entries?: Iterable<Address>);
     add(value: Address): this;
     delete(value: Address): boolean;
     has(value: Address): boolean;
+    /**
+     * Returns all addresses as an array.
+     **/
     asArray(): Address[];
+    /**
+     * Maps each address through `fn` and returns the resulting array.
+     **/
     map<T>(fn: (address: Address) => T): T[];
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gearbox-protocol/sdk",
-  "version": "13.3.3",
+  "version": "13.4.0-beta.2",
   "description": "Gearbox SDK",
   "license": "MIT",
   "main": "./dist/cjs/sdk/index.js",
@@ -70,7 +70,8 @@
     "check:ci": "biome check --diagnostic-level=error",
     "typecheck:ci": "tsc --noEmit",
     "docs": "NODE_OPTIONS='--max-old-space-size=8192' pnpm --filter @gearbox-protocol/sdk-docs build",
-    "docs:dev": "pnpm --filter @gearbox-protocol/sdk-docs start"
+    "docs:dev": "pnpm --filter @gearbox-protocol/sdk-docs start",
+    "docs:serve": "pnpm --filter @gearbox-protocol/sdk-docs serve"
   },
   "dependencies": {
     "@gearbox-protocol/integrations-v3": "1.54.2",
@@ -103,6 +104,7 @@
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
     "viem-deal": "^2.0.4",
+    "vite": "^8.0.3",
     "vitest": "^4.1.2"
   },
   "peerDependencies": {