docs

DEXBot2 Documentation

This directory contains the comprehensive technical documentation for the DEXBot2 trading bot. It is designed to guide developers from high-level architecture down to the nuances of fund accounting and state management.

---

🛠️ Core System Documentation

🏛️ Architecture

The blueprint of the system.

• Design Philosophy: Simplicity, constant spread, minimal blockchain interaction, and closed-loop market dynamics.
• System Design: High-level overview of how the bot components interact.
• Module Responsibilities: Detailed breakdown of the Manager, Accountant, Strategy, and Grid modules.
• Copy-on-Write Pattern: Safe concurrent rebalancing with isolated working grids (see COPY_ON_WRITE_MASTER_PLAN.md)
• Fill Processing Pipeline: Fixed-cap batch fill processing (1-4 fills per broadcast, ~24s for 29 fills)
• Fund-Driven Boundary Sync: Automatic grid alignment with inventory distribution
• Spread Correction: Conservative, fund-aware maintenance of constant spread width
• Periodic Market Price Refresh: Background 4-hour price updates
• Pipeline Safety & Diagnostics: 5-minute timeout safeguard and health monitoring
• Data Flow: Visualization of how market data becomes trading operations and then blockchain transactions.

📖 Developer Guide

Your daily companion for coding.

• Quick Start: How to get the development environment running.
• Module Deep-Dive: In-depth analysis of the internal logic of each primary module.
• Copy-on-Write Pattern: How to work safely within the COW rebalance pipeline; WorkingGrid usage and master-grid commit rules (see COPY_ON_WRITE_MASTER_PLAN.md)
• Startup Sequence & Lock Ordering: Consolidated startup with deadlock prevention
• Zero-Amount Order Prevention: Validation gates for healthy order sizes
• Configurable startPrice: Fixed numeric, pool, or market-derived pricing modes
• Pool ID Caching: Optimization for price derivation
• Order State Helper Functions: Centralized predicate functions for state checking
• Common Tasks: Practical "how-to" guides for adding features or fixing bugs.
• Glossary: Definitions of project-specific terminology (e.g., "Virtual Orders", "Rotation", "Pipeline Safety", "Fund-Driven Boundary", "WorkingGrid", "COW Commit").

🔄 Workflow

How we build and release.

• Branching Strategy: Explanation of the test → dev → main lifecycle.
• CI/CD Patterns: Standards for merging and ensuring code quality across branches.

---

🔬 Specialized Technical References

💰 Fund Movement & Accounting

The most critical part of the bot: safe capital management.

• Single Source of Truth: How the bot avoids double-spending and out-of-sync balances.
• Optimistic ChainFree: The mechanism that allows the bot to trade with fill proceeds before they are finalized on-chain.
• Fill Batch Processing: Fixed-cap batching for efficient fill processing (<=4 unified, >4 chunked)
• Partial Order Consolidation: Simplified, direct consolidation through grid rebuilding (no merge/split mechanics)
• Dust Detection & Management: Unhealthy partials are absorbed into next grid rebuild cycle or auto-cancelled on-chain after a configurable delay (DUST_CANCEL_DELAY_MIN)
• BTS Fee Object Structure: netProceeds field for accounting precision
• BUY Side Sizing & Fee Accounting: Correct fee application by order side
• Mixed Order Fund Validation: Separate validation for BUY vs SELL order fund checks
• Fee Management: Detailed logic for BTS fee reservations and market fee deductions.

📊 Grid Recalculation

When and why the grid resets.

• Three Independent Triggers: AMA Delta (market move), RMS Divergence (state drift), and Cache Regeneration (fund accumulation)
• Configuration: Per-trigger thresholds and their defaults
• AMA Delta: How the market adapter's price signal drives grid repositioning

📝 Logging System

Observability and debugging.

• Severity Levels: Guidelines on using info, warn, error, and debug.
• Log Rotation: Configuration for managing log file sizes and retention.
• Performance: How the logging system minimizes overhead during high-frequency events.
• Batch Processing Logs: Fill batching, recovery retry, and orphan-fill deduplication messages.

🧪 Test Suite Updates

Reliability and regression testing.

• Recent Fixes: Summary of test coverage added for the most recent critical bugfixes.
• Integration Scenarios: Documentation of complex multi-fill and partial-fill test cases.
• Fill Batching Tests: Regression tests for fixed-cap batching and recovery retry system.
• Verification: How to use the test suite to validate grid stability.

---

📂 Source Code Map

While these docs explain the why, the how lives in the code. Key source modules:

Core Modules:

• modules/dexbot_class.js: Bot initialization, account setup, order placement, fill processing, and rebalancing
• modules/order/manager.js: Central controller with Copy-on-Write rebalancing pattern (see COPY_ON_WRITE_MASTER_PLAN.md)
• modules/order/working_grid.js: COW grid wrapper enabling safe concurrent rebalancing with isolated modifications
• modules/order/grid.js: Grid generation, sizing, divergence detection, and spread management
• modules/order/accounting.js: Fund tracking, available balance calculation, fee deduction, and committed fund management
• modules/order/strategy.js: Grid rebalancing, order activation, consolidation, rotation, and spread management
• modules/order/sync_engine.js: Blockchain synchronization, fill detection, order reconciliation

Utilities & Support:

• modules/order/utils/math.js: Precision conversions, RMS divergence calculation, fund allocation math
• modules/order/utils/order.js: Order state predicates, grid indexing, reconciliation helpers, delta building, index utilities
• modules/order/utils/validate.js: Order validation, grid reconciliation, COW action building
• modules/order/utils/system.js: System utilities, price derivation, fill deduplication
• modules/order/startup_reconcile.js: Startup grid reconciliation and offline fill detection