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

package/dist/types/sdk/core/AbstractAddressProviderContract.d.ts

@@ -4,13 +4,36 @@ import { BaseContract, type ConstructOptions } from "../base/index.js";
 import type { VersionRange } from "../constants/index.js";
 import type { AddressProviderV3StateHuman } from "../types/index.js";
 import type { AddressProviderAddresses, AddressProviderState } from "./types.js";
+/**
+ * Base implementation of the Gearbox address provider contract.
+ *
+ * Maintains an in-memory registry of `(contractName, version) → address`
+ * mappings for all global (chain-wide) Gearbox contracts.
+ *
+ * @typeParam abi - The contract's ABI type.
+ **/
 export default abstract class AbstractAddressProviderContract<abi extends Abi | readonly unknown[]> extends BaseContract<abi> {
     #private;
     constructor(options: ConstructOptions, args: BaseContractArgs<abi>, addresses?: AddressProviderAddresses);
     protected setInternalAddress(key: string, address: Address, version: number): void;
+    /**
+     * {@inheritDoc IAddressProviderContract.getAddress}
+     **/
     getAddress(contract: string, version?: number): Address;
+    /**
+     * {@inheritDoc IAddressProviderContract.getLatest}
+     **/
     getLatest(contract: string, range: VersionRange): [address: Address, version: number] | undefined;
+    /**
+     * {@inheritDoc IAddressProviderContract.mustGetLatest}
+     **/
     mustGetLatest(contract: string, range: VersionRange): [address: Address, version: number];
+    /**
+     * {@inheritDoc IAddressProviderContract.state}
+     **/
     get state(): AddressProviderState;
+    /**
+     * {@inheritDoc IAddressProviderContract.stateHuman}
+     **/
     stateHuman(raw?: boolean): AddressProviderV3StateHuman;
 }

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

@@ -17,15 +17,61 @@ export interface AddressProviderAddresses {
      */
     overrides?: Record<string, Record<number, Address>>;
 }
+/**
+ * Serializable snapshot of the address provider's current state,
+ * including its on-chain identity and all registered contract addresses.
+ **/
 export interface AddressProviderState {
+    /**
+     * On-chain identification parameters for the address provider itself.
+     **/
     baseParams: BaseParams;
+    /**
+     * Registered addresses keyed by contract name, then by version number.
+     **/
     addresses: Record<string, Record<number, Address>>;
 }
+/**
+ * Public interface for the Gearbox address provider contract.
+ *
+ * The address provider is the single entry-point for discovering all other
+ * Gearbox contracts on a given chain. It maps `(contractName, version)` pairs
+ * to on-chain addresses.
+ **/
 export interface IAddressProviderContract extends IBaseContract {
+    /**
+     * Serializable snapshot of the provider's current state.
+     **/
     state: AddressProviderState;
+    /**
+     * Resolves the address of a registered contract by name and version.
+     * @param contract - Registered contract name (e.g. `"MARKET_COMPRESSOR"`).
+     * @param version - Version number to look up. Defaults to 0 - contract without versioning
+     * @throws If no address is registered for the given name and version.
+     **/
     getAddress: (contract: string, version?: number) => Address;
+    /**
+     * Finds the highest-versioned address within a version range.
+     * @param contract - Registered contract name.
+     * @param range - Inclusive `[min, max]` version range to search.
+     * @returns A `[address, version]` tuple, or `undefined` if none match.
+     **/
     getLatest: (contract: string, range: VersionRange) => [address: Address, version: number] | undefined;
+    /**
+     * Like {@link getLatest}, but throws if no address is found in the range.
+     * @param contract - Registered contract name.
+     * @param range - Inclusive `[min, max]` version range to search.
+     * @throws If no address is registered in the given range.
+     **/
     mustGetLatest: (contract: string, range: VersionRange) => [address: Address, version: number];
+    /**
+     * Re-reads all registered addresses from chain at the given block.
+     * @param blockNumber - Block number to read state at.
+     **/
     syncState: (blockNumber: bigint) => Promise<void>;
+    /**
+     * Returns a human-readable snapshot of the address provider state.
+     * @param raw - When `true`, includes raw/unformatted values alongside display strings.
+     **/
     stateHuman: (raw?: boolean) => AddressProviderV3StateHuman;
 }

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

