@0xmonaco/core 1.1.5 → 1.1.6

package/dist/api/websocket/websocket.js

@@ -2,6 +2,7 @@ import { hexToBytes } from "@noble/hashes/utils.js";
 import { composeWsSigningString, signMessage } from "../../crypto/session";
 import { ALL_MAGNITUDES } from "../../utils";
 import { ServerClock } from "../../utils/server-clock";
+import { LocalBbo, LocalDepthBook, parseBboEvent, parseBboSnapshot, parseDepthDelta, parseDepthSnapshot, quoteSequenceNumbers, tryReadSequence, } from "./local-book";
 import { keysToCamelCase } from "./utils";
 // Connection constants
 const CONNECTION_TIMEOUT = 10000;
@@ -21,6 +22,8 @@ const SKEW_REJECTION = /timestamp outside allowed skew/i;
 // Unsubscribe for listing too many channels, after parsing it (ws-api
 // `oversized_channel_list_message`) or before (`too_many_elements_message`).
 // No ack follows either.
+/** `Resynced` frames arriving this close together form one reported burst. */
+const RESYNCED_BURST_MS = 50;
 const OVERSIZED_REQUEST = /^(?:(?:Subscribe|Unsubscribe) lists \d+ channels; at most \d+ per request|Message lists too many elements; at most \d+ channels per request)$/;
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -431,22 +434,41 @@ function parseRfqSideViewEventData(raw) {
     if (!isRecord(raw)) {
         throw new Error("Invalid RFQ view: a side must be an object");
     }
+    const grossVwap = readOptionalDecimalString(raw, "grossVwap");
+    const estimatedMonacoFee = readOptionalDecimalString(raw, "estimatedMonacoFee");
+    const estimatedBuilderFee = readOptionalDecimalString(raw, "estimatedBuilderFee");
+    const estimatedTotalFee = readOptionalDecimalString(raw, "estimatedTotalFee");
     return {
         vwap: readString(raw, "vwap"),
         availableQuantity: readString(raw, "availableQuantity"),
+        ...(grossVwap !== undefined && { grossVwap }),
+        ...(estimatedMonacoFee !== undefined && { estimatedMonacoFee }),
+        ...(estimatedBuilderFee !== undefined && { estimatedBuilderFee }),
+        ...(estimatedTotalFee !== undefined && { estimatedTotalFee }),
     };
 }
+/** An optional wire integer that may be negative; absent or `null` is `undefined`. */
+function readOptionalInteger(source, field) {
+    const value = source[field];
+    if (value === undefined || value === null)
+        return undefined;
+    return readInteger(source, field);
+}
 /** Parse the taker's view. A side no maker quotes is absent. */
 function parseRfqViewEventData(raw) {
     if (!isRecord(raw)) {
         throw new Error("Invalid RFQ view: view must be an object");
     }
+    const monacoFeeCbps = readOptionalInteger(raw, "monacoFeeCbps");
+    const builderFeeCbps = readOptionalInteger(raw, "builderFeeCbps");
     return {
         viewVersion: readSequence(raw, "viewVersion"),
         ...(raw.bid != null && { bid: parseRfqSideViewEventData(raw.bid) }),
         ...(raw.ask != null && { ask: parseRfqSideViewEventData(raw.ask) }),
         asOfMs: readSequence(raw, "asOfMs"),
         sequence: readSequence(raw, "sequence"),
+        ...(monacoFeeCbps !== undefined && { monacoFeeCbps }),
+        ...(builderFeeCbps !== undefined && { builderFeeCbps }),
     };
 }
 /** Parse a selected maker's own part of an acceptance. */
@@ -454,6 +476,8 @@ function parseRfqSelectionEventData(raw) {
     if (!isRecord(raw)) {
         throw new Error("Invalid RFQ selection: selection must be an object");
     }
+    const maxBuilderFeeCbps = readOptionalInteger(raw, "maxBuilderFeeCbps");
+    const estimatedNet = readOptionalDecimalString(raw, "estimatedNet");
     return {
         acceptanceId: readString(raw, "acceptanceId"),
         takerSide: readString(raw, "takerSide"),
@@ -465,17 +489,23 @@ function parseRfqSelectionEventData(raw) {
         capacity: readString(raw, "capacity"),
         makerFeeCbps: readInteger(raw, "makerFeeCbps"),
         lastLookDeadlineAtMs: readSequence(raw, "lastLookDeadlineAtMs"),
+        ...(maxBuilderFeeCbps !== undefined && { maxBuilderFeeCbps }),
+        ...(estimatedNet !== undefined && { estimatedNet }),
     };
 }
 function parseRfqFillEventData(raw) {
     if (!isRecord(raw)) {
         throw new Error("Invalid RFQ outcome: a fill must be an object");
     }
+    const monacoFee = readOptionalDecimalString(raw, "monacoFee");
+    const builderFee = readOptionalDecimalString(raw, "builderFee");
     return {
         executionId: readString(raw, "executionId"),
         price: readString(raw, "price"),
         quantity: readString(raw, "quantity"),
         fee: readString(raw, "fee"),
+        ...(monacoFee !== undefined && { monacoFee }),
+        ...(builderFee !== undefined && { builderFee }),
     };
 }
 /** Parse the taker's outcome. Nothing filled leaves `vwap` absent and `fills` empty. */
@@ -777,8 +807,18 @@ function parseOrderbookEvent(rawData) {
         quoteDecimals: data.quote_decimals || 0,
         timestamp: data.timestamp || new Date().toISOString(),
         sequence: data.sequence_number || 0,
+        // Sent only when the server renders `orderbook` from market-data's book
+        // (0XM-3552), as JSON numbers; surfaced as decimal strings like REST's
+        // `bookSeq` (a u64 may pass `Number.MAX_SAFE_INTEGER`).
+        ...sequenceField("bookSeq", data, "book_seq"),
+        ...sequenceField("prevBookSeq", data, "prev_book_seq"),
     };
 }
