@katanaperps/katana-perps-sdk 0.0.0-placeholder

package/dist/client/orderBook/realTime.js

@@ -0,0 +1,344 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OrderBookRealTimeClient = void 0;
+const events_1 = require("events");
+const _pipmath_1 = require("#pipmath");
+const _utils_1 = require("#utils");
+const utils_1 = require("#client/orderBook/utils");
+const public_1 = require("#client/rest/public");
+const index_1 = require("#client/webSocket/index");
+const apiConversions_1 = require("#orderbook/apiConversions");
+const quantities_1 = require("#orderbook/quantities");
+const utils_2 = require("#orderbook/utils");
+const index_2 = require("#types/enums/index");
+/**
+ * Orderbook API client
+ *
+ * @see typedoc  [Reference Documentation](https://sdk-js-docs-v1-perps.katana.network/classes/OrderBookRealTimeClient.html)
+ * @see options  {@link OrderBookRealTimeClientOptions}
+ * @see events   {@link OrderBookRealTimeClientEvent}
+ *
+ * @category API Clients
+ *
+ * @example
+ * ```typescript
+ * import {
+ *  OrderBookRealTimeClient,
+ *  OrderBookRealTimeClientEvent,
+ *  type L2OrderBook
+ * } from '@katanaperps/katana-perps-sdk';
+ *
+ * // type is just to show it will match the form string-string.
+ * // actual type will be typed as string
+ * type MarketSymbol = `${string}-${string}`;
+ *
+ * const LIMIT = 10;
+ * const MARKETS: MarketSymbol[] = ['BTC-USD'];
+ *
+ * const client = new OrderBookRealTimeClient({
+ *   sandbox: true,
+ * });
+ *
+ * client.start(MARKETS);
+ *
+ * const orderbooksMap = new Map<MarketSymbol, L2OrderBook>()
+ *
+ * async function handleOrderBookLevel2(market: MarketSymbol) {
+ *   const levelTwoOrderBook = await client.getOrderBookL2(market, LIMIT);
+ *
+ *   orderbooksMap.set(market, levelTwoOrderBook)
+ *
+ *   console.log('Updated OrderBook for market: ', market, levelTwoOrderBook);
+ * }
+ *
+ * client.on(OrderBookRealTimeClientEvent.ready, () => {
+ *  MARKETS.forEach(market => {
+ *    handleOrderBookLevel2(market)
+ *  })
+ * });
+ *
+ * client.on(OrderBookRealTimeClientEvent.l2, handleOrderBookLevel2);
+ * ```
+ */
+class OrderBookRealTimeClient extends events_1.EventEmitter {
+    l1OrderBooks = new Map();
+    l2OrderBooks = new Map();
+    l2OrderBookUpdates = new Map();
+    markets = [];
+    marketsByAssetSymbol = new Map();
+    /**
+     * When creating an {@link OrderBookRealTimeClient}, a public client is automatically
+     * created and can be used based to make additional public requests if needed.
+     *
+     * - Can be utilized to fetch public data instead of creating both clients.
+     *
+     * @category Accessors
+     */
+    public;
+    marketsResponse = undefined;
+    isTickSizesLoaded = false;
+    tickSizesByMarket = new Map();
+    webSocketClient;
+    webSocketConnectionListenersConfigured = false;
+    webSocketResponseListenerConfigured = false;
+    /**
+     * @see typedoc  [Reference Documentation](https://sdk-js-docs-v1-perps.katana.network/classes/OrderBookRealTimeClient.html)
+     *
+     * @category Constructor
+     */
+    constructor(options = {}) {
+        super();
+        const { sandbox = false } = options;
+        this.marketsResponse = options.marketsResponse;
+        this.public = new public_1.RestPublicClient({
+            sandbox,
+            apiKey: options.apiKey,
+            baseURL: options.baseRestApiURL,
+        });
+        // monitor realtime client
+        this.public[_utils_1.INTERNAL_SYMBOL].realtime();
+        this.webSocketClient = new index_1.WebSocketClient({
+            sandbox,
+            baseRestApiURL: options.baseRestApiURL,
+            baseWebSocketURL: options.baseWebSocketURL,
+        });
+    }
+    /**
+     * Loads initial state from REST API and begin listening to orderbook updates.
+     *
+     * @see typedoc  [Reference Documentation](https://sdk-js-docs-v1-perps.katana.network/classes/OrderBookRealTimeClient.html#start)
+     *
+     * @category Connection Management
+     */
+    async start(markets, marketsResponse) {
+        this.markets = markets;
+        if (marketsResponse) {
+            this.marketsResponse = marketsResponse;
+        }
+        this.mapTokensToMarkets();
+        this.setupInternalWebSocket();
+        await this.webSocketClient.connect(true);
+    }
+    /**
+     * Stop the order book client, and reset internal state.
+     * Call this when you are no longer using the client, to release memory and network resources.
+     *
+     * @see typedoc  [Reference Documentation](https://sdk-js-docs-v1-perps.katana.network/classes/OrderBookRealTimeClient.html#stop)
+     *
+     * @category Connection Management
+     */
+    stop() {
+        if (this.webSocketClient.isConnected) {
+            this.unsubscribe();
+            this.webSocketClient.disconnect();
+        }
+        this.resetInternalState(true);
+    }
+    async getMaximumTickSizeUnderSpread(market) {
+        const { bids } = await this.getOrderBookL2(market, 1000);
+        const minBidPrice = bids.length > 0 && bids[bids.length - 1][0];
+        const numDigits = minBidPrice ?
+            (0, _pipmath_1.decimalToPip)(minBidPrice).toString().length
+            : _pipmath_1.exchangeDecimals;
+        return BigInt(10 ** (Math.min(numDigits, _pipmath_1.exchangeDecimals) - 1));
+    }
+    /**
+     * Load the current state of the level 1 orderbook for this market.
+     *
+     * @param tickSize
+     *   Minimum price movement expressed in pips (10^-8), defaults to market setting
+     *
+     * @see typedoc  [Reference Documentation](https://sdk-js-docs-v1-perps.katana.network/classes/OrderBookRealTimeClient.html#getOrderBookL1)
+     * @see response {@link RestResponseGetOrderBookLevel1}
+     *
+     * @category Requests
+     */
+    async getOrderBookL1(market, tickSize) {
+        return (0, apiConversions_1.L1OrderBookToRestResponse)((await this.getOrderBooks(market, tickSize)).l1);
+    }
+    /**
+     * Load the current state of the level 2 orderbook for this market.
+     *
+     * @param limit
+     *   Total number of price levels (bids + asks) to return
+     *   - Between 2 and 1000
+     *   - Defaults to `100`
+     * @param tickSize
+     *   Minimum price movement expressed in pips (10^-8), defaults to market setting
+     *
+     * @see typedoc  [Reference Documentation](https://sdk-js-docs-v1-perps.katana.network/classes/OrderBookRealTimeClient.html#getOrderBookL2)
+     * @see response {@link RestResponseGetOrderBookLevel2}
+     *
+     * @category Requests
+     */
+    async getOrderBookL2(market, limit, tickSize) {
+        return (0, apiConversions_1.L2OrderBookToRestResponse)((await this.getOrderBooks(market, tickSize)).l2, limit ?? 100);
+    }
+    async getOrderBooks(market, tickSize) {
+        const appliedTickSize = tickSize || this.tickSizesByMarket.get(market) || BigInt(1);
+        const l2 = (0, quantities_1.aggregateL2OrderBookAtTickSize)(await this.loadLevel2(market), appliedTickSize);
+        return { l1: (0, utils_2.L2toL1OrderBook)(l2), l2 };
+    }
+    async applyOrderBookUpdates(market) {
+        const updates = this.l2OrderBookUpdates.get(market);
+        if (!updates) {
+            return;
+        }
+        const book = this.l2OrderBooks.get(market);
+        // If this market has not yet been synchronized from the REST API, then halt processing -
+        // messages for the market will queue and proccess after it runs
+        if (!book) {
+            return;
+        }
+        const beforeL1 = (0, utils_2.L2toL1OrderBook)(book);
+        for (const update of updates) {
+            // outdated sequence, ignore
+            if (book.sequence >= update.sequence) {
+                // eslint-disable-next-line no-continue
+                continue;
+            }
+            // an expected next update has arrived
+            else if (book.sequence + 1 === update.sequence) {
+                (0, utils_1.updateL2Levels)(book, update);
+            }
+            else {
+                // If an invalid update arrives, reset all data and synchronize anew
+                this.emit(index_2.OrderBookRealTimeClientEvent.disconnected);
+                this.emit(index_2.OrderBookRealTimeClientEvent.error, new Error(`Missing l2 update sequence, current book is ${book.sequence} message was ${update.sequence}, awaiting ${update.sequence - book.sequence} updates from REST API...`));
+                // this.unsubscribe();
+                this.resetInternalState();
+                // this.subscribe();
+                // eslint-disable-next-line no-await-in-loop
+                await this.synchronizeFromRestApi();
+                this.emit(index_2.OrderBookRealTimeClientEvent.connected);
+                return;
+            }
+        }
+        const afterL1 = (0, utils_2.L2toL1OrderBook)(book);
+        this.l1OrderBooks.set(market, (0, utils_2.L2toL1OrderBook)(book));
+        if (!(0, utils_1.L1Equal)(beforeL1, afterL1)) {
+            this.emit(index_2.OrderBookRealTimeClientEvent.l1, market);
+        }
+        this.emit(index_2.OrderBookRealTimeClientEvent.l2, market);
+        this.l2OrderBookUpdates.delete(market);
+    }
+    async synchronizeFromRestApi() {
+        let reconnectAttempt = 0;
+        // Updates cannot be applied until successfully synchronized with the REST API, so keep trying
+        // with exponential backoff until success
+        // eslint-disable-next-line no-constant-condition
+        while (true) {
+            const backoffSeconds = 2 ** reconnectAttempt;
+            reconnectAttempt += 1;
+            try {
+                // Load minimums and token prices first so synthetic orderbook calculations are accurate
+                // eslint-disable-next-line no-await-in-loop
+                await this.loadTickSizes();
+                // eslint-disable-next-line no-await-in-loop
+                await Promise.all([
+                    ...this.markets.map(async (market) => {
+                        await this.loadLevel2(market);
+                        this.emit(index_2.OrderBookRealTimeClientEvent.ready, market);
+                    }),
+                ]);
+                return;
+            }
+            catch (error) {
+                this.emit(index_2.OrderBookRealTimeClientEvent.error, error);
+                // eslint-disable-next-line no-await-in-loop
+                await sleep(backoffSeconds * 1000);
+            }
+        }
+    }
+    async loadLevel2(market) {
+        let l2 = this.l2OrderBooks.get(market);
+        if (!l2) {
+            this.emit(index_2.OrderBookRealTimeClientEvent.sync, market);
+            l2 = (0, apiConversions_1.restResponseToL2OrderBook)(await this.public.getOrderBookLevel2({
+                market,
+                limit: 1000,
+            }));
+        }
+        this.l2OrderBooks.set(market, l2);
+        return l2;
+    }
+    async loadTickSizes() {
+        // Market tick sizes only need to be loaded once as they are effectively static
+        if (this.isTickSizesLoaded) {
+            return;
+        }
+        this.marketsResponse =
+            this.marketsResponse ?? (await this.public.getMarkets());
+        for (const market of this.marketsResponse) {
+            this.tickSizesByMarket.set(market.market, (0, _pipmath_1.decimalToPip)(market.tickSize));
+        }
+        this.isTickSizesLoaded = true;
+    }
+    mapTokensToMarkets() {
+        for (const market of this.markets) {
+            const [baseSymbol, quoteSymbol] = market.split('-');
+            const marketsByBase = this.marketsByAssetSymbol.get(baseSymbol) || new Set();
+            marketsByBase.add(market);
+            this.marketsByAssetSymbol.set(baseSymbol, marketsByBase);
+            const marketsByQuote = this.marketsByAssetSymbol.get(quoteSymbol) || new Set();
+            marketsByQuote.add(market);
+            this.marketsByAssetSymbol.set(quoteSymbol, marketsByQuote);
+        }
+    }
+    resetInternalState(includeUpdates = false) {
+        this.l1OrderBooks.clear();
+        this.l2OrderBooks.clear();
+        if (includeUpdates) {
+            this.l2OrderBookUpdates.clear();
+        }
+        //
+    }
+    /* Connection management */
+    setupInternalWebSocket() {
+        if (!this.webSocketConnectionListenersConfigured) {
+            this.webSocketClient.onConnect(this.webSocketHandleConnect.bind(this));
+            this.webSocketClient.onDisconnect(this.webSocketHandleDisconnect.bind(this));
+            this.webSocketClient.onError(this.webSocketHandleError.bind(this));
+            this.webSocketConnectionListenersConfigured = true;
+        }
+    }
+    subscribe() {
+        this.webSocketClient.subscribePublic([{ name: index_2.SubscriptionNamePublic.l2orderbook }], this.markets);
+    }
+    unsubscribe() {
+        this.webSocketClient.unsubscribe([index_2.SubscriptionNamePublic.l2orderbook]);
+    }
+    /* Event handlers */
+    async webSocketHandleConnect() {
+        if (!this.webSocketResponseListenerConfigured) {
+            this.webSocketClient.onMessage(this.webSocketHandleResponse.bind(this));
+            this.webSocketResponseListenerConfigured = true;
+        }
+        this.subscribe();
+        await this.synchronizeFromRestApi();
+        this.emit(index_2.OrderBookRealTimeClientEvent.connected);
+    }
+    webSocketHandleDisconnect() {
+        // Assume messages will be lost during disconnection and clear state. State will be re-synchronized again on reconnect
+        this.resetInternalState(true);
+        this.emit(index_2.OrderBookRealTimeClientEvent.disconnected);
+    }
+    webSocketHandleError(error) {
+        this.emit(index_2.OrderBookRealTimeClientEvent.error, error instanceof Error ? error : error.error);
+    }
+    async webSocketHandleResponse(response) {
+        if (response.type === index_2.MessageEventType.l2orderbook) {
+            // accumulate L2 updates to be applied
+            const updatesToApply = this.l2OrderBookUpdates.get(response.data.market) || [];
+            updatesToApply.push((0, apiConversions_1.webSocketResponseToL2OrderBook)(response.data));
+            this.l2OrderBookUpdates.set(response.data.market, updatesToApply);
+            await this.applyOrderBookUpdates(response.data.market);
+        }
+    }
+}
+exports.OrderBookRealTimeClient = OrderBookRealTimeClient;
+function sleep(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}

