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

package/dist/esm/sdk/utils/AddressMap.js

@@ -3,6 +3,10 @@ class AddressMap {
   #map;
   #frozen = false;
   #name;
+  /**
+   * @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, name) {
     this.#map = /* @__PURE__ */ new Map();
     if (entries) {
@@ -14,9 +18,10 @@ class AddressMap {
     this.#name = name;
   }
   /**
-   * 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, value) {
     if (this.#frozen) {
@@ -30,9 +35,10 @@ class AddressMap {
     }
   }
   /**
-   * 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, value) {
     if (this.#frozen) {
@@ -47,27 +53,26 @@ class AddressMap {
     this.#map.set(key, value);
   }
   /**
-   * 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) {
     const key = getAddress(address);
     return this.#map.has(key);
   }
   /**
-   * 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) {
     const key = getAddress(address);
     return this.#map.get(key);
   }
   /**
-   * 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) {
     const key = getAddress(address);
@@ -77,40 +82,71 @@ class AddressMap {
     return this.#map.get(key);
   }
   /**
-   * 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) {
     const key = getAddress(address);
     this.#map.delete(key);
   }
+  /**
+   * Removes all entries from the map.
+   **/
   clear() {
     this.#map.clear();
   }
+  /**
+   * Returns all entries as an array of `[checksummedAddress, value]` tuples.
+   **/
   entries() {
     return Array.from(this.#map.entries());
   }
+  /**
+   * Returns all values in insertion order.
+   **/
   values() {
     return Array.from(this.#map.values());
   }
+  /**
+   * Returns all checksummed addresses in insertion order.
+   **/
   keys() {
     return Array.from(this.#map.keys());
   }
+  /**
+   * Converts the map to a plain `Record<Address, T>` object.
+   **/
   asRecord() {
     return Object.fromEntries(this.#map.entries());
   }
+  /**
+   * Number of entries in the map.
+   **/
   get size() {
     return this.#map.size;
   }
+  /**
+   * Prevents further mutations. Any subsequent call to {@link upsert},
+   * {@link insert}, or {@link delete} will throw.
+   */
   freeze() {
     this.#frozen = true;
   }
   get name() {
     return this.#name;
   }
+  /**
+   * Creates an `AddressMap` from a plain record object.
+   * @param record - Object whose keys are EVM addresses.
+   */
   static fromRecord(record) {
     return new AddressMap(Object.entries(record));
   }
+  /**
+   * 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(array, mapFn) {
     return new AddressMap(array.map((item) => [mapFn(item), item]));
   }

package/dist/esm/sdk/utils/AddressSet.js

@@ -1,5 +1,8 @@
 import { getAddress } from "viem";
 class AddressSet extends Set {
+  /**
+   * @param entries - Optional initial addresses. Each is checksummed automatically.
+   */
   constructor(entries) {
     super(Array.from(entries ?? []).map((a) => getAddress(a)));
   }
@@ -12,9 +15,15 @@ class AddressSet extends Set {
   has(value) {
     return super.has(getAddress(value));
   }
+  /**
+   * Returns all addresses as an array.
+   **/
   asArray() {
     return Array.from(this);
   }
+  /**
+   * Maps each address through `fn` and returns the resulting array.
+   **/
   map(fn) {
     return this.asArray().map(fn);
   }

package/dist/types/permissionless/bindings/price-feed-store.d.ts

@@ -1,8 +1,7 @@
 import { type Address, type Chain, type DecodeFunctionDataReturnType, type Hex, type PublicClient, type Transport } from "viem";
-import type { RawTx } from "../../sdk/index.js";
+import type { PriceUpdate, RawTx } from "../../sdk/index.js";
 import { BaseContract, type ParsedCallArgs } from "../../sdk/index.js";
 import type { InputValueParams, PriceFeed } from "../core/index.js";
-import type { PriceUpdate } from "./types.js";
 declare const abi: readonly [{
     readonly type: "function";
     readonly inputs: readonly [{

package/dist/types/permissionless/bindings/types.d.ts

@@ -59,10 +59,6 @@ export interface Market {
     symbol: string;
     isDeployed: boolean;
 }
-export interface PriceUpdate {
-    priceFeed: Address;
-    data: Hex;
-}
 export declare enum AccessMode {
     Permissionless = 0,
     Permissioned = 1,

package/dist/types/permissionless/utils/price-update/get-price-update-tx.d.ts

@@ -1,7 +1,5 @@
 import { type Address, type Chain, type PublicClient, type Transport } from "viem";
-import { type IPriceUpdateTx, type RawTx } from "../../../sdk/index.js";
-import { type PriceUpdate } from "../../bindings/index.js";
-export declare function getUpdateCalldata(tx: IPriceUpdateTx): PriceUpdate;
+import type { RawTx } from "../../../sdk/index.js";
 export declare function getPriceUpdateTx({ client, priceFeeds, useMulticall3, gasLimit, }: {
     client: PublicClient<Transport, Chain>;
     priceFeeds: Address[];

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

@@ -13,100 +13,302 @@ import { type PluginsMap } from "./plugins/index.js";
 import { type IRouterContract } from "./router/index.js";
 import type { GearboxState, GearboxStateHuman } from "./types/index.js";
 /**
- * State version, checked duryng hydration
- */
+ * Serialised state format version, checked during hydration to detect
+ * incompatible snapshots.
+ **/
 export declare const STATE_VERSION = 1;
+/**
+ * Explicit network identity, required when working with forked testnets
+ * whose chain IDs differ from the canonical mainnet/testnet values.
+ **/
 export interface NetworkOptions {
     /**
-     * Chain Id needs to be set, because we sometimemes use forked testnets with different chain ids
-     */
+     * EVM chain ID.
+     * Must be set explicitly for forked testnets whose chain ID differs
+     * from the canonical network.
+     **/
     chainId: number;
     /**
-     * NetworkType needs to be set, because we sometimemes use forked testnets with different chain ids
-     */
+     * Gearbox network type (e.g. `"Mainnet"`, `"Arbitrum"`).
+     * Must be set explicitly for forked testnets whose chain ID differs
+     * from the canonical network.
+     **/
     networkType: NetworkType;
 }
+/**
+ * Connection options for the underlying JSON-RPC provider.
+ *
+ * Supply **one** of the three variants:
+ * - `rpcURLs` — the SDK creates a viem transport internally (with optional
+ *    fallback when multiple URLs are given).
+ * - `transport` — bring your own viem `Transport`.
+ * - `client` — bring your own fully-configured viem `PublicClient`.
+ *    When using this variant, the client is responsible for carrying the
+ *    correct `networkType` and `chainId`.
+ *
+ * ### Network detection
+ *
+ * For the `rpcURLs` and `transport` variants, `networkType` and `chainId` are
+ * resolved as follows (see {@link NetworkOptions}):
+ * - If `networkType` is provided, it is used directly; `chainId` defaults to
+ *   the canonical chain ID for that network when omitted.
+ * - If `networkType` is **not** provided, it is detected automatically using {@link detectNetwork}.
+ *   When `chainId` is also omitted it is fetched via `eth_chainId`.
+ *
+ **/
 export type ClientOptions = {
     /**
-     * RPC URL (and fallbacks) to use.
-     */
+     * One or more JSON-RPC endpoint URLs.
+     * When more than one URL is provided, a viem `fallback` transport is created.
+     **/
     rpcURLs: string[];
     /**
-     * RPC client timeout in milliseconds
-     */
+     * Per-request timeout in milliseconds.
+     **/
     timeout?: number;
     /**
-     * Retry count for RPC
-     */
+     * Number of automatic retries per RPC call.
+     **/
     retryCount?: number;
+    /**
+     * Low-level options forwarded to the viem HTTP transport.
+     **/
     httpTransportOptions?: HttpRpcClientOptions | undefined;
 } | {
     /**
-     * Alternatively, can pass viem transport
-     */
+     * Pre-built viem transport.
+     **/
     transport: Transport;
 } | {
     /**
-     * Alternatively, can pass entire viem client
-     * If you bring your own client, it is responsible for defining networkType and chainId
-     */
+     * Pre-built viem public client.
+     * Must already carry a {@link GearboxChain} definition with `networkType`
+     * and `chainId`.
+     **/
     client: PublicClient<Transport, GearboxChain>;
 };
+/**
+ * Options accepted by {@link GearboxSDK.hydrate}.
+ *
+ * Same as {@link SDKOptions} but without fields that are already captured
+ * inside the serialised {@link GearboxState} (`blockNumber`,
+ * `addressProvider`, `marketConfigurators`).
+ *
+ * @typeParam Plugins - Map of plugin names to plugin instances.
+ **/
 export type HydrateOptions<Plugins extends PluginsMap> = Omit<SDKOptions<Plugins>, "blockNumber" | "addressProvider" | "marketConfigurators">;
+/**
+ * Options for {@link GearboxSDK.syncState}, controlling which block to
+ * sync to and whether updatable price feeds should be refreshed.
+ **/
 export interface SyncStateOptions {
+    /**
+     * Target block number to sync to.
+     **/
     blockNumber: bigint;
+    /**
+     * Block timestamp corresponding to `blockNumber`.
+     **/
     timestamp: bigint;
+    /**
+     * When `true`, skip refreshing updatable price feeds during this sync.
+     **/
     ignoreUpdateablePrices?: boolean;
 }
+/**
+ * Hook event map for the SDK lifecycle.
+ *
+ * Register listeners via {@link GearboxSDK.addHook} and remove them
+ * with {@link GearboxSDK.removeHook}.
+ *
+ * - `syncState` — fired after {@link GearboxSDK.syncState} completes.
+ * - `rehydrate` — fired after {@link GearboxSDK.rehydrate} completes.
+ **/
 export type SDKHooks = {
     syncState: [SyncStateOptions];
     rehydrate: [SyncStateOptions];
 };
+/**
+ * Main entry point for the Gearbox SDK.
+ *
+ * `GearboxSDK` aggregates on-chain state for the Gearbox protocol — markets,
+ * credit managers, pools, price oracles, and price feeds — into a single
+ * queryable object that can be kept up-to-date via {@link syncState} or
+ * serialised/restored via {@link state}/{@link hydrate}.
+ *
+ * It represents on-chain state using instances of js classes that provide convenient methods
+ * to read state and prepare transactions to interact with the protocol.
+ *
+ * Create an instance with the static {@link GearboxSDK.attach | attach}
+ * (reads live chain data) or {@link GearboxSDK.hydrate | hydrate}
+ * (restores from a saved snapshot) factory methods.
+ *
+ * @typeParam Plugins - Map of plugin names to plugin instances that extend
+ *   the SDK with additional domain-specific functionality.
+ **/
 export declare class GearboxSDK<const Plugins extends PluginsMap = {}> extends ChainContractsRegister {
     #private;
+    /**
+     * Registered plugin instances, keyed by plugin name.
+     **/
     readonly plugins: Plugins;
+    /**
+     * Gas limit applied to read-only `eth_call` requests.
+     * `undefined` means that gas limit will not be set on read-only calls,
+     * leaving it to rpc provider to decide.
+     **/
     readonly gasLimit: bigint | undefined;
     /**
-     * Will throw an error if contract type is not supported, otherwise will try to use generic contract first, if possible
-     */
+     * When `true`, the SDK throws on unrecognised contract types instead of
+     * falling back to a generic contract wrapper.
+     **/
     readonly strictContractTypes: boolean;
+    /**
+     * Registers a callback for an SDK lifecycle event.
+     *
+     * @see {@link SDKHooks} for available event names.
+     **/
     addHook: <K extends keyof SDKHooks>(hookName: K, fn: (...args: SDKHooks[K]) => void | Promise<void>) => void;
+    /**
+     * Removes a previously registered lifecycle callback.
+     *
+     * @see {@link SDKHooks} for available event names.
+     **/
     removeHook: <K extends keyof SDKHooks>(hookName: K, fn: (...args: SDKHooks[K]) => void | Promise<void>) => void;
+    /**
+     * Creates and initialises a new SDK instance by reading live on-chain state.
+     *
+     * This is the primary way to bootstrap the SDK.  The method connects to the
+     * chain, discovers the address provider and all configured markets, and
+     * attaches any supplied plugins.
+     *
+     * @param options - Combined SDK, client, and (optional) network options.
+     * @returns A fully initialised SDK instance.
+     **/
     static attach<const Plugins extends PluginsMap>(options: SDKOptions<Plugins> & ClientOptions & Partial<NetworkOptions>): Promise<GearboxSDK<Plugins>>;
+    /**
+     * Creates a new SDK instance from a previously serialised {@link GearboxState}
+     * snapshot, without making any on-chain calls.
+     *
+     * Use this for fast startup when a recent state snapshot is available
+     * (e.g. loaded from a file or received from a backend service).
+     *
+     * @param options - SDK and client options (block number and address provider
+     *   are taken from the snapshot).
+     * @param state - Serialised state obtained from {@link GearboxSDK.state}.
+     * @returns A fully initialised SDK instance.
+     * @throws If the snapshot's {@link STATE_VERSION} does not match.
+     **/
     static hydrate<const Plugins extends PluginsMap>(options: HydrateOptions<Plugins> & ClientOptions, state: GearboxState<Plugins>): GearboxSDK<Plugins>;
     private constructor();
     /**
-     * Reattach SDK with the same config as before, without re-creating instance. Will load all state from scratch
-     * Be mindful of block number, for example
-     */
+     * Re-attaches the SDK using the same configuration, discarding all cached
+     * state and re-reading everything from the chain.
+     *
+     * Useful when the SDK needs a full refresh (e.g. after a protocol upgrade).
+     * Note that if the original `blockNumber` was pinned, the same block is
+     * re-used — call {@link syncState} instead if you want to advance.
+     *
+     * @throws If the SDK has not been attached yet.
+     **/
     reattach(): Promise<void>;
     /**
-     * Rehydrate existing SDK from new state without re-creating instance
-     */
+     * Replaces the SDK's in-memory state with a new serialised snapshot
+     * without re-creating the instance.
+     *
+     * After hydration the `rehydrate` hook is triggered so that listeners
+     * can react to the state change.
+     *
+     * @param state - Serialised state obtained from {@link GearboxSDK.state}.
+     * @throws If the SDK has not been attached or hydrated yet.
+     **/
     rehydrate(state: GearboxState<Plugins>): Promise<void>;
+    /**
+     * Gearbox network type the SDK is connected to (e.g. `"Mainnet"`, `"Arbitrum"`).
+     **/
     get networkType(): NetworkType;
+    /**
+     * Returns a human-readable snapshot of the entire SDK state, suitable
+     * for logging or diagnostic inspection.
+     *
+     * @param raw - When `true`, include raw numeric values alongside
+     *   formatted ones.
+     * @default true
+     **/
     stateHuman(raw?: boolean): GearboxStateHuman;
+    /**
+     * Serialisable snapshot of the current SDK state.
+     *
+     * The returned object can be persisted (e.g. written to a file) and later
+     * passed to {@link GearboxSDK.hydrate} for instant restoration without
+     * on-chain reads.
+     **/
     get state(): GearboxState<Plugins>;
     /**
-     * Reloads markets states based on events from last processed block to new block (defaults to latest block)
-     * @param opts
-     * @returns true if successful, false if was skipped or failed
-     */
+     * Incrementally updates the SDK state by replaying on-chain events from the
+     * last processed block up to the target block (defaults to `latest`).
+     *
+     * Use the to periodically update sdk state on cron, or subscribe to new blocks
+     * using viem's `watchBlocks`
+     *
+     * On failure the SDK reverts to the previous block/timestamp so that
+     * subsequent calls can retry.
+     *
+     * @param opts - Target block and sync behaviour. When omitted the latest
+     *   block is fetched automatically.
+     * @returns `true` if the sync completed successfully, `false` if it was
+     *   skipped or failed.
+     **/
     syncState(opts?: SyncStateOptions): Promise<boolean>;
+    /**
+     * Block number that the SDK state corresponds to.
+     *
+     * @throws If the SDK has not been attached or hydrated yet.
+     **/
     get currentBlock(): bigint;
+    /**
+     * Block timestamp (Unix epoch seconds) corresponding to {@link currentBlock}.
+     *
+     * @throws If the SDK has not been attached or hydrated yet.
+     **/
     get timestamp(): bigint;
     /**
-     * All price feeds known to sdk, without oracle-related data (stalenessPeriod, main/reserve, etc.)
-     */
+     * Global registry of all price feeds known to the SDK (on all markets).
+     *
+     * Unlike per-oracle price feed references, this register does not carry
+     * oracle-specific metadata (staleness period, main/reserve designation, etc.).
+     *
+     * @throws If the SDK has not been attached or hydrated yet.
+     **/
     get priceFeeds(): PriceFeedRegister;
+    /**
+     * Address of the GEAR governance token on this chain, or `undefined`
+     * if the address provider does not list it.
+     **/
     get gear(): Address | undefined;
+    /**
+     * The chain's address provider contract, the central directory for all
+     * protocol-wide Gearbox protocol addresses.
+     *
+     * @throws If the SDK has not been attached or hydrated yet.
+     **/
     get addressProvider(): IAddressProviderContract;
+    /**
+     * Registry of all loaded markets (pools, credit managers, oracles, etc.).
+     *
+     * @throws If the SDK has not been attached or hydrated yet.
+     **/
     get marketRegister(): MarketRegister;
     /**
-     * Returns router contract that will work for given credit manager or credit facade, or simply version range
-     * @param params
-     * @returns
-     */
+     * Resolves the appropriate router contract for a given credit manager,
+     * credit facade, or explicit version range.
+     *
+     * @param params - Identifies the context: a credit manager address/state,
+     *   a credit facade address/state, or a {@link VersionRange}.
+     * @returns The matching router contract instance.
+     * @throws If the credit facade version is unsupported or no router is
+     *   registered for the resolved version range.
+     **/
     routerFor(params: {
         creditManager: Address | BaseState | IBaseContract;
     } | {