@signals-protocol/v1-sdk 1.0.0

package/dist/utils/math.d.ts

@@ -0,0 +1,185 @@
+import Big from "big.js";
+import { WADAmount, USDCAmount } from "../types";
+/** WAD format constant: 1e18 */
+export declare const WAD: Big.Big;
+/** Scale difference between USDC (6 decimals) and WAD (18 decimals): 1e12 */
+export declare const SCALE_DIFF: Big.Big;
+export declare const HALF_SCALE_DIFF: Big.Big;
+/** USDC precision constant: 1e6 */
+export declare const USDC_PRECISION: Big.Big;
+/** Maximum safe input for exp() function: 133.084... * 1e18 (PRBMath limit) */
+export declare const MAX_EXP_INPUT_WAD: Big.Big;
+/** Maximum number of chunks per transaction */
+export declare const MAX_CHUNKS_PER_TX = 100;
+/** Minimum and maximum factor bounds for segment tree operations */
+export declare const MIN_FACTOR: Big.Big;
+export declare const MAX_FACTOR: Big.Big;
+export declare const HALF_WAD: Big.Big;
+export declare const LN_MAX_FACTOR_WAD: Big.Big;
+export declare const MAX_UINT256: bigint;
+export declare function toBigInt(value: Big, label?: string): bigint;
+export declare function fromBigInt(value: bigint): Big;
+/**
+ * Convert 6-decimal USDC amount to 18-decimal WAD format
+ * @param amt6 Amount in 6-decimal format
+ * @returns Amount in WAD format
+ */
+export declare function toWad(amt6: USDCAmount): WADAmount;
+/**
+ * Convert 18-decimal WAD format to 6-decimal USDC amount (truncates)
+ * @param amtWad Amount in WAD format
+ * @returns Amount in 6-decimal format
+ */
+export declare function fromWad(amtWad: WADAmount): USDCAmount;
+/**
+ * Convert 18-decimal WAD format to 6-decimal USDC amount with round-up
+ * Always rounds up to ensure minimum 1 micro unit cost
+ * @param amtWad Amount in WAD format
+ * @returns Amount in 6-decimal format (rounded up)
+ */
+export declare function fromWadRoundUp(amtWad: WADAmount): USDCAmount;
+/**
+ * Convert 18-decimal WAD format to 6-decimal USDC amount with nearest rounding (ties up)
+ * @param amtWad Amount in WAD format
+ * @returns Amount in 6-decimal format (rounded to nearest)
+ */
+export declare function fromWadNearest(amtWad: WADAmount): USDCAmount;
+/**
+ * Convert 18-decimal WAD format to 6-decimal USDC amount with nearest rounding
+ * but enforce minimum 1 micro unit when the input is non-zero.
+ * @param amtWad Amount in WAD format
+ * @returns Amount in 6-decimal format (rounded to nearest, minimum 1 if non-zero)
+ */
+export declare function fromWadNearestMin1(amtWad: WADAmount): USDCAmount;
+/**
+ * Convert WAD format to regular number (divide by 1e18)
+ * @param amtWad Amount in WAD format
+ * @returns Regular number
+ */
+export declare function wadToNumber(amtWad: WADAmount): Big;
+/**
+ * Format USDC amount to 6 decimal places maximum
+ * @param amount USDC amount (in micro USDC)
+ * @returns Formatted amount with max 6 decimals
+ */
+export declare function formatUSDC(amount: USDCAmount): USDCAmount;
+/**
+ * WAD multiplication: (a * b) / WAD
+ * @param a First operand
+ * @param b Second operand
+ * @returns Product in WAD format
+ */
+export declare function wMul(a: WADAmount, b: WADAmount): WADAmount;
+/**
+ * WAD multiplication with nearest rounding (ties up)
+ * Mirrors on-chain wMulNearest helper.
+ * @param a First operand
+ * @param b Second operand
+ * @returns Product in WAD format rounded to nearest
+ */
+export declare function wMulNearest(a: WADAmount, b: WADAmount): WADAmount;
+/**
+ * WAD division: (a * WAD) / b
+ * @param a Dividend
+ * @param b Divisor
+ * @returns Quotient in WAD format
+ */
+export declare function wDiv(a: WADAmount, b: WADAmount): WADAmount;
+/**
+ * WAD division with rounding up: ceil((a * WAD) / b)
+ * @param a Dividend
+ * @param b Divisor
+ * @returns Quotient in WAD format rounded up
+ */
+export declare function wDivUp(a: WADAmount, b: WADAmount): WADAmount;
+/**
+ * WAD exponentiation: e^x
+ * Uses Taylor series expansion for accurate results
+ * @param x Exponent in WAD format
+ * @returns e^x in WAD format
+ */
+export declare function wExp(x: WADAmount): WADAmount;
+/**
+ * WAD natural logarithm: ln(x)
+ * @param x Input in WAD format (must be >= 1.0)
+ * @returns ln(x) in WAD format
+ */
+export declare function wLn(x: WADAmount): WADAmount;
+/**
+ * WAD square root: √x
+ * @param x Input in WAD format
+ * @returns √x in WAD format
+ */
+export declare function wSqrt(x: WADAmount): WADAmount;
+/**
+ * Sum of exponentials: Σ exp(v_i)
+ * @param values Array of values in WAD format
+ * @returns Sum of exponentials in WAD format
+ */
+export declare function sumExp(values: WADAmount[]): WADAmount;
+/**
+ * Logarithm of sum of exponentials: ln(Σ exp(v_i))
+ * Uses numerical stability techniques (subtract max value)
+ * @param values Array of values in WAD format
+ * @returns ln(Σ exp(v_i)) in WAD format
+ */
+export declare function logSumExp(values: WADAmount[]): WADAmount;
+/**
+ * Calculate CLMSR price from exponential values
+ * Price = exp(q/α) / Σ exp(q_i/α)
+ * @param expValue Pre-computed exp(q/α) value for this tick
+ * @param totalSumExp Sum of all exponentials Σ exp(q/α)
+ * @returns Normalized price in WAD format
+ */
+export declare function clmsrPrice(expValue: WADAmount, totalSumExp: WADAmount): WADAmount;
+/**
+ * Calculate CLMSR cost: α * ln(Σ_after / Σ_before)
+ * @param alpha Liquidity parameter α in WAD format
+ * @param sumBefore Sum of exponentials before trade
+ * @param sumAfter Sum of exponentials after trade
+ * @returns Trade cost in WAD format (always positive)
+ */
+export declare function clmsrCost(alpha: WADAmount, sumBefore: WADAmount, sumAfter: WADAmount): WADAmount;
+/**
+ * Calculate CLMSR proceeds (for selling): α * ln(Σ_before / Σ_after)
+ * @param alpha Liquidity parameter α in WAD format
+ * @param sumBefore Sum of exponentials before sell
+ * @param sumAfter Sum of exponentials after sell
+ * @returns Trade proceeds in WAD format
+ */
+export declare function clmsrProceeds(alpha: WADAmount, sumBefore: WADAmount, sumAfter: WADAmount): WADAmount;
+/**
+ * Calculate exp(q/α) with contract-equivalent overflow guard
+ * Equivalent to contract's _safeExp function
+ * @param q Quantity in WAD format
+ * @param alpha Liquidity parameter in WAD format
+ * @returns Result of exp(q/α) in WAD format
+ */
+export declare function safeExp(q: WADAmount, alpha: WADAmount): WADAmount;
+export declare function maxSafeChunkQuantity(alpha: WADAmount): WADAmount;
+/**
+ * Check if a factor is within safe bounds for segment tree operations
+ * @param factor Factor to check
+ * @returns true if factor is within bounds
+ */
+export declare function isFactorSafe(factor: WADAmount): boolean;
+/**
+ * Create a new Big number from string, number, or Big
+ * @param value Input value
+ * @returns Big number
+ */
+export declare function toBig(value: string | number | Big): Big;
+/**
+ * Create WAD amount from numeric value (multiply by 1e18)
+ * Use this for converting regular numbers to WAD format
+ * @param value Input value in regular units (e.g., 1.5 USDC)
+ * @returns WAD amount (18 decimals)
+ */
+export declare function toWAD(value: string | number): WADAmount;
+/**
+ * Create micro-USDC amount from USDC value (multiply by 1e6)
+ * Use this for converting user input USDC amounts to SDK format
+ * @param value Input value in USDC (e.g., "100" = 100 USDC)
+ * @returns USDC amount in 6-decimal format (micro-USDC)
+ */
+export declare function toMicroUSDC(value: string | number): USDCAmount;

