@pod-network/trade-sdk 0.2.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (43) hide show
  1. package/dist/client.d.ts.map +1 -1
  2. package/dist/client.js +1 -12
  3. package/dist/client.js.map +1 -1
  4. package/dist/codec/decode.d.ts.map +1 -1
  5. package/dist/codec/decode.js +7 -6
  6. package/dist/codec/decode.js.map +1 -1
  7. package/dist/codec/direction.d.ts +10 -0
  8. package/dist/codec/direction.d.ts.map +1 -0
  9. package/dist/codec/direction.js +46 -0
  10. package/dist/codec/direction.js.map +1 -0
  11. package/dist/codec/orders-v2.d.ts +19 -0
  12. package/dist/codec/orders-v2.d.ts.map +1 -0
  13. package/dist/codec/orders-v2.js +200 -0
  14. package/dist/codec/orders-v2.js.map +1 -0
  15. package/dist/codec/units.d.ts +10 -0
  16. package/dist/codec/units.d.ts.map +1 -1
  17. package/dist/codec/units.js +16 -0
  18. package/dist/codec/units.js.map +1 -1
  19. package/dist/sync/orders.d.ts +71 -16
  20. package/dist/sync/orders.d.ts.map +1 -1
  21. package/dist/sync/orders.js +202 -83
  22. package/dist/sync/orders.js.map +1 -1
  23. package/dist/transport/ws.d.ts +19 -2
  24. package/dist/transport/ws.d.ts.map +1 -1
  25. package/dist/transport/ws.js +14 -2
  26. package/dist/transport/ws.js.map +1 -1
  27. package/dist/types/public.d.ts +125 -9
  28. package/dist/types/public.d.ts.map +1 -1
  29. package/dist/types/wire.d.ts +104 -40
  30. package/dist/types/wire.d.ts.map +1 -1
  31. package/dist/write/index.d.ts +1 -1
  32. package/dist/write/index.js +1 -1
  33. package/package.json +1 -1
  34. package/src/client.ts +1 -14
  35. package/src/codec/decode.ts +7 -6
  36. package/src/codec/direction.ts +36 -0
  37. package/src/codec/orders-v2.ts +222 -0
  38. package/src/codec/units.ts +16 -0
  39. package/src/sync/orders.ts +203 -83
  40. package/src/transport/ws.ts +26 -3
  41. package/src/types/public.ts +139 -7
  42. package/src/types/wire.ts +114 -28
  43. package/src/write/index.ts +1 -1