package/dist/client/orderBook/utils.d.ts

@@ -0,0 +1,15 @@
+import type { L1OrderBook, L2OrderBook } from '#types/orderBook';
+/**
+ * Determine whether two level 1 order books are equal
+ */
+export declare function L1Equal(beforeL1: L1OrderBook, afterL1: L1OrderBook): boolean;
+/**
+ * Updates a level 2 orderbook using a partial "diff" received over websockets
+ *
+ * @param updatedLevels
+ * - level 2 orderbook containing only limit order price levels that have changed
+ *
+ * @returns orderbook is updated in-place
+ */
+export declare function updateL2Levels(book: L2OrderBook, updatedLevels: L2OrderBook): void;
+//# sourceMappingURL=utils.d.ts.map

package/dist/client/orderBook/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../../src/client/orderBook/utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,WAAW,EACX,WAAW,EAEZ,MAAM,kBAAkB,CAAC;AAE1B;;GAEG;AACH,wBAAgB,OAAO,CAAC,QAAQ,EAAE,WAAW,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAS5E;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,WAAW,EACjB,aAAa,EAAE,WAAW,GACzB,IAAI,CAMN"}

package/dist/client/orderBook/utils.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.updateL2Levels = exports.L1Equal = void 0;
+/**
+ * Determine whether two level 1 order books are equal
+ */
+function L1Equal(beforeL1, afterL1) {
+    return (beforeL1.asks.price === afterL1.asks.price &&
+        beforeL1.bids.price === afterL1.bids.price &&
+        beforeL1.asks.size === afterL1.asks.size &&
+        beforeL1.bids.size === afterL1.bids.size &&
+        beforeL1.asks.numOrders === afterL1.asks.numOrders &&
+        beforeL1.bids.numOrders === afterL1.bids.numOrders);
+}
+exports.L1Equal = L1Equal;
+/**
+ * Updates a level 2 orderbook using a partial "diff" received over websockets
+ *
+ * @param updatedLevels
+ * - level 2 orderbook containing only limit order price levels that have changed
+ *
+ * @returns orderbook is updated in-place
+ */
+function updateL2Levels(book, updatedLevels) {
+    /* eslint-disable no-param-reassign */
+    book.sequence = updatedLevels.sequence;
+    book.asks = updateL2Side(true, book.asks, updatedLevels.asks);
+    book.bids = updateL2Side(false, book.bids, updatedLevels.bids);
+    /* eslint-enable no-param-reassign */
+}
+exports.updateL2Levels = updateL2Levels;
+function isBeforeOrEqual(isAscending, a, b) {
+    if (isAscending && a.price <= b.price) {
+        return true;
+    }
+    if (!isAscending && a.price >= b.price) {
+        return true;
+    }
+    return false;
+}
+/**
+ * Applies a changeset to a single side of the orderbook
+ *
+ * @param {boolean} isAscending
+ *   `true` for asks, `false` for bids (ordering of price levels)
+ */
+function updateL2Side(isAscending, side, updates) {
+    let nextUpdate = updates.shift();
+    if (!nextUpdate) {
+        return side;
+    }
+    let lastPriceUpdated = BigInt(0);
+    const newLevels = [];
+    for (const level of side) {
+        // push all updated price levels prior to the existing level
+        // skip any with no size, and no orders
+        while (nextUpdate && isBeforeOrEqual(isAscending, nextUpdate, level)) {
+            if (nextUpdate.size > BigInt(0) && nextUpdate.numOrders > BigInt(0)) {
+                newLevels.push(nextUpdate);
+            }
+            lastPriceUpdated = nextUpdate.price;
+            nextUpdate = updates.shift();
+        }
+        // if the current level was not already updated, add it
+        if (level.price !== lastPriceUpdated) {
+            newLevels.push(level);
+        }
+    }
+    // add all updates that go beyond the current end of the book
+    while (nextUpdate &&
+        nextUpdate.size > BigInt(0) &&
+        nextUpdate.numOrders > BigInt(0)) {
+        newLevels.push(nextUpdate);
+        nextUpdate = updates.shift();
+    }
+    return newLevels;
+}