@pod-network/trade-sdk 0.10.0 → 0.12.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 (86) hide show
  1. package/README.md +6 -4
  2. package/dist/client.d.ts +30 -11
  3. package/dist/client.d.ts.map +1 -1
  4. package/dist/client.js +37 -17
  5. package/dist/client.js.map +1 -1
  6. package/dist/codec/activity.d.ts +11 -0
  7. package/dist/codec/activity.d.ts.map +1 -0
  8. package/dist/codec/activity.js +33 -0
  9. package/dist/codec/activity.js.map +1 -0
  10. package/dist/codec/decode.d.ts +14 -6
  11. package/dist/codec/decode.d.ts.map +1 -1
  12. package/dist/codec/decode.js +58 -24
  13. package/dist/codec/decode.js.map +1 -1
  14. package/dist/codec/json.d.ts +3 -0
  15. package/dist/codec/json.d.ts.map +1 -0
  16. package/dist/codec/json.js +14 -0
  17. package/dist/codec/json.js.map +1 -0
  18. package/dist/codec/orders-v2.d.ts +9 -3
  19. package/dist/codec/orders-v2.d.ts.map +1 -1
  20. package/dist/codec/orders-v2.js +12 -9
  21. package/dist/codec/orders-v2.js.map +1 -1
  22. package/dist/index.d.ts +3 -2
  23. package/dist/index.d.ts.map +1 -1
  24. package/dist/index.js +1 -0
  25. package/dist/index.js.map +1 -1
  26. package/dist/stores/resource.d.ts +48 -2
  27. package/dist/stores/resource.d.ts.map +1 -1
  28. package/dist/stores/resource.js +75 -6
  29. package/dist/stores/resource.js.map +1 -1
  30. package/dist/sync/activity.d.ts +58 -0
  31. package/dist/sync/activity.d.ts.map +1 -0
  32. package/dist/sync/activity.js +259 -0
  33. package/dist/sync/activity.js.map +1 -0
  34. package/dist/sync/orders.d.ts +8 -65
  35. package/dist/sync/orders.d.ts.map +1 -1
  36. package/dist/sync/orders.js +44 -192
  37. package/dist/sync/orders.js.map +1 -1
  38. package/dist/sync/pnl-history.d.ts +33 -14
  39. package/dist/sync/pnl-history.d.ts.map +1 -1
  40. package/dist/sync/pnl-history.js +255 -65
  41. package/dist/sync/pnl-history.js.map +1 -1
  42. package/dist/sync/sources.d.ts.map +1 -1
  43. package/dist/sync/sources.js +12 -5
  44. package/dist/sync/sources.js.map +1 -1
  45. package/dist/sync/stream.d.ts +101 -0
  46. package/dist/sync/stream.d.ts.map +1 -0
  47. package/dist/sync/stream.js +243 -0
  48. package/dist/sync/stream.js.map +1 -0
  49. package/dist/transport/jsonrpc.d.ts +0 -5
  50. package/dist/transport/jsonrpc.d.ts.map +1 -1
  51. package/dist/transport/jsonrpc.js +0 -20
  52. package/dist/transport/jsonrpc.js.map +1 -1
  53. package/dist/transport/rest.d.ts +36 -4
  54. package/dist/transport/rest.d.ts.map +1 -1
  55. package/dist/transport/rest.js +43 -10
  56. package/dist/transport/rest.js.map +1 -1
  57. package/dist/transport/ws.d.ts +5 -1
  58. package/dist/transport/ws.d.ts.map +1 -1
  59. package/dist/transport/ws.js.map +1 -1
  60. package/dist/types/public.d.ts +62 -23
  61. package/dist/types/public.d.ts.map +1 -1
  62. package/dist/types/wire.d.ts +98 -16
  63. package/dist/types/wire.d.ts.map +1 -1
  64. package/dist/write/index.d.ts +3 -3
  65. package/dist/write/index.d.ts.map +1 -1
  66. package/dist/write/index.js +0 -3
  67. package/dist/write/index.js.map +1 -1
  68. package/package.json +1 -1
  69. package/src/client.ts +49 -19
  70. package/src/codec/activity.ts +46 -0
  71. package/src/codec/decode.ts +65 -30
  72. package/src/codec/json.ts +18 -0
  73. package/src/codec/orders-v2.ts +24 -11
  74. package/src/index.ts +4 -2
  75. package/src/stores/resource.ts +111 -5
  76. package/src/sync/activity.ts +266 -0
  77. package/src/sync/orders.ts +46 -189
  78. package/src/sync/pnl-history.ts +244 -75
  79. package/src/sync/sources.ts +12 -6
  80. package/src/sync/stream.ts +270 -0
  81. package/src/transport/jsonrpc.ts +0 -23
  82. package/src/transport/rest.ts +62 -14
  83. package/src/transport/ws.ts +5 -1
  84. package/src/types/public.ts +62 -26
  85. package/src/types/wire.ts +105 -18
  86. package/src/write/index.ts +3 -6
