@morpho-org/blue-sdk 6.0.0 → 6.1.0

package/lib/esm/market/MarketUtils.js

@@ -11,6 +11,22 @@ export var MarketUtils;
     /**
      * Returns the id of a market based on its params.
      * @param market The market params.
+     * @returns The deterministic Morpho Blue market id.
+     * @example
+     * ```ts
+     * import { MarketUtils } from "@morpho-org/blue-sdk";
+     *
+     * const marketParams = {
+     *   loanToken: "0x0000000000000000000000000000000000000001",
+     *   collateralToken: "0x0000000000000000000000000000000000000002",
+     *   oracle: "0x0000000000000000000000000000000000000003",
+     *   irm: "0x0000000000000000000000000000000000000004",
+     *   lltv: 860_000_000_000_000_000n,
+     * } as const;
+     *
+     * const id = MarketUtils.getMarketId(marketParams);
+     * // id satisfies MarketId
+     * ```
      */
     function getMarketId(market) {
         return `0x${bytesToHex(keccak_256(hexToBytes(`${market.loanToken.substring(2).toLowerCase().padStart(64, "0") +
@@ -26,6 +42,14 @@ export var MarketUtils;
     /**
      * Returns the liquidation incentive factor for a given market params.
      * @param config The market params.
+     * @returns The liquidation incentive factor, scaled by WAD.
+     * @example
+     * ```ts
+     * import { MarketUtils } from "@morpho-org/blue-sdk";
+     *
+     * const lif = MarketUtils.getLiquidationIncentiveFactor({ lltv: 86_0000000000000000n });
+     * // lif satisfies bigint
+     * ```
      */
     function getLiquidationIncentiveFactor({ lltv }) {
         return MathLib.min(MAX_LIQUIDATION_INCENTIVE_FACTOR, MathLib.wDivDown(MathLib.WAD, MathLib.WAD -
@@ -35,6 +59,17 @@ export var MarketUtils;
     /**
      * Returns the market's utilization rate (scaled by WAD).
      * @param market The market state.
+     * @returns The market utilization rate, scaled by WAD.
+     * @example
+     * ```ts
+     * import { MarketUtils } from "@morpho-org/blue-sdk";
+     *
+     * const utilization = MarketUtils.getUtilization({
+     *   totalSupplyAssets: 100n,
+     *   totalBorrowAssets: 50n,
+     * });
+     * // utilization === 500000000000000000n
+     * ```
      */
     function getUtilization({ totalSupplyAssets, totalBorrowAssets, }) {
         totalSupplyAssets = BigInt(totalSupplyAssets);
@@ -51,6 +86,14 @@ export var MarketUtils;
      * Returns the per-second rate continuously compounded over a year,
      * as calculated in Morpho Blue assuming the market is frequently accrued onchain.
      * @param rate The per-second rate to compound annually.
+     * @returns The annual percentage yield as a JavaScript number.
+     * @example
+     * ```ts
+     * import { MarketUtils } from "@morpho-org/blue-sdk";
+     *
+     * const apy = MarketUtils.rateToApy(1n);
+     * // apy satisfies number
+     * ```
      */
     function rateToApy(rate) {
         return Math.expm1(+formatEther(BigInt(rate) * SECONDS_PER_YEAR));
@@ -103,6 +146,17 @@ export var MarketUtils;
      * Returns the smallest volume to supply until the market gets the closest to the given utilization rate.
      * @param market The market state.
      * @param utilization The target utilization rate (scaled by WAD).
+     * @returns The amount to supply to approach the target utilization.
+     * @example
+     * ```ts
+     * import { MarketUtils, MathLib } from "@morpho-org/blue-sdk";
+     *
+     * const assets = MarketUtils.getSupplyToUtilization(
+     *   { totalSupplyAssets: 100n, totalBorrowAssets: 80n },
+     *   MathLib.WAD / 2n,
+     * );
+     * // assets satisfies bigint
+     * ```
      */
     function getSupplyToUtilization(market, utilization) {
         // biome-ignore lint/style/noParameterAssign: TODO refactor to avoid mutating parameter
@@ -119,6 +173,17 @@ export var MarketUtils;
      * Returns the liquidity available to withdraw until the market gets the closest to the given utilization rate.
      * @param market The market state.
      * @param utilization The target utilization rate (scaled by WAD).
+     * @returns The amount withdrawable before reaching the target utilization.
+     * @example
+     * ```ts
+     * import { MarketUtils, MathLib } from "@morpho-org/blue-sdk";
+     *
+     * const assets = MarketUtils.getWithdrawToUtilization(
+     *   { totalSupplyAssets: 100n, totalBorrowAssets: 50n },
+     *   MathLib.WAD,
+     * );
+     * // assets satisfies bigint
+     * ```
      */
     function getWithdrawToUtilization({ totalSupplyAssets, totalBorrowAssets, }, utilization) {
         // biome-ignore lint/style/noParameterAssign: TODO refactor to avoid mutating parameter
@@ -137,6 +202,17 @@ export var MarketUtils;
      * Returns the liquidity available to borrow until the market gets the closest to the given utilization rate.
      * @param market The market state.
      * @param utilization The target utilization rate (scaled by WAD).
+     * @returns The amount borrowable before reaching the target utilization.
+     * @example
+     * ```ts
+     * import { MarketUtils, MathLib } from "@morpho-org/blue-sdk";
+     *
+     * const assets = MarketUtils.getBorrowToUtilization(
+     *   { totalSupplyAssets: 100n, totalBorrowAssets: 50n },
+     *   MathLib.WAD,
+     * );
+     * // assets satisfies bigint
+     * ```
      */
     function getBorrowToUtilization({ totalSupplyAssets, totalBorrowAssets, }, utilization) {
         return MathLib.zeroFloorSub(MathLib.wMulDown(totalSupplyAssets, utilization), totalBorrowAssets);
@@ -146,11 +222,36 @@ export var MarketUtils;
      * Returns the smallest volume to repay until the market gets the closest to the given utilization rate.
      * @param market The market state.
      * @param utilization The target utilization rate (scaled by WAD).
+     * @returns The amount to repay before reaching the target utilization.
+     * @example
+     * ```ts
+     * import { MarketUtils, MathLib } from "@morpho-org/blue-sdk";
+     *
+     * const assets = MarketUtils.getRepayToUtilization(
+     *   { totalSupplyAssets: 100n, totalBorrowAssets: 80n },
+     *   MathLib.WAD / 2n,
+     * );
+     * // assets satisfies bigint
+     * ```
      */
     function getRepayToUtilization({ totalSupplyAssets, totalBorrowAssets, }, utilization) {
         return MathLib.zeroFloorSub(totalBorrowAssets, MathLib.wMulDown(totalSupplyAssets, utilization));
     }
     MarketUtils.getRepayToUtilization = getRepayToUtilization;
+    /**
+     * Returns the borrow power of a collateral amount before oracle pricing.
+     *
+     * @param collateral - The collateral amount.
+     * @param marketParams.lltv - The market liquidation loan-to-value, scaled by WAD.
+     * @returns The collateral amount multiplied by LLTV.
+     * @example
+     * ```ts
+     * import { MarketUtils } from "@morpho-org/blue-sdk";
+     *
+     * const power = MarketUtils.getCollateralPower(100n, { lltv: 50_0000000000000000n });
+     * // power === 50n
+     * ```
+     */
     function getCollateralPower(collateral, { lltv }) {
         return MathLib.wMulDown(collateral, lltv);
     }
@@ -158,6 +259,17 @@ export var MarketUtils;
     /**
      * Returns the value of a given amount of collateral quoted in loan assets.
      * Return `undefined` iff the market's price is undefined.
+     *
+     * @param collateral - The collateral amount.
+     * @param market.price - The oracle price, scaled by `ORACLE_PRICE_SCALE`.
+     * @returns The collateral value in loan assets, or `undefined` when price is unavailable.
+     * @example
+     * ```ts
+     * import { MarketUtils, ORACLE_PRICE_SCALE } from "@morpho-org/blue-sdk";
+     *
+     * const value = MarketUtils.getCollateralValue(2n, { price: ORACLE_PRICE_SCALE });
+     * // value === 2n
+     * ```
      */
     function getCollateralValue(collateral, { price }) {
         if (price == null)
@@ -169,6 +281,22 @@ export var MarketUtils;
      * Returns the maximum debt allowed given a certain amount of collateral.
      * Return `undefined` iff the market's price is undefined.
      * To calculate the amount of loan assets that can be borrowed, use `getMaxBorrowableAssets`.
+     *
+     * @param collateral - The collateral amount.
+     * @param market.price - The oracle price, scaled by `ORACLE_PRICE_SCALE`.
+     * @param marketParams.lltv - The market liquidation loan-to-value, scaled by WAD.
+     * @returns The maximum borrow assets allowed, or `undefined` when price is unavailable.
+     * @example
+     * ```ts
+     * import { MarketUtils, ORACLE_PRICE_SCALE } from "@morpho-org/blue-sdk";
+     *
+     * const maxBorrow = MarketUtils.getMaxBorrowAssets(
+     *   2n,
+     *   { price: ORACLE_PRICE_SCALE },
+     *   { lltv: 50_0000000000000000n },
+     * );
+     * // maxBorrow === 1n
+     * ```
      */
     // biome-ignore lint/complexity/useMaxParams: TODO refactor to ≤2 params
     function getMaxBorrowAssets(collateral, market, { lltv }) {
@@ -181,6 +309,25 @@ export var MarketUtils;
     /**
      * Returns the maximum amount of loan assets that can be borrowed given a certain borrow position.
      * Return `undefined` iff the market's price is undefined.
+     *
+     * @param position.collateral - The collateral amount in the position.
+     * @param position.borrowShares - The borrow shares in the position.
+     * @param market.totalBorrowAssets - The market's total borrowed assets.
+     * @param market.totalBorrowShares - The market's total borrow shares.
+     * @param market.price - The oracle price, scaled by `ORACLE_PRICE_SCALE`.
+     * @param marketParams.lltv - The market liquidation loan-to-value, scaled by WAD.
+     * @returns The additional borrowable loan assets, or `undefined` when price is unavailable.
+     * @example
+     * ```ts
+     * import { MarketUtils, ORACLE_PRICE_SCALE } from "@morpho-org/blue-sdk";
+     *
+     * const borrowable = MarketUtils.getMaxBorrowableAssets(
+     *   { collateral: 2n, borrowShares: 0n },
+     *   { totalBorrowAssets: 0n, totalBorrowShares: 0n, price: ORACLE_PRICE_SCALE },
+     *   { lltv: 50_0000000000000000n },
+     * );
+     * // borrowable satisfies bigint | undefined
+     * ```
      */
     // biome-ignore lint/complexity/useMaxParams: TODO refactor to ≤2 params
     function getMaxBorrowableAssets({ collateral, borrowShares, }, market, marketParams) {
@@ -193,6 +340,24 @@ export var MarketUtils;
     /**
      * Returns the amount of collateral that would be seized in a liquidation given a certain amount of repaid shares.
      * Return `undefined` iff the market's price is undefined.
+     *
+     * @param repaidShares - The borrow shares repaid by the liquidation.
+     * @param market.totalBorrowAssets - The market's total borrowed assets.
+     * @param market.totalBorrowShares - The market's total borrow shares.
+     * @param market.price - The oracle price, scaled by `ORACLE_PRICE_SCALE`.
+     * @param config.lltv - The market liquidation loan-to-value, scaled by WAD.
+     * @returns The seized collateral amount, or `undefined` when price is unavailable.
+     * @example
+     * ```ts
+     * import { MarketUtils, ORACLE_PRICE_SCALE } from "@morpho-org/blue-sdk";
+     *
+     * const seized = MarketUtils.getLiquidationSeizedAssets(
+     *   1n,
+     *   { totalBorrowAssets: 1n, totalBorrowShares: 1n, price: ORACLE_PRICE_SCALE },
+     *   { lltv: 86_0000000000000000n },
+     * );
+     * // seized satisfies bigint | undefined
+     * ```
      */
     // biome-ignore lint/complexity/useMaxParams: TODO refactor to ≤2 params
     function getLiquidationSeizedAssets(repaidShares, market, config) {
@@ -207,6 +372,24 @@ export var MarketUtils;
     /**
      * Returns the amount of borrow shares that would be repaid in a liquidation given a certain amount of seized collateral.
      * Return `undefined` iff the market's price is undefined.
+     *
+     * @param seizedAssets - The collateral amount seized by the liquidation.
+     * @param market.totalBorrowAssets - The market's total borrowed assets.
+     * @param market.totalBorrowShares - The market's total borrow shares.
+     * @param market.price - The oracle price, scaled by `ORACLE_PRICE_SCALE`.
+     * @param config.lltv - The market liquidation loan-to-value, scaled by WAD.
+     * @returns The borrow shares repaid, or `undefined` when price is unavailable.
+     * @example
+     * ```ts
+     * import { MarketUtils, ORACLE_PRICE_SCALE } from "@morpho-org/blue-sdk";
+     *
+     * const shares = MarketUtils.getLiquidationRepaidShares(
+     *   1n,
+     *   { totalBorrowAssets: 1n, totalBorrowShares: 1n, price: ORACLE_PRICE_SCALE },
+     *   { lltv: 86_0000000000000000n },
+     * );
+     * // shares satisfies bigint | undefined
+     * ```
      */
     // biome-ignore lint/complexity/useMaxParams: TODO refactor to ≤2 params
     function getLiquidationRepaidShares(seizedAssets, market, config) {
@@ -218,6 +401,25 @@ export var MarketUtils;
     /**
      * Returns the maximum amount of collateral that is worth being seized in a liquidation given a certain borrow position.
      * Return `undefined` iff the market's price is undefined.
+     *
+     * @param position.collateral - The collateral amount in the position.
+     * @param position.borrowShares - The borrow shares in the position.
+     * @param market.totalBorrowAssets - The market's total borrowed assets.
+     * @param market.totalBorrowShares - The market's total borrow shares.
+     * @param market.price - The oracle price, scaled by `ORACLE_PRICE_SCALE`.
+     * @param config.lltv - The market liquidation loan-to-value, scaled by WAD.
+     * @returns The maximum seizable collateral, or `undefined` when price is unavailable.
+     * @example
+     * ```ts
+     * import { MarketUtils, ORACLE_PRICE_SCALE } from "@morpho-org/blue-sdk";
+     *
+     * const collateral = MarketUtils.getSeizableCollateral(
+     *   { collateral: 1n, borrowShares: 1n },
+     *   { totalBorrowAssets: 1n, totalBorrowShares: 1n, price: ORACLE_PRICE_SCALE },
+     *   { lltv: 50_0000000000000000n },
+     * );
+     * // collateral satisfies bigint | undefined
+     * ```
      */
     // biome-ignore lint/complexity/useMaxParams: TODO refactor to ≤2 params
     function getSeizableCollateral(position, market, config) {
@@ -232,6 +434,25 @@ export var MarketUtils;
     /**
      * Returns the amount of collateral that can be withdrawn given a certain borrow position.
      * Return `undefined` iff the market's price is undefined.
+     *
+     * @param position.collateral - The collateral amount in the position.
+     * @param position.borrowShares - The borrow shares in the position.
+     * @param market.totalBorrowAssets - The market's total borrowed assets.
+     * @param market.totalBorrowShares - The market's total borrow shares.
+     * @param market.price - The oracle price, scaled by `ORACLE_PRICE_SCALE`.
+     * @param marketParams.lltv - The market liquidation loan-to-value, scaled by WAD.
+     * @returns The withdrawable collateral amount, or `undefined` when price is unavailable.
+     * @example
+     * ```ts
+     * import { MarketUtils, ORACLE_PRICE_SCALE } from "@morpho-org/blue-sdk";
+     *
+     * const collateral = MarketUtils.getWithdrawableCollateral(
+     *   { collateral: 2n, borrowShares: 0n },
+     *   { totalBorrowAssets: 0n, totalBorrowShares: 0n, price: ORACLE_PRICE_SCALE },
+     *   { lltv: 50_0000000000000000n },
+     * );
+     * // collateral satisfies bigint | undefined
+     * ```
      */
     // biome-ignore lint/complexity/useMaxParams: TODO refactor to ≤2 params
     function getWithdrawableCollateral({ collateral, borrowShares, }, market, { lltv }) {
@@ -247,6 +468,20 @@ export var MarketUtils;
      * Returns whether a given borrow position is healthy.
      * Return `undefined` iff the market's price is undefined.
      * @param position The borrow position to check.
+     * @param market The market state used to value the position.
+     * @param marketParams The market params containing LLTV.
+     * @returns Whether the position is healthy, or `undefined` when price is unavailable.
+     * @example
+     * ```ts
+     * import { MarketUtils, ORACLE_PRICE_SCALE } from "@morpho-org/blue-sdk";
+     *
+     * const healthy = MarketUtils.isHealthy(
+     *   { collateral: 2n, borrowShares: 0n },
+     *   { totalBorrowAssets: 0n, totalBorrowShares: 0n, price: ORACLE_PRICE_SCALE },
+     *   { lltv: 50_0000000000000000n },
+     * );
+     * // healthy satisfies boolean | undefined
+     * ```
      */
     // biome-ignore lint/complexity/useMaxParams: TODO refactor to ≤2 params
     function isHealthy({ collateral, borrowShares, }, market, marketParams) {
@@ -260,6 +495,24 @@ export var MarketUtils;
      * Returns the price of the collateral quoted in the loan token (e.g. ETH/DAI)
      * that set the user's position to be liquidatable.
      * Returns null if the position is not a borrow.
+     *
+     * @param position.collateral - The collateral amount in the position.
+     * @param position.borrowShares - The borrow shares in the position.
+     * @param market.totalBorrowAssets - The market's total borrowed assets.
+     * @param market.totalBorrowShares - The market's total borrow shares.
+     * @param marketParams.lltv - The market liquidation loan-to-value, scaled by WAD.
+     * @returns The liquidation price, or `null` when the position has no borrow.
+     * @example
+     * ```ts
+     * import { MarketUtils } from "@morpho-org/blue-sdk";
+     *
+     * const price = MarketUtils.getLiquidationPrice(
+     *   { collateral: 2n, borrowShares: 1n },
+     *   { totalBorrowAssets: 1n, totalBorrowShares: 1n },
+     *   { lltv: 50_0000000000000000n },
+     * );
+     * // price satisfies bigint | null
+     * ```
      */
     // biome-ignore lint/complexity/useMaxParams: TODO refactor to ≤2 params
     function getLiquidationPrice({ collateral, borrowShares, }, market, marketParams) {
@@ -279,6 +532,22 @@ export var MarketUtils;
      * Negative when healthy (the price needs to drop x%), positive when unhealthy (the price needs to soar x%).
      * Returns `undefined` iff the market's price is undefined.
      * Returns null if the position is not a borrow.
+     *
+     * @param position - The borrow position to evaluate.
+     * @param market - The market state used to value the position.
+     * @param marketParams - The market params containing LLTV.
+     * @returns The WAD-scaled price variation, `undefined`, or `null` when the position has no borrow.
+     * @example
+     * ```ts
+     * import { MarketUtils, ORACLE_PRICE_SCALE } from "@morpho-org/blue-sdk";
+     *
+     * const variation = MarketUtils.getPriceVariationToLiquidationPrice(
+     *   { collateral: 2n, borrowShares: 1n },
+     *   { totalBorrowAssets: 1n, totalBorrowShares: 1n, price: ORACLE_PRICE_SCALE },
+     *   { lltv: 50_0000000000000000n },
+     * );
+     * // variation satisfies bigint | null | undefined
+     * ```
      */
     // biome-ignore lint/complexity/useMaxParams: TODO refactor to ≤2 params
     function getPriceVariationToLiquidationPrice(position, market, marketParams) {
@@ -297,6 +566,25 @@ export var MarketUtils;
      * Returns the health factor of a given borrow position (scaled by WAD).
      * If the debt is 0, health factor is `MaxUint256`.
      * Returns `undefined` iff the market's price is undefined.
+     *
+     * @param position.collateral - The collateral amount in the position.
+     * @param position.borrowShares - The borrow shares in the position.
+     * @param market.totalBorrowAssets - The market's total borrowed assets.
+     * @param market.totalBorrowShares - The market's total borrow shares.
+     * @param market.price - The oracle price, scaled by `ORACLE_PRICE_SCALE`.
+     * @param marketParams.lltv - The market liquidation loan-to-value, scaled by WAD.
+     * @returns The WAD-scaled health factor, or `undefined` when price is unavailable.
+     * @example
+     * ```ts
+     * import { MarketUtils, ORACLE_PRICE_SCALE } from "@morpho-org/blue-sdk";
+     *
+     * const healthFactor = MarketUtils.getHealthFactor(
+     *   { collateral: 2n, borrowShares: 1n },
+     *   { totalBorrowAssets: 1n, totalBorrowShares: 1n, price: ORACLE_PRICE_SCALE },
+     *   { lltv: 50_0000000000000000n },
+     * );
+     * // healthFactor satisfies bigint | undefined
+     * ```
      */
     // biome-ignore lint/complexity/useMaxParams: TODO refactor to ≤2 params
     function getHealthFactor({ collateral, borrowShares, }, market, marketParams) {
@@ -313,6 +601,23 @@ export var MarketUtils;
      * Returns the loan-to-value ratio of a given borrow position (scaled by WAD).
      * Returns `undefined` iff the market's price is undefined.
      * Returns null if the position is not a borrow.
+     *
+     * @param position.collateral - The collateral amount in the position.
+     * @param position.borrowShares - The borrow shares in the position.
+     * @param market.totalBorrowAssets - The market's total borrowed assets.
+     * @param market.totalBorrowShares - The market's total borrow shares.
+     * @param market.price - The oracle price, scaled by `ORACLE_PRICE_SCALE`.
+     * @returns The WAD-scaled loan-to-value ratio, `undefined`, or `null` when the position has no borrow.
+     * @example
+     * ```ts
+     * import { MarketUtils, ORACLE_PRICE_SCALE } from "@morpho-org/blue-sdk";
+     *
+     * const ltv = MarketUtils.getLtv(
+     *   { collateral: 2n, borrowShares: 1n },
+     *   { totalBorrowAssets: 1n, totalBorrowShares: 1n, price: ORACLE_PRICE_SCALE },
+     * );
+     * // ltv satisfies bigint | null | undefined
+     * ```
      */
     function getLtv({ collateral, borrowShares, }, market) {
         borrowShares = BigInt(borrowShares);
@@ -330,34 +635,124 @@ export var MarketUtils;
     /**
      * Returns the usage ratio of the maximum borrow capacity given a certain borrow position (scaled by WAD).
      * Returns `undefined` iff the market's price is undefined.
+     *
+     * @param position - The borrow position to evaluate.
+     * @param market - The market state used to value the position.
+     * @param marketParams - The market params containing LLTV.
+     * @returns The WAD-scaled borrow capacity usage, or `undefined` when price is unavailable.
+     * @example
+     * ```ts
+     * import { MarketUtils, ORACLE_PRICE_SCALE } from "@morpho-org/blue-sdk";
+     *
+     * const usage = MarketUtils.getBorrowCapacityUsage(
+     *   { collateral: 2n, borrowShares: 1n },
+     *   { totalBorrowAssets: 1n, totalBorrowShares: 1n, price: ORACLE_PRICE_SCALE },
+     *   { lltv: 50_0000000000000000n },
+     * );
+     * // usage satisfies bigint | undefined
+     * ```
      */
     // biome-ignore lint/complexity/useMaxParams: TODO refactor to ≤2 params
     function getBorrowCapacityUsage(position, market, marketParams) {
         const hf = getHealthFactor(position, market, marketParams);
         if (hf === undefined)
             return;
-        if (hf === null)
-            return 0n;
         if (hf === 0n)
             return MathLib.MAX_UINT_256;
         return MathLib.wDivUp(MathLib.WAD, hf);
     }
     MarketUtils.getBorrowCapacityUsage = getBorrowCapacityUsage;
+    /**
+     * Converts market supply shares to loan assets.
+     *
+     * @param shares - The supply shares to convert.
+     * @param market.totalSupplyAssets - The market's total supplied assets.
+     * @param market.totalSupplyShares - The market's total supply shares.
+     * @param rounding - Optional rounding direction. Defaults to `"Down"`.
+     * @returns The equivalent amount of supplied loan assets.
+     * @example
+     * ```ts
+     * import { MarketUtils } from "@morpho-org/blue-sdk";
+     *
+     * const assets = MarketUtils.toSupplyAssets(100n, {
+     *   totalSupplyAssets: 1_000n,
+     *   totalSupplyShares: 100n,
+     * });
+     * // assets satisfies bigint
+     * ```
+     */
     // biome-ignore lint/complexity/useMaxParams: TODO refactor to ≤2 params
     function toSupplyAssets(shares, market, rounding = "Down") {
         return SharesMath.toAssets(shares, market.totalSupplyAssets, market.totalSupplyShares, rounding);
     }
     MarketUtils.toSupplyAssets = toSupplyAssets;
+    /**
+     * Converts market supply assets to supply shares.
+     *
+     * @param assets - The supplied loan assets to convert.
+     * @param market.totalSupplyAssets - The market's total supplied assets.
+     * @param market.totalSupplyShares - The market's total supply shares.
+     * @param rounding - Optional rounding direction. Defaults to `"Up"`.
+     * @returns The equivalent amount of supply shares.
+     * @example
+     * ```ts
+     * import { MarketUtils } from "@morpho-org/blue-sdk";
+     *
+     * const shares = MarketUtils.toSupplyShares(100n, {
+     *   totalSupplyAssets: 1_000n,
+     *   totalSupplyShares: 100n,
+     * });
+     * // shares satisfies bigint
+     * ```
+     */
     // biome-ignore lint/complexity/useMaxParams: TODO refactor to ≤2 params
     function toSupplyShares(assets, market, rounding = "Up") {
         return SharesMath.toShares(assets, market.totalSupplyAssets, market.totalSupplyShares, rounding);
     }
     MarketUtils.toSupplyShares = toSupplyShares;
+    /**
+     * Converts market borrow shares to loan assets.
+     *
+     * @param shares - The borrow shares to convert.
+     * @param market.totalBorrowAssets - The market's total borrowed assets.
+     * @param market.totalBorrowShares - The market's total borrow shares.
+     * @param rounding - Optional rounding direction. Defaults to `"Up"`.
+     * @returns The equivalent amount of borrowed loan assets.
+     * @example
+     * ```ts
+     * import { MarketUtils } from "@morpho-org/blue-sdk";
+     *
+     * const assets = MarketUtils.toBorrowAssets(100n, {
+     *   totalBorrowAssets: 1_000n,
+     *   totalBorrowShares: 100n,
+     * });
+     * // assets satisfies bigint
+     * ```
+     */
     // biome-ignore lint/complexity/useMaxParams: TODO refactor to ≤2 params
     function toBorrowAssets(shares, market, rounding = "Up") {
         return SharesMath.toAssets(shares, market.totalBorrowAssets, market.totalBorrowShares, rounding);
     }
     MarketUtils.toBorrowAssets = toBorrowAssets;
+    /**
+     * Converts market borrow assets to borrow shares.
+     *
+     * @param assets - The borrowed loan assets to convert.
+     * @param market.totalBorrowAssets - The market's total borrowed assets.
+     * @param market.totalBorrowShares - The market's total borrow shares.
+     * @param rounding - Optional rounding direction. Defaults to `"Down"`.
+     * @returns The equivalent amount of borrow shares.
+     * @example
+     * ```ts
+     * import { MarketUtils } from "@morpho-org/blue-sdk";
+     *
+     * const shares = MarketUtils.toBorrowShares(100n, {
+     *   totalBorrowAssets: 1_000n,
+     *   totalBorrowShares: 100n,
+     * });
+     * // shares satisfies bigint
+     * ```
+     */
     // biome-ignore lint/complexity/useMaxParams: TODO refactor to ≤2 params
     function toBorrowShares(assets, market, rounding = "Down") {
         return SharesMath.toShares(assets, market.totalBorrowAssets, market.totalBorrowShares, rounding);

package/lib/esm/math/AdaptiveCurveIrmLib.d.ts

@@ -3,11 +3,17 @@ import type { BigIntish } from "../types.js";
  * JS implementation of {@link https://github.com/morpho-org/morpho-blue-irm/blob/main/src/libraries/adaptive-curve/ExpLib.sol ExpLib} used by the Adaptive Curve IRM.
  */
 export declare namespace AdaptiveCurveIrmLib {
+    /** Curve steepness constant, scaled by WAD. */
     const CURVE_STEEPNESS = 4000000000000000000n;
+    /** Target utilization for the Adaptive Curve IRM, scaled by WAD. */
     const TARGET_UTILIZATION = 900000000000000000n;
+    /** Initial per-second rate at target utilization, scaled by WAD. */
     const INITIAL_RATE_AT_TARGET: bigint;
+    /** Per-second speed used to adjust the rate at target utilization. */
     const ADJUSTMENT_SPEED: bigint;
+    /** Minimum per-second rate at target utilization, scaled by WAD. */
     const MIN_RATE_AT_TARGET: bigint;
+    /** Maximum per-second rate at target utilization, scaled by WAD. */
     const MAX_RATE_AT_TARGET: bigint;
     /**
      * ln(2), scaled by WAD.
@@ -28,13 +34,57 @@ export declare namespace AdaptiveCurveIrmLib {
     const WEXP_UPPER_VALUE = 57716089161558943949701069502944508345128422502756744429568n;
     /**
      * Returns an approximation of exp(x) used by the Adaptive Curve IRM.
-     * @param x
+     * @param x - The WAD-scaled exponent.
+     * @returns The WAD-scaled exponential approximation.
+     * @example
+     * ```ts
+     * import { AdaptiveCurveIrmLib } from "@morpho-org/blue-sdk";
+     *
+     * const value = AdaptiveCurveIrmLib.wExp(0n);
+     * // value === 1000000000000000000n
+     * ```
      */
     function wExp(x: BigIntish): bigint;
+    /**
+     * Computes Adaptive Curve IRM borrow rates from utilization and elapsed time.
+     *
+     * @param startUtilization - The market utilization at the start of the period, scaled by WAD.
+     * @param startRateAtTarget - The rate at target utilization at the start of the period, scaled by WAD.
+     * @param elapsed - The elapsed time in seconds.
+     * @returns The average borrow rate, end borrow rate, and end rate at target, all scaled by WAD.
+     * @example
+     * ```ts
+     * import { AdaptiveCurveIrmLib } from "@morpho-org/blue-sdk";
+     *
+     * const rates = AdaptiveCurveIrmLib.getBorrowRate(
+     *   AdaptiveCurveIrmLib.TARGET_UTILIZATION,
+     *   AdaptiveCurveIrmLib.INITIAL_RATE_AT_TARGET,
+     *   12n,
+     * );
+     * // rates satisfies { avgBorrowRate: bigint; endBorrowRate: bigint; endRateAtTarget: bigint }
+     * ```
+     */
     function getBorrowRate(startUtilization: BigIntish, startRateAtTarget: BigIntish, elapsed: BigIntish): {
         avgBorrowRate: bigint;
         endBorrowRate: bigint;
         endRateAtTarget: bigint;
     };
+    /**
+     * Finds the utilization corresponding to a borrow rate and rate at target.
+     *
+     * @param borrowRate - The borrow rate to invert, scaled by WAD.
+     * @param rateAtTarget - The rate at target utilization, scaled by WAD.
+     * @returns The utilization corresponding to `borrowRate`, scaled by WAD.
+     * @example
+     * ```ts
+     * import { AdaptiveCurveIrmLib } from "@morpho-org/blue-sdk";
+     *
+     * const utilization = AdaptiveCurveIrmLib.getUtilizationAtBorrowRate(
+     *   AdaptiveCurveIrmLib.INITIAL_RATE_AT_TARGET,
+     *   AdaptiveCurveIrmLib.INITIAL_RATE_AT_TARGET,
+     * );
+     * // utilization === AdaptiveCurveIrmLib.TARGET_UTILIZATION
+     * ```
+     */
     function getUtilizationAtBorrowRate(borrowRate: BigIntish, rateAtTarget: BigIntish): bigint;
 }