package/dist/utils/math.js

@@ -0,0 +1,427 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_UINT256 = exports.LN_MAX_FACTOR_WAD = exports.HALF_WAD = exports.MAX_FACTOR = exports.MIN_FACTOR = exports.MAX_CHUNKS_PER_TX = exports.MAX_EXP_INPUT_WAD = exports.USDC_PRECISION = exports.HALF_SCALE_DIFF = exports.SCALE_DIFF = exports.WAD = void 0;
+exports.toBigInt = toBigInt;
+exports.fromBigInt = fromBigInt;
+exports.toWad = toWad;
+exports.fromWad = fromWad;
+exports.fromWadRoundUp = fromWadRoundUp;
+exports.fromWadNearest = fromWadNearest;
+exports.fromWadNearestMin1 = fromWadNearestMin1;
+exports.wadToNumber = wadToNumber;
+exports.formatUSDC = formatUSDC;
+exports.wMul = wMul;
+exports.wMulNearest = wMulNearest;
+exports.wDiv = wDiv;
+exports.wDivUp = wDivUp;
+exports.wExp = wExp;
+exports.wLn = wLn;
+exports.wSqrt = wSqrt;
+exports.sumExp = sumExp;
+exports.logSumExp = logSumExp;
+exports.clmsrPrice = clmsrPrice;
+exports.clmsrCost = clmsrCost;
+exports.clmsrProceeds = clmsrProceeds;
+exports.safeExp = safeExp;
+exports.maxSafeChunkQuantity = maxSafeChunkQuantity;
+exports.isFactorSafe = isFactorSafe;
+exports.toBig = toBig;
+exports.toWAD = toWAD;
+exports.toMicroUSDC = toMicroUSDC;
+const big_js_1 = __importDefault(require("big.js"));
+const types_1 = require("../types");
+const prb_math_1 = require("./prb-math");
+// ============================================================================
+// CONSTANTS
+// ============================================================================
+/** WAD format constant: 1e18 */
+exports.WAD = new big_js_1.default("1e18");
+const WAD_BI = prb_math_1.UUNIT;
+/** Scale difference between USDC (6 decimals) and WAD (18 decimals): 1e12 */
+exports.SCALE_DIFF = new big_js_1.default("1e12");
+exports.HALF_SCALE_DIFF = exports.SCALE_DIFF.div(2);
+const SCALE_DIFF_BI = 1000000000000n;
+const HALF_SCALE_DIFF_BI = SCALE_DIFF_BI / 2n;
+/** USDC precision constant: 1e6 */
+exports.USDC_PRECISION = new big_js_1.default("1000000");
+/** Maximum safe input for exp() function: 133.084... * 1e18 (PRBMath limit) */
+exports.MAX_EXP_INPUT_WAD = new big_js_1.default(prb_math_1.UEXP_MAX_INPUT.toString());
+/** Maximum number of chunks per transaction */
+exports.MAX_CHUNKS_PER_TX = 100;
+/** Minimum and maximum factor bounds for segment tree operations */
+exports.MIN_FACTOR = new big_js_1.default("0.01e18"); // 1%
+exports.MAX_FACTOR = new big_js_1.default("100e18"); // 100x
+exports.HALF_WAD = exports.WAD.div(2);
+const HALF_WAD_BI = WAD_BI / 2n;
+exports.LN_MAX_FACTOR_WAD = new big_js_1.default("4605170185988091368"); // ln(100) * 1e18
+exports.MAX_UINT256 = prb_math_1.MAX_UINT256;
+// Big.js configuration for precision (optimized for performance)
+big_js_1.default.DP = 30; // 30 decimal places for internal calculations (sufficient for CLMSR precision)
+big_js_1.default.RM = big_js_1.default.roundHalfUp; // Round half up
+function toBigIntStrict(value, label) {
+    const rounded = value.round(0, big_js_1.default.roundDown);
+    if (!rounded.eq(value)) {
+        throw new types_1.CalculationError(`${label} must be an integer`);
+    }
+    return BigInt(rounded.toFixed(0, big_js_1.default.roundDown));
+}
+function toBigInt(value, label = "value") {
+    return toBigIntStrict(value, label);
+}
+function fromBigInt(value) {
+    return new big_js_1.default(value.toString());
+}
+// ============================================================================
+// SCALING FUNCTIONS
+// ============================================================================
+/**
+ * Convert 6-decimal USDC amount to 18-decimal WAD format
+ * @param amt6 Amount in 6-decimal format
+ * @returns Amount in WAD format
+ */
+function toWad(amt6) {
+    return amt6.mul(exports.SCALE_DIFF);
+}
+/**
+ * Convert 18-decimal WAD format to 6-decimal USDC amount (truncates)
+ * @param amtWad Amount in WAD format
+ * @returns Amount in 6-decimal format
+ */
+function fromWad(amtWad) {
+    if (amtWad.eq(0)) {
+        return new big_js_1.default(0);
+    }
+    const amtBI = toBigIntStrict(amtWad, "amtWad");
+    return fromBigInt(amtBI / SCALE_DIFF_BI);
+}
+/**
+ * Convert 18-decimal WAD format to 6-decimal USDC amount with round-up
+ * Always rounds up to ensure minimum 1 micro unit cost
+ * @param amtWad Amount in WAD format
+ * @returns Amount in 6-decimal format (rounded up)
+ */
+function fromWadRoundUp(amtWad) {
+    if (amtWad.eq(0)) {
+        return new big_js_1.default(0);
+    }
+    const amtBI = toBigIntStrict(amtWad, "amtWad");
+    const numerator = amtBI + SCALE_DIFF_BI - 1n;
+    return fromBigInt(numerator / SCALE_DIFF_BI);
+}
+/**
+ * Convert 18-decimal WAD format to 6-decimal USDC amount with nearest rounding (ties up)
+ * @param amtWad Amount in WAD format
+ * @returns Amount in 6-decimal format (rounded to nearest)
+ */
+function fromWadNearest(amtWad) {
+    if (amtWad.eq(0)) {
+        return new big_js_1.default(0);
+    }
+    const amtBI = toBigIntStrict(amtWad, "amtWad");
+    const shifted = amtBI + HALF_SCALE_DIFF_BI;
+    return fromBigInt(shifted / SCALE_DIFF_BI);
+}
+/**
+ * Convert 18-decimal WAD format to 6-decimal USDC amount with nearest rounding
+ * but enforce minimum 1 micro unit when the input is non-zero.
+ * @param amtWad Amount in WAD format
+ * @returns Amount in 6-decimal format (rounded to nearest, minimum 1 if non-zero)
+ */
+function fromWadNearestMin1(amtWad) {
+    if (amtWad.eq(0)) {
+        return new big_js_1.default(0);
+    }
+    const rounded = fromWadNearest(amtWad);
+    return rounded.eq(0) ? new big_js_1.default(1) : rounded;
+}
+/**
+ * Convert WAD format to regular number (divide by 1e18)
+ * @param amtWad Amount in WAD format
+ * @returns Regular number
+ */
+function wadToNumber(amtWad) {
+    return amtWad.div(exports.WAD);
+}
+/**
+ * Format USDC amount to 6 decimal places maximum
+ * @param amount USDC amount (in micro USDC)
+ * @returns Formatted amount with max 6 decimals
+ */
+function formatUSDC(amount) {
+    // amount는 이미 micro USDC 단위이므로 정수여야 함
+    return new big_js_1.default(amount.toFixed(0, big_js_1.default.roundDown));
+}
+// ============================================================================
+// BASIC MATH OPERATIONS
+// ============================================================================
+/**
+ * WAD multiplication: (a * b) / WAD
+ * @param a First operand
+ * @param b Second operand
+ * @returns Product in WAD format
+ */
+function wMul(a, b) {
+    const aBI = toBigIntStrict(a, "a");
+    const bBI = toBigIntStrict(b, "b");
+    return fromBigInt((aBI * bBI) / WAD_BI);
+}
+/**
+ * WAD multiplication with nearest rounding (ties up)
+ * Mirrors on-chain wMulNearest helper.
+ * @param a First operand
+ * @param b Second operand
+ * @returns Product in WAD format rounded to nearest
+ */
+function wMulNearest(a, b) {
+    if (a.eq(0) || b.eq(0)) {
+        return new big_js_1.default(0);
+    }
+    const aBI = toBigIntStrict(a, "a");
+    const bBI = toBigIntStrict(b, "b");
+    const product = aBI * bBI;
+    return fromBigInt((product + HALF_WAD_BI) / WAD_BI);
+}
+/**
+ * WAD division: (a * WAD) / b
+ * @param a Dividend
+ * @param b Divisor
+ * @returns Quotient in WAD format
+ */
+function wDiv(a, b) {
+    if (b.eq(0)) {
+        throw new types_1.ValidationError("Division by zero");
+    }
+    const aBI = toBigIntStrict(a, "a");
+    const bBI = toBigIntStrict(b, "b");
+    return fromBigInt((aBI * WAD_BI) / bBI);
+}
+/**
+ * WAD division with rounding up: ceil((a * WAD) / b)
+ * @param a Dividend
+ * @param b Divisor
+ * @returns Quotient in WAD format rounded up
+ */
+function wDivUp(a, b) {
+    if (b.eq(0)) {
+        throw new types_1.ValidationError("Division by zero");
+    }
+    const aBI = toBigIntStrict(a, "a");
+    const bBI = toBigIntStrict(b, "b");
+    const numerator = aBI * WAD_BI;
+    const quotient = numerator / bBI;
+    if (numerator % bBI === 0n) {
+        return fromBigInt(quotient);
+    }
+    return fromBigInt(quotient + 1n);
+}
+/**
+ * WAD exponentiation: e^x
+ * Uses Taylor series expansion for accurate results
+ * @param x Exponent in WAD format
+ * @returns e^x in WAD format
+ */
+function wExp(x) {
+    if (x.lt(0)) {
+        throw new types_1.ValidationError("Exponent must be non-negative");
+    }
+    const xBI = toBigIntStrict(x, "x");
+    if (xBI > prb_math_1.UEXP_MAX_INPUT) {
+        throw new types_1.ValidationError(`Exponent too large: ${x.toString()}, max: ${exports.MAX_EXP_INPUT_WAD.toString()}`);
+    }
+    return fromBigInt((0, prb_math_1.expWad)(xBI));
+}
+/**
+ * WAD natural logarithm: ln(x)
+ * @param x Input in WAD format (must be >= 1.0)
+ * @returns ln(x) in WAD format
+ */
+function wLn(x) {
+    const xBI = toBigIntStrict(x, "x");
+    if (xBI < WAD_BI) {
+        throw new types_1.ValidationError("Logarithm input must be >= 1.0 (WAD)");
+    }
+    return fromBigInt((0, prb_math_1.lnWad)(xBI));
+}
+/**
+ * WAD square root: √x
+ * @param x Input in WAD format
+ * @returns √x in WAD format
+ */
+function wSqrt(x) {
+    if (x.lt(0)) {
+        throw new types_1.ValidationError("Square root input must be non-negative");
+    }
+    // Use Big.js sqrt method
+    const xScaled = x.div(exports.WAD);
+    const result = xScaled.sqrt();
+    return result.mul(exports.WAD);
+}
+// ============================================================================
+// AGGREGATION FUNCTIONS
+// ============================================================================
+/**
+ * Sum of exponentials: Σ exp(v_i)
+ * @param values Array of values in WAD format
+ * @returns Sum of exponentials in WAD format
+ */
+function sumExp(values) {
+    if (values.length === 0) {
+        throw new types_1.ValidationError("Empty array provided to sumExp");
+    }
+    let sum = new big_js_1.default(0);
+    for (const v of values) {
+        const expV = wExp(v);
+        sum = sum.plus(expV);
+    }
+    return sum;
+}
+/**
+ * Logarithm of sum of exponentials: ln(Σ exp(v_i))
+ * Uses numerical stability techniques (subtract max value)
+ * @param values Array of values in WAD format
+ * @returns ln(Σ exp(v_i)) in WAD format
+ */
+function logSumExp(values) {
+    if (values.length === 0) {
+        throw new types_1.ValidationError("Empty array provided to logSumExp");
+    }
+    // Find maximum value for numerical stability
+    let maxVal = values[0];
+    for (let i = 1; i < values.length; i++) {
+        if (values[i].gt(maxVal)) {
+            maxVal = values[i];
+        }
+    }
+    // Calculate sum of exp(x - max) with proper scaling
+    let sumScaled = new big_js_1.default(0);
+    for (const v of values) {
+        // Safe subtraction to avoid underflow
+        const diff = v.gte(maxVal) ? v.minus(maxVal) : new big_js_1.default(0);
+        const eScaled = wExp(diff);
+        sumScaled = sumScaled.plus(eScaled);
+    }
+    if (sumScaled.eq(0)) {
+        throw new types_1.CalculationError("Sum scaled to zero in logSumExp");
+    }
+    return maxVal.plus(wLn(sumScaled));
+}
+// ============================================================================
+// CLMSR-SPECIFIC FUNCTIONS
+// ============================================================================
+/**
+ * Calculate CLMSR price from exponential values
+ * Price = exp(q/α) / Σ exp(q_i/α)
+ * @param expValue Pre-computed exp(q/α) value for this tick
+ * @param totalSumExp Sum of all exponentials Σ exp(q/α)
+ * @returns Normalized price in WAD format
+ */
+function clmsrPrice(expValue, totalSumExp) {
+    if (totalSumExp.eq(0)) {
+        throw new types_1.ValidationError("Total sum of exponentials is zero");
+    }
+    return wDiv(expValue, totalSumExp);
+}
+/**
+ * Calculate CLMSR cost: α * ln(Σ_after / Σ_before)
+ * @param alpha Liquidity parameter α in WAD format
+ * @param sumBefore Sum of exponentials before trade
+ * @param sumAfter Sum of exponentials after trade
+ * @returns Trade cost in WAD format (always positive)
+ */
+function clmsrCost(alpha, sumBefore, sumAfter) {
+    if (sumBefore.eq(0)) {
+        throw new types_1.ValidationError("Sum before trade is zero");
+    }
+    const ratio = wDiv(sumAfter, sumBefore);
+    if (ratio.lt(exports.WAD)) {
+        throw new types_1.ValidationError("Ratio < 1 not supported in unsigned version");
+    }
+    const lnRatio = wLn(ratio);
+    return wMul(alpha, lnRatio);
+}
+/**
+ * Calculate CLMSR proceeds (for selling): α * ln(Σ_before / Σ_after)
+ * @param alpha Liquidity parameter α in WAD format
+ * @param sumBefore Sum of exponentials before sell
+ * @param sumAfter Sum of exponentials after sell
+ * @returns Trade proceeds in WAD format
+ */
+function clmsrProceeds(alpha, sumBefore, sumAfter) {
+    if (sumBefore.eq(0) || sumAfter.eq(0)) {
+        throw new types_1.ValidationError("Sum before or after trade is zero");
+    }
+    if (sumBefore.lte(sumAfter)) {
+        return new big_js_1.default(0); // No proceeds if sum doesn't decrease
+    }
+    const ratio = wDiv(sumBefore, sumAfter);
+    const lnRatio = wLn(ratio);
+    return wMul(alpha, lnRatio);
+}
+// ============================================================================
+// SAFE EXPONENTIAL WITH CHUNKING
+// ============================================================================
+/**
+ * Calculate exp(q/α) with contract-equivalent overflow guard
+ * Equivalent to contract's _safeExp function
+ * @param q Quantity in WAD format
+ * @param alpha Liquidity parameter in WAD format
+ * @returns Result of exp(q/α) in WAD format
+ */
+function safeExp(q, alpha) {
+    if (alpha.eq(0)) {
+        throw new types_1.ValidationError("Alpha cannot be zero");
+    }
+    const input = wDiv(q, alpha);
+    if (input.gt(exports.MAX_EXP_INPUT_WAD)) {
+        throw new types_1.ValidationError(`Exponent too large: ${input.toString()}, max: ${exports.MAX_EXP_INPUT_WAD.toString()}`);
+    }
+    return wExp(input);
+}
+function maxSafeChunkQuantity(alpha) {
+    if (alpha.eq(0)) {
+        return new big_js_1.default(0);
+    }
+    const treeLimit = wMul(alpha, exports.LN_MAX_FACTOR_WAD);
+    const expLimit = wMul(alpha, exports.MAX_EXP_INPUT_WAD);
+    return treeLimit.lt(expLimit) ? treeLimit : expLimit;
+}
+// ============================================================================
+// UTILITY FUNCTIONS
+// ============================================================================
+/**
+ * Check if a factor is within safe bounds for segment tree operations
+ * @param factor Factor to check
+ * @returns true if factor is within bounds
+ */
+function isFactorSafe(factor) {
+    return factor.gte(exports.MIN_FACTOR) && factor.lte(exports.MAX_FACTOR);
+}
+/**
+ * Create a new Big number from string, number, or Big
+ * @param value Input value
+ * @returns Big number
+ */
+function toBig(value) {
+    return new big_js_1.default(value);
+}
+/**
+ * Create WAD amount from numeric value (multiply by 1e18)
+ * Use this for converting regular numbers to WAD format
+ * @param value Input value in regular units (e.g., 1.5 USDC)
+ * @returns WAD amount (18 decimals)
+ */
+function toWAD(value) {
+    return new big_js_1.default(value).mul(exports.WAD);
+}
+/**
+ * Create micro-USDC amount from USDC value (multiply by 1e6)
+ * Use this for converting user input USDC amounts to SDK format
+ * @param value Input value in USDC (e.g., "100" = 100 USDC)
+ * @returns USDC amount in 6-decimal format (micro-USDC)
+ */
+function toMicroUSDC(value) {
+    return new big_js_1.default(value).mul(exports.USDC_PRECISION);
+}

package/dist/utils/prb-math.d.ts

@@ -0,0 +1,6 @@
+declare const UUNIT = 1000000000000000000n;
+declare const UEXP_MAX_INPUT = 133084258667509499440n;
+declare const MAX_UINT256: bigint;
+declare function ln(x: bigint): bigint;
+declare function exp(x: bigint): bigint;
+export { exp as expWad, ln as lnWad, UEXP_MAX_INPUT, UUNIT, MAX_UINT256 };