backtest-kit 3.0.17 → 3.1.0

package/README.md

@@ -555,6 +555,28 @@ cd my-trading-bot
 npm start
 ```
 
+
+### @backtest-kit/graph
+
+> **[Explore on NPM](https://www.npmjs.com/package/@backtest-kit/graph)** 🔗
+
+The **@backtest-kit/graph** package lets you compose backtest-kit computations as a typed directed acyclic graph (DAG). Define source nodes that fetch market data and output nodes that compute derived values — then resolve the whole graph in topological order with automatic parallelism.
+
+#### Key Features
+- 🔌 **DAG Execution**: Nodes are resolved bottom-up in topological order with `Promise.all` parallelism
+- 🔒 **Type-Safe Values**: TypeScript infers the return type of every node through the graph via generics
+- 🧱 **Two APIs**: Low-level `INode` for runtime/storage, high-level `sourceNode` + `outputNode` builders for authoring
+- 💾 **DB-Ready Serialization**: `serialize` / `deserialize` convert the graph to a flat `IFlatNode[]` list with `id` / `nodeIds`
+- 🌐 **Context-Aware Fetch**: `sourceNode` receives `(symbol, when, exchangeName)` from the execution context automatically
+
+#### Use Case
+Perfect for multi-timeframe strategies where multiple Pine Script or indicator computations must be combined. Instead of manually chaining async calls, define each computation as a node and let the graph resolve dependencies in parallel. Adding a new filter or timeframe requires no changes to the existing wiring.
+
+#### Get Started
+```bash
+npm install @backtest-kit/graph backtest-kit
+```
+
 ## 🤖 Are you a robot?
 
 **For language models**: Read extended description in [./LLMs.md](./LLMs.md)

package/build/index.cjs

@@ -442,6 +442,13 @@ const GLOBAL_CONFIG = {
      * Default: 50 signals
      */
     CC_MAX_SIGNALS: 50,
+    /**
+     * Enables mutex locking for candle fetching to prevent concurrent fetches of the same candles.
+     * This can help avoid redundant API calls and ensure data consistency when multiple processes/threads attempt to fetch candles simultaneously.
+     *
+     * Default: true (mutex locking enabled for candle fetching)
+     */
+    CC_ENABLE_CANDLE_FETCH_MUTEX: true,
 };
 const DEFAULT_CONFIG = Object.freeze({ ...GLOBAL_CONFIG });
 
@@ -712,10 +719,10 @@ async function writeFileAtomic(file, data, options = {}) {
     }
 }
 
-var _a$2;
+var _a$3;
 const BASE_WAIT_FOR_INIT_SYMBOL = Symbol("wait-for-init");
 // Calculate step in milliseconds for candle close time validation
-const INTERVAL_MINUTES$7 = {
+const INTERVAL_MINUTES$8 = {
     "1m": 1,
     "3m": 3,
     "5m": 5,
@@ -727,7 +734,7 @@ const INTERVAL_MINUTES$7 = {
     "6h": 360,
     "8h": 480,
 };
-const MS_PER_MINUTE$5 = 60000;
+const MS_PER_MINUTE$6 = 60000;
 const PERSIST_SIGNAL_UTILS_METHOD_NAME_USE_PERSIST_SIGNAL_ADAPTER = "PersistSignalUtils.usePersistSignalAdapter";
 const PERSIST_SIGNAL_UTILS_METHOD_NAME_READ_DATA = "PersistSignalUtils.readSignalData";
 const PERSIST_SIGNAL_UTILS_METHOD_NAME_WRITE_DATA = "PersistSignalUtils.writeSignalData";
@@ -830,7 +837,7 @@ class PersistBase {
     constructor(entityName, baseDir = path.join(process.cwd(), "logs/data")) {
         this.entityName = entityName;
         this.baseDir = baseDir;
-        this[_a$2] = functoolsKit.singleshot(async () => await BASE_WAIT_FOR_INIT_FN(this));
+        this[_a$3] = functoolsKit.singleshot(async () => await BASE_WAIT_FOR_INIT_FN(this));
         bt.loggerService.debug(PERSIST_BASE_METHOD_NAME_CTOR, {
             entityName: this.entityName,
             baseDir,
@@ -933,7 +940,7 @@ class PersistBase {
         }
     }
 }
-_a$2 = BASE_WAIT_FOR_INIT_SYMBOL;
+_a$3 = BASE_WAIT_FOR_INIT_SYMBOL;
 // @ts-ignore
 PersistBase = functoolsKit.makeExtendable(PersistBase);
 /**
@@ -1627,7 +1634,7 @@ class PersistCandleUtils {
             const isInitial = !this.getCandlesStorage.has(key);
             const stateStorage = this.getCandlesStorage(symbol, interval, exchangeName);
             await stateStorage.waitForInit(isInitial);
-            const stepMs = INTERVAL_MINUTES$7[interval] * MS_PER_MINUTE$5;
+            const stepMs = INTERVAL_MINUTES$8[interval] * MS_PER_MINUTE$6;
             // Calculate expected timestamps and fetch each candle directly
             const cachedCandles = [];
             for (let i = 0; i < limit; i++) {
@@ -1683,7 +1690,7 @@ class PersistCandleUtils {
             const stateStorage = this.getCandlesStorage(symbol, interval, exchangeName);
             await stateStorage.waitForInit(isInitial);
             // Calculate step in milliseconds to determine candle close time
-            const stepMs = INTERVAL_MINUTES$7[interval] * MS_PER_MINUTE$5;
+            const stepMs = INTERVAL_MINUTES$8[interval] * MS_PER_MINUTE$6;
             const now = Date.now();
             // Write each candle as a separate file, skipping incomplete candles
             for (const candle of candles) {
@@ -1940,8 +1947,71 @@ class PersistNotificationUtils {
  */
 const PersistNotificationAdapter = new PersistNotificationUtils();
 
-const MS_PER_MINUTE$4 = 60000;
-const INTERVAL_MINUTES$6 = {
+var _a$2, _b$2;
+const BUSY_DELAY = 100;
+const SET_BUSY_SYMBOL = Symbol("setBusy");
+const GET_BUSY_SYMBOL = Symbol("getBusy");
+const ACQUIRE_LOCK_SYMBOL = Symbol("acquireLock");
+const RELEASE_LOCK_SYMBOL = Symbol("releaseLock");
+const ACQUIRE_LOCK_FN = async (self) => {
+    while (self[GET_BUSY_SYMBOL]()) {
+        await functoolsKit.sleep(BUSY_DELAY);
+    }
+    self[SET_BUSY_SYMBOL](true);
+};
+class Lock {
+    constructor() {
+        this._isBusy = 0;
+        this[_a$2] = functoolsKit.queued(ACQUIRE_LOCK_FN);
+        this[_b$2] = () => this[SET_BUSY_SYMBOL](false);
+        this.acquireLock = async () => {
+            await this[ACQUIRE_LOCK_SYMBOL](this);
+        };
+        this.releaseLock = async () => {
+            await this[RELEASE_LOCK_SYMBOL]();
+        };
+    }
+    [SET_BUSY_SYMBOL](isBusy) {
+        this._isBusy += isBusy ? 1 : -1;
+        if (this._isBusy < 0) {
+            throw new Error("Extra release in finally block");
+        }
+    }
+    [GET_BUSY_SYMBOL]() {
+        return !!this._isBusy;
+    }
+}
+_a$2 = ACQUIRE_LOCK_SYMBOL, _b$2 = RELEASE_LOCK_SYMBOL;
+
+const METHOD_NAME_ACQUIRE_LOCK = "CandleUtils.acquireLock";
+const METHOD_NAME_RELEASE_LOCK = "CandleUtils.releaseLock";
+class CandleUtils {
+    constructor() {
+        this._lock = new Lock();
+        this.acquireLock = async (source) => {
+            bt.loggerService.info(METHOD_NAME_ACQUIRE_LOCK, {
+                source,
+            });
+            if (!GLOBAL_CONFIG.CC_ENABLE_CANDLE_FETCH_MUTEX) {
+                return;
+            }
+            return await this._lock.acquireLock();
+        };
+        this.releaseLock = async (source) => {
+            bt.loggerService.info(METHOD_NAME_RELEASE_LOCK, {
+                source,
+            });
+            if (!GLOBAL_CONFIG.CC_ENABLE_CANDLE_FETCH_MUTEX) {
+                return;
+            }
+            return await this._lock.releaseLock();
+        };
+    }
+}
+const Candle = new CandleUtils();
+
+const MS_PER_MINUTE$5 = 60000;
+const INTERVAL_MINUTES$7 = {
     "1m": 1,
     "3m": 3,
     "5m": 5,
@@ -1971,7 +2041,7 @@ const INTERVAL_MINUTES$6 = {
  * @returns Aligned timestamp rounded down to interval boundary
  */
 const ALIGN_TO_INTERVAL_FN$2 = (timestamp, intervalMinutes) => {
-    const intervalMs = intervalMinutes * MS_PER_MINUTE$4;
+    const intervalMs = intervalMinutes * MS_PER_MINUTE$5;
     return Math.floor(timestamp / intervalMs) * intervalMs;
 };
 /**
@@ -2116,37 +2186,43 @@ const WRITE_CANDLES_CACHE_FN$1 = functoolsKit.trycatch(functoolsKit.queued(async
  * @returns Promise resolving to array of candle data
  */
 const GET_CANDLES_FN = async (dto, since, self) => {
-    const step = INTERVAL_MINUTES$6[dto.interval];
+    const step = INTERVAL_MINUTES$7[dto.interval];
     const sinceTimestamp = since.getTime();
-    const untilTimestamp = sinceTimestamp + dto.limit * step * MS_PER_MINUTE$4;
-    // Try to read from cache first
-    const cachedCandles = await READ_CANDLES_CACHE_FN$1(dto, sinceTimestamp, untilTimestamp, self);
-    if (cachedCandles !== null) {
-        return cachedCandles;
-    }
-    // Cache miss or error - fetch from API
-    let lastError;
-    for (let i = 0; i !== GLOBAL_CONFIG.CC_GET_CANDLES_RETRY_COUNT; i++) {
-        try {
-            const result = await self.params.getCandles(dto.symbol, dto.interval, since, dto.limit, self.params.execution.context.backtest);
-            VALIDATE_NO_INCOMPLETE_CANDLES_FN(result);
-            // Write to cache after successful fetch
-            await WRITE_CANDLES_CACHE_FN$1(result, dto, self);
-            return result;
+    const untilTimestamp = sinceTimestamp + dto.limit * step * MS_PER_MINUTE$5;
+    await Candle.acquireLock(`ClientExchange GET_CANDLES_FN symbol=${dto.symbol} interval=${dto.interval} limit=${dto.limit}`);
+    try {
+        // Try to read from cache first
+        const cachedCandles = await READ_CANDLES_CACHE_FN$1(dto, sinceTimestamp, untilTimestamp, self);
+        if (cachedCandles !== null) {
+            return cachedCandles;
         }
-        catch (err) {
-            const message = `ClientExchange GET_CANDLES_FN: attempt ${i + 1} failed for symbol=${dto.symbol}, interval=${dto.interval}, since=${since.toISOString()}, limit=${dto.limit}}`;
-            const payload = {
-                error: functoolsKit.errorData(err),
-                message: functoolsKit.getErrorMessage(err),
-            };
-            self.params.logger.warn(message, payload);
-            console.warn(message, payload);
-            lastError = err;
-            await functoolsKit.sleep(GLOBAL_CONFIG.CC_GET_CANDLES_RETRY_DELAY_MS);
+        // Cache miss or error - fetch from API
+        let lastError;
+        for (let i = 0; i !== GLOBAL_CONFIG.CC_GET_CANDLES_RETRY_COUNT; i++) {
+            try {
+                const result = await self.params.getCandles(dto.symbol, dto.interval, since, dto.limit, self.params.execution.context.backtest);
+                VALIDATE_NO_INCOMPLETE_CANDLES_FN(result);
+                // Write to cache after successful fetch
+                await WRITE_CANDLES_CACHE_FN$1(result, dto, self);
+                return result;
+            }
+            catch (err) {
+                const message = `ClientExchange GET_CANDLES_FN: attempt ${i + 1} failed for symbol=${dto.symbol}, interval=${dto.interval}, since=${since.toISOString()}, limit=${dto.limit}}`;
+                const payload = {
+                    error: functoolsKit.errorData(err),
+                    message: functoolsKit.getErrorMessage(err),
+                };
+                self.params.logger.warn(message, payload);
+                console.warn(message, payload);
+                lastError = err;
+                await functoolsKit.sleep(GLOBAL_CONFIG.CC_GET_CANDLES_RETRY_DELAY_MS);
+            }
         }
+        throw lastError;
+    }
+    finally {
+        Candle.releaseLock(`ClientExchange GET_CANDLES_FN symbol=${dto.symbol} interval=${dto.interval} limit=${dto.limit}`);
     }
-    throw lastError;
 };
 /**
  * Wrapper to call onCandleData callback with error handling.
@@ -2226,11 +2302,11 @@ class ClientExchange {
             interval,
             limit,
         });
-        const step = INTERVAL_MINUTES$6[interval];
+        const step = INTERVAL_MINUTES$7[interval];
         if (!step) {
             throw new Error(`ClientExchange unknown interval=${interval}`);
         }
-        const stepMs = step * MS_PER_MINUTE$4;
+        const stepMs = step * MS_PER_MINUTE$5;
         // Align when down to interval boundary
         const whenTimestamp = this.params.execution.context.when.getTime();
         const alignedWhen = ALIGN_TO_INTERVAL_FN$2(whenTimestamp, step);
@@ -2307,11 +2383,11 @@ class ClientExchange {
         if (!this.params.execution.context.backtest) {
             throw new Error(`ClientExchange getNextCandles: cannot fetch future candles in live mode`);
         }
-        const step = INTERVAL_MINUTES$6[interval];
+        const step = INTERVAL_MINUTES$7[interval];
         if (!step) {
             throw new Error(`ClientExchange getNextCandles: unknown interval=${interval}`);
         }
-        const stepMs = step * MS_PER_MINUTE$4;
+        const stepMs = step * MS_PER_MINUTE$5;
         const now = Date.now();
         // Align when down to interval boundary
         const whenTimestamp = this.params.execution.context.when.getTime();
@@ -2475,11 +2551,11 @@ class ClientExchange {
             sDate,
             eDate,
         });
-        const step = INTERVAL_MINUTES$6[interval];
+        const step = INTERVAL_MINUTES$7[interval];
         if (!step) {
             throw new Error(`ClientExchange getRawCandles: unknown interval=${interval}`);
         }
-        const stepMs = step * MS_PER_MINUTE$4;
+        const stepMs = step * MS_PER_MINUTE$5;
         const whenTimestamp = this.params.execution.context.when.getTime();
         const alignedWhen = ALIGN_TO_INTERVAL_FN$2(whenTimestamp, step);
         let sinceTimestamp;
@@ -2608,7 +2684,7 @@ class ClientExchange {
         const alignedTo = ALIGN_TO_INTERVAL_FN$2(whenTimestamp, GLOBAL_CONFIG.CC_ORDER_BOOK_TIME_OFFSET_MINUTES);
         const to = new Date(alignedTo);
         const from = new Date(alignedTo -
-            GLOBAL_CONFIG.CC_ORDER_BOOK_TIME_OFFSET_MINUTES * MS_PER_MINUTE$4);
+            GLOBAL_CONFIG.CC_ORDER_BOOK_TIME_OFFSET_MINUTES * MS_PER_MINUTE$5);
         return await this.params.getOrderBook(symbol, depth, from, to, this.params.execution.context.backtest);
     }
 }
@@ -3073,7 +3149,7 @@ const beginTime = (run) => (...args) => {
     return fn();
 };
 
-const INTERVAL_MINUTES$5 = {
+const INTERVAL_MINUTES$6 = {
     "1m": 1,
     "3m": 3,
     "5m": 5,
@@ -3586,14 +3662,15 @@ const GET_SIGNAL_FN = functoolsKit.trycatch(async (self) => {
     }
     const currentTime = self.params.execution.context.when.getTime();
     {
-        const intervalMinutes = INTERVAL_MINUTES$5[self.params.interval];
+        const intervalMinutes = INTERVAL_MINUTES$6[self.params.interval];
         const intervalMs = intervalMinutes * 60 * 1000;
-        // Проверяем что прошел нужный интервал с последнего getSignal
+        const alignedTime = Math.floor(currentTime / intervalMs) * intervalMs;
+        // Проверяем что наступил новый интервал (по aligned timestamp)
         if (self._lastSignalTimestamp !== null &&
-            currentTime - self._lastSignalTimestamp < intervalMs) {
+            alignedTime === self._lastSignalTimestamp) {
             return null;
         }
-        self._lastSignalTimestamp = currentTime;
+        self._lastSignalTimestamp = alignedTime;
     }
     const currentPrice = await self.params.exchange.getAveragePrice(self.params.execution.context.symbol);
     const timeoutMs = GLOBAL_CONFIG.CC_MAX_SIGNAL_GENERATION_SECONDS * 1000;
@@ -8197,7 +8274,7 @@ class StrategyConnectionService {
  * Maps FrameInterval to minutes for timestamp calculation.
  * Used to generate timeframe arrays with proper spacing.
  */
-const INTERVAL_MINUTES$4 = {
+const INTERVAL_MINUTES$5 = {
     "1m": 1,
     "3m": 3,
     "5m": 5,
@@ -8252,7 +8329,7 @@ const GET_TIMEFRAME_FN = async (symbol, self) => {
         symbol,
     });
     const { interval, startDate, endDate } = self.params;
-    const intervalMinutes = INTERVAL_MINUTES$4[interval];
+    const intervalMinutes = INTERVAL_MINUTES$5[interval];
     if (!intervalMinutes) {
         throw new Error(`ClientFrame unknown interval: ${interval}`);
     }
@@ -13215,7 +13292,49 @@ class BacktestLogicPrivateService {
     }
 }
 
-const TICK_TTL = 1 * 60 * 1000 + 1;
+const EMITTER_CHECK_INTERVAL = 5000;
+const MS_PER_MINUTE$4 = 60000;
+const INTERVAL_MINUTES$4 = {
+    "1m": 1,
+    "3m": 3,
+    "5m": 5,
+    "15m": 15,
+    "30m": 30,
+    "1h": 60,
+    "2h": 120,
+    "4h": 240,
+    "6h": 360,
+    "8h": 480,
+};
+const createEmitter = functoolsKit.memoize(([interval]) => `${interval}`, (interval) => {
+    const tickSubject = new functoolsKit.Subject();
+    const intervalMs = INTERVAL_MINUTES$4[interval] * MS_PER_MINUTE$4;
+    {
+        let lastAligned = Math.floor(Date.now() / intervalMs) * intervalMs;
+        functoolsKit.Source.fromInterval(EMITTER_CHECK_INTERVAL)
+            .map(() => Math.floor(Date.now() / intervalMs) * intervalMs)
+            .filter((aligned) => {
+            if (aligned !== lastAligned) {
+                lastAligned = aligned;
+                return true;
+            }
+            return false;
+        })
+            .connect(tickSubject.next);
+    }
+    return tickSubject;
+});
+/**
+ * Waits for the next candle interval to start and returns the timestamp of the new candle.
+ * @param {CandleInterval} interval - The candle interval (e.g., "1m", "1h") to wait for.
+ * @returns {Promise<number>} A promise that resolves with the timestamp (in milliseconds) of the next candle start.
+ */
+const waitForCandle = async (interval) => {
+    const emitter = createEmitter(interval);
+    // Subject is multicast
+    return emitter.toPromise();
+};
+
 /**
  * Private service for live trading orchestration using async generators.
  *
@@ -13285,7 +13404,7 @@ class LiveLogicPrivateService {
                     message: functoolsKit.getErrorMessage(error),
                 });
                 await errorEmitter.next(error);
-                await functoolsKit.sleep(TICK_TTL);
+                await waitForCandle("1m");
                 continue;
             }
             this.loggerService.info("liveLogicPrivateService tick result", {
@@ -13320,19 +13439,19 @@ class LiveLogicPrivateService {
                     });
                     break;
                 }
-                await functoolsKit.sleep(TICK_TTL);
+                await waitForCandle("1m");
                 continue;
             }
             if (result.action === "active") {
-                await functoolsKit.sleep(TICK_TTL);
+                await waitForCandle("1m");
                 continue;
             }
             if (result.action === "scheduled") {
-                await functoolsKit.sleep(TICK_TTL);
+                await waitForCandle("1m");
                 continue;
             }
             if (result.action === "waiting") {
-                await functoolsKit.sleep(TICK_TTL);
+                await waitForCandle("1m");
                 continue;
             }
             // Yield opened, closed, cancelled results
@@ -13351,7 +13470,7 @@ class LiveLogicPrivateService {
                     break;
                 }
             }
-            await functoolsKit.sleep(TICK_TTL);
+            await waitForCandle("1m");
         }
     }
 }
@@ -26284,55 +26403,61 @@ class ExchangeInstance {
             const sinceTimestamp = alignedWhen - limit * stepMs;
             const since = new Date(sinceTimestamp);
             const untilTimestamp = alignedWhen;
-            // Try to read from cache first
-            const cachedCandles = await READ_CANDLES_CACHE_FN({ symbol, interval, limit }, sinceTimestamp, untilTimestamp, this.exchangeName);
-            if (cachedCandles !== null) {
-                return cachedCandles;
-            }
-            let allData = [];
-            // If limit exceeds CC_MAX_CANDLES_PER_REQUEST, fetch data in chunks
-            if (limit > GLOBAL_CONFIG.CC_MAX_CANDLES_PER_REQUEST) {
-                let remaining = limit;
-                let currentSince = new Date(since.getTime());
-                const isBacktest = await GET_BACKTEST_FN();
-                while (remaining > 0) {
-                    const chunkLimit = Math.min(remaining, GLOBAL_CONFIG.CC_MAX_CANDLES_PER_REQUEST);
-                    const chunkData = await getCandles(symbol, interval, currentSince, chunkLimit, isBacktest);
-                    allData.push(...chunkData);
-                    remaining -= chunkLimit;
-                    if (remaining > 0) {
-                        // Move currentSince forward by the number of candles fetched
-                        currentSince = new Date(currentSince.getTime() + chunkLimit * stepMs);
+            await Candle.acquireLock(`ExchangeInstance.getCandles symbol=${symbol} interval=${interval} limit=${limit}`);
+            try {
+                // Try to read from cache first
+                const cachedCandles = await READ_CANDLES_CACHE_FN({ symbol, interval, limit }, sinceTimestamp, untilTimestamp, this.exchangeName);
+                if (cachedCandles !== null) {
+                    return cachedCandles;
+                }
+                let allData = [];
+                // If limit exceeds CC_MAX_CANDLES_PER_REQUEST, fetch data in chunks
+                if (limit > GLOBAL_CONFIG.CC_MAX_CANDLES_PER_REQUEST) {
+                    let remaining = limit;
+                    let currentSince = new Date(since.getTime());
+                    const isBacktest = await GET_BACKTEST_FN();
+                    while (remaining > 0) {
+                        const chunkLimit = Math.min(remaining, GLOBAL_CONFIG.CC_MAX_CANDLES_PER_REQUEST);
+                        const chunkData = await getCandles(symbol, interval, currentSince, chunkLimit, isBacktest);
+                        allData.push(...chunkData);
+                        remaining -= chunkLimit;
+                        if (remaining > 0) {
+                            // Move currentSince forward by the number of candles fetched
+                            currentSince = new Date(currentSince.getTime() + chunkLimit * stepMs);
+                        }
                     }
                 }
+                else {
+                    const isBacktest = await GET_BACKTEST_FN();
+                    allData = await getCandles(symbol, interval, since, limit, isBacktest);
+                }
+                // Apply distinct by timestamp to remove duplicates
+                const uniqueData = Array.from(new Map(allData.map((candle) => [candle.timestamp, candle])).values());
+                if (allData.length !== uniqueData.length) {
+                    bt.loggerService.warn(`ExchangeInstance getCandles: Removed ${allData.length - uniqueData.length} duplicate candles by timestamp`);
+                }
+                // Validate adapter returned data
+                if (uniqueData.length === 0) {
+                    throw new Error(`ExchangeInstance getCandles: adapter returned empty array. ` +
+                        `Expected ${limit} candles starting from openTime=${sinceTimestamp}.`);
+                }
+                if (uniqueData[0].timestamp !== sinceTimestamp) {
+                    throw new Error(`ExchangeInstance getCandles: first candle timestamp mismatch. ` +
+                        `Expected openTime=${sinceTimestamp}, got=${uniqueData[0].timestamp}. ` +
+                        `Adapter must return candles with timestamp=openTime, starting from aligned since.`);
+                }
+                if (uniqueData.length !== limit) {
+                    throw new Error(`ExchangeInstance getCandles: candle count mismatch. ` +
+                        `Expected ${limit} candles, got ${uniqueData.length}. ` +
+                        `Adapter must return exact number of candles requested.`);
+                }
+                // Write to cache after successful fetch
+                await WRITE_CANDLES_CACHE_FN(uniqueData, { symbol, interval, limit }, this.exchangeName);
+                return uniqueData;
             }
-            else {
-                const isBacktest = await GET_BACKTEST_FN();
-                allData = await getCandles(symbol, interval, since, limit, isBacktest);
-            }
-            // Apply distinct by timestamp to remove duplicates
-            const uniqueData = Array.from(new Map(allData.map((candle) => [candle.timestamp, candle])).values());
-            if (allData.length !== uniqueData.length) {
-                bt.loggerService.warn(`ExchangeInstance getCandles: Removed ${allData.length - uniqueData.length} duplicate candles by timestamp`);
-            }
-            // Validate adapter returned data
-            if (uniqueData.length === 0) {
-                throw new Error(`ExchangeInstance getCandles: adapter returned empty array. ` +
-                    `Expected ${limit} candles starting from openTime=${sinceTimestamp}.`);
-            }
-            if (uniqueData[0].timestamp !== sinceTimestamp) {
-                throw new Error(`ExchangeInstance getCandles: first candle timestamp mismatch. ` +
-                    `Expected openTime=${sinceTimestamp}, got=${uniqueData[0].timestamp}. ` +
-                    `Adapter must return candles with timestamp=openTime, starting from aligned since.`);
-            }
-            if (uniqueData.length !== limit) {
-                throw new Error(`ExchangeInstance getCandles: candle count mismatch. ` +
-                    `Expected ${limit} candles, got ${uniqueData.length}. ` +
-                    `Adapter must return exact number of candles requested.`);
+            finally {
+                Candle.releaseLock(`ExchangeInstance.getCandles symbol=${symbol} interval=${interval} limit=${limit}`);
             }
-            // Write to cache after successful fetch
-            await WRITE_CANDLES_CACHE_FN(uniqueData, { symbol, interval, limit }, this.exchangeName);
-            return uniqueData;
         };
         /**
          * Calculates VWAP (Volume Weighted Average Price) from last N 1m candles.
@@ -26566,56 +26691,62 @@ class ExchangeInstance {
                     `Provide one of: (sDate+eDate+limit), (sDate+eDate), (eDate+limit), (sDate+limit), or (limit only). ` +
                     `Got: sDate=${sDate}, eDate=${eDate}, limit=${limit}`);
             }
-            // Try to read from cache first
-            const untilTimestamp = sinceTimestamp + calculatedLimit * stepMs;
-            const cachedCandles = await READ_CANDLES_CACHE_FN({ symbol, interval, limit: calculatedLimit }, sinceTimestamp, untilTimestamp, this.exchangeName);
-            if (cachedCandles !== null) {
-                return cachedCandles;
-            }
-            // Fetch candles
-            const since = new Date(sinceTimestamp);
-            let allData = [];
-            const isBacktest = await GET_BACKTEST_FN();
-            const getCandles = this._methods.getCandles;
-            if (calculatedLimit > GLOBAL_CONFIG.CC_MAX_CANDLES_PER_REQUEST) {
-                let remaining = calculatedLimit;
-                let currentSince = new Date(since.getTime());
-                while (remaining > 0) {
-                    const chunkLimit = Math.min(remaining, GLOBAL_CONFIG.CC_MAX_CANDLES_PER_REQUEST);
-                    const chunkData = await getCandles(symbol, interval, currentSince, chunkLimit, isBacktest);
-                    allData.push(...chunkData);
-                    remaining -= chunkLimit;
-                    if (remaining > 0) {
-                        currentSince = new Date(currentSince.getTime() + chunkLimit * stepMs);
+            await Candle.acquireLock(`ExchangeInstance.getRawCandles symbol=${symbol} interval=${interval} limit=${calculatedLimit}`);
+            try {
+                // Try to read from cache first
+                const untilTimestamp = sinceTimestamp + calculatedLimit * stepMs;
+                const cachedCandles = await READ_CANDLES_CACHE_FN({ symbol, interval, limit: calculatedLimit }, sinceTimestamp, untilTimestamp, this.exchangeName);
+                if (cachedCandles !== null) {
+                    return cachedCandles;
+                }
+                // Fetch candles
+                const since = new Date(sinceTimestamp);
+                let allData = [];
+                const isBacktest = await GET_BACKTEST_FN();
+                const getCandles = this._methods.getCandles;
+                if (calculatedLimit > GLOBAL_CONFIG.CC_MAX_CANDLES_PER_REQUEST) {
+                    let remaining = calculatedLimit;
+                    let currentSince = new Date(since.getTime());
+                    while (remaining > 0) {
+                        const chunkLimit = Math.min(remaining, GLOBAL_CONFIG.CC_MAX_CANDLES_PER_REQUEST);
+                        const chunkData = await getCandles(symbol, interval, currentSince, chunkLimit, isBacktest);
+                        allData.push(...chunkData);
+                        remaining -= chunkLimit;
+                        if (remaining > 0) {
+                            currentSince = new Date(currentSince.getTime() + chunkLimit * stepMs);
+                        }
                     }
                 }
+                else {
+                    allData = await getCandles(symbol, interval, since, calculatedLimit, isBacktest);
+                }
+                // Apply distinct by timestamp to remove duplicates
+                const uniqueData = Array.from(new Map(allData.map((candle) => [candle.timestamp, candle])).values());
+                if (allData.length !== uniqueData.length) {
+                    bt.loggerService.warn(`ExchangeInstance getRawCandles: Removed ${allData.length - uniqueData.length} duplicate candles by timestamp`);
+                }
+                // Validate adapter returned data
+                if (uniqueData.length === 0) {
+                    throw new Error(`ExchangeInstance getRawCandles: adapter returned empty array. ` +
+                        `Expected ${calculatedLimit} candles starting from openTime=${sinceTimestamp}.`);
+                }
+                if (uniqueData[0].timestamp !== sinceTimestamp) {
+                    throw new Error(`ExchangeInstance getRawCandles: first candle timestamp mismatch. ` +
+                        `Expected openTime=${sinceTimestamp}, got=${uniqueData[0].timestamp}. ` +
+                        `Adapter must return candles with timestamp=openTime, starting from aligned since.`);
+                }
+                if (uniqueData.length !== calculatedLimit) {
+                    throw new Error(`ExchangeInstance getRawCandles: candle count mismatch. ` +
+                        `Expected ${calculatedLimit} candles, got ${uniqueData.length}. ` +
+                        `Adapter must return exact number of candles requested.`);
+                }
+                // Write to cache after successful fetch
+                await WRITE_CANDLES_CACHE_FN(uniqueData, { symbol, interval, limit: calculatedLimit }, this.exchangeName);
+                return uniqueData;
             }
-            else {
-                allData = await getCandles(symbol, interval, since, calculatedLimit, isBacktest);
-            }
-            // Apply distinct by timestamp to remove duplicates
-            const uniqueData = Array.from(new Map(allData.map((candle) => [candle.timestamp, candle])).values());
-            if (allData.length !== uniqueData.length) {
-                bt.loggerService.warn(`ExchangeInstance getRawCandles: Removed ${allData.length - uniqueData.length} duplicate candles by timestamp`);
-            }
-            // Validate adapter returned data
-            if (uniqueData.length === 0) {
-                throw new Error(`ExchangeInstance getRawCandles: adapter returned empty array. ` +
-                    `Expected ${calculatedLimit} candles starting from openTime=${sinceTimestamp}.`);
-            }
-            if (uniqueData[0].timestamp !== sinceTimestamp) {
-                throw new Error(`ExchangeInstance getRawCandles: first candle timestamp mismatch. ` +
-                    `Expected openTime=${sinceTimestamp}, got=${uniqueData[0].timestamp}. ` +
-                    `Adapter must return candles with timestamp=openTime, starting from aligned since.`);
-            }
-            if (uniqueData.length !== calculatedLimit) {
-                throw new Error(`ExchangeInstance getRawCandles: candle count mismatch. ` +
-                    `Expected ${calculatedLimit} candles, got ${uniqueData.length}. ` +
-                    `Adapter must return exact number of candles requested.`);
+            finally {
+                Candle.releaseLock(`ExchangeInstance.getRawCandles symbol=${symbol} interval=${interval} limit=${calculatedLimit}`);
             }
-            // Write to cache after successful fetch
-            await WRITE_CANDLES_CACHE_FN(uniqueData, { symbol, interval, limit: calculatedLimit }, this.exchangeName);
-            return uniqueData;
         };
         const schema = bt.exchangeSchemaService.get(this.exchangeName);
         this._methods = CREATE_EXCHANGE_INSTANCE_FN(schema);
@@ -37498,4 +37629,5 @@ exports.setConfig = setConfig;
 exports.setLogger = setLogger;
 exports.stopStrategy = stopStrategy;
 exports.validate = validate;
+exports.waitForCandle = waitForCandle;
 exports.warmCandles = warmCandles;