fix(src): Fix 24h price gap calculation by widening retention and lookup window (#300)

* Fix 24h price gap calculation by widening retention and lookup window

  The Redis Time Series retention period (24h) and the 24h-ago lookup
  threshold (5min tolerance) created only a 5-minute overlap window for
  finding historical price data. As the token count grows and update
  cycles take longer, this narrow window frequently contains no data
  points, causing percentagePriceChange24h to return null.

  - Increase RETENTION_PERIOD from 24h to 25h
  - Increase DEFAULT_ONE_DAY_THRESHOLD_MS from 5min (300000ms) to 30min (1800000ms)

  This expands the overlap window from 5 minutes to 90 minutes, tolerating
  longer update cycles and transient Horizon outages without losing 24h
  price change data.

* gap calculation by decoupling history gate from lookup tolerance

  The 24h price change calculation frequently returns null because a single
  threshold (oneDayThreshold) was used for both the minimum history
  requirement and the revRange lookup window. With a 5-minute tolerance and
  24h retention, the overlap window for finding a historical price point was
  only 5 minutes — easily missed during update gaps.

  - Increase RETENTION_PERIOD from 24h to 25h for wider data retention
  - Add separate PRICE_LOOKUP_TOLERANCE_MS (30min) for the revRange lookup
  - Keep DEFAULT_ONE_DAY_THRESHOLD_MS (5min) for the strict ~24h history gate

  The history gate still requires ~23h55m of data before computing a 24h
  change (no stale data). The lookup now searches with a 90-minute overlap
  window instead of 5 minutes, tolerating gaps in price updates., wiring up the handoff from setup to live ingestion

* Add boundary tests for decoupled history gate and lookup tolerance

  Add tests verifying that the 24h history gate and the lookup tolerance
  operate independently:

  - Token with 23h54m of history (1min under gate) returns null for
    percentagePriceChange24h and does not attempt the revRange lookup
  - Token with 23h56m of history (1min over gate) computes the 24h change
    using the wider 30min PRICE_LOOKUP_TOLERANCE_MS, not the strict 5min
    DEFAULT_ONE_DAY_THRESHOLD_MS

* Update retention comments to match new window

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* refactor: express PRICE_LOOKUP_TOLERANCE_MS as 30 * 60 * 1000 and improve doc comment

Agent-Logs-Url: https://github.com/stellar/freighter-backend/sessions/c6614a68-5178-48c6-911e-a16f20fb16b1

---------

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>

Author: 3 people

src/service/prices/index.test.ts

@@ -69,7 +69,7 @@ describe("Token Price Client", () => {
       // Use PriceClient static properties if available, otherwise redefine
       const ONE_DAY = 24 * 60 * 60 * 1000;
       const ONE_MINUTE = 60 * 1000;
-      const twentyFourHoursAgo = mockNow - (ONE_DAY - 5 * ONE_MINUTE);
+      const lookupCutoff = mockNow - ONE_DAY + 30 * ONE_MINUTE;
       const muchOlderTimestamp = mockNow - 2 * ONE_DAY; // Timestamp > 24h ago
 
       // Mock ts.get to return current price data
@@ -89,7 +89,7 @@ describe("Token Price Client", () => {
       // Mock ts.revRange for the oldPrices check
       mockRedisClient.ts.revRange.mockResolvedValue([
         {
-          timestamp: twentyFourHoursAgo, // Simulate finding a price exactly 24h ago
+          timestamp: lookupCutoff, // Simulate finding a price at the lookup cutoff
           value: mockHistoricalPrice,
         },
       ]);
@@ -112,7 +112,7 @@ describe("Token Price Client", () => {
       expect(mockRedisClient.ts.revRange).toHaveBeenCalledWith(
         token,
         "-",
-        twentyFourHoursAgo, // Match the timestamp used in getPrice
+        lookupCutoff, // Match the lookup cutoff used in getPrice
         { COUNT: 1 },
       );
       // Check the counter increment
@@ -161,6 +161,73 @@ describe("Token Price Client", () => {
       );
     });
 
+    it("should return null when history is just under the 24h gate (23h54m)", async () => {
+      const mockCurrentPrice = 50000;
+      const mockNow = Date.now();
+      const ONE_DAY = 24 * 60 * 60 * 1000;
+      const ONE_MINUTE = 60 * 1000;
+      // First entry is 23h54m ago — 1 minute short of the 23h55m gate
+      const justUnderGate = mockNow - (ONE_DAY - 6 * ONE_MINUTE);
+
+      mockRedisClient.ts.get.mockResolvedValue({
+        timestamp: mockNow,
+        value: mockCurrentPrice,
+      });
+
+      mockRedisClient.ts.range.mockResolvedValue([
+        { timestamp: justUnderGate, value: 48000 },
+      ]);
+
+      const token = "BOUNDARY:GUNDER";
+      const result = await priceClient.getPrice(token);
+
+      expect(result).not.toBeNull();
+      expect(result?.currentPrice.toNumber()).toBe(mockCurrentPrice);
+      expect(result?.percentagePriceChange24h).toBeNull();
+      expect(mockRedisClient.ts.revRange).not.toHaveBeenCalled();
+    });
+
+    it("should compute 24h change when history just passes the gate (23h56m)", async () => {
+      const mockCurrentPrice = 50000;
+      const mockHistoricalPrice = 45000;
+      const mockNow = Date.now();
+      const ONE_DAY = 24 * 60 * 60 * 1000;
+      const ONE_MINUTE = 60 * 1000;
+      // First entry is 23h56m ago — 1 minute past the 23h55m gate
+      const justOverGate = mockNow - (ONE_DAY - 4 * ONE_MINUTE);
+      // Lookup cutoff uses the wider 30min tolerance: mockNow - 24h + 30min
+      const lookupCutoff = mockNow - ONE_DAY + 30 * ONE_MINUTE;
+
+      mockRedisClient.ts.get.mockResolvedValue({
+        timestamp: mockNow,
+        value: mockCurrentPrice,
+      });
+
+      mockRedisClient.ts.range.mockResolvedValue([
+        { timestamp: justOverGate, value: 48000 },
+      ]);
+
+      mockRedisClient.ts.revRange.mockResolvedValue([
+        { timestamp: lookupCutoff, value: mockHistoricalPrice },
+      ]);
+
+      const token = "BOUNDARY:GOVER";
+      const result = await priceClient.getPrice(token);
+
+      expect(result).not.toBeNull();
+      expect(result?.currentPrice.toNumber()).toBe(mockCurrentPrice);
+      expect(result?.percentagePriceChange24h?.toFixed(2)).toBe("11.11");
+
+      // Verify the lookup uses the wider PRICE_LOOKUP_TOLERANCE_MS (30min),
+      // NOT the history gate's DEFAULT_ONE_DAY_THRESHOLD_MS (5min)
+      expect(mockRedisClient.ts.revRange).toHaveBeenCalledWith(
+        token,
+        "-",
+        lookupCutoff,
+        { COUNT: 1 },
+      );
+    });
+
     it("should handle new token request", async () => {
       // Setup mock - ts.get throws error for non-existent key
       mockRedisClient.ts.get.mockRejectedValue(new Error("Key does not exist"));

src/service/prices/index.ts

@@ -78,9 +78,10 @@ export class PriceClient {
 
   /**
    * The time period (in milliseconds) for which to retain price data in Redis time series.
-   * Currently set to 1 day in milliseconds to support 24-hour price change calculations while managing storage usage.
+   * Currently set to 25 hours in milliseconds to support 24-hour price change calculations while managing storage usage.
+   * The extra hour of retention helps avoid gaps when computing 24-hour price changes from the time series data.
    */
-  private static readonly RETENTION_PERIOD = 24 * 60 * 60 * 1000;
+  private static readonly RETENTION_PERIOD = 25 * 60 * 60 * 1000;
 
   /**
    * Delay (in milliseconds) between processing batches of tokens during price updates.
@@ -106,6 +107,13 @@ export class PriceClient {
    */
   private static readonly DEFAULT_ONE_DAY_THRESHOLD_MS = 300000;
 
+  /**
+   * Tolerance window (in milliseconds) for the revRange lookup when searching
+   * for a historical price point. Set to 30 minutes, wider than the history
+   * gate threshold, to tolerate gaps in price updates within the retained data.
+   */
+  private static readonly PRICE_LOOKUP_TOLERANCE_MS = 30 * 60 * 1000;
+
   /**
    * Maximum number of tokens to fetch and track prices for initially.
    * Limits the total number of tokens to manage system resource usage.
@@ -211,27 +219,31 @@ export class PriceClient {
 
       const currentPrice = new BigNumber(latestPrice.value);
       let percentagePriceChange24h: BigNumber | null = null;
-      const oneDayThreshold = PriceClient.ONE_DAY - this.priceOneDayThresholdMs;
+      const minHistoryRequired =
+        PriceClient.ONE_DAY - this.priceOneDayThresholdMs;
 
-      // When calculating the 24h price change, we want to make sure the token has been tracked for at least 24 hours.
+      // Ensure the token has been tracked for at least ~24 hours before computing a 24h change.
       const firstEntry = await this.redisClient.ts.range(tsKey, "-", "+", {
         COUNT: 1,
       });
       if (
         firstEntry &&
         firstEntry.length > 0 &&
-        latestPrice.timestamp - oneDayThreshold >= firstEntry[0].timestamp
+        latestPrice.timestamp - minHistoryRequired >= firstEntry[0].timestamp
       ) {
-        // revRange traverses the time series in reverse chronological order.
-        // We use the "-" symbol to indicate the earliest/oldest timestamp of the time series.
-        // We dont use the exact 1 day calculation but use an offset of few minutes to account for slight timing variations.
-        const dayAgo = latestPrice.timestamp - oneDayThreshold;
+        // Use a wider tolerance for the lookup to tolerate gaps in price updates.
+        // The history gate above guarantees data ≥ ~24h old exists, so the wider
+        // lookup window will reliably find a price point.
+        const lookupCutoff =
+          latestPrice.timestamp -
+          PriceClient.ONE_DAY +
+          PriceClient.PRICE_LOOKUP_TOLERANCE_MS;
         const oldPrices = await this.redisClient.ts.revRange(
           tsKey,
-          "-", // Indicates the earliest/oldest timestamp of the time series
-          dayAgo, // Indicates the timestamp roughly 24 hours ago from the latest price.
+          "-",
+          lookupCutoff,
           {
-            COUNT: 1, // Get the single most recent entry at or before dayAgo
+            COUNT: 1,
           },
         );
 
@@ -256,7 +268,7 @@ export class PriceClient {
         );
         this.logger.info(`Earliest entry: ${JSON.stringify(firstEntry)}`);
         this.logger.info(
-          `Time difference: ${latestPrice.timestamp - firstEntry[0].timestamp}, 1 day threshold: ${oneDayThreshold}`,
+          `Time difference: ${latestPrice.timestamp - firstEntry[0].timestamp}, 1 day threshold: ${minHistoryRequired}`,
         );
       }