@gearbox-protocol/sdk 13.0.0-beta.4 → 13.0.0-beta.5

package/dist/types/common-utils/utils/bigintMath.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Utility namespace for common `bigint` operations.
+ *
+ * The constructor is private because this class is not meant to be
+ * instantiated; all helpers are exposed as static functions.
+ */
+export declare class BigIntMath {
+    private constructor();
+    /**
+     * Returns the absolute (non-negative) value of a bigint.
+     *
+     * @param x Input value.
+     * @returns `x` when `x` is already non-negative, otherwise `-x`.
+     */
+    static abs: (x: bigint) => bigint;
+    /**
+     * Returns the greater of two bigint values.
+     *
+     * @param a First candidate value.
+     * @param b Second candidate value.
+     * @returns The larger value between `a` and `b`.
+     */
+    static max: (a: bigint, b: bigint) => bigint;
+    /**
+     * Returns the smaller of two bigint values.
+     *
+     * @param a First candidate value.
+     * @param b Second candidate value.
+     * @returns The smaller value between `a` and `b`.
+     */
+    static min: (a: bigint, b: bigint) => bigint;
+    /**
+     * Returns the negative form of a bigint if it is currently positive.
+     *
+     * Useful when a value should be represented as an outflow/debit:
+     * - positive values become negative
+     * - zero and negative values are returned unchanged
+     *
+     * @param a Input value.
+     * @returns A non-positive bigint representation of `a`.
+     */
+    static neg: (a: bigint) => bigint;
+}

package/dist/types/common-utils/utils/creditAccount/calcHealthFactor.d.ts

@@ -0,0 +1,25 @@
+import type { Address } from "viem";
+import { type Asset } from "../../../sdk/index.js";
+import type { QuotaInfoIsActiveSlice, TokenDataSlice } from "./types.js";
+export interface CalcHealthFactorProps {
+    assets: Array<Asset>;
+    quotas: Record<Address, Asset>;
+    quotasInfo: Record<Address, QuotaInfoIsActiveSlice>;
+    prices: Record<Address, bigint>;
+    liquidationThresholds: Record<Address, bigint>;
+    underlyingToken: Address;
+    debt: bigint;
+    tokensList: Record<Address, TokenDataSlice>;
+}
+/**
+ * Computes account health factor in percentage-factor units.
+ *
+ * The function evaluates collateral value under liquidation thresholds,
+ * applies quota caps for quoted tokens, and compares the resulting
+ * liquidation-adjusted collateral against borrowed value.
+ *
+ * @param props Credit account balances, quotas, prices, thresholds, and debt context.
+ * @returns Health factor as a number in `PERCENTAGE_FACTOR` scale,
+ * or `65535` when debt is zero.
+ */
+export declare function calcHealthFactor({ assets, quotas, quotasInfo, liquidationThresholds, underlyingToken, debt, prices, tokensList, }: CalcHealthFactorProps): number;

package/dist/types/common-utils/utils/creditAccount/calcOverallAPY.d.ts

@@ -0,0 +1,37 @@
+import type { Address } from "viem";
+import { type Asset } from "../../../sdk/index.js";
+import type { QuotaInfoSlice, TokenDataSlice } from "./types.js";
+export interface CalcOverallAPYProps {
+    caAssets: Array<Asset>;
+    lpAPY: Record<Address, number> | undefined;
+    quotas: Record<Address, Asset>;
+    quotaRates: Record<Address, QuotaInfoSlice>;
+    feeInterest: number;
+    prices: Record<Address, bigint>;
+    totalValue: bigint | undefined;
+    debt: bigint | undefined;
+    baseRateWithFee: number;
+    underlyingToken: Address;
+    tokensList: Record<Address, TokenDataSlice>;
+}
+/**
+ * Computes net portfolio APY for a credit account.
+ *
+ * The resulting value combines:
+ * - positive LP yield from supplied assets
+ * - negative quota borrowing cost (with interest fee)
+ * - negative base debt borrowing cost
+ * and normalizes by user-owned equity (`totalValue - debt`) in underlying value terms.
+ *
+ * ```
+ * [
+ * Sum(amount_i * price_i * apy_i - quota_i * quotaPrice * quotaRate_i * (1 + feeInterest)) -
+ *  debt * debtPrice * baseRateWithFee
+ * ] / (totalValue - debt) * debtPrice
+ * ```
+ *
+ * @param props Credit account assets, rates, prices, debt, and token metadata.
+ * @returns APY in percentage-factor scale as `bigint`, or `undefined`
+ * when required inputs are missing or invalid.
+ */
+export declare function calcOverallAPY({ caAssets, lpAPY, prices, quotas, quotaRates, feeInterest, totalValue, debt, baseRateWithFee, underlyingToken, tokensList, }: CalcOverallAPYProps): bigint | undefined;

