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

package/dist/cjs/common-utils/utils/creditAccount/quotaUtils.js

@@ -0,0 +1,149 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var quotaUtils_exports = {};
+__export(quotaUtils_exports, {
+  calcDefaultQuota: () => calcDefaultQuota,
+  calcQuotaUpdate: () => calcQuotaUpdate,
+  calcRecommendedQuota: () => calcRecommendedQuota,
+  roundUpQuota: () => roundUpQuota
+});
+module.exports = __toCommonJS(quotaUtils_exports);
+var import_sdk = require("../../../sdk/index.js");
+var import_bigintMath = require("../bigintMath.js");
+function roundUpQuota(quotaChange) {
+  return quotaChange !== import_sdk.MIN_INT96 ? quotaChange / import_sdk.PERCENTAGE_FACTOR * import_sdk.PERCENTAGE_FACTOR : quotaChange;
+}
+function calcRecommendedQuota({
+  amount,
+  debt,
+  lt,
+  quotaReserve
+}) {
+  const recommendedBaseQuota = import_bigintMath.BigIntMath.min(
+    debt,
+    amount * lt / import_sdk.PERCENTAGE_FACTOR
+  );
+  const recommendedQuota = recommendedBaseQuota * (import_sdk.PERCENTAGE_FACTOR + quotaReserve) / import_sdk.PERCENTAGE_FACTOR;
+  return roundUpQuota(recommendedQuota);
+}
+function calcDefaultQuota({
+  amount,
+  lt,
+  quotaReserve
+}) {
+  const recommendedBaseQuota = amount * lt / import_sdk.PERCENTAGE_FACTOR;
+  const recommendedQuota = recommendedBaseQuota * (import_sdk.PERCENTAGE_FACTOR + quotaReserve) / import_sdk.PERCENTAGE_FACTOR;
+  return roundUpQuota(recommendedQuota);
+}
+function calcQuotaUpdate(props) {
+  const { quotas, initialQuotas, maxDebt, allowedToSpend, allowedToObtain } = props;
+  const quotaDecrease = Object.keys(allowedToSpend).reduce((acc, token) => {
+    const ch = getSingleQuotaChange(token, 0n, props);
+    if (ch && ch.balance < 0) acc[ch.token] = ch;
+    return acc;
+  }, {});
+  const quotaCap = roundUpQuota(maxDebt * 2n);
+  const quotaBought = Object.values(initialQuotas).reduce(
+    (sum, q) => sum + roundUpQuota(q?.quota || 0n),
+    0n
+  );
+  const quotaReduced = Object.values(quotaDecrease).reduce((sum, q) => {
+    const quotaBalance = q.balance || 0n;
+    const safeBalance = quotaBalance === import_sdk.MIN_INT96 ? import_bigintMath.BigIntMath.neg(roundUpQuota(initialQuotas[q.token]?.quota || 0n)) : quotaBalance;
+    return sum + safeBalance;
+  }, 0n);
+  const maxQuotaIncrease = roundUpQuota(
+    import_bigintMath.BigIntMath.max(quotaCap - (quotaBought + quotaReduced), 0n)
+  );
+  const quotaIncrease = Object.keys(allowedToObtain).reduce((acc, token) => {
+    const ch = getSingleQuotaChange(token, maxQuotaIncrease, props);
+    if (ch && ch.balance > 0) acc[ch.token] = ch;
+    return acc;
+  }, {});
+  const quotaChange = {
+    ...quotaDecrease,
+    ...quotaIncrease
+  };
+  const desiredQuota = Object.values(quotas).reduce(
+    (acc, cmQuota) => {
+      const { token, isActive } = cmQuota;
+      const { quota: initialQuota = 0n } = initialQuotas[token] || {};
+      if (!isActive) {
+        acc[token] = {
+          balance: initialQuota,
+          token
+        };
+      } else {
+        const change = quotaChange[token]?.balance || 0n;
+        const quotaAfter = change === import_sdk.MIN_INT96 ? 0n : initialQuota + change;
+        acc[token] = {
+          balance: quotaAfter,
+          token
+        };
+      }
+      return acc;
+    },
+    {}
+  );
+  return {
+    desiredQuota,
+    quotaDecrease: Object.values(quotaDecrease),
+    quotaIncrease: Object.values(quotaIncrease)
+  };
+}
+function getSingleQuotaChange(token, unsafeMaxQuotaIncrease, props) {
+  const { isActive = false } = props.quotas[token] || {};
+  const { quota: unsafeInitialQuota = 0n } = props.initialQuotas[token] || {};
+  if (!isActive) {
+    return void 0;
+  }
+  const assetAfter = props.assetsAfterUpdate[token];
+  const { amountInTarget = 0n } = assetAfter || {};
+  const lt = props.liquidationThresholds[token] || 0n;
+  const maxQuotaIncrease = roundUpQuota(unsafeMaxQuotaIncrease);
+  const initialQuota = roundUpQuota(unsafeInitialQuota);
+  const defaultQuota = props.calcModification?.type === "recommendedQuota" && props.calcModification.debt > 0 ? calcRecommendedQuota({
+    lt,
+    quotaReserve: props.quotaReserve,
+    amount: amountInTarget,
+    debt: props.calcModification.debt
+  }) : calcDefaultQuota({
+    lt,
+    quotaReserve: props.quotaReserve,
+    amount: amountInTarget
+  });
+  const unsafeQuotaChange = roundUpQuota(defaultQuota - initialQuota);
+  const quotaChange = unsafeQuotaChange > 0 ? import_bigintMath.BigIntMath.min(maxQuotaIncrease, unsafeQuotaChange) : unsafeQuotaChange < 0 && import_bigintMath.BigIntMath.abs(unsafeQuotaChange) >= initialQuota ? import_sdk.MIN_INT96 : unsafeQuotaChange;
+  const correctIncrease = assetAfter && props.allowedToObtain[token] && quotaChange > 0;
+  const correctDecrease = assetAfter && props.allowedToSpend[token] && quotaChange < 0;
+  if (correctIncrease || correctDecrease) {
+    return {
+      balance: quotaChange,
+      token
+    };
+  }
+  return void 0;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  calcDefaultQuota,
+  calcQuotaUpdate,
+  calcRecommendedQuota,
+  roundUpQuota
+});

