@imbingox/acex 0.3.0 → 0.3.1-beta.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imbingox/acex",
-  "version": "0.3.0",
+  "version": "0.3.1-beta.0",
   "description": "Multi-exchange trading SDK for market data, account, and order management",
   "repository": {
     "type": "git",

package/src/adapters/binance/adapter.ts

@@ -1,3 +1,4 @@
+import { SubscriptionMultiplexer } from "../../internal/subscription-multiplexer.ts";
 import type {
   MarketDefinition,
   VenueMarketCapabilities,
@@ -10,12 +11,34 @@ import type {
   MarketAdapter,
   StreamHandle,
 } from "../types.ts";
-import { subscribeBinanceBookTicker } from "./book-ticker.ts";
-import { subscribeBinanceMarkPrice } from "./mark-price.ts";
 import {
   type BinanceMarketDefinition,
   loadBinanceMarkets,
 } from "./market-catalog.ts";
+import {
+  type BinanceStreamDescriptor,
+  type BinanceStreamMessage,
+  type BinanceStreamPayload,
+  BinanceStreamProtocol,
+} from "./stream-protocol.ts";
+
+const BINANCE_CONTROL_FRAME_MAX_PER_SEC = 5;
+// Binance allows up to 1024 streams per connection; keep a conservative pool cap.
+const BINANCE_MAX_SUBSCRIPTIONS_PER_CONNECTION = 200;
+
+type BinanceMarketMultiplexer = SubscriptionMultiplexer<
+  BinanceStreamMessage,
+  BinanceStreamDescriptor,
+  BinanceStreamPayload
+>;
+
+interface BinanceMultiplexerConfig {
+  readonly initialMessageTimeoutMs: number;
+  readonly staleAfterMs: number;
+  readonly reconnectDelayMs: number;
+  readonly reconnectMaxDelayMs: number;
+  readonly now?: () => number;
+}
 
 export class BinanceMarketAdapter implements MarketAdapter {
   readonly venue = "binance" as const;
@@ -27,6 +50,8 @@ export class BinanceMarketAdapter implements MarketAdapter {
   };
 
   private readonly definitions = new Map<string, BinanceMarketDefinition>();
+  private multiplexer: BinanceMarketMultiplexer | undefined;
+  private multiplexerConfig: BinanceMultiplexerConfig | undefined;
 
   async loadMarkets(): Promise<MarketDefinition[]> {
     const markets = await loadBinanceMarkets();
@@ -49,18 +74,38 @@ export class BinanceMarketAdapter implements MarketAdapter {
       throw new Error(`Unknown Binance market: ${market.symbol}`);
     }
 
-    return subscribeBinanceBookTicker(
-      binanceMarket,
+    const handle = this.getMultiplexer(options).subscribe(
+      {
+        channel: "l1book",
+        market: binanceMarket,
+      },
       {
-        onBookTicker(update) {
-          callbacks.onUpdate(update);
+        onPayload(payload, receivedAt) {
+          if (payload.channel !== "l1book") {
+            return;
+          }
+
+          callbacks.onUpdate({
+            bidPrice: payload.bidPrice,
+            bidSize: payload.bidSize,
+            askPrice: payload.askPrice,
+            askSize: payload.askSize,
+            exchangeTs: payload.exchangeTs,
+            receivedAt,
+          });
         },
         onFreshnessChange: callbacks.onFreshnessChange,
         onDisconnected: callbacks.onDisconnected,
         onError: callbacks.onError,
       },
-      options,
     );
+
+    return {
+      ready: handle.ready,
+      close(): void {
+        handle.close();
+      },
+    };
   }
 
   createFundingRateStream(
@@ -73,17 +118,91 @@ export class BinanceMarketAdapter implements MarketAdapter {
       throw new Error(`Unknown Binance market: ${market.symbol}`);
     }
 
-    return subscribeBinanceMarkPrice(
-      binanceMarket,
+    const handle = this.getMultiplexer(options).subscribe(
       {
-        onFundingRate(update) {
-          callbacks.onUpdate(update);
+        channel: "fundingRate",
+        market: binanceMarket,
+      },
+      {
+        onPayload(payload, receivedAt) {
+          if (payload.channel !== "fundingRate") {
+            return;
+          }
+
+          callbacks.onUpdate({
+            fundingRate: payload.fundingRate,
+            nextFundingTime: payload.nextFundingTime,
+            markPrice: payload.markPrice,
+            indexPrice: payload.indexPrice,
+            exchangeTs: payload.exchangeTs,
+            receivedAt,
+          });
         },
         onFreshnessChange: callbacks.onFreshnessChange,
         onDisconnected: callbacks.onDisconnected,
         onError: callbacks.onError,
       },
-      options,
     );
+
+    return {
+      ready: handle.ready,
+      close(): void {
+        handle.close();
+      },
+    };
+  }
+
+  private getMultiplexer(
+    options: L1BookStreamOptions | FundingRateStreamOptions,
+  ): BinanceMarketMultiplexer {
+    const config: BinanceMultiplexerConfig = {
+      initialMessageTimeoutMs: options.initialMessageTimeoutMs,
+      staleAfterMs: options.staleAfterMs,
+      reconnectDelayMs: options.reconnectDelayMs,
+      reconnectMaxDelayMs: options.reconnectMaxDelayMs,
+      now: options.now,
+    };
+
+    if (!this.multiplexer) {
+      this.multiplexer = new SubscriptionMultiplexer(
+        new BinanceStreamProtocol(),
+        {
+          initialMessageTimeoutMs: config.initialMessageTimeoutMs,
+          staleAfterMs: config.staleAfterMs,
+          reconnectDelayMs: config.reconnectDelayMs,
+          reconnectMaxDelayMs: config.reconnectMaxDelayMs,
+          controlFrameMaxPerSec: BINANCE_CONTROL_FRAME_MAX_PER_SEC,
+          maxSubscriptionsPerConnection:
+            BINANCE_MAX_SUBSCRIPTIONS_PER_CONNECTION,
+          now: config.now,
+        },
+      );
+      this.multiplexerConfig = config;
+      return this.multiplexer;
+    }
+
+    if (
+      !this.multiplexerConfig ||
+      !sameMultiplexerConfig(config, this.multiplexerConfig)
+    ) {
+      throw new Error(
+        "Binance market stream options differ from the active multiplexer; create a new adapter instance for different stream timing options",
+      );
+    }
+
+    return this.multiplexer;
   }
 }
+
+function sameMultiplexerConfig(
+  left: BinanceMultiplexerConfig,
+  right: BinanceMultiplexerConfig,
+): boolean {
+  return (
+    left.initialMessageTimeoutMs === right.initialMessageTimeoutMs &&
+    left.staleAfterMs === right.staleAfterMs &&
+    left.reconnectDelayMs === right.reconnectDelayMs &&
+    left.reconnectMaxDelayMs === right.reconnectMaxDelayMs &&
+    left.now === right.now
+  );
+}

package/src/adapters/binance/stream-protocol.ts

@@ -0,0 +1,202 @@
+import type { VenueStreamProtocol } from "../../internal/subscription-multiplexer.ts";
+import type { BinanceMarketDefinition } from "./market-catalog.ts";
+
+export type BinanceStreamChannel = "l1book" | "fundingRate";
+
+export interface BinanceStreamDescriptor {
+  readonly channel: BinanceStreamChannel;
+  readonly market: BinanceMarketDefinition;
+}
+
+export interface BinanceStreamMessage {
+  readonly result?: unknown;
+  readonly id?: number | string;
+  readonly e?: string;
+  readonly E?: number;
+  readonly s?: string;
+  readonly b?: string;
+  readonly B?: string;
+  readonly a?: string;
+  readonly A?: string;
+  readonly p?: string;
+  readonly i?: string;
+  readonly r?: string;
+  readonly T?: number;
+}
+
+export type BinanceStreamPayload =
+  | {
+      readonly channel: "l1book";
+      readonly bidPrice: string;
+      readonly bidSize: string;
+      readonly askPrice: string;
+      readonly askSize: string;
+      readonly exchangeTs?: number;
+    }
+  | {
+      readonly channel: "fundingRate";
+      readonly fundingRate: string;
+      readonly nextFundingTime?: number;
+      readonly markPrice?: string;
+      readonly indexPrice?: string;
+      readonly exchangeTs?: number;
+    };
+
+const BINANCE_SPOT_WS_BASE_URL = "wss://stream.binance.com:9443/ws";
+const BINANCE_USDM_WS_BASE_URL = "wss://fstream.binance.com/ws";
+const BINANCE_USDM_MARKET_WS_BASE_URL = "wss://fstream.binance.com/market/ws";
+const BINANCE_COINM_WS_BASE_URL = "wss://dstream.binance.com/ws";
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function hasField(value: object, field: keyof BinanceStreamMessage): boolean {
+  return Object.hasOwn(value, field);
+}
+
+function streamName(descriptor: BinanceStreamDescriptor): string {
+  const channel = descriptor.channel === "l1book" ? "bookTicker" : "markPrice";
+  return `${descriptor.market.id.toLowerCase()}@${channel}`;
+}
+
+function connectionKeyFor(descriptor: BinanceStreamDescriptor): string {
+  switch (descriptor.market.family) {
+    case "spot":
+      if (descriptor.channel === "fundingRate") {
+        throw new Error(
+          `Funding rate is not supported for spot market: ${descriptor.market.symbol}`,
+        );
+      }
+      return BINANCE_SPOT_WS_BASE_URL;
+    case "usdm":
+      return descriptor.channel === "l1book"
+        ? BINANCE_USDM_WS_BASE_URL
+        : BINANCE_USDM_MARKET_WS_BASE_URL;
+    case "coinm":
+      return BINANCE_COINM_WS_BASE_URL;
+  }
+}
+
+export class BinanceStreamProtocol
+  implements
+    VenueStreamProtocol<
+      BinanceStreamMessage,
+      BinanceStreamDescriptor,
+      BinanceStreamPayload
+    >
+{
+  private nextControlFrameId = 1;
+
+  subscriptionKey(descriptor: BinanceStreamDescriptor): string {
+    return `${descriptor.channel}:${descriptor.market.id}`;
+  }
+
+  connectionKey(descriptor: BinanceStreamDescriptor): string {
+    return connectionKeyFor(descriptor);
+  }
+
+  connectionUrl(connectionKey: string): string {
+    return connectionKey;
+  }
+
+  parseMessage(data: string): BinanceStreamMessage | undefined {
+    try {
+      const parsed = JSON.parse(data) as unknown;
+      if (!isRecord(parsed)) {
+        return undefined;
+      }
+
+      return parsed;
+    } catch {
+      return undefined;
+    }
+  }
+
+  encodeSubscribe(descriptors: BinanceStreamDescriptor[]): string {
+    return this.encodeControlFrame("SUBSCRIBE", descriptors);
+  }
+
+  encodeUnsubscribe(descriptors: BinanceStreamDescriptor[]): string {
+    return this.encodeControlFrame("UNSUBSCRIBE", descriptors);
+  }
+
+  routeMessage(message: BinanceStreamMessage):
+    | {
+        kind: "data";
+        subscriptionKey: string;
+        payload: BinanceStreamPayload;
+      }
+    | { kind: "ack" }
+    | { kind: "ignore" } {
+    if (hasField(message, "result") || this.isIdOnlyAck(message)) {
+      return { kind: "ack" };
+    }
+
+    if (
+      typeof message.s === "string" &&
+      typeof message.r === "string" &&
+      message.e === "markPriceUpdate"
+    ) {
+      return {
+        kind: "data",
+        subscriptionKey: `fundingRate:${message.s}`,
+        payload: {
+          channel: "fundingRate",
+          fundingRate: message.r,
+          nextFundingTime: message.T,
+          markPrice: message.p,
+          indexPrice: message.i,
+          exchangeTs: message.E,
+        },
+      };
+    }
+
+    if (
+      typeof message.s === "string" &&
+      typeof message.b === "string" &&
+      typeof message.B === "string" &&
+      typeof message.a === "string" &&
+      typeof message.A === "string"
+    ) {
+      return {
+        kind: "data",
+        subscriptionKey: `l1book:${message.s}`,
+        payload: {
+          channel: "l1book",
+          bidPrice: message.b,
+          bidSize: message.B,
+          askPrice: message.a,
+          askSize: message.A,
+          exchangeTs: message.T,
+        },
+      };
+    }
+
+    return { kind: "ignore" };
+  }
+
+  private encodeControlFrame(
+    method: "SUBSCRIBE" | "UNSUBSCRIBE",
+    descriptors: BinanceStreamDescriptor[],
+  ): string {
+    const frame = {
+      method,
+      params: descriptors.map(streamName),
+      id: this.nextControlFrameId,
+    };
+    this.nextControlFrameId += 1;
+    return JSON.stringify(frame);
+  }
+
+  private isIdOnlyAck(message: BinanceStreamMessage): boolean {
+    return (
+      message.id !== undefined &&
+      message.e === undefined &&
+      message.s === undefined &&
+      message.b === undefined &&
+      message.a === undefined &&
+      message.r === undefined
+    );
+  }
+}

package/src/client/runtime.ts

@@ -115,7 +115,7 @@ export class AcexClientImpl implements AcexClient, ClientContext {
       privateAdapters.map((adapter) => [adapter.venue, adapter]),
     );
 
-    this.marketManager = new MarketManagerImpl(this, marketAdapter, {
+    this.marketManager = new MarketManagerImpl(this, this.marketAdapters, {
       initialL1TimeoutMs: options.market?.l1InitialMessageTimeoutMs,
       l1StaleAfterMs: options.market?.l1StaleAfterMs,
       l1ReconnectDelayMs: options.market?.l1ReconnectDelayMs,

package/src/internal/managed-websocket.ts

@@ -33,6 +33,7 @@ export interface ManagedWebSocketOptions<TMessage> {
 
 export interface ManagedWebSocketSession {
   readonly ready: Promise<void>;
+  send(data: string): void;
   close(): void;
 }
 
@@ -265,6 +266,13 @@ export function createManagedWebSocket<TMessage>(
 
   return {
     ready,
+    send(data: string): void {
+      if (!activeSocket || activeSocket.readyState !== WebSocket.OPEN) {
+        return;
+      }
+
+      activeSocket.send(data);
+    },
     close() {
       if (closed) {
         return;