dexbot 1.1.10

package/dist/modules/order/utils/math.d.ts

@@ -0,0 +1,677 @@
+/**
+ * modules/order/utils/math.ts - Mathematical and Numeric Utilities
+ *
+ * Pure numeric calculations, blockchain conversions, fee math, and fund allocation.
+ *
+ * ===============================================================================
+ * TABLE OF CONTENTS (42 exported functions)
+ * ===============================================================================
+ *
+ * SECTION 1: PARSING & VALIDATION (4 functions)
+ *   - isExplicitZeroAllocation(value) - Check if value is explicitly zero
+ *   - isPercentageString(v) - Check if value is percentage string
+ *   - parsePercentageString(v) - Parse percentage string to decimal
+ *   - resolveRelativePrice(value, startPrice, mode) - Resolve relative price values
+ *
+ * SECTION 2: FUND CALCULATIONS (4 functions)
+ *   - computeChainFundTotals(accountTotals, committedChain) - Compute total funds
+ *   - calculateAvailableFundsValue(side, accountTotals, funds, ...) - Calculate available funds
+ *   - calculateSpreadFromOrders(activeBuys, activeSells) - Calculate spread percentage
+ *   - resolveConfigValue(value, total) - Resolve percentage or absolute config value
+ *
+ * SECTION 3: BLOCKCHAIN CONVERSIONS (5 functions)
+ *   - blockchainToFloat(intValue, precision) - Convert blockchain int to float
+ *   - floatToBlockchainInt(floatValue, precision) - Convert float to blockchain int
+ *   - quantizeFloat(value, precision) - Round float to blockchain precision
+ *   - normalizeInt(value, precision) - Normalize int within precision bounds
+ *   - hasValidAccountTotals(accountTotals, checkFree) - Validate account totals structure
+ *
+ * SECTION 4: PRECISION UTILITIES (5 functions)
+ *   - getPrecision(assets, orderType) - Get precision for order type
+ *   - getPrecisionByOrderType(assets, orderType) - Alias for getPrecision
+ *   - getPrecisionForSide(assets, side) - Get precision by side (buy/sell)
+ *   - getPrecisionsForManager(manager) - Get both asset precisions
+ *   - getPrecisionSlack(precision) - Calculate tolerance for precision
+ *
+ * SECTION 5: ORDER SIZE VALIDATION (7 functions)
+ *   - calculatePriceTolerance(price, size, type, assets) - Calculate price match tolerance
+ *   - validateOrderAmountsWithinLimits(amountToSell, minToReceive) - Validate order limits
+ *   - getMinOrderSize(assets, type) - Get minimum order size for type
+ *   - getDustThresholdFactor() - Get dust threshold multiplier
+ *   - getSingleDustThreshold(idealSize, dustThresholdPercent) - Get single dust threshold
+ *   - getDoubleDustThreshold(idealSize, dustThresholdPercent) - Get double dust threshold
+ *   - getMinAbsoluteOrderSize(orderType, assets, minFactor) - Get minimum absolute order size
+ *   - validateOrderSize(manager, size, type, context) - Validate order size against minimums
+ *
+ * SECTION 6: FEE CALCULATIONS (2 functions + 2 internal)
+ *   - getAssetFees(assetSymbol, assetAmount, isMaker) - Get fee info for asset
+ *   - _setFeeCache(cache) - Set internal fee cache (internal)
+ *   - _getFeeCache() - Get internal fee cache (internal)
+ *
+ * SECTION 7: FUND ALLOCATION (6 functions)
+ *   - allocateFundsByWeights(available, targetCount) - Allocate funds by weight
+ *   - cloneWeightDistribution(weightDistribution, base) - Clone weight distribution safely
+ *   - calculateOrderSizes(manager, orderType) - Calculate order sizes for placement
+ *   - calculateRotationOrderSizes(manager, orderType, fillAmount) - Calculate rotation sizes
+ *   - calculateGridSideDivergenceMetric(manager, orderType, threshold) - Calculate divergence
+ *   - clamp(value, min, max) - Clamp a value between min and max bounds
+ *
+ * SECTION 8: FEE DEDUCTION (3 functions)
+ *   - calculateOrderCreationFees(count, btsFeeData) - Calculate total creation fees
+ *   - deductOrderFeesFromFunds(available, count, btsFeeData, btsSide) - Deduct fees from funds
+ *   - calculateSwapInAmount(targetReceive, poolReserveOut, poolReserveIn) - AMM swap math
+ *
+ * SECTION 9: GRID UTILITIES (1 function)
+ *   - calculateGapSlots(incrementPercent, targetSpreadPercent) - Calculate gap slots count
+ *
+ * ===============================================================================
+ */
+/**
+ * Check if a value is explicitly set to zero (number 0, string "0", or "0%").
+ * Used to distinguish between "not set" and "explicitly disabled".
+ *
+ * @param {*} value - Value to check
+ * @returns {boolean} True if value is explicitly zero
+ */
+declare function isExplicitZeroAllocation(value: any): boolean;
+/**
+ * Check if a value is a percentage string (ends with '%').
+ *
+ * @param {*} v - Value to test
+ * @returns {boolean} True if v is a string ending with '%'
+ */
+declare function isPercentageString(v: any): boolean;
+/**
+ * Check if a value is a positive number.
+ *
+ * @param {*} value - Value to test
+ * @returns {boolean} True if the value is a finite number greater than 0
+ */
+declare function isPositiveNumber(value: any): boolean;
+/**
+ * Check if a value is a positive number or a positive percentage string.
+ *
+ * @param {*} value - Value to test
+ * @returns {boolean} True if the value is a positive number or a percentage string like "25%"
+ */
+declare function isPositiveNumberOrPercent(value: any): boolean;
+/**
+ * Check if a value is a positive integer.
+ *
+ * @param {*} value - Value to test
+ * @returns {boolean} True if the value is an integer greater than 0
+ */
+declare function isPositiveInt(value: any): boolean;
+/**
+ * Parse a percentage string to decimal form.
+ * Extracts numeric value before '%' and divides by 100.
+ *
+ * @param {string} v - Percentage string (e.g., "50%")
+ * @returns {number|null} Decimal form (e.g., 0.5) or null if invalid
+ */
+declare function parsePercentageString(v: any): number;
+/**
+ * Convert a value (number, percentage string, or numeric string) to its
+ * decimal form. Unlike parsePercentageString which only handles '%' strings,
+ * this also accepts bare numbers and numeric strings.
+ * @param {*} value - Number (100 = 100), "100%" (= 1.0), or "100" (= 100)
+ * @returns {number} Decimal value, 0 if unparseable
+ */
+declare function toDecimal(value: any): number;
+/**
+ * Resolve a relative price expression (multiplier format) to absolute price.
+ * Supports expressions like "3x" to mean 3 times the reference price.
+ *
+ * @param {*} value - Value to resolve (e.g., "3x" or "0.5x")
+ * @param {number} startPrice - Reference price for multiplier calculation
+ * @param {string} [mode='min'] - "min" divides (price/multiplier), "max" multiplies (price*multiplier)
+ * @returns {number|null} Resolved price or null if value is not a relative expression
+ */
+declare function resolveRelativePrice(value: any, startPrice: any, mode?: string): number;
+/**
+ * Calculate chain fund totals from account balances and committed orders.
+ * Reconciles free/locked balances with committed capital to produce fund summary.
+ *
+ * @param {Object} accountTotals - Account balance snapshot with buyFree, sellFree, buy, sell properties
+ * @param {Object} committedChain - Committed capital with buy and sell properties
+ * @returns {Object} Summary object with chainFreeBuy, chainFreeSell, committedChainBuy,
+ *                   committedChainSell, freePlusLockedBuy, freePlusLockedSell, chainTotalBuy, chainTotalSell
+ */
+declare function computeChainFundTotals(accountTotals: any, committedChain: any): {
+    chainFreeBuy: any;
+    chainFreeSell: any;
+    committedChainBuy: any;
+    committedChainSell: any;
+    freePlusLockedBuy: any;
+    freePlusLockedSell: any;
+    chainTotalBuy: any;
+    chainTotalSell: any;
+};
+/**
+ * Quantize a float value by round-tripping through blockchain integer representation.
+ * Converts float → blockchain int (satoshi-level precision) → float.
+ * Eliminates floating-point accumulation errors.
+ *
+ * @param {number} value - Float value to quantize
+ * @param {number} precision - Asset precision (satoshis)
+ * @returns {number} Quantized float value
+ */
+declare function quantizeFloat(value: any, precision: any): number;
+/**
+ * Normalize an integer value by round-tripping through float representation.
+ * Converts int → float (readable format) → blockchain int.
+ * Ensures the integer aligns with precision boundaries.
+ * Used for precision-aware comparisons.
+ *
+ * @param {number} value - Integer value to normalize
+ * @param {number} precision - Asset precision (satoshis)
+ * @returns {number} Normalized integer value
+ */
+declare function normalizeInt(value: any, precision: any): number;
+/**
+ * @private Set the fee cache (called by system.js::initializeFeeCache).
+ *
+ * @param {Object} cache - Fee cache object keyed by asset symbol
+ * @returns {void}
+ */
+declare function _setFeeCache(cache: any): void;
+/**
+ * Get fee information for an asset.
+
+ * Returns fee structure or net proceeds calculation if asset amount provided.
+ *
+ * @param {string} assetSymbol - Asset symbol (e.g., "BTS", "USD")
+ * @param {number} [assetAmount=null] - Asset amount to calculate net proceeds
+ * @param {boolean} [isMaker=true] - Whether this is a maker or taker (affects BTS fees)
+ * @returns {Object} Fee structure with create/update/net fees or net proceeds if amount provided
+ * @throws {Error} If fees not cached (call initializeFeeCache first)
+ */
+declare function getAssetFees(assetSymbol: any, assetAmount?: any, isMaker?: boolean): {
+    netProceeds: number;
+    total: number;
+    refund: number;
+    isMaker: boolean;
+    createFee?: undefined;
+    updateFee?: undefined;
+    cancelFee?: undefined;
+    makerFeeDiscountPercent?: undefined;
+    makerNetFee?: undefined;
+    takerNetFee?: undefined;
+    netFee?: undefined;
+    feeAmount?: undefined;
+    feePercent?: undefined;
+    marketFee?: undefined;
+    takerFee?: undefined;
+    percent?: undefined;
+} | {
+    total: any;
+    createFee: any;
+    updateFee: any;
+    cancelFee: any;
+    makerFeeDiscountPercent: any;
+    makerNetFee: number;
+    takerNetFee: number;
+    netFee: number;
+    isMaker: boolean;
+    netProceeds?: undefined;
+    refund?: undefined;
+    feeAmount?: undefined;
+    feePercent?: undefined;
+    marketFee?: undefined;
+    takerFee?: undefined;
+    percent?: undefined;
+} | {
+    netProceeds: number;
+    total: number;
+    feeAmount: number;
+    feePercent: any;
+    isMaker: boolean;
+    refund?: undefined;
+    createFee?: undefined;
+    updateFee?: undefined;
+    cancelFee?: undefined;
+    makerFeeDiscountPercent?: undefined;
+    makerNetFee?: undefined;
+    takerNetFee?: undefined;
+    netFee?: undefined;
+    marketFee?: undefined;
+    takerFee?: undefined;
+    percent?: undefined;
+} | {
+    marketFee: any;
+    takerFee: any;
+    percent: any;
+    netProceeds?: undefined;
+    total?: undefined;
+    refund?: undefined;
+    isMaker?: undefined;
+    createFee?: undefined;
+    updateFee?: undefined;
+    cancelFee?: undefined;
+    makerFeeDiscountPercent?: undefined;
+    makerNetFee?: undefined;
+    takerNetFee?: undefined;
+    netFee?: undefined;
+    feeAmount?: undefined;
+    feePercent?: undefined;
+};
+/**
+ * Calculate available funds for a specific side (buy or sell).
+ * Deducts virtual reservations, BTS fees owed, and BTS fee reservation from chain-free balance.
+ *
+ * @param {string} side - Trading side: "buy" or "sell"
+ * @param {Object} accountTotals - Account balance snapshot
+ * @param {Object} funds - Fund allocation object with virtual, btsFeesOwed properties
+ * @param {string} assetA - First asset symbol
+ * @param {string} assetB - Second asset symbol
+ * @param {Object} [activeOrders=null] - Active order counts {buy, sell} for BTS reservation calculation
+ * @returns {number} Available funds for the side (0 if side invalid or insufficient funds)
+ */
+declare function calculateAvailableFundsValue(side: any, accountTotals: any, funds: any, assetA: any, assetB: any, activeOrders?: any, configMinBtsValue?: any, feeParams?: any): number;
+/**
+ * Find the best (highest) buy price and best (lowest) sell price from active orders.
+ *
+ * @param {Array<Object>} activeBuys - Active buy orders with price property
+ * @param {Array<Object>} activeSells - Active sell orders with price property
+ * @returns {{bestBuy: number|null, bestSell: number|null}} Best prices or null if no orders
+ */
+declare function getGridBestPrices(activeBuys: any, activeSells: any): {
+    bestBuy: number;
+    bestSell: number;
+};
+/**
+ * Calculate bid-ask spread percentage from active buy and sell orders.
+ * Spread = (bestSell / bestBuy - 1) * 100 (percentage).
+ *
+ * @param {Array<Object>} activeBuys - Active buy orders with price property
+ * @param {Array<Object>} activeSells - Active sell orders with price property
+ * @returns {number} Spread percentage or 0 if insufficient data
+ */
+declare function calculateSpreadFromOrders(activeBuys: any, activeSells: any): number;
+/**
+ * Resolve a config value to a numeric amount.
+ * Interprets percentage strings, numeric strings, or direct numbers.
+ *
+ * @param {*} value - Value to resolve (string, number, or percentage)
+ * @param {number} total - Total amount for percentage calculations
+ * @returns {number} Resolved numeric value or 0 if uninterpretable
+ */
+declare function resolveConfigValue(value: any, total: any): number;
+/**
+ * Resolve a config value to a numeric amount, accounting for shared-account
+ * fund registry. If the bot has a registry entry, returns the proportional
+ * share of chainTotal. Falls back to standard resolveConfigValue if the
+ * registry has no entry for this bot (single-bot accounts or unregistered).
+ *
+ * @param {*} value - Value to resolve (string, number, or percentage)
+ * @param {number} chainTotal - Total chain balance for this side
+ * @param {string} account - Blockchain account name
+ * @param {string} botName - Bot identifier
+ * @param {'buy'|'sell'} side - Trade side
+ * @returns {number} Resolved numeric value or 0 if uninterpretable
+ */
+declare function resolveConfigValueWithRegistry(value: any, chainTotal: any, account: any, botName: any, side: any): any;
+/**
+ * Check if account totals contain valid buy/sell balance data.
+ *
+ * @param {Object} accountTotals - Account total balances object
+ * @param {boolean} [checkFree=true] - Check free balances if true, else check total balances
+ * @returns {boolean} True if both buy and sell values are valid finite numbers
+ */
+declare function hasValidAccountTotals(accountTotals: any, checkFree?: boolean): any;
+/**
+ * Convert blockchain integer to float using asset precision.
+ * Divides by 10^precision to convert satoshi-level units to human-readable float.
+ * Formula: float = blockchain_int / (10^precision)
+ *
+ * @param {number} intValue - Integer value from blockchain (satoshi units)
+ * @param {number} precision - Asset precision level (exponent: 5, 8, 4, etc)
+ * @returns {number} Float representation in human-readable units
+ * @throws {Error} If precision is invalid
+ */
+declare function blockchainToFloat(intValue: any, precision: any): number;
+/**
+ * Convert float to blockchain integer using asset precision.
+ * Multiplies by 10^precision and rounds to satoshi-level units.
+ * Clamps to MAX_INT64/MIN_INT64 to prevent overflow.
+ * Formula: blockchain_int = round(float * (10^precision))
+ *
+ * Round-trip (float → int → float) eliminates floating-point accumulation errors.
+ * Overflow protection: Blockchain integers must fit in signed 64-bit range.
+ *
+ * @param {number} floatValue - Float value to convert (human-readable units)
+ * @param {number} precision - Asset precision level (exponent: 5, 8, 4, etc)
+ * @returns {number} Blockchain integer representation (satoshi units)
+ * @throws {Error} If precision is invalid
+ */
+declare function floatToBlockchainInt(floatValue: any, precision: any): number;
+/**
+ * Get asset precision for a specific order type (BUY or SELL).
+ * BUY orders size in assetB, SELL orders size in assetA.
+ *
+ * @param {Object} assets - Asset metadata with assetA and assetB
+ * @param {string} orderType - Order type (ORDER_TYPES.BUY or ORDER_TYPES.SELL)
+ * @returns {number} Asset precision
+ * @throws {Error} If precision missing for the required asset
+ */
+declare function getPrecisionByOrderType(assets: any, orderType: any): any;
+/**
+ * Get asset precision for a specific trading side.
+ *
+ * @param {Object} assets - Asset metadata with assetA and assetB
+ * @param {string} side - Side ("buy" or "sell")
+ * @returns {number} Asset precision for the side
+ * @throws {Error} If precision missing
+ */
+declare function getPrecisionForSide(assets: any, side: any): any;
+/**
+ * Get asset precisions for both assetA and assetB.
+ *
+ * @param {Object} assets - Asset metadata with assetA and assetB
+ * @returns {Object} Object with A and B precision properties
+ * @throws {Error} If precision missing for either asset
+ */
+declare function getPrecisionsForManager(assets: any): {
+    A: any;
+    B: any;
+};
+/**
+ * Calculate precision slack (rounding tolerance) for a given precision level.
+ * Used for safe comparison of blockchain values that may differ by rounding.
+ *
+ * @param {number} precision - Asset precision level
+ * @param {number} [factor=2] - Multiplier for slack (default 2)
+ * @returns {number} Tolerance value (e.g., 2 * 10^-8 for 8-decimal precision)
+ */
+declare function getPrecisionSlack(precision: any, factor?: number): number;
+/**
+ * Unified precision lookup for assets.
+ *
+ * @param {Object} assets - Assets object with assetA and assetB
+ * @param {Object} [options={}] - Lookup options { type, side, proceeds }
+ * @returns {number} Asset precision
+ */
+declare function getPrecision(assets: any, { type, side, proceeds }?: {
+    type?: string;
+    side?: string;
+    proceeds?: boolean;
+}): any;
+/**
+ * Calculate price tolerance for order matching on-chain.
+ * Accounts for precision limits of both assets to determine acceptable price deviation.
+ * Used when matching grid orders to blockchain orders.
+ *
+ * NOTE on the orderSize parameter: larger sizes produce tighter (more precise)
+ * tolerance values. When using this function for duplicate-price-level
+ * detection, always pass Math.max(sizeA, sizeB) as orderSize — a tiny dust
+ * order would inflate the tolerance window and falsely match distant prices.
+ *
+ * @param {number} gridPrice - Grid order price
+ * @param {number} orderSize - Order size on primary side (larger = tighter tolerance)
+ * @param {string} orderType - Order type ("buy" or "sell")
+ * @param {Object} [assets=null] - Asset metadata with precision (required)
+ * @returns {number|null} Price tolerance value or null if invalid inputs
+ * @throws {Error} If assets missing or precisions invalid
+ */
+declare function calculatePriceTolerance(gridPrice: any, orderSize: any, orderType: any, assets?: any): number;
+/**
+ * Validate order amounts are within blockchain limits (0 < INT64_MAX).
+ * Converts floats to blockchain integers and checks they fit in signed 64-bit integers.
+ *
+ * @param {number} amountToSell - Amount to sell (float)
+ * @param {number} minToReceive - Minimum amount to receive (float)
+ * @param {number} sellPrecision - Precision of sell asset
+ * @param {number} receivePrecision - Precision of receive asset
+ * @returns {boolean} True if both amounts are valid and within limits
+ */
+declare function validateOrderAmountsWithinLimits(amountToSell: any, minToReceive: any, sellPrecision: any, receivePrecision: any): boolean;
+/**
+ * Calculate minimum absolute order size for an order type.
+ * Returns factor * 10^-precision (e.g., 50 * 10^-8 for 8-decimal asset).
+ *
+ * @param {string} orderType - Order type (BUY or SELL)
+ * @param {Object} assets - Asset metadata with assetA and assetB precisions
+ * @param {number} [factor=50] - Minimum size factor (default 50)
+ * @returns {number} Minimum order size in asset units
+ * @throws {Error} If precision cannot be determined
+ */
+declare function getMinOrderSize(orderType: any, assets: any, factor?: number): number;
+/**
+ * Calculate dust threshold factor as decimal fraction.
+ *
+ * @param {number} [dustThresholdPercent=5] - Dust threshold percentage (default 5%)
+ * @returns {number} Dust factor (e.g., 0.05 for 5%)
+ */
+declare function getDustThresholdFactor(dustThresholdPercent?: number): number;
+/**
+ * Calculate single dust threshold for an ideal order size.
+ * Returns idealSize * (dustThresholdPercent / 100).
+ *
+ * @param {number} idealSize - Ideal/reference order size
+ * @param {number} [dustThresholdPercent=5] - Threshold percentage (default 5%)
+ * @returns {number} Single dust threshold (0 if idealSize invalid)
+ */
+declare function getSingleDustThreshold(idealSize: any, dustThresholdPercent?: number): number;
+/**
+ * Calculate double dust threshold for an ideal order size.
+ * Returns idealSize * (dustThresholdPercent / 100) * 2.
+ * Used to filter very small orders that would be uneconomical.
+ *
+ * @param {number} idealSize - Ideal/reference order size
+ * @param {number} [dustThresholdPercent=5] - Threshold percentage (default 5%)
+ * @returns {number} Double dust threshold (0 if idealSize invalid)
+ */
+declare function getDoubleDustThreshold(idealSize: any, dustThresholdPercent?: number): number;
+/**
+ * Calculate minimum absolute order size (wrapper for getMinOrderSize with default factor).
+ *
+ * @param {string} orderType - Order type (BUY or SELL)
+ * @param {Object} assets - Asset metadata
+ * @param {number} [minFactor=50] - Minimum size factor (default 50)
+ * @returns {number} Minimum order size in asset units
+ */
+declare function getMinAbsoluteOrderSize(orderType: any, assets: any, minFactor?: number): number;
+/**
+ * Validate an order size against minimum absolute and dust thresholds.
+ * Returns detailed validation result with reasons if invalid.
+ *
+ * @param {number} orderSize - Order size to validate
+ * @param {string} orderType - Order type (BUY or SELL)
+ * @param {Object} assets - Asset metadata with precisions
+ * @param {number} [minFactor=50] - Minimum size factor (default 50)
+ * @param {number} [idealSize=null] - Ideal size for dust calculations
+ * @param {number} [dustThresholdPercent=5] - Dust threshold percentage (default 5%)
+ * @returns {Object} Validation result {isValid, reason, minAbsoluteSize, minDustSize}
+ */
+declare function validateOrderSize(orderSize: any, orderType: any, assets: any, minFactor?: number, idealSize?: any, dustThresholdPercent?: number): {
+    isValid: boolean;
+    reason: string;
+    minAbsoluteSize: number;
+    minDustSize: number;
+};
+/**
+ * Allocate total funds across n orders using exponential weight distribution.
+ * Optionally enforces precision quantization to match blockchain constraints.
+ * If precision provided, adjusts the largest order to compensate for rounding errors.
+ *
+ * @param {number} totalFunds - Total funds to allocate
+ * @param {number} n - Number of orders to create allocations for
+ * @param {number} weight - Weight factor (0-1) controlling distribution steepness
+ * @param {number} incrementFactor - Increment factor (typically 0.01 for 1% grid spacing)
+ * @param {boolean} [reverse=false] - If true, allocate larger sizes to higher indices
+ * @param {number} [minSize=0] - Minimum size for each allocation (currently unused, for future validation)
+ * @param {number} [precision=null] - Asset precision; if provided, quantize to blockchain integers
+ * @returns {Array<number>} Array of n allocation sizes
+ */
+declare function allocateFundsByWeights(totalFunds: any, n: any, weight: any, incrementFactor: any, reverse?: boolean, minSize?: number, precision?: any): any[];
+/**
+ * Calculate order sizes for a list of orders using weighted fund allocation.
+ * Allocates buy and sell funds separately using weight distribution from config.
+ * Preserves order sequence while adding size property to each order.
+ *
+ * @param {Array<Object>} orders - Array of order objects with type property
+ * @param {Object} config - Configuration with incrementPercent and weightDistribution
+ * @param {number} sellFunds - Total funds available for SELL orders
+ * @param {number} buyFunds - Total funds available for BUY orders
+ * @param {number} [minSellSize=0] - Minimum size for sell allocations
+ * @param {number} [minBuySize=0] - Minimum size for buy allocations
+ * @param {number} [precisionA=null] - Precision for assetA (SELL asset)
+ * @param {number} [precisionB=null] - Precision for assetB (BUY asset)
+ * @returns {Array<Object>} Orders array with size property added to each
+ */
+declare function calculateOrderSizes(orders: any, config: any, sellFunds: any, buyFunds: any, minSellSize?: number, minBuySize?: number, precisionA?: any, precisionB?: any): any;
+/**
+ * Calculate order sizes for rotation operations.
+ * Combines available funds with existing grid allocation for sizing.
+ * Used during order refreshes when rotating orders to new positions.
+ *
+ * @param {number} availableFunds - Free funds not yet allocated
+ * @param {number} totalGridAllocation - Sum of all existing grid order sizes
+ * @param {number} orderCount - Number of orders to size
+ * @param {string} orderType - Order type (BUY or SELL)
+ * @param {Object} config - Configuration with incrementPercent and weightDistribution
+ * @param {number} [minSize=0] - Minimum size for each allocation
+ * @param {number} [precision=null] - Asset precision for quantization
+ * @returns {Array<number>} Array of order sizes
+ */
+declare function calculateRotationOrderSizes(availableFunds: any, totalGridAllocation: any, orderCount: any, orderType: any, config: any, minSize?: number, precision?: any): any[];
+/**
+ * Calculate RMS (Root Mean Square) divergence between calculated and persisted grids.
+ * Measures how much the current grid differs from the calculated ideal.
+ * Used to determine if grid recalculation is needed.
+ *
+ * RMS quadratically penalizes large errors and unmatched orders (treated as 100% error).
+ * Default 14.3% RMS threshold allows ~3.2% average error concentrated in few orders.
+ * See README GRID RECALCULATION section for threshold interpretation table.
+ *
+ * @param {Array<Object>} calculatedOrders - Ideal/calculated order grid
+ * @param {Array<Object>} persistedOrders - Current/persisted order grid
+ * @param {string} [sideName='unknown'] - Side name for logging (buy/sell)
+ * @returns {number} RMS divergence metric (0 = perfect match, higher = more divergence)
+ */
+declare function calculateGridSideDivergenceMetric(calculatedOrders: any, persistedOrders: any, sideName?: string): number;
+/**
+ * Calculate estimated BTS order creation fees for a number of orders.
+ * Works for all pairs — returns the BTS fee budget needed for order operations.
+ *
+ * @param {string} assetA - First asset symbol
+ * @param {string} assetB - Second asset symbol (unused in calculation, kept for signature compat)
+ * @param {number} totalOrders - Number of orders to create
+ * @param {number} [feeMultiplier=BTS_RESERVATION_MULTIPLIER] - Multiplier for reservation (typically 5x)
+ * @returns {number} Total fee amount (fallback BTS_FALLBACK_FEE if fee lookup fails; warning logged)
+ */
+declare function calculateOrderCreationFees(assetA: any, assetB: any, totalOrders: any, feeMultiplier?: any): any;
+/**
+ * Deduct order fees from available buy/sell funds.
+ * If BTS is the buy asset, deducts from buyFunds; if sell asset, deducts from sellFunds.
+ *
+ * @param {number} buyFunds - Available buy-side funds
+ * @param {number} sellFunds - Available sell-side funds
+ * @param {number} fees - Fee amount to deduct
+ * @param {Object} config - Configuration with assetA and assetB
+ * @param {Object} [logger=null] - Optional logger for logging deductions
+ * @returns {Object} Updated funds object {buyFunds, sellFunds}
+ */
+declare function deductOrderFeesFromFunds(buyFunds: any, sellFunds: any, fees: any, config: any, logger?: any): {
+    buyFunds: any;
+    sellFunds: any;
+};
+/**
+ * Calculate how much input asset to swap into a constant-product AMM pool
+ * to receive a target amount of output asset.
+ *
+ * Formula: k = reserveIn * reserveOut
+ *          newReserveOut = reserveOut - targetReceive
+ *          newReserveIn = k / newReserveOut
+ *          sellAmount = newReserveIn - reserveIn
+ *
+ * Caps swap at 50% of pool reserves to prevent extreme slippage.
+ *
+ * @param {number} targetReceive - Desired amount of output asset
+ * @param {number} poolReserveOut - Pool reserve of output asset
+ * @param {number} poolReserveIn - Pool reserve of input asset
+ * @returns {number} Amount of input asset to sell
+ */
+declare function calculateSwapInAmount(targetReceive: any, poolReserveOut: any, poolReserveIn: any): number;
+/**
+ * Calculate the spread gap size (number of empty slots between BUY and SELL rails).
+ * Used by both grid creation and strategy rebalancing to keep spread math consistent.
+ *
+ * @param {number} incrementPercent - Grid increment percentage
+ * @param {number} targetSpreadPercent - Target spread percentage
+ * @param {Object} GRID_LIMITS - Grid limits constants (optional, uses defaults)
+ * @returns {number} Number of gap slots
+ */
+declare function calculateGapSlots(incrementPercent: any, targetSpreadPercent: any, gridLimits?: {
+    MIN_SPREAD_FACTOR?: number;
+    MIN_SPREAD_ORDERS?: number;
+}): number;
+declare const _default: {
+    calculateGapSlots: typeof calculateGapSlots;
+    isPercentageString: typeof isPercentageString;
+    isPositiveNumber: typeof isPositiveNumber;
+    isPositiveNumberOrPercent: typeof isPositiveNumberOrPercent;
+    isPositiveInt: typeof isPositiveInt;
+    parsePercentageString: typeof parsePercentageString;
+    toDecimal: typeof toDecimal;
+    resolveRelativePrice: typeof resolveRelativePrice;
+    isExplicitZeroAllocation: typeof isExplicitZeroAllocation;
+    getPrecision: typeof getPrecision;
+    computeChainFundTotals: typeof computeChainFundTotals;
+    calculateAvailableFundsValue: typeof calculateAvailableFundsValue;
+    getGridBestPrices: typeof getGridBestPrices;
+    calculateSpreadFromOrders: typeof calculateSpreadFromOrders;
+    resolveConfigValue: typeof resolveConfigValue;
+    resolveConfigValueWithRegistry: typeof resolveConfigValueWithRegistry;
+    hasValidAccountTotals: typeof hasValidAccountTotals;
+    blockchainToFloat: typeof blockchainToFloat;
+    floatToBlockchainInt: typeof floatToBlockchainInt;
+    quantizeFloat: typeof quantizeFloat;
+    normalizeInt: typeof normalizeInt;
+    getPrecisionByOrderType: typeof getPrecisionByOrderType;
+    getPrecisionForSide: typeof getPrecisionForSide;
+    getPrecisionsForManager: typeof getPrecisionsForManager;
+    getPrecisionSlack: typeof getPrecisionSlack;
+    calculatePriceTolerance: typeof calculatePriceTolerance;
+    validateOrderAmountsWithinLimits: typeof validateOrderAmountsWithinLimits;
+    getMinOrderSize: typeof getMinOrderSize;
+    getDustThresholdFactor: typeof getDustThresholdFactor;
+    getSingleDustThreshold: typeof getSingleDustThreshold;
+    getDoubleDustThreshold: typeof getDoubleDustThreshold;
+    getMinAbsoluteOrderSize: typeof getMinAbsoluteOrderSize;
+    validateOrderSize: typeof validateOrderSize;
+    getAssetFees: typeof getAssetFees;
+    allocateFundsByWeights: typeof allocateFundsByWeights;
+    calculateOrderSizes: typeof calculateOrderSizes;
+    calculateRotationOrderSizes: typeof calculateRotationOrderSizes;
+    calculateGridSideDivergenceMetric: typeof calculateGridSideDivergenceMetric;
+    calculateOrderCreationFees: typeof calculateOrderCreationFees;
+    deductOrderFeesFromFunds: typeof deductOrderFeesFromFunds;
+    calculateSwapInAmount: typeof calculateSwapInAmount;
+    _setFeeCache: typeof _setFeeCache;
+    cloneWeightDistribution: typeof cloneWeightDistribution;
+    clamp: typeof clamp;
+};
+export = _default;
+/**
+ * Clamp a value between min and max bounds.
+ * @param {number} value - The value to clamp
+ * @param {number} min - Lower bound
+ * @param {number} max - Upper bound
+ * @returns {number}
+ */
+declare function clamp(value: any, min: any, max: any): number;
+/**
+ * Safely clone a weight distribution object.
+ * Validates numeric sell/buy values and falls back to a base object if provided.
+ * Returns null if neither primary nor base yields valid numbers.
+ *
+ * @param {Object|null} weightDistribution - Primary weights (e.g. { sell, buy })
+ * @param {Object|null} base - Fallback weights if primary is missing/invalid
+ * @returns {{sell:number,buy:number}|null}
+ */
+declare function cloneWeightDistribution(weightDistribution: any, base?: any): {
+    sell: number;
+    buy: number;
+};
+//# sourceMappingURL=math.d.ts.map

package/dist/modules/order/utils/math.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"math.d.ts","sourceRoot":"","sources":["../../../../modules/order/utils/math.ts"],"names":[],"mappings":"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"}