@pod-network/trade-sdk 0.9.0 → 0.11.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 (72) hide show
  1. package/README.md +6 -4
  2. package/dist/client.d.ts +32 -4
  3. package/dist/client.d.ts.map +1 -1
  4. package/dist/client.js +50 -5
  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/orders-v2.d.ts +9 -3
  15. package/dist/codec/orders-v2.d.ts.map +1 -1
  16. package/dist/codec/orders-v2.js +12 -9
  17. package/dist/codec/orders-v2.js.map +1 -1
  18. package/dist/index.d.ts +3 -1
  19. package/dist/index.d.ts.map +1 -1
  20. package/dist/index.js +2 -0
  21. package/dist/index.js.map +1 -1
  22. package/dist/sync/activity.d.ts +58 -0
  23. package/dist/sync/activity.d.ts.map +1 -0
  24. package/dist/sync/activity.js +259 -0
  25. package/dist/sync/activity.js.map +1 -0
  26. package/dist/sync/order-preview.d.ts +3 -0
  27. package/dist/sync/order-preview.d.ts.map +1 -1
  28. package/dist/sync/order-preview.js +56 -0
  29. package/dist/sync/order-preview.js.map +1 -1
  30. package/dist/sync/orders.d.ts +4 -64
  31. package/dist/sync/orders.d.ts.map +1 -1
  32. package/dist/sync/orders.js +40 -190
  33. package/dist/sync/orders.js.map +1 -1
  34. package/dist/sync/pnl-history.d.ts +140 -0
  35. package/dist/sync/pnl-history.d.ts.map +1 -0
  36. package/dist/sync/pnl-history.js +617 -0
  37. package/dist/sync/pnl-history.js.map +1 -0
  38. package/dist/sync/stream.d.ts +101 -0
  39. package/dist/sync/stream.d.ts.map +1 -0
  40. package/dist/sync/stream.js +243 -0
  41. package/dist/sync/stream.js.map +1 -0
  42. package/dist/transport/rest.d.ts +36 -4
  43. package/dist/transport/rest.d.ts.map +1 -1
  44. package/dist/transport/rest.js +43 -10
  45. package/dist/transport/rest.js.map +1 -1
  46. package/dist/transport/ws.d.ts +5 -1
  47. package/dist/transport/ws.d.ts.map +1 -1
  48. package/dist/transport/ws.js.map +1 -1
  49. package/dist/types/public.d.ts +62 -23
  50. package/dist/types/public.d.ts.map +1 -1
  51. package/dist/types/wire.d.ts +98 -16
  52. package/dist/types/wire.d.ts.map +1 -1
  53. package/dist/write/index.d.ts +3 -3
  54. package/dist/write/index.d.ts.map +1 -1
  55. package/dist/write/index.js +0 -3
  56. package/dist/write/index.js.map +1 -1
  57. package/package.json +1 -1
  58. package/src/client.ts +54 -7
  59. package/src/codec/activity.ts +46 -0
  60. package/src/codec/decode.ts +65 -30
  61. package/src/codec/orders-v2.ts +24 -11
  62. package/src/index.ts +7 -1
  63. package/src/sync/activity.ts +266 -0
  64. package/src/sync/order-preview.ts +63 -0
  65. package/src/sync/orders.ts +41 -187
  66. package/src/sync/pnl-history.ts +639 -0
  67. package/src/sync/stream.ts +270 -0
  68. package/src/transport/rest.ts +62 -14
  69. package/src/transport/ws.ts +5 -1
  70. package/src/types/public.ts +62 -26
  71. package/src/types/wire.ts +105 -18
  72. package/src/write/index.ts +3 -6
@@ -6,6 +6,7 @@
6
6
  // available_margin = withdrawable_cash (free cross margin)
7
7
  // max_notional = available_margin / initial_margin_rate (≈ available · max_leverage)
8
8
  // implied_leverage = (Σ current perp notional + notional) / perps_equity
9
+ // liquidation = mark where equity falls to Σ maintenance margin (im/2)
9
10
 
10
11
  import type { Market, PerpPosition, PositionsSnapshot, Trigger } from "../types/public.js";
11
12
  import { div, imRate, mul } from "../codec/fixed.js";
