@pod-network/trade-sdk 0.14.0 → 0.16.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 +29 -0
  2. package/dist/client.d.ts +0 -1
  3. package/dist/client.d.ts.map +1 -1
  4. package/dist/client.js +0 -1
  5. package/dist/client.js.map +1 -1
  6. package/dist/codec/activity.d.ts.map +1 -1
  7. package/dist/codec/activity.js +6 -2
  8. package/dist/codec/activity.js.map +1 -1
  9. package/dist/codec/decode.d.ts.map +1 -1
  10. package/dist/codec/decode.js +4 -12
  11. package/dist/codec/decode.js.map +1 -1
  12. package/dist/codec/orders-v2.d.ts.map +1 -1
  13. package/dist/codec/orders-v2.js +7 -1
  14. package/dist/codec/orders-v2.js.map +1 -1
  15. package/dist/index.d.ts +2 -2
  16. package/dist/index.d.ts.map +1 -1
  17. package/dist/index.js +1 -1
  18. package/dist/index.js.map +1 -1
  19. package/dist/stores/resource.d.ts +1 -0
  20. package/dist/stores/resource.d.ts.map +1 -1
  21. package/dist/stores/resource.js +1 -0
  22. package/dist/stores/resource.js.map +1 -1
  23. package/dist/sync/activity.d.ts +1 -1
  24. package/dist/sync/activity.d.ts.map +1 -1
  25. package/dist/sync/activity.js +4 -2
  26. package/dist/sync/activity.js.map +1 -1
  27. package/dist/sync/candles.d.ts +3 -1
  28. package/dist/sync/candles.d.ts.map +1 -1
  29. package/dist/sync/candles.js +13 -7
  30. package/dist/sync/candles.js.map +1 -1
  31. package/dist/sync/orders.d.ts +1 -1
  32. package/dist/sync/orders.d.ts.map +1 -1
  33. package/dist/sync/orders.js +11 -13
  34. package/dist/sync/orders.js.map +1 -1
  35. package/dist/sync/pnl-history.js +1 -1
  36. package/dist/sync/pnl-history.js.map +1 -1
  37. package/dist/sync/sources.d.ts +11 -1
  38. package/dist/sync/sources.d.ts.map +1 -1
  39. package/dist/sync/sources.js +117 -32
  40. package/dist/sync/sources.js.map +1 -1
  41. package/dist/sync/stream.d.ts.map +1 -1
  42. package/dist/sync/stream.js +2 -1
  43. package/dist/sync/stream.js.map +1 -1
  44. package/dist/sync/withdrawals.d.ts.map +1 -1
  45. package/dist/sync/withdrawals.js +32 -23
  46. package/dist/sync/withdrawals.js.map +1 -1
  47. package/dist/transport/rest.d.ts +19 -9
  48. package/dist/transport/rest.d.ts.map +1 -1
  49. package/dist/transport/rest.js +42 -18
  50. package/dist/transport/rest.js.map +1 -1
  51. package/dist/transport/ws.d.ts +1 -1
  52. package/dist/transport/ws.d.ts.map +1 -1
  53. package/dist/transport/ws.js +5 -4
  54. package/dist/transport/ws.js.map +1 -1
  55. package/dist/types/public.d.ts +16 -12
  56. package/dist/types/public.d.ts.map +1 -1
  57. package/dist/types/wire.d.ts +15 -10
  58. package/dist/types/wire.d.ts.map +1 -1
  59. package/dist/write/delegation.d.ts +7 -0
  60. package/dist/write/delegation.d.ts.map +1 -1
  61. package/dist/write/delegation.js +86 -8
  62. package/dist/write/delegation.js.map +1 -1
  63. package/dist/write/index.d.ts +2 -3
  64. package/dist/write/index.d.ts.map +1 -1
  65. package/dist/write/index.js +9 -12
  66. package/dist/write/index.js.map +1 -1
  67. package/package.json +2 -1
  68. package/src/client.ts +1 -2
  69. package/src/codec/activity.ts +7 -2
  70. package/src/codec/decode.ts +4 -12
  71. package/src/codec/orders-v2.ts +6 -1
  72. package/src/index.ts +2 -2
  73. package/src/stores/resource.ts +2 -0
  74. package/src/sync/activity.ts +7 -3
  75. package/src/sync/candles.ts +12 -8
  76. package/src/sync/orders.ts +14 -14
  77. package/src/sync/pnl-history.ts +1 -1
  78. package/src/sync/sources.ts +112 -30
  79. package/src/sync/stream.ts +2 -1
  80. package/src/sync/withdrawals.ts +35 -25
  81. package/src/transport/rest.ts +40 -19
  82. package/src/transport/ws.ts +8 -6
  83. package/src/types/public.ts +16 -12
  84. package/src/types/wire.ts +16 -10
  85. package/src/write/delegation.ts +82 -8
  86. package/src/write/index.ts +15 -23
@@ -8,7 +8,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 type { SyncContext } from "./sources.js";
11
+ import { readAtLeast, type SyncContext } from "./sources.js";
12
12
  import { compareCursor, ResumableStream } from "./stream.js";
13
13
 
14
14
  export { compareCursor } from "./stream.js";