@@ -9,30 +9,111 @@ import { MarketConfiguratorContract } from "./MarketConfiguratorContract.js";
 import { MarketSuite } from "./MarketSuite.js";
 import type { IPriceOracleContract } from "./oracle/index.js";
 import type { PoolSuite } from "./pool/index.js";
+/**
+ * Central registry of all Gearbox markets on the current chain.
+ *
+ * A market groups a lending pool, a price oracle, and one or more credit
+ * managers into a single unit. The `MarketRegister` loads this data from the
+ * on-chain market compressor and exposes convenience lookup methods
+ **/
 export declare class MarketRegister extends SDKConstruct {
     #private;
+    /**
+     * @param sdk - Top-level SDK instance.
+     * @param ignoreMarkets - Pool addresses of markets to exclude from loading.
+     **/
     constructor(sdk: GearboxSDK, ignoreMarkets?: Address[]);
+    /**
+     * Restores market state from a previously serialized snapshot,
+     * bypassing on-chain reads.
+     * @param state - Array of market data snapshots.
+     **/
     hydrate(state: MarketData[]): void;
+    /**
+     * Fetches all markets from the on-chain for the given market configurators.
+     *
+     * @param marketConfigurators - Addresses of market configurator contracts to query.
+     * @param ignoreUpdateablePrices - When `true`, skips generating off-chain
+     *   price updates before loading
+     **/
     loadMarkets(marketConfigurators: Address[], ignoreUpdateablePrices?: boolean): Promise<void>;
+    /**
+     * The active filter used to scope market compressor queries.
+     * @throws If the register has not been hydrated or attached yet.
+     **/
     get marketFilter(): MarketFilter;
+    /**
+     * Re-synchronizes market state with the chain. If during sdk synchronization
+     * we detected that some markets or market configurators were changed,
+     * we reload everything.
+     *
+     * Otherwise only prices are refreshed.
+     *
+     * @param ignoreUpdateablePrices - When `true`, skips off-chain price updates.
+     **/
     syncState(ignoreUpdateablePrices?: boolean): Promise<void>;
     /**
      * Loads new prices and price feeds for given oracles from PriceFeedCompressor, defaults to all oracles
      */
     updatePrices(oracles?: Address[]): Promise<void>;
     get watchAddresses(): Set<Address>;
+    /**
+     * Serializable snapshot of all loaded markets, suitable for hydration.
+     **/
     get state(): MarketData[];
+    /**
+     * Returns a human-readable snapshot of all markets.
+     * @param raw - When `true`, includes raw/unformatted values.
+     **/
     stateHuman(raw?: boolean): {
         markets: MarketStateHuman[];
     };
+    /**
+     * All pool suites across loaded markets.
+     **/
     get pools(): PoolSuite[];
+    /**
+     * All price oracles across loaded markets.
+     **/
     get priceOracles(): IPriceOracleContract[];
+    /**
+     * All credit manager suites across loaded markets.
+     **/
     get creditManagers(): CreditSuite[];
+    /**
+     * All known market configurator contracts.
+     **/
     get marketConfigurators(): MarketConfiguratorContract[];
+    /**
+     * Finds a credit manager suite by its on-chain address.
+     * @param creditManager - Credit manager contract address.
+     * @throws If no loaded market contains the given credit manager.
+     **/
     findCreditManager(creditManager: Address): CreditSuite;
+    /**
+     * Finds the market that contains the given credit manager.
+     * @param creditManager - Credit manager contract address.
+     * @throws If no loaded market contains the given credit manager.
+     **/
     findByCreditManager(creditManager: Address): MarketSuite;
+    /**
+     * Finds the market that uses the given price oracle.
+     * @param address - Price oracle contract address.
+     * @throws If no loaded market uses the given oracle.
+     **/
     findByPriceOracle(address: Address): MarketSuite;
+    /**
+     * Finds the market associated with the given pool.
+     * @param address - Pool contract address.
+     * @throws If no loaded market uses the given pool.
+     **/
     findByPool(address: Address): MarketSuite;
+    /**
+     * Underlying address map of pool address to market suite
+     **/
     get marketsMap(): AddressMap<MarketSuite>;
+    /**
+     * All loaded market suites.
+     **/
     get markets(): MarketSuite[];
 }