@@ -1,115 +1,56 @@
1
1
  // OrderHistory: a SeriesResource<Order> seeded from the warm first page, kept
2
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
- //
5
- // Reconnect: on every (re)connect we re-seed the first page (authoritative open
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.
3
+ // cursor by `ResumableStream`), and paged backwards by cursor for deep history.
11
4
 
12
- import type { Address, MarketId, Order, OrderEvent, OrdersQuery } from "../types/public.js";
5
+ import type { Address, Order, OrderEvent, OrdersQuery } from "../types/public.js";
13
6
  import type { WireOrdersFrame } from "../types/wire.js";
14
7
  import { applyOrdersFrame } from "../codec/orders-v2.js";
15
- import { BaseResource, type ResourceHandle } from "../stores/resource.js";
16
- import { PodSubscriptionClosedError, type SubParams, type Subscription } from "../transport/ws.js";
8
+ import { BaseResource, type ResourceHandle, type Snapshot, type SnapshotSlot } from "../stores/resource.js";
9
+ import type { SubParams } from "../transport/ws.js";
17
10
  import type { SeriesResource } from "./candles.js";
18
11
  import type { SyncContext } from "./sources.js";
12
+ import { compareCursor, ResumableStream } from "./stream.js";
19
13
 
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
- }
14
+ export { compareCursor } from "./stream.js";
58
15
 
59
16
  export class OrderHistory implements SeriesResource<Order> {
60
17
  private readonly base: BaseResource<Order[]>;
61
18
  private handle: ResourceHandle<Order[]> | undefined;
62
19
  private readonly byId = new Map<string, Order>();
63
20
  private nextCursor: string | null = null;
64
- private sub: Subscription | undefined;
65
- private alive = false;
21
+ private painted = false;
22
+ private seedGen = 0;
66
23
  private _hasMore = true;
67
24
  private _loading = false;
68
- private subRetries = 0;
69
- private fastResumes = 0;
70
- private retryTimer?: ReturnType<typeof setTimeout>;
71
25
  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
- }
26
+ private readonly stream: ResumableStream;
90
27
 
91
28
  constructor(
92
29
  private readonly ctx: SyncContext,
93
30
  private readonly account: Address,
94
31
  private readonly query: OrdersQuery = {},
32
+ slot?: SnapshotSlot,
95
33
  ) {
34
+ this.stream = new ResumableStream({
35
+ ws: ctx.ws,
36
+ channel: "pod_orders_v2",
37
+ params: { account },
38
+ reseed: () => this.fetchFirstPage(),
39
+ onFrame: (r) => this.onFrame(r),
40
+ });
96
41
  this.base = new BaseResource<Order[]>((h) => {
97
42
  this.handle = h;
98
- this.alive = true;
99
- const offOpen = this.ctx.ws.on("open", () => { if (this.alive) this.seed(); });
100
- this.seed(); // initial paint (REST is independent of the socket being open)
43
+ this.stream.start();
101
44
  return () => {
102
- this.alive = false;
103
- offOpen();
104
- if (this.retryTimer) clearTimeout(this.retryTimer);
105
- this.sub?.unsubscribe();
106
- this.sub = undefined;
45
+ this.stream.stop();
107
46
  this.handle = undefined;
108
47
  };
109
- });
48
+ }, slot);
110
49
  }
111
50
 
112
51
  get(): Order[] | undefined { return this.base.get(); }
52
+ lastKnown(): Snapshot<Order[]> | undefined { return this.base.lastKnown(); }
53
+ isProvisional(): boolean { return this.base.isProvisional(); }
113
54
  subscribe(listener: () => void): () => void { return this.base.subscribe(listener); }
114
55
  ready(): Promise<Order[]> { return this.base.ready(); }
115
56
  get error(): Error | undefined { return this.base.error; }