@@ -87,6 +88,67 @@ export interface OrderPreview {
87
88
  sufficientMargin: boolean;
88
89
  /** Estimated fee = notional · fee rate (taker for market, maker for limit). */
89
90
  estimatedFee: bigint;
91
+ /** Mark at which the account is liquidated once this order fills; undefined
92
+ * when this market's mark alone can never trigger one. */
93
+ liquidationPrice?: bigint;
94
+ }
95
+
96
+ const absB = (x: bigint) => (x < 0n ? -x : x);
97
+ const maxB = (a: bigint, b: bigint) => (a > b ? a : b);
98
+
99
+ /**
100
+ * Mark at which the account is liquidated once an order for signed `size` fills
101
+ * at `price`. Margin is cross, so this is an account-level number in one
102
+ * market's mark: the engine liquidates at `perps_equity < Σ maintenance margin`,
103
+ * and both sides are linear in this market's mark X (others held still) —
104
+ *
105
+ * equity(X) = equity_now + (X − mark)·size_existing + (X − price)·size
106
+ * mm(X) = mm_other + |size_total|·X·mm_rate
107
+ * root = (mm_other − C) / (size_total − |size_total|·mm_rate),
108
+ * C = equity_now − mark·size_existing − price·size
109
+ *
110
+ * Undefined when no such mark exists (spot, flat after the fill, or a root at or
111
+ * below zero), or when `maintenanceMargin` is absent while perps elsewhere need
112
+ * it — one `market` cannot supply their rates, and `enrichPositions` sets the
113
+ * field. Prices the fill only: fees and funding shift the real number.
114
+ */
115
+ function liquidationPriceAfter(
116
+ snap: PositionsSnapshot,
117
+ market: Market,
118
+ size: bigint,
119
+ price: bigint,
120
+ ): bigint | undefined {
121
+ if (market.type !== "perp") return undefined;
122
+ const mmRate = imRate(market.maxLeverage) / 2n; // mm = im/2, as in enrichPositions
123
+ if (mmRate <= 0n) return undefined;
124
+
125
+ // Split the book: this market's perps move with X, every other one is constant.
126
+ let sizeExisting = 0n;
127
+ let markedExisting = 0n; // Σ mark·size here — the uPnL already in equity_now
128
+ let mmHere = 0n;
129
+ let mmElsewhere = false;
130
+ for (const p of snap.positions) {
131
+ if (p.kind !== "perp" || p.size === 0n) continue;
132
+ if (p.orderbookId === market.id) {
133
+ sizeExisting += p.size;
134
+ markedExisting += mul(p.markPrice, p.size);
135
+ mmHere += mul(mul(absB(p.size), p.markPrice), mmRate);
136
+ } else {
137
+ mmElsewhere = true;
138
+ }
139
+ }
140
+ if (snap.maintenanceMargin === undefined && mmElsewhere) return undefined;
141
+ const mmOther = snap.maintenanceMargin === undefined
142
+ ? 0n
143
+ : maxB(0n, snap.maintenanceMargin - mmHere);
144
+
145
+ const sizeTotal = sizeExisting + size;
146
+ const denom = sizeTotal - mul(absB(sizeTotal), mmRate);
147
+ if (denom === 0n) return undefined; // flat after the fill
148
+
149
+ const c = snap.perpsEquity - markedExisting - mul(price, size);
150
+ const liq = div(mmOther - c, denom);
151
+ return liq > 0n ? liq : undefined;
90
152
  }
91
153
 
92
154
  export function previewOrder(
@@ -124,6 +186,7 @@ export function previewOrder(
124
186
  impliedLeverage,
125
187
  sufficientMargin: marginRequired <= availableMargin,
126
188
  estimatedFee: mul(notional, input.orderType === "limit" ? market.makerFee : market.takerFee),
189
+ liquidationPrice: liquidationPriceAfter(snap, market, size, input.price),
127
190
  };
128
191
  }
129
192
 
@@ -1,109 +1,47 @@
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
8
  import { BaseResource, type ResourceHandle } from "../stores/resource.js";