package/dist/types/sdk/market/adapters/PlaceholderAdapterContracts.d.ts

@@ -6,6 +6,9 @@ import type { IAdapterContract } from "./types.js";
 export interface PlaceholderAdapterContractOptions {
     baseParams: RelaxedBaseParams;
 }
+/**
+ * @internal
+ */
 export declare class PlaceholderAdapterContract extends PlaceholderContract implements IAdapterContract {
     #private;
     constructor(options: ConstructOptions, args: PlaceholderAdapterContractOptions);

package/dist/types/sdk/market/credit/CreditFacadeV310Contract.d.ts

@@ -14,6 +14,7 @@ export declare class CreditFacadeV310Contract extends CreditFacadeV310BaseContra
     liquidateCreditAccount(ca: Address, to: Address, calls: MultiCall[], lossPolicyData?: Hex): RawTx;
     closeCreditAccount(ca: Address, calls: MultiCall[]): RawTx;
     multicall(ca: Address, calls: MultiCall[]): RawTx;
+    botMulticall(ca: Address, calls: MultiCall[]): RawTx;
     openCreditAccount(to: Address, calls: MultiCall[], referralCode: bigint): RawTx;
 }
 export {};

package/dist/types/sdk/market/oracle/PriceOracleBaseContract.d.ts

@@ -9,88 +9,78 @@ import type { IPriceFeedContract, UpdatePriceFeedsResult } from "../pricefeeds/i
 import { PriceFeedRef } from "../pricefeeds/index.js";
 import PriceFeedAnswerMap from "./PriceFeedAnswerMap.js";
 import type { DelegatedOracleMulticall, IPriceOracleContract, OnDemandPriceUpdates, PriceFeedsForTokensOptions } from "./types.js";
