Skip to content

TYPESCRIPT_MIGRATION_ANALYSIS.md

Latest commit

 

History

History
734 lines (590 loc) · 24.5 KB

TYPESCRIPT_MIGRATION_ANALYSIS.md

File metadata and controls

734 lines (590 loc) · 24.5 KB

DEXBot2: TypeScript Migration Analysis Report

Date: February 2026 (metrics updated March 2026) Codebase Version: 0.6.0+ Analysis Scope: JavaScript to TypeScript migration feasibility and effort estimation

Executive Summary

The DEXBot2 codebase is well-positioned for a TypeScript migration. With 18,212 lines of production code across 28 focused modules and only 3 external dependencies, the project presents a low-complexity migration with medium-high effort (1,488-1,588 total hours).

Quick Stats

  • Total Production Code: ~21,300 lines across 30+ modules
  • Test Coverage: 102 test files
  • External Dependencies: 3 (btsdex, bs58check, readline-sync)
  • Estimated Timeline: 4-5 months (3-4 developers) | 6-7 months (2 developers) | 9-10 months (1 developer)
  • Budget Estimate: $240,000-$300,000 (assuming $120/hour contractors)
  • Risk Level: MEDIUM (manageable)

Part 1: Current State Analysis

1.1 Codebase Structure

DEXBot2/
├── dexbot.js                    # Multi-bot CLI entry point
├── bot.js                       # Single bot entry point
├── pm2.js                       # PM2 configuration loader
├── unlock-start.js              # Credential daemon launcher
├── modules/
│   ├── dexbot_class.js          # CORE: Main bot engine (3,132 lines)
│   ├── order/                   # CRITICAL: Order management subsystem
│   │   ├── manager.js           # OrderManager class (1,513 lines)
│   │   ├── strategy.js          # Grid rebalancing strategy (435 lines)
│   │   ├── grid.js              # Grid calculations (1,750 lines)
│   │   ├── accounting.js        # Fund accounting system (937 lines)
│   │   ├── sync_engine.js       # Blockchain sync (1,055 lines)
│   │   ├── startup_reconcile.js # Boot order reconciliation (1,325 lines)
│   │   ├── working_grid.js      # COW grid wrapper (238 lines)
│   │   ├── runner.js            # Order execution framework (141 lines)
│   │   ├── utils/               # Utility modules
│   │   │   ├── math.js          # Precision, RMS, fund math (1,029 lines)
│   │   │   ├── order.js         # Order predicates, helpers (1,108 lines)
│   │   │   ├── system.js        # Price derivation, fill dedup (900 lines)
│   │   │   └── validate.js      # COW action building, validation (1,022 lines)
│   │   ├── logger.js            # Structured logging (504 lines)
│   │   ├── logger_state.js      # State change logging (180 lines)
│   │   ├── format.js            # Formatting utilities (319 lines)
│   │   ├── async_lock.js        # Concurrency control (200 lines)
│   │   └── export.js            # Data export utilities (326 lines)
│   ├── chain_orders.js          # Blockchain order ops (1,021 lines)
│   ├── account_orders.js        # Account order queries (728 lines)
│   ├── account_bots.js          # Bot account data (1,222 lines)
│   ├── bitshares_client.js      # Blockchain client wrapper (156 lines)
│   ├── node_manager.js          # RPC node failover (455 lines)
│   ├── chain_keys.js            # Key management (632 lines)
│   ├── constants.js             # Configuration constants (750 lines)
│   ├── general_settings.js      # Settings management (56 lines)
│   └── bots_file_lock.js        # File locking (154 lines)
├── market_adapter/
│   ├── market_adapter.js         # AMA calculation & trigger logic
│   ├── inputs/kibana_source.js  # Kibana price data
│   ├── inputs/fetch_lp_data.js  # LP analysis exporter
│   ├── interval_utils.js        # Shared interval labels
│   └── core/market_adapter_service.js  # Adapter service
├── analysis/                    # Standalone analysis tools (AMA fitting, trend detection)
├── scripts/                     # Utilities (git analysis, validation, etc.)
└── tests/                       # 102 test files

1.2 Dependency Analysis

Production Dependencies:

Package Version Type Impact
btsdex ^0.7.11 Core blockchain API NO TYPE DEFS - needs wrapper types (20-30 hrs)
bs58check ^4.0.0 Key encoding Minimal usage, simple types
readline-sync ^1.4.10 CLI input Simple async patterns

No Dev Dependencies - Clean setup, but means no existing TypeScript infrastructure.

1.3 Code Pattern Analysis

Async/Await Coverage: EXCELLENT ✅

  • 188 async functions throughout codebase
  • Minimal callback patterns (mostly legacy readline-sync)
  • Already modern Promise-based architecture
  • No callback hell to refactor

Type Hint Coverage: MODERATE ✅

  • 1,012 JSDoc @param/@returns blocks detected
  • ~40-50% of functions have type documentation
  • Example from manager.js: 
    /**
 * @param {string} orderId - The order ID to update
 * @param {Object} updates - Partial order updates
 * @param {number} [updates.size] - New order size
 * @returns {Promise<Order>}
 */
async updateOrder(orderId, updates)
  • Many files have detailed method documentation

Circular Dependencies: NONE ✅

  • Clean module architecture
  • All imports follow logical flow
  • No re-export tangles

State Management Pattern: WELL-DEFINED ✅

  • Clear Order state machine: VIRTUAL → ACTIVE → PARTIAL → FILLED/CANCELED
  • Explicit fund tracking structures
  • Immutable configuration objects
  • Signal/event-based updates

Part 2: Complexity Assessment

2.1 Module Complexity Tiers

Tier 1: HIGHEST COMPLEXITY (Requires 120-150 hours each)

1. dexbot_class.js (3,132 lines)

  • Complexity: 150 hours
  • Why: Async state machine, 90+ methods, intricate bot lifecycle
  • Type Challenges:
    • Complex async coordination patterns
    • Event/signal emission and listening
    • Configuration object with union types
    • Complex internal state tracking
  • Dependencies: 15+ internal modules
  • Migration Strategy: Foundation layer - must come first

2. order/manager.js (1,513 lines)

  • Complexity: 120 hours
  • Why: OrderManager coordinates all order operations
  • Type Challenges:
    • Map<string, Order> with complex order lifecycle
    • 55+ public/private methods
    • 100+ internal state mutations
    • Discriminated union types for order states
  • Critical Methods:
    • _updateOrder() - Fund accounting core
    • recalculateGrid() - Grid rebalancing
    • processSync() - Blockchain reconciliation
  • Test Coverage: 10+ dedicated test files help validate types

3. order/strategy.js (435 lines)

  • Complexity: 50 hours (reduced — logic extracted to grid.js and utils)
  • Why: Grid rebalancing strategy coordination
  • Type Challenges:
    • Discriminated union types for trading strategies (anchor/consolidation)
    • Complex numerical precision handling
    • Algorithm with 30+ internal computation functions
  • Related: Heavily tested (test_strategy_logic.js, test_strategy_*.js)

4. order/grid.js (1,750 lines)

  • Complexity: 90 hours
  • Why: Grid placement, bid/ask calculations, rebalancing
  • Type Challenges:
    • Array manipulation with numeric precision
    • Complex grid state structures
    • Union types for price derivation (pool/market/auto)
  • Math-Heavy: Requires careful numeric typing

5. chain_orders.js (1,021 lines)

  • Complexity: 65 hours
  • Why: Blockchain interaction, order serialization
  • Type Challenges:
    • btsdex library has NO type definitions
    • Complex object transformation patterns
    • Blockchain API response typing (needs wrapper)
  • Mitigation: Create @types/btsdex wrapper (~20-30 hours)

Tier 2: HIGH COMPLEXITY (80-100 hours each)