package/dist/types/common-utils/utils/creditAccount/calcQuotaBorrowRate.d.ts

@@ -0,0 +1,18 @@
+import type { Address } from "viem";
+import type { Asset } from "../../../sdk/index.js";
+import type { QuotaInfoSlice } from "./types.js";
+export interface CalcQuotaBorrowRateProps {
+    quotas: Record<Address, Asset>;
+    quotaRates: Record<Address, QuotaInfoSlice>;
+}
+/**
+ * Aggregates weighted quota borrow rate exposure across active quotas.
+ *
+ * For each quota token, contribution is:
+ * `activeQuotaBalance * quotaRate`.
+ * Inactive quotas are ignored.
+ *
+ * @param props Quota balances and per-token quota rates.
+ * @returns Sum of `balance * rate` terms in percentage-factor scale.
+ */
+export declare function calcQuotaBorrowRate({ quotas, quotaRates, }: CalcQuotaBorrowRateProps): bigint;

package/dist/types/common-utils/utils/creditAccount/calcRelativeBaseBorrowRate.d.ts

@@ -0,0 +1,15 @@
+export interface CalcRelativeBaseBorrowRateProps {
+    debt: bigint;
+    baseRateWithFee: number;
+    assetAmountInUnderlying: bigint;
+}
+/**
+ * Computes base borrow-rate impact relative to asset amount.
+ *
+ * This helper is used as an intermediate weighted term:
+ * `debt * baseRateWithFee * assetAmountInUnderlying`.
+ *
+ * @param props Debt amount, base borrow rate (with fee), and normalized asset amount.
+ * @returns Relative borrow-rate contribution in bigint arithmetic.
+ */
+export declare function calcRelativeBaseBorrowRate({ debt, baseRateWithFee, assetAmountInUnderlying, }: CalcRelativeBaseBorrowRateProps): bigint;

package/dist/types/common-utils/utils/creditAccount/debt.d.ts

@@ -0,0 +1,35 @@
+import type { Address } from "viem";
+import { type Asset } from "../../../sdk/index.js";
+import type { TokenDataSlice } from "./types.js";
+export interface CalcMaxLendingDebtProps {
+    assets: Array<Asset>;
+    prices: Record<Address, bigint>;
+    liquidationThresholds: Record<Address, bigint>;
+    underlyingToken: Address;
+    tokensList: Record<Address, TokenDataSlice>;
+    targetHF?: bigint;
+}
+/**
+ * Calculates additional debt that can be borrowed while targeting
+ * a minimum health factor after the borrow.
+ *
+ * The derivation comes from the post-borrow HF equation and clamps
+ * negative results to zero.
+ *
+ * @param healthFactor Current health factor in percentage-factor units.
+ * @param debt Current debt amount.
+ * @param underlyingLT Liquidation threshold of underlying token.
+ * @param minHf Target minimum health factor (defaults to `PERCENTAGE_FACTOR`).
+ * @returns Maximum non-negative debt increase.
+ */
+export declare function calcMaxDebtIncrease(healthFactor: number, debt: bigint, underlyingLT: number, minHf?: number): bigint;
+/**
+ * Calculates maximum debt capacity for lending based on collateral mix.
+ *
+ * It computes liquidation-threshold-weighted collateral value and converts
+ * it into underlying-token debt units at the requested target health factor.
+ *
+ * @param props Asset balances, prices, thresholds, target HF, and token metadata.
+ * @returns Maximum borrowable debt amount in underlying token units.
+ */
+export declare function calcMaxLendingDebt({ assets, liquidationThresholds, underlyingToken, prices, tokensList, targetHF, }: CalcMaxLendingDebtProps): bigint;

package/dist/types/common-utils/utils/creditAccount/getTimeToLiquidation.d.ts

@@ -0,0 +1,16 @@
+export interface TimeToLiquidationProps {
+    totalBorrowRate_debt: bigint;
+    healthFactor: number;
+}
+/**
+ * Estimates time remaining until health factor reaches liquidation level.
+ *
+ * Assumes linear debt growth under current aggregate borrow-rate exposure
+ * and returns a millisecond duration until `healthFactor` decays to `1.0`
+ * (`PERCENTAGE_FACTOR` in internal scale).
+ *
+ * @param props Current health factor and `totalBorrowRate * debt` term.
+ * @returns Milliseconds to liquidation as `bigint`, or `null` when already at/under
+ * liquidation threshold or when borrow-rate exposure is zero.
+ */
+export declare function getTimeToLiquidation({ healthFactor, totalBorrowRate_debt, }: TimeToLiquidationProps): bigint | null;