+/**
+ * Base implementation of the Gearbox price oracle.
+ *
+ * Manages dual main/reserve price feed mappings and price answers for
+ * every collateral token in a market. Provides token-to-USD and
+ * token-to-token conversion using the latest known prices.
+ *
+ * @typeParam abi - The concrete oracle contract's ABI type.
+ **/
 export declare abstract class PriceOracleBaseContract<abi extends Abi | readonly unknown[]> extends BaseContract<abi> implements IPriceOracleContract {
     #private;
     readonly sdk: GearboxSDK;
     /**
-     * Mapping Token => [PriceFeed Address, stalenessPeriod]
-     */
+     * {@inheritDoc IPriceOracleContract.mainPriceFeeds}
+     **/
     readonly mainPriceFeeds: AddressMap<PriceFeedRef>;
     /**
-     * Mapping Token => [PriceFeed Address, stalenessPeriod]
-     */
+     * {@inheritDoc IPriceOracleContract.reservePriceFeeds}
+     **/
     readonly reservePriceFeeds: AddressMap<PriceFeedRef>;
     /**
-     * Mapping Token => Price in USD
-     */
+     * {@inheritDoc IPriceOracleContract.mainPrices}
+     **/
     readonly mainPrices: PriceFeedAnswerMap;
     /**
-     * Mapping Token => Price in USD
-     */
+     * {@inheritDoc IPriceOracleContract.reservePrices}
+     **/
     readonly reservePrices: PriceFeedAnswerMap;
     constructor(sdk: GearboxSDK, args: BaseContractArgs<abi>, data: PriceOracleData);
     /**
-     * Returns main and reserve price feeds for given tokens
-     * @param tokens
-     * @param opts Option to include main/reserve feeds only, defaults to both
-     * @returns
-     */
+     * {@inheritDoc IPriceOracleContract.priceFeedsForTokens}
+     **/
     priceFeedsForTokens(tokens: Address[], opts?: PriceFeedsForTokensOptions): IPriceFeedContract[];
     abstract onDemandPriceUpdates(creditFacade: Address, updates?: UpdatePriceFeedsResult): OnDemandPriceUpdates;
     /**
-     * Gets main price for given token
-     * Throws if token price feed is not found or answer is not successful
-     * @param token
-     * @returns
-     */
+     * {@inheritDoc IPriceOracleContract.mainPrice}
+     **/
     mainPrice(token: Address): bigint;
     /**
-     * Gets reserve price for given token
-     * Throws if token price feed is not found or answer is not successful
-     * @param token
-     * @returns
-     */
+     * {@inheritDoc IPriceOracleContract.reservePrice}
+     **/
     reservePrice(token: Address): bigint;
     /**
-     * Returns true if oracle's price feed tree contains given price feed
-     * This feed is not necessary connected to token, but can be a component of composite feed for some token
-     * @param priceFeed
-     * @returns
-     */
+     * {@inheritDoc IPriceOracleContract.usesPriceFeed}
+     **/
     usesPriceFeed(priceFeed: Address): boolean;
     /**
-     * Tries to convert amount of from one token to another, using latest known prices
-     * @param from
-     * @param to
-     * @param amount
-     * @param reserve use reserve price feed instead of main
-     */
+     * {@inheritDoc IPriceOracleContract.convert}
+     **/
     convert(from: Address, to: Address, amount: bigint, reserve?: boolean): bigint;
     /**
-     * Tries to convert amount of token to USD, using latest known prices
-     * @param from
-     * @param amount
-     * @param reserve use reserve price feed instead of main
-     */
+     * {@inheritDoc IPriceOracleContract.convertToUSD}
+     **/
     convertToUSD(from: Address, amount: bigint, reserve?: boolean): bigint;
     /**
-     * Tries to convert amount of USD to token, using latest known prices
-     * @param to
-     * @param amount
-     * @param reserve use reserve price feed instead of main
-     */
+     * {@inheritDoc IPriceOracleContract.convertFromUSD}
+     **/
     convertFromUSD(to: Address, amount: bigint, reserve?: boolean): bigint;
     /**
-     * All price feed tree nodes known to this oracle
-     */
+     * {@inheritDoc IPriceOracleContract.priceFeeds}
+     **/
     get priceFeeds(): IPriceFeedContract[];
     /**
-     * Paired method to updatePrices, helps to update prices on all oracles in one multicall
-     */
+     * {@inheritDoc IPriceOracleContract.syncStateMulticall}
+     **/
     syncStateMulticall(): DelegatedOracleMulticall;
     /**
-     * Returns list of addresses that should be watched for events to sync state
-     */
+     * {@inheritDoc IPriceOracleContract.watchAddresses}
+     **/
     get watchAddresses(): Set<Address>;
+    /**
+     * {@inheritDoc IPriceOracleContract.stateHuman}
+     **/
     stateHuman(raw?: boolean): PriceOracleStateHuman;
 }

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

@@ -3,10 +3,22 @@ import type { priceFeedCompressorAbi } from "../../../abi/compressors/priceFeedC
 import type { IBaseContract } from "../../base/index.js";
 import type { MultiCall, PriceOracleStateHuman } from "../../types/index.js";
 import type { AddressMap } from "../../utils/index.js";
-import type { IPriceFeedContract, PriceFeedRef, PriceUpdateV310, UpdatePriceFeedsResult } from "../pricefeeds/index.js";
+import type { IPriceFeedContract, PriceFeedRef, PriceUpdate, UpdatePriceFeedsResult } from "../pricefeeds/index.js";
 import type PriceFeedAnswerMap from "./PriceFeedAnswerMap.js";
+/**
+ * Filter controlling which feed types to include when querying
+ * price feeds for a set of tokens. Both default to `true`.
+ **/
 export interface PriceFeedsForTokensOptions {
+    /**
+     * Include main (primary) price feeds.
+     * @default true
+     **/
     main?: boolean;
+    /**
+     * Include reserve (fallback) price feeds.
+     * @default true
+     **/
     reserve?: boolean;
 }
 /**
@@ -14,100 +26,107 @@ export interface PriceFeedsForTokensOptions {
  * as raw PriceUpdate in liquidator calls.
  */
 export interface OnDemandPriceUpdates {
-    raw: PriceUpdateV310[];
+    raw: PriceUpdate[];
     multicall: MultiCall[];
 }
