How CloddsBot's Backtesting Framework Validates Strategy Performance: A Technical Deep Dive

CloddsBot validates trading strategies by replaying historical market data through a simulation engine that computes over 20 risk-adjusted performance metrics, including Monte Carlo stress testing to ensure robustness.

The alsk1992/CloddsBot repository provides a comprehensive backtesting framework that validates strategy performance through rigorous historical simulation and statistical analysis. Located primarily in src/trading/backtest.ts, the engine supports both bar-level and tick-level replay modes while calculating metrics like Sharpe ratio, Sortino ratio, and maximum drawdown to assess risk-adjusted returns.

Engine Initialization and Configuration

The validation process begins with the BacktestEngine, instantiated via createBacktestEngine(db) in src/trading/backtest.ts (lines 22-34). This factory function accepts a Database instance—typically SQLite or SQL—that serves as the source for historical trade data.

The engine relies on a BacktestConfig object that defines the simulation parameters. According to the source code (lines 23-38), this configuration includes:

• Start and end dates for the simulation period
• Initial capital allocation
• Commission percentage and slippage percentage to model transaction costs realistically
• Resolution settings for data granularity
• Risk-free rate for calculating excess returns

These defaults ensure every strategy validation accounts for real-world trading friction before any metrics are computed.

Historical Data Loading Pipeline

CloddsBot supports two distinct data ingestion modes depending on the required precision level.

For price-bar backtests, the engine calls loadPricesFromTrades within the run method (lines 97-108). This aggregates historic price bars—typically hourly intervals—for every platform and market utilized by the strategy. The function queries the database to construct a chronological sequence of closing prices that serves as the simulation timeline.

For tick-replay backtests, the engine leverages runFromTickRecorder (lines 107-113). This higher-precision mode pulls raw tick data and optional order-book snapshots directly from the Tick-Recorder service. Tick-level validation is essential for high-frequency strategies where intrabar price movements significantly impact performance.

Simulation Execution Loops

Once data is loaded, CloddsBot executes the strategy through specialized simulation loops that differ by data granularity.

Bar-Level Simulation

The runWithData method (lines 44-68) orchestrates bar-level backtesting. It constructs a chronological timeline of close prices, then iterates through each price point. At every step, the engine builds a StrategyContext object containing:

• Current portfolio value and cash position
• Open positions and recent trade history
• Latest market price data

The engine calls strategy.evaluate(ctx) to obtain trading signals, then applies those signals to update cash balances, position states, and trade records (lines 73-124). This loop continues until the end date is reached, generating a complete equity curve and trade log.

Tick-Level Precision

For scenarios requiring sub-minute accuracy, runWithTicks (lines 124-170) processes raw tick data while respecting an evaluation interval (evalIntervalMs). This method prevents over-trading by limiting strategy evaluation frequency while still capturing rapid price movements. When available, order-book data integrates into the context to simulate fill quality and market impact.

Comprehensive Metrics Calculation

After simulation completion, calculateMetrics(trades, equityCurve, cfg) (lines 73-95) derives over 20 statistical measures from the raw performance data. The CloddsBot framework computes:

• Return metrics: Total and annualized percentage returns
• Risk ratios: Sharpe, Sortino, and Calmar ratios for risk-adjusted performance assessment
• Drawdown analysis: Maximum drawdown percentage and drawdown duration
• Trade statistics: Win rate, profit factor, and expectancy
• Cost analysis: Total commission and slippage impact on final equity

The function returns these values within a BacktestResult object that bundles the strategy ID, configuration, complete trade log, equity curve time series, daily returns, drawdown series, and the computed metrics (lines 94-101).

Advanced Validation Techniques

Beyond basic backtesting, CloddsBot incorporates sophisticated statistical methods to validate strategy robustness.

Monte Carlo Simulation

The monteCarlo(result, simulations) function (lines 120-152) performs stress testing by reshuffling the historical daily returns to generate thousands of alternate equity curve paths. This process produces a probability distribution of outcomes, reporting:

• Percentile returns (5th, 50th, 95th percentiles)
• Probability of profit across random return sequences
• Probability of a greater than 20% loss
• Expected value under simulated uncertainty

This technique helps distinguish robust strategies from those relying on fortunate historical sequencing.

Strategy Comparison

The compare(strategies, config) method (lines 104-118) enables portfolio optimization by running multiple strategies against identical historical conditions. It ranks results by Sharpe ratio, providing an objective "best performer" view that accounts for risk-adjusted returns rather than raw profitability alone.

Summary

• Core Engine: Located in src/trading/backtest.ts, the createBacktestEngine function initializes the validation pipeline with database connectivity and configuration parameters.
• Dual Modes: The framework supports both bar-level (runWithData) and tick-level (runWithTicks) simulation to match strategy timeframes.
• Rich Metrics: The calculateMetrics function computes comprehensive statistics including Sharpe, Sortino, and Calmar ratios alongside drawdown and cost analysis.
• Statistical Rigor: Monte Carlo simulation reshuffles returns to test strategy robustness, while the compare method ranks alternatives by risk-adjusted performance.
• TypeScript Implementation: All components expose strongly-typed interfaces for Strategy and StrategyContext, ensuring type-safe strategy development.

Frequently Asked Questions

What file contains the core backtesting logic in CloddsBot?

The primary implementation resides in src/trading/backtest.ts. This file exports createBacktestEngine, calculateMetrics, monteCarlo, and the compare function, alongside the BacktestEngine class that orchestrates the entire validation pipeline.

How does CloddsBot calculate risk-adjusted performance metrics?

The engine computes risk-adjusted metrics through the calculateMetrics function called at the end of every simulation. It derives the Sharpe ratio (return per unit of total volatility), Sortino ratio (return per unit of downside volatility), and Calmar ratio (return relative to maximum drawdown), providing a multi-dimensional view of risk-adjusted performance.

What is the difference between bar-level and tick-level backtesting in CloddsBot?

Bar-level backtesting uses the runWithData method to simulate trading on aggregated price bars—typically hourly closes—making it suitable for swing trading strategies. Tick-level backtesting via runFromTickRecorder processes individual market ticks with configurable evaluation intervals (evalIntervalMs), providing the precision necessary for high-frequency or scalping strategies that depend on intrabar price action.

How does Monte Carlo simulation work in CloddsBot's framework?

The monteCarlo(result, simulations) function takes a completed backtest result and reshuffles its daily returns to create thousands of synthetic equity curves. By analyzing the distribution of these permutations, the framework calculates the probability of profit, the likelihood of severe losses exceeding 20%, and various percentile outcomes—helping traders understand how their strategy might perform under different historical scenarios.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}