Merge pull request #474 from fasenderos/snapshot-with-stopbook

feat: add stop orders on snapshot

Author: fasenderos

README.md

@@ -387,6 +387,7 @@ A `snapshot` represents the state of the order book at a specific point in time.
 
  - `asks`: List of ask orders, each with a `price` and a list of associated `orders`.
  - `bids`: List of bid orders, each with a `price` and a list of associated `orders`.
+ - `stopBook`: an object with `bids` and `asks` properties related to every `StopOrder` in the orderbook.
  - `ts`: A timestamp indicating when the snapshot was taken, in Unix timestamp format.
  - `lastOp`: The id of the last operation included in the snapshot
 
@@ -405,7 +406,7 @@ await saveLog(order.log)
 // ... after some time take a snapshot of the order book and save it on the database
 
 const snapshot = ob.snapshot()
-await saveSnapshot(snapshot)
+await saveSnapshot(JSON.stringify(snapshot))
 
 // If you want you can safely remove all logs preceding the `lastOp` id of the snapshot, and continue to save each subsequent log to the database
 await removePreviousLogs(snapshot.lastOp)
@@ -414,7 +415,7 @@ await removePreviousLogs(snapshot.lastOp)
 const logs = await getLogs()
 const snapshot = await getSnapshot()
 