+/**
+ * Public interface for a Gearbox price oracle contract.
+ *
+ * Each Gearbox market has one price oracle that aggregates USD-denominated
+ * price feeds for every collateral token.
+ **/
 export interface IPriceOracleContract extends IBaseContract {
     /**
-     * All price feed tree nodes known to this oracle
-     */
+     * All price feed contract instances known to this oracle
+     **/
     priceFeeds: IPriceFeedContract[];
     /**
-     * Mapping Token => [PriceFeed Address, stalenessPeriod]
-     */
+     * Main price feed references, keyed by token address.
+     **/
     mainPriceFeeds: AddressMap<PriceFeedRef>;
     /**
-     * Mapping Token => Price in USD
-     */
+     * Latest main prices in USD (8 decimals), keyed by token address.
+     **/
     mainPrices: PriceFeedAnswerMap;
     /**
-     * Gets main price for given token
-     * Throws if token price feed is not found or answer is not successful
-     * @param token
-     * @returns
-     */
+     * Returns the main USD price for a token.
+     * @param token - Token address.
+     * @throws If the token has no main feed or the answer failed.
+     **/
     mainPrice: (token: Address) => bigint;
     /**
-     * Mapping Token => [PriceFeed Address, stalenessPeriod]
-     */
+     * Reserve price feed references, keyed by token address.
+     **/
     reservePriceFeeds: AddressMap<PriceFeedRef>;
     /**
-     * Mapping Token => Price in USD
-     */
+     * Latest reserve prices in USD (8 decimals), keyed by token address.
+     **/
     reservePrices: PriceFeedAnswerMap;
     /**
-     * Gets reserve price for given token
-     * Throws if token price feed is not found or answer is not successful
-     * @param token
-     * @returns
-     */
+     * Returns the reserve USD price for a token.
+     * @param token - Token address.
+     * @throws If the token has no reserve feed or the answer failed.
+     **/
     reservePrice: (token: Address) => bigint;
     /**
-     * Paired method to updatePrices, helps to update prices on all oracles in one multicall
-     */
+     * @internal
+     **/
     syncStateMulticall: () => DelegatedOracleMulticall;
     /**
-     * Returns true if oracle's price feed tree contains given price feed
-     * This feed is not necessary connected to token, but can be a component of composite feed for some token
-     * @param priceFeed
-     * @returns
-     */
+     * Checks whether the given price feed address appears anywhere in this
+     * oracle's feed tree (including as a dependency of a composite feed,
+     * not just directly assigned to a token).
+     * @param priceFeed - Price feed address to look up.
+     **/
     usesPriceFeed: (priceFeed: Address) => boolean;
     /**
-     * Returns main and reserve price feeds for given tokens
-     * @param tokens
-     * @param opts Option to include main/reserve feeds only, defaults to both
-     * @returns
-     */
+     * Collects the main and/or reserve price feeds assigned to the given tokens.
+     * @param tokens - Token addresses to query.
+     * @param opts - Filter to include only main or only reserve feeds.
+     **/
     priceFeedsForTokens: (tokens: Address[], opts?: PriceFeedsForTokensOptions) => IPriceFeedContract[];
     /**
-     * Converts previously obtained price updates into CreditFacade multicall entries
-     * @param creditFacade
-     * @param updates
-     * @returns
-     */
+     * Converts previously obtained price updates into CreditFacade
+     * multicall entries and raw `PriceUpdateV310` structures.
+     * @param creditFacade - Address of the credit facade that will receive the multicall.
+     * @param updates - Price update result to convert. When omitted, uses latest cached updates.
+     **/
     onDemandPriceUpdates: (creditFacade: Address, updates?: UpdatePriceFeedsResult) => OnDemandPriceUpdates;
     /**
-     * Tries to convert amount of from one token to another, using latest known prices
-     * @param from
-     * @param to
-     * @param amount
-     * @param reserve use reserve price feed instead of main
-     */
+     * Converts an amount from one token to another using latest known prices.
+     * @param from - Source token address.
+     * @param to - Destination token address.
+     * @param amount - Amount in source-token decimals.
+     * @param reserve - Use reserve feeds instead of main.
+     **/
     convert: (from: Address, to: Address, amount: bigint, reserve?: boolean) => bigint;
     /**
-     * Tries to convert amount of token to USD, using latest known prices
-     * @param from
-     * @param amount
-     * @param reserve use reserve price feed instead of main
-     */
+     * Converts a token amount to its USD value using latest known prices.
+     * @param from - Token address.
+     * @param amount - Amount in token decimals.
+     * @param reserve - Use reserve feeds instead of main.
+     **/
     convertToUSD: (from: Address, amount: bigint, reserve?: boolean) => bigint;
     /**
-     * Tries to convert amount of USD to token, using latest known prices
-     * @param to
-     * @param amount
-     * @param reserve use reserve price feed instead of main
-     */
+     * Converts a USD amount to a token amount using latest known prices.
+     * @param to - Token address.
+     * @param amount - Amount in USD (8 decimals).
+     * @param reserve - Use reserve feeds instead of main.
+     **/
     convertFromUSD: (to: Address, amount: bigint, reserve?: boolean) => bigint;
     /**
-     * Returns list of addresses that should be watched for events to sync state
-     */
+     * @internal
+     **/
     watchAddresses: Set<Address>;
     /**
-     * Returns human readable state of the oracle
-     */
+     * Returns a human-readable snapshot of the oracle state.
+     * @param raw - When `true`, includes raw/unformatted values.
+     **/
     stateHuman: (raw?: boolean) => PriceOracleStateHuman;
 }