package/dist/types/common-utils/utils/creditAccount/index.d.ts

@@ -0,0 +1,9 @@
+export * from "./calcHealthFactor.js";
+export * from "./calcQuotaBorrowRate.js";
+export * from "./calcQuotaBorrowRate.js";
+export * from "./calcRelativeBaseBorrowRate.js";
+export * from "./debt.js";
+export * from "./getTimeToLiquidation.js";
+export * from "./liquidationPrice.js";
+export * from "./quotaUtils.js";
+export * from "./sort.js";

package/dist/types/common-utils/utils/creditAccount/liquidationPrice.d.ts

@@ -0,0 +1,25 @@
+import type { Address } from "viem";
+import type { Asset } from "../../../sdk/index.js";
+import type { TokenDataSlice } from "./types.js";
+interface LiquidationPriceProps {
+    liquidationThresholds: Record<Address, bigint>;
+    debt: bigint;
+    underlyingToken: Address;
+    targetToken: Address;
+    assets: Record<Address, Asset>;
+    tokensList: Record<Address, TokenDataSlice>;
+}
+/**
+ * Calculates target token liquidation price for a credit account.
+ *
+ * The formula uses:
+ * - effective debt adjusted by underlying-token collateral contribution
+ * - target token effective balance
+ * - target token liquidation threshold
+ *
+ * @param props Debt context, assets, thresholds, and token metadata.
+ * @returns Target token price in `PRICE_DECIMALS` precision that corresponds
+ * to liquidation boundary; returns `0n` when target balance or LT is non-positive.
+ */
+export declare function liquidationPrice({ liquidationThresholds, debt, underlyingToken, targetToken, assets, tokensList, }: LiquidationPriceProps): bigint;
+export {};

package/dist/types/common-utils/utils/creditAccount/quotaUtils.d.ts

@@ -0,0 +1,81 @@
+import type { Address } from "viem";
+import { type Asset } from "../../../sdk/index.js";
+import type { AssetWithAmountInTarget, QuotaInfoTokenSlice } from "./types.js";
+export interface CalcDefaultQuotaProps {
+    amount: bigint;
+    lt: bigint;
+    quotaReserve: bigint;
+}
+export interface CalcRecommendedQuotaProps {
+    amount: bigint;
+    debt: bigint;
+    lt: bigint;
+    quotaReserve: bigint;
+}
+export interface CalcQuotaUpdateProps {
+    quotas: Record<Address, QuotaInfoTokenSlice>;
+    initialQuotas: Record<Address, {
+        quota: bigint;
+    }>;
+    liquidationThresholds: Record<Address, bigint>;
+    assetsAfterUpdate: Record<Address, AssetWithAmountInTarget>;
+    maxDebt: bigint;
+    calcModification?: {
+        type: "recommendedQuota";
+        debt: bigint;
+    };
+    allowedToSpend: Record<Address, object>;
+    allowedToObtain: Record<Address, object>;
+    quotaReserve: bigint;
+}
+interface CalcQuotaUpdateReturnType {
+    desiredQuota: Record<Address, Asset>;
+    quotaIncrease: Array<Asset>;
+    quotaDecrease: Array<Asset>;
+}
+/**
+ * Rounds quota deltas to protocol precision step (`PERCENTAGE_FACTOR`).
+ *
+ * The `MIN_INT96` sentinel is preserved as-is because it encodes
+ * "reset quota" semantics and must not be transformed.
+ *
+ * @param quotaChange Raw quota delta.
+ * @returns Rounded quota delta, or untouched `MIN_INT96` sentinel.
+ */
+export declare function roundUpQuota(quotaChange: bigint): bigint;
+/**
+ * Computes recommended quota for a token when debt-aware capping is enabled.
+ *
+ * Base quota is `min(debt, amount * LT)`, then reserve buffer is applied.
+ * Final value is rounded to protocol quota step.
+ *
+ * @param props Token amount in target units, debt, liquidation threshold, reserve.
+ * @returns Recommended rounded quota.
+ */
+export declare function calcRecommendedQuota({ amount, debt, lt, quotaReserve, }: CalcRecommendedQuotaProps): bigint;
+/**
+ * Computes default quota for a token without debt capping.
+ *
+ * Base quota is `amount * LT`, then reserve buffer is applied.
+ * Final value is rounded to protocol quota step.
+ *
+ * @param props Token amount in target units, liquidation threshold, reserve.
+ * @returns Default rounded quota.
+ */
+export declare function calcDefaultQuota({ amount, lt, quotaReserve, }: CalcDefaultQuotaProps): bigint;
+/**
+ * Produces desired quota state and explicit increase/decrease actions.
+ *
+ * The function:
+ * - computes decreases for spendable tokens
+ * - computes increase capacity based on global quota cap
+ * - computes increases for obtainable tokens within remaining capacity
+ * - applies changes on top of initial quotas for active quota tokens
+ *
+ * `MIN_INT96` is treated as a full reset marker for a token quota.
+ *
+ * @param props Current quotas, initial quotas, permissions, and calculation context.
+ * @returns Desired quota map plus separate increase/decrease instruction lists.
+ */
+export declare function calcQuotaUpdate(props: CalcQuotaUpdateProps): CalcQuotaUpdateReturnType;
+export {};

