v0.4.6 - CacheFunds Double-Counting Fix & Fill Deduplication

Release v0.4.6 - Critical Bug Fixes: CacheFunds Double-Counting, Fill Deduplication & Race Conditions

🔴 23 Critical Bugs Fixed

1. CRITICAL: CacheFunds Double-Counting in Partial Fills

• Location: modules/order/manager.js lines 570-596, 1618-1625
• Problem: Proceeds being counted twice in cacheFunds balance
  • When partial fill occurred, proceeds added to chainFree, then available recalculated from updated chainFree (which already included proceeds)
  • Both proceeds + available added to cacheFunds → double-counting
• Impact: User reported 649.72 BTS discrepancy in fund accounting
• Bug Timeline: Introduced in v0.4.0, present through v0.4.5
• Solution: Calculate available BEFORE updating chainFree, use pre-update value in processFilledOrders()

2. CRITICAL: Fee Double-Deduction After Bot Restart

• Location: modules/account_orders.js lines 427-551, modules/dexbot_class.js lines 42-48, 77-251, 652-660
• Problem: Permanent fund loss on bot restart during fill processing
  • When bot restarts, same fills detected again from blockchain history
  • processFilledOrders() called twice with identical fills
  • BTS fees double-deducted from cacheFunds
• Impact: Every bot restart during active trading could lose funds
• Solution: Persistent fill ID deduplication with multi-layer protection
  • In-Memory Layer (5 seconds): Prevents immediate reprocessing
  • Persistent Layer (1 hour): Saves fill IDs to disk, loads on startup
  • Automatic Cleanup: Removes entries older than 1 hour
  • AsyncLock Protection: Prevents race conditions during writes
• Defensive Impact: Protects entire fill pipeline (committed funds, fund cycling, grid rebalancing, order status)

3. 20+ Race Conditions: TOCTOU & Concurrent Access

AsyncLock Implementation: 7 lock instances protecting critical sections across the codebase

A. File Persistence Races - Prevent stale in-memory data overwrites

• Lock: _persistenceLock (account_orders.js)
• Protected: storeMasterGrid, updateCacheFunds, updateBtsFeesOwed, ensureBotEntries, processedFills methods
• Pattern: Reload-before-write to prevent Process-A-reads → Process-B-writes → Process-A-overwrites scenarios

B. Account Subscription Management Races - Prevent duplicate subscriptions

• Lock: _subscriptionLock (chain_orders.js)
• Protected: _ensureAccountSubscriber, listenForFills, unsubscribe
• Result: Atomic subscription creation and callback management

C. Account Resolution Cache Races - Atomic name/ID resolution

• Lock: _resolutionLock (chain_orders.js)
• Protected: resolveAccountName, resolveAccountId
• Result: Atomic cache check-and-set operations

D. Preferred Account State Races - Thread-safe global state

• Lock: _preferredAccountLock (chain_orders.js)
• Protected: setPreferredAccount, getPreferredAccount
• Pattern: All access through thread-safe getters/setters

E. Fill Processing Races - Serialized fill event handling

• Lock: _fillProcessingLock (dexbot_class.js)
• Protected: Fill callback, triggered resync, order manager loop
• Result: Prevents concurrent modifications during fill processing

F. Divergence Correction Races - Grid update serialization

• Lock: _divergenceLock (dexbot_class.js)
• Protected: Post-rotation divergence, timer-based divergence
• Result: Grid updates serialized, prevents concurrent conflicts

G. Order Corrections List Races - Foundation for serialized price correction

• Lock: _correctionsLock (manager.js)
• Status: Declared and prepared for active use
• Arrays affected: ordersNeedingPriceCorrection at 11 locations

📊 Files Modified

New:

• modules/order/async_lock.js (84 lines): FIFO queue-based synchronization utility

Modified (specific locations):

• modules/account_orders.js: Persistence lock, reload-before-write, processedFills tracking
• modules/chain_orders.js: 3 lock instances, thread-safe account management
• modules/dexbot_class.js: Fill dedup, lock declarations, persistent fill loading
• modules/order/manager.js: Cachefunds fix, pre-update available calculation

🔍 Technical Details

• Reload-Before-Write Pattern: Always reload from disk immediately before writing to prevent stale data overwrites
• Async/Await Consistency: All persistence methods properly awaited, no fire-and-forget promises
• Lock Nesting Prevention: No nested lock acquisition, prevents deadlocks
• Fill Dedup Storage Format: Persistent storage in profiles/orders/{botKey}.json with fill key: ${orderId}:${blockNum}:${historyId}

✓ Testing & Safety

• All 20 integration tests passing ✅
• Test coverage: ensureBotEntries, storeMasterGrid, cacheFunds persistence, fee deduction, fill dedup
• No changes to fill processing logic or output (only adds deduplication layer)
• Low-risk: Simple addition of locks to existing code paths, no core algorithm changes
• Backward compatible: No breaking changes, fully transparent to users

📈 Performance

• Minimal Overhead: Efficient FIFO queue, millisecond lock durations, ~5ms disk read negligible vs network latency
• Benefits: Eliminates fund loss, prevents duplicate processing, ensures consistent state recovery
• Cleanup Strategy: Runs ~10% of batches, not every batch (reduces I/O overhead)

🔒 Migration

• Backward Compatible: No API or configuration changes
• No Schema Changes: File format unchanged, existing bot data continues to work
• Automatic Initialization: processedFills field auto-initialized if missing

📋 Summary

Total Fixes: 23 critical bugs

• 1 cacheFunds double-counting fix
• 1 fee double-deduction fix
• 20+ race condition fixes (7 categories)
• 1 defensive fill deduplication system

Implementation: 7 AsyncLock instances, ~300 LOC, 5 files modified + 1 new, 20/20 tests ✅

Commits:

• f7cb80c - fix: prevent cacheFunds double-counting in partial fill processing
• 969f98b - feat: add persistent fill ID deduplication to prevent fee double-deduction
• cf39cd7 - docs: expand v0.4.6 CHANGELOG with comprehensive race condition and bug fix details