@@ -160,143 +101,59 @@ export class OrderHistory implements SeriesResource<Order> {
160
101
  // --- internals ---
161
102
 
162
103
  private async fetchFirstPage(): Promise<boolean> {
163
- const before = this.cursor;
104
+ const gen = ++this.seedGen;
105
+ const before = this.stream.cursor;
164
106
  try {
165
107
  const page = await this.ctx.rest.orders(this.account, { limit: this.query.limit ?? 100 });
166
- if (!this.alive) return false;
108
+ // A seed overtaken by a fresher one is dropped whole: it would absorb rows the
109
+ // newer page has already corrected, and raise the cursor to an older watermark.
110
+ if (!this.stream.running || gen !== this.seedGen) return false;
167
111
  // The transport resubscribes synchronously right after the `open` event that
168
112
  // starts this fetch, so replayed frames can land while it is still in flight —
169
113
  // 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;
114
+ // already advanced would revert it, permanently: the cursor refuses to rewind
115
+ // and `onFrame` drops a re-delivery, so nothing would repair it.
116
+ const streamMovedOn = compareCursor(this.stream.cursor, before) > 0;
173
117
  for (const o of page.orders) {
174
118
  if (streamMovedOn && this.byId.has(o.id)) continue;
175
119
  this.byId.set(o.id, o);
176
120
  }
177
- this.nextCursor = page.nextCursor;
178
- this._hasMore = page.nextCursor !== null;
121
+ // Paging is the consumer's position in history, not the seed's: a reconnect
122
+ // re-paints the first page, and taking its cursor again would hand back pages
123
+ // `loadOlder` has already walked past.
124
+ if (!this.painted) {
125
+ this.painted = true;
126
+ this.nextCursor = page.nextCursor;
127
+ this._hasMore = page.nextCursor !== null;
128
+ }
179
129
  // Only ever forward, and a page settles whole batches, so its watermark
180
130
  // carries no book — which makes it *ahead* of a stream position in the same
181
131
  // 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;
132
+ this.stream.raise({ since: page.solutionNow * 1000, sinceBook: undefined });
184
133
  this.rebuild();
185
134
  return true;
186
135
  } catch (e) {
187
- if (this.byId.size === 0) this.handle?.fail(e as Error);
188
- return false;
136
+ // Only before the first paint: an account whose history is genuinely empty has
137
+ // a resource, and reporting a later transient failure on it would blank the view.
138
+ if (this.handle && this.handle.current() === undefined) this.handle.fail(e as Error);
139
+ throw e;
189
140
  }
190
141
  }
191
142
 
192
- private seed(): void {
193
- void this.fetchFirstPage().then((ok) => {
194
- if (!ok || !this.alive) return;
195
- if (!this.sub) {
196
- this.sub = this.ctx.ws.subscribe(
197
- "pod_orders_v2",
198
- { account: this.account, ...this.cursor },
199
- (r) => this.onFrame(r),
200
- (e) => this.onSubError(e),
201
- );
202
- } else {
203
- this.pushCursor(); // refresh for the next reconnect
204
- }
205
- });
206
- }
207
-
208
- /**
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`).
224
- */
225
- private onSubError(err: unknown): void {
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 {
265
- this.subRetries++;
266
- const delay = Math.min(30_000, 500 * 2 ** (this.subRetries - 1));
267
- if (this.retryTimer) clearTimeout(this.retryTimer);
268
- this.retryTimer = setTimeout(() => {
269
- void this.fetchFirstPage().then((ok) => {
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();
275
- this.sub?.resubscribe();
276
- });
277
- }, delay);
278
- }
279
-
280
143
  /** One frame: everything that happened to one book in one auction batch. */
281
144
  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
145
  const frame = result as WireOrdersFrame;
286
146
  if (!frame || !Array.isArray(frame.orders) || !Array.isArray(frame.events)) return;
287
147
 
288
148
  // Drop what we already hold. Applying a frame is not idempotent — a fill event
289
149
  // appends to `order.fills`, and re-creating an entity resets its totals — and
290
150
  // 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.
151
+ // the replay boundary is a whole batch.
293
152
  const at: SubParams = { since: frame.batch, sinceBook: frame.book };
294
- if (compareCursor(at, this.cursor) <= 0) return;
153
+ if (this.stream.delivered(at)) return;
295
154
 
296
155
  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);
156
+ this.stream.advance(at);
300
157
  this.rebuild();
301
158
  // Strictly after `rebuild()`: a listener that reads the resource in response to an
302
159
  // event must see the state that event produced, not the state before it.