dexbot 1.1.10

package/dist/modules/order/accounting.d.ts

@@ -0,0 +1,349 @@
+/**
+ * modules/order/accounting.ts - Accountant Engine
+ *
+ * Specialized engine for financial state and fund tracking.
+ * Responsible for calculating available funds, committed capital, and managing BTS blockchain fees.
+ * Exports a single Accountant class that manages all fund accounting operations.
+ *
+ * ===============================================================================
+ * TABLE OF CONTENTS - Accountant Class (18 methods)
+ * ===============================================================================
+ *
+ * CORE INITIALIZATION & RECALCULATION (2 methods)
+ *   1. constructor(manager) - Create new Accountant instance
+ *   2. resetFunds() - Initialize funds structure with zeroed values
+ *
+ * MASTER FUND CALCULATIONS (1 method)
+ *   3. recalculateFunds() - MASTER FUND CALCULATION: Recalculate all fund values based on order states
+ *      Called after any state change. Aggregates committed/available funds and triggers allocation.
+ *
+ * VERIFICATION & RECOVERY (3 methods - async, internal)
+ *   4. _verifyFundInvariants(mgr, chainFreeBuy, chainFreeSell, chainBuy, chainSell) - Verify fund tracking invariants
+ *   5. _performStateRecovery(mgr) - Centralized state recovery (fetch + sync + validate) (async, internal)
+ *   6. _attemptFundRecovery(mgr, violationType) - Attempt immediate recovery from invariant violations (async, internal)
+ *
+ * CHAINFREE BALANCE MANAGEMENT (2 methods)
+ *   7. tryDeductFromChainFree(orderType, size, operation) - Atomically deduct from FREE portion
+ *   8. addToChainFree(orderType, size, operation) - Add amount back to optimistic chainFree balance
+ *
+ * BALANCE ADJUSTMENTS (4 methods)
+ *   9. adjustTotalBalance(orderType, delta, operation, totalOnly) - Adjust total and free balances
+ *   10. _normalizeSideHint(sideHint) - Normalize side hint to standard key (internal)
+ *   11. _resolveOrderSide(order, fallbackOrder, explicitSideHint) - Resolve order side (internal)
+ *   12. updateOptimisticFreeBalance(oldOrder, newOrder, context, fee, skipAssetAccounting) - Update optimistic balance during transitions
+ *
+ * FEE MANAGEMENT (2 methods)
+ *   13. deductBtsFees(requestedSide) - Deduct BTS fees using adjustTotalBalance with deferral strategy (async)
+ *   14. _deductFeesFromProceeds(assetSymbol, rawAmount, isMaker) - Deduct fees from fill proceeds (internal)
+ *
+ * FILL BALANCE TRACKING (1 method)
+ *   15. recordFillBalances(paysAsset, paysAmount, receivesAsset, receivesAmount, context) - Record fill proceeds (async)
+ *
+ * FILL PROCESSING (1 method)
+ *   16. processFillAccounting(fillOp, fillKey, persistenceMode) - Process fund impact of order fill (atomically updates accountTotals)
+ *
+ * RECOVERY & VALIDATION (2 methods)
+ *   17. resetRecoveryState() - Reset recovery backoff and state
+ *   18. validateTargetGrid(targetGrid, mgr) - Validate target grid fund requirements
+ *
+ * ===============================================================================
+ * FUND STRUCTURE (managed by Accountant)
+ * ===============================================================================
+ *
+ * manager.funds = {
+ *     available:   { buy, sell }          // Available funds for placement
+ *     total:       { chain, grid }        // Total across blockchain + grid
+ *     virtual:     { buy, sell }          // Virtual order capital
+ *     committed:   { chain, grid }        // Capital locked in active orders
+ *     btsFeesOwed: number                 // Unpaid BTS fees
+ * }
+ *
+ * manager.accountTotals = {
+ *     buy:      number                   // Total BUY balance on blockchain
+ *     sell:     number                   // Total SELL balance on blockchain
+ *     buyFree:  number                   // FREE BUY (not in any order)
+ *     sellFree: number                   // FREE SELL (not in any order)
+ * }
+ *
+ * ===============================================================================
+ *
+ * FUND INVARIANTS (verified by _verifyFundInvariants):
+ * - blockchainTotal = chainFreeBalance + committedAmount
+ * - Virtual orders don't reduce FREE balance
+ *
+ * ===============================================================================
+ */
+/**
+ * Accountant engine - Specialized handler for fund tracking and calculations
+ * @class Accountant
+ */
+declare class Accountant {
+    /**
+     * Create a new Accountant instance
+     *
+     * @param {Object} manager - OrderManager instance
+     * @param {Map<string, Object>} manager.orders - Orders map
+     * @param {Object} manager.accountTotals - Blockchain account balances
+     * @param {Object} manager.funds - Fund tracking structure
+     * @param {Logger} manager.logger - Logger instance
+     */
+    manager: any;
+    _isVerifyingInvariants: boolean;
+    _pendingInvariantSnapshot: {
+        chainFreeBuy: number;
+        chainFreeSell: number;
+        chainBuy: number;
+        chainSell: number;
+    } | null;
+    _logThrottleState: Map<string, {
+        lastAt: number;
+        suppressed: number;
+        lastMessage: string | null;
+    }>;
+    constructor(manager: any);
+    _logThrottled(key: any, message: any, level?: string, intervalMs?: any): boolean;
+    /**
+     * @returns {Map<string, number>|null}
+     */
+    _getProcessedFillTracker(): any;
+    /**
+     * @returns {import('./processed_fill_store').ProcessedFillStore|null}
+     */
+    _getProcessedFillStore(): any;
+    /**
+     * Apply a list of balance adjustments.
+     * @param {Array<{orderType: string, delta: number, operation: string}>} balanceAdjustments
+     * @returns {void}
+     */
+    _applyBalanceAdjustments(balanceAdjustments: any): void;
+    /**
+     * Roll back a list of balance adjustments in reverse order.
+     * @param {Array<{orderType: string, delta: number, operation: string}>} balanceAdjustments
+     * @returns {void}
+     */
+    _rollbackBalanceAdjustments(balanceAdjustments: any): void;
+    _getBtsOrderType(): any;
+    _normalizeBtsFeeState(order: any): {
+        deferredFee: number;
+    };
+    _getBtsFeeSchedule(): {
+        createFee: number;
+        updateFee: number;
+        cancelFee: number;
+        makerFeeDiscountPercent: any;
+    };
+    _calculateUpdateDeferredCharge(oldDeferredFee: any, feeSchedule: any): number;
+    _resolveBtsFeeLifecycle(oldOrder: any, newOrder: any, context: any, explicitFee: any): {
+        balanceDelta: number;
+        nextDeferred: number;
+    };
+    _buildBtsDeferredRefundAdjustment(orderId: any, isMaker: any): {
+        orderType: any;
+        delta: number;
+        operation: string;
+    };
+    /**
+     * Initialize the funds structure with zeroed values.
+     *
+     * @returns {void}
+     */
+    resetFunds(): void;
+    /**
+     * Recalculate all fund values based on current order states.
+     * This is THE MASTER FUND CALCULATION and must be called after any state change.
+     * Called automatically by _updateOrder(), but can be manually triggered to verify consistency.
+     *
+     * PSEUDOCODE ALGORITHM:
+     * =====================
+     * 1. Initialize accumulators (gridBuy, gridSell, chainBuy, chainSell, virtualBuy, virtualSell)
+     * 2. Classify each order's state (ACTIVE/PARTIAL = on-chain committed, VIRTUAL = pending)
+     * 3. Determine side from order.type, or derive from SPREAD price vs startPrice threshold
+     * 4. Aggregate sizes by side and state:
+     *    - ACTIVE/PARTIAL orders → committed.grid and committed.chain
+     *    - VIRTUAL orders → virtual pool
+     *    - Skip zero-sized orders
+     * 5. Calculate blockchain totals:
+     *    - chainTotalBuy = chainFreeBuy (from accountTotals) + chainBuy (committed on-chain)
+     *    - chainTotalSell = chainFreeSell + chainSell
+     * 6. Calculate available funds by subtracting committed amounts from blockchain totals
+     *    - available.buy = chainTotalBuy - committed.chain.buy (after grid allocation)
+     *    - available.sell = chainTotalSell - committed.chain.sell (after grid allocation)
+     * 7. Apply percentage-based fund allocations (botFunds) if configured
+     * 8. Verify fund invariants (total = free + committed) to detect tracking drift
+     *
+     * CRITICAL INVARIANTS MAINTAINED:
+     * - Total on-chain balance = Free portion + Committed portion
+     * - Virtual orders don't reduce blockchain-tracked free balance
+     * - Grid totals = committed amounts + virtual amounts (pending placements)
+     * - Available funds represent true spending power (after commitment deductions)
+     *
+     * @returns {void}
+     */
+    recalculateFunds(): Promise<void>;
+    /**
+     * Verify critical fund tracking invariants.
+     *
+     * Checks that accountTotals.buy/sell match chainFree + committed amounts
+     * within combined precision and percentage tolerances. Detects fee double-
+     * deductions, missing fills, and blockchain state desync.
+     *
+     * @param {Object} mgr - OrderManager instance
+     * @param {number} chainFreeBuy - Free (unallocated) buy-side balance from chain
+     * @param {number} chainFreeSell - Free (unallocated) sell-side balance from chain
+     * @param {number} chainBuy - Committed buy-side balance from chain
+     * @param {number} chainSell - Committed sell-side balance from chain
+     * @returns {void}
+     * @private
+     */
+    _verifyFundInvariants(mgr: any, chainFreeBuy: any, chainFreeSell: any, chainBuy: any, chainSell: any): Promise<void>;
+    /**
+     * Perform centralized state recovery (fetch + sync + validate).
+     * Shared by both immediate recovery and stabilization gate.
+     *
+     * @param {Object} mgr - Manager instance
+     * @returns {Promise<Object>} - Validation result from validateGridStateForPersistence()
+     */
+    _performStateRecovery(mgr: any): Promise<any>;
+    /**
+     * Attempt immediate recovery from fund invariant violations.
+     * Runs once per cycle - subsequent violations in same cycle are skipped.
+     *
+     * @param {Object} mgr - Manager instance
+     * @param {string} violationType - Description of the violation for logging
+     * @returns {Promise<boolean>} - True if recovery succeeded, false otherwise
+     */
+    _attemptFundRecovery(mgr: any, violationType: any): Promise<boolean>;
+    /**
+     * Reset the recovery attempt flag.
+     * Called at the start of each fill processing cycle to allow fresh recovery attempts.
+     * @returns {void}
+     */
+    resetRecoveryState(): void;
+    /**
+     * Check if sufficient funds exist AND atomically deduct (FREE portion only).
+     * PRIVATE: Must be called while holding _fundLock.
+     * @param {string} orderType - ORDER_TYPES.BUY or ORDER_TYPES.SELL
+     * @param {number} size - Amount to deduct from chainFree
+     * @param {string} [operation='move'] - Label for logging
+     * @returns {Promise<boolean>} true if deduction succeeded, false if insufficient funds
+     */
+    tryDeductFromChainFree(orderType: any, size: any, operation?: string): Promise<boolean>;
+    /**
+     * Add an amount back to the optimistic chainFree balance (FREE portion only).
+     * PRIVATE: Must be called while holding _fundLock.
+     * @param {string} orderType - ORDER_TYPES.BUY or ORDER_TYPES.SELL
+     * @param {number} size - Amount to add to chainFree
+     * @param {string} [operation='release'] - Label for logging
+     * @returns {Promise<boolean>} true if addition succeeded
+     */
+    addToChainFree(orderType: any, size: any, operation?: string): Promise<boolean>;
+    /**
+     * Record a fill in the optimistic total balances.
+     * PUBLIC API: Acquires _fundLock.
+     * @param {string} paysAsset - Asset symbol or ID the bot paid
+     * @param {number} paysAmount - Amount the bot paid
+     * @param {string} receivesAsset - Asset symbol or ID the bot received
+     * @param {number} receivesAmount - Amount the bot received
+     * @param {string} [context='fill'] - Label for logging
+     * @returns {Promise<void>}
+     */
+    recordFillBalances(paysAsset: any, paysAmount: any, receivesAsset: any, receivesAmount: any, context?: string): Promise<any>;
+    /**
+     * Adjust both total and free balances (for fills, fees, deposits).
+     * @param {string} orderType - ORDER_TYPES.BUY or ORDER_TYPES.SELL
+     * @param {number} delta - Amount to adjust
+     * @param {string} operation - Context for logging
+     * @param {boolean} totalOnly - If true, only adjust TOTAL balance, not FREE portion.
+     */
+    adjustTotalBalance(orderType: any, delta: any, operation: any, totalOnly?: boolean): void;
+    /**
+     * Normalize side hint to standard ORDER_TYPES constant.
+     * @param {string|null} sideHint - Side hint ('buy', 'sell', ORDER_TYPES.BUY, ORDER_TYPES.SELL, or null)
+     * @returns {string|null} Normalized side or null if unrecognised
+     */
+    _normalizeSideHint(sideHint: any): any;
+    /**
+     * Resolve the effective order side from multiple sources of truth.
+     * @param {Object|null} order - Order object carrying optional side hints
+     * @param {Object|null} [fallbackOrder] - Fallback order object
+     * @param {string|null} [explicitSideHint] - Explicit side override
+     * @returns {string|null} Resolved side (ORDER_TYPES.BUY, ORDER_TYPES.SELL) or null
+     */
+    _resolveOrderSide(order: any, fallbackOrder?: any, explicitSideHint?: any): any;
+    /**
+     * Update optimistic balance during transitions.
+     * @param {Object} oldOrder - Previous order state
+     * @param {Object} newOrder - New order state
+     * @param {string} context - Context for logging/tracking
+     * @param {number} fee - Blockchain fee to deduct
+     * @param {boolean} skipAssetAccounting - If true, skip capital commitment changes (asset amounts) but still process fees
+     */
+    updateOptimisticFreeBalance(oldOrder: any, newOrder: any, context: any, fee?: number, skipAssetAccounting?: boolean): Promise<void>;
+    /**
+     * Deduct BTS fees using adjustTotalBalance.
+     *
+     * Strategy: Accumulate fees in btsFeesOwed, then settle when sufficient funds available.
+     * - Fees are part of chainFree (not separate capital)
+     * - Full fee amount must reduce chainFree
+     * - Defers settlement if insufficient funds (will retry when funds become available)
+     * @param {string|null} [requestedSide=null] - ORDER_TYPES.BUY or ORDER_TYPES.SELL to target a specific side
+     * @returns {void}
+     */
+    deductBtsFees(requestedSide?: any): Promise<void>;
+    /**
+     * Validate that a proposed Target Grid fits within the account's total available funds.
+     * Prevents over-commitment before orders are broadcast.
+     *
+     * @param {Map} targetGrid - Proposed grid (price -> {size, type})
+     * @returns {Object} { isValid, shortfall, details }
+     */
+    validateTargetGrid(targetGrid: any): {
+        isValid: boolean;
+        shortfall: {
+            buy: number;
+            sell: number;
+        };
+        details: {
+            error: string;
+            requiredBuy?: undefined;
+            requiredSell?: undefined;
+            totalBuy?: undefined;
+            totalSell?: undefined;
+        };
+    } | {
+        isValid: boolean;
+        shortfall: {
+            buy: number;
+            sell: number;
+        };
+        details: {
+            requiredBuy: number;
+            requiredSell: number;
+            totalBuy: any;
+            totalSell: any;
+            error?: undefined;
+        };
+    };
+    /**
+     * Centralized fee deduction helper - prevents duplicate logic across codebase.
+     * Returns net proceeds after market fees, or raw amount if asset is not recognized.
+     * @param {string} assetSymbol - Asset symbol (e.g., 'BTS', 'XRP')
+     * @param {number} rawAmount - Amount before fees
+     * @param {boolean} isMaker - Whether this was a maker order (lower fee) vs taker (full fee)
+     * @returns {number} Net proceeds after fees, or rawAmount if symbol not found
+     * @private
+     */
+    _deductFeesFromProceeds(assetSymbol: any, rawAmount: any, isMaker: any): any;
+    /**
+     * Process the fund impact of an order fill.
+     * Atomically updates accountTotals to keep internal state in sync with blockchain.
+     * CRITICAL: Called within fill processing lock context to prevent race conditions.
+     * @param {Object} fillOp - Fill operation object from chain history
+     * @param {string} [fillKey=null] - Deduplication key for processed fill store
+     * @param {Object} [options={}] - Persistence mode options
+     * @returns {Promise<boolean>} true if fill was successfully processed
+     */
+    processFillAccounting(fillOp: any, fillKey?: any, options?: {}): Promise<boolean>;
+}
+export = Accountant;
+//# sourceMappingURL=accounting.d.ts.map

package/dist/modules/order/accounting.d.ts.map

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