@morpho-org/blue-sdk 6.0.1 → 6.1.0

package/lib/esm/position/Position.d.ts

@@ -1,5 +1,6 @@
 import { type IMarket, Market, type MaxBorrowOptions, type MaxPositionCapacities, type MaxWithdrawCollateralOptions } from "../market/index.js";
 import type { Address, BigIntish, MarketId } from "../types.js";
+/** Plain input shape for a user's Morpho Blue market position. */
 export interface IPosition {
     user: Address;
     marketId: MarketId;
@@ -7,6 +8,7 @@ export interface IPosition {
     borrowShares: bigint;
     collateral: bigint;
 }
+/** Represents a user's supply, borrow, and collateral balances on one market. */
 export declare class Position implements IPosition {
     /**
      * The user holding this position.
@@ -30,8 +32,10 @@ export declare class Position implements IPosition {
     collateral: bigint;
     constructor({ user, marketId, supplyShares, borrowShares, collateral, }: IPosition);
 }
+/** Plain input shape for a position paired with market state for accrual math. */
 export interface IAccrualPosition extends Omit<IPosition, "marketId"> {
 }
+/** Represents a position paired with market state for derived and accrued values. */
 export declare class AccrualPosition extends Position implements IAccrualPosition {
     protected readonly _market: Market;
     constructor(position: IAccrualPosition, market: IMarket);

package/lib/esm/position/Position.js

@@ -2,6 +2,7 @@ import { BlueErrors } from "../errors.js";
 import { Market, } from "../market/index.js";
 import { MathLib } from "../math/MathLib.js";
 import { CapacityLimitReason } from "../utils.js";
+/** Represents a user's supply, borrow, and collateral balances on one market. */
 export class Position {
     /**
      * The user holding this position.
@@ -31,6 +32,7 @@ export class Position {
         this.collateral = collateral;
     }
 }
+/** Represents a position paired with market state for derived and accrued values. */
 export class AccrualPosition extends Position {
     _market;
     constructor(position, market) {

package/lib/esm/position/PreLiquidationPosition.d.ts

@@ -2,6 +2,7 @@ import type { Address } from "viem";
 import { type IMarket, Market } from "../market/index.js";
 import type { BigIntish } from "../types.js";
 import { AccrualPosition, type IAccrualPosition } from "./Position.js";
+/** Plain input shape for PreLiquidation contract parameters. */
 export interface IPreLiquidationParams {
     preLltv: BigIntish;
     preLCF1: BigIntish;
@@ -10,6 +11,7 @@ export interface IPreLiquidationParams {
     preLIF2: BigIntish;
     preLiquidationOracle: Address;
 }
+/** Represents PreLiquidation contract parameters and factor interpolation helpers. */
 export declare class PreLiquidationParams implements IPreLiquidationParams {
     readonly preLltv: bigint;
     readonly preLCF1: bigint;
@@ -21,6 +23,7 @@ export declare class PreLiquidationParams implements IPreLiquidationParams {
     getCloseFactor(quotient: BigIntish): bigint;
     getIncentiveFactor(quotient: BigIntish): bigint;
 }
+/** Plain input shape for a position associated with a PreLiquidation contract. */
 export interface IPreLiquidationPosition extends IAccrualPosition {
     /**
      * The pre-liquidation parameters of the associated PreLiquidation contract.
@@ -36,6 +39,7 @@ export interface IPreLiquidationPosition extends IAccrualPosition {
      */
     preLiquidationOraclePrice?: BigIntish;
 }
+/** Represents a position evaluated under PreLiquidation-specific risk parameters. */
 export declare class PreLiquidationPosition extends AccrualPosition implements IPreLiquidationPosition {
     readonly preLiquidationParams: PreLiquidationParams;
     readonly preLiquidation: `0x${string}`;

package/lib/esm/position/PreLiquidationPosition.js

@@ -2,6 +2,7 @@ import { ORACLE_PRICE_SCALE } from "../constants.js";
 import { Market } from "../market/index.js";
 import { MathLib, SharesMath } from "../math/index.js";
 import { AccrualPosition } from "./Position.js";
+/** Represents PreLiquidation contract parameters and factor interpolation helpers. */
 export class PreLiquidationParams {
     preLltv;
     preLCF1;
@@ -24,6 +25,7 @@ export class PreLiquidationParams {
         return (this.preLIF1 + MathLib.wMulDown(quotient, this.preLIF2 - this.preLIF1));
     }
 }
+/** Represents a position evaluated under PreLiquidation-specific risk parameters. */
 export class PreLiquidationPosition extends AccrualPosition {
     preLiquidationParams;
     preLiquidation;

package/lib/esm/preLiquidation.d.ts

@@ -1,4 +1,5 @@
 import type { BigIntish } from "./types.js";
+/** Default PreLiquidation parameter registry keyed by Morpho Blue LLTV. */
 export declare const defaultPreLiquidationParamsRegistry: Map<bigint, {
     preLltv: bigint;
     preLCF1: bigint;
@@ -6,6 +7,21 @@ export declare const defaultPreLiquidationParamsRegistry: Map<bigint, {
     preLIF1: bigint;
     preLIF2: bigint;
 }>;
+/**
+ * Returns default PreLiquidation params for a supported Morpho Blue LLTV.
+ *
+ * @param lltv - The Morpho Blue liquidation loan-to-value, scaled by WAD.
+ * @returns The default PreLiquidation parameter set for `lltv`.
+ * @throws {UnsupportedPreLiquidationParamsError} when no default parameters exist for `lltv`.
+ * @example
+ * ```ts
+ * import { getDefaultPreLiquidationParams } from "@morpho-org/blue-sdk";
+ * import { parseEther } from "viem";
+ *
+ * const params = getDefaultPreLiquidationParams(parseEther("0.86"));
+ * // params satisfies { preLltv: bigint; preLCF1: bigint; preLCF2: bigint; preLIF1: bigint; preLIF2: bigint }
+ * ```
+ */
 export declare const getDefaultPreLiquidationParams: (lltv: BigIntish) => {
     preLltv: bigint;
     preLCF1: bigint;

package/lib/esm/preLiquidation.js

@@ -1,5 +1,6 @@
 import { parseEther } from "viem";
 import { UnsupportedPreLiquidationParamsError } from "./errors.js";
+/** Default PreLiquidation parameter registry keyed by Morpho Blue LLTV. */
 export const defaultPreLiquidationParamsRegistry = new Map([
     [
         parseEther("0.385"),
@@ -82,6 +83,21 @@ export const defaultPreLiquidationParamsRegistry = new Map([
         },
     ],
 ]);
+/**
+ * Returns default PreLiquidation params for a supported Morpho Blue LLTV.
+ *
+ * @param lltv - The Morpho Blue liquidation loan-to-value, scaled by WAD.
+ * @returns The default PreLiquidation parameter set for `lltv`.
+ * @throws {UnsupportedPreLiquidationParamsError} when no default parameters exist for `lltv`.
+ * @example
+ * ```ts
+ * import { getDefaultPreLiquidationParams } from "@morpho-org/blue-sdk";
+ * import { parseEther } from "viem";
+ *
+ * const params = getDefaultPreLiquidationParams(parseEther("0.86"));
+ * // params satisfies { preLltv: bigint; preLCF1: bigint; preLCF2: bigint; preLIF1: bigint; preLIF2: bigint }
+ * ```
+ */
 export const getDefaultPreLiquidationParams = (lltv) => {
     // biome-ignore lint/style/noParameterAssign: TODO refactor to avoid mutating parameter
     lltv = BigInt(lltv);

package/lib/esm/token/ConstantWrappedToken.d.ts

@@ -2,6 +2,7 @@ import { type RoundingDirection } from "../math/index.js";
 import type { Address, BigIntish } from "../types.js";
 import type { IToken } from "./Token.js";
 import { WrappedToken } from "./WrappedToken.js";
+/** Represents a wrapped token with a constant decimals-based conversion rate. */
 export declare class ConstantWrappedToken extends WrappedToken {
     readonly underlyingDecimals: bigint;
     constructor(token: IToken, underlying: Address, underlyingDecimals?: BigIntish);

package/lib/esm/token/ConstantWrappedToken.js

@@ -1,5 +1,6 @@
 import { MathLib } from "../math/index.js";
 import { WrappedToken } from "./WrappedToken.js";
+/** Represents a wrapped token with a constant decimals-based conversion rate. */
 export class ConstantWrappedToken extends WrappedToken {
     underlyingDecimals;
     // biome-ignore lint/complexity/useMaxParams: TODO refactor to ≤2 params

package/lib/esm/token/Eip5267Domain.d.ts

@@ -1,6 +1,9 @@
 import type { Address } from "../types.js";
+/** Ordered EIP-712 domain fields exposed by EIP-5267. */
 export declare const EIP_712_FIELDS: readonly ["name", "version", "chainId", "verifyingContract", "salt"];
+/** EIP-712 domain field name exposed by EIP-5267. */
 export type Eip712Field = (typeof EIP_712_FIELDS)[number];
+/** Plain input shape for an EIP-5267 signing domain. */
 export interface IEip5267Domain {
     fields: `0x${string}`;
     name: string;
@@ -10,6 +13,7 @@ export interface IEip5267Domain {
     salt: `0x${string}`;
     extensions: readonly bigint[];
 }
+/** Represents an EIP-5267 signing domain and derived EIP-712 domain object. */
 export declare class Eip5267Domain implements IEip5267Domain {
     /**
      * A bit map where bit i is set to 1 if and only if domain field i is present (0 ≤ i ≤ 4).

package/lib/esm/token/Eip5267Domain.js

@@ -1,3 +1,4 @@
+/** Ordered EIP-712 domain fields exposed by EIP-5267. */
 export const EIP_712_FIELDS = [
     "name",
     "version",
@@ -5,6 +6,7 @@ export const EIP_712_FIELDS = [
     "verifyingContract",
     "salt",
 ];
+/** Represents an EIP-5267 signing domain and derived EIP-712 domain object. */
 export class Eip5267Domain {
     /**
      * A bit map where bit i is set to 1 if and only if domain field i is present (0 ≤ i ≤ 4).

package/lib/esm/token/ExchangeRateWrappedToken.d.ts

@@ -2,6 +2,7 @@ import { type RoundingDirection } from "../math/index.js";
 import type { Address } from "../types.js";
 import type { IToken } from "./Token.js";
 import { WrappedToken } from "./WrappedToken.js";
+/** Represents a wrapped token whose conversion uses a WAD-scaled exchange rate. */
 export declare class ExchangeRateWrappedToken extends WrappedToken {
     readonly underlying: Address;
     wrappedTokenExchangeRate: bigint;

package/lib/esm/token/ExchangeRateWrappedToken.js

@@ -1,5 +1,6 @@
 import { MathLib } from "../math/index.js";
 import { WrappedToken } from "./WrappedToken.js";
+/** Represents a wrapped token whose conversion uses a WAD-scaled exchange rate. */
 export class ExchangeRateWrappedToken extends WrappedToken {
     underlying;
     wrappedTokenExchangeRate;

package/lib/esm/token/Token.d.ts

@@ -2,6 +2,7 @@ import { type ChainId } from "../chain.js";
 import { type RoundingDirection } from "../math/index.js";
 import type { Address, BigIntish } from "../types.js";
 import type { Eip5267Domain } from "./Eip5267Domain.js";
+/** Plain input shape for an ERC-20-like token. */
 export interface IToken {
     address: Address;
     name?: string;
@@ -10,6 +11,7 @@ export interface IToken {
     price?: BigIntish;
     eip5267Domain?: Eip5267Domain;
 }
+/** Represents an ERC-20-like token and optional price/signing metadata. */
 export declare class Token implements IToken {
     static native(chainId: ChainId): Token;
     /**

package/lib/esm/token/Token.js

@@ -1,6 +1,7 @@
 import { NATIVE_ADDRESS } from "../addresses.js";
 import { ChainUtils } from "../chain.js";
 import { MathLib } from "../math/index.js";
+/** Represents an ERC-20-like token and optional price/signing metadata. */
 export class Token {
     static native(chainId) {
         const currency = ChainUtils.CHAIN_METADATA[chainId].nativeCurrency;

package/lib/esm/token/VaultToken.d.ts

@@ -2,10 +2,12 @@ import type { RoundingDirection } from "../math/index.js";
 import type { Address, BigIntish } from "../types.js";
 import type { IVaultConfig } from "../vault/VaultConfig.js";
 import { WrappedToken } from "./WrappedToken.js";
+/** Plain input shape for ERC-4626-like vault token totals. */
 export interface IVaultToken {
     totalAssets: bigint;
     totalSupply: bigint;
 }
+/** Represents an ERC-4626-like vault token with share and asset conversion math. */
 export declare class VaultToken extends WrappedToken implements IVaultToken {
     readonly asset: Address;
     readonly decimalsOffset: bigint;

package/lib/esm/token/VaultToken.js

@@ -1,5 +1,6 @@
 import { VaultUtils } from "../vault/VaultUtils.js";
 import { WrappedToken } from "./WrappedToken.js";
+/** Represents an ERC-4626-like vault token with share and asset conversion math. */
 export class VaultToken extends WrappedToken {
     asset;
     decimalsOffset;

package/lib/esm/token/WrappedToken.d.ts

@@ -1,6 +1,7 @@
 import { type RoundingDirection } from "../math/index.js";
 import type { Address } from "../types.js";
 import { type IToken, Token } from "./Token.js";
+/** Base class for tokens that wrap and unwrap another token. */
 export declare abstract class WrappedToken extends Token {
     readonly underlying: Address;
     constructor(token: IToken, underlying: Address);

package/lib/esm/token/WrappedToken.js

@@ -1,5 +1,6 @@
 import { MathLib } from "../math/index.js";
 import { Token } from "./Token.js";
+/** Base class for tokens that wrap and unwrap another token. */
 export class WrappedToken extends Token {
     underlying;
     constructor(token, underlying) {

package/lib/esm/types.d.ts

@@ -8,6 +8,7 @@ export type Address = `0x${string}`;
 export type MarketId = `0x${string}` & {
     __TYPE__: "marketId";
 };
+/** Primitive values accepted at SDK boundaries and normalized to `bigint`. */
 export type BigIntish = bigint | string | number | boolean;
 /**
  * The possible transaction type on the Blue contract
@@ -20,7 +21,23 @@ export declare enum TransactionType {
     Borrow = "Borrow",
     Repay = "Repay"
 }
+/** Value that may not have been loaded yet. */
 export type Loadable<T> = T | undefined;
+/** Value that may fail to resolve. */
 export type Failable<T> = T | null;
+/** Value that may be unloaded or fail to resolve. */
 export type Fetchable<T> = Failable<Loadable<T>>;
+/**
+ * Checks whether a value is a 32-byte Morpho Blue market id.
+ *
+ * @param value - The unknown value to inspect.
+ * @returns `true` when `value` is a `0x`-prefixed 32-byte hex string.
+ * @example
+ * ```ts
+ * import { isMarketId } from "@morpho-org/blue-sdk";
+ *
+ * const valid = isMarketId("0x0000000000000000000000000000000000000000000000000000000000000000");
+ * // valid satisfies boolean
+ * ```
+ */
 export declare const isMarketId: (value: unknown) => value is MarketId;

package/lib/esm/types.js

@@ -10,4 +10,17 @@ export var TransactionType;
     TransactionType["Borrow"] = "Borrow";
     TransactionType["Repay"] = "Repay";
 })(TransactionType || (TransactionType = {}));
+/**
+ * Checks whether a value is a 32-byte Morpho Blue market id.
+ *
+ * @param value - The unknown value to inspect.
+ * @returns `true` when `value` is a `0x`-prefixed 32-byte hex string.
+ * @example
+ * ```ts
+ * import { isMarketId } from "@morpho-org/blue-sdk";
+ *
+ * const valid = isMarketId("0x0000000000000000000000000000000000000000000000000000000000000000");
+ * // valid satisfies boolean
+ * ```
+ */
 export const isMarketId = (value) => typeof value === "string" && /^0x[0-9A-Fa-f]{64}$/.test(value);

package/lib/esm/user/User.d.ts

@@ -1,4 +1,5 @@
 import type { Address } from "../types.js";
+/** Represents a Morpho Blue user authorization and nonce state. */
 export declare class User {
     /**
      * The user's address.

package/lib/esm/user/User.js

@@ -1,3 +1,4 @@
+/** Represents a Morpho Blue user authorization and nonce state. */
 export class User {
     /**
      * The user's address.

package/lib/esm/utils.d.ts

@@ -1,3 +1,4 @@
+/** Reason why a capacity calculation is capped. */
 export declare enum CapacityLimitReason {
     liquidity = "Liquidity",
     balance = "Balance",
@@ -7,6 +8,7 @@ export declare enum CapacityLimitReason {
     vaultV2_absoluteCap = "VaultV2_AbsoluteCap",
     vaultV2_relativeCap = "VaultV2_RelativeCap"
 }
+/** Bounded capacity value and the reason for the bound. */
 export interface CapacityLimit {
     value: bigint;
     limiter: CapacityLimitReason;

package/lib/esm/utils.js

@@ -1,3 +1,4 @@
+/** Reason why a capacity calculation is capped. */
 export var CapacityLimitReason;
 (function (CapacityLimitReason) {
     CapacityLimitReason["liquidity"] = "Liquidity";

package/lib/esm/vault/Vault.d.ts

@@ -4,10 +4,12 @@ import type { Address, BigIntish, MarketId } from "../types.js";
 import { type CapacityLimit } from "../utils.js";
 import type { IVaultConfig } from "./VaultConfig.js";
 import { type IVaultMarketAllocation, VaultMarketAllocation } from "./VaultMarketAllocation.js";
+/** Pending governance value and the timestamp at which it becomes valid. */
 export interface Pending<T> {
     value: T;
     validAt: bigint;
 }
+/** PublicAllocator configuration attached to a MetaMorpho vault. */
 export interface VaultPublicAllocatorConfig {
     /**
      * The PublicAllocator's admin address.
@@ -22,6 +24,7 @@ export interface VaultPublicAllocatorConfig {
      */
     accruedFee: bigint;
 }
+/** Plain input shape for a MetaMorpho vault. */
 export interface IVault extends IVaultConfig {
     curator: Address;
     owner: Address;
@@ -41,6 +44,7 @@ export interface IVault extends IVaultConfig {
     lostAssets?: bigint;
     publicAllocatorConfig?: VaultPublicAllocatorConfig;
 }
+/** Represents a MetaMorpho vault and its governance, queue, and accounting state. */
 export declare class Vault extends VaultToken implements IVault {
     /**
      * The vault's share token's name.
@@ -119,6 +123,7 @@ export declare class Vault extends VaultToken implements IVault {
     toAssets(shares: BigIntish, rounding?: RoundingDirection): bigint;
     toShares(assets: BigIntish, rounding?: RoundingDirection): bigint;
 }
+/** Aggregated vault allocation exposure for one collateral asset. */
 export interface CollateralAllocation {
     address: Address;
     lltvs: Set<bigint>;
@@ -126,8 +131,10 @@ export interface CollateralAllocation {
     markets: Set<MarketId>;
     proportion: bigint;
 }
+/** Plain input shape for a MetaMorpho vault paired with accrued market allocations. */
 export interface IAccrualVault extends Omit<IVault, "withdrawQueue" | "totalAssets"> {
 }
+/** Represents a MetaMorpho vault with accrued market allocation state. */
 export declare class AccrualVault extends Vault implements IAccrualVault {
     /**
      * @inheritdoc

package/lib/esm/vault/Vault.js

@@ -4,6 +4,7 @@ import { MathLib } from "../math/index.js";
 import { VaultToken } from "../token/index.js";
 import { CapacityLimitReason } from "../utils.js";
 import { VaultMarketAllocation, } from "./VaultMarketAllocation.js";
+/** Represents a MetaMorpho vault and its governance, queue, and accounting state. */
 export class Vault extends VaultToken {
     /**
      * The MetaMorpho vault's owner address.
@@ -100,6 +101,7 @@ export class Vault extends VaultToken {
         return this._wrap(assets, rounding);
     }
 }
+/** Represents a MetaMorpho vault with accrued market allocation state. */
 export class AccrualVault extends Vault {
     /**
      * The allocation of the vault on each market enabled.

package/lib/esm/vault/VaultConfig.d.ts

@@ -1,9 +1,11 @@
 import { type IToken, Token } from "../token/Token.js";
 import type { Address, BigIntish } from "../types.js";
+/** Plain input shape for immutable MetaMorpho vault token configuration. */
 export interface IVaultConfig extends Omit<IToken, "decimals"> {
     decimalsOffset: BigIntish;
     asset: Address;
 }
+/** Represents immutable MetaMorpho vault token configuration. */
 export declare class VaultConfig extends Token implements IVaultConfig {
     readonly decimalsOffset: bigint;
     readonly asset: `0x${string}`;

package/lib/esm/vault/VaultConfig.js

@@ -1,4 +1,5 @@
 import { Token } from "../token/Token.js";
+/** Represents immutable MetaMorpho vault token configuration. */
 export class VaultConfig extends Token {
     decimalsOffset;
     asset;

package/lib/esm/vault/VaultMarketAllocation.d.ts

@@ -1,9 +1,11 @@
 import type { AccrualPosition } from "../position/index.js";
 import { type IVaultMarketConfig, VaultMarketConfig } from "./VaultMarketConfig.js";
+/** Plain input shape for a vault allocation on one Morpho Blue market. */
 export interface IVaultMarketAllocation {
     config: IVaultMarketConfig;
     position: AccrualPosition;
 }
+/** Represents a vault allocation on one Morpho Blue market. */
 export declare class VaultMarketAllocation implements IVaultMarketAllocation {
     /**
      * The vault's configuration on the corresponding market.

package/lib/esm/vault/VaultMarketAllocation.js

@@ -1,5 +1,6 @@
 import { MathLib } from "../math/index.js";
 import { VaultMarketConfig, } from "./VaultMarketConfig.js";
+/** Represents a vault allocation on one Morpho Blue market. */
 export class VaultMarketAllocation {
     /**
      * The vault's configuration on the corresponding market.

package/lib/esm/vault/VaultMarketConfig.d.ts

@@ -1,6 +1,7 @@
 import type { Address, MarketId } from "../types.js";
 import type { Pending } from "./Vault.js";
 import type { VaultMarketPublicAllocatorConfig } from "./VaultMarketPublicAllocatorConfig.js";
+/** Plain input shape for a vault's configuration on one Morpho Blue market. */
 export interface IVaultMarketConfig {
     vault: Address;
     marketId: MarketId;
@@ -10,6 +11,7 @@ export interface IVaultMarketConfig {
     enabled: boolean;
     publicAllocatorConfig?: VaultMarketPublicAllocatorConfig;
 }
+/** Represents a vault's configuration on one Morpho Blue market. */
 export declare class VaultMarketConfig implements IVaultMarketConfig {
     /**
      * The vault's address.

package/lib/esm/vault/VaultMarketConfig.js

@@ -1,3 +1,4 @@
+/** Represents a vault's configuration on one Morpho Blue market. */
 export class VaultMarketConfig {
     /**
      * The vault's address.

package/lib/esm/vault/VaultMarketPublicAllocatorConfig.d.ts

@@ -8,6 +8,7 @@ export interface IVaultMarketPublicAllocatorConfig {
     maxIn: bigint;
     maxOut: bigint;
 }
+/** Represents a vault market's PublicAllocator limits. */
 export declare class VaultMarketPublicAllocatorConfig implements IVaultMarketPublicAllocatorConfig {
     /**
      * The vault's address.

package/lib/esm/vault/VaultMarketPublicAllocatorConfig.js

@@ -1,3 +1,4 @@
+/** Represents a vault market's PublicAllocator limits. */
 export class VaultMarketPublicAllocatorConfig {
     /**
      * The vault's address.

package/lib/esm/vault/VaultUser.d.ts

@@ -1,10 +1,12 @@
 import type { Address } from "../types.js";
+/** Plain input shape for a user's MetaMorpho vault state. */
 export interface IVaultUser {
     vault: Address;
     user: Address;
     isAllocator: boolean;
     allowance: bigint;
 }
+/** Represents a user's MetaMorpho vault allocator and allowance state. */
 export declare class VaultUser implements IVaultUser {
     /**
      * The vault's address.

package/lib/esm/vault/VaultUser.js

@@ -1,3 +1,4 @@
+/** Represents a user's MetaMorpho vault allocator and allowance state. */
 export class VaultUser {
     /**
      * The vault's address.

package/lib/esm/vault/VaultUtils.d.ts

@@ -1,13 +1,62 @@
 import { type RoundingDirection } from "../math/index.js";
 import type { BigIntish } from "../types.js";
+/** ERC-4626 virtual share and asset conversion helpers for MetaMorpho vaults. */
 export declare namespace VaultUtils {
+    /** Virtual assets added to ERC-4626 total assets in conversion formulas. */
     const VIRTUAL_ASSETS = 1n;
+    /**
+     * Returns the decimals offset between 18-decimal vault shares and an asset.
+     *
+     * @param decimals - The asset decimals.
+     * @returns The non-negative decimals offset.
+     * @example
+     * ```ts
+     * import { VaultUtils } from "@morpho-org/blue-sdk";
+     *
+     * const offset = VaultUtils.decimalsOffset(6n);
+     * // offset === 12n
+     * ```
+     */
     function decimalsOffset(decimals: BigIntish): bigint;
+    /**
+     * Converts vault shares to underlying assets.
+     *
+     * @param shares - The amount of vault shares.
+     * @param vault.totalAssets - The vault's total assets.
+     * @param vault.totalSupply - The vault's total share supply.
+     * @param vault.decimalsOffset - The vault's decimals offset.
+     * @param rounding - Optional rounding direction. Defaults to `"Down"`.
+     * @returns The equivalent amount of underlying assets.
+     * @example
+     * ```ts
+     * import { VaultUtils } from "@morpho-org/blue-sdk";
+     *
+     * const assets = VaultUtils.toAssets(100n, { totalAssets: 1_000n, totalSupply: 100n, decimalsOffset: 0n });
+     * // assets satisfies bigint
+     * ```
+     */
     function toAssets(shares: BigIntish, { totalAssets, totalSupply, decimalsOffset, }: {
         totalAssets: BigIntish;
         totalSupply: BigIntish;
         decimalsOffset: BigIntish;
     }, rounding?: RoundingDirection): bigint;
+    /**
+     * Converts underlying assets to vault shares.
+     *
+     * @param assets - The amount of underlying assets.
+     * @param vault.totalAssets - The vault's total assets.
+     * @param vault.totalSupply - The vault's total share supply.
+     * @param vault.decimalsOffset - The vault's decimals offset.
+     * @param rounding - Optional rounding direction. Defaults to `"Up"`.
+     * @returns The equivalent amount of vault shares.
+     * @example
+     * ```ts
+     * import { VaultUtils } from "@morpho-org/blue-sdk";
+     *
+     * const shares = VaultUtils.toShares(100n, { totalAssets: 1_000n, totalSupply: 100n, decimalsOffset: 0n });
+     * // shares satisfies bigint
+     * ```
+     */
     function toShares(assets: BigIntish, { totalAssets, totalSupply, decimalsOffset, }: {
         totalAssets: BigIntish;
         totalSupply: BigIntish;