@@ -0,0 +1,36 @@
1
+ // What a perp fill did to the owner's position: opened, added to, reduced, closed
2
+ // or flipped it.
3
+ //
4
+ // A port of `classify_perp_order_direction` in `node/src/rpc/types.rs`, branch for
5
+ // branch and in the same order. It exists because the two sources of an order's
6
+ // direction have to agree: REST sends the server's label on `OrderResponse`, while
7
+ // `pod_orders_v2` sends the raw position and leaves the classification to the
8
+ // client. A divergence here would show one label on a streamed row and another after
9
+ // a refetch — so this file is a transcription, not an interpretation, and the test
10
+ // pins every branch.
11
+
12
+ import type { OrderDirection } from "../types/public.js";
13
+
14
+ /**
15
+ * Classify a position transition.
16
+ *
17
+ * `before` is not on the wire: it is `after - sign(size) * filledThisFill`, which is
18
+ * the same arithmetic the engine used to produce the pair (`buy_bookends` /
19
+ * `sell_bookends` in `trading/src/book.rs`), so deriving it loses nothing.
20
+ */
21
+ export function classifyPerpDirection(before: bigint, after: bigint): OrderDirection {
22
+ if (before === 0n && after === 0n) return "reduce_long";
23
+ if (before === after) return before > 0n ? "reduce_long" : "reduce_short";
24
+ if (before === 0n && after > 0n) return "open_long";
25
+ if (before === 0n && after < 0n) return "open_short";
26
+ if (before > 0n && after === 0n) return "close_long";
27
+ if (before < 0n && after === 0n) return "close_short";
28
+ if (before > 0n && after < 0n) return "long_to_short";
29
+ if (before < 0n && after > 0n) return "short_to_long";
30
+ if (before > 0n && after > before) return "add_long";
31
+ if (before > 0n && after < before) return "reduce_long";
32
+ if (before < 0n && after < before) return "add_short";
33
+ if (before < 0n && after > before) return "reduce_short";
34
+ // Unreachable, and the Rust returns the same rather than erroring.
35
+ return "open_long";
36
+ }
@@ -0,0 +1,222 @@
1
+ // `pod_orders_v2` frames -> the public `Order` map (ADR 0029).
2
+ //
3
+ // A frame is entity/event shaped: identity and terms cross the wire once, in
4
+ // `orders`, and everything after that is a reference. So decoding is two passes —
5
+ // materialize this batch's entities, then let the events say what happened to
6
+ // them and to orders already held. Status lives only in the events, which is what
7
+ // lets the server add transition kinds without changing the entity.
8
+
9
+ import type {
10
+ Address, AmendRejection, Order, OrderEvent, OrderEventFill, OrderEventKind, OrderStatus,
11
+ PartialFill, RejectCode, TerminalStatus,
12
+ } from "../types/public.js";
13
+ import type { WireOrderEntity, WireOrderEvent, WireOrdersFrame } from "../types/wire.js";
14
+ import { dec, endMsFromUs, usToMs } from "./units.js";
15
+ import { div } from "./fixed.js";
16
+ import { classifyPerpDirection } from "./direction.js";
17
+
18
+ export interface OrdersFrameContext {
19
+ /** The account the subscription is filtered to, used when the frame omits `accts`. */
20
+ account: Address;
21
+ }
22
+
23
+ /** Per-frame facts the events need. */
24
+ interface FrameFacts {
25
+ batchMs: number;
26
+ accts?: WireOrdersFrame["accts"];
27
+ }
28
+
29
+ /**
30
+ * Fold one frame into `byId`, in place, and report the transitions it applied.
31
+ *
32
+ * Events naming an order that is not in `byId` and not in this frame are skipped:
33
+ * they belong to an order resting outside the caller's window, and its terms have
34
+ * never been on the wire, so there is nothing to display — and nothing to report.
35
+ *
36
+ * The returned events carry the order as the *whole* frame left it, not as it stood
37
+ * mid-frame: they are collected while applying but the rows are mutated in place, so a
38
+ * consumer never sees a half-applied order.
39
+ */
40
+ export function applyOrdersFrame(frame: WireOrdersFrame, byId: Map<string, Order>, ctx: OrdersFrameContext): OrderEvent[] {
41
+ // The book and the batch are frame constants: resolved once, not per entity.
42
+ const batchMs = usToMs(frame.batch);
43
+ const facts: FrameFacts = { batchMs, accts: frame.accts };
44
+ const created = frame.orders.map((e) => decodeEntity(e, frame, batchMs, ctx.account));
45
+
46
+ const applied: OrderEvent[] = [];
47
+ for (const event of frame.events) {
48
+ // `o` indexes this frame's entities and `id` names one resting from an earlier
49
+ // batch — but an event kind added later (ADR 0029 §6 reserves several) may name
50
+ // an entity from *this* frame by id, so try both before giving up. `created` is
51
+ // not in `byId` yet: entities are inserted after the events, so their own
52
+ // `new`/`reject` decides the status they land with.
53
+ const target = event.o !== undefined
54
+ ? created[event.o]
55
+ : byId.get(event.id ?? "") ?? created.find((o) => o.id === event.id);
56
+ if (!target) continue;
57
+ // `undefined` means a kind this version does not know, which is ignored rather than
58
+ // handed on as an event a consumer cannot act on (ADR 0029 §6). The switch is the
59
+ // only list of what is recognised — a separate one could disagree with it.
60
+ const outcome = applyEvent(event, target, facts);
61
+ if (outcome) {
62
+ applied.push({
63
+ kind: event.k as OrderEventKind,
64
+ order: target,
65
+ batchMs,
66
+ fill: outcome.fill,
67
+ amendRejection: outcome.amendRejection,
68
+ });
69
+ }
70
+ }
71
+
72
+ // After the events, not before: an entity's own `new`/`reject` decides the
73
+ // status it lands with. Entities left untouched by every event this version
74
+ // understands are still inserted — the frame said the order exists, and a
75
+ // transition from a newer server is no reason to drop the row.
76
+ for (const order of created) byId.set(order.id, order);
77
+ return applied;
78
+ }
79
+
80
+ function decodeEntity(e: WireOrderEntity, frame: WireOrdersFrame, batchMs: number, account: Address): Order {
81
+ const initialSize = dec(e.sz);
82
+ return {
83
+ id: e.id,
84
+ txHash: e.tx,
85
+ // The frame names the book, so this is exact rather than inferred. Whether
86
+ // that book is spot or perp is static market metadata, joined at read time by
87
+ // whoever needs it — freezing it here would strand every order decoded before
88
+ // the markets list loaded.
89
+ orderbookId: frame.book,
90
+ side: initialSize < 0n ? "sell" : "buy",
91
+ orderType: e.type === "market" ? "market" : "limit",
92
+ // Not on the entity: an order that rests is `active`, and the events below
93
+ // move it from there.
94
+ status: "active",
95
+ kind: (e.kind ?? "user_signed") as Order["kind"],
96
+ nonce: e.n,
97
+ // A frame with no `accts` covers exactly one account, so every row is its. An
98
+ // index the table does not reach falls back the same way rather than becoming an
99
+ // `undefined` typed as an address.
100
+ bidder: (e.a !== undefined ? frame.accts?.[e.a] : undefined) ?? account,
101
+ price: dec(e.px),
102
+ initialSize,
103
+ filledBase: 0n,
104
+ filledQuote: 0n,
105
+ fee: 0n,
106
+ endMs: endMsFromUs(e.end),
107
+ // When the order became real. The signed deadline is not on this wire and is
108
+ // deliberately not invented from the batch: REST reports both separately, so
109
+ // inclusion time is the one thing every source agrees on and the only honest
110
+ // key to order by.
111
+ includedMs: batchMs,
112
+ fills: [],
113
+ reduceOnly: e.reduce_only ?? false,
114
+ ioc: e.ioc ?? false,
115
+ triggerType: e.trigger as Order["triggerType"],
116
+ };
117
+ }
118
+
119
+ /**
120
+ * Take the order's life-to-date totals off the event that reports them.
121
+ *
122
+ * Every fill, cancel and expiry carries all three, zero included (ADR 0029 §4.1) —
123
+ * so they are read unconditionally, and an order that leaves the book reports what
124
+ * it filled rather than keeping whatever it last had. Authoritative rather than
125
+ * accumulated, so a client that missed a fill cannot drift.
126
+ */
127
+ function applyTotals(event: WireOrderEvent, order: Order): void {
128
+ order.filledBase = dec(event.tb);
129
+ order.filledQuote = dec(event.tq);
130
+ order.fee = dec(event.tf);
131
+ // Cleared, not skipped, when nothing is filled: a row reporting zero filled beside
132
+ // a fill price from before is worse than one with no fill price.
133
+ order.effectivePrice = order.filledBase > 0n ? div(order.filledQuote, order.filledBase) : undefined;
134
+ }
135
+
136
+ /**
137
+ * Apply one event. `undefined` when the kind is not one this version knows; otherwise what
138
+ * the event contributed beyond the order's own state — the fill, or the refused amendment.
139
+ */
140
+ function applyEvent(
141
+ event: WireOrderEvent,
142
+ order: Order,
143
+ facts: FrameFacts,
144
+ ): { fill?: OrderEventFill; amendRejection?: AmendRejection } | undefined {
145
+ switch (event.k) {
146
+ case "new":
147
+ order.status = "active";
148
+ return {};
149
+ case "reject":
150
+ order.status = "invalid";
151
+ order.rejectReason = event.why;
152
+ return {};
153
+ case "cancel":
154
+ order.status = "canceled";
155
+ applyTotals(event, order);
156
+ return {};
157
+ case "expire":
158
+ order.status = "expired";
159
+ applyTotals(event, order);
160
+ return {};
161
+ case "modify": {
162
+ order.price = dec(event.px);
163
+ // `sz` is an unsigned magnitude, so the side comes from the order we hold.
164
+ const sign = order.initialSize < 0n ? -1n : 1n;
165
+ order.initialSize = sign * dec(event.sz);
166
+ return {};
167
+ }
168
+ case "fill": {
169
+ applyTotals(event, order);
170
+ // `b`/`q` are this fill alone, and its time is the batch it cleared in — the
171
+ // auction's own timestamp rather than when this client happened to read it.
172
+ const base = dec(event.b);
173
+ const quote = dec(event.q);
174
+ const fill: PartialFill = { base, quote, price: div(quote, base), time: facts.batchMs };
175
+ // A real fill always has size. A zero-size one is the engine flipping status: the
176
+ // cap-to-filled amendment fabricates it so `st: filled` reaches the indexer, which
177
+ // reads status from fills alone. Its totals and status count; adding a
178
+ // `0.0000 @ $0.00` row to the order's fill history would only invent a trade.
179
+ if (base !== 0n) order.fills = [...order.fills, fill];
180
+ // A perp fill reports the position it left. The position it started from is
181
+ // that minus what this fill moved it — a buy raises it, a sell lowers it — and
182
+ // the transition is what says whether the order opened, added to, reduced,
183
+ // closed or flipped. Without it a client can only guess from the order's own
184
+ // side and `reduceOnly`, which calls a plain sell that closed a long an
185
+ // "Open Short".
186
+ if (event.pa !== undefined) {
187
+ const after = dec(event.pa);
188
+ const before = after - (order.initialSize < 0n ? -base : base);
189
+ // A forced close is labelled by how it came about, not by the transition it
190
+ // made — `order_direction_for_response` overrides the classifier the same way,
191
+ // and without this a liquidation reads `close_long` here and `liquidation`
192
+ // after a REST refetch.
193
+ order.direction = order.kind === "liquidation" ? "liquidation" : classifyPerpDirection(before, after);
194
+ }
195
+ // Present only on the fill that closed the order.
196
+ if (event.st) order.status = event.st as OrderStatus;
197
+ // Copied rather than shared: the same object is in `order.fills`, and attaching a
198
+ // per-event field to it would leak the event into the order's fill history.
199
+ return {
200
+ fill: { ...fill, totalBase: dec(event.tb), closedAs: event.st as TerminalStatus | undefined },
201
+ };
202
+ }
203
+ case "modify_reject":
204
+ // Reported, not applied: this answers an amendment that did not happen, so the order
205
+ // is left exactly as it was — which is also why it belongs to the event and not to
206
+ // the order. Without it a refused price change looks like one still in flight.
207
+ // `by` is the requester, not the owner — on `not_order_owner` it is precisely who
208
+ // does not own the order — so it is resolved separately from `a`.
209
+ return {
210
+ amendRejection: {
211
+ requestedPrice: dec(event.req_px),
212
+ requestedSize: dec(event.req_sz),
213
+ code: (event.code ?? "unspecified") as RejectCode,
214
+ message: event.why,
215
+ requestedBy: event.by !== undefined ? facts.accts?.[event.by] : undefined,
216
+ batchMs: facts.batchMs,
217
+ },
218
+ };
219
+ // ADR 0029 §6: kinds are open, so an unrecognised one falls through to
220
+ // `undefined` — applied to nothing, reported to nobody.
221
+ }
222
+ }
@@ -34,6 +34,22 @@ export function usToMsOpt(us: number | string | null | undefined): number | unde
34
34
  return us === null || us === undefined ? undefined : usToMs(us);
