@morpho-org/blue-sdk 6.0.1 → 6.1.0

package/lib/cjs/market/MarketUtils.d.ts

@@ -8,11 +8,35 @@ export declare namespace 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: IMarketParams): MarketId;
     /**
      * 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 }: {
         lltv: BigIntish;
@@ -20,6 +44,17 @@ export declare namespace 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: BigIntish;
@@ -29,6 +64,14 @@ export declare namespace 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: BigIntish): number;
     /**
@@ -75,6 +118,17 @@ export declare namespace 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: {
         totalSupplyAssets: BigIntish;
@@ -84,6 +138,17 @@ export declare namespace 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, }: {
         totalSupplyAssets: BigIntish;
@@ -93,6 +158,17 @@ export declare namespace 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, }: {
         totalSupplyAssets: BigIntish;
@@ -102,17 +178,53 @@ export declare namespace 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, }: {
         totalSupplyAssets: BigIntish;
         totalBorrowAssets: BigIntish;
     }, utilization: BigIntish): bigint;
+    /**
+     * 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: BigIntish, { lltv }: {
         lltv: BigIntish;
     }): bigint;
     /**
      * 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: BigIntish, { price }: {
         price?: BigIntish;
@@ -121,6 +233,22 @@ export declare namespace 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
+     * ```
      */
     function getMaxBorrowAssets(collateral: BigIntish, market: {
         price?: BigIntish;
@@ -130,6 +258,25 @@ export declare namespace 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
+     * ```
      */
     function getMaxBorrowableAssets({ collateral, borrowShares, }: {
         collateral: BigIntish;
@@ -144,6 +291,24 @@ export declare namespace 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
+     * ```
      */
     function getLiquidationSeizedAssets(repaidShares: BigIntish, market: {
         totalBorrowAssets: BigIntish;
@@ -155,6 +320,24 @@ export declare namespace 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
+     * ```
      */
     function getLiquidationRepaidShares(seizedAssets: BigIntish, market: {
         totalBorrowAssets: BigIntish;
@@ -166,6 +349,25 @@ export declare namespace 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
+     * ```
      */
     function getSeizableCollateral(position: {
         collateral: BigIntish;
@@ -180,6 +382,25 @@ export declare namespace 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
+     * ```
      */
     function getWithdrawableCollateral({ collateral, borrowShares, }: {
         collateral: BigIntish;
@@ -195,6 +416,20 @@ export declare namespace 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
+     * ```
      */
     function isHealthy({ collateral, borrowShares, }: {
         collateral: BigIntish;
@@ -210,6 +445,24 @@ export declare namespace 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
+     * ```
      */
     function getLiquidationPrice({ collateral, borrowShares, }: {
         collateral: BigIntish;
@@ -225,6 +478,22 @@ export declare namespace 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
+     * ```
      */
     function getPriceVariationToLiquidationPrice(position: {
         collateral: BigIntish;
@@ -240,6 +509,25 @@ export declare namespace 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
+     * ```
      */
     function getHealthFactor({ collateral, borrowShares, }: {
         collateral: BigIntish;
@@ -255,6 +543,23 @@ export declare namespace 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, }: {
         collateral: BigIntish;
@@ -267,6 +572,22 @@ export declare namespace 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
+     * ```
      */
     function getBorrowCapacityUsage(position: {
         collateral: BigIntish;
@@ -278,18 +599,94 @@ export declare namespace MarketUtils {
     }, marketParams: {
         lltv: BigIntish;
     }): bigint | undefined;
+    /**
+     * 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
+     * ```
+     */
     function toSupplyAssets(shares: BigIntish, market: {
         totalSupplyAssets: BigIntish;
         totalSupplyShares: BigIntish;
     }, rounding?: RoundingDirection): bigint;
+    /**
+     * 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
+     * ```
+     */
     function toSupplyShares(assets: BigIntish, market: {
         totalSupplyAssets: BigIntish;
         totalSupplyShares: BigIntish;
     }, rounding?: RoundingDirection): bigint;
+    /**
+     * 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
+     * ```
+     */
     function toBorrowAssets(shares: BigIntish, market: {
         totalBorrowAssets: BigIntish;
         totalBorrowShares: BigIntish;
     }, rounding?: RoundingDirection): bigint;
+    /**
+     * 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
+     * ```
+     */
     function toBorrowShares(assets: BigIntish, market: {
         totalBorrowAssets: BigIntish;
         totalBorrowShares: BigIntish;