package/dist/types/common-utils/utils/creditAccount/sort.d.ts

@@ -0,0 +1,55 @@
+import type { Address } from "viem";
+import { type Asset } from "../../../sdk/index.js";
+import type { TokenDataSlice } from "./types.js";
+/**
+ * Sorts balance record entries by descending total value.
+ *
+ * Ordering uses `assetComparator` (value-desc, then amount-desc, then symbol-asc).
+ *
+ * @param balances Token balance map.
+ * @param prices Token prices map.
+ * @param tokens Token metadata map.
+ * @returns Sorted `[token, balance]` tuples.
+ */
+export declare function sortBalances(balances: Record<Address, bigint>, prices: Record<Address, bigint>, tokens: Record<Address, TokenDataSlice>): Array<[Address, bigint]>;
+/**
+ * Sorts an asset array by descending total value.
+ *
+ * Ordering uses `assetComparator` (value-desc, then amount-desc, then symbol-asc).
+ *
+ * @param balances Asset list to sort.
+ * @param prices Token prices map.
+ * @param tokens Token metadata map.
+ * @returns New sorted array (input is not mutated).
+ */
+export declare function sortAssets<T extends Asset>(balances: Array<T>, prices: Record<Address, bigint>, tokens: Record<Address, TokenDataSlice>): T[];
+/**
+ * Compares two assets for deterministic sorting.
+ *
+ * Priority:
+ * 1) higher total value (price * amount) first
+ * 2) higher raw balance first when values are equal
+ * 3) token symbol alphabetical order when balances are equal
+ *
+ * Missing prices fall back to `PRICE_DECIMALS`; missing token metadata
+ * is tolerated.
+ *
+ * @returns Comparator result suitable for `Array.prototype.sort`.
+ */
+export declare function assetComparator<T extends Asset>(t1: T, t2: T, prices1: Record<Address, bigint> | undefined, prices2: Record<Address, bigint> | undefined, tokens1: Record<Address, TokenDataSlice> | undefined, tokens2: Record<Address, TokenDataSlice> | undefined): 1 | 0 | -1;
+/**
+ * Alphabetical comparator for token symbols (case-insensitive).
+ *
+ * @param t1 First token metadata.
+ * @param t2 Second token metadata.
+ * @returns `-1`, `0`, or `1` for ascending symbol order.
+ */
+export declare function tokensAbcComparator(t1?: TokenDataSlice, t2?: TokenDataSlice): 1 | 0 | -1;
+/**
+ * Descending numeric comparator for bigint amounts.
+ *
+ * @param t1 First amount.
+ * @param t2 Second amount.
+ * @returns `-1` when `t1` should come before `t2`, otherwise `1`.
+ */
+export declare function amountAbcComparator(t1: bigint, t2: bigint): 1 | -1;

package/dist/types/common-utils/utils/creditAccount/types.d.ts

@@ -0,0 +1,18 @@
+import type { Address } from "viem";
+import type { Asset } from "../../../sdk/index.js";
+export interface TokenDataSlice {
+    symbol: string;
+    decimals: number;
+}
+export interface QuotaInfoIsActiveSlice {
+    isActive: boolean;
+}
+export interface QuotaInfoTokenSlice extends QuotaInfoIsActiveSlice {
+    token: Address;
+}
+export interface QuotaInfoSlice extends QuotaInfoIsActiveSlice {
+    rate: bigint;
+}
+export interface AssetWithAmountInTarget extends Asset {
+    amountInTarget: bigint;
+}

package/dist/types/{sdk → common-utils}/utils/endpoints.d.ts

@@ -1,6 +1,18 @@
 import type { Address } from "viem";
-import { type NetworkType } from "../chain/chains.js";
+import { type NetworkType } from "../../sdk/index.js";
 type ChartsPriceSource = "chainlink" | "spot";
