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

package/dist/cjs/sdk/router/AbstractRouterContract.js

@@ -26,6 +26,9 @@ var import_math = require("../constants/math.js");
 var import_utils = require("../utils/index.js");
 var import_helpers = require("./helpers.js");
 class AbstractRouterContract extends import_base.BaseContract {
+  /**
+   * Reference to the parent SDK instance.
+   **/
   sdk;
   constructor(sdk, args) {
     super(sdk, args);
@@ -88,7 +91,7 @@ class AbstractRouterContract extends import_base.BaseContract {
     };
   }
   /**
-   * 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/cjs/sdk/router/RouterV310Contract.js

@@ -41,8 +41,8 @@ class RouterV310Contract extends import_AbstractRouterContract.AbstractRouterCon
     });
   }
   /**
-   * Implements {@link IRouterContract.findOneTokenPath}
-   */
+   * {@inheritDoc IRouterContract.findOneTokenPath}
+   **/
   async findOneTokenPath(props) {
     const {
       creditAccount,
@@ -83,8 +83,8 @@ class RouterV310Contract extends import_AbstractRouterContract.AbstractRouterCon
     };
   }
   /**
-   * Implements {@link IRouterContract.findOpenStrategyPath}
-   */
+   * {@inheritDoc IRouterContract.findOpenStrategyPath}
+   **/
   async findOpenStrategyPath(props) {
     const {
       creditManager: cm,
@@ -141,8 +141,8 @@ class RouterV310Contract extends import_AbstractRouterContract.AbstractRouterCon
     };
   }
   /**
-   * Implements {@link IRouterContract.findClaimAllRewards}
-   */
+   * {@inheritDoc IRouterContract.findClaimAllRewards}
+   **/
   async findClaimAllRewards(props) {
     const record = props.tokensToClaim.reduce(
       (acc, a) => {
@@ -167,8 +167,8 @@ class RouterV310Contract extends import_AbstractRouterContract.AbstractRouterCon
     };
   }
   /**
-   * Implements {@link IRouterContract.findBestClosePath}
-   */
+   * {@inheritDoc IRouterContract.findBestClosePath}
+   **/
   async findBestClosePath(props) {
     const {
       creditAccount: ca,
@@ -233,17 +233,22 @@ class RouterV310Contract extends import_AbstractRouterContract.AbstractRouterCon
     };
   }
   /**
-   * 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, numSplits) {
     this.#numSplits.upsert(token, numSplits);
   }
   /**
-   * 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) {
     this.#defaultNumSplits = numSplits;
   }

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

@@ -26,6 +26,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) {
@@ -37,9 +41,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) {
@@ -53,9 +58,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) {
@@ -70,27 +76,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 = (0, import_viem.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 = (0, import_viem.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 = (0, import_viem.getAddress)(address);
@@ -100,40 +105,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 = (0, import_viem.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/cjs/sdk/utils/AddressSet.js

@@ -23,6 +23,9 @@ __export(AddressSet_exports, {
 module.exports = __toCommonJS(AddressSet_exports);
 var import_viem = require("viem");
 class AddressSet extends Set {
+  /**
+   * @param entries - Optional initial addresses. Each is checksummed automatically.
+   */
   constructor(entries) {
     super(Array.from(entries ?? []).map((a) => (0, import_viem.getAddress)(a)));
   }
@@ -35,9 +38,15 @@ class AddressSet extends Set {
   has(value) {
     return super.has((0, import_viem.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/esm/permissionless/utils/price-update/get-price-update-tx.js

@@ -1,26 +1,13 @@
 import {
-  decodeFunctionData,
-  multicall3Abi,
-  parseAbi
+  multicall3Abi
 } from "viem";
 import {
   createRawTx,
-  GearboxSDK
+  GearboxSDK,
+  getRawPriceUpdates
 } from "../../../sdk/index.js";
-import {
-  PriceFeedStoreContract
-} from "../../bindings/index.js";
+import { PriceFeedStoreContract } from "../../bindings/index.js";
 import { Addresses } from "../../deployment/addresses.js";
-function getUpdateCalldata(tx) {
-  const data = decodeFunctionData({
-    abi: parseAbi(["function updatePrice(bytes calldata data) external"]),
-    data: tx.raw.callData
-  });
-  return {
-    priceFeed: tx.raw.to,
-    data: data.args[0]
-  };
-}
 async function getPriceUpdateTx({
   client,
   priceFeeds,
@@ -57,13 +44,12 @@ async function getPriceUpdateTx({
     });
     return multicallTx;
   }
-  const priceUpdates = updateTxs.txs.map((tx) => getUpdateCalldata(tx));
+  const priceUpdates = getRawPriceUpdates(updateTxs);
   if (priceUpdates.length === 0) {
     return void 0;
   }
   return pfStore.updatePrices(priceUpdates);
 }
 export {
-  getPriceUpdateTx,
-  getUpdateCalldata
+  getPriceUpdateTx
 };

package/dist/esm/sdk/GearboxSDK.js

@@ -67,24 +67,50 @@ async function attachClient(options, network) {
 }
 class GearboxSDK extends ChainContractsRegister {
   #hooks = new Hooks();
+  /**
+   * Registered plugin instances, keyed by plugin name.
+   **/
   plugins;
-  // Block which was use for data query
   #currentBlock;
   #timestamp;
   #syncing = false;
-  // Collection of core singleton contracts
   #addressProvider;
   #attachConfig;
-  // Collection of markets
   #marketRegister;
   #priceFeeds;
+  /**
+   * 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.
+   **/
   gasLimit;
   /**
-   * 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.
+   **/
   strictContractTypes;
+  /**
+   * Registers a callback for an SDK lifecycle event.
+   *
+   * @see {@link SDKHooks} for available event names.
+   **/
   addHook = this.#hooks.addHook.bind(this.#hooks);
+  /**
+   * Removes a previously registered lifecycle callback.
+   *
+   * @see {@link SDKHooks} for available event names.
+   **/
   removeHook = this.#hooks.removeHook.bind(this.#hooks);
+  /**
+   * 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 async attach(options) {
     const {
       logger,
@@ -120,6 +146,19 @@ class GearboxSDK extends ChainContractsRegister {
       pyth
     });
   }
+  /**
+   * 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(options, state) {
     const { logger, plugins, strictContractTypes, gasLimit, ...rest } = options;
     const client = createClient(options, {
@@ -272,9 +311,15 @@ class GearboxSDK extends ChainContractsRegister {
     return this;
   }
   /**
-   * 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.
+   **/
   async reattach() {
     if (!this.#attachConfig) {
       throw new Error("cannot reattach, attach config is not set");
@@ -282,8 +327,15 @@ class GearboxSDK extends ChainContractsRegister {
     await this.#attach(this.#attachConfig);
   }
   /**
-   * 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.
+   **/
   async rehydrate(state) {
     if (!this.#attachConfig) {
       throw new Error("cannot rehydrate, attach config is not set");
@@ -299,9 +351,20 @@ class GearboxSDK extends ChainContractsRegister {
       timestamp: state.timestamp
     });
   }
+  /**
+   * Gearbox network type the SDK is connected to (e.g. `"Mainnet"`, `"Arbitrum"`).
+   **/
   get networkType() {
     return this.client.chain.network;
   }
+  /**
+   * 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 = true) {
     return {
       block: Number(this.currentBlock),
@@ -319,6 +382,13 @@ class GearboxSDK extends ChainContractsRegister {
       ...this.marketRegister.stateHuman(raw)
     };
   }
+  /**
+   * 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() {
     return {
       version: STATE_VERSION,
@@ -337,10 +407,20 @@ class GearboxSDK extends ChainContractsRegister {
     };
   }
   /**
-   * 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.
+   **/
   async syncState(opts) {
     let {
       blockNumber,
@@ -442,12 +522,22 @@ class GearboxSDK extends ChainContractsRegister {
     }
     return success;
   }
+  /**
+   * Block number that the SDK state corresponds to.
+   *
+   * @throws If the SDK has not been attached or hydrated yet.
+   **/
   get currentBlock() {
     if (this.#currentBlock === void 0) {
       throw ERR_NOT_ATTACHED;
     }
     return this.#currentBlock;
   }
+  /**
+   * Block timestamp (Unix epoch seconds) corresponding to {@link currentBlock}.
+   *
+   * @throws If the SDK has not been attached or hydrated yet.
+   **/
   get timestamp() {
     if (this.#timestamp === void 0) {
       throw ERR_NOT_ATTACHED;
@@ -455,14 +545,23 @@ class GearboxSDK extends ChainContractsRegister {
     return this.#timestamp;
   }
   /**
-   * 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() {
     if (this.#priceFeeds === void 0) {
       throw ERR_NOT_ATTACHED;
     }
     return this.#priceFeeds;
   }
+  /**
+   * Address of the GEAR governance token on this chain, or `undefined`
+   * if the address provider does not list it.
+   **/
   get gear() {
     try {
       const g = this.addressProvider.getAddress(AP_GEAR_TOKEN, NO_VERSION);
@@ -472,12 +571,23 @@ class GearboxSDK extends ChainContractsRegister {
       return void 0;
     }
   }
+  /**
+   * 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() {
     if (this.#addressProvider === void 0) {
       throw ERR_NOT_ATTACHED;
     }
     return this.#addressProvider;
   }
+  /**
+   * Registry of all loaded markets (pools, credit managers, oracles, etc.).
+   *
+   * @throws If the SDK has not been attached or hydrated yet.
+   **/
   get marketRegister() {
     if (this.#marketRegister === void 0) {
       throw ERR_NOT_ATTACHED;
@@ -485,10 +595,15 @@ class GearboxSDK extends ChainContractsRegister {
     return this.#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) {
     let routerRange;
     if (Array.isArray(params)) {