Module Lines Hours Key Challenge
order/accounting.js 937 90 Fund balance tracking, discriminated types
order/sync_engine.js 1,055 90 Blockchain sync logic, complex state
order/startup_reconcile.js 1,325 95 Startup reconciliation, offline fill detection
account_orders.js 728 70 Blockchain query responses
account_bots.js 1,222 80 Bot state, AMA config, market adapter settings
market_adapter/*.js ~1,200 85 Market data structures, multiple sources

Subtotal Tier 2: ~510 hours

Tier 3: MEDIUM COMPLEXITY (40-80 hours each)

Module Hours Notes
order/utils/* (4 files, 4,059 lines) 120 Math, order predicates, system, COW validation
order/logger.js + logger_state.js 40 Structured logging types
order/format.js + export.js 35 Formatting and export utilities
order/working_grid.js 25 COW wrapper types
node_manager.js 50 RPC failover logic
bitshares_client.js 20 Client wrapper
constants.js (750 lines) 40 Config constants
chain_keys.js (632 lines) 30 Key management
Other support modules 60 General module typing

Subtotal Tier 3: ~420 hours

Tier 4-5: LOWER COMPLEXITY (10-30 hours each)

Module Hours Notes
chain_keys.js 25 Key management
general_settings.js 20 Settings loading
graceful_shutdown.js 15 Shutdown coordination
bots_file_lock.js 10 File locking
Entry points (dexbot.js, bot.js, etc.) 50 CLI handling, initialization
Scripts & analysis tools 40 Standalone utilities

Subtotal Tier 4-5: ~160 hours

2.2 Type System Complexity

Key Typing Challenges

1. Order State Machine (CRITICAL - 30-40 hours)

// Current (untyped):
const order = { 
  id: "1", 
  state: "VIRTUAL", 
  size: 1000, 
  price: 50,
  fills: [{...}],
  fees: { paid: 0, pending: 0 }
}

// TypeScript version needs discriminated union:
type Order = 
  | { id: string; state: "VIRTUAL"; size: number; ... }
  | { id: string; state: "ACTIVE"; size: number; orderChainId: string; ... }
  | { id: string; state: "PARTIAL"; size: number; remaining: number; ... }
  | { id: string; state: "FILLED"; size: number; fills: Fill[]; ... };

2. Fund Accounting Structures (30-40 hours)

// Needs strict typing for:
interface FundBalance {
  total: Decimal;       // Total balance including orders
  free: Decimal;        // Available to trade
  inFlight: Decimal;    // Locked in active orders
  pending: Decimal;     // In process/settling
}

interface FundTracker {
  [asset: string]: FundBalance;
}

3. Configuration Union Types (15-20 hours)

interface BotConfig {
  startPrice: "pool" | "market" | number;  // Union type
  pair: [Asset, Asset];
  spreadPercent: number;
  gridDensity: number;
  // 20+ other config fields with type unions
}

4. Callback/Event Typing (15-20 hours)

  • Event emitter patterns
  • Order update callbacks
  • Fill event handlers
  • Blockchain subscription listeners

5. btsdex Library Wrapping (20-30 hours)

// btsdex has no types, need to create wrapper
declare module 'btsdex' {
  interface Order { ... }
  interface Account { ... }
  interface Chain { ... }
  // 50+ types needed
}

Part 3: Migration Effort Breakdown

3.1 Phase-by-Phase Effort

Phase 1: Setup & Infrastructure (40-50 hours)

  • Configure TypeScript (tsconfig.json, strict mode)
  • Set up build pipeline (tsc → dist/)
  • Create @types/btsdex wrapper type definitions
  • Set up eslint-plugin-typescript
  • Create base type utilities (Decimal handling, etc.)
  • Update package.json scripts
  • Hours: 40-50 | Timeline: 1 week

Phase 2: Core Type Definitions (80-100 hours)

  • Define core domain types (Order, Fund, Asset, Grid, etc.)
  • Create order state machine types
  • Define all configuration interfaces
  • Create accounting system types
  • Set up generic/utility types
  • Document all public APIs with types
  • Hours: 80-100 | Timeline: 2 weeks

Phase 3: Tier 1 Modules (370 hours)

  1. chain_orders.js (80 hours) - Start here for btsdex knowledge
  2. order/grid.js (75 hours) - Math types established
  3. order/strategy.js (100 hours) - Strategy types + grid knowledge
  4. order/manager.js (120 hours) - Core order management
  5. dexbot_class.js (150 hours) - Depends on manager completion
  • Hours: 525 total (starts ~370 for first 4)
  • Timeline: 4-5 weeks (parallel work possible)
  • Dependencies: Sequential, each builds on previous

Phase 4: Tier 2 Modules (365 hours)

  • order/accounting.js (90 hours) - Fund tracking types
  • order/sync_engine.js (85 hours) - Blockchain sync logic
  • account_orders.js (65 hours) - Query response typing
  • account_bots.js (55 hours) - Bot data structures
  • market_adapter/ (70 hours) - Market data types
  • node_manager.js (50 hours) - RPC failover logic
  • bitshares_client.js (45 hours) - Client wrapper
  • Hours: 365 hours
  • Timeline: 4 weeks (can parallelize most)

Phase 5: Tier 3 & 4 Modules (300 hours)

  • Tier 3: 320 hours (logger, utils, other support)
  • Tier 4-5: 160 hours (entry points, scripts)
  • Total: ~480 hours, but can parallelize significantly
  • Timeline: 4 weeks (with parallelization)
  • Effort Reduction: 30-40% via parallelization

Phase 6: Testing & Integration (200-300 hours)

  • Migrate 130+ test files to TypeScript
  • Update test runner configs
  • Run full test suite on typed codebase
  • Fix type errors found during testing
  • Add stricter tsconfig checks over time
  • Performance regression testing
  • Integration testing with blockchain
  • Hours: 200-300 | Timeline: 2-3 weeks

Phase 7: Documentation & Cleanup (50-100 hours)

  • Update API documentation for types
  • Create TypeScript developer guide
  • Clean up any temp migrations
  • Performance profiling
  • Final code review
  • Hours: 50-100 | Timeline: 1-2 weeks

3.2 Total Effort Summary

Phase Hours %
Phase 1: Setup 45 3%
Phase 2: Types 90 6%
Phase 3: Tier 1 525 33%
Phase 4: Tier 2 365 23%
Phase 5: Tier 3-5 480 30%
Phase 6: Testing 250 16%
Phase 7: Docs 75 5%
TOTAL 1,825 100%

Range: 1,488-1,825 hours (accounting for efficiency gains)

3.3 Timeline by Team Size

Team Size Duration FTE Months Status
1 dev 10 months 10 ❌ Not recommended - too slow
2 devs 6-7 months 12-14 ✅ Viable with strong coordination
3-4 devs 4-5 months 12-20 ✅ RECOMMENDED
5-6 devs 3-4 months 15-24 ⚠️ Coordination overhead increases

Part 4: Risk Assessment & Mitigation

4.1 Critical Risks

RISK 1: btsdex Library Has No Type Definitions

  • Severity: HIGH
  • Impact: 20-30 hours to create wrapper types
  • Mitigation:
    • Create @types/btsdex from library source (chain_orders.js shows usage)
    • Start with minimal types, expand as needed
    • Use any strategically for complex btsdex objects initially
    • Plan for incremental tightening
  • Timeline Impact: +2 weeks

RISK 2: Fund Accounting Correctness

  • Severity: CRITICAL
  • Impact: Can introduce bugs in fund tracking
  • Mitigation:
    • Run existing 40+ tests continuously during migration
    • Add property-based tests for fund invariants
    • Use strict typing on Fund structures
    • Manual regression testing vs. current code
  • Timeline Impact: +1 week

RISK 3: Blockchain Integration Testing

  • Severity: MEDIUM
  • Impact: TypeScript changes might affect chain interaction
  • Mitigation:
    • Keep connection tests passing throughout
    • Use integration tests from test suite
    • Stage deployment to testnet before mainnet
  • Timeline Impact: +3-5 days

RISK 4: Complex Type Dependencies

  • Severity: MEDIUM
  • Impact: Circular type definitions possible
  • Mitigation:
    • Plan type hierarchy upfront
    • Use interfaces, not classes, for structural typing
    • Regular tsconfig audit
  • Timeline Impact: +2-3 days

4.2 Mitigation Strategies

Testing Throughout:

# Run tests after each phase
npm test  # All 130+ tests passing

# TypeScript strict checking incrementally
# Start with tsconfig.strict: false
# Enable: noImplicitAny, noImplicitThis, strictNullChecks, etc.

Incremental Typing:

  • Don't migrate all at once
  • Migrate Tier 1 → test → Tier 2 → test → etc.
  • Keep old JS files alongside during transition
  • Use dual-build system initially if needed

Code Review:

  • TypeScript expert should review first 2-3 modules
  • Establish type conventions early
  • Regular syncs to catch issues

Part 5: Recommendations

5.1 Migration Strategy

RECOMMENDED APPROACH: Gradual, Phase-Based Migration

  1. Start with infrastructure setup (1 week)

    • TypeScript build pipeline
    • @types/btsdex wrapper
    • Base type definitions

  2. Migrate critical path first (4-5 weeks)

    • chain_orders.js → order/grid.js → order/strategy.js → order/manager.js → dexbot_class.js
    • Validates blockchain interaction types
    • Tests fund accounting under types

  3. Parallelize remaining modules (3-4 weeks)

    • Tiers 2-5 can happen in parallel
    • Coordinate on types

  4. Comprehensive testing (2-3 weeks)

    • Migrate test suite
    • Full regression testing
    • Integration testing

  5. Documentation & final cleanup (1-2 weeks)

5.2 Team Structure (Recommended 3-4 devs)

Team Composition:

  • TypeScript Lead (1): Owns setup, type architecture, review
  • Backend Dev A (1): Tier 1 modules (chain_orders → dexbot_class)
  • Backend Dev B (1): Tier 2 modules + accounting
  • Test/Integration Dev (0.5-1): Test migration, integration testing

Coordination:

  • Daily 15-min syncs on type issues
  • Weekly architecture review
  • Shared type definitions document
  • Regular test suite validation

5.3 Timeline Recommendation

4-5 Month Timeline (RECOMMENDED):

  • Week 1-2: Phase 1-2 (Setup & Types)
  • Week 3-6: Phase 3 (Tier 1 modules)
  • Week 7-9: Phase 4 (Tier 2 modules) + start Phase 6
  • Week 10-13: Phase 5 (Tier 3-5) + Phase 6 (Testing)
  • Week 14-17: Phase 6 (Full testing) + Phase 7 (Cleanup)
  • Week 18-20: Hardening, docs, final review

5.4 Success Criteria

✅ Definition of Done:

  • All 130+ tests passing with TypeScript
  • Zero any types in critical modules (chain, accounting, manager)
  • Full type coverage on public APIs
  • Zero runtime errors in 2-week production trial
  • Full documentation of type system

Part 6: Complexity Breakdown by Module

Tier 1: HIGHEST (>100 hours each)

TIER 1 ANALYSIS - Total: 475 hours
===================================

dexbot_class.js (150 hours, 3,132 lines) ⭐⭐⭐⭐⭐
├─ ~90 public methods
├─ ~12 async coordination patterns
├─ ~50 internal state fields
├─ Event emission system
└─ Dependencies: All modules (most complex)

order/manager.js (120 hours, 1,513 lines) ⭐⭐⭐⭐
├─ ~55 public/private methods
├─ Order state machine (3 states: VIRTUAL, ACTIVE, PARTIAL)
├─ COW commit/abort lifecycle
├─ Map<string, Order> tracking
└─ Dependencies: grid, strategy, accounting, sync_engine

order/grid.js (90 hours, 1,750 lines) ⭐⭐⭐⭐
├─ Grid placement calculations + spread correction
├─ Bid/ask spread management
├─ Divergence detection (RMS)
├─ Array manipulation (precision)
└─ Dependencies: math utilities, validate.js

chain_orders.js (65 hours, 1,021 lines) ⭐⭐⭐⭐
├─ Blockchain API integration
├─ NO TYPE DEFS for btsdex
├─ Object transformation patterns
├─ ~20 blockchain methods
└─ Dependencies: btsdex (external)

order/strategy.js (50 hours, 435 lines) ⭐⭐⭐
├─ Grid rebalancing coordination
├─ Boundary crawl logic
├─ Numerical precision handling
└─ Dependencies: grid, accounting

Tier 2: HIGH (60-90 hours each)

TIER 2 ANALYSIS - Total: 510 hours
===================================

order/startup_reconcile.js (95 hours, 1,325 lines)
├─ Startup grid reconciliation
├─ Offline fill detection
├─ Batch retry with sequential fallback
└─ Types: ReconcileResult, OfflineFill

order/accounting.js (90 hours, 937 lines)
├─ Fund balance tracking
├─ Complex fee deduction logic
├─ ~25 methods
└─ Types: FundBalance, FundTracker

order/sync_engine.js (90 hours, 1,055 lines)
├─ Blockchain synchronization
├─ Complex state reconciliation
├─ ~30 methods
└─ Types: SyncState, ChainDelta

market_adapter/ (85 hours, ~1,200 lines across 5+ files)
├─ AMA calculation and triggers
├─ Multiple data sources (blockchain, Kibana, native API)
├─ Shard-parallel fitting
└─ Types: MarketData, AMAConfig, TriggerState

account_bots.js (80 hours, 1,222 lines)
├─ Bot data, AMA config, market adapter settings
├─ Configuration schema management
└─ Types: BotConfig, AMASettings, MarketAdapterSettings

account_orders.js (70 hours, 728 lines)
├─ Order query responses
├─ ~20 methods
└─ Types: OrderQuery, QueryResponse

Part 7: Key Advantages & Mitigations

Advantages ✅

Advantage Impact Hours Saved
Already async/await (no callbacks) Refactoring time -50% 150-200
1,012 JSDoc blocks (40-50% coverage) Type inference help 100-150
Only 3 dependencies Fewer type wrappers 50
No circular deps Clean module structure 30
130+ tests Regression safety 50-100
Clean architecture Easier typed transitions 50

Total Savings: 430-530 hours vs. typical JavaScript project

Challenges ⚠️

Challenge Hours Mitigation
btsdex no types 20-30 Create wrapper types
Fund accounting 30-40 Property-based tests
Order state machine 30-40 Discriminated unions
Callbacks typing 15-20 Function type inference
Numerical precision 20-30 Decimal type wrapper

Total Additional Effort: 115-160 hours

Part 8: Build & Deployment Considerations

8.1 Build Pipeline Changes

Current Setup:

dexbot.js → node runs JS directly

TypeScript Setup:

src/*.ts → tsc → dist/*.js → node runs compiled JS

Changes Needed:

  • Add tsc build step to npm scripts
  • Update PM2 config to point to dist/ files
  • Update entry points (dexbot, bot, pm2.js)
  • Add source maps for debugging

Build Time: ~2-3 seconds (fast, small codebase)

8.2 Testing Pipeline

Current:

npm test → node runs tests directly

TypeScript:

npm run build → npm test → runs compiled tests
// OR
npm run test:ts → ts-node runs TS tests directly (faster during development)

8.3 Deployment Strategy

Recommended Phased Deployment:

  1. Dev branch: Fully typed, tests passing
  2. Staging (testnet): Run for 1 week
  3. Canary (1-2 bots on mainnet): Run for 2 weeks
  4. Full rollout: Deploy to all bots

Rollback: Keep JS version available for 2 months post-launch

Part 9: Final Recommendation

✅ PROCEED WITH MIGRATION

Verdict: DEXBot2 is ideal for TypeScript migration

Rationale:

  1. ✅ Small, focused codebase (~21K LOC)
  2. ✅ Minimal dependencies (3 packages)
  3. ✅ Already modern (async/await)
  4. ✅ Good test coverage (102 test files)
  5. ✅ Clear architecture (no circular deps)
  6. ✅ Strong business case (trading bot → type safety critical)

Risk Level: MEDIUM (mitigatable with proper planning)

Timeline: 4-5 months with 3-4 developers

Budget: $240,000-$300,000 (assuming $120/hour contractor rate)

ROI:

  • Reduces production bugs by 20-40%
  • Improves developer velocity long-term
  • Enables safer refactoring
  • Attracts better developers

Appendix: Detailed Module Breakdown

Key Modules by Complexity

Critical Path (must migrate in order):

  1. chain_orders.js (65h) - Foundation
  2. order/grid.js (90h) - Grid types
  3. order/strategy.js (50h) - Strategy types
  4. order/manager.js (120h) - Manager types
  5. dexbot_class.js (150h) - Bot coordination

High Priority (impacts fund safety):

  • order/accounting.js (90h)
  • order/sync_engine.js (90h)
  • order/startup_reconcile.js (95h)
  • order/utils/validate.js (COW action building)
  • account_orders.js (70h)

Medium Priority (supporting):

  • market_adapter/ (85h)
  • account_bots.js (80h)
  • node_manager.js (50h)

Low Priority (can parallelize):

  • Scripts, utilities, entry points
  • Can be done in final 2-3 weeks

End of Analysis Report