@0xmonaco/core 1.1.5 → 1.1.6

package/dist/api/websocket/local-book.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Local depth book and BBO state for the market-data `depth` / `bbo`
+ * WebSocket channels (0XM-3551).
+ *
+ * Handoff rules (the server enforces them; the client checks defensively):
+ * - A Snapshot replaces the local state, including mid-stream.
+ * - A frame with `book_seq <=` the current sequence is stale or a duplicate
+ *   and is dropped.
+ * - Every kept frame must have `prev_book_seq <=` the current sequence (the
+ *   snapshot's for the first frame, else the last applied frame's): a delta
+ *   restates every level changed since its link, so it may link below the
+ *   previous frame. A frame that links above it means a lost frame: rebuild
+ *   from a new snapshot.
+ * - A BBO frame carries the whole top of book, so any frame newer than the
+ *   state applies without a link check.
+ * - Frames that arrive before the snapshot are buffered and replayed through
+ *   the same rules once it lands.
+ * - On a side whose snapshot was not complete, levels beyond its deepest
+ *   returned level are unknown, so the book keeps only levels at or better
+ *   than that boundary.
+ *
+ * Sequences are u64 durable-log positions, held as decimal strings and
+ * compared as `BigInt`.
+ */
+import type { Bbo, BboEvent, BboSnapshot, DepthBook, DepthDelta, DepthSnapshot } from "@0xmonaco/types";
+/**
+ * Quote the market-data sequence numbers in a raw frame before `JSON.parse`,
+ * so a u64 above `Number.MAX_SAFE_INTEGER` survives exactly. Only the
+ * unescaped `"book_seq":` / `"prev_book_seq":` keys followed by an integer are
+ * touched; inside a JSON string those quotes would be escaped.
+ */
+export declare function quoteSequenceNumbers(raw: string): string;
+/**
+ * {@link readSequence} that leaves an absent or malformed value `undefined`
+ * instead of throwing. A JSON number counts only while it is still exact (a
+ * quoted integer always does), so a rounded u64 never passes for a precise one.
+ */
+export declare function tryReadSequence(data: Record<string, unknown>, key: string): string | undefined;
+export declare function parseDepthSnapshot(raw: unknown): DepthSnapshot;
+export declare function parseDepthDelta(raw: unknown): DepthDelta;
+export declare function parseBboSnapshot(raw: unknown): BboSnapshot;
+export declare function parseBboEvent(raw: unknown): BboEvent;
+/** Compare two non-negative decimal strings numerically. */
+export declare function compareDecimal(a: string, b: string): number;
+/** The result of offering a frame to the local state. */
+export type FrameOutcome = 
+/** Applied; the state moved forward. */
+"applied"
+/** Held until the snapshot arrives. */
+ | "buffered"
+/** Stale or a duplicate. */
+ | "dropped"
+/** Did not link: a frame was lost. */
+ | "gap"
+/** Applied, but a side whose snapshot was incomplete is now empty: its remainder is unknown. */
+ | "truncated";
+/** The result of applying a snapshot (with any buffered frames replayed). */
+export type SnapshotOutcome = "applied" | "gap" | "truncated";
+/**
+ * The sequence guard shared by `depth` and `bbo`: snapshot replaces, stale
+ * frames drop, a frame linking above the current sequence is a gap, frames
+ * before the snapshot buffer.
+ */
+declare abstract class SequencedState<Snapshot extends {
+    bookSeq: string;
+}, Frame extends {
+    bookSeq: string;
+    prevBookSeq: string;
+}> {
+    private current;
+    private buffered;
+    /**
+     * Whether a frame must link to the current state. Depth deltas carry only
+     * changed levels, so a frame past a lost one is a gap; a BBO frame carries
+     * the whole top of book, so any newer one is complete on its own.
+     */
+    protected readonly checksLinks: boolean;
+    /** Whether a snapshot has been applied since the last reset. */
+    get ready(): boolean;
+    protected abstract resetFrom(snapshot: Snapshot): void;
+    protected abstract applyFrame(frame: Frame): void;
+    /** Whether the state can no longer be trusted past its known levels (see `"truncated"`). */
+    protected truncated(): boolean;
+    /** Replace the state with `snapshot`, then replay buffered frames. Returns `"gap"` if a buffered frame does not link. */
+    applySnapshot(snapshot: Snapshot): SnapshotOutcome;
+    /** Offer a live frame. */
+    offer(frame: Frame): FrameOutcome;
+    /** Discard everything; the next snapshot starts over. */
+    reset(): void;
+}
+/** The local depth book for one `depth` channel. */
+export declare class LocalDepthBook extends SequencedState<DepthSnapshot, DepthDelta> {
+    private readonly bids;
+    private readonly asks;
+    private header;
+    protected resetFrom(snapshot: DepthSnapshot): void;
+    protected applyFrame(frame: DepthDelta): void;
+    protected truncated(): boolean;
+    reset(): void;
+    /** The current book, or `null` before a snapshot. */
+    view(): DepthBook | null;
+}
+/** The local top of book for one `bbo` channel. */
+export declare class LocalBbo extends SequencedState<BboSnapshot, BboEvent> {
+    protected readonly checksLinks = false;
+    private state;
+    protected resetFrom(snapshot: BboSnapshot): void;
+    protected applyFrame(frame: BboEvent): void;
+    reset(): void;
+    view(): Bbo | null;
+}
+export {};