16
- import { PodSubscriptionClosedError, type SubParams, type Subscription } from "../transport/ws.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 = {},
95
32
  ) {
33
+ this.stream = new ResumableStream({
34
+ ws: ctx.ws,
35
+ channel: "pod_orders_v2",
36
+ params: { account },
37
+ reseed: () => this.fetchFirstPage(),
38
+ onFrame: (r) => this.onFrame(r),
39
+ });
96
40
  this.base = new BaseResource<Order[]>((h) => {
97
41
  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)
42
+ this.stream.start();
101
43
  return () => {
102
- this.alive = false;
103
- offOpen();
104
- if (this.retryTimer) clearTimeout(this.retryTimer);
105
- this.sub?.unsubscribe();
106
- this.sub = undefined;
44
+ this.stream.stop();
107
45
  this.handle = undefined;
108
46
  };
109
47
  });
@@ -160,143 +98,59 @@ export class OrderHistory implements SeriesResource<Order> {
160
98
  // --- internals ---
161
99
 
162
100
  private async fetchFirstPage(): Promise<boolean> {
163
- const before = this.cursor;
101
+ const gen = ++this.seedGen;
102
+ const before = this.stream.cursor;
164
103
  try {
165
104
  const page = await this.ctx.rest.orders(this.account, { limit: this.query.limit ?? 100 });
166
- if (!this.alive) return false;
105
+ // A seed overtaken by a fresher one is dropped whole: it would absorb rows the
106
+ // newer page has already corrected, and raise the cursor to an older watermark.
107
+ if (!this.stream.running || gen !== this.seedGen) return false;
167
108
  // The transport resubscribes synchronously right after the `open` event that
168
109
  // starts this fetch, so replayed frames can land while it is still in flight —
169
110
  // 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;
111
+ // already advanced would revert it, permanently: the cursor refuses to rewind
112
+ // and `onFrame` drops a re-delivery, so nothing would repair it.
113
+ const streamMovedOn = compareCursor(this.stream.cursor, before) > 0;
173
114
  for (const o of page.orders) {
174
115
  if (streamMovedOn && this.byId.has(o.id)) continue;
175
116
  this.byId.set(o.id, o);
176
117
  }
177
- this.nextCursor = page.nextCursor;
178
- this._hasMore = page.nextCursor !== null;
118
+ // Paging is the consumer's position in history, not the seed's: a reconnect
119
+ // re-paints the first page, and taking its cursor again would hand back pages
120
+ // `loadOlder` has already walked past.
121
+ if (!this.painted) {
122
+ this.painted = true;
123
+ this.nextCursor = page.nextCursor;
124
+ this._hasMore = page.nextCursor !== null;
125
+ }
179
126
  // Only ever forward, and a page settles whole batches, so its watermark
180
127
  // carries no book — which makes it *ahead* of a stream position in the same
181
128
  // 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;
129
+ this.stream.raise({ since: page.solutionNow * 1000, sinceBook: undefined });
184
130
  this.rebuild();
185
131
  return true;
186
132
  } catch (e) {
187
- if (this.byId.size === 0) this.handle?.fail(e as Error);
188
- return false;
189
- }
190
- }
191
-
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;
133
+ // Only before the first paint: an account whose history is genuinely empty has
134
+ // a resource, and reporting a later transient failure on it would blank the view.
135
+ if (this.handle && this.handle.current() === undefined) this.handle.fail(e as Error);
136
+ throw e;
242
137
  }
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
138
  }
279
139
 
280
140
  /** One frame: everything that happened to one book in one auction batch. */
281
141
  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
142
  const frame = result as WireOrdersFrame;
286
143
  if (!frame || !Array.isArray(frame.orders) || !Array.isArray(frame.events)) return;
287
144
 
288
145
  // Drop what we already hold. Applying a frame is not idempotent — a fill event
289
146
  // appends to `order.fills`, and re-creating an entity resets its totals — and
290
147
  // 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.
148
+ // the replay boundary is a whole batch.
293
149
  const at: SubParams = { since: frame.batch, sinceBook: frame.book };
294
- if (compareCursor(at, this.cursor) <= 0) return;
150
+ if (this.stream.delivered(at)) return;
295
151
 
296
152
  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);
153
+ this.stream.advance(at);
300
154
  this.rebuild();
301
155
  // Strictly after `rebuild()`: a listener that reads the resource in response to an
302
156
  // event must see the state that event produced, not the state before it.