+/**
+ * @internal
+ **/
 export interface DelegatedOracleMulticall {
     call: ContractFunctionParameters<typeof priceFeedCompressorAbi, "view", "getPriceOracleState">;
     onResult: (resp: ContractFunctionReturnType<typeof priceFeedCompressorAbi, "view", "getPriceOracleState">) => void;

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

@@ -2,6 +2,9 @@ import type { Abi, Address, UnionOmit } from "viem";
 import type { ConstructOptions } from "../../base/Construct.js";
 import type { LPPriceFeedStateHuman } from "../../types/state-human.js";
 import { AbstractPriceFeedContract, type PriceFeedConstructorArgs } from "./AbstractPriceFeed.js";
+/**
+ * @internal
+ */
 export declare abstract class AbstractLPPriceFeedContract<const abi extends Abi | readonly unknown[]> extends AbstractPriceFeedContract<abi> {
     readonly lpContract: Address;
     readonly lpToken: Address;

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

@@ -13,6 +13,9 @@ export declare class PartialPriceFeedInitError extends Error {
     readonly priceFeed: PriceFeedConstructorArgs<any>;
     constructor(priceFeed: PriceFeedConstructorArgs<any>);
 }
+/**
+ * @internal
+ */
 export declare abstract class AbstractPriceFeedContract<const abi extends Abi | readonly unknown[]> extends BaseContract<abi> implements IPriceFeedContract {
     #private;
     hasLowerBoundCap: boolean;

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

@@ -3,13 +3,33 @@ import { Construct, type ConstructOptions } from "../../base/index.js";
 import type { PriceFeedStateHuman } from "../../types/index.js";
 import type { IPriceFeedContract } from "./types.js";
 /**
- * PriceFeedRef is a connector between price feed and oracle, e.g. oracle's entry for price feed + staleness period
- */
+ * Connector between a price oracle and a price feed contract.
+ *
+ * Each token tracked by a {@link IPriceOracleContract} has an associated
+ * `PriceFeedRef` that pairs the feed's on-chain address with the
+ * staleness period the oracle uses when evaluating the feed's answer.
+ **/
 export declare class PriceFeedRef extends Construct {
     #private;
+    /**
+     * On-chain address of the referenced price feed contract.
+     **/
     readonly address: Address;
+    /**
+     * Maximum allowed age (in seconds) of the feed's answer before the
+     * oracle considers it stale.
+     **/
     readonly stalenessPeriod: number;
     constructor(options: ConstructOptions, address: Address, stalenessPeriod: number);
+    /**
+     * Lazily resolved price feed contract instance.
+     * @throws If the feed is not registered in the contracts register.
+     **/
     get priceFeed(): IPriceFeedContract;
+    /**
+     * Returns a human-readable snapshot of the feed state, including the
+     * staleness period formatted as a duration string.
+     * @param raw - When `true`, includes raw/unformatted values.
+     **/
     stateHuman(raw?: boolean): PriceFeedStateHuman;
 }