@pod-network/trade-sdk 0.17.0 → 0.19.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 (77) hide show
  1. package/README.md +15 -0
  2. package/dist/client.d.ts +23 -0
  3. package/dist/client.d.ts.map +1 -1
  4. package/dist/client.js +32 -5
  5. package/dist/client.js.map +1 -1
  6. package/dist/codec/activity.d.ts +4 -9
  7. package/dist/codec/activity.d.ts.map +1 -1
  8. package/dist/codec/activity.js +6 -23
  9. package/dist/codec/activity.js.map +1 -1
  10. package/dist/codec/bridge.d.ts +24 -0
  11. package/dist/codec/bridge.d.ts.map +1 -1
  12. package/dist/codec/bridge.js +21 -0
  13. package/dist/codec/bridge.js.map +1 -1
  14. package/dist/index.d.ts +2 -2
  15. package/dist/index.d.ts.map +1 -1
  16. package/dist/index.js +2 -2
  17. package/dist/index.js.map +1 -1
  18. package/dist/stores/resource.d.ts +9 -3
  19. package/dist/stores/resource.d.ts.map +1 -1
  20. package/dist/stores/resource.js +6 -1
  21. package/dist/stores/resource.js.map +1 -1
  22. package/dist/sync/activity.d.ts +11 -2
  23. package/dist/sync/activity.d.ts.map +1 -1
  24. package/dist/sync/activity.js +74 -18
  25. package/dist/sync/activity.js.map +1 -1
  26. package/dist/sync/candles.d.ts.map +1 -1
  27. package/dist/sync/candles.js +6 -0
  28. package/dist/sync/candles.js.map +1 -1
  29. package/dist/sync/order-ledger.d.ts +42 -0
  30. package/dist/sync/order-ledger.d.ts.map +1 -0
  31. package/dist/sync/order-ledger.js +163 -0
  32. package/dist/sync/order-ledger.js.map +1 -0
  33. package/dist/sync/order-preview.d.ts.map +1 -1
  34. package/dist/sync/order-preview.js +5 -1
  35. package/dist/sync/order-preview.js.map +1 -1
  36. package/dist/sync/orders.d.ts +5 -1
  37. package/dist/sync/orders.d.ts.map +1 -1
  38. package/dist/sync/orders.js +41 -16
  39. package/dist/sync/orders.js.map +1 -1
  40. package/dist/sync/positions-live.d.ts.map +1 -1
  41. package/dist/sync/positions-live.js +33 -7
  42. package/dist/sync/positions-live.js.map +1 -1
  43. package/dist/sync/sources.d.ts +3 -1
  44. package/dist/sync/sources.d.ts.map +1 -1
  45. package/dist/sync/sources.js +21 -9
  46. package/dist/sync/sources.js.map +1 -1
  47. package/dist/sync/withdrawals.d.ts +1 -1
  48. package/dist/sync/withdrawals.d.ts.map +1 -1
  49. package/dist/sync/withdrawals.js +15 -6
  50. package/dist/sync/withdrawals.js.map +1 -1
  51. package/dist/transport/claim.d.ts +15 -0
  52. package/dist/transport/claim.d.ts.map +1 -1
  53. package/dist/transport/claim.js +39 -1
  54. package/dist/transport/claim.js.map +1 -1
  55. package/dist/transport/rest.d.ts +5 -0
  56. package/dist/transport/rest.d.ts.map +1 -1
  57. package/dist/transport/rest.js +3 -0
  58. package/dist/transport/rest.js.map +1 -1
  59. package/dist/types/public.d.ts +4 -0
  60. package/dist/types/public.d.ts.map +1 -1
  61. package/package.json +1 -1
  62. package/src/client.ts +39 -5
  63. package/src/codec/activity.ts +5 -22
  64. package/src/codec/bridge.ts +37 -0
  65. package/src/index.ts +2 -1
  66. package/src/stores/resource.ts +13 -4
  67. package/src/sync/activity.ts +78 -20
  68. package/src/sync/candles.ts +5 -0
  69. package/src/sync/order-ledger.ts +157 -0
  70. package/src/sync/order-preview.ts +5 -1
  71. package/src/sync/orders.ts +39 -14
  72. package/src/sync/positions-live.ts +32 -7
  73. package/src/sync/sources.ts +22 -8
  74. package/src/sync/withdrawals.ts +15 -6
  75. package/src/transport/claim.ts +44 -1
  76. package/src/transport/rest.ts +8 -0
  77. package/src/types/public.ts +4 -0
@@ -1,15 +1,17 @@
1
1
  // `pod_activity` sends one batch per tick, so the batch alone is the resume cursor (ADR 0057).
2
2
 
3
3
  import type {
4
- ActivityEntry, ActivityEvent, ActivityQuery, ActivityType, Address, Order, OrderEventKind,
4
+ ActivityEntry, ActivityEvent, ActivityQuery, ActivityType, Address, OrderEventKind,
5
5
  } from "../types/public.js";
6
6
  import type { WireActivityEntry } from "../types/wire.js";