package/dist/api/websocket/local-book.js

@@ -0,0 +1,423 @@
+/**
+ * Local depth book and BBO state for the market-data `depth` / `bbo`
+ * WebSocket channels (0XM-3551).
+ *
+ * Handoff rules (the server enforces them; the client checks defensively):
+ * - A Snapshot replaces the local state, including mid-stream.
+ * - A frame with `book_seq <=` the current sequence is stale or a duplicate
+ *   and is dropped.
+ * - Every kept frame must have `prev_book_seq <=` the current sequence (the
+ *   snapshot's for the first frame, else the last applied frame's): a delta
+ *   restates every level changed since its link, so it may link below the
+ *   previous frame. A frame that links above it means a lost frame: rebuild
+ *   from a new snapshot.
+ * - A BBO frame carries the whole top of book, so any frame newer than the
+ *   state applies without a link check.
+ * - Frames that arrive before the snapshot are buffered and replayed through
+ *   the same rules once it lands.
+ * - On a side whose snapshot was not complete, levels beyond its deepest
+ *   returned level are unknown, so the book keeps only levels at or better
+ *   than that boundary.
+ *
+ * Sequences are u64 durable-log positions, held as decimal strings and
+ * compared as `BigInt`.
+ */
+/** Frames buffered before a snapshot; past it the oldest are dropped (the link check catches the hole). */
+const MAX_BUFFERED_FRAMES = 10_000;
+const SEQUENCE_KEYS = ["book_seq", "prev_book_seq"];
+// A whole integer only: a fractional or exponent value is left as it is, so
+// `JSON.parse` still reads it and the lenient readers leave it unset.
+const SEQUENCE_KEY_PATTERN = new RegExp(`"(${SEQUENCE_KEYS.join("|")})"\\s*:\\s*(\\d+)(?![\\d.eE])`, "g");
+/**
+ * Quote the market-data sequence numbers in a raw frame before `JSON.parse`,
+ * so a u64 above `Number.MAX_SAFE_INTEGER` survives exactly. Only the
+ * unescaped `"book_seq":` / `"prev_book_seq":` keys followed by an integer are
+ * touched; inside a JSON string those quotes would be escaped.
+ */
+export function quoteSequenceNumbers(raw) {
+    if (!raw.includes("book_seq"))
+        return raw;
+    return raw.replace(SEQUENCE_KEY_PATTERN, '"$1":"$2"');
+}
+function asRecord(value, what) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error(`Invalid ${what}: must be an object`);
+    }
+    return value;
+}
+/** A u64 sequence as a decimal string: a quoted integer, or a JSON number that is still exact. */
+function readSequence(data, key) {
+    const sequence = tryReadSequence(data, key);
+    if (sequence === undefined)
+        throw new Error(`Invalid ${key}: must be a non-negative integer`);
+    return sequence;
+}
+/**
+ * {@link readSequence} that leaves an absent or malformed value `undefined`
+ * instead of throwing. A JSON number counts only while it is still exact (a
+ * quoted integer always does), so a rounded u64 never passes for a precise one.
+ */
+export function tryReadSequence(data, key) {
+    const value = data[key];
+    if (typeof value === "string" && /^\d+$/.test(value))
+        return value;
+    if (typeof value === "number" && Number.isSafeInteger(value) && value >= 0)
+        return String(value);
+    return undefined;
+}
+function readString(data, key) {
+    const value = data[key];
+    if (typeof value !== "string")
+        throw new Error(`Invalid ${key}: must be a string`);
+    return value;
+}
+/*
+ * Value fields parse leniently (packages/core/AGENTS.md: an over-strict value
+ * check drops the whole frame, and here a dropped frame costs a rebuild):
+ * numbers and numeric strings are interchangeable, an absent flag takes its
+ * safe default. Identity and sequence fields stay strict.
+ */
+/**
+ * A non-negative number as plain decimal digits: `String(1e-7)` is exponent
+ * notation, which the decimal compare cannot order, so the exponent is
+ * expanded into the digits (the number's shortest round-trip form).
+ */
+function plainDecimal(value) {
+    const text = String(value);
+    const match = /^(\d+)(?:\.(\d+))?e([+-]\d+)$/i.exec(text);
+    if (!match)
+        return text;
+    const [, whole = "0", fraction = "", exponentText = "0"] = match;
+    const digits = whole + fraction;
+    const point = whole.length + Number(exponentText);
+    if (point <= 0)
+        return `0.${"0".repeat(-point)}${digits}`.replace(/\.?0+$/, "") || "0";
+    if (point >= digits.length)
+        return digits + "0".repeat(point - digits.length);
+    return `${digits.slice(0, point)}.${digits.slice(point)}`;
+}
+/** A decimal value as a string: a string as sent, a finite number as plain digits. */
+function readDecimal(data, key) {
+    const value = data[key];
+    if (typeof value === "string")
+        return value;
+    if (typeof value === "number" && Number.isFinite(value) && value >= 0)
+        return plainDecimal(value);
+    throw new Error(`Invalid ${key}: must be a decimal`);
+}
+function readNullableDecimal(data, key) {
+    const value = data[key];
+    if (value === null || value === undefined)
+        return null;
+    return readDecimal(data, key);
+}
+/** A boolean, or `fallback` when absent or not a boolean. */
+function readFlag(data, key, fallback) {
+    const value = data[key];
+    return typeof value === "boolean" ? value : fallback;
+}
+/** A number, or a numeric string; `fallback` otherwise. */
+function readLenientNumber(data, key, fallback) {
+    const value = data[key];
+    const parsed = typeof value === "number" ? value : typeof value === "string" ? Number(value) : Number.NaN;
+    return Number.isFinite(parsed) ? parsed : fallback;
+}
+/** A level's order count: a number or numeric string, required (it decides removals). */
+function readOrderCount(level) {
+    const parsed = readLenientNumber(level, "order_count", Number.NaN);
+    if (!Number.isFinite(parsed) || parsed < 0)
+        throw new Error("Invalid order_count: must be a non-negative number");
+    return Math.trunc(parsed);
+}
+function readLevels(data, key) {
+    const value = data[key];
+    if (value === undefined || value === null)
+        return [];
+    if (!Array.isArray(value))
+        throw new Error(`Invalid ${key}: must be an array`);
+    return value.map((raw) => {
+        const level = asRecord(raw, `${key} level`);
+        return {
+            price: readDecimal(level, "price"),
+            quantity: readDecimal(level, "quantity"),
+            orderCount: readOrderCount(level),
+        };
+    });
+}
+export function parseDepthSnapshot(raw) {
+    const data = asRecord(raw, "depth snapshot");
+    return {
+        tradingPairId: readString(data, "trading_pair_id"),
+        tradingMode: readString(data, "trading_mode"),
+        bookSeq: readSequence(data, "book_seq"),
+        bids: readLevels(data, "bids"),
+        asks: readLevels(data, "asks"),
+        // Absent means unknown: treat the side as incomplete (the safe reading).
+        bidsComplete: readFlag(data, "bids_complete", false),
+        asksComplete: readFlag(data, "asks_complete", false),
+    };
+}
+export function parseDepthDelta(raw) {
+    const data = asRecord(raw, "depth frame");
+    return {
+        tradingPairId: readString(data, "trading_pair_id"),
+        tradingMode: readString(data, "trading_mode"),
+        bookSeq: readSequence(data, "book_seq"),
+        prevBookSeq: readSequence(data, "prev_book_seq"),
+        timestampMs: readLenientNumber(data, "timestamp_ms", 0),
+        bids: readLevels(data, "bids"),
+        asks: readLevels(data, "asks"),
+        stale: readFlag(data, "stale", false),
+    };
+}
+export function parseBboSnapshot(raw) {
+    const data = asRecord(raw, "bbo snapshot");
+    return {
+        tradingPairId: readString(data, "trading_pair_id"),
+        tradingMode: readString(data, "trading_mode"),
+        bookSeq: readSequence(data, "book_seq"),
+        bestBid: readNullableDecimal(data, "best_bid"),
+        bidQty: readNullableDecimal(data, "bid_qty"),
+        bestAsk: readNullableDecimal(data, "best_ask"),
+        askQty: readNullableDecimal(data, "ask_qty"),
+    };
+}
+export function parseBboEvent(raw) {
+    const data = asRecord(raw, "bbo frame");
+    return {
+        ...parseBboSnapshot(data),
+        prevBookSeq: readSequence(data, "prev_book_seq"),
+        timestampMs: readLenientNumber(data, "timestamp_ms", 0),
+        stale: readFlag(data, "stale", false),
+    };
+}
+/** Canonical form of a decimal price, so "64250.50" and "64250.5" are one level. */
+function priceKey(price) {
+    const trimmed = price.trim();
+    const [integer = "0", fraction = ""] = trimmed.split(".");
+    const int = integer.replace(/^0+(?=\d)/, "") || "0";
+    const frac = fraction.replace(/0+$/, "");
+    return frac ? `${int}.${frac}` : int;
+}
+/** Compare two canonical (`priceKey`) non-negative decimals numerically. */
+function compareCanonical(a, b) {
+    const [ai = "0", af = ""] = a.split(".");
+    const [bi = "0", bf = ""] = b.split(".");
+    if (ai.length !== bi.length)
+        return ai.length - bi.length;
+    if (ai !== bi)
+        return ai < bi ? -1 : 1;
+    const width = Math.max(af.length, bf.length);
+    const ap = af.padEnd(width, "0");
+    const bp = bf.padEnd(width, "0");
+    if (ap === bp)
+        return 0;
+    return ap < bp ? -1 : 1;
+}
+/** Compare two non-negative decimal strings numerically. */
+export function compareDecimal(a, b) {
+    return compareCanonical(priceKey(a), priceKey(b));
+}
+/** A zero quantity, or zero orders, removes the level (the server sends both together). */
+function isRemoval(level) {
+    return level.orderCount === 0 || compareDecimal(level.quantity, "0") === 0;
+}
+/**
+ * An incomplete side is refreshed once its known levels fall below this
+ * fraction of what its snapshot held: deltas never bring back the levels
+ * beyond its boundary, so a thinned side would otherwise understate the book.
+ */
+const THIN_SIDE_FRACTION = 0.5;
+/** The deepest a side is kept, matching the server's book mirror and snapshots. */
+const MAX_LEVELS_PER_SIDE = 1000;
+/** One side of the book: levels keyed by canonical price, with an optional boundary. */
+class BookSide {
+    bestFirst;
+    levels = new Map();
+    /** Canonical price of the deepest known level on an incomplete side; levels beyond it are unknown. */
+    boundary = null;
+    /** Whether the side's snapshot was incomplete. */
+    incomplete = false;
+    /** Known levels below which an incomplete side needs a fresh snapshot. */
+    thinBelow = 0;
+    /** Whether every level of the side is known. */
+    get complete() {
+        return !this.incomplete;
+    }
+    /** `bestFirst` orders canonical prices best first (negative when `a` is better). */
+    constructor(bestFirst) {
+        this.bestFirst = bestFirst;
+    }
+    reset(levels, complete) {
+        this.levels.clear();
+        for (const level of levels) {
+            if (!isRemoval(level))
+                this.levels.set(priceKey(level.price), level);
+        }
+        this.incomplete = !complete;
+        const known = [...this.levels.keys()].sort(this.bestFirst);
+        this.boundary = complete ? null : (known.at(-1) ?? null);
+        this.thinBelow = complete ? 0 : Math.max(1, Math.ceil(known.length * THIN_SIDE_FRACTION));
+    }
+    apply(levels) {
+        for (const level of levels) {
+            const key = priceKey(level.price);
+            // Beyond the boundary of an incomplete side nothing is known.
+            if (this.boundary !== null && this.bestFirst(key, this.boundary) > 0)
+                continue;
+            if (isRemoval(level)) {
+                this.levels.delete(key);
+            }
+            else {
+                this.levels.set(key, level);
+            }
+        }
+        // Like the server's mirror, keep at most MAX_LEVELS_PER_SIDE after each
+        // frame: the worst levels go, and the side becomes incomplete at the new
+        // deepest level.
+        if (this.levels.size > MAX_LEVELS_PER_SIDE) {
+            const kept = [...this.levels.keys()].sort(this.bestFirst);
+            for (const key of kept.slice(MAX_LEVELS_PER_SIDE))
+                this.levels.delete(key);
+            this.boundary = kept[MAX_LEVELS_PER_SIDE - 1] ?? null;
+            if (!this.incomplete) {
+                this.incomplete = true;
+                this.thinBelow = Math.ceil(MAX_LEVELS_PER_SIDE * THIN_SIDE_FRACTION);
+            }
+        }
+    }
+    /**
+     * An incomplete side that has thinned below its refresh threshold (or came
+     * back with no level at all): what lies beyond its boundary is unknown and
+     * may now be near the top, so it needs a fresh snapshot.
+     */
+    exhausted() {
+        return this.incomplete && this.levels.size < this.thinBelow;
+    }
+    /** The side, best first, sorted once on the canonical keys. */
+    view() {
+        return [...this.levels.entries()].sort(([a], [b]) => this.bestFirst(a, b)).map(([, level]) => level);
+    }
+}
+/**
+ * The sequence guard shared by `depth` and `bbo`: snapshot replaces, stale
+ * frames drop, a frame linking above the current sequence is a gap, frames
+ * before the snapshot buffer.
+ */
+class SequencedState {
+    current = null;
+    buffered = [];
+    /**
+     * Whether a frame must link to the current state. Depth deltas carry only
+     * changed levels, so a frame past a lost one is a gap; a BBO frame carries
+     * the whole top of book, so any newer one is complete on its own.
+     */
+    checksLinks = true;
+    /** Whether a snapshot has been applied since the last reset. */
+    get ready() {
+        return this.current !== null;
+    }
+    /** Whether the state can no longer be trusted past its known levels (see `"truncated"`). */
+    truncated() {
+        return false;
+    }
+    /** Replace the state with `snapshot`, then replay buffered frames. Returns `"gap"` if a buffered frame does not link. */
+    applySnapshot(snapshot) {
+        this.resetFrom(snapshot);
+        this.current = BigInt(snapshot.bookSeq);
+        const pending = this.buffered;
+        this.buffered = [];
+        for (const frame of pending) {
+            const outcome = this.offer(frame);
+            if (outcome === "gap" || outcome === "truncated")
+                return outcome;
+        }
+        // An incomplete side that came back with no level is unusable as sent.
+        return this.truncated() ? "truncated" : "applied";
+    }
+    /** Offer a live frame. */
+    offer(frame) {
+        if (this.current === null) {
+            this.buffered.push(frame);
+            if (this.buffered.length > MAX_BUFFERED_FRAMES)
+                this.buffered.shift();
+            return "buffered";
+        }
+        const seq = BigInt(frame.bookSeq);
+        if (seq <= this.current)
+            return "dropped";
+        if (this.checksLinks && BigInt(frame.prevBookSeq) > this.current)
+            return "gap";
+        this.applyFrame(frame);
+        this.current = seq;
+        return this.truncated() ? "truncated" : "applied";
+    }
+    /** Discard everything; the next snapshot starts over. */
+    reset() {
+        this.current = null;
+        this.buffered = [];
+    }
+}
+/** The local depth book for one `depth` channel. */
+export class LocalDepthBook extends SequencedState {
+    bids = new BookSide((a, b) => compareCanonical(b, a));
+    asks = new BookSide((a, b) => compareCanonical(a, b));
+    header = null;
+    resetFrom(snapshot) {
+        this.bids.reset(snapshot.bids, snapshot.bidsComplete);
+        this.asks.reset(snapshot.asks, snapshot.asksComplete);
+        this.header = {
+            tradingPairId: snapshot.tradingPairId,
+            tradingMode: snapshot.tradingMode,
+            bookSeq: snapshot.bookSeq,
+            bidsComplete: snapshot.bidsComplete,
+            asksComplete: snapshot.asksComplete,
+            stale: false,
+        };
+    }
+    applyFrame(frame) {
+        this.bids.apply(frame.bids);
+        this.asks.apply(frame.asks);
+        if (this.header) {
+            this.header = { ...this.header, bookSeq: frame.bookSeq, stale: frame.stale, timestampMs: frame.timestampMs };
+        }
+    }
+    truncated() {
+        return this.bids.exhausted() || this.asks.exhausted();
+    }
+    reset() {
+        super.reset();
+        this.header = null;
+    }
+    /** The current book, or `null` before a snapshot. */
+    view() {
+        if (!this.ready || !this.header)
+            return null;
+        return {
+            ...this.header,
+            bids: this.bids.view(),
+            asks: this.asks.view(),
+            bidsComplete: this.bids.complete,
+            asksComplete: this.asks.complete,
+        };
+    }
+}
+/** The local top of book for one `bbo` channel. */
+export class LocalBbo extends SequencedState {
+    checksLinks = false;
+    state = null;
+    resetFrom(snapshot) {
+        this.state = { ...snapshot, stale: false };
+    }
+    applyFrame(frame) {
+        const { prevBookSeq: _prev, ...rest } = frame;
+        this.state = { ...rest };
+    }
+    reset() {
+        super.reset();
+        this.state = null;
+    }
+    view() {
+        return this.ready && this.state ? { ...this.state } : null;
+    }
+}