@0xarchive/sdk 0.6.2 → 0.6.4

package/dist/index.js

@@ -41,6 +41,7 @@ __export(index_exports, {
   OpenInterestResponseSchema: () => OpenInterestResponseSchema,
   OpenInterestSchema: () => OpenInterestSchema,
   OrderBookArrayResponseSchema: () => OrderBookArrayResponseSchema,
+  OrderBookReconstructor: () => OrderBookReconstructor,
   OrderBookResponseSchema: () => OrderBookResponseSchema,
   OrderBookSchema: () => OrderBookSchema,
   OxArchive: () => OxArchive,
@@ -71,7 +72,9 @@ __export(index_exports, {
   WsStreamStoppedSchema: () => WsStreamStoppedSchema,
   WsSubscribedSchema: () => WsSubscribedSchema,
   WsUnsubscribedSchema: () => WsUnsubscribedSchema,
-  default: () => OxArchive
+  default: () => OxArchive,
+  reconstructFinal: () => reconstructFinal,
+  reconstructOrderBook: () => reconstructOrderBook
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -412,6 +415,185 @@ var OpenInterestArrayResponseSchema = ApiResponseSchema(import_zod.z.array(OpenI
 var CandleArrayResponseSchema = ApiResponseSchema(import_zod.z.array(CandleSchema));
 var LiquidationArrayResponseSchema = ApiResponseSchema(import_zod.z.array(LiquidationSchema));
 
+// src/orderbook-reconstructor.ts
+var OrderBookReconstructor = class {
+  bids = /* @__PURE__ */ new Map();
+  asks = /* @__PURE__ */ new Map();
+  coin = "";
+  lastTimestamp = "";
+  lastSequence = 0;
+  /**
+   * Initialize or reset the reconstructor with a checkpoint
+   */
+  initialize(checkpoint) {
+    this.bids.clear();
+    this.asks.clear();
+    this.coin = checkpoint.coin;
+    this.lastTimestamp = checkpoint.timestamp;
+    this.lastSequence = 0;
+    for (const level of checkpoint.bids) {
+      const price = parseFloat(level.px);
+      this.bids.set(price, {
+        price,
+        size: parseFloat(level.sz),
+        orders: level.n
+      });
+    }
+    for (const level of checkpoint.asks) {
+      const price = parseFloat(level.px);
+      this.asks.set(price, {
+        price,
+        size: parseFloat(level.sz),
+        orders: level.n
+      });
+    }
+  }
+  /**
+   * Apply a single delta to the current state
+   */
+  applyDelta(delta) {
+    const book = delta.side === "bid" ? this.bids : this.asks;
+    if (delta.size === 0) {
+      book.delete(delta.price);
+    } else {
+      book.set(delta.price, {
+        price: delta.price,
+        size: delta.size,
+        orders: 1
+        // Deltas don't include order count, assume 1
+      });
+    }
+    this.lastTimestamp = new Date(delta.timestamp).toISOString();
+    this.lastSequence = delta.sequence;
+  }
+  /**
+   * Get the current orderbook state as a snapshot
+   */
+  getSnapshot(depth) {
+    const sortedBids = Array.from(this.bids.values()).sort((a, b) => b.price - a.price);
+    const sortedAsks = Array.from(this.asks.values()).sort((a, b) => a.price - b.price);
+    const bidsOutput = (depth ? sortedBids.slice(0, depth) : sortedBids).map(this.toLevel);
+    const asksOutput = (depth ? sortedAsks.slice(0, depth) : sortedAsks).map(this.toLevel);
+    const bestBid = sortedBids[0]?.price;
+    const bestAsk = sortedAsks[0]?.price;
+    const midPrice = bestBid && bestAsk ? (bestBid + bestAsk) / 2 : void 0;
+    const spread = bestBid && bestAsk ? bestAsk - bestBid : void 0;
+    const spreadBps = midPrice && spread ? spread / midPrice * 1e4 : void 0;
+    return {
+      coin: this.coin,
+      timestamp: this.lastTimestamp,
+      bids: bidsOutput,
+      asks: asksOutput,
+      midPrice: midPrice?.toString(),
+      spread: spread?.toString(),
+      spreadBps: spreadBps?.toFixed(2),
+      sequence: this.lastSequence
+    };
+  }
+  /**
+   * Convert internal level to API format
+   */
+  toLevel = (level) => ({
+    px: level.price.toString(),
+    sz: level.size.toString(),
+    n: level.orders
+  });
+  /**
+   * Reconstruct all orderbook states from checkpoint + deltas.
+   * Returns an array of snapshots, one after each delta.
+   *
+   * For large datasets, prefer `iterate()` to avoid memory issues.
+   *
+   * @param checkpoint - Initial orderbook state
+   * @param deltas - Array of delta updates
+   * @param options - Reconstruction options
+   * @returns Array of reconstructed orderbook snapshots
+   */
+  reconstructAll(checkpoint, deltas, options = {}) {
+    const { depth, emitAll = true } = options;
+    const snapshots = [];
+    this.initialize(checkpoint);
+    const sortedDeltas = [...deltas].sort((a, b) => a.sequence - b.sequence);
+    if (emitAll) {
+      snapshots.push(this.getSnapshot(depth));
+    }
+    for (const delta of sortedDeltas) {
+      this.applyDelta(delta);
+      if (emitAll) {
+        snapshots.push(this.getSnapshot(depth));
+      }
+    }
+    if (!emitAll) {
+      snapshots.push(this.getSnapshot(depth));
+    }
+    return snapshots;
+  }
+  /**
+   * Iterate over reconstructed orderbook states (memory-efficient).
+   * Yields a snapshot after each delta is applied.
+   *
+   * @param checkpoint - Initial orderbook state
+   * @param deltas - Array of delta updates
+   * @param options - Reconstruction options
+   * @yields Reconstructed orderbook snapshots
+   */
+  *iterate(checkpoint, deltas, options = {}) {
+    const { depth } = options;
+    this.initialize(checkpoint);
+    yield this.getSnapshot(depth);
+    const sortedDeltas = [...deltas].sort((a, b) => a.sequence - b.sequence);
+    for (const delta of sortedDeltas) {
+      this.applyDelta(delta);
+      yield this.getSnapshot(depth);
+    }
+  }
+  /**
+   * Get the final reconstructed state without intermediate snapshots.
+   * Most efficient when you only need the end result.
+   *
+   * @param checkpoint - Initial orderbook state
+   * @param deltas - Array of delta updates
+   * @param depth - Maximum price levels to include
+   * @returns Final orderbook state after all deltas applied
+   */
+  reconstructFinal(checkpoint, deltas, depth) {
+    this.initialize(checkpoint);
+    const sortedDeltas = [...deltas].sort((a, b) => a.sequence - b.sequence);
+    for (const delta of sortedDeltas) {
+      this.applyDelta(delta);
+    }
+    return this.getSnapshot(depth);
+  }
+  /**
+   * Check for sequence gaps in deltas.
+   * Returns array of missing sequence numbers.
+   *
+   * @param deltas - Array of delta updates
+   * @returns Array of [expectedSeq, actualSeq] tuples where gaps exist
+   */
+  static detectGaps(deltas) {
+    if (deltas.length < 2) return [];
+    const sorted = [...deltas].sort((a, b) => a.sequence - b.sequence);
+    const gaps = [];
+    for (let i = 1; i < sorted.length; i++) {
+      const expected = sorted[i - 1].sequence + 1;
+      const actual = sorted[i].sequence;
+      if (actual !== expected) {
+        gaps.push([expected, actual]);
+      }
+    }
+    return gaps;
+  }
+};
+function reconstructOrderBook(tickData, options = {}) {
+  const reconstructor = new OrderBookReconstructor();
+  return reconstructor.reconstructAll(tickData.checkpoint, tickData.deltas, options);
+}
+function reconstructFinal(tickData, depth) {
+  const reconstructor = new OrderBookReconstructor();
+  return reconstructor.reconstructFinal(tickData.checkpoint, tickData.deltas, depth);
+}
+
 // src/resources/orderbook.ts
 var OrderBookResource = class {
   constructor(http, basePath = "/v1") {
@@ -471,6 +653,120 @@ var OrderBookResource = class {
       nextCursor: response.meta.nextCursor
     };
   }
+  /**
+   * Get raw tick-level orderbook data (Enterprise tier only).
+   *
+   * Returns a checkpoint (full orderbook state) and array of deltas.
+   * Use this when you want to implement custom reconstruction logic
+   * (e.g., in Rust for maximum performance).
+   *
+   * For automatic reconstruction, use `historyReconstructed()` instead.
+   *
+   * @param coin - The coin symbol (e.g., 'BTC', 'ETH')
+   * @param params - Time range parameters
+   * @returns Tick data with checkpoint and deltas
+   *
+   * @example
+   * ```typescript
+   * const tickData = await client.lighter.orderbook.historyTick('BTC', {
+   *   start: Date.now() - 3600000,
+   *   end: Date.now()
+   * });
+   *
+   * console.log('Checkpoint:', tickData.checkpoint);
+   * console.log('Deltas:', tickData.deltas.length);
+   *
+   * // Implement your own reconstruction...
+   * for (const delta of tickData.deltas) {
+   *   // delta: { timestamp, side, price, size, sequence }
+   * }
+   * ```
+   */
+  async historyTick(coin, params) {
+    const response = await this.http.get(
+      `${this.basePath}/orderbook/${coin.toUpperCase()}/history`,
+      {
+        ...params,
+        granularity: "tick"
+      }
+    );
+    const tickData = response.data;
+    if (!tickData?.checkpoint || !tickData?.deltas) {
+      const errorMsg = response.error || response.message || "Tick-level orderbook data requires Enterprise tier. Upgrade your subscription or use a different granularity.";
+      throw new Error(errorMsg);
+    }
+    return {
+      checkpoint: tickData.checkpoint,
+      deltas: tickData.deltas
+    };
+  }
+  /**
+   * Get reconstructed tick-level orderbook history (Enterprise tier only).
+   *
+   * Fetches raw tick data and reconstructs full orderbook state at each delta.
+   * All reconstruction happens client-side for optimal server performance.
+   *
+   * For large time ranges, consider using `historyTick()` with the
+   * `OrderBookReconstructor.iterate()` method for memory efficiency.
+   *
+   * @param coin - The coin symbol (e.g., 'BTC', 'ETH')
+   * @param params - Time range parameters
+   * @param options - Reconstruction options
+   * @returns Array of reconstructed orderbook snapshots
+   *
+   * @example
+   * ```typescript
+   * // Get all snapshots
+   * const snapshots = await client.lighter.orderbook.historyReconstructed('BTC', {
+   *   start: Date.now() - 3600000,
+   *   end: Date.now()
+   * });
+   *
+   * for (const ob of snapshots) {
+   *   console.log(ob.timestamp, 'Best bid:', ob.bids[0]?.px, 'Best ask:', ob.asks[0]?.px);
+   * }
+   *
+   * // Get only final state
+   * const [final] = await client.lighter.orderbook.historyReconstructed('BTC',
+   *   { start, end },
+   *   { emitAll: false }
+   * );
+   * ```
+   */
+  async historyReconstructed(coin, params, options = {}) {
+    const tickData = await this.historyTick(coin, params);
+    const reconstructor = new OrderBookReconstructor();
+    return reconstructor.reconstructAll(tickData.checkpoint, tickData.deltas, options);
+  }
+  /**
+   * Create a reconstructor for streaming tick-level data.
+   *
+   * Returns an OrderBookReconstructor instance that you can use
+   * to process tick data incrementally or with custom logic.
+   *
+   * @returns A new OrderBookReconstructor instance
+   *
+   * @example
+   * ```typescript
+   * const reconstructor = client.lighter.orderbook.createReconstructor();
+   * const tickData = await client.lighter.orderbook.historyTick('BTC', { start, end });
+   *
+   * // Memory-efficient iteration
+   * for (const snapshot of reconstructor.iterate(tickData.checkpoint, tickData.deltas)) {
+   *   // Process each snapshot
+   *   if (someCondition(snapshot)) break; // Early exit if needed
+   * }
+   *
+   * // Check for gaps
+   * const gaps = OrderBookReconstructor.detectGaps(tickData.deltas);
+   * if (gaps.length > 0) {
+   *   console.warn('Sequence gaps detected:', gaps);
+   * }
+   * ```
+   */
+  createReconstructor() {
+    return new OrderBookReconstructor();
+  }
 };
 
 // src/resources/trades.ts
@@ -1673,6 +1969,7 @@ var OxArchiveWs = class {
   OpenInterestResponseSchema,
   OpenInterestSchema,
   OrderBookArrayResponseSchema,
+  OrderBookReconstructor,
   OrderBookResponseSchema,
   OrderBookSchema,
   OxArchive,
@@ -1702,6 +1999,8 @@ var OxArchiveWs = class {
   WsStreamStartedSchema,
   WsStreamStoppedSchema,
   WsSubscribedSchema,
-  WsUnsubscribedSchema
+  WsUnsubscribedSchema,
+  reconstructFinal,
+  reconstructOrderBook
 });
 //# sourceMappingURL=index.js.map