package/dist/cjs/common-utils/utils/creditAccount/sort.js

@@ -0,0 +1,95 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var sort_exports = {};
+__export(sort_exports, {
+  amountAbcComparator: () => amountAbcComparator,
+  assetComparator: () => assetComparator,
+  sortAssets: () => sortAssets,
+  sortBalances: () => sortBalances,
+  tokensAbcComparator: () => tokensAbcComparator
+});
+module.exports = __toCommonJS(sort_exports);
+var import_sdk = require("../../../sdk/index.js");
+var import_priceMath = require("../priceMath.js");
+function sortBalances(balances, prices, tokens) {
+  return Object.entries(balances).sort(
+    ([addr1, amount1], [addr2, amount2]) => {
+      return assetComparator(
+        {
+          token: addr1,
+          balance: amount1
+        },
+        {
+          token: addr2,
+          balance: amount2
+        },
+        prices,
+        prices,
+        tokens,
+        tokens
+      );
+    }
+  );
+}
+function sortAssets(balances, prices, tokens) {
+  return [...balances].sort(
+    (t1, t2) => assetComparator(t1, t2, prices, prices, tokens, tokens)
+  );
+}
+function assetComparator(t1, t2, prices1, prices2, tokens1, tokens2) {
+  const addr1Lc = t1.token.toLowerCase();
+  const addr2Lc = t2.token.toLowerCase();
+  const token1 = tokens1?.[addr1Lc];
+  const token2 = tokens2?.[addr2Lc];
+  const price1 = prices1?.[addr1Lc] || import_sdk.PRICE_DECIMALS;
+  const price2 = prices2?.[addr2Lc] || import_sdk.PRICE_DECIMALS;
+  const totalPrice1 = import_priceMath.PriceUtils.calcTotalPrice(
+    price1,
+    t1.balance,
+    token1?.decimals
+  );
+  const totalPrice2 = import_priceMath.PriceUtils.calcTotalPrice(
+    price2,
+    t2.balance,
+    token2?.decimals
+  );
+  if (totalPrice1 === totalPrice2) {
+    return t1.balance === t2.balance ? tokensAbcComparator(token1, token2) : amountAbcComparator(t1.balance, t2.balance);
+  }
+  return amountAbcComparator(totalPrice1, totalPrice2);
+}
+function tokensAbcComparator(t1, t2) {
+  const { symbol: symbol1 = "" } = t1 || {};
+  const { symbol: symbol2 = "" } = t2 || {};
+  const symbol1LC = symbol1.toLowerCase();
+  const symbol2LC = symbol2.toLowerCase();
+  if (symbol1LC === symbol2LC) return 0;
+  return symbol1LC > symbol2LC ? 1 : -1;
+}
+function amountAbcComparator(t1, t2) {
+  return t1 > t2 ? -1 : 1;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  amountAbcComparator,
+  assetComparator,
+  sortAssets,
+  sortBalances,
+  tokensAbcComparator
+});