@@ -85,10 +85,11 @@ export class OrderHistory implements SeriesResource<Order> {
85
85
  this._loading = true;
86
86
  this.rebuild();
87
87
  try {
88
- const page = await this.ctx.rest.orders(this.account, {
89
- cursor: this.nextCursor,
88
+ const cursor = this.nextCursor;
89
+ const page = await readAtLeast((min) => this.ctx.rest.orders(this.account, {
90
+ cursor,
90
91
  limit: this.query.limit ?? 100,
91
- });
92
+ }, min), this.stream.cursor.since);
92
93
  for (const o of page.orders) if (!this.byId.has(o.id)) this.byId.set(o.id, o);
93
94
  this.nextCursor = page.nextCursor;
94
95
  this._hasMore = page.nextCursor !== null;
@@ -102,20 +103,19 @@ export class OrderHistory implements SeriesResource<Order> {
102
103
 
103
104
  private async fetchFirstPage(): Promise<boolean> {
104
105
  const gen = ++this.seedGen;
105
- const before = this.stream.cursor;
106
106
  try {
107
- const page = await this.ctx.rest.orders(this.account, { limit: this.query.limit ?? 100 });
107
+ const page = await readAtLeast(
108
+ (min) => this.ctx.rest.orders(this.account, { limit: this.query.limit ?? 100 }, min),
109
+ this.stream.cursor.since,
110
+ );
108
111
  // A seed overtaken by a fresher one is dropped whole: it would absorb rows the
109
112
  // newer page has already corrected, and raise the cursor to an older watermark.
110
113
  if (!this.stream.running || gen !== this.seedGen) return false;
111
- // The transport resubscribes synchronously right after the `open` event that
112
- // starts this fetch, so replayed frames can land while it is still in flight —
113
- // and the indexer trails the stream by design. Overwriting a row the stream has
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;
114
+ 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
117
  for (const o of page.orders) {
118
- if (streamMovedOn && this.byId.has(o.id)) continue;
118
+ if (stale && this.byId.has(o.id)) continue;
119
119
  this.byId.set(o.id, o);
120
120
  }
121
121
  // Paging is the consumer's position in history, not the seed's: a reconnect
@@ -129,7 +129,7 @@ export class OrderHistory implements SeriesResource<Order> {
129
129
  // Only ever forward, and a page settles whole batches, so its watermark
130
130
  // carries no book — which makes it *ahead* of a stream position in the same
131
131
  // batch, not equal to it.
132
- this.stream.raise({ since: page.solutionNow * 1000, sinceBook: undefined });
132
+ this.stream.raise(settled);
133
133
  this.rebuild();
134
134
  return true;
135
135
  } catch (e) {
@@ -541,7 +541,7 @@ export async function* streamPnlHistory(
541
541
  use(b.orderbookId);
542
542
  fixed.push({ market: b.orderbookId, timeUs, deltaSize: -b.size, price: b.markPrice, kind: "sweep" });
543
543
  }
544
- for (const w of withdrawals) {
544
+ for (const w of withdrawals.withdrawals) {
545
545
  if (w.error || w.timeUs < fromUs || w.timeUs > nowUs) continue;
546
546
  const m = spotByToken.get(w.token);
547
547
  if (!m) { fixed.push({ timeUs: w.timeUs, deltaSize: -w.amount, price: 0n, kind: "cash" }); continue; }
@@ -2,9 +2,8 @@
2
2
  // maintain in memory from the matching `pod_*` channel.
3
3
  //
4
4
  // Reconnect model:
5
- // - Current-state channels (markets/positions/triggers) subscribe with
6
- // `since: 0`, so every (re)subscribe yields a fresh immediate snapshot — no
7
- // staleness possible, nothing to re-seed.
5
+ // - Current-state channels (markets/positions/triggers) (re)subscribe with
6
+ // `since` = the held timestamp; the node answers with a snapshot at or past it.
8
7
  // - REST-seeded channels (markets static, orderbook, balances) seed
9
8
  // immediately — the fetch doesn't need the socket, so first data isn't
10
9
  // held behind the WS handshake — and re-seed on every (re)connect via
@@ -17,14 +16,15 @@ import type {
17
16
  Address, Balances, BridgeConfig, Market, MarketId, Orderbook, PositionsSnapshot, Status, Trigger,
18
17
  } from "../types/public.js";
19
18
  import type {
20
- WireMarketDynamics, WireOrderbook, WirePositionsPush, WireTriggersPush,
19
+ WireMarketDynamics, WireOrderbook, WirePositionsPush, WireSpotPosition, WireTriggersPush,
21
20
  } from "../types/wire.js";
22
21
  import {
23
- decodeMarketDynamics, decodeOrderbook, decodePositions, decodeTrigger,
22
+ decodeBalances, decodeMarketDynamics, decodeOrderbook, decodePositions, decodeTrigger,
24
23
  } from "../codec/decode.js";
25
24
  import { parseBig, stringifyBig } from "../codec/json.js";
26
- import type { PodRestClient } from "../transport/rest.js";
27
- import type { PodWsClient } from "../transport/ws.js";
25
+ import { PodBehindError, type PodRestClient } from "../transport/rest.js";
26
+ import type { Channel, PodWsClient, SubParams } from "../transport/ws.js";
27
+ import { usToMs } from "../codec/units.js";
28
28
  import type { ResourceSource } from "../stores/resource.js";
29
29
 
30
30
  export interface SyncContext {
@@ -77,6 +77,68 @@ export function seedNowAndOnReconnect(ws: PodWsClient, fn: () => void): () => vo
77
77
  return off;
78
78
  }
79
79
 
80
+ /** Concurrent answers for one entity land in either order, so an answer below what is held is dropped. */
81
+ export function watermarks(): (ts: number | undefined, key?: string) => boolean {
82
+ const seen = new Map<string, number>();
83
+ return (ts, key = "") => {
84
+ if (ts === undefined) return true;
85
+ if (ts < (seen.get(key) ?? -Infinity)) return false;
86
+ seen.set(key, ts);
87
+ return true;
88
+ };
89
+ }
90
+
91
+ /**
92
+ * A REST read that asks the node for state at or past `minUs`. A node that
93
+ * cannot get there in time is retried once after its `Retry-After`; a second
94
+ * {@link PodBehindError} is thrown to the caller.
95
+ */
96
+ export async function readAtLeast<T>(read: (minUs?: number) => Promise<T>, minUs: number | undefined): Promise<T> {
97
+ if (!minUs) return read(undefined);
98
+ try {
99
+ return await read(minUs);
100
+ } catch (e) {
101
+ if (!(e instanceof PodBehindError)) throw e;
102
+ await new Promise((r) => setTimeout(r, e.retryAfterMs));
103
+ return read(minUs);
104
+ }
105
+ }
106
+
107
+ export const MAX_SUB_RETRIES = 5;
108
+ export const subBackoffMs = (retries: number) => Math.min(30_000, 500 * 2 ** (retries - 1));
109
+
110
+ /** `ws.subscribe` for channels that need no cursor: a rejected or server-closed
111
+ * sub is resubscribed with bounded backoff, cancelled once it is live again. A
112
+ * 995 rejection (node not yet at `since`) is retried every second while alive. */
113
+ function subscribeRetrying(
114
+ ws: PodWsClient,
115
+ channel: Channel,
116
+ params: SubParams | (() => SubParams),
117
+ onMessage: (result: unknown) => void,
118
+ ): { unsubscribe(): void } {
119
+ let retries = 0;
120
+ let dead = false;
121
+ let timer: ReturnType<typeof setTimeout> | undefined;
122
+ const cancel = () => { if (timer) { clearTimeout(timer); timer = undefined; } };
123
+ // A reconnect resubscribes from `onopen`; a timer firing after that would drop the live server id.
124
+ const offOpen = ws.on("open", cancel);
125
+ const sub = ws.subscribe(channel, params, (result) => {
126
+ retries = 0;
127
+ cancel();
128
+ onMessage(result);
129
+ }, (err) => {
130
+ if (dead) return;
131
+ const behind = (err as { code?: unknown } | undefined)?.code === 995;
132
+ if (!behind) {
133
+ if (retries >= MAX_SUB_RETRIES) return;
134
+ retries++;
135
+ }
136
+ cancel();
137
+ timer = setTimeout(() => { timer = undefined; if (!dead) sub.resubscribe(); }, behind ? 1_000 : subBackoffMs(retries));
138
+ });
139
+ return { unsubscribe: () => { dead = true; cancel(); offOpen(); sub.unsubscribe(); } };
140
+ }
141
+
80
142
  export function statusSource({ rest, ws }: SyncContext): ResourceSource<Status> {
81
143
  return (h) => {
82
144
  let alive = true;
@@ -124,6 +186,8 @@ export function marketsSource(
124
186
  (orderIndex.get(a.id) ?? Number.MAX_SAFE_INTEGER) - (orderIndex.get(b.id) ?? Number.MAX_SAFE_INTEGER)
125
187
  || a.id.localeCompare(b.id)),
126
188
  );
189
+ const fresh = watermarks();
190
+ let heldUs = 0;
127
191
  const mergePatch = (patch: Partial<Market> & { id: string }) => {
128
192
  const existing = byId.get(patch.id);
129
193
  byId.set(patch.id, existing ? { ...existing, ...patch } : (patch as Market));
@@ -157,11 +221,12 @@ export function marketsSource(
157
221
  try { marketsCache?.set(serializeMarkets(markets)); } catch { /* storage denied/full */ }
158
222
  }).catch((e) => { if (!byId.size) h.fail(e); });
159
223
 
160
- // 24h vol/high/low slide with time and only the REST stats reflect that
161
- // (the WS only pushes on a clear) — so poll them periodically.
162
- const seedStats = () => rest.marketStats().then((page) => {
224
+ // A push carries the 24h stats too, but only for markets cleared that tick;
225
+ // the periodic REST poll keeps the 24h window sliding for the rest.
226
+ const seedStats = () => readAtLeast((min) => rest.marketStats(undefined, min), heldUs).then((page) => {
163
227
  if (!alive) return;
164
- page.markets.forEach(mergePatch);
228
+ heldUs = Math.max(heldUs, page.solutionNow * 1000);
229
+ page.markets.forEach((m) => { if (fresh(page.solutionNow, m.id)) mergePatch(m); });
165
230
  publish();
166
231
  }).catch(() => { /* live dynamics also arrive on the stream */ });
167
232
 
@@ -169,11 +234,14 @@ export function marketsSource(
169
234
  const timer = marketResyncMs > 0 ? setInterval(seedStats, marketResyncMs) : undefined;
170
235
 
171
236
  // Live clearing/mark/funding between polls.
172
- const sub = ws.subscribe("pod_markets", { since: 0 }, (result) => {
237
+ const sub = subscribeRetrying(ws, "pod_markets", () => ({ since: heldUs }), (result) => {
173
238
  const items = Array.isArray(result) ? result : [result];
174
239
  for (const it of items) {
175
240
  const w = it as Record<string, unknown>;
176
- mergePatch(decodeMarketDynamics({ ...w, orderbook_id: w.orderbook_id ?? w.orderbook } as WireMarketDynamics));
241
+ const id = (w.orderbook_id ?? w.orderbook) as string;
242
+ if (typeof w.timestamp === "number") heldUs = Math.max(heldUs, w.timestamp);
243
+ if (!fresh(typeof w.timestamp === "number" ? usToMs(w.timestamp) : undefined, id)) continue;
244
+ mergePatch(decodeMarketDynamics({ ...w, orderbook_id: id } as WireMarketDynamics));
177
245
  }
178
246
  publish();
179
247
  });
@@ -190,13 +258,13 @@ export function orderbookSource(
190
258
  return (h) => {
191
259
  let alive = true;
192
260
  const seed = () => {
193
- rest.orderbook(id).then((ob) => {
261
+ readAtLeast((min) => rest.orderbook(id, min), (h.current()?.timeMs ?? 0) * 1000).then((ob) => {
194
262
  const cur = h.current();
195
263
  if (alive && (!cur || cur.timeMs <= ob.timeMs)) h.set(ob);
196
264
  }).catch((e) => { if (!h.current()) h.fail(e); });
197
265
  };
198
266
  const offOpen = seedNowAndOnReconnect(ws, seed);
199
- const sub = ws.subscribe("pod_orderbook", { clobIds: [id], depth }, (result) => {
267
+ const sub = subscribeRetrying(ws, "pod_orderbook", { clobIds: [id], depth }, (result) => {
200
268
  const ob = decodeOrderbook(result as WireOrderbook);
201
269
  const cur = h.current();
202
270
  if (!cur || ob.timeMs >= cur.timeMs) h.set(ob);
@@ -212,14 +280,17 @@ export function positionsSource(
212
280
  return (h) => {
213
281
  let alive = true;
214
282
  // Baseline refreshes from three triggers, all just replacing the snapshot:
215
- // - WS since:0 immediate + on every account-touching tick,
283
+ // - WS snapshot on every (re)subscribe + on every account-touching tick,
216
284
  // - a periodic REST poll that re-aligns to the backend's exact accounting
217
285
  // (corrects mark-extrapolation drift even when the account isn't touched).
218
- const reseed = () => rest.positions(account).then((s) => { if (alive) h.set(s); }).catch(() => {});
286
+ const fresh = watermarks();
287
+ const accept = (s: PositionsSnapshot) => { if (alive && fresh(s.timestampUs)) h.set(s); };
288
+ const reseed = () =>
289
+ readAtLeast((min) => rest.positions(account, min), h.current()?.timestampUs).then(accept).catch(() => {});
219
290
  reseed();
220
291
  const timer = positionResyncMs > 0 ? setInterval(reseed, positionResyncMs) : undefined;
221
- const sub = ws.subscribe("pod_positions", { account, since: 0 }, (result) => {
222
- if (alive) h.set(decodePositions((result as WirePositionsPush).data));
292
+ const sub = subscribeRetrying(ws, "pod_positions", () => ({ account, since: h.current()?.timestampUs ?? 0 }), (result) => {
293
+ accept(decodePositions((result as WirePositionsPush).data));
223
294
  });
224
295
  return () => { alive = false; if (timer) clearInterval(timer); sub.unsubscribe(); };
225
296
  };
@@ -231,22 +302,29 @@ export function balancesSource(
231
302
  ): ResourceSource<Balances> {
232
303
  return (h) => {
233
304
  let alive = true;
234
- // No dedicated balances stream — seed over REST, re-poll periodically, and
235
- // re-fetch (debounced) whenever the account is touched on pod_positions, so
236
- // a spot fill / deposit reflects promptly without spamming a fetch per tick.
237
- const seed = () => rest.balances(account).then((b) => { if (alive) h.set(b); }).catch((e) => { if (!h.current()) h.fail(e as Error); });
305
+ // No dedicated balances stream: the pod_positions push carries the spot
306
+ // holdings and cash too, so it is folded in; REST seeds and re-aligns.
307
+ const fresh = watermarks();
308
+ fresh(h.lastKnown()?.value.timestampUs);
309
+ const accept = (b: Balances) => { if (alive && fresh(b.timestampUs)) h.set(b); };
310
+ const seed = () => readAtLeast((min) => rest.balances(account, min), h.lastKnown()?.value.timestampUs)
311
+ .then(accept).catch((e) => { if (!h.current()) h.fail(e as Error); });
238
312
  const offOpen = seedNowAndOnReconnect(ws, seed);
239
313
  const timer = positionResyncMs > 0 ? setInterval(seed, positionResyncMs) : undefined;
240
- let debounce: ReturnType<typeof setTimeout> | undefined;
241
- const sub = ws.subscribe("pod_positions", { account, since: 0 }, () => {
242
- if (!alive || debounce) return;
243
- debounce = setTimeout(() => { debounce = undefined; seed(); }, 500);
314
+ const sub = subscribeRetrying(ws, "pod_positions", () => ({ account, since: h.lastKnown()?.value.timestampUs ?? 0 }), (result) => {
315
+ const w = (result as WirePositionsPush).data;
316
+ accept(decodeBalances({
317
+ balances: w.positions.filter((p): p is WireSpotPosition => p.kind === "spot"),
318
+ cash: w.cash,
319
+ withdrawable_cash: w.withdrawable_cash,
320
+ net_deposits: w.net_deposits,
321
+ timestamp: w.timestamp,
322
+ }));
244
323
  });
245
324
  return () => {
246
325
  alive = false;
247
326
  offOpen();
248
327
  if (timer) clearInterval(timer);
249
- if (debounce) clearTimeout(debounce);
250
328
  sub.unsubscribe();
251
329
  };
252
330
  };
@@ -256,9 +334,13 @@ export function triggersSource(
256
334
  { ws }: SyncContext,
257
335
  account: Address,
258
336
  ): ResourceSource<Trigger[]> {
337
+ const fresh = watermarks();
338
+ let heldUs = 0;
259
339
  return (h) => {
260
- const sub = ws.subscribe("pod_triggers", { account, since: 0 }, (result) => {
261
- h.set((result as WireTriggersPush).triggers.map(decodeTrigger));
340
+ const sub = subscribeRetrying(ws, "pod_triggers", () => ({ account, since: heldUs }), (result) => {
341
+ const w = result as WireTriggersPush;
342
+ heldUs = Math.max(heldUs, w.timestamp ?? 0);
343
+ if (fresh(w.timestamp)) h.set(w.triggers.map(decodeTrigger));
262
344
  });
263
345
  return () => sub.unsubscribe();
264
346
  };
@@ -11,6 +11,7 @@ import type { MarketId } from "../types/public.js";
11
11
  import { PodHttpError } from "../transport/rest.js";
12
12
  import type { Channel, PodWsClient, SubParams, Subscription } from "../transport/ws.js";
13
13
  import { PodSubscriptionClosedError } from "../transport/ws.js";
14
+ import { subBackoffMs } from "./sources.js";
14
15
 
15
16
  /**
16
17
  * Consecutive server closes we resume from before falling back to the re-seed
@@ -242,7 +243,7 @@ export class ResumableStream {
242
243
  */
243
244
  private scheduleReseed(): void {
244
245
  this.subRetries++;
245
- const delay = Math.min(30_000, 500 * 2 ** (this.subRetries - 1));
246
+ const delay = subBackoffMs(this.subRetries);
246
247
  this.clearRetry();
247
248
  this.retryTimer = setTimeout(() => {
248
249
  this.retryTimer = undefined;
@@ -1,5 +1,5 @@
1
1
  // Terminal withdrawal outcomes for one account (ADR 0033 §6): seeded and
2
- // gap-filled over `GET /v1/bridge/withdrawals/{account}`, kept live by the
2
+ // gap-filled over `GET /v2/bridge/withdrawals/{account}`, kept live by the
3
3
  // `pod_withdrawals` subscription.
4
4
  //
5
5
  // The two surfaces serve the identical shape, so a backfilled outcome is
@@ -13,7 +13,8 @@ import type { Address, Withdrawal } from "../types/public.js";
13
13
  import type { WireWithdrawal } from "../types/wire.js";
14
14
  import { decodeWithdrawal } from "../codec/decode.js";
15
15
  import type { ResourceSource } from "../stores/resource.js";
16
- import { seedNowAndOnReconnect, type SyncContext } from "./sources.js";
16
+ import type { Subscription } from "../transport/ws.js";
17
+ import { MAX_SUB_RETRIES, readAtLeast, subBackoffMs, type SyncContext } from "./sources.js";
17
18
 
18
19
  /** Page size for the backfill. The server caps at 1000 and defaults to 500. */
19
20
  const PAGE_LIMIT = 500;
@@ -22,10 +23,6 @@ const PAGE_LIMIT = 500;
22
23
  * forever. 50 pages × 500 covers 25k outcomes — far past any real account. */
23
24
  const MAX_PAGES = 50;
24
25
 
25
- /** Resubscribe attempts after a rejection before leaving the channel alone.
26
- * Reached only when the rejection is permanent — see the `onError` comment. */
27
- const MAX_SUB_RETRIES = 5;
28
-
29
26
  export function withdrawalsSource(
30
27
  { rest, ws }: SyncContext,
31
28
  account: Address,
@@ -41,6 +38,9 @@ export function withdrawalsSource(
41
38
  let sinceId: Withdrawal["txHash"] | undefined;
42
39
  let retries = 0;
43
40
  let retryTimer: ReturnType<typeof setTimeout> | undefined;
41
+ // Newest tick a backfill's node could serve; never behind the rows it returned.
42
+ let servedUs = 0;
43
+ let sub: Subscription | undefined;
44
44
 
45
45
  const publish = () => {
46
46
  // Newest first: a user reads their most recent withdrawal at the top, and
@@ -65,8 +65,8 @@ export function withdrawalsSource(
65
65
  * reconnect can fire while a retry's backfill is still paging. Both share
66
66
  * the cursor, so concurrent loops would re-request each other's pages.
67
67
  */
68
- let inflight: Promise<void> | undefined;
69
- const backfill = (): Promise<void> => (inflight ??= run().finally(() => { inflight = undefined; }));
68
+ let inflight: Promise<boolean> | undefined;
69
+ const backfill = (): Promise<boolean> => (inflight ??= run().finally(() => { inflight = undefined; }));
70
70
 
71
71
  const run = async () => {
72
72
  try {
@@ -77,21 +77,21 @@ export function withdrawalsSource(
77
77
  let pageSince = sinceUs;
78
78
  let pageSinceId = sinceId;
79
79
  for (let page = 0; page < MAX_PAGES; page++) {
80
- const rows = await rest.bridgeWithdrawals(account, {
81
- since: pageSince,
82
- sinceId: pageSinceId,
83
- limit: PAGE_LIMIT,
84
- });
85
- if (!alive) return;
86
- if (rows.length === 0) break;
80
+ const query = { since: pageSince, sinceId: pageSinceId, limit: PAGE_LIMIT };
81
+ const res = await readAtLeast(
82
+ (min) => rest.bridgeWithdrawals(account, query, min),
83
+ Math.max(sinceUs, servedUs),
84
+ );
85
+ if (!alive) return false;
86
+ const rows = res.withdrawals;
87
87
  absorb(rows);
88
+ // Pages may come from different nodes: only the one that served the end of the log vouches for it.
89
+ if (rows.length < PAGE_LIMIT) { servedUs = Math.max(servedUs, res.timestampUs); break; }
88
90
  // Rows come back ascending, so the last one is this page's high-water
89
91
  // mark — regardless of what the stream did to the shared cursor.
90
- // Non-empty by the check above.
91
92
  const last = rows[rows.length - 1]!;
92
93
  pageSince = last.timeUs;
93
94
  pageSinceId = last.txHash;
94
- if (rows.length < PAGE_LIMIT) break;
95
95
  }
96
96
  // Once, after paging: publishing per page re-copies and re-sorts
97
97
  // everything accumulated so far for a list the user sees for
@@ -102,6 +102,7 @@ export function withdrawalsSource(
102
102
  // on "not loaded yet" and treats the first live outcome as its initial
103
103
  // snapshot — silently swallowing a user's first-ever withdrawal.
104
104
  publish();
105
+ return true;
105
106
  } catch (e) {
106
107
  // Publish on the failure path too, for exactly the reason the success
107
108
  // path publishes unconditionally: a consumer left on "not loaded yet"
@@ -113,10 +114,11 @@ export function withdrawalsSource(
113
114
  // Only surface the failure when there is nothing to show; otherwise the
114
115
  // stream is still feeding a usable list and a toast would be noise.
115
116
  if (byHash.size === 0) h.fail(e as Error);
117
+ return false;
116
118
  }
117
119
  };
118
120
 
119
- const sub = ws.subscribe(
121
+ const subscribe = (since: number | undefined) => sub = ws.subscribe(
120
122
  "pod_withdrawals",
121
123
  // Live-only until a cursor exists. This is a replay channel, so the server
122
124
  // accepts `since` only when its buffer still reaches back that far — and
@@ -124,7 +126,7 @@ export function withdrawalsSource(
124
126
  // and burn the retry budget below on a self-inflicted rejection. (The
125
127
  // `since: 0` idiom belongs to the *state* channels, which answer it with a
126
128
  // snapshot.) REST backfill covers history either way.
127
- { account },
129
+ { account, since },
128
130
  (result) => {
129
131
  retries = 0;
130
132
  // A frame means the subscription is healthy, so a retry armed by an
@@ -135,7 +137,7 @@ export function withdrawalsSource(
135
137
  // One message per tick carrying that tick's outcomes for this account.
136
138
  absorb((result as WireWithdrawal[]).map(decodeWithdrawal));
137
139
  publish();
138
- sub.update({ since: sinceUs }); // keep the resume point fresh for a reconnect
140
+ sub!.update({ since: Math.max(sinceUs, servedUs) }); // keep the resume point fresh for a reconnect
139
141
  },
140
142
  () => {
141
143
  // Rejected — usually a `since` older than the replay buffer. Back off,
@@ -156,22 +158,30 @@ export function withdrawalsSource(
156
158
  // Live-only until a real cursor exists (see the subscribe above), and
157
159
  // dropped again after a couple of failures in case the replay buffer
158
160
  // has outrun it.
159
- sub.update({ since: retries > 2 || sinceUs === 0 ? undefined : sinceUs });
160
- sub.resubscribe();
161
+ const since = Math.max(sinceUs, servedUs);
162
+ sub!.update({ since: retries > 2 || since === 0 ? undefined : since });
163
+ sub!.resubscribe();
161
164
  });
162
- }, Math.min(30_000, 500 * 2 ** (retries - 1)));
165
+ }, subBackoffMs(retries));
163
166
  },
164
167
  );
165
168
 
166
169
  // Seed immediately — REST needs no socket, so history paints without waiting
167
170
  // on the handshake — and fill the gap again on every reconnect.
168
- const offOpen = seedNowAndOnReconnect(ws, () => { if (alive) void backfill(); });
171
+ const offOpen = ws.on("open", () => { if (alive) void backfill(); });
172
+ // Subscribing after the first backfill lets `since` cover the gap between a
173
+ // lagging REST node and the head of the node the socket landed on.
174
+ void backfill().then((ok) => {
175
+ if (!alive) return;
176
+ const since = Math.max(sinceUs, servedUs);
177
+ subscribe(ok && since > 0 ? since : undefined);
178
+ });
169
179
 
170
180
  return () => {
171
181
  alive = false;
172
182
  offOpen();
173
183
  if (retryTimer) clearTimeout(retryTimer);
174
- sub.unsubscribe();
184
+ sub?.unsubscribe();
175
185
  };
176
186
  };
177
187
  }
@@ -11,7 +11,7 @@ import type {
11
11
  import type {
12
12
  WireActivityEntry, WireActivityPage, WireBackstopPage, WireBalances, WireBridgeConfig, WireCandlesEnvelope,
13
13
  WireMarketStatic, WireMarketStatsPage, WireOrderbook, WireOrdersPage, WirePositionsSnapshot,
14
- WireStatus, WireTriggersPage, WireWithdrawal,
14
+ WireStatus, WireTriggersPage, WireWithdrawalsPage,
15
15
  } from "../types/wire.js";
16
16
  import {
17
17
  decodeBackstopTransfer, decodeBalances, decodeBridgeConfig, decodeCandle,
@@ -49,6 +49,10 @@ export interface TriggersPage {
49
49
  totalCount: number;
50
50
  nextCursor: string | null;
51
51
  }
52
+ export interface WithdrawalsPage {
53
+ withdrawals: Withdrawal[];
54
+ timestampUs: number;
55
+ }
52
56
  export interface CandlesPage {
53
57
  bars: Bar[]; // oldest-first
54
58
  resolution: Resolution;
@@ -80,6 +84,14 @@ export class PodHttpError extends Error {
80
84
  }
81
85
  }
82
86
 
87
+ /** 503 from a node whose state has not reached the requested `timestamp`. */
88
+ export class PodBehindError extends PodHttpError {
89
+ constructor(url: string, public currentUs: number, public retryAfterMs: number) {
90
+ super(503, url, `GET ${url} -> 503 behind at ${currentUs}`);
91
+ this.name = "PodBehindError";
92
+ }
93
+ }
94
+
83
95
  type FetchFn = typeof fetch;
84
96
 
85
97
  export interface RestClientOptions {
@@ -138,6 +150,12 @@ export class PodRestClient {
138
150
  if (!res.ok) {
139
151
  let body = "";
140
152
  try { body = await res.text(); } catch { /* ignore */ }
153
+ if (res.status === 503) {
154
+ let current: unknown;
155
+ try { current = (JSON.parse(body) as { timestamp?: unknown }).timestamp; } catch { /* not ours */ }
156
+ const retryAfter = Number(res.headers.get("retry-after"));
157
+ if (typeof current === "number") throw new PodBehindError(url, current, retryAfter > 0 ? retryAfter * 1000 : 1000);
158
+ }
141
159
  throw new PodHttpError(res.status, url, `GET ${url} -> ${res.status} ${body}`.trim());
142
160
  }
143
161
  return (await res.json()) as T;
@@ -152,9 +170,10 @@ export class PodRestClient {
152
170
  return w.map(decodeMarketStatic);
153
171
  }
154
172
 
155
- async marketStats(opts?: { to?: number }): Promise<MarketStatsPage> {
173
+ async marketStats(opts?: { to?: number }, minTimestampUs?: number): Promise<MarketStatsPage> {
156
174
  const w = await this.get<WireMarketStatsPage>("/clob/markets/stats", {
157
175
  to: opts?.to !== undefined ? msToSecs(opts.to) : undefined,
176
+ timestamp: minTimestampUs,
158
177
  });
159
178
  return {
160
179
  solutionNow: Math.trunc(w.solution_now / 1000),
@@ -162,12 +181,13 @@ export class PodRestClient {
162
181
  };
163
182
  }
164
183
 
165
- async candles(id: MarketId, q: CandleQuery): Promise<CandlesPage> {
184
+ async candles(id: MarketId, q: CandleQuery, minTimestampUs?: number): Promise<CandlesPage> {
166
185
  const w = await this.get<WireCandlesEnvelope>(`/clob/candles/${id}`, {
167
186
  resolution: q.resolution,
168
187
  from: q.from !== undefined ? msToSecs(q.from) : undefined,
169
188
  to: q.to !== undefined ? msToSecs(q.to) : undefined,
170
189
  limit: q.limit,
190
+ timestamp: minTimestampUs,
171
191
  });
172
192
  return {
173
193
  // Wire is newest-first; return oldest-first for chart consumption.
@@ -178,11 +198,12 @@ export class PodRestClient {
178
198
  };
179
199
  }
180
200
 
181
- async orders(account: Address, q?: OrdersQueryRest): Promise<OrdersPage> {
201
+ async orders(account: Address, q?: OrdersQueryRest, minTimestampUs?: number): Promise<OrdersPage> {
182
202
  const w = await this.get<WireOrdersPage>(`/clob/orders/${account}`, {
183
203
  until: q?.until !== undefined ? msToSecs(q.until) : undefined,
184
204
  limit: q?.limit,
185
205
  cursor: q?.cursor,
206
+ timestamp: minTimestampUs,
186
207
  });
187
208
  return {
188
209
  orders: w.orders.map(decodeOrder),
@@ -193,12 +214,13 @@ export class PodRestClient {
193
214
  }
194
215
 
195
216
  /** One page of an account's activity by batch, newest batches first (ADR 0057 §5); page with `nextUs`. */
196
- async activity(account: Address, q?: ActivityQueryRest): Promise<ActivityPage> {
217
+ async activity(account: Address, q?: ActivityQueryRest, minTimestampUs?: number): Promise<ActivityPage> {
197
218
  const w = await this.get<WireActivityPage>(`/clob/activity/${account}`, {
198
219
  activity_types: q?.types?.length ? q.types.join(",") : undefined,
199
220
  from: q?.fromUs !== undefined ? String(q.fromUs) : undefined,
200
221
  to: q?.toUs !== undefined ? String(q.toUs) : undefined,
201
222
  limit: q?.limit,
223
+ timestamp: minTimestampUs,
202
224
  });
203
225
  const batches = Object.entries(w.activity)
204
226
  .map(([batch, entries]): [number, WireActivityEntry[]] => [Number(batch), entries])
@@ -243,18 +265,18 @@ export class PodRestClient {
243
265
  };
244
266
  }
245
267
 
246
- async orderbook(id: MarketId): Promise<Orderbook> {
247
- return decodeOrderbook(await this.get<WireOrderbook>(`/clob/orderbook/${id}`));
268
+ async orderbook(id: MarketId, minTimestampUs?: number): Promise<Orderbook> {
269
+ return decodeOrderbook(await this.get<WireOrderbook>(`/clob/orderbook/${id}`, { timestamp: minTimestampUs }));
248
270
  }
249
271
 
250
272
  /** Perp positions + account aggregates (spot holdings are at `/clob/balances`). */
251
- async positions(account: Address): Promise<PositionsSnapshot> {
252
- return decodePositions(await this.get<WirePositionsSnapshot>(`/clob/positions/${account}`));
273
+ async positions(account: Address, minTimestampUs?: number): Promise<PositionsSnapshot> {
274
+ return decodePositions(await this.get<WirePositionsSnapshot>(`/clob/positions/${account}`, { timestamp: minTimestampUs }));
253
275
  }
254
276
 
255
277
  /** Spot holdings + native cash. */
256
- async balances(account: Address): Promise<Balances> {
257
- return decodeBalances(await this.get<WireBalances>(`/clob/balances/${account}`));
278
+ async balances(account: Address, minTimestampUs?: number): Promise<Balances> {
279
+ return decodeBalances(await this.get<WireBalances>(`/clob/balances/${account}`, { timestamp: minTimestampUs }));
258
280
  }
259
281
 
260
282
  /** Flat explorer view of a transaction (fields, receipt, logs, attestations,
@@ -279,20 +301,19 @@ export class PodRestClient {
279
301
  * cannot tell which one an outcome arrived on. Page with `since` (the tick
280
302
  * cursor) plus `sinceId` to resume *inside* a tick that spanned a page.
281
303
  */
282
- async bridgeWithdrawals(account?: Address, q?: WithdrawalsQuery): Promise<Withdrawal[]> {
304
+ async bridgeWithdrawals(account?: Address, q?: WithdrawalsQuery, minTimestampUs?: number): Promise<WithdrawalsPage> {
283
305
  const path = account ? `/bridge/withdrawals/${account}` : "/bridge/withdrawals";
284
- const w = await this.get<WireWithdrawal[]>(path, {
285
- since: q?.since,
286
- since_id: q?.sinceId,
287
- limit: q?.limit,
288
- });
289
- return w.map(decodeWithdrawal);
306
+ const query = { since: q?.since, since_id: q?.sinceId, limit: q?.limit };
307
+ // `restUrl` ends in the API version, so this resolves to its v2 sibling.
308
+ const w = await this.get<WireWithdrawalsPage>(`/../v2${path}`, { ...query, timestamp: minTimestampUs });
309
+ return { withdrawals: w.withdrawals.map(decodeWithdrawal), timestampUs: w.timestamp };
290
310
  }
291
311
 
292
- async triggers(account: Address, q?: TriggersQueryRest): Promise<TriggersPage> {
312
+ async triggers(account: Address, q?: TriggersQueryRest, minTimestampUs?: number): Promise<TriggersPage> {
293
313
  const w = await this.get<WireTriggersPage>(`/clob/triggers/${account}`, {
294
314
  orderbook: q?.orderbook,
295
315
  limit: q?.limit,
316
+ timestamp: minTimestampUs,
296
317
  });
297
318
  return {
298
319
  triggers: w.triggers.map(decodeTrigger),