+/**
+ * Centralized endpoint builder for Gearbox backend resources.
+ *
+ * This utility exposes static helpers that compose canonical URLs for:
+ * - charts backend API routes
+ * - static token metadata
+ * - rewards and NFT merkle proof files
+ * - APY state cache snapshots
+ *
+ * The class is intentionally non-instantiable and is used as a pure
+ * namespace of URL-construction functions.
+ */
 export declare class GearboxBackendApi {
     private constructor();
     static getChartsUrl: (url: string, chainId: number, options?: Options, priceSource?: ChartsPriceSource) => string;
@@ -12,8 +24,4 @@ export declare class GearboxBackendApi {
 interface Options {
     params?: Record<string, string | number>;
 }
-export declare class URLApi {
-    private constructor();
-    static getRelativeUrl: (url: string, options?: Options) => string;
-}
 export {};

package/dist/types/common-utils/utils/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./assetsMath.js";
+export * from "./bigintMath.js";
+export * from "./creditAccount/index.js";
+export * from "./endpoints.js";
+export * from "./priceMath.js";

package/dist/types/common-utils/utils/priceMath.d.ts

@@ -0,0 +1,47 @@
+interface Target {
+    price: bigint;
+    decimals: number | undefined;
+}
+/**
+ * Static utility namespace for converting between token amounts and
+ * normalized value using oracle-like prices.
+ *
+ * All helpers rely on shared fixed-point constants (`WAD` and
+ * `PRICE_DECIMALS`) to keep arithmetic consistent across assets
+ * with different token decimal precisions.
+ */
+export declare class PriceUtils {
+    /**
+     * This class is intentionally non-instantiable.
+     */
+    private constructor();
+    /**
+     * Calculates normalized total value for a token amount at a given price.
+     *
+     * Formula:
+     * `(amount * WAD * price) / 10^decimals / PRICE_DECIMALS`
+     *
+     * @param price Token unit price in `PRICE_DECIMALS` precision.
+     * @param amount Token amount in raw token units.
+     * @param decimals Token decimals used to normalize `amount` (defaults to `18`).
+     * @returns Total value in WAD-normalized units.
+     */
+    static calcTotalPrice: (price: bigint, amount: bigint, decimals?: number | undefined) => bigint;
+    /**
+     * Converts a normalized monetary value into target token amount by price.
+     *
+     * Formula:
+     * `(totalMoney * 10^targetDecimals * PRICE_DECIMALS) / targetPrice / WAD`
+     *
+     * Safety behavior:
+     * - returns `0n` when `targetPrice <= 0n` to avoid invalid division
+     *
+     * @param totalMoney Value to convert, expected in WAD-normalized units.
+     * @param target Conversion target configuration:
+     * - `price`: target token unit price in `PRICE_DECIMALS` precision
+     * - `decimals`: target token decimals (defaults to `18`)
+     * @returns Target token amount in raw token units.
+     */
+    static convertByPrice(totalMoney: bigint, { price: targetPrice, decimals: targetDecimals }: Target): bigint;
+}
+export {};

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

@@ -1,13 +1,9 @@
 export * from "./AddressMap.js";
 export * from "./AddressSet.js";
 export * from "./abi-decode.js";
-export * from "./assetsMath.js";
-export * from "./bigintMath.js";
 export * from "./bytes32ToString.js";
 export * from "./childLogger.js";
 export * from "./createRawTx.js";
-export * from "./creditAccount.js";
-export * from "./endpoints.js";
 export * from "./etherscan.js";
 export * from "./filterDust.js";
 export * from "./formatter.js";
@@ -15,7 +11,6 @@ export * from "./hex.js";
 export * from "./isDust.js";
 export * from "./json.js";
 export * from "./mappers.js";
-export * from "./priceMath.js";
 export * from "./retry.js";
 export * from "./toAddress.js";
 export * from "./type-utils.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gearbox-protocol/sdk",
-  "version": "13.0.0-beta.4",
+  "version": "13.0.0-beta.5",
   "description": "Gearbox SDK",
   "license": "MIT",
   "main": "./dist/cjs/sdk/index.js",
@@ -39,6 +39,11 @@
       "types": "./dist/types/permissionless/index.d.ts",
       "import": "./dist/esm/permissionless/index.js",
       "default": "./dist/cjs/permissionless/index.js"
+    },
+    "./common-utils": {
+      "types": "./dist/types/common-utils/index.d.ts",
+      "import": "./dist/esm/common-utils/index.js",
+      "default": "./dist/cjs/common-utils/index.js"
     }
   },
   "files": [