+/** `{ [name]: sequence }` when `data[key]` is an exact u64 sequence, `{}` otherwise, so an absent or malformed key never surfaces. */
+function sequenceField(name, data, key) {
+    const sequence = tryReadSequence(data, key);
+    return sequence === undefined ? {} : { [name]: sequence };
+}
 /**
  * Parse the one row of an `orderbook` snapshot: the channel's current book in
  * the live frame's shape, read the same way.
@@ -786,7 +826,9 @@ function parseOrderbookEvent(rawData) {
  * The live parser casts; here a row that is not an object, or carries no `data`
  * object, throws, so {@link snapshotFrameHandler} withholds the frame rather
  * than handing over an empty book. The engine's book read carries no sequence,
- * so the row's `sequence` is 0.
+ * so under the engine source the row's `sequence` is 0; when the server renders
+ * the channel from market-data's book (0XM-3552) the row carries `book_seq` as
+ * `sequence_number` and surfaces `bookSeq` / `prevBookSeq` like a live frame.
  */
 function parseOrderbookSnapshotRow(raw) {
     if (!isRecord(raw) || !isRecord(raw.data)) {
@@ -1146,35 +1188,23 @@ function parseOrderSnapshotItem(raw) {
         ...(placementMakerFeeBps === undefined ? {} : { placementMakerFeeBps }),
     };
 }
-/**
- * Wrap a caller's `onSnapshot` in the internal snapshot-frame handler.
- *
- * The frame's `data` is the channel's COMPLETE current state as a flat array,
- * and that completeness is the whole contract: a consumer is expected to
- * replace state from it, so absence from the array means the entity is gone.
- *
- * Delivery is therefore all-or-nothing. If the payload is not an array, or any
- * single row fails to parse, NOTHING is delivered.
- *
- * Skipping just the unreadable row and delivering the rest would be worse than
- * delivering nothing, because the array would still be presented as complete: a
- * consumer would drop the entity that row described — zero its balance, remove
- * its market, cancel its order in the UI — on the strength of an omission the
- * SDK itself created. Nor is that self-correcting. A resting order or an
- * unchanged market has no later diff to repair it, so the deletion would stand
- * for the life of the connection.
- *
- * Withholding the frame instead leaves the consumer on whatever baseline it
- * already had, and the channel keeps streaming live events over it. That is a
- * strictly smaller loss, and it is the same all-or-nothing rule this channel's
- * original `instrument` snapshot already applied.
- *
- * `[]` is a legitimate baseline, not a failure, and is always delivered:
- * "nothing is open" is exactly the information a consumer needs to clear stale
- * state after a reconnect.
- */
+/** A `trades:<pair>` snapshot cursor; `null` is a meaningful value (no trade applied since seeding). */
+function parseTradeSnapshotCursor(raw) {
+    if (raw === null)
+        return null;
+    if (!isRecord(raw))
+        throw new Error("Invalid trades snapshot cursor: must be an object or null");
+    const seq = raw.seq;
+    const matchIndex = raw.match_index;
+    if (!Number.isSafeInteger(seq) || seq < 0 || !Number.isSafeInteger(matchIndex) || matchIndex < 0) {
+        throw new Error("Invalid trades snapshot cursor: seq and match_index must be non-negative integers");
+    }
+    return { seq: seq, matchIndex: matchIndex };
+}
 function snapshotFrameHandler(channel, parseItem, onSnapshot) {
-    return (rawData) => {
+    // `frame` is the router's second argument, unused here; `meta` is passed
+    // only by a channel that reads something beside the rows (trades' cursor).
+    return (rawData, _frame, meta) => {
         try {
             if (!Array.isArray(rawData)) {
                 throw new Error(`Invalid ${channel} snapshot: data must be an array`);
@@ -1182,13 +1212,86 @@ function snapshotFrameHandler(channel, parseItem, onSnapshot) {
             // Parsed fully before anything is handed over, so a failure part-way
             // through cannot deliver a truncated baseline.
             const items = rawData.map(parseItem);
-            onSnapshot(items);
+            // Only a snapshot that carries meta passes it, so every other channel
+            // sees exactly the call it always did.
+            if (meta)
+                onSnapshot(items, meta);
+            else
+                onSnapshot(items);
         }
         catch (err) {
             console.error(`WebSocket: Error processing ${channel} snapshot`, err);
         }
     };
 }
+function tradeKeyAtOrBelow(key, bound) {
+    return key.seq < bound.seq || (key.seq === bound.seq && key.matchIndex <= bound.matchIndex);
+}
+/** An optional chain field: a non-negative integer, else absent (a malformed value never drops the trade). */
+function readOptionalChainNumber(data, key) {
+    const value = data[key];
+    return Number.isSafeInteger(value) && value >= 0 ? value : undefined;
+}
+/** The trade frame's chain fields (market-data source only), set only when present and well formed. */
+function readTradeChain(data) {
+    const chain = {};
+    const seq = readOptionalChainNumber(data, "seq");
+    const matchIndex = readOptionalChainNumber(data, "match_index");
+    const prevSeq = readOptionalChainNumber(data, "prev_seq");
+    if (seq !== undefined)
+        chain.seq = seq;
+    if (matchIndex !== undefined)
+        chain.matchIndex = matchIndex;
+    if (prevSeq !== undefined)
+        chain.prevSeq = prevSeq;
+    if (data.prev_match_index === null)
+        chain.prevMatchIndex = null;
+    else {
+        const prevMatchIndex = readOptionalChainNumber(data, "prev_match_index");
+        if (prevMatchIndex !== undefined)
+            chain.prevMatchIndex = prevMatchIndex;
+    }
+    return chain;
+}
+/** Backoff for repeated client-side rebuilds (a gap, an unreadable frame or snapshot, a thinned side). */
+const SNAPSHOT_RETRY_BASE_MS = 500;
+const SNAPSHOT_RETRY_MAX_MS = 15_000;
+/**
+ * After SNAPSHOT_UNAVAILABLE the subscription stays routed: the server retries
+ * a failed book (5 s doubling to 60 s) or a capped one once a slot frees, and
+ * pushes the healing snapshot with no client action. A resubscribe lands on
+ * the same per-pod book, so it is never required; this timer is only a
+ * harmless safety net. The cases that never heal (an unknown pair id, a
+ * durable-log reset until ws-api restarts) are not fixed by it either.
+ */
+const SNAPSHOT_FALLBACK_BASE_MS = 90_000;
+const SNAPSHOT_FALLBACK_MAX_MS = 300_000;
+/**
+ * Whether a raw frame belongs to a channel carrying market-data sequences:
+ * depth, bbo, or orderbook rendered from market-data's book (0XM-3552). A
+ * cheap prefix test before the sequence quoting pass.
+ */
+const MARKET_DATA_CHANNEL_KEY = /"channel"\s*:\s*"(?:depth|bbo|orderbook):/;
+function isMarketDataFrame(raw) {
+    // The substring test first: almost every frame fails it without a regex.
+    return raw.includes("book_seq") && MARKET_DATA_CHANNEL_KEY.test(raw);
+}
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/**
+ * The canonical market-data channel: lowercase pair UUID, uppercase mode. The
+ * server sends live frames on this form and echoes the subscribed form on
+ * the snapshot, so subscribing canonically keeps both on one key.
+ */
+function marketDataChannel(kind, tradingPairId, tradingMode) {
+    if (!tradingPairId || !UUID_PATTERN.test(tradingPairId)) {
+        throw new Error(`${kind} subscription requires a trading pair UUID, got "${tradingPairId}"`);
+    }
+    const mode = String(tradingMode ?? "").toUpperCase();
+    if (mode !== "SPOT" && mode !== "MARGIN") {
+        throw new Error(`${kind} subscription requires tradingMode "SPOT" or "MARGIN", got "${tradingMode}"`);
+    }
+    return `${kind}:${tradingPairId.toLowerCase()}:${mode}`;
+}
 /**
  * Create a Monaco WebSocket client
  *
@@ -1231,6 +1334,22 @@ export function createMonacoWebSocket(baseUrl, options = {}, serverClock = new S
     // Close code of the connection loss the next successful reopen recovers
     // from; null when no resync is owed (first connect, clean disconnect).
     let pendingResyncCode = null;
+    // Scoped resync (0XM-3553): offer the capability once per socket, on its
+    // first Authenticate or Subscribe; the server keeps it for the connection.
+    // Only to a client with an onResync: without one a scoped resync would
+    // leave the app silently stale, where the 1013 close at least resubscribes
+    // and re-delivers subscribe snapshots.
+    const offerResync = (options.scopedResync ?? true) && options.onResync !== undefined;
+    let resyncOffered = false;
+    let resyncedBursts = [];
+    // A scoped refetch was still owed when a socket was lost: the next
+    // connection's onResync reports it (as a 1013 gap if the close itself owed
+    // none).
+    let scopedResyncOwed = false;
+    // Snapshot handlers that keep only internal state and hand the app
+    // nothing (the trades chain cursor without an app `onSnapshot`): a re-sent
+    // snapshot through one alone still reaches no app code.
+    const internalSnapshotHandlers = new WeakSet();
     // Authentication-ending Error frame received on the current socket, tagged
     // with the session it rejected. The server answers handshakes in the order
     // they were sent, so each Authenticated / AUTH_FAILED reply belongs to the
@@ -1252,6 +1371,14 @@ export function createMonacoWebSocket(baseUrl, options = {}, serverClock = new S
     // reusing the Event handlers would feed every other channel's parser a frame
     // it must reject.
     const snapshotHandlers = new Map();
+    // Per-channel listeners for Error frames that name a channel (the local
+    // depth/bbo books retry a SNAPSHOT_UNAVAILABLE subscribe). They run before
+    // the app's onError and never stop it.
+    const channelErrorHandlers = new Map();
+    // One shared local book per depth/bbo channel: the server sends a snapshot
+    // only for a new wire subscription, so a second local subscriber must share
+    // the first one's state rather than wait for a snapshot that never comes.
+    const localStateChannels = new Map();
     // Latest known full-config frame per market for each subscribed instrument
     // channel, seeded by the subscribe-time Snapshot and superseded by every
     // live frame (instrument frames are terminal-state, never deltas). The
@@ -1357,6 +1484,7 @@ export function createMonacoWebSocket(baseUrl, options = {}, serverClock = new S
             public_key: session.publicKey,
             timestamp,
             signature,
+            ...capabilitiesOnce(),
         }));
     };
     const stopHeartbeat = () => {
@@ -1444,7 +1572,67 @@ export function createMonacoWebSocket(baseUrl, options = {}, serverClock = new S
         if (channels.length === 0 || ws?.readyState !== WebSocket.OPEN)
             return;
         pendingRequests.push({ kind: "subscribe", channels });
-        send({ type: "Subscribe", channels });
+        send({ type: "Subscribe", channels, ...capabilitiesOnce() });
+    };
+    /** The capability offer, on the first request of each socket only. */
+    const capabilitiesOnce = () => {
+        if (!offerResync || resyncOffered)
+            return {};
+        resyncOffered = true;
+        return { capabilities: ["resync"] };
+    };
+    /** Report `channel` in a scoped onResync, at least `delayMs` from now. */
+    const scheduleResynced = (channel, delayMs) => {
+        const now = performance.now();
+        let burst = resyncedBursts.at(-1);
+        if (!burst || now - burst.opened > RESYNCED_BURST_MS) {
+            // Held open for the whole window, so frames still arriving join it.
+            burst = { opened: now, due: now + RESYNCED_BURST_MS, channels: new Set(), timer: null };
+            resyncedBursts.push(burst);
+        }
+        burst.channels.add(channel);
+        burst.due = Math.max(burst.due, now + delayMs);
+        armResynced(burst);
+    };
+    /** (Re)arm `burst`'s timer for its deadline, rounding up. */
+    const armResynced = (burst) => {
+        if (burst.timer)
+            clearTimeout(burst.timer);
+        burst.timer = setTimeout(() => flushResynced(burst), Math.max(0, Math.ceil(burst.due - performance.now())));
+    };
+    const flushResynced = (burst) => {
+        // A timer can fire before the monotonic deadline: wait out the rest.
+        if (performance.now() < burst.due) {
+            armResynced(burst);
+            return;
+        }
+        resyncedBursts = resyncedBursts.filter((other) => other !== burst);
+        const channels = [...burst.channels].filter((channel) => handlers.has(channel));
+        if (channels.length === 0)
+            return;
+        // Called from a timer: a throw or a rejection must not escape it.
+        const logResyncError = (err) => console.error("WebSocket: onResync threw", err);
+        try {
+            const result = options.onResync?.({ code: 1013, slowClient: true, reason: "resynced", channels });
+            if (result instanceof Promise)
+                result.catch(logResyncError);
+        }
+        catch (err) {
+            logResyncError(err);
+        }
+    };
+    /**
+     * Drop every pending scoped resync; whether one was owed. A reconnect's
+     * onResync covers it.
+     */
+    const cancelResynced = () => {
+        // Owed only for a channel the app still holds.
+        const owed = resyncedBursts.some((burst) => [...burst.channels].some((channel) => handlers.has(channel)));
+        for (const burst of resyncedBursts)
+            if (burst.timer)
+                clearTimeout(burst.timer);
+        resyncedBursts = [];
+        return owed;
     };
     const sendUnsubscribe = (channels) => {
         if (channels.length === 0 || ws?.readyState !== WebSocket.OPEN)
@@ -1595,6 +1783,8 @@ export function createMonacoWebSocket(baseUrl, options = {}, serverClock = new S
                 // oldest outstanding request: retire it, or every later ack would
                 // pair with the wrong request.
                 if (msg.code === "INVALID_MESSAGE" && OVERSIZED_REQUEST.test(msg.message)) {
+                    // Refused unread: any capability it carried was never recorded.
+                    resyncOffered = false;
                     pendingRequests.shift();
                 }
                 if (msg.code === "AUTH_FAILED") {
@@ -1613,6 +1803,16 @@ export function createMonacoWebSocket(baseUrl, options = {}, serverClock = new S
                 // actionable without it. (The frame is untyped JSON, so the declared
                 // `string` type of `channel` is not trusted here.)
                 const channel = msg.channel;
+                if (typeof channel === "string") {
+                    for (const handler of channelErrorHandlers.get(channel) ?? []) {
+                        try {
+                            handler(msg.code, msg.message);
+                        }
+                        catch (err) {
+                            console.error("WebSocket: Error in channel error handler", err);
+                        }
+                    }
+                }
                 options.onError?.(typeof channel === "string" ? { code: msg.code, message: msg.message, channel } : { code: msg.code, message: msg.message });
             }
             return;
@@ -1658,13 +1858,36 @@ export function createMonacoWebSocket(baseUrl, options = {}, serverClock = new S
             }
             return;
         }
+        if (msg.type === "Resynced") {
+            // A channel the server could not repair in place (0XM-3553). A frame
+            // missing either field is malformed and ignored.
+            const retryAfterMs = msg.retry_after_ms;
+            if (typeof msg.channel === "string" && typeof retryAfterMs === "number" && Number.isFinite(retryAfterMs) && retryAfterMs >= 0) {
+                scheduleResynced(msg.channel, retryAfterMs);
+            }
+            return;
+        }
         if (!msg.channel)
             return;
         if (msg.type === "Snapshot") {
             // Exact match only: the Snapshot frame's channel echoes the raw
             // subscribed channel, never a more specific one.
-            for (const handler of snapshotHandlers.get(msg.channel) ?? []) {
-                handler(msg.data);
+            const channelSnapshotHandlers = snapshotHandlers.get(msg.channel);
+            for (const handler of channelSnapshotHandlers ?? []) {
+                handler(msg.data, msg);
+            }
+            // A server-side repair after an upstream loss (0XM-3553) is marked; a
+            // channel consumed without an app snapshot handler would never see it.
+            if (offerResync && msg.resynced === true && handlers.has(msg.channel)) {
+                // Every subscriber needs an app snapshot handler for the repair to
+                // reach it; an event-only one is told to refetch instead.
+                let appSnapshotHandlers = 0;
+                for (const handler of channelSnapshotHandlers ?? []) {
+                    if (!internalSnapshotHandlers.has(handler))
+                        appSnapshotHandlers++;
+                }
+                if (appSnapshotHandlers < (handlers.get(msg.channel)?.size ?? 0))
+                    scheduleResynced(msg.channel, 0);
             }
             return;
         }
@@ -1687,6 +1910,12 @@ export function createMonacoWebSocket(baseUrl, options = {}, serverClock = new S
     const handleSocketLoss = (code) => {
         ws = null;
         stopHeartbeat();
+        // A scoped refetch still owed is owed by whichever connection comes next,
+        // even one opened later by connect() rather than by the reconnect loop.
+        if (cancelResynced())
+            scopedResyncOwed = true;
+        for (const entry of [...localStateChannels.values()])
+            entry.onSocketLoss();
         // The server dropped every subscription with the connection.
         resetSubscriptionAcks();
         // Terminal authentication loss: the server revoked the session
@@ -1766,6 +1995,7 @@ export function createMonacoWebSocket(baseUrl, options = {}, serverClock = new S
             try {
                 const socket = new WebSocket(getUrl());
                 ws = socket;
+                resyncOffered = false;
                 lastAuthError = null;
                 pendingAuthSessions = [];
                 confirmedSession = undefined;
@@ -1807,9 +2037,10 @@ export function createMonacoWebSocket(baseUrl, options = {}, serverClock = new S
                     //
                     // This callback waits for neither acknowledgements nor snapshots,
                     // and the SDK performs no REST recovery itself.
-                    if (pendingResyncCode !== null) {
-                        const code = pendingResyncCode;
+                    if (pendingResyncCode !== null || scopedResyncOwed) {
+                        const code = pendingResyncCode ?? 1013;
                         pendingResyncCode = null;
+                        scopedResyncOwed = false;
                         options.onResync?.({ code, slowClient: code === 1013 });
                     }
                     resolve();
@@ -1819,7 +2050,10 @@ export function createMonacoWebSocket(baseUrl, options = {}, serverClock = new S
                         return;
                     lastMessageAt = Date.now();
                     try {
-                        const msg = JSON.parse(event.data);
+                        // Market-data sequences are u64: quote them before parsing so
+                        // one above Number.MAX_SAFE_INTEGER stays exact.
+                        const raw = event.data;
+                        const msg = JSON.parse(typeof raw === "string" && isMarketDataFrame(raw) ? quoteSequenceNumbers(raw) : raw);
                         // Handle pong silently
                         if (msg.type === "Pong")
                             return;
@@ -1869,6 +2103,14 @@ export function createMonacoWebSocket(baseUrl, options = {}, serverClock = new S
         stopReconnect();
         stopHeartbeat();
         pendingResyncCode = null;
+        cancelResynced();
+        scopedResyncOwed = false;
+        // Local depth/bbo books go with their wire handlers: stop each (its retry
+        // timer too) so a later depth()/bbo() call starts a fresh subscription.
+        for (const entry of [...localStateChannels.values()])
+            entry.stop();
+        localStateChannels.clear();
+        channelErrorHandlers.clear();
         handlers.clear();
         snapshotHandlers.clear();
         instrumentBaseline.clear();
@@ -1953,6 +2195,266 @@ export function createMonacoWebSocket(baseUrl, options = {}, serverClock = new S
             }
         }, onSnapshot && snapshotFrameHandler("orderbook", parseOrderbookSnapshotRow, onSnapshot));
     };
+    /**
+     * Keep one shared, sequenced local state for a depth/bbo channel: the
+     * subscribe-time snapshot is the base, linked frames update it, and a gap,
+     * an unreadable frame or snapshot, an exhausted incomplete side or a
+     * SNAPSHOT_UNAVAILABLE rebuilds it from a fresh wire subscription.
+     */
+    const openLocalState = (channel, createState, onValue, localOptions) => {
+        let entry = localStateChannels.get(channel);
+        if (!entry) {
+            const state = createState();
+            const listeners = new Set();
+            let unsubscribeWire = null;
+            let stopped = false;
+            // One pending resubscribe at a time (a rebuild, or the fallback after a
+            // SNAPSHOT_UNAVAILABLE); scheduling another supersedes it, and a stale
+            // timer or microtask finds its token outdated and does nothing.
+            let scheduleToken = 0;
+            let scheduledTimer = null;
+            // Set while a rebuild is pending: frames still being routed for the old
+            // subscription (the router may visit the re-added channel in the same
+            // pass) are ignored rather than buffered against the next snapshot.
+            let rebuildPending = false;
+            // Rebuilds since the last frame that applied cleanly on a fresh
+            // snapshot: a fault that recurs on every snapshot backs off instead of
+            // resubscribing per frame.
+            let consecutiveRebuilds = 0;
+            let fallbackDelay = SNAPSHOT_FALLBACK_BASE_MS;
+            // The channel's last rejection, replayed to a listener that joins later
+            // (no new Subscribe goes out for it); a snapshot clears it.
+            let lastRejection = null;
+            const forEachListener = (what, call) => {
+                for (const listener of [...listeners]) {
+                    try {
+                        call(listener);
+                    }
+                    catch (err) {
+                        console.error(`WebSocket: Error in ${channel} ${what}`, err);
+                    }
+                }
+            };
+            // The view is built once; each listener gets its own copy of it, so one
+            // that mutates the book cannot change what the others see.
+            const emit = () => {
+                const value = state.view();
+                if (value === null)
+                    return;
+                forEachListener("listener", (listener) => listener.onValue(state.copy(value)));
+            };
+            const notifyResync = (reason) => forEachListener("onResync", (listener) => listener.options?.onResync?.(reason));
+            const open = () => subscribe(channel, onFrame, onSnapshot);
+            const cancelScheduled = () => {
+                scheduleToken += 1;
+                if (scheduledTimer)
+                    clearTimeout(scheduledTimer);
+                scheduledTimer = null;
+                rebuildPending = false;
+            };
+            const schedule = (delay, run) => {
+                cancelScheduled();
+                const token = scheduleToken;
+                const fire = () => {
+                    if (token !== scheduleToken || stopped)
+                        return;
+                    scheduledTimer = null;
+                    rebuildPending = false;
+                    run();
+                };
+                if (delay === 0)
+                    queueMicrotask(fire);
+                else
+                    scheduledTimer = setTimeout(fire, delay);
+            };
+            const resubscribe = () => {
+                unsubscribeWire?.();
+                unsubscribeWire = open();
+            };
+            /** Discard the state now; resubscribe once the current routing pass is done, backing off on repeats. */
+            const rebuild = (reason) => {
+                state.reset();
+                notifyResync(reason);
+                if (rebuildPending)
+                    return;
+                const delay = consecutiveRebuilds === 0 ? 0 : Math.min(SNAPSHOT_RETRY_BASE_MS * 2 ** (consecutiveRebuilds - 1), SNAPSHOT_RETRY_MAX_MS);
+                consecutiveRebuilds += 1;
+                schedule(delay, resubscribe);
+                rebuildPending = true;
+                if (delay > 0) {
+                    // Waiting out the backoff unsubscribed, so no frame or snapshot
+                    // arrives for the abandoned subscription meanwhile.
+                    unsubscribeWire?.();
+                    unsubscribeWire = null;
+                }
+            };
+            /**
+             * The server could not serve a snapshot. The subscription stays routed
+             * and ws-api pushes the healing snapshot with no client action, so stay
+             * subscribed (frames are withheld until then). The resubscribe after the
+             * long fallback is a safety net only: it lands on the same book.
+             */
+            const awaitServerSnapshot = (reason) => {
+                state.reset();
+                notifyResync(reason);
+                schedule(fallbackDelay, resubscribe);
+                fallbackDelay = Math.min(fallbackDelay * 2, SNAPSHOT_FALLBACK_MAX_MS);
+                if (unsubscribeWire === null)
+                    unsubscribeWire = open();
+            };
+            function onFrame(raw) {
+                if (rebuildPending || stopped)
+                    return;
+                let outcome;
+                try {
+                    outcome = state.offerRaw(raw);
+                }
+                catch (err) {
+                    // An unreadable frame is a lost frame.
+                    console.error(`WebSocket: Error processing ${channel} frame`, err);
+                    rebuild("gap");
+                    return;
+                }
+                if (outcome === "applied") {
+                    consecutiveRebuilds = 0;
+                    emit();
+                }
+                else if (outcome === "gap")
+                    rebuild("gap");
+                else if (outcome === "truncated")
+                    rebuild("truncated");
+            }
+            function onSnapshot(raw) {
+                if (stopped)
+                    return;
+                let outcome;
+                try {
+                    outcome = state.applySnapshotRaw(raw);
+                }
+                catch (err) {
+                    // No further snapshot would come on this subscription unless the
+                    // server reloads the book: rebuild it (backing off on repeats).
+                    console.error(`WebSocket: Error processing ${channel} snapshot`, err);
+                    rebuild("snapshot_unavailable");
+                    return;
+                }
+                // A snapshot supersedes any pending fallback or rebuild, and any
+                // earlier rejection.
+                cancelScheduled();
+                lastRejection = null;
+                fallbackDelay = SNAPSHOT_FALLBACK_BASE_MS;
+                if (outcome === "gap" || outcome === "truncated") {
+                    rebuild(outcome);
+                    return;
+                }
+                emit();
+            }
+            const onChannelError = (code, message) => {
+                if (stopped)
+                    return;
+                if (code === "SNAPSHOT_UNAVAILABLE") {
+                    awaitServerSnapshot("snapshot_unavailable");
+                    return;
+                }
+                lastRejection = { code, message };
+                forEachListener("onError", (listener) => listener.options?.onError?.({ code, message }));
+            };
+            const onSocketLoss = () => {
+                if (stopped)
+                    return;
+                // The reconnect resubscribes and its snapshot rebuilds the book;
+                // until then the old one is not live. Frames buffered from the dead
+                // connection go too.
+                const wasLive = state.ready;
+                state.reset();
+                if (wasLive)
+                    notifyResync("disconnected");
+            };
+            if (!channelErrorHandlers.has(channel))
+                channelErrorHandlers.set(channel, new Set());
+            channelErrorHandlers.get(channel)?.add(onChannelError);
+            unsubscribeWire = open();
+            const created = {
+                listeners,
+                current: () => {
+                    const value = state.view();
+                    return value === null ? null : state.copy(value);
+                },
+                rejection: () => lastRejection,
+                onSocketLoss,
+                stop: () => {
+                    if (stopped)
+                        return;
+                    stopped = true;
+                    cancelScheduled();
+                    unsubscribeWire?.();
+                    unsubscribeWire = null;
+                    channelErrorHandlers.get(channel)?.delete(onChannelError);
+                    if (channelErrorHandlers.get(channel)?.size === 0)
+                        channelErrorHandlers.delete(channel);
+                    if (localStateChannels.get(channel) === created)
+                        localStateChannels.delete(channel);
+                },
+            };
+            localStateChannels.set(channel, created);
+            entry = created;
+        }
+        const listener = { onValue: onValue, options: localOptions };
+        const held = entry;
+        held.listeners.add(listener);
+        const current = held.current();
+        const rejection = held.rejection();
+        try {
+            if (current !== null)
+                listener.onValue(current);
+            else if (rejection !== null)
+                listener.options?.onError?.(rejection);
+        }
+        catch (err) {
+            console.error(`WebSocket: Error in ${channel} listener`, err);
+        }
+        let unsubscribed = false;
+        return () => {
+            if (unsubscribed)
+                return;
+            unsubscribed = true;
+            held.listeners.delete(listener);
+            if (held.listeners.size === 0)
+                held.stop();
+        };
+    };
+    const subscribeDepth = (tradingPairId, tradingMode, onBook, localOptions) => {
+        const channel = marketDataChannel("depth", tradingPairId, tradingMode);
+        return openLocalState(channel, () => {
+            const book = new LocalDepthBook();
+            return {
+                offerRaw: (raw) => book.offer(parseDepthDelta(raw)),
+                applySnapshotRaw: (raw) => book.applySnapshot(parseDepthSnapshot(raw)),
+                reset: () => book.reset(),
+                view: () => book.view(),
+                copy: (value) => ({ ...value, bids: value.bids.map((level) => ({ ...level })), asks: value.asks.map((level) => ({ ...level })) }),
+                get ready() {
+                    return book.ready;
+                },
+            };
+        }, onBook, localOptions);
+    };
+    const subscribeBbo = (tradingPairId, tradingMode, onBbo, localOptions) => {
+        const channel = marketDataChannel("bbo", tradingPairId, tradingMode);
+        return openLocalState(channel, () => {
+            const bbo = new LocalBbo();
+            return {
+                offerRaw: (raw) => bbo.offer(parseBboEvent(raw)),
+                applySnapshotRaw: (raw) => bbo.applySnapshot(parseBboSnapshot(raw)),
+                reset: () => bbo.reset(),
+                view: () => bbo.view(),
+                copy: (value) => ({ ...value }),
+                get ready() {
+                    return bbo.ready;
+                },
+            };
+        }, onBbo, localOptions);
+    };
     const subscribeOHLCV = (tradingPairId, tradingMode, interval, handler, priceType, onSnapshot) => {
         // Four-token channel selects the trade-derived candles (back-compat); the
         // optional fifth token selects the price series (`mark` = close-only mark
@@ -2003,8 +2505,43 @@ export function createMonacoWebSocket(baseUrl, options = {}, serverClock = new S
             }
         }, onSnapshot && snapshotFrameHandler("ohlcv", (raw) => parseOHLCVSnapshotCandle(raw, interval), onSnapshot));
     };
-    const subscribeTrades = (tradingPairId, handler, onSnapshot) => {
+    const subscribeTrades = (tradingPairId, handler, onSnapshot, tradesOptions) => {
         const channel = `trades:${tradingPairId}`;
+        // The chain check runs once a snapshot carries a cursor key (the
+        // market-data source); under the engine source every trade is delivered
+        // as before. The server forwards only trades linking to this
+        // connection's cursor and reseeds by itself on a break it sees, so the
+        // check here is a safety net: it drops a trade at or below the cursor or
+        // the last delivered one, and reports a trade that does not link (a
+        // frame this client could not read, say) to onGap, then continues from
+        // it. Withholding would freeze the feed, since the server believes the
+        // connection is in sync and sends no fresh snapshot for it.
+        let checking = false;
+        let last = null;
+        const deliverSnapshot = onSnapshot && snapshotFrameHandler("trades", parseTradeEventData, onSnapshot);
+        const onSnapshotFrame = (rawData, frame) => {
+            let meta;
+            if (frame && "cursor" in frame) {
+                try {
+                    const cursor = parseTradeSnapshotCursor(frame.cursor);
+                    // The internal bound is a copy: a consumer mutating meta.cursor
+                    // must not move it.
+                    last = cursor === null ? null : { ...cursor };
+                    checking = true;
+                    meta = { cursor };
+                }
+                catch (err) {
+                    // An unreadable cursor leaves nothing to check against: deliver as
+                    // the engine source does until the next snapshot (the rows still go).
+                    console.error("WebSocket: Error processing trades snapshot cursor", err);
+                    checking = false;
+                    last = null;
+                }
+            }
+            deliverSnapshot?.(rawData, frame, meta);
+        };
+        if (!deliverSnapshot)
+            internalSnapshotHandlers.add(onSnapshotFrame);
         return subscribe(channel, (rawData) => {
             try {
                 const data = rawData;
@@ -2020,13 +2557,37 @@ export function createMonacoWebSocket(baseUrl, options = {}, serverClock = new S
                         makerSide: tradeData.maker_side.toUpperCase(),
                         executedAt: tradeData.executed_at,
                     },
+                    ...readTradeChain(data),
                 };
+                if (checking && event.seq !== undefined && event.matchIndex !== undefined) {
+                    const key = { seq: event.seq, matchIndex: event.matchIndex };
+                    if (last !== null) {
+                        // At or below the cursor or the last delivered trade: already reflected.
+                        if (tradeKeyAtOrBelow(key, last))
+                            return;
+                        if (event.prevSeq !== last.seq || event.prevMatchIndex !== last.matchIndex) {
+                            // A throwing onGap must not stop the chain advancing or the
+                            // trade being delivered.
+                            try {
+                                tradesOptions?.onGap?.({
+                                    tradingPairId: event.tradingPairId,
+                                    expected: { seq: last.seq, matchIndex: last.matchIndex },
+                                    received: { prevSeq: event.prevSeq ?? null, prevMatchIndex: event.prevMatchIndex ?? null },
+                                });
+                            }
+                            catch (err) {
+                                console.error("WebSocket: Error in trades onGap", err);
+                            }
+                        }
+                    }
+                    last = key;
+                }
                 handler(event);
             }
             catch (err) {
                 console.error("WebSocket: Error processing trade event", err);
             }
-        }, onSnapshot && snapshotFrameHandler("trades", parseTradeEventData, onSnapshot));
+        }, onSnapshotFrame);
     };
     const subscribeMovements = (handler) => {
         // User is identified from the authenticated session, so channel is just "movements"
@@ -2522,6 +3083,8 @@ export function createMonacoWebSocket(baseUrl, options = {}, serverClock = new S
         },
         orders: subscribeOrders,
         orderbook: subscribeOrderbook,
+        depth: subscribeDepth,
+        bbo: subscribeBbo,
         ohlcv: subscribeOHLCV,
         trades: subscribeTrades,
         movements: subscribeMovements,