@morpho-org/blue-sdk 6.0.1 → 6.1.0

package/lib/cjs/math/AdaptiveCurveIrmLib.js

@@ -8,11 +8,17 @@ const MathLib_js_1 = require("./MathLib.js");
  */
 var AdaptiveCurveIrmLib;
 (function (AdaptiveCurveIrmLib) {
+    /** Curve steepness constant, scaled by WAD. */
     AdaptiveCurveIrmLib.CURVE_STEEPNESS = 4000000000000000000n;
+    /** Target utilization for the Adaptive Curve IRM, scaled by WAD. */
     AdaptiveCurveIrmLib.TARGET_UTILIZATION = 900000000000000000n;
+    /** Initial per-second rate at target utilization, scaled by WAD. */
     AdaptiveCurveIrmLib.INITIAL_RATE_AT_TARGET = 40000000000000000n / constants_js_1.SECONDS_PER_YEAR;
+    /** Per-second speed used to adjust the rate at target utilization. */
     AdaptiveCurveIrmLib.ADJUSTMENT_SPEED = 50000000000000000000n / constants_js_1.SECONDS_PER_YEAR;
+    /** Minimum per-second rate at target utilization, scaled by WAD. */
     AdaptiveCurveIrmLib.MIN_RATE_AT_TARGET = 1000000000000000n / constants_js_1.SECONDS_PER_YEAR;
+    /** Maximum per-second rate at target utilization, scaled by WAD. */
     AdaptiveCurveIrmLib.MAX_RATE_AT_TARGET = 2000000000000000000n / constants_js_1.SECONDS_PER_YEAR;
     /**
      * ln(2), scaled by WAD.
@@ -33,7 +39,15 @@ var AdaptiveCurveIrmLib;
     AdaptiveCurveIrmLib.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) {
         // biome-ignore lint/style/noParameterAssign: TODO refactor to avoid mutating parameter
@@ -57,6 +71,25 @@ var AdaptiveCurveIrmLib;
         return expR >> -q;
     }
     AdaptiveCurveIrmLib.wExp = wExp;
+    /**
+     * 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 }
+     * ```
+     */
     // biome-ignore lint/complexity/useMaxParams: TODO refactor to ≤2 params
     function getBorrowRate(startUtilization, startRateAtTarget, elapsed) {
         // biome-ignore lint/style/noParameterAssign: TODO refactor to avoid mutating parameter
@@ -124,6 +157,23 @@ var AdaptiveCurveIrmLib;
         };
     }
     AdaptiveCurveIrmLib.getBorrowRate = getBorrowRate;
+    /**
+     * 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, rateAtTarget) {
         // biome-ignore lint/style/noParameterAssign: TODO refactor to avoid mutating parameter
         borrowRate = BigInt(borrowRate);

package/lib/cjs/math/MathLib.d.ts

@@ -1,74 +1,174 @@
 import type { BigIntish } from "../types.js";
+/** Rounding direction used by fixed-point math helpers. */
 export type RoundingDirection = "Up" | "Down";
 /**
  * Library to manage fixed-point arithmetic.
  * https://github.com/morpho-org/morpho-blue/blob/main/src/libraries/MathLib.sol
  */
 export declare namespace MathLib {
+    /** WAD scale used for 18-decimal fixed-point values. */
     const WAD = 1000000000000000000n;
+    /** RAY scale used for 27-decimal fixed-point values. */
     const RAY = 1000000000000000000000000000n;
+    /** Maximum unsigned integer representable with 256 bits. */
     const MAX_UINT_256: bigint;
+    /** Maximum unsigned integer representable with 160 bits. */
     const MAX_UINT_160: bigint;
+    /** Maximum unsigned integer representable with 128 bits. */
     const MAX_UINT_128: bigint;
+    /** Maximum unsigned integer representable with 48 bits. */
     const MAX_UINT_48: bigint;
+    /**
+     * Returns the maximum unsigned integer representable with a bit width.
+     *
+     * @param nBits - The bit width, which must be divisible by 4.
+     * @returns The maximum unsigned integer representable by `nBits`.
+     * @example
+     * ```ts
+     * import { MathLib } from "@morpho-org/blue-sdk";
+     *
+     * const max = MathLib.maxUint(8);
+     * // max === 255n
+     * ```
+     */
     function maxUint(nBits: number): bigint;
     /**
      * Returns the absolute value of a number
      * @param a The number
+     * @returns The absolute value as a bigint.
+     * @example
+     * ```ts
+     * import { MathLib } from "@morpho-org/blue-sdk";
+     *
+     * const value = MathLib.abs(-2n);
+     * // value === 2n
+     * ```
      */
     function abs(a: BigIntish): bigint;
     /**
      * Returns the smallest number given as param
-     * @param x The first number
-     * @param y The second number
+     * @param xs The numbers to compare.
+     * @returns The smallest value as a bigint.
+     * @example
+     * ```ts
+     * import { MathLib } from "@morpho-org/blue-sdk";
+     *
+     * const value = MathLib.min(2n, 1n, 3n);
+     * // value === 1n
+     * ```
      */
     function min(...xs: BigIntish[]): bigint;
     /**
      * Returns the greatest number given as param
-     * @param x The first number
-     * @param y The second number
+     * @param xs The numbers to compare.
+     * @returns The greatest value as a bigint.
+     * @example
+     * ```ts
+     * import { MathLib } from "@morpho-org/blue-sdk";
+     *
+     * const value = MathLib.max(2n, 1n, 3n);
+     * // value === 3n
+     * ```
      */
     function max(...xs: BigIntish[]): bigint;
     /**
      * Returns the subtraction of b from a, floored to zero if negative
      * @param x The first number
      * @param y The second number
+     * @returns `x - y`, floored to `0n`.
+     * @example
+     * ```ts
+     * import { MathLib } from "@morpho-org/blue-sdk";
+     *
+     * const value = MathLib.zeroFloorSub(1n, 2n);
+     * // value === 0n
+     * ```
      */
     function zeroFloorSub(x: BigIntish, y: BigIntish): bigint;
     /**
      * Perform the WAD-based multiplication of 2 numbers, rounded down
      * @param x The first number
      * @param y The second number
+     * @returns The WAD-scaled product rounded down.
+     * @example
+     * ```ts
+     * import { MathLib } from "@morpho-org/blue-sdk";
+     *
+     * const value = MathLib.wMulDown(MathLib.WAD, 2n * MathLib.WAD);
+     * // value === 2n * MathLib.WAD
+     * ```
      */
     function wMulDown(x: BigIntish, y: BigIntish): bigint;
     /**
      * Perform the WAD-based multiplication of 2 numbers, rounded up
      * @param x The first number
      * @param y The second number
+     * @returns The WAD-scaled product rounded up.
+     * @example
+     * ```ts
+     * import { MathLib } from "@morpho-org/blue-sdk";
+     *
+     * const value = MathLib.wMulUp(1n, MathLib.WAD);
+     * // value === 1n
+     * ```
      */
     function wMulUp(x: BigIntish, y: BigIntish): bigint;
     /**
      * Perform the WAD-based multiplication of 2 numbers with a provided rounding direction
      * @param x The first number
      * @param y The second number
+     * @param rounding The rounding direction.
+     * @returns The WAD-scaled product rounded as requested.
+     * @example
+     * ```ts
+     * import { MathLib } from "@morpho-org/blue-sdk";
+     *
+     * const value = MathLib.wMul(MathLib.WAD, MathLib.WAD, "Down");
+     * // value === MathLib.WAD
+     * ```
      */
     function wMul(x: BigIntish, y: BigIntish, rounding: RoundingDirection): bigint;
     /**
      * Perform the WAD-based division of 2 numbers, rounded down
      * @param x The first number
      * @param y The second number
+     * @returns The WAD-scaled quotient rounded down.
+     * @example
+     * ```ts
+     * import { MathLib } from "@morpho-org/blue-sdk";
+     *
+     * const value = MathLib.wDivDown(MathLib.WAD, 2n * MathLib.WAD);
+     * // value === 500000000000000000n
+     * ```
      */
     function wDivDown(x: BigIntish, y: BigIntish): bigint;
     /**
      * Perform the WAD-based multiplication of 2 numbers, rounded up
      * @param x The first number
      * @param y The second number
+     * @returns The WAD-scaled quotient rounded up.
+     * @example
+     * ```ts
+     * import { MathLib } from "@morpho-org/blue-sdk";
+     *
+     * const value = MathLib.wDivUp(MathLib.WAD, 2n * MathLib.WAD);
+     * // value === 500000000000000000n
+     * ```
      */
     function wDivUp(x: BigIntish, y: BigIntish): bigint;
     /**
      * Perform the WAD-based multiplication of 2 numbers with a provided rounding direction
      * @param x The first number
      * @param y The second number
+     * @param rounding The rounding direction.
+     * @returns The WAD-scaled quotient rounded as requested.
+     * @example
+     * ```ts
+     * import { MathLib } from "@morpho-org/blue-sdk";
+     *
+     * const value = MathLib.wDiv(MathLib.WAD, MathLib.WAD, "Down");
+     * // value === MathLib.WAD
+     * ```
      */
     function wDiv(x: BigIntish, y: BigIntish, rounding: RoundingDirection): bigint;
     /**
@@ -76,6 +176,14 @@ export declare namespace MathLib {
      * @param x The first number
      * @param y The second number
      * @param denominator The denominator
+     * @returns `x * y / denominator`, rounded down.
+     * @example
+     * ```ts
+     * import { MathLib } from "@morpho-org/blue-sdk";
+     *
+     * const value = MathLib.mulDivDown(5n, 2n, 3n);
+     * // value === 3n
+     * ```
      */
     function mulDivDown(x: BigIntish, y: BigIntish, denominator: BigIntish): bigint;
     /**
@@ -83,8 +191,32 @@ export declare namespace MathLib {
      * @param x The first number
      * @param y The second number
      * @param denominator The denominator
+     * @returns `x * y / denominator`, rounded up.
+     * @example
+     * ```ts
+     * import { MathLib } from "@morpho-org/blue-sdk";
+     *
+     * const value = MathLib.mulDivUp(5n, 2n, 3n);
+     * // value === 4n
+     * ```
      */
     function mulDivUp(x: BigIntish, y: BigIntish, denominator: BigIntish): bigint;
+    /**
+     * Multiplies two numbers and divides by a denominator.
+     *
+     * @param x - The first number.
+     * @param y - The second number.
+     * @param denominator - The denominator.
+     * @param rounding - The rounding direction.
+     * @returns `x * y / denominator`, rounded as requested.
+     * @example
+     * ```ts
+     * import { MathLib } from "@morpho-org/blue-sdk";
+     *
+     * const value = MathLib.mulDiv(5n, 2n, 3n, "Down");
+     * // value === 3n
+     * ```
+     */
     function mulDiv(x: BigIntish, y: BigIntish, denominator: BigIntish, rounding: RoundingDirection): bigint;
     /**
      * The sum of the first three non-zero terms of a Taylor expansion of e^(nx) - 1,
@@ -92,11 +224,27 @@ export declare namespace MathLib {
      *
      * @param x The base of the exponent
      * @param n The exponent
+     * @returns The WAD-scaled compounded rate approximation.
+     * @example
+     * ```ts
+     * import { MathLib } from "@morpho-org/blue-sdk";
+     *
+     * const compounded = MathLib.wTaylorCompounded(1n, 1n);
+     * // compounded satisfies bigint
+     * ```
      */
     function wTaylorCompounded(x: BigIntish, n: BigIntish): bigint;
     /**
      * Converts a WAD-based quantity to a RAY-based quantity.
      * @param x The WAD-based quantity.
+     * @returns The same quantity scaled to RAY precision.
+     * @example
+     * ```ts
+     * import { MathLib } from "@morpho-org/blue-sdk";
+     *
+     * const ray = MathLib.wToRay(MathLib.WAD);
+     * // ray === MathLib.RAY
+     * ```
      */
     function wToRay(x: BigIntish): bigint;
 }

package/lib/cjs/math/MathLib.js

@@ -7,12 +7,31 @@ exports.MathLib = void 0;
  */
 var MathLib;
 (function (MathLib) {
+    /** WAD scale used for 18-decimal fixed-point values. */
     MathLib.WAD = 1000000000000000000n;
+    /** RAY scale used for 27-decimal fixed-point values. */
     MathLib.RAY = 1000000000000000000000000000n;
+    /** Maximum unsigned integer representable with 256 bits. */
     MathLib.MAX_UINT_256 = maxUint(256);
+    /** Maximum unsigned integer representable with 160 bits. */
     MathLib.MAX_UINT_160 = maxUint(160);
+    /** Maximum unsigned integer representable with 128 bits. */
     MathLib.MAX_UINT_128 = maxUint(128);
+    /** Maximum unsigned integer representable with 48 bits. */
     MathLib.MAX_UINT_48 = maxUint(48);
+    /**
+     * Returns the maximum unsigned integer representable with a bit width.
+     *
+     * @param nBits - The bit width, which must be divisible by 4.
+     * @returns The maximum unsigned integer representable by `nBits`.
+     * @example
+     * ```ts
+     * import { MathLib } from "@morpho-org/blue-sdk";
+     *
+     * const max = MathLib.maxUint(8);
+     * // max === 255n
+     * ```
+     */
     function maxUint(nBits) {
         if (nBits % 4 !== 0)
             throw new Error(`Invalid number of bits: ${nBits}`);
@@ -22,6 +41,14 @@ var MathLib;
     /**
      * Returns the absolute value of a number
      * @param a The number
+     * @returns The absolute value as a bigint.
+     * @example
+     * ```ts
+     * import { MathLib } from "@morpho-org/blue-sdk";
+     *
+     * const value = MathLib.abs(-2n);
+     * // value === 2n
+     * ```
      */
     function abs(a) {
         // biome-ignore lint/style/noParameterAssign: TODO refactor to avoid mutating parameter
@@ -31,8 +58,15 @@ var MathLib;
     MathLib.abs = abs;
     /**
      * Returns the smallest number given as param
-     * @param x The first number
-     * @param y The second number
+     * @param xs The numbers to compare.
+     * @returns The smallest value as a bigint.
+     * @example
+     * ```ts
+     * import { MathLib } from "@morpho-org/blue-sdk";
+     *
+     * const value = MathLib.min(2n, 1n, 3n);
+     * // value === 1n
+     * ```
      */
     function min(...xs) {
         return xs.map(BigInt).reduce((x, y) => (x <= y ? x : y));
@@ -40,8 +74,15 @@ var MathLib;
     MathLib.min = min;
     /**
      * Returns the greatest number given as param
-     * @param x The first number
-     * @param y The second number
+     * @param xs The numbers to compare.
+     * @returns The greatest value as a bigint.
+     * @example
+     * ```ts
+     * import { MathLib } from "@morpho-org/blue-sdk";
+     *
+     * const value = MathLib.max(2n, 1n, 3n);
+     * // value === 3n
+     * ```
      */
     function max(...xs) {
         return xs.map(BigInt).reduce((x, y) => (x <= y ? y : x));
@@ -51,6 +92,14 @@ var MathLib;
      * Returns the subtraction of b from a, floored to zero if negative
      * @param x The first number
      * @param y The second number
+     * @returns `x - y`, floored to `0n`.
+     * @example
+     * ```ts
+     * import { MathLib } from "@morpho-org/blue-sdk";
+     *
+     * const value = MathLib.zeroFloorSub(1n, 2n);
+     * // value === 0n
+     * ```
      */
     function zeroFloorSub(x, y) {
         // biome-ignore lint/style/noParameterAssign: TODO refactor to avoid mutating parameter
@@ -64,6 +113,14 @@ var MathLib;
      * Perform the WAD-based multiplication of 2 numbers, rounded down
      * @param x The first number
      * @param y The second number
+     * @returns The WAD-scaled product rounded down.
+     * @example
+     * ```ts
+     * import { MathLib } from "@morpho-org/blue-sdk";
+     *
+     * const value = MathLib.wMulDown(MathLib.WAD, 2n * MathLib.WAD);
+     * // value === 2n * MathLib.WAD
+     * ```
      */
     function wMulDown(x, y) {
         return MathLib.wMul(x, y, "Down");
@@ -73,6 +130,14 @@ var MathLib;
      * Perform the WAD-based multiplication of 2 numbers, rounded up
      * @param x The first number
      * @param y The second number
+     * @returns The WAD-scaled product rounded up.
+     * @example
+     * ```ts
+     * import { MathLib } from "@morpho-org/blue-sdk";
+     *
+     * const value = MathLib.wMulUp(1n, MathLib.WAD);
+     * // value === 1n
+     * ```
      */
     function wMulUp(x, y) {
         return MathLib.wMul(x, y, "Up");
@@ -82,6 +147,15 @@ var MathLib;
      * Perform the WAD-based multiplication of 2 numbers with a provided rounding direction
      * @param x The first number
      * @param y The second number
+     * @param rounding The rounding direction.
+     * @returns The WAD-scaled product rounded as requested.
+     * @example
+     * ```ts
+     * import { MathLib } from "@morpho-org/blue-sdk";
+     *
+     * const value = MathLib.wMul(MathLib.WAD, MathLib.WAD, "Down");
+     * // value === MathLib.WAD
+     * ```
      */
     // biome-ignore lint/complexity/useMaxParams: TODO refactor to ≤2 params
     function wMul(x, y, rounding) {
@@ -92,6 +166,14 @@ var MathLib;
      * Perform the WAD-based division of 2 numbers, rounded down
      * @param x The first number
      * @param y The second number
+     * @returns The WAD-scaled quotient rounded down.
+     * @example
+     * ```ts
+     * import { MathLib } from "@morpho-org/blue-sdk";
+     *
+     * const value = MathLib.wDivDown(MathLib.WAD, 2n * MathLib.WAD);
+     * // value === 500000000000000000n
+     * ```
      */
     function wDivDown(x, y) {
         return MathLib.wDiv(x, y, "Down");
@@ -101,6 +183,14 @@ var MathLib;
      * Perform the WAD-based multiplication of 2 numbers, rounded up
      * @param x The first number
      * @param y The second number
+     * @returns The WAD-scaled quotient rounded up.
+     * @example
+     * ```ts
+     * import { MathLib } from "@morpho-org/blue-sdk";
+     *
+     * const value = MathLib.wDivUp(MathLib.WAD, 2n * MathLib.WAD);
+     * // value === 500000000000000000n
+     * ```
      */
     function wDivUp(x, y) {
         return MathLib.wDiv(x, y, "Up");
@@ -110,6 +200,15 @@ var MathLib;
      * Perform the WAD-based multiplication of 2 numbers with a provided rounding direction
      * @param x The first number
      * @param y The second number
+     * @param rounding The rounding direction.
+     * @returns The WAD-scaled quotient rounded as requested.
+     * @example
+     * ```ts
+     * import { MathLib } from "@morpho-org/blue-sdk";
+     *
+     * const value = MathLib.wDiv(MathLib.WAD, MathLib.WAD, "Down");
+     * // value === MathLib.WAD
+     * ```
      */
     // biome-ignore lint/complexity/useMaxParams: TODO refactor to ≤2 params
     function wDiv(x, y, rounding) {
@@ -121,6 +220,14 @@ var MathLib;
      * @param x The first number
      * @param y The second number
      * @param denominator The denominator
+     * @returns `x * y / denominator`, rounded down.
+     * @example
+     * ```ts
+     * import { MathLib } from "@morpho-org/blue-sdk";
+     *
+     * const value = MathLib.mulDivDown(5n, 2n, 3n);
+     * // value === 3n
+     * ```
      */
     // biome-ignore lint/complexity/useMaxParams: TODO refactor to ≤2 params
     function mulDivDown(x, y, denominator) {
@@ -140,6 +247,14 @@ var MathLib;
      * @param x The first number
      * @param y The second number
      * @param denominator The denominator
+     * @returns `x * y / denominator`, rounded up.
+     * @example
+     * ```ts
+     * import { MathLib } from "@morpho-org/blue-sdk";
+     *
+     * const value = MathLib.mulDivUp(5n, 2n, 3n);
+     * // value === 4n
+     * ```
      */
     // biome-ignore lint/complexity/useMaxParams: TODO refactor to ≤2 params
     function mulDivUp(x, y, denominator) {
@@ -155,6 +270,22 @@ var MathLib;
         return (x * y) / denominator + roundup;
     }
     MathLib.mulDivUp = mulDivUp;
+    /**
+     * Multiplies two numbers and divides by a denominator.
+     *
+     * @param x - The first number.
+     * @param y - The second number.
+     * @param denominator - The denominator.
+     * @param rounding - The rounding direction.
+     * @returns `x * y / denominator`, rounded as requested.
+     * @example
+     * ```ts
+     * import { MathLib } from "@morpho-org/blue-sdk";
+     *
+     * const value = MathLib.mulDiv(5n, 2n, 3n, "Down");
+     * // value === 3n
+     * ```
+     */
     // biome-ignore lint/complexity/useMaxParams: TODO refactor to ≤2 params
     function mulDiv(x, y, denominator, rounding) {
         return MathLib[`mulDiv${rounding}`](x, y, denominator);
@@ -166,6 +297,14 @@ var MathLib;
      *
      * @param x The base of the exponent
      * @param n The exponent
+     * @returns The WAD-scaled compounded rate approximation.
+     * @example
+     * ```ts
+     * import { MathLib } from "@morpho-org/blue-sdk";
+     *
+     * const compounded = MathLib.wTaylorCompounded(1n, 1n);
+     * // compounded satisfies bigint
+     * ```
      */
     function wTaylorCompounded(x, n) {
         const firstTerm = BigInt(x) * BigInt(n);
@@ -177,6 +316,14 @@ var MathLib;
     /**
      * Converts a WAD-based quantity to a RAY-based quantity.
      * @param x The WAD-based quantity.
+     * @returns The same quantity scaled to RAY precision.
+     * @example
+     * ```ts
+     * import { MathLib } from "@morpho-org/blue-sdk";
+     *
+     * const ray = MathLib.wToRay(MathLib.WAD);
+     * // ray === MathLib.RAY
+     * ```
      */
     function wToRay(x) {
         return BigInt(x) * 1000000000n;

package/lib/cjs/math/SharesMath.d.ts

@@ -5,8 +5,42 @@ import { type RoundingDirection } from "./MathLib.js";
  * & MetaMorpho (via {@link https://github.com/OpenZeppelin/openzeppelin-contracts/blob/master/contracts/token/ERC20/extensions/ERC4626.sol ERC4626}).
  */
 export declare namespace SharesMath {
+    /** Virtual shares added to Morpho Blue and ERC-4626 share conversions. */
     const VIRTUAL_SHARES = 1000000n;
+    /** Virtual assets added to Morpho Blue and ERC-4626 asset conversions. */
     const VIRTUAL_ASSETS = 1n;
+    /**
+     * Converts shares to assets using Morpho virtual shares and assets.
+     *
+     * @param shares - The amount of shares.
+     * @param totalAssets - The total assets before conversion.
+     * @param totalShares - The total shares before conversion.
+     * @param rounding - The rounding direction.
+     * @returns The equivalent amount of assets.
+     * @example
+     * ```ts
+     * import { SharesMath } from "@morpho-org/blue-sdk";
+     *
+     * const assets = SharesMath.toAssets(100n, 1_000n, 100n, "Down");
+     * // assets satisfies bigint
+     * ```
+     */
     function toAssets(shares: BigIntish, totalAssets: BigIntish, totalShares: BigIntish, rounding: RoundingDirection): bigint;
+    /**
+     * Converts assets to shares using Morpho virtual shares and assets.
+     *
+     * @param assets - The amount of assets.
+     * @param totalAssets - The total assets before conversion.
+     * @param totalShares - The total shares before conversion.
+     * @param rounding - The rounding direction.
+     * @returns The equivalent amount of shares.
+     * @example
+     * ```ts
+     * import { SharesMath } from "@morpho-org/blue-sdk";
+     *
+     * const shares = SharesMath.toShares(100n, 1_000n, 100n, "Up");
+     * // shares satisfies bigint
+     * ```
+     */
     function toShares(assets: BigIntish, totalAssets: BigIntish, totalShares: BigIntish, rounding: RoundingDirection): bigint;
 }

package/lib/cjs/math/SharesMath.js

@@ -8,13 +8,47 @@ const MathLib_js_1 = require("./MathLib.js");
  */
 var SharesMath;
 (function (SharesMath) {
+    /** Virtual shares added to Morpho Blue and ERC-4626 share conversions. */
     SharesMath.VIRTUAL_SHARES = 1000000n;
+    /** Virtual assets added to Morpho Blue and ERC-4626 asset conversions. */
     SharesMath.VIRTUAL_ASSETS = 1n;
+    /**
+     * Converts shares to assets using Morpho virtual shares and assets.
+     *
+     * @param shares - The amount of shares.
+     * @param totalAssets - The total assets before conversion.
+     * @param totalShares - The total shares before conversion.
+     * @param rounding - The rounding direction.
+     * @returns The equivalent amount of assets.
+     * @example
+     * ```ts
+     * import { SharesMath } from "@morpho-org/blue-sdk";
+     *
+     * const assets = SharesMath.toAssets(100n, 1_000n, 100n, "Down");
+     * // assets satisfies bigint
+     * ```
+     */
     // biome-ignore lint/complexity/useMaxParams: TODO refactor to ≤2 params
     function toAssets(shares, totalAssets, totalShares, rounding) {
         return MathLib_js_1.MathLib.mulDiv(shares, BigInt(totalAssets) + SharesMath.VIRTUAL_ASSETS, BigInt(totalShares) + SharesMath.VIRTUAL_SHARES, rounding);
     }
     SharesMath.toAssets = toAssets;
+    /**
+     * Converts assets to shares using Morpho virtual shares and assets.
+     *
+     * @param assets - The amount of assets.
+     * @param totalAssets - The total assets before conversion.
+     * @param totalShares - The total shares before conversion.
+     * @param rounding - The rounding direction.
+     * @returns The equivalent amount of shares.
+     * @example
+     * ```ts
+     * import { SharesMath } from "@morpho-org/blue-sdk";
+     *
+     * const shares = SharesMath.toShares(100n, 1_000n, 100n, "Up");
+     * // shares satisfies bigint
+     * ```
+     */
     // biome-ignore lint/complexity/useMaxParams: TODO refactor to ≤2 params
     function toShares(assets, totalAssets, totalShares, rounding) {
         return MathLib_js_1.MathLib.mulDiv(assets, BigInt(totalShares) + SharesMath.VIRTUAL_SHARES, BigInt(totalAssets) + SharesMath.VIRTUAL_ASSETS, rounding);