35
35
  }
36
36
 
37
+ /**
38
+ * An order's TTL expiry: microseconds -> milliseconds, or undefined when it never
39
+ * expires.
40
+ *
41
+ * "Never" has two spellings on the wire. `pod_orders_v2` omits the field; REST
42
+ * sends the engine's `Timestamp::MAX` sentinel, a u128 that arrives as a 39-digit
43
+ * number no JS number can hold exactly. Anything past `Number.MAX_SAFE_INTEGER`
44
+ * micros — the year 2255 — is that sentinel rather than a TTL someone signed.
45
+ */
46
+ export function endMsFromUs(us: number | string | null | undefined): number | undefined {
47
+ if (us === null || us === undefined) return undefined;
48
+ const n = typeof us === "string" ? Number(us) : us;
49
+ // `NaN` and `Infinity` both fail this comparison, so it is the whole guard.
50
+ return n <= Number.MAX_SAFE_INTEGER ? usToMs(n) : undefined;
51
+ }
52
+
37
53
  /** Milliseconds -> microseconds (for request params that take micros). */
38
54
  export function msToUs(ms: number): number {
39
55
  return ms * 1000;
@@ -1,39 +1,97 @@
1
1
  // OrderHistory: a SeriesResource<Order> seeded from the warm first page, kept
2
- // live by the pod_orders stream (bidder-filtered, `since`-resumed, all update
3
- // variants incl. `modified`), and paged backwards by cursor for deep history.
2
+ // live by the pod_orders_v2 stream (bidder-filtered, resumed from a (batch, book)
3
+ // cursor), and paged backwards by cursor for deep history.
4
4
  //
5
5
  // Reconnect: on every (re)connect we re-seed the first page (authoritative open
6
- // orders) and refresh `since` from its watermark; the WS auto-resubscribes, and
7
- // if `since` is too old (down too long) `onError` re-seeds and resubscribes.
6
+ // orders) and refresh the cursor from its watermark; the WS auto-resubscribes,
7
+ // and if the cursor is too old (down too long) `onError` re-seeds and
8
+ // resubscribes. A server-initiated close is not the same as a rejection: it
9
+ // reports where delivery stopped, so resuming from one is a bare `resubscribe()`
10
+ // with no re-seed.
8
11
 
9
- import type { Address, MarketId, Order, OrderStatus, OrdersQuery } from "../types/public.js";
10
- import type { WireOrderUpdate } from "../types/wire.js";
11
- import { dec, WAD } from "../codec/units.js";
12
- import { decodeOrder } from "../codec/decode.js";
12
+ import type { Address, MarketId, Order, OrderEvent, OrdersQuery } from "../types/public.js";
13
+ import type { WireOrdersFrame } from "../types/wire.js";
14
+ import { applyOrdersFrame } from "../codec/orders-v2.js";
13
15
  import { BaseResource, type ResourceHandle } from "../stores/resource.js";
14
- import type { Subscription } from "../transport/ws.js";
16
+ import { PodSubscriptionClosedError, type SubParams, type Subscription } from "../transport/ws.js";
15
17
  import type { SeriesResource } from "./candles.js";
16
18
  import type { SyncContext } from "./sources.js";
17
19
 
20
+ /**
21
+ * Consecutive server closes we resume from before falling back to the re-seed
22
+ * path. A lagged close is recoverable by resubscribing, so the fast path is the
23
+ * right default — but a stream that keeps closing is one we are not keeping up
24
+ * with, and re-seeding beats replaying a growing backlog on every attempt.
25
+ */
26
+ const FAST_RESUMES_BEFORE_RESEED = 3;
27
+
28
+ /**
29
+ * Re-seed attempts that keep the cursor before we conclude the cursor is what the
30
+ * server is rejecting, drop it, and settle for streaming live.
31
+ */
32
+ const RETRIES_BEFORE_DROPPING_CURSOR = 2;
33
+
34
+ /** The largest book id, which is what an absent `sinceBook` means. */
35
+ const WHOLE_BATCH = `0x${"ff".repeat(32)}` as MarketId;
36
+
37
+ /**
38
+ * Order two positions in the stream, the way the server does.
39
+ *
40
+ * A batch is delivered as one frame per book, so a position is the pair
41
+ * `(batch, book)` — and an absent book means the whole batch, which sorts *above*
42
+ * every book in it. This mirrors `already_delivered` in
43
+ * `node/src/rpc/orders_v2.rs`: `(frame_batch, frame_book) <= (since,
44
+ * since_book.unwrap_or(0xff…))`. Getting the absent case wrong turns "all of batch
45
+ * N" into "up to book B of batch N", which asks the server to re-send the rest.
46
+ *
47
+ * Book ids are fixed-width lowercase hex, so comparing them as strings is
48
+ * comparing their bytes.
49
+ */
50
+ export function compareCursor(a: SubParams, b: SubParams): number {
51
+ const aBatch = a.since ?? 0;
52
+ const bBatch = b.since ?? 0;
53
+ if (aBatch !== bBatch) return aBatch < bBatch ? -1 : 1;
54
+ const aBook = a.sinceBook ?? WHOLE_BATCH;
55
+ const bBook = b.sinceBook ?? WHOLE_BATCH;
56
+ return aBook === bBook ? 0 : aBook < bBook ? -1 : 1;
57
+ }
58
+
18
59
  export class OrderHistory implements SeriesResource<Order> {
19
60
  private readonly base: BaseResource<Order[]>;
20
61
  private handle: ResourceHandle<Order[]> | undefined;
21
62
  private readonly byId = new Map<string, Order>();
22
63
  private nextCursor: string | null = null;
23
64
  private sub: Subscription | undefined;
24
- private watermarkUs = 0;
25
65
  private alive = false;
26
66
  private _hasMore = true;
27
67
  private _loading = false;
28
68
  private subRetries = 0;
69
+ private fastResumes = 0;
29
70
  private retryTimer?: ReturnType<typeof setTimeout>;
71
+ private readonly eventListeners = new Set<(events: OrderEvent[]) => void>();
72
+ /**
73
+ * Where the stream is: the last frame accepted, as the `(batch, book)` pair the
74
+ * channel resumes from. Replaced whole rather than patched half at a time —
75
+ * `sinceBook` names a book *within* `since`, so the two are one fact and a
76
+ * mismatched pair asks the server to skip books we never saw.
77
+ */
78
+ private cursor: SubParams = { since: 0, sinceBook: undefined };
79
+
80
+ /**
81
+ * Push the cursor to the transport, both halves.
82
+ *
83
+ * `update` merges, so sending `{ since }` alone would leave whatever `sinceBook` was
84
+ * there before — a book from an older batch beside a newer `since`, which asks the
85
+ * server to skip less than it should and re-send the difference.
86
+ */
87
+ private pushCursor(): void {
88
+ this.sub?.update({ since: this.cursor.since, sinceBook: this.cursor.sinceBook });
89
+ }
30
90
 
31
91
  constructor(
32
92
  private readonly ctx: SyncContext,
33
93
  private readonly account: Address,
34
94
  private readonly query: OrdersQuery = {},
35
- /** Maps a WS order's token pair to its orderbook id (see rebuild). */
36
- private readonly resolveOrderbookId?: (pair: { base: Address; quote: Address }) => MarketId | undefined,
37
95
  ) {
38
96
  this.base = new BaseResource<Order[]>((h) => {
39
97
  this.handle = h;
@@ -59,6 +117,26 @@ export class OrderHistory implements SeriesResource<Order> {
59
117
  loading(): boolean { return this._loading; }
60
118
  destroy(): void { this.base.destroy(); }
61
119
 
120
+ /**
121
+ * Observe the transitions the stream reports, as they arrive — a frame at a time, in
122
+ * the order the engine caused them.
123
+ *
124
+ * The snapshot (`get`/`subscribe`) is what to render; this is what *happened*, which
125
+ * a snapshot cannot express: two fills in one batch are one state change, and a
126
+ * refused amendment is none at all. Nothing is emitted for the REST seed, so a
127
+ * consumer never has to filter out a backlog of history as if it were live.
128
+ */
129
+ onEvent(listener: (events: OrderEvent[]) => void): () => void {
130
+ this.eventListeners.add(listener);
131
+ // Listening starts the stream, like subscribing does. The resource is ref-counted
132
+ // from `subscribe`/`ready` alone, so without holding one an event-only consumer
133
+ // would wait forever — and would fall silent the moment the last snapshot
134
+ // subscriber left, since teardown drops the websocket subscription and leaves the
135
+ // listeners registered.
136
+ const release = this.base.subscribe(() => {});
137
+ return () => { this.eventListeners.delete(listener); release(); };
138
+ }
139
+
62
140
  setWindow(): void { /* order history pages by cursor, not by time window */ }
63
141
 
64
142
  async loadOlder(): Promise<void> {
@@ -82,13 +160,27 @@ export class OrderHistory implements SeriesResource<Order> {
82
160
  // --- internals ---
83
161
 
84
162
  private async fetchFirstPage(): Promise<boolean> {
163
+ const before = this.cursor;
85
164
  try {
86
165
  const page = await this.ctx.rest.orders(this.account, { limit: this.query.limit ?? 100 });
87
166
  if (!this.alive) return false;
88
- for (const o of page.orders) this.byId.set(o.id, o);
167
+ // The transport resubscribes synchronously right after the `open` event that
168
+ // starts this fetch, so replayed frames can land while it is still in flight —
169
+ // and the indexer trails the stream by design. Overwriting a row the stream has
170
+ // already advanced would revert it, permanently: the cursor below refuses to
171
+ // rewind and `onFrame` drops a re-delivery, so nothing would repair it.
172
+ const streamMovedOn = compareCursor(this.cursor, before) > 0;
173
+ for (const o of page.orders) {
174
+ if (streamMovedOn && this.byId.has(o.id)) continue;
175
+ this.byId.set(o.id, o);
176
+ }
89
177
  this.nextCursor = page.nextCursor;
90
178
  this._hasMore = page.nextCursor !== null;
91
- this.watermarkUs = page.solutionNow * 1000;
179
+ // Only ever forward, and a page settles whole batches, so its watermark
180
+ // carries no book — which makes it *ahead* of a stream position in the same
181
+ // batch, not equal to it.
182
+ const settled: SubParams = { since: page.solutionNow * 1000, sinceBook: undefined };
183
+ if (compareCursor(settled, this.cursor) > 0) this.cursor = settled;
92
184
  this.rebuild();
93
185
  return true;
94
186
  } catch (e) {
@@ -102,104 +194,132 @@ export class OrderHistory implements SeriesResource<Order> {
102
194
  if (!ok || !this.alive) return;
103
195
  if (!this.sub) {
104
196
  this.sub = this.ctx.ws.subscribe(
105
- "pod_orders",
106
- { account: this.account, since: this.watermarkUs },
107
- (r) => this.onUpdates(r),
108
- () => this.onSubError(),
197
+ "pod_orders_v2",
198
+ { account: this.account, ...this.cursor },
199
+ (r) => this.onFrame(r),
200
+ (e) => this.onSubError(e),
109
201
  );
110
202
  } else {
111
- this.sub.update({ since: this.watermarkUs }); // refresh for the next reconnect
203
+ this.pushCursor(); // refresh for the next reconnect
112
204
  }
113
205
  });
114
206
  }
115
207
 
116
208
  /**
117
- * Subscription rejected — re-seed then resubscribe. Backed off (and capped),
118
- * so a server that keeps rejecting can't spin this into a tight re-seed /
119
- * resubscribe loop. After a couple of failures we drop `since` (the likely
120
- * culprit) and just stream live. Reset once live data flows (`onUpdates`).
209
+ * The subscription is not running: `eth_subscribe` was rejected, or the server
210
+ * closed it.
211
+ *
212
+ * A resumable close needs neither a re-seed nor a delay: the server reports where
213
+ * it stopped, so resubscribing from that delivers exactly the frames we never got.
214
+ * That fast path is only taken while the socket is actually open — `resubscribe()`
215
+ * is a no-op otherwise, which would spend the budget without an attempt and leave
216
+ * nothing scheduled, and `-32021` (node shutting down) arrives exactly as the
217
+ * socket goes away.
218
+ *
219
+ * Everything else (a rejection, a server bug, a close with the socket already
220
+ * gone, or closes that keep coming) takes the slow path: backed off and capped, so
221
+ * a server that keeps refusing cannot spin this into a tight re-seed loop, and
222
+ * eventually the cursor is dropped (the likely culprit) to just stream live. Both
223
+ * counters reset once live data flows (`onFrame`).
121
224
  */
122
- private onSubError(): void {
225
+ private onSubError(err: unknown): void {
123
226
  if (!this.alive) return;
227
+ const canFastResume = err instanceof PodSubscriptionClosedError && err.resumable
228
+ && this.fastResumes < FAST_RESUMES_BEFORE_RESEED && this.ctx.ws.state === "open";
229
+ if (canFastResume) {
230
+ this.fastResumes++;
231
+ // Adopt the server's watermark only when it is ahead of ours: it knows which
232
+ // frames it handed over, but a re-seed may already have carried us past it,
233
+ // and rewinding would re-deliver frames we have applied.
234
+ const reported: SubParams = { since: err.resumeSince, sinceBook: err.resumeSinceBook };
235
+ if (err.resumeSince !== undefined && compareCursor(reported, this.cursor) > 0) this.cursor = reported;
236
+ // The transport rewrote `sub.params` from the close before this ran, so without
237
+ // pushing our own decision back the wire resumes from the server's point
238
+ // regardless and the guard above protects nothing.
239
+ this.pushCursor();
240
+ this.sub?.resubscribe();
241
+ return;
242
+ }
243
+ // The slow path, and the one that answers "what if we fell behind the server's
244
+ // replay buffer": `eth_subscribe` rejects a `since` older than what the buffer
245
+ // retains, and the prescribed recovery is to backfill over REST and resubscribe.
246
+ // That is what this is. `fetchFirstPage` also *replaces the cursor* with the
247
+ // page's watermark, so the position that was too old is gone by the first retry
248
+ // and the resubscribe is accepted with no gap — the server replays from the page
249
+ // forward. Dropping the cursor below is the backstop for when even that fresh
250
+ // watermark is refused (the indexer further behind than the buffer retains):
251
+ // live-only resubscribe, trading the unreplayable window for a working stream.
252
+ this.scheduleReseed();
253
+ }
254
+
255
+ /**
256
+ * Back off, re-seed over REST, then resubscribe — and keep trying.
257
+ *
258
+ * The re-seed can fail too (the same node is usually behind both the stream and the
259
+ * indexer), and a failure has to re-arm here: not resubscribing means no further
260
+ * close or rejection arrives, so nothing else would ever schedule another attempt and
261
+ * the stream would stay down with no error surfaced. Capped, so a node that keeps
262
+ * refusing cannot spin this.
263
+ */
264
+ private scheduleReseed(): void {
124
265
  this.subRetries++;
125
266
  const delay = Math.min(30_000, 500 * 2 ** (this.subRetries - 1));
126
267
  if (this.retryTimer) clearTimeout(this.retryTimer);
127
268
  this.retryTimer = setTimeout(() => {
128
269
  void this.fetchFirstPage().then((ok) => {
129
- if (!ok || !this.alive) return;
130
- this.sub?.update({ since: this.subRetries > 2 ? undefined : this.watermarkUs });
270
+ if (!this.alive) return;
271
+ if (!ok) { this.scheduleReseed(); return; }
272
+ const tooOld = this.subRetries > RETRIES_BEFORE_DROPPING_CURSOR;
273
+ if (tooOld) this.sub?.update({ since: undefined, sinceBook: undefined });
274
+ else this.pushCursor();
131
275
  this.sub?.resubscribe();
132
276
  });
133
277
  }, delay);
134
278
  }
135
279
 
136
- private onUpdates(result: unknown): void {
137
- this.subRetries = 0; // live data flowing → subscription is healthy
138
- const updates = (Array.isArray(result) ? result : [result]) as WireOrderUpdate[];
139
- for (const u of updates) this.applyUpdate(u);
140
- this.rebuild();
141
- }
280
+ /** One frame: everything that happened to one book in one auction batch. */
281
+ private onFrame(result: unknown): void {
282
+ // Live data flowing → the subscription is healthy on both paths.
283
+ this.subRetries = 0;
284
+ this.fastResumes = 0;
285
+ const frame = result as WireOrdersFrame;
286
+ if (!frame || !Array.isArray(frame.orders) || !Array.isArray(frame.events)) return;
142
287
 
143
- private applyUpdate(u: WireOrderUpdate): void {
144
- switch (u.type) {
145
- case "new":
146
- case "invalid": {
147
- const o = decodeOrder(u);
148
- this.byId.set(o.id, o);
149
- break;
150
- }
151
- case "fill": {
152
- const e = this.byId.get(u.order_id);
153
- if (e) {
154
- e.filledBase = dec(u.filled_base_amount);
155
- e.filledQuote = dec(u.filled_quote_amount);
156
- e.fee = dec(u.fee);
157
- e.status = u.status as OrderStatus;
158
- if (u.effective_price != null) e.effectivePrice = dec(u.effective_price);
159
- // Keep the per-fill breakdown live too. The push carries this fill's
160
- // base/quote delta but no timestamp — receipt time is close enough.
161
- const base = dec(u.base_amount);
162
- const quote = dec(u.quote_amount);
163
- e.fills = [...e.fills, { base, quote, price: base > 0n ? (quote * WAD) / base : 0n, time: Date.now() }];
164
- }
165
- break;
166
- }
167
- case "modified": {
168
- const e = this.byId.get(u.order_id);
169
- if (e) {
170
- e.price = dec(u.new_price);
171
- const sign = e.initialSize < 0n ? -1n : 1n;
172
- e.initialSize = sign * dec(u.new_size); // new_size is an unsigned magnitude
173
- }
174
- break;
175
- }
176
- case "expired": {
177
- const e = this.byId.get(u.order_id);
178
- if (e) e.status = "expired";
179
- break;
180
- }
181
- case "canceled": {
182
- const e = this.byId.get(u.order_id);
183
- if (e) e.status = "canceled";
184
- break;
288
+ // Drop what we already hold. Applying a frame is not idempotent — a fill event
289
+ // appends to `order.fills`, and re-creating an entity resets its totals — and
290
+ // re-delivery is designed in: a resumed subscription replays from a cursor, and
291
+ // the replay boundary is a whole batch. Same predicate as the server's
292
+ // `already_delivered`, so client and server agree on what "already sent" means.
293
+ const at: SubParams = { since: frame.batch, sinceBook: frame.book };
294
+ if (compareCursor(at, this.cursor) <= 0) return;
295
+
296
+ const events = applyOrdersFrame(frame, this.byId, { account: this.account });
297
+ // A socket-level reconnect resubscribes from whatever is stored here.
298
+ this.cursor = at;
299
+ this.sub?.update(at);
300
+ this.rebuild();
301
+ // Strictly after `rebuild()`: a listener that reads the resource in response to an
302
+ // event must see the state that event produced, not the state before it.
303
+ if (events.length) {
304
+ for (const listener of this.eventListeners) {
305
+ try { listener(events); } catch { /* a listener's failure is not the stream's */ }
185
306
  }
186
307
  }
187
308
  }
188
309
 
189
310
  private rebuild(): void {
190
311
  if (!this.handle) return;
191
- // WS stream orders carry a token `pair` instead of orderbook_id — resolve
192
- // it here so consumers can always filter by market. Retried every rebuild,
193
- // so orders that streamed in before the markets list loaded still resolve.
194
- if (this.resolveOrderbookId) {
195
- for (const o of this.byId.values()) {
196
- if (o.orderbookId === undefined && o.pair) o.orderbookId = this.resolveOrderbookId(o.pair);
197
- }
198
- }
199
312
  let arr = [...this.byId.values()];
200
313
  if (this.query.status) arr = arr.filter((o) => o.status === this.query.status);
201
314
  if (this.query.orderbookId) arr = arr.filter((o) => o.orderbookId === this.query.orderbookId);
202
- arr.sort((a, b) => b.deadlineMs - a.deadlineMs || b.nonce - a.nonce);
315
+ // Newest first by when the order became real. Inclusion time is the key both
316
+ // sources report — REST sends it alongside the signed deadline, and a frame's
317
+ // batch *is* it — so a REST row and a streamed row sort against each other. An
318
+ // order with none has not been in a batch yet, so it is newer than every order
319
+ // that has; the signed deadline is deliberately not a fallback, since it is a
320
+ // future time and would sort on a different clock.
321
+ const at = (o: Order) => o.includedMs ?? Number.MAX_SAFE_INTEGER;
322
+ arr.sort((a, b) => at(b) - at(a) || b.nonce - a.nonce);
203
323
  this.handle.set(arr);
204
324
  }
205
325
  }