7
- import { foldActivityBatch } from "../codec/activity.js";
8
- import { msToUs } from "../codec/units.js";
7
+ import { decodeActivityEntry, foldActivityBatch } from "../codec/activity.js";
8
+ import { decodeOrder } from "../codec/decode.js";
9
+ import { msToUs, usToMs } from "../codec/units.js";
9
10
  import { BaseResource, type ResourceHandle } from "../stores/resource.js";
10
11
  import type { ActivityPage } from "../transport/rest.js";
11
12
  import type { SubParams } from "../transport/ws.js";
12
13
  import type { SeriesResource } from "./candles.js";
14
+ import { OrderLedger, readActivityAfter } from "./order-ledger.js";
13
15
  import { readAtLeast, type SyncContext } from "./sources.js";
14
16
  import { ResumableStream } from "./stream.js";
15
17
 
@@ -23,7 +25,10 @@ export class ActivityHistory implements ActivityView {
23
25
  private handle: ResourceHandle<ActivityEntry[]> | undefined;
24
26
  /** Every batch's rows, from either source; what dedupes one against the other. */
25
27
  private readonly batches = new Map<number, ActivityEntry[]>();
26
- private readonly orders = new Map<string, Order>();
28
+ private readonly ledger = new OrderLedger<[number, WireActivityEntry[]], { rows: ActivityEntry[]; events: ActivityEvent[] }>(
29
+ ([batchUs, entries], orders) => foldActivityBatch(batchUs, entries, orders),
30
+ );
31
+ private reconciling = false;
27
32
  private rows: ActivityEntry[] = [];
28
33
  private nextUs: number | null = null;
29
34
  private seedGen = 0;
@@ -47,7 +52,9 @@ export class ActivityHistory implements ActivityView {
47
52
  this.base = new BaseResource<ActivityEntry[]>((h) => {
48
53
  this.handle = h;
49
54
  this.stream.start();
55
+ const timer = ctx.historyResyncMs > 0 ? setInterval(() => void this.reconcile(), ctx.historyResyncMs) : undefined;
50
56
  return () => {
57
+ clearInterval(timer);
51
58
  this.stream.stop();
52
59
  this.handle = undefined;
53
60
  };
@@ -93,9 +100,9 @@ export class ActivityHistory implements ActivityView {
93
100
  const toUs = this.nextUs;
94
101
  const page = await readAtLeast(
95
102
  (min) => this.ctx.rest.activity(this.account, { toUs }, min),
96
- this.stream.cursor.since,
103
+ this.minimum(),
97
104
  );
98
- this.store([page]);
105
+ if (!this.store([page])) return;
99
106
  this.nextUs = page.nextUs;
100
107
  this._hasMore = page.nextUs !== null;
101
108
  this.restack();
@@ -113,7 +120,8 @@ export class ActivityHistory implements ActivityView {
113
120
  if (since === undefined) {
114
121
  const page = await this.ctx.rest.activity(this.account);
115
122
  if (stale()) return false;
116
- this.store([page]);
123
+ if (!this.store([page])) throw new Error("activity read below the held frames");
124
+ this.ledger.stampUs ||= page.solutionNowUs;
117
125
  this.nextUs = page.nextUs;
118
126
  this._hasMore = page.nextUs !== null;
119
127
  this.restack();
@@ -125,12 +133,15 @@ export class ActivityHistory implements ActivityView {
125
133
  let toUs: number | undefined;
126
134
  const pages: ActivityPage[] = [];
127
135
  do {
128
- const page = await readAtLeast((min) => this.ctx.rest.activity(this.account, { fromUs, toUs }, min), since);
136
+ const page = await readAtLeast(
137
+ (min) => this.ctx.rest.activity(this.account, { fromUs, toUs }, min),
138
+ Math.max(since, this.ledger.minimum()),
139
+ );
129
140
  if (stale()) return false;
130
141
  pages.push(page);
131
142
  toUs = page.nextUs ?? undefined;
132
143
  } while (toUs !== undefined);
133
- this.store(pages);
144
+ if (!this.store(pages)) throw new Error("activity read below the held frames");
134
145
  this.restack();
135
146
  for (const page of pages) this.stream.raise({ since: msToUs(page.solutionNow) });
136
147
  return true;
@@ -142,12 +153,51 @@ export class ActivityHistory implements ActivityView {
142
153
  }
143
154
  }
144
155
 
145
- /** Oldest batch first, so transitions to held orders land in order; a batch already held is skipped. */
146
- private store(pages: ActivityPage[]): void {
147
- const fresh = pages.flatMap((p) => p.batches).filter(([batchUs]) => !this.batches.has(batchUs));
148
- const pageOrders = new Set(fresh.flatMap(([, entries]) => entries.flatMap((e) => (e.k === "order" ? [e.order_id] : []))));
156
+ /**
157
+ * A page's `order` rows are each order's state at the page's read; its batches are
158
+ * folded like frames, so the ledger skips the orders those rows already cover.
159
+ */
160
+ private store(pages: ActivityPage[]): boolean {
161
+ const kept = pages.filter((p) => this.ledger.rows(
162
+ p.batches.flatMap(([, entries]) => entries.flatMap((e) => (e.k === "order" ? [decodeOrder(e)] : []))),
163
+ p.solutionNowUs,
164
+ ));
165
+ const fresh = kept.flatMap((p) => p.batches).filter(([batchUs]) => !this.batches.has(batchUs));
149
166
  for (const [batchUs, entries] of fresh.sort((a, b) => a[0] - b[0])) {
150
- this.batches.set(batchUs, foldActivityBatch(batchUs, entries, this.orders, { pageOrders }).rows);
167
+ this.batches.set(batchUs, this.shown(this.ledger.live(batchUs, [batchUs, entries]).rows));
168
+ }
169
+ return kept.length === pages.length;
170
+ }
171
+
172
+ /** Point `order` rows at the ledger's order, which later transitions and reconciles update in place. */
173
+ private shown(rows: ActivityEntry[]): ActivityEntry[] {
174
+ for (const row of rows) {
175
+ if (row.activityType === "order") row.order = this.ledger.view.get(row.order.id) ?? row.order;
176
+ }
177
+ return rows;
178
+ }
179
+
180
+ private minimum(): number | undefined {
181
+ return Math.max(this.stream.cursor.since ?? 0, this.ledger.minimum()) || undefined;
182
+ }
183
+
184
+ /** Activity since the last reconcile: adds the batches the stream lost and corrects the orders. */
185
+ private async reconcile(): Promise<void> {
186
+ if (this.reconciling || !this.ledger.stampUs || !this.stream.running) return;
187
+ this.reconciling = true;
188
+ try {
189
+ const pages = await readActivityAfter(this.ctx.rest, this.account, this.ledger.stampUs, this.ledger.minimum());
190
+ if (!this.stream.running || !this.ledger.reconcile(pages)) return;
191
+ const fresh = pages.flatMap((p) => p.batches).filter(([batchUs]) => !this.batches.has(batchUs));
192
+ for (const [batchUs, entries] of fresh) {
193
+ const rows = entries.flatMap((e) => decodeActivityEntry(e, usToMs(batchUs)) ?? []);
194
+ this.batches.set(batchUs, this.shown(rows));
195
+ }
196
+ this.restack();
197
+ } catch {
198
+ // The next interval asks again.
199
+ } finally {
200
+ this.reconciling = false;
151
201
  }
152
202
  }
153
203
 
@@ -163,12 +213,20 @@ export class ActivityHistory implements ActivityView {
163
213
  const at: SubParams = { since: batchUs };
164
214
  if (this.stream.delivered(at)) return;
165
215
  this.stream.advance(at);
166
- if (!entries.length || this.batches.has(batchUs)) return;
167
- const { rows, events } = foldActivityBatch(batchUs, entries as WireActivityEntry[], this.orders, "stream");
168
- this.batches.set(batchUs, rows);
169
- this.rows = [...rows, ...this.rows];
170
- // Listeners run after rebuild() so one that reads the resource sees what the event produced.
171
- this.rebuild();
216
+ if (!entries.length) return;
217
+ const frame: [number, WireActivityEntry[]] = [batchUs, entries as WireActivityEntry[]];
218
+ let events: ActivityEvent[];
219
+ if (this.batches.has(batchUs)) {
220
+ // A REST read already applied this batch; the app still hears about it.
221
+ events = this.ledger.report(frame).events;
222
+ } else {
223
+ const folded = this.ledger.live(batchUs, frame);
224
+ events = folded.events;
225
+ this.batches.set(batchUs, this.shown(folded.rows));
226
+ this.rows = [...folded.rows, ...this.rows];
227
+ // Listeners run after rebuild() so one that reads the resource sees what the event produced.
228
+ this.rebuild();
229
+ }
172
230
  if (events.length) {
173
231
  for (const listener of this.eventListeners) {
174
232
  try { listener(events); } catch { /* a listener's failure is not the stream's */ }
@@ -358,9 +358,14 @@ export class CandleSeries implements SeriesResource<Bar> {
358
358
  // On reconnect, refresh closed bars (the WS auto-resubscribes pod_candles
359
359
  // itself with the advanced `since`).
360
360
  const offOpen = this.ctx.ws.on("open", () => { if (this.alive) void this.loadWindow(this.window); });
361
+ // The trailing page is re-read each time; a page read before its last bars closed is not (CORE-508).
362
+ const timer = this.ctx.historyResyncMs > 0
363
+ ? setInterval(() => { if (this.alive) void this.loadWindow(this.window); }, this.ctx.historyResyncMs)
364
+ : undefined;
361
365
  return () => {
362
366
  this.alive = false;
363
367
  offOpen();
368
+ clearInterval(timer);
364
369
  if (this.retryTimer) clearTimeout(this.retryTimer);
365
370
  this.tickSub?.unsubscribe();
366
371
  this.tickSub = undefined;
@@ -0,0 +1,157 @@
1
+ // Order state built from REST reads, with the stream frames above them replayed on top.
2
+ //
3
+ // `base` holds each order as a REST read reported it, with the tick it was read at.
4
+ // `frames` holds the stream frames above `stampUs`, the tick activity has been
5
+ // reconciled to. `view` is what consumers see: `base` with `frames` replayed, kept
6
+ // current frame by frame in between.
7
+
8
+ import type { ActivityType, Address, Order } from "../types/public.js";
9
+ import type { ActivityPage, PodRestClient } from "../transport/rest.js";
10
+ import { decodeOrder } from "../codec/decode.js";
11
+ import { asOrderEvent } from "../codec/activity.js";
12
+ import { applyEvent } from "../codec/orders-v2.js";
13
+ import { usToMs } from "../codec/units.js";
14
+ import { readAtLeast } from "./sources.js";
15
+
16
+ const MAX_FRAMES = 1_024;
17
+
18
+ export class OrderLedger<F, E> {
19
+ readonly view = new Map<string, Order>();
20
+ /** Activity has been reconciled up to this tick. */
21
+ stampUs = 0;
22
+ private readonly base = new Map<string, { order: Order; atUs: number }>();
23
+ private frames: Array<[number, F]> = [];
24
+ private floorUs = 0;
25
+ private newestRowUs = 0;
26
+
27
+ constructor(private readonly fold: (frame: F, orders: Map<string, Order>) => E) {}
28
+
29
+ /** The lowest stamp a reconcile may answer at without a hole under the held frames. */
30
+ minimum(): number {
31
+ return Math.max(this.stampUs, this.floorUs);
32
+ }
33
+
34
+ /**
35
+ * Apply a stream frame to `view`, and hold it for replay. An order a REST read already
36
+ * has at `us` keeps that state, but the frame still reports its events on a copy.
37
+ */
38
+ live(us: number, frame: F): E {
39
+ const result = this.foldPast(us, frame, this.view);
40
+ if (us > this.stampUs) {
41
+ let i = this.frames.length;
42
+ while (i > 0 && this.frames[i - 1]![0] > us) i--;
43
+ this.frames.splice(i, 0, [us, frame]);
44
+ if (this.frames.length > MAX_FRAMES) this.floorUs = this.frames.shift()![0];
45
+ }
46
+ return result;
47
+ }
48
+
49
+ /**
50
+ * Fold a frame whose batch a REST read already applied: its events, on a copy of the view.
51
+ */
52
+ report(frame: F): E {
53
+ return this.fold(frame, new Map([...this.view].map(([id, order]) => [id, { ...order }])));
54
+ }
55
+
56
+ /**
57
+ * Orders a REST read reported at `atUs`; a held order read later is kept. `false`, with
58
+ * nothing taken, when `atUs` is below the evicted frames the rows would need.
59
+ */
60
+ rows(orders: Order[], atUs: number): boolean {
61
+ if (atUs < this.floorUs) return false;
62
+ const taken: string[] = [];
63
+ for (const order of orders) {
64
+ const held = this.base.get(order.id);
65
+ if (held && held.atUs > atUs) continue;
66
+ this.base.set(order.id, { order, atUs });
67
+ taken.push(order.id);
68
+ }
69
+ this.newestRowUs = Math.max(this.newestRowUs, atUs);
70
+ const scratch = new Map<string, Order>();
71
+ this.replay(taken, scratch);
72
+ for (const id of taken) this.put(id, scratch.get(id)!);
73
+ return true;
74
+ }
75
+
76
+ /**
77
+ * Apply activity read from `stampUs` up to R, the newest page's stamp, then move the
78
+ * stamp to R and replay the frames above it. `false` when R is below `minimum()`.
79
+ */
80
+ reconcile(pages: ActivityPage[]): boolean {
81
+ const r = pages[0]?.solutionNowUs;
82
+ if (r === undefined || r < this.minimum()) return false;
83
+ const batches = pages
84
+ .flatMap((p) => p.batches.map(([batchUs, entries]) => ({ batchUs, entries, atUs: p.solutionNowUs })))
85
+ .sort((a, b) => a.batchUs - b.batchUs);
86
+ for (const { batchUs, entries, atUs } of batches) {
87
+ for (const e of entries) {
88
+ if (e.k === "order") {
89
+ const held = this.base.get(e.order_id);
90
+ if (!held || held.atUs <= atUs) this.base.set(e.order_id, { order: decodeOrder(e), atUs });
91
+ this.newestRowUs = Math.max(this.newestRowUs, atUs);
92
+ continue;
93
+ }
94
+ const event = asOrderEvent(e);
95
+ if (!event?.id) continue;
96
+ const held = this.base.get(event.id);
97
+ if (held && batchUs > held.atUs) applyEvent(event, held.order, { batchMs: usToMs(batchUs) });
98
+ }
99
+ }
100
+ for (const held of this.base.values()) held.atUs = Math.max(held.atUs, r);
101
+ this.newestRowUs = Math.max(this.newestRowUs, r);
102
+ this.stampUs = r;
103
+ this.frames = this.frames.filter(([us]) => us > r);
104
+ if (this.floorUs <= r) this.floorUs = 0;
105
+
106
+ const fresh = new Map<string, Order>();
107
+ this.replay(this.base.keys(), fresh);
108
+ // Orders only the stream knows keep their streamed state.
109
+ for (const [id, order] of fresh) this.put(id, order);
110
+ return true;
111
+ }
112
+
113
+ private replay(ids: Iterable<string>, into: Map<string, Order>): void {
114
+ for (const id of ids) into.set(id, { ...this.base.get(id)!.order });
115
+ for (const [us, frame] of this.frames) this.foldPast(us, frame, into);
116
+ }
117
+
118
+ /** Fold `frame` into `orders`; the orders whose REST state is at or past `us` take it on a copy that is thrown away. */
119
+ private foldPast(us: number, frame: F, orders: Map<string, Order>): E {
120
+ if (us > this.newestRowUs) return this.fold(frame, orders);
121
+ const hidden: Order[] = [];
122
+ for (const [id, order] of orders) {
123
+ const held = this.base.get(id);
124
+ if (held && held.atUs >= us) { hidden.push(order); orders.set(id, { ...order }); }
125
+ }
126
+ const result = this.fold(frame, orders);
127
+ for (const order of hidden) orders.set(order.id, order);
128
+ return result;
129
+ }
130
+
131
+ /** Overwrite in place: activity rows hold the view's order objects. */
132
+ private put(id: string, order: Order): void {
133
+ const shown = this.view.get(id);
134
+ if (!shown) { this.view.set(id, order); return; }
135
+ if (shown === order) return;
136
+ for (const key of Object.keys(shown)) delete (shown as unknown as Record<string, unknown>)[key];
137
+ Object.assign(shown, order);
138
+ }
139
+ }
140
+
141
+ /** Activity from `fromUs` (exclusive) to the newest tick, every page, newest first. */
142
+ export async function readActivityAfter(
143
+ rest: PodRestClient,
144
+ account: Address,
145
+ fromUs: number,
146
+ minUs: number,
147
+ types?: ActivityType[],
148
+ ): Promise<ActivityPage[]> {
149
+ const pages: ActivityPage[] = [];
150
+ let toUs: number | undefined;
151
+ do {
152
+ const page = await readAtLeast((min) => rest.activity(account, { types, fromUs: fromUs + 1, toUs }, min), minUs);
153
+ pages.push(page);
154
+ toUs = page.nextUs ?? undefined;
155
+ } while (toUs !== undefined);
156
+ return pages;
157
+ }
@@ -159,7 +159,11 @@ export function previewOrder(
159
159
  // Spot has no leverage: the order locks the full notional in cash (im = 1.0).
160
160
  // Perps use the market's initial-margin rate (1 / max_leverage).
161
161
  const im = market.type === "spot" ? WAD : imRate(market.maxLeverage);
162
- const availableMargin = snap.withdrawableCash;
162
+ // Opening is funded by equity over initial margin; withdrawable also nets the
163
+ // node's notional floor and is stricter. A raw REST snapshot lacks the sum.
164
+ const availableMargin = snap.initialMargin === undefined
165
+ ? snap.withdrawableCash
166
+ : maxB(0n, snap.perpsEquity - snap.initialMargin);
163
167
  // An inverse, so it stays on the requested basis: callers clamp the request with it.
164
168
  const maxNotional = im > 0n ? div(availableMargin, im) : 0n;
165
169
 
@@ -2,21 +2,25 @@
2
2
  // live by the pod_orders_v2 stream (bidder-filtered, resumed from a (batch, book)
3
3
  // cursor by `ResumableStream`), and paged backwards by cursor for deep history.
4
4
 
5
- import type { Address, Order, OrderEvent, OrdersQuery } from "../types/public.js";
5
+ import type { ActivityType, Address, Order, OrderEvent, OrdersQuery } from "../types/public.js";
6
6
  import type { WireOrdersFrame } from "../types/wire.js";
7
7
  import { applyOrdersFrame } from "../codec/orders-v2.js";
8
8
  import { BaseResource, type ResourceHandle, type Snapshot, type SnapshotSlot } from "../stores/resource.js";
9
9
  import type { SubParams } from "../transport/ws.js";
10
10
  import type { SeriesResource } from "./candles.js";
11
+ import { OrderLedger, readActivityAfter } from "./order-ledger.js";
11
12
  import { readAtLeast, type SyncContext } from "./sources.js";
12
- import { compareCursor, ResumableStream } from "./stream.js";
13
+ import { ResumableStream } from "./stream.js";
13
14
 
14
15
  export { compareCursor } from "./stream.js";
15
16
 
17
+ const ORDER_ACTIVITY: ActivityType[] = ["order", "fill", "modify", "termination"];
18
+
16
19
  export class OrderHistory implements SeriesResource<Order> {
17
20
  private readonly base: BaseResource<Order[]>;
18
21
  private handle: ResourceHandle<Order[]> | undefined;
19
- private readonly byId = new Map<string, Order>();
22
+ private readonly ledger: OrderLedger<WireOrdersFrame, OrderEvent[]>;
23
+ private reconciling = false;
20
24
  private nextCursor: string | null = null;
21
25
  private painted = false;
22
26
  private seedGen = 0;
@@ -31,6 +35,7 @@ export class OrderHistory implements SeriesResource<Order> {
31
35
  private readonly query: OrdersQuery = {},
32
36
  slot?: SnapshotSlot,
33
37
  ) {
38
+ this.ledger = new OrderLedger((frame, orders) => applyOrdersFrame(frame, orders, { account }));
34
39
  this.stream = new ResumableStream({
35
40
  ws: ctx.ws,
36
41
  channel: "pod_orders_v2",
@@ -41,7 +46,9 @@ export class OrderHistory implements SeriesResource<Order> {
41
46
  this.base = new BaseResource<Order[]>((h) => {
42
47
  this.handle = h;
43
48
  this.stream.start();
49
+ const timer = ctx.historyResyncMs > 0 ? setInterval(() => void this.reconcile(), ctx.historyResyncMs) : undefined;
44
50
  return () => {
51
+ clearInterval(timer);
45
52
  this.stream.stop();
46
53
  this.handle = undefined;
47
54
  };
@@ -89,8 +96,8 @@ export class OrderHistory implements SeriesResource<Order> {
89
96
  const page = await readAtLeast((min) => this.ctx.rest.orders(this.account, {
90
97
  cursor,
91
98
  limit: this.query.limit ?? 100,
92
- }, min), this.stream.cursor.since);
93
- for (const o of page.orders) if (!this.byId.has(o.id)) this.byId.set(o.id, o);
99
+ }, min), this.minimum());
100
+ if (!this.ledger.rows(page.orders, page.solutionNowUs)) return;
94
101
  this.nextCursor = page.nextCursor;
95
102
  this._hasMore = page.nextCursor !== null;
96
103
  } finally {
@@ -106,18 +113,16 @@ export class OrderHistory implements SeriesResource<Order> {
106
113
  try {
107
114
  const page = await readAtLeast(
108
115
  (min) => this.ctx.rest.orders(this.account, { limit: this.query.limit ?? 100 }, min),
109
- this.stream.cursor.since,
116
+ this.minimum(),
110
117
  );
111
118
  // A seed overtaken by a fresher one is dropped whole: it would absorb rows the
112
119
  // newer page has already corrected, and raise the cursor to an older watermark.
113
120
  if (!this.stream.running || gen !== this.seedGen) return false;
114
121
  const settled: SubParams = { since: page.solutionNow * 1000, sinceBook: undefined };
115
- // A page settled behind the stream would revert rows the stream advanced.
116
- const stale = compareCursor(this.stream.cursor, settled) > 0;
117
- for (const o of page.orders) {
118
- if (stale && this.byId.has(o.id)) continue;
119
- this.byId.set(o.id, o);
120
- }
122
+ if (!this.ledger.rows(page.orders, page.solutionNowUs)) throw new Error("orders read below the held frames");
123
+ // A reconnect: the stream may have missed frames for orders this page does not hold.
124
+ if (this.painted) void this.reconcile();
125
+ else this.ledger.stampUs ||= page.solutionNowUs;
121
126
  // Paging is the consumer's position in history, not the seed's: a reconnect
122
127
  // re-paints the first page, and taking its cursor again would hand back pages
123
128
  // `loadOlder` has already walked past.
@@ -152,7 +157,7 @@ export class OrderHistory implements SeriesResource<Order> {
152
157
  const at: SubParams = { since: frame.batch, sinceBook: frame.book };
153
158
  if (this.stream.delivered(at)) return;
154
159
 
155
- const events = applyOrdersFrame(frame, this.byId, { account: this.account });
160
+ const events = this.ledger.live(frame.batch, frame);
156
161
  this.stream.advance(at);
157
162
  this.rebuild();
158
163
  // Strictly after `rebuild()`: a listener that reads the resource in response to an
@@ -164,9 +169,29 @@ export class OrderHistory implements SeriesResource<Order> {
164
169
  }
165
170
  }
166
171
 
172
+ /** The lowest round a read may answer at: past the stream, and past the reconcile so no order misses a transition. */
173
+ private minimum(): number | undefined {
174
+ return Math.max(this.stream.cursor.since ?? 0, this.ledger.minimum()) || undefined;
175
+ }
176
+
177
+ private async reconcile(): Promise<void> {
178
+ if (this.reconciling || !this.painted || !this.stream.running) return;
179
+ this.reconciling = true;
180
+ try {
181
+ const pages = await readActivityAfter(
182
+ this.ctx.rest, this.account, this.ledger.stampUs, this.ledger.minimum(), ORDER_ACTIVITY,
183
+ );
184
+ if (this.stream.running && this.ledger.reconcile(pages)) this.rebuild();
185
+ } catch {
186
+ // The next interval or reconnect asks again.
187
+ } finally {
188
+ this.reconciling = false;
189
+ }
190
+ }
191
+
167
192
  private rebuild(): void {
168
193
  if (!this.handle) return;
169
- let arr = [...this.byId.values()];
194
+ let arr = [...this.ledger.view.values()];
170
195
  if (this.query.status) arr = arr.filter((o) => o.status === this.query.status);
171
196
  if (this.query.orderbookId) arr = arr.filter((o) => o.orderbookId === this.query.orderbookId);
172
197
  // Newest first by when the order became real. Inclusion time is the key both
@@ -8,7 +8,7 @@
8
8
  // basis, resting-order escrow).
9
9
  //
10
10
  // EXACT replication of pod — see the cross-reference notes in pod at:
11
- // trading/src/perps/mod.rs `cross_budgets` (withdrawable / equity)
11
+ // trading/src/perps/mod.rs `cross_budgets` (equity)
12
12
  // trading/src/perps/mod.rs `pending_funding` (funding)
13
13
  // Integer semantics match trading/src/decimal.rs:
14
14
  // mul(a,b) = (a*b)/1e18 truncated toward zero (Decimal `*`)
@@ -37,6 +37,13 @@ export function enrichPositions(snap: PositionsSnapshot, markets: Market[]): Pos
37
37
  let im = 0n; // Σ initial-margin requirement at live notional
38
38
  let mm = 0n; // Σ maintenance-margin requirement at live notional
39
39
  let dSpot = 0n; // change in spot mark value vs snapshot (slope = balance)
40
+ // Withdrawable is the node's figure moved by the equity and reserve change since
41
+ // it was read. Market data older than the snapshot (another node behind a load
42
+ // balancer) moves nothing.
43
+ let dEquity = 0n;
44
+ let imMoved = 0n;
45
+ let notionalMoved = 0n;
46
+ let notionalSnap = 0n;
40
47
 
41
48
  const positions: Position[] = snap.positions.map((p) => {
42
49
  const market = p.orderbookId ? byId.get(p.orderbookId) : undefined;
@@ -48,9 +55,10 @@ export function enrichPositions(snap: PositionsSnapshot, markets: Market[]): Pos
48
55
  const liveMark = market?.markPrice && market.markPrice > 0n ? market.markPrice : p.markPrice;
49
56
  const mark = liveMark > 0n ? liveMark : p.entryPrice;
50
57
  // The entry-price fallback rounds against the holder.
51
- const upnl = p.costBasis !== undefined
52
- ? mul(mark, p.size) - p.costBasis
53
- : mulFloor(mark - p.entryPrice, p.size); // pure price drift (signed)
58
+ const pnlAt = (m: bigint) => p.costBasis !== undefined
59
+ ? mul(m, p.size) - p.costBasis
60
+ : mulFloor(m - p.entryPrice, p.size); // pure price drift (signed)
61
+ const upnl = pnlAt(mark);
54
62
  const sizeQuote = mul(absB(p.size), mark); // = notional
55
63
  const imr = market?.initialMargin ?? imRate(market?.maxLeverage ?? 0);
56
64
  im += mul(sizeQuote, imr);
@@ -66,6 +74,15 @@ export function enrichPositions(snap: PositionsSnapshot, markets: Market[]): Pos
66
74
  }
67
75
  fundingLiveTotal += funding;
68
76
  fundingSnapTotal += p.fundingAccrued;
77
+ const marketFresh = snap.timestampUs === undefined
78
+ || (market?.dynamicsUs !== undefined && market.dynamicsUs >= snap.timestampUs);
79
+ const snapMark = p.markPrice > 0n ? p.markPrice : p.entryPrice;
80
+ const movedMark = marketFresh ? mark : snapMark;
81
+ if (marketFresh) dEquity += upnl - pnlAt(snapMark) - (funding - p.fundingAccrued);
82
+ const movedNotional = mul(absB(p.size), movedMark);
83
+ imMoved += mul(movedNotional, imr);
84
+ notionalMoved += movedNotional;
85
+ notionalSnap += mul(absB(p.size), snapMark);
69
86
 
70
87
  return { ...p, markPrice: mark, unrealizedPnl: upnl, notional: sizeQuote, fundingAccrued: funding };
71
88
  }
@@ -80,10 +97,16 @@ export function enrichPositions(snap: PositionsSnapshot, markets: Market[]): Pos
80
97
  const nativeCash = snap.cash + fundingSnapTotal;
81
98
  const cashWithFunding = nativeCash - fundingLiveTotal;
82
99
 
83
- // EXACT (perp-only, integer-faithful): equity = cash_with_funding + Σ price PnL;
84
- // withdrawable = max(0, equity - Σ IM), forced to 0 below maintenance margin.
100
+ // EXACT (perp-only, integer-faithful): equity = cash_with_funding + Σ price PnL.
85
101
  const perpsEquity = cashWithFunding + priceUpnl;
86
- const withdrawableCash = perpsEquity < mm ? 0n : maxB(0n, perpsEquity - im);
102
+ // The node reserves max(IM, ratio × notional) plus frozen profit; the ratio is not
103
+ // served, so the snapshot's reserve is scaled with notional, floored at live IM.
104
+ // A zero base hides the reserve, so it moves with equity alone.
105
+ const reserveSnap = snap.perpsEquity - snap.withdrawableCash;
106
+ const dReserve = snap.withdrawableCash > 0n && notionalSnap > 0n
107
+ ? maxB(imMoved, (reserveSnap * notionalMoved) / notionalSnap) - reserveSnap
108
+ : 0n;
109
+ const withdrawableCash = maxB(0n, snap.withdrawableCash + dEquity - dReserve);
87
110
 
88
111
  // account_value moves with perp equity (incl. funding) AND spot mark; total
89
112
  // uPnL is pure price drift only (funding is reported separately). Re-baseline
@@ -95,8 +118,10 @@ export function enrichPositions(snap: PositionsSnapshot, markets: Market[]): Pos
95
118
  totalRealizedPnl: snap.totalRealizedPnl,
96
119
  perpsEquity,
97
120
  withdrawableCash,
121
+ initialMargin: im,
98
122
  maintenanceMargin: mm,
99
123
  totalUnrealizedPnl: snap.totalUnrealizedPnl + dPriceUpnl + dSpot,
100
124
  accountValue: snap.accountValue + (perpsEquity - snap.perpsEquity) + dSpot,
125
+ timestampUs: snap.timestampUs,
101
126
  };
102
127
  }
@@ -34,6 +34,8 @@ export interface SyncContext {
34
34
  positionResyncMs: number;
35
35
  /** Periodic REST re-poll (ms) of market 24h stats; 0 disables. */
36
36
  marketResyncMs: number;
37
+ /** Periodic REST reconcile (ms) of orders, activity, withdrawals, candles and triggers; 0 disables. */
38
+ historyResyncMs: number;
37
39
  /** Optional persistence for the static markets list (see marketsSource). */
38
40
  marketsCache?: MarketsCache;
39
41
  }
@@ -226,7 +228,7 @@ export function marketsSource(
226
228
  const seedStats = () => readAtLeast((min) => rest.marketStats(undefined, min), heldUs).then((page) => {
227
229
  if (!alive) return;
228
230
  heldUs = Math.max(heldUs, page.solutionNow * 1000);
229
- page.markets.forEach((m) => { if (fresh(page.solutionNow, m.id)) mergePatch(m); });
231
+ page.markets.forEach((m) => { if (fresh(page.solutionNow, m.id)) mergePatch({ ...m, dynamicsUs: page.solutionNow * 1000 }); });
230
232
  publish();
231
233
  }).catch(() => { /* live dynamics also arrive on the stream */ });
232
234
 
@@ -241,7 +243,10 @@ export function marketsSource(
241
243
  const id = (w.orderbook_id ?? w.orderbook) as string;
242
244
  if (typeof w.timestamp === "number") heldUs = Math.max(heldUs, w.timestamp);
243
245
  if (!fresh(typeof w.timestamp === "number" ? usToMs(w.timestamp) : undefined, id)) continue;
244
- mergePatch(decodeMarketDynamics({ ...w, orderbook_id: id } as WireMarketDynamics));
246
+ mergePatch({
247
+ ...decodeMarketDynamics({ ...w, orderbook_id: id } as WireMarketDynamics),
248
+ dynamicsUs: typeof w.timestamp === "number" ? w.timestamp : undefined,
249
+ });
245
250
  }
246
251
  publish();
247
252
  });
@@ -284,12 +289,13 @@ export function positionsSource(
284
289
  // - a periodic REST poll that re-aligns to the backend's exact accounting
285
290
  // (corrects mark-extrapolation drift even when the account isn't touched).
286
291
  const fresh = watermarks();
292
+ fresh(h.lastKnown()?.value.timestampUs);
287
293
  const accept = (s: PositionsSnapshot) => { if (alive && fresh(s.timestampUs)) h.set(s); };
288
294
  const reseed = () =>
289
- readAtLeast((min) => rest.positions(account, min), h.current()?.timestampUs).then(accept).catch(() => {});
295
+ readAtLeast((min) => rest.positions(account, min), h.lastKnown()?.value.timestampUs).then(accept).catch(() => {});
290
296
  reseed();
291
297
  const timer = positionResyncMs > 0 ? setInterval(reseed, positionResyncMs) : undefined;
292
- const sub = subscribeRetrying(ws, "pod_positions", () => ({ account, since: h.current()?.timestampUs ?? 0 }), (result) => {
298
+ const sub = subscribeRetrying(ws, "pod_positions", () => ({ account, since: h.lastKnown()?.value.timestampUs ?? 0 }), (result) => {
293
299
  accept(decodePositions((result as WirePositionsPush).data));
294
300
  });
295
301
  return () => { alive = false; if (timer) clearInterval(timer); sub.unsubscribe(); };
@@ -331,17 +337,25 @@ export function balancesSource(
331
337
  }
332
338
 
333
339
  export function triggersSource(
334
- { ws }: SyncContext,
340
+ { rest, ws, historyResyncMs }: SyncContext,
335
341
  account: Address,
336
342
  ): ResourceSource<Trigger[]> {
337
343
  const fresh = watermarks();
338
344
  let heldUs = 0;
339
345
  return (h) => {
346
+ let alive = true;
347
+ const accept = (triggers: Trigger[], timestampUs: number | undefined) => {
348
+ heldUs = Math.max(heldUs, timestampUs ?? 0);
349
+ if (alive && fresh(timestampUs)) h.set(triggers);
350
+ };
351
+ // 200 is the page `pod_triggers` pushes.
352
+ const reconcile = () => readAtLeast((min) => rest.triggers(account, { limit: 200 }, min), heldUs)
353
+ .then((page) => accept(page.triggers, page.timestampUs)).catch(() => {});
354
+ const timer = historyResyncMs > 0 ? setInterval(reconcile, historyResyncMs) : undefined;
340
355
  const sub = subscribeRetrying(ws, "pod_triggers", () => ({ account, since: heldUs }), (result) => {
341
356
  const w = result as WireTriggersPush;
342
- heldUs = Math.max(heldUs, w.timestamp ?? 0);
343
- if (fresh(w.timestamp)) h.set(w.triggers.map(decodeTrigger));
357
+ accept(w.triggers.map(decodeTrigger), w.timestamp);
344
358
  });
345
- return () => sub.unsubscribe();
359
+ return () => { alive = false; clearInterval(timer); sub.unsubscribe(); };
346
360
  };
347
361
  }