-const ob = new OrderBook({ snapshot, journal: log, enableJournaling: true })
+const ob = new OrderBook({ snapshot: JSON.parse(snapshot), journal: log, enableJournaling: true })
 ```
 
 ### Journal Logs

src/orderbook.ts

@@ -421,7 +421,8 @@ export class OrderBook {
 		this.asks.priceTree().forEach((price: number, orders: OrderQueue) => {
 			asks.push({ price, orders: orders.toArray().map((o) => o.toObject()) });
 		});
-		return { bids, asks, ts: Date.now(), lastOp: this._lastOp };
+		const stopBook = this.stopBook.snapshot();
+		return { bids, asks, stopBook, ts: Date.now(), lastOp: this._lastOp };
 	};
 
 	private readonly _market = (
@@ -572,6 +573,28 @@ export class OrderBook {
 				this.asks.append(newOrder);
 			}
 		}
+
+		if (snapshot.stopBook?.bids?.length > 0) {
+			for (const level of snapshot.stopBook.bids) {
+				for (const order of level.orders) {
+					// @ts-expect-error // TODO fix types
+					const newOrder = OrderFactory.createOrder(order);
+					// @ts-expect-error // TODO fix types
+					this.stopBook.add(newOrder);
+				}
+			}
+		}
+
+		if (snapshot.stopBook?.asks?.length > 0) {
+			for (const level of snapshot.stopBook.asks) {
+				for (const order of level.orders) {
+					// @ts-expect-error // TODO fix types
+					const newOrder = OrderFactory.createOrder(order);
+					// @ts-expect-error // TODO fix types
+					this.stopBook.add(newOrder);
+				}
+			}
+		}
 	};
 
 	/**

src/stopbook.ts

@@ -1,7 +1,7 @@
 /* node:coverage ignore next - Don't know why first and last line of each file count as uncovered */
 import type { StopQueue } from "./stopqueue";
 import { StopSide } from "./stopside";
-import { OrderType, Side, type StopOrder } from "./types";
+import { type IStopOrder, OrderType, Side, type StopOrder } from "./types";
 
 export class StopBook {
 	private readonly bids: StopSide;
@@ -76,5 +76,17 @@ export class StopBook {
 		}
 		return response;
 	};
+
+	snapshot = () => {
+		const bids: Array<{ price: number; orders: IStopOrder[] }> = [];
+		const asks: Array<{ price: number; orders: IStopOrder[] }> = [];
+		this.bids.priceTree().forEach((price: number, orders: StopQueue) => {
+			bids.push({ price, orders: orders.toArray().map((o) => o.toObject()) });
+		});
+		this.asks.priceTree().forEach((price: number, orders: StopQueue) => {
+			asks.push({ price, orders: orders.toArray().map((o) => o.toObject()) });
+		});
+		return { bids, asks };
+	};
 	/* node:coverage ignore next - Don't know why first and last line of each file count as uncovered */
 }

src/stopqueue.ts

@@ -52,5 +52,9 @@ export class StopQueue {
 		}
 		return deletedOrder;
 	};
+
+	toArray = (): StopOrder[] => {
+		return this._orders.toArray();
+	};
 	/* node:coverage ignore next - Don't know why first and last line of each file count as uncovered */
 }

src/stopside.ts

@@ -77,5 +77,9 @@ export class StopSide {
 		);
 		return queues;
 	};
+
+	priceTree = (): createRBTree.Tree<number, StopQueue> => {
+		return this._priceTree;
+	};
 	/* node:coverage ignore next - Don't know why first and last line of each file count as uncovered */
 }

src/types.ts

@@ -399,6 +399,16 @@ export interface Snapshot {
 		/** List of orders associated with this price */
 		orders: ILimitOrder[];
 	}>;
+	stopBook: {
+		asks: Array<{
+			price: number;
+			orders: IStopOrder[];
+		}>;
+		bids: Array<{
+			price: number;
+			orders: IStopOrder[];
+		}>;
+	};
 	/** Unix timestamp representing when the snapshot was taken */
 	ts: number;
 	/** The id of the last operation inserted in the orderbook */

test/orderbook.test.ts

@@ -4,6 +4,7 @@ import { ERROR, ErrorCodes, ErrorMessages } from "../src/errors";
 import type { LimitOrder } from "../src/order";
 import { OrderBook } from "../src/orderbook";
 import type { OrderQueue } from "../src/orderqueue";
+import type { StopQueue } from "../src/stopqueue";
 import {
 	type ILimitOrder,
 	type IProcessOrder,
@@ -12,6 +13,7 @@ import {
 	type JournalLog,
 	OrderType,
 	Side,
+	type StopOrder,
 	TimeInForce,
 } from "../src/types";
 
@@ -1561,12 +1563,48 @@ void test("orderbook replayJournal test wrong journal", () => {
 });
 
 void test("orderbook test snapshot", () => {
-	const ob = new OrderBook();
+	const ob = new OrderBook({ experimentalConditionalOrders: true });
+	const addStopOrder = (
+		side: Side,
+		orderId: string,
+		stopPrice: number,
+	): void => {
+		ob.createOrder({
+			id: orderId,
+			type: OrderType.STOP_LIMIT,
+			side,
+			size: 10,
+			price: stopPrice,
+			stopPrice,
+			timeInForce: TimeInForce.GTC,
+		});
+	};
+	// Inizialize order book with some orders
 	addDepth(ob, "", 10);
+
+	// Add some stop orders
+	//  Start with SELL side
+	addStopOrder(Side.SELL, "sell-1", 110);
+	addStopOrder(Side.SELL, "sell-2", 110); // Same price as before
+	addStopOrder(Side.SELL, "sell-3", 120);
+	addStopOrder(Side.SELL, "sell-4", 130);
+	addStopOrder(Side.SELL, "sell-5", 140);
+
+	// Test BUY side
+	addStopOrder(Side.BUY, "buy-1", 100);
+	addStopOrder(Side.BUY, "buy-2", 100); // Same price as before
+	addStopOrder(Side.BUY, "buy-3", 90);
+	addStopOrder(Side.BUY, "buy-4", 80);
+	addStopOrder(Side.BUY, "buy-5", 70);
+
 	const snapshot = ob.snapshot();
 
 	assert.equal(Array.isArray(snapshot.asks), true);
 	assert.equal(Array.isArray(snapshot.bids), true);
+
+	assert.equal(Array.isArray(snapshot.stopBook.asks), true);
+	assert.equal(Array.isArray(snapshot.stopBook.bids), true);
+
 	assert.equal(typeof snapshot.ts, "number");
 	snapshot.asks.forEach((level) => {
 		assert.equal(typeof level.price, "number");
@@ -1591,15 +1629,84 @@ void test("orderbook test snapshot", () => {
 			assert.equal(order.origSize, 10);
 		});
 	});
+
+	snapshot.stopBook.asks.forEach((level) => {
+		assert.equal(typeof level.price, "number");
+		assert.equal(Array.isArray(level.orders), true);
+		level.orders.forEach((order) => {
+			assert.equal(typeof order.id, "string");
+			assert.equal(order.type, OrderType.STOP_LIMIT);
+			assert.equal(order.side, Side.BUY);
+			assert.equal(order.size, 10);
+			// @ts-expect-error we know exists for IStopLimitOrder
+			assert.equal(typeof order.price, "number");
+			assert.equal(typeof order.stopPrice, "number");
+		});
+	});
+
+	snapshot.stopBook.bids.forEach((level) => {
+		assert.equal(typeof level.price, "number");
+		assert.equal(Array.isArray(level.orders), true);
+		level.orders.forEach((order) => {
+			assert.equal(typeof order.id, "string");
+			assert.equal(order.type, OrderType.STOP_LIMIT);
+			assert.equal(order.side, Side.BUY);
+			assert.equal(order.size, 10);
+			// @ts-expect-error we know exists for IStopLimitOrder
+			assert.equal(typeof order.price, "number");
+			assert.equal(typeof order.stopPrice, "number");
+		});
+	});
 });
 
 void test("orderbook restore from snapshot", () => {
 	// Create a new orderbook with 3 orders for price levels and make a snapshot
 	const journal: JournalLog[] = [];
-	const ob = new OrderBook({ enableJournaling: true });
+	const ob = new OrderBook({
+		enableJournaling: true,
+		experimentalConditionalOrders: true,
+	});
+
+	const addStopOrder = (
+		side: Side,
+		orderId: string,
+		stopPrice: number,
+	): void => {
+		ob.createOrder({
+			id: orderId,
+			type: OrderType.STOP_LIMIT,
+			side,
+			size: 10,
+			price: stopPrice,
+			stopPrice,
+			timeInForce: TimeInForce.GTC,
+		});
+	};
+
+	// Inizialize order book with some orders
 	addDepth(ob, "first-run-", 10, journal);
-	// addDepth(ob, "second-run-", 10, journal);
-	// addDepth(ob, "third-run-", 10, journal);
+	addDepth(ob, "second-run-", 10, journal);
+	addDepth(ob, "third-run-", 10, journal);
+
+	// Add some stop orders
+	// Test BUY side
+	addStopOrder(Side.BUY, "buy-1", 100);
+	addStopOrder(Side.BUY, "buy-2", 100); // Same price as before
+	addStopOrder(Side.BUY, "buy-3", 90);
+	addStopOrder(Side.BUY, "buy-4", 80);
+	addStopOrder(Side.BUY, "buy-5", 70);
+
+	//  Start with SELL side
+	const prevMarketprice = ob.marketPrice;
+	// @ts-expect-error we should hack the marketPrice in order to let stop order to be executed
+	ob._marketPrice = 150;
+	addStopOrder(Side.SELL, "sell-1", 110);
+	addStopOrder(Side.SELL, "sell-2", 110); // Same price as before
+	addStopOrder(Side.SELL, "sell-3", 120);
+	addStopOrder(Side.SELL, "sell-4", 130);
+	addStopOrder(Side.SELL, "sell-5", 140);
+	// @ts-expect-error restore marketPrice to the original market price
+	ob._marketPrice = prevMarketprice;
 
 	const snapshot = ob.snapshot();
 	{
@@ -1608,6 +1715,30 @@ void test("orderbook restore from snapshot", () => {
 
 		assert.equal(ob.toString(), ob2.toString());
 		assert.deepStrictEqual(ob.depth(), ob2.depth());
+		assert.equal(
+			// @ts-expect-error these are private properties
+			ob.stopBook.bids
+				.priceTree()
+				.values.map((queue) => queue.toArray())
+				.join(","),
+			// @ts-expect-error these are private properties
+			ob2.stopBook.bids
+				.priceTree()
+				.values.map((queue) => queue.toArray())
+				.join(","),
+		);
+		assert.equal(
+			// @ts-expect-error these are private properties
+			ob.stopBook.asks
+				.priceTree()
+				.values.map((queue) => queue.toArray())
+				.join(","),
+			// @ts-expect-error these are private properties
+			ob2.stopBook.asks
+				.priceTree()
+				.values.map((queue) => queue.toArray())
+				.join(","),
+		);
 
 		// @ts-expect-error these are private properties
 		Object.entries(ob.orders).forEach(([key, order]) => {
@@ -1661,10 +1792,42 @@ void test("orderbook restore from snapshot", () => {
 			);
 		});
 
+		const prevStopBook: Record<number, StopOrder[]> = {};
+		const restoredStopBook: Record<number, StopOrder[]> = {};
+
+		// @ts-expect-error these are private properties
+		ob.stopBook.asks.priceTree().forEach((price: number, level: StopQueue) => {
+			prevStopBook[price] = level.toArray();
+		});
+
+		// @ts-expect-error these are private properties
+		ob.stopBook.bids.priceTree().forEach((price: number, level: StopQueue) => {
+			prevStopBook[price] = level.toArray();
+		});
+
+		// @ts-expect-error these are private properties
+		ob2.stopBook.asks.priceTree().forEach((price: number, level: StopQueue) => {
+			restoredStopBook[price] = level.toArray();
+		});
+
+		// @ts-expect-error these are private properties
+		ob2.stopBook.bids.priceTree().forEach((price: number, level: StopQueue) => {
+			restoredStopBook[price] = level.toArray();
+		});
+
+		Object.entries(prevStopBook).forEach(([price, orders]) => {
+			assert.deepStrictEqual(
+				orders.map((order) => order.toObject()),
+				restoredStopBook[price].map((order) => order.toObject()),
+			);
+		});
+
 		// Compare also the snapshot from the original order book and the restored one
 		const snapshot2 = ob2.snapshot();
 		assert.deepStrictEqual(snapshot.asks, snapshot2.asks);
 		assert.deepStrictEqual(snapshot.bids, snapshot2.bids);
+		assert.deepStrictEqual(snapshot.stopBook.asks, snapshot2.stopBook.asks);
+		assert.deepStrictEqual(snapshot.stopBook.bids, snapshot2.stopBook.bids);
 	}
 
 	{