package/dist/cjs/common-utils/utils/creditAccount/types.js

@@ -0,0 +1,16 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var types_exports = {};
+module.exports = __toCommonJS(types_exports);

package/dist/cjs/{sdk → common-utils}/utils/endpoints.js

@@ -18,11 +18,10 @@ var __copyProps = (to, from, except, desc) => {
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var endpoints_exports = {};
 __export(endpoints_exports, {
-  GearboxBackendApi: () => GearboxBackendApi,
-  URLApi: () => URLApi
+  GearboxBackendApi: () => GearboxBackendApi
 });
 module.exports = __toCommonJS(endpoints_exports);
-var import_chains = require("../chain/chains.js");
+var import_sdk = require("../../sdk/index.js");
 const CHARTS_BACKEND_ADDRESS = "https://charts-server.fly.dev";
 const STATIC_TOKEN = "https://static.gearbox.finance/tokens/";
 class GearboxBackendApi {
@@ -31,8 +30,8 @@ class GearboxBackendApi {
   static getChartsUrl = (url, chainId, options = { params: {} }, priceSource) => {
     const domain = CHARTS_BACKEND_ADDRESS;
     const priceSourceArr = priceSource ? [priceSource] : [];
-    const isMain = (0, import_chains.isSupportedNetwork)(chainId);
-    const relativePath = URLApi.getRelativeUrl(
+    const isMain = (0, import_sdk.isSupportedNetwork)(chainId);
+    const relativePath = getRelativeUrl(
       url,
       isMain ? {
         ...options,
@@ -51,21 +50,16 @@ class GearboxBackendApi {
     const url = `https://dm.gearbox.finance/${network.toLowerCase()}_${root}.json`;
     return url;
   };
-  static apyAllRewards = () => URLApi.getRelativeUrl(
+  static apyAllRewards = () => getRelativeUrl(
     "https://state-cache.gearbox.foundation/apy-server/latest.json"
   );
 }
-class URLApi {
-  constructor() {
-  }
-  static getRelativeUrl = (url, options) => {
-    const { params = {} } = options || {};
-    const paramsString = Object.entries(params).map(([key, value]) => `${key}=${value}`).join("&");
-    return [url, ...paramsString ? [paramsString] : []].join("?");
-  };
-}
+const getRelativeUrl = (url, options) => {
+  const { params = {} } = options || {};
+  const paramsString = Object.entries(params).map(([key, value]) => `${key}=${value}`).join("&");
+  return [url, ...paramsString ? [paramsString] : []].join("?");
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  GearboxBackendApi,
-  URLApi
+  GearboxBackendApi
 });

package/dist/cjs/common-utils/utils/index.js

@@ -0,0 +1,30 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __reExport = (target, mod, secondTarget) => (__copyProps(target, mod, "default"), secondTarget && __copyProps(secondTarget, mod, "default"));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var utils_exports = {};
+module.exports = __toCommonJS(utils_exports);
+__reExport(utils_exports, require("./assetsMath.js"), module.exports);
+__reExport(utils_exports, require("./bigintMath.js"), module.exports);
+__reExport(utils_exports, require("./creditAccount/index.js"), module.exports);
+__reExport(utils_exports, require("./endpoints.js"), module.exports);
+__reExport(utils_exports, require("./priceMath.js"), module.exports);
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ...require("./assetsMath.js"),
+  ...require("./bigintMath.js"),
+  ...require("./creditAccount/index.js"),
+  ...require("./endpoints.js"),
+  ...require("./priceMath.js")
+});

package/dist/cjs/common-utils/utils/priceMath.js

@@ -0,0 +1,66 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var priceMath_exports = {};
+__export(priceMath_exports, {
+  PriceUtils: () => PriceUtils
+});
+module.exports = __toCommonJS(priceMath_exports);
+var import_sdk = require("../../sdk/index.js");
+class PriceUtils {
+  /**
+   * This class is intentionally non-instantiable.
+   */
+  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, amount, decimals = 18) => amount * import_sdk.WAD * price / 10n ** BigInt(decimals) / import_sdk.PRICE_DECIMALS;
+  /**
+   * 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, { price: targetPrice, decimals: targetDecimals = 18 }) {
+    if (targetPrice <= 0n) return 0n;
+    return totalMoney * 10n ** BigInt(targetDecimals) * import_sdk.PRICE_DECIMALS / targetPrice / import_sdk.WAD;
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  PriceUtils
+});

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

@@ -18,13 +18,9 @@ module.exports = __toCommonJS(utils_exports);
 __reExport(utils_exports, require("./AddressMap.js"), module.exports);
 __reExport(utils_exports, require("./AddressSet.js"), module.exports);
 __reExport(utils_exports, require("./abi-decode.js"), module.exports);
-__reExport(utils_exports, require("./assetsMath.js"), module.exports);
-__reExport(utils_exports, require("./bigintMath.js"), module.exports);
 __reExport(utils_exports, require("./bytes32ToString.js"), module.exports);
 __reExport(utils_exports, require("./childLogger.js"), module.exports);
 __reExport(utils_exports, require("./createRawTx.js"), module.exports);
-__reExport(utils_exports, require("./creditAccount.js"), module.exports);
-__reExport(utils_exports, require("./endpoints.js"), module.exports);
 __reExport(utils_exports, require("./etherscan.js"), module.exports);
 __reExport(utils_exports, require("./filterDust.js"), module.exports);
 __reExport(utils_exports, require("./formatter.js"), module.exports);
@@ -32,7 +28,6 @@ __reExport(utils_exports, require("./hex.js"), module.exports);
 __reExport(utils_exports, require("./isDust.js"), module.exports);
 __reExport(utils_exports, require("./json.js"), module.exports);
 __reExport(utils_exports, require("./mappers.js"), module.exports);
-__reExport(utils_exports, require("./priceMath.js"), module.exports);
 __reExport(utils_exports, require("./retry.js"), module.exports);
 __reExport(utils_exports, require("./toAddress.js"), module.exports);
 __reExport(utils_exports, require("./type-utils.js"), module.exports);
@@ -42,13 +37,9 @@ __reExport(utils_exports, require("./zod.js"), module.exports);
   ...require("./AddressMap.js"),
   ...require("./AddressSet.js"),
   ...require("./abi-decode.js"),
-  ...require("./assetsMath.js"),
-  ...require("./bigintMath.js"),
   ...require("./bytes32ToString.js"),
   ...require("./childLogger.js"),
   ...require("./createRawTx.js"),
-  ...require("./creditAccount.js"),
-  ...require("./endpoints.js"),
   ...require("./etherscan.js"),
   ...require("./filterDust.js"),
   ...require("./formatter.js"),
@@ -56,7 +47,6 @@ __reExport(utils_exports, require("./zod.js"), module.exports);
   ...require("./isDust.js"),
   ...require("./json.js"),
   ...require("./mappers.js"),
-  ...require("./priceMath.js"),
   ...require("./retry.js"),
   ...require("./toAddress.js"),
   ...require("./type-utils.js"),

package/dist/esm/common-utils/index.js

@@ -0,0 +1 @@
+export * from "./utils/index.js";

package/dist/esm/common-utils/package.json

@@ -0,0 +1 @@
+{"type": "module","sideEffects":false}

package/dist/esm/{sdk → common-utils}/utils/assetsMath.js

@@ -1,7 +1,22 @@
 import { BigIntMath } from "./bigintMath.js";
-import { CreditAccountDataUtils } from "./creditAccount.js";
+import { sortBalances } from "./creditAccount/sort.js";
 import { PriceUtils } from "./priceMath.js";
 class AssetUtils {
+  constructor() {
+  }
+  /**
+   * Selects the next candidate token to add to a selected-asset list.
+   *
+   * Flow:
+   * 1) Removes tokens already present in `selectedAssets`
+   * 2) Builds balances for the remaining allowed tokens
+   * 3) Sorts the balances using `CreditAccountDataUtils.sortBalances`
+   * 4) Returns the highest-priority token address, if any
+   *
+   * Addresses are normalized to lowercase for matching.
+   *
+   * @returns The next token address to select, or `undefined` if no candidates remain.
+   */
   static nextAsset({
     allowedTokens,
     selectedAssets,
@@ -20,7 +35,7 @@ class AssetUtils {
       const alreadySelected = selectedRecord[allowedToken.toLowerCase()];
       return !alreadySelected;
     });
-    const sorted = CreditAccountDataUtils.sortBalances(
+    const sorted = sortBalances(
       AssetUtils.getBalances(notSelected, balances),
       prices,
       tokensList
@@ -28,15 +43,30 @@ class AssetUtils {
     const [address] = sorted[0] || [];
     return address;
   }
+  /**
+   * Builds a normalized balance record for a specific token subset.
+   *
+   * Missing balances are defaulted to `0n`.
+   *
+   * @param allowedTokens Tokens to include in the output record.
+   * @param externalBalances Source balances keyed by lowercase address.
+   * @returns A record that contains only `allowedTokens`.
+   */
   static getBalances(allowedTokens, externalBalances) {
     return allowedTokens.reduce((acc, address) => {
       const addressLc = address.toLowerCase();
-      return {
-        ...acc,
-        [addressLc]: externalBalances[addressLc] || 0n
-      };
+      acc[addressLc] = externalBalances[addressLc] || 0n;
+      return acc;
     }, {});
   }
+  /**
+   * Converts an asset array into a token-address keyed record.
+   *
+   * If duplicate token addresses are present, the last occurrence wins.
+   *
+   * @param a Source asset list.
+   * @returns Record keyed by `asset.token`.
+   */
   static constructAssetRecord(a) {
     const record = a.reduce((acc, asset) => {
       acc[asset.token] = asset;
@@ -44,6 +74,18 @@ class AssetUtils {
     }, {});
     return record;
   }
+  /**
+   * Creates a reusable wrapper function that merges "unwrapped" and "wrapped"
+   * token balances into the wrapped token representation.
+   *
+   * The returned function:
+   * - converts non-negative unwrapped balance into wrapped units by price
+   * - adds the converted amount to the wrapped token balance
+   * - removes the unwrapped token from the result list
+   * - leaves input untouched when no unwrapped token is present
+   *
+   * @returns A function producing `[assets, convertedUnwrapped, originalWrapped]`.
+   */
   static memoWrap = (unwrappedAddress, wrappedAddress, prices, tokensList) => function wrap(assets) {
     const assetsRecord = AssetUtils.constructAssetRecord(assets);
     const unwrapped = assetsRecord[unwrappedAddress];
@@ -76,8 +118,16 @@ class AssetUtils {
     return [Object.values(assetsRecord), 0n, wrappedAmount];
   };
   /**
-   * Sums the the second assets list into the first assets list
-   * Balances cant be negative; creates new assets.
+   * Adds balances from the second asset list into the first list.
+   *
+   * Behavior:
+   * - balances are clamped to non-negative before summation
+   * - tokens found only in `b` are created in the output
+   * - existing asset metadata is preserved from `a` when possible
+   *
+   * @param a Base asset list.
+   * @param b Asset deltas to add.
+   * @returns A merged list containing assets from both inputs.
    */
   static sumAssets(a, b) {
     const aRecord = AssetUtils.constructAssetRecord(a);
@@ -95,8 +145,16 @@ class AssetUtils {
     return Object.values(resRecord);
   }
   /**
-   * Sums the the second assets list into the first assets list
-   * Balances cant be negative; doesn't create new assets.
+   * Adds balances from the second list to matching assets in the first list.
+   *
+   * Behavior:
+   * - balances are clamped to non-negative before summation
+   * - only assets already present in `a` are returned
+   * - no new token entries are created
+   *
+   * @param a Base asset list.
+   * @param b Asset deltas keyed by token.
+   * @returns Updated version of `a` with adjusted balances.
    */
   static addBalances(a, b) {
     const bRecord = AssetUtils.constructAssetRecord(b);
@@ -108,8 +166,16 @@ class AssetUtils {
     });
   }
   /**
-   * Subtracts the the second assets list from the first assets list
-   * Balances cant be negative; doesn't create new assets.
+   * Subtracts balances in the second list from matching assets in the first list.
+   *
+   * Behavior:
+   * - both operands are clamped to non-negative before subtraction
+   * - output balances are clamped to non-negative after subtraction
+   * - only assets already present in `a` are returned
+   *
+   * @param a Base asset list.
+   * @param b Asset amounts to subtract by token.
+   * @returns Updated `a` list with non-negative post-subtraction balances.
    */
   static subAssets(a, b) {
     const bRecord = AssetUtils.constructAssetRecord(b);

package/dist/esm/common-utils/utils/bigintMath.js

@@ -0,0 +1,41 @@
+class BigIntMath {
+  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) => x < 0n ? -x : x;
+  /**
+   * 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, b) => a > b ? a : b;
+  /**
+   * 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, b) => a < b ? a : b;
+  /**
+   * 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) => a > 0 ? a * -1n : a;
+}
+export {
+  BigIntMath
+};