@pod-network/trade-sdk 0.3.0 → 0.4.1

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 (89) hide show
  1. package/README.md +99 -2
  2. package/dist/client.d.ts +45 -1
  3. package/dist/client.d.ts.map +1 -1
  4. package/dist/client.js +63 -2
  5. package/dist/client.js.map +1 -1
  6. package/dist/codec/bridge.d.ts +82 -0
  7. package/dist/codec/bridge.d.ts.map +1 -0
  8. package/dist/codec/bridge.js +114 -0
  9. package/dist/codec/bridge.js.map +1 -0
  10. package/dist/codec/decode.d.ts +15 -2
  11. package/dist/codec/decode.d.ts.map +1 -1
  12. package/dist/codec/decode.js +39 -0
  13. package/dist/codec/decode.js.map +1 -1
  14. package/dist/codec/resolution.d.ts +4 -1
  15. package/dist/codec/resolution.d.ts.map +1 -1
  16. package/dist/codec/resolution.js +6 -3
  17. package/dist/codec/resolution.js.map +1 -1
  18. package/dist/codec/units.d.ts.map +1 -1
  19. package/dist/codec/units.js +9 -1
  20. package/dist/codec/units.js.map +1 -1
  21. package/dist/datafeed.d.ts.map +1 -1
  22. package/dist/datafeed.js +15 -9
  23. package/dist/datafeed.js.map +1 -1
  24. package/dist/index.d.ts +3 -0
  25. package/dist/index.d.ts.map +1 -1
  26. package/dist/index.js +5 -0
  27. package/dist/index.js.map +1 -1
  28. package/dist/stores/resource.d.ts +14 -1
  29. package/dist/stores/resource.d.ts.map +1 -1
  30. package/dist/stores/resource.js +7 -1
  31. package/dist/stores/resource.js.map +1 -1
  32. package/dist/sync/candles.d.ts +62 -4
  33. package/dist/sync/candles.d.ts.map +1 -1
  34. package/dist/sync/candles.js +259 -42
  35. package/dist/sync/candles.js.map +1 -1
  36. package/dist/sync/sources.d.ts +5 -1
  37. package/dist/sync/sources.d.ts.map +1 -1
  38. package/dist/sync/sources.js +16 -0
  39. package/dist/sync/sources.js.map +1 -1
  40. package/dist/sync/withdrawals.d.ts +5 -0
  41. package/dist/sync/withdrawals.d.ts.map +1 -0
  42. package/dist/sync/withdrawals.js +172 -0
  43. package/dist/sync/withdrawals.js.map +1 -0
  44. package/dist/transport/claim.d.ts +160 -0
  45. package/dist/transport/claim.d.ts.map +1 -0
  46. package/dist/transport/claim.js +341 -0
  47. package/dist/transport/claim.js.map +1 -0
  48. package/dist/transport/jsonrpc.d.ts +16 -0
  49. package/dist/transport/jsonrpc.d.ts.map +1 -0
  50. package/dist/transport/jsonrpc.js +42 -0
  51. package/dist/transport/jsonrpc.js.map +1 -0
  52. package/dist/transport/rest.d.ts +23 -1
  53. package/dist/transport/rest.d.ts.map +1 -1
  54. package/dist/transport/rest.js +33 -2
  55. package/dist/transport/rest.js.map +1 -1
  56. package/dist/transport/ws.d.ts +4 -1
  57. package/dist/transport/ws.d.ts.map +1 -1
  58. package/dist/transport/ws.js.map +1 -1
  59. package/dist/types/public.d.ts +87 -0
  60. package/dist/types/public.d.ts.map +1 -1
  61. package/dist/types/wire.d.ts +43 -1
  62. package/dist/types/wire.d.ts.map +1 -1
  63. package/dist/write/delegation.d.ts.map +1 -1
  64. package/dist/write/delegation.js +2 -12
  65. package/dist/write/delegation.js.map +1 -1
  66. package/dist/write/index.d.ts +25 -0
  67. package/dist/write/index.d.ts.map +1 -1
  68. package/dist/write/index.js +20 -13
  69. package/dist/write/index.js.map +1 -1
  70. package/package.json +1 -1
  71. package/src/client.ts +77 -5
  72. package/src/codec/bridge.ts +138 -0
  73. package/src/codec/decode.ts +47 -4
  74. package/src/codec/resolution.ts +6 -3
  75. package/src/codec/units.ts +8 -1
  76. package/src/datafeed.ts +15 -9
  77. package/src/index.ts +16 -0
  78. package/src/stores/resource.ts +14 -1
  79. package/src/sync/candles.ts +297 -45
  80. package/src/sync/sources.ts +16 -1
  81. package/src/sync/withdrawals.ts +177 -0
  82. package/src/transport/claim.ts +434 -0
  83. package/src/transport/jsonrpc.ts +54 -0
  84. package/src/transport/rest.ts +50 -8
  85. package/src/transport/ws.ts +4 -1
  86. package/src/types/public.ts +94 -0
  87. package/src/types/wire.ts +47 -1
  88. package/src/write/delegation.ts +2 -12
  89. package/src/write/index.ts +58 -12
@@ -17,11 +17,13 @@ import { dec, usToMs, WAD } from "../codec/units.js";
17
17
  import { RESOLUTION_PAGE_BUCKETS, RESOLUTION_SECONDS } from "../codec/resolution.js";
18
18
  import { BaseResource, type ResourceHandle } from "../stores/resource.js";
19
19
  import type { Subscription } from "../transport/ws.js";
20
+ import { PodHttpError, type PodRestClient } from "../transport/rest.js";
20
21
  import type { SyncContext } from "./sources.js";
21
22
 
22
23
  export interface SeriesResource<Item> {
23
24
  get(): Item[] | undefined;
24
25
  subscribe(listener: () => void): () => void;
26
+ /** First committed value, not "window loaded" — see `Resource.ready`. */
25
27
  ready(): Promise<Item[]>;
26
28
  readonly error?: Error;
27
29
  setWindow(range: TimeRange): void;
@@ -40,6 +42,271 @@ const bmin = (a: bigint, b: bigint) => (a < b ? a : b);
40
42
  const REPLAY_SAFE_SECS = 3_600;
41
43
  const SEED_RESOLUTION: Resolution = "1h";
42
44
 
45
+ /** One canonical page window: an epoch-anchored span of `RESOLUTION_PAGE_BUCKETS`
46
+ * buckets, identified by its page index. */
47
+ export interface CandlePageWindow { page: number; fromMs: number; toMs: number }
48
+
49
+ /**
50
+ * One page's bars, plus how far the indexer had actually got. `watermarkMs` is
51
+ * `MAX_SAFE_INTEGER` when the page is known complete (a settled cache hit), so
52
+ * it never bounds a read it has nothing to say about.
53
+ */
54
+ interface CandlePage { bars: Bar[]; watermarkMs: number }
55
+
56
+ const pageSpanMs = (resolution: Resolution) =>
57
+ RESOLUTION_PAGE_BUCKETS[resolution] * RESOLUTION_SECONDS[resolution] * 1000;
58
+
59
+ /**
60
+ * Page index of `ms` on a resolution's epoch-anchored grid — the single
61
+ * definition of that grid. Every candle read goes through it on purpose: the
62
+ * server's `immutable` responses and the REST client's URL-keyed in-flight
63
+ * dedupe both only pay off while every request lands on the same boundaries, so
64
+ * a second implementation of this arithmetic would silently turn cache hits
65
+ * into node traffic.
66
+ */
67
+ export function candlePageAt(resolution: Resolution, ms: number): number {
68
+ return Math.floor(Math.max(0, ms) / pageSpanMs(resolution));
69
+ }
70
+
71
+ /**
72
+ * One page's canonical window — `undefined` when the page holds nothing but the
73
+ * forming bucket, because there is nothing closed to fetch. The window is
74
+ * clamped to the last closed bucket so it stays fully elapsed: those are the
75
+ * responses the server marks `immutable`, while a `to` in the future is
76
+ * `no-store` on every open.
77
+ */
78
+ export function candlePageWindow(
79
+ resolution: Resolution,
80
+ page: number,
81
+ nowMs = Date.now(),
82
+ ): CandlePageWindow | undefined {
83
+ const stepMs = RESOLUTION_SECONDS[resolution] * 1000;
84
+ const fromMs = page * pageSpanMs(resolution);
85
+ const toMs = Math.min(fromMs + pageSpanMs(resolution), Math.floor(nowMs / stepMs) * stepMs);
86
+ return toMs > fromMs ? { page, fromMs, toMs } : undefined;
87
+ }
88
+
89
+ /** The canonical windows covering `[fromMs, toMs)`, oldest first. */
90
+ export function candlePageWindows(
91
+ resolution: Resolution,
92
+ fromMs: number,
93
+ toMs: number,
94
+ nowMs = Date.now(),
95
+ ): CandlePageWindow[] {
96
+ const windows: CandlePageWindow[] = [];
97
+ const last = candlePageAt(resolution, toMs - 1);
98
+ for (let page = candlePageAt(resolution, fromMs); page <= last; page++) {
99
+ const window = candlePageWindow(resolution, page, nowMs);
100
+ if (window) windows.push(window);
101
+ }
102
+ return windows;
103
+ }
104
+
105
+ /**
106
+ * The live series' bars inside `range`, waiting up to `timeoutMs` for one to
107
+ * turn up. The series folds the tick stream, so this is where the forming
108
+ * bucket comes from — REST withholds it.
109
+ *
110
+ * Deliberately not `ready()`: that resolves on the series' FIRST commit, and a
111
+ * fresh series commits an empty seed while its load is still in flight (see
112
+ * `fetchPages`, which surfaces loading state before any page lands). Awaiting
113
+ * it hands back `[]` and gives up before the bucket it was called for arrives.
114
+ */
115
+ export function candleTailFrom(
116
+ series: SeriesResource<Bar>,
117
+ range: TimeRange,
118
+ timeoutMs: number,
119
+ ): Promise<Bar[]> {
120
+ const toMs = range.to ?? Number.MAX_SAFE_INTEGER;
121
+ const inWindow = () => (series.get() ?? []).filter((b) => b.time >= range.from && b.time < toMs);
122
+ const found = inWindow();
123
+ if (found.length) return Promise.resolve(found);
124
+ return new Promise((resolve) => {
125
+ let release: (() => void) | undefined;
126
+ let timer: ReturnType<typeof setTimeout> | undefined;
127
+ let settled = false;
128
+ const settle = (bars: Bar[]) => {
129
+ if (settled) return;
130
+ settled = true;
131
+ clearTimeout(timer);
132
+ release?.();
133
+ resolve(bars);
134
+ };
135
+ timer = setTimeout(() => settle(inWindow()), timeoutMs);
136
+ release = series.subscribe(() => {
137
+ const bars = inWindow();
138
+ if (bars.length) settle(bars);
139
+ });
140
+ // `subscribe` starts the source, which can emit synchronously inside the
141
+ // call above — before `release` was assigned. Release here or the listener
142
+ // (and with it the series' tick fold) is never let go.
143
+ if (settled) release();
144
+ });
145
+ }
146
+
147
+ /**
148
+ * Decoded pages, per REST client — so per host, never shared between clients
149
+ * pointed at different environments. A page is only stored once it can never
150
+ * change again, which takes BOTH of: a full span (not the trailing page, which
151
+ * still grows as buckets close) and an indexer watermark past the window's end.
152
+ * Wall clock is not enough — the server gates its own `immutable` header on
153
+ * solution time, and a window that has elapsed by the clock while the indexer
154
+ * lags comes back SHORT of its newest buckets. Caching that would pin a hole
155
+ * for the process's lifetime, which is the failure this whole read exists to
156
+ * avoid.
157
+ *
158
+ * Without this, overlapping requests re-decode the same bars, and overlap is
159
+ * the norm: a chart's opening window reaches further back than it has been
160
+ * served, and every pan-left ends mid-page. Decoding costs six `BigInt` parses
161
+ * per bar (see `decodeCandle`) on the thread that draws the chart.
162
+ */
163
+ const pageCaches = new WeakMap<PodRestClient, Map<string, Bar[]>>();
164
+ const PAGE_CACHE_MAX = 256;
165
+
166
+ /** One canonical page, served from this client's page cache when it is final. */
167
+ async function fetchCandlePage(
168
+ rest: PodRestClient,
169
+ id: MarketId,
170
+ resolution: Resolution,
171
+ window: CandlePageWindow,
172
+ ): Promise<CandlePage> {
173
+ const wholePage = window.toMs - window.fromMs === pageSpanMs(resolution);
174
+ const key = `${id}:${resolution}:${window.page}`;
175
+ let cache = pageCaches.get(rest);
176
+ if (!cache) pageCaches.set(rest, (cache = new Map()));
177
+ // Cached entries were verified final when stored, so a hit needs no re-check.
178
+ const hit = wholePage ? cache.get(key) : undefined;
179
+ if (hit) return { bars: hit, watermarkMs: Number.MAX_SAFE_INTEGER };
180
+ for (let attempt = 1; ; attempt++) {
181
+ try {
182
+ const page = await rest.candles(id, {
183
+ resolution,
184
+ from: window.fromMs,
185
+ to: window.toMs,
186
+ limit: RESOLUTION_PAGE_BUCKETS[resolution],
187
+ });
188
+ // Two different questions, so two predicates. Cacheable? Only a whole
189
+ // page the indexer has passed can never change again.
190
+ const covered = page.solutionNow >= window.toMs;
191
+ if (covered && wholePage) {
192
+ // Oldest insertion out first; the bound is on memory, not a policy.
193
+ if (cache.size >= PAGE_CACHE_MAX) cache.delete(cache.keys().next().value!);
194
+ cache.set(key, page.bars);
195
+ }
196
+ // Worth retrying? Only a WHOLE page that came back short — the indexer is
197
+ // behind by more than a page and a moment will fix it. The trailing page
198
+ // is clamped by OUR clock, so its shortfall is the normal state of
199
+ // affairs, and retrying it spins three requests and seconds of backoff
200
+ // against a healthy node on nothing worse than clock skew.
201
+ if (covered || !wholePage || attempt >= PAGE_ATTEMPTS) {
202
+ return { bars: page.bars, watermarkMs: page.solutionNow };
203
+ }
204
+ } catch (err) {
205
+ if (attempt >= PAGE_ATTEMPTS || !worthRetrying(err)) throw err;
206
+ }
207
+ // Exponential with jitter: the node sheds load in bursts, and a read that
208
+ // retries on a fixed short delay just lands inside the same burst.
209
+ const backoff = PAGE_RETRY_MS * 2 ** (attempt - 1) * (1 + Math.random());
210
+ await new Promise((resolve) => setTimeout(resolve, backoff));
211
+ }
212
+ }
213
+
214
+ /** How many pages a history read has in flight at once. */
215
+ const HISTORY_CONCURRENCY = 8;
216
+
217
+ /**
218
+ * Attempts per page, and the backoff between them. One failure must not decide
219
+ * a whole read: `fetchCandleHistory` rejects the window on a failed page, and a
220
+ * chart shows that as a hard error it will not retry on its own. Cold windows
221
+ * on a busy node do fail once and then answer in half a second, which is
222
+ * exactly what a retry is for. A 4xx (other than 429) is the server saying the
223
+ * request itself is wrong — asking again cannot help.
224
+ */
225
+ const PAGE_ATTEMPTS = 3;
226
+ const PAGE_RETRY_MS = 400;
227
+
228
+ const worthRetrying = (err: unknown) =>
229
+ !(err instanceof PodHttpError) || err.status === 429 || err.status >= 500;
230
+
231
+ /**
232
+ * Closed bars covering `[range.from, range.to)` — the one-shot read behind a
233
+ * chart's history request, with no resource, no subscription and no shared
234
+ * mutable state.
235
+ *
236
+ * A page that fails after its retries decides how much of the window is
237
+ * deliverable, and WHERE it failed is what matters:
238
+ *
239
+ * - at the old end, the answer is simply shorter — history stops at the gap,
240
+ * and the caller asks again for the older range when it needs it (a chart
241
+ * does exactly that on the next pan). Nothing is misrepresented, with one
242
+ * exception that must not slip through: if nothing at all survives, an empty
243
+ * answer would assert the window is empty, so that case rejects too.
244
+ * - anywhere inside, the read REJECTS. A chart treats the answer as the truth
245
+ * for the range it asked about and does not re-ask, so bars either side of a
246
+ * swallowed gap would draw a hole nobody can detect — the failure this whole
247
+ * read exists to prevent. Callers get an error they can retry.
248
+ *
249
+ * (The live series takes the opposite side of that trade — see `fetchPages`.)
250
+ */
251
+ export async function fetchCandleHistory(
252
+ rest: PodRestClient,
253
+ id: MarketId,
254
+ resolution: Resolution,
255
+ range: TimeRange,
256
+ nowMs = Date.now(),
257
+ ): Promise<Bar[]> {
258
+ const toMs = range.to ?? nowMs;
259
+ const windows = candlePageWindows(resolution, range.from, toMs, nowMs);
260
+ const pages: CandlePage[] = new Array(windows.length);
261
+ const failures: unknown[] = new Array(windows.length);
262
+ // Newest page first, `HISTORY_CONCURRENCY` at a time: a wide window is tens
263
+ // of pages (56 for a fortnight of 1m bars, thousands for a year), and firing
264
+ // them all at once queues the visible edge behind the oldest history on
265
+ // HTTP/1.1 and lands the whole fan-out on the node at once on HTTP/2.
266
+ let next = windows.length - 1;
267
+ const worker = async () => {
268
+ while (next >= 0) {
269
+ const i = next--;
270
+ try {
271
+ pages[i] = await fetchCandlePage(rest, id, resolution, windows[i]!);
272
+ } catch (err) {
273
+ failures[i] = err;
274
+ }
275
+ }
276
+ };
277
+ await Promise.all(Array.from({ length: Math.min(HISTORY_CONCURRENCY, windows.length) }, worker));
278
+
279
+ // An unfetched page reads as `undefined`; an empty page is an empty array, so
280
+ // "no bars here" and "never arrived" stay distinguishable.
281
+ const oldestOk = pages.findIndex((page) => page !== undefined);
282
+ if (windows.length && oldestOk === -1) throw failures.find((err) => err !== undefined);
283
+ for (let i = oldestOk; i < pages.length; i++) {
284
+ if (pages[i] === undefined) throw failures[i]; // a gap with bars on both sides
285
+ }
286
+ const kept = pages.slice(Math.max(0, oldestOk));
287
+ // The indexer's watermark bounds what any of these answers could cover:
288
+ // buckets past it are not history yet, they are simply unwritten. Claiming
289
+ // only up to there keeps a lagging indexer from looking like a complete
290
+ // window that happens to stop early.
291
+ const coveredToMs = kept.reduce((limit, page) => Math.min(limit, page.watermarkMs), toMs);
292
+ // Pages tile the window in ascending order and never overlap, so this is
293
+ // already sorted; the filter drops the partial buckets at either edge.
294
+ const bars = kept.flatMap((page) => page.bars).filter((b) => b.time >= range.from && b.time < coveredToMs);
295
+
296
+ // An EMPTY answer is not a small answer: it asserts "there are no bars in this
297
+ // window", and a chart takes that as settled and stops asking. Only the part
298
+ // of the window that was actually read can say that. So when nothing came
299
+ // back and the window was not covered — a failed page dropped off the old
300
+ // end, or the watermark short of the new end — surface the failure instead,
301
+ // which the caller retries. Otherwise a quiet stretch next to a shed page
302
+ // would hide that page's bars for as long as the chart lives.
303
+ if (!bars.length && (oldestOk > 0 || coveredToMs < toMs)) {
304
+ throw failures[oldestOk - 1]
305
+ ?? new Error(`candle history for ${id} is not indexed past ${coveredToMs}`);
306
+ }
307
+ return bars;
308
+ }
309
+
43
310
  export class CandleSeries implements SeriesResource<Bar> {
44
311
  private readonly base: BaseResource<Bar[]>;
45
312
  private handle: ResourceHandle<Bar[]> | undefined;
@@ -47,12 +314,9 @@ export class CandleSeries implements SeriesResource<Bar> {
47
314
  private readonly pages = new Map<number, Bar[]>(); // pageIndex -> closed bars
48
315
  private readonly live = new Map<number, Bar>(); // bucketStartMs -> forming bar
49
316
  private readonly resSecs: number;
50
- private readonly pageBuckets: number;
51
- private readonly pageSpanSecs: number;
52
317
 
53
318
  private window: TimeRange;
54
319
  private minPage: number | undefined;
55
- private maxPage: number | undefined;
56
320
  private _loading = false;
57
321
  private _hasMore = true;
58
322
  private lastTickUs = 0;
@@ -68,10 +332,7 @@ export class CandleSeries implements SeriesResource<Bar> {
68
332
  range?: TimeRange,
69
333
  ) {
70
334
  this.resSecs = RESOLUTION_SECONDS[resolution];
71
- this.pageBuckets = RESOLUTION_PAGE_BUCKETS[resolution];
72
- this.pageSpanSecs = this.resSecs * this.pageBuckets;
73
- const span = this.pageSpanSecs * 1000;
74
- this.window = range ?? { from: Date.now() - span };
335
+ this.window = range ?? { from: Date.now() - pageSpanMs(resolution) };
75
336
 
76
337
  this.base = new BaseResource<Bar[]>((h) => {
77
338
  this.handle = h;
@@ -105,6 +366,12 @@ export class CandleSeries implements SeriesResource<Bar> {
105
366
  this.tickSub?.unsubscribe();
106
367
  this.tickSub = undefined;
107
368
  this.handle = undefined;
369
+ // Folded buckets do not survive the fold being stopped: on re-subscribe
370
+ // the first `rebuild()` would re-emit a partially-folded bucket from
371
+ // whenever the series last ran, and a reader asking for the forming
372
+ // edge would take it as the answer. Closed pages are immutable, so they
373
+ // stay — dropping them would only refetch what is already correct.
374
+ this.live.clear();
108
375
  };
109
376
  });
110
377
  }
@@ -131,17 +398,12 @@ export class CandleSeries implements SeriesResource<Bar> {
131
398
 
132
399
  // --- internals ---
133
400
 
134
- private pageOf(secs: number): number {
135
- return Math.floor(secs / this.pageSpanSecs);
136
- }
137
-
138
401
  private async loadWindow(range: TimeRange): Promise<void> {
139
- const fromSecs = Math.floor(range.from / 1000);
140
- const toSecs = Math.floor((range.to ?? Date.now()) / 1000);
141
- const startPage = this.pageOf(fromSecs);
142
- const endPage = this.pageOf(Math.max(fromSecs, toSecs - 1));
143
- const nowSecs = Math.floor(Date.now() / 1000);
144
- const trailingPage = this.pageOf(nowSecs);
402
+ const nowMs = Date.now();
403
+ const toMs = range.to ?? nowMs;
404
+ const startPage = candlePageAt(this.resolution, range.from);
405
+ const endPage = candlePageAt(this.resolution, Math.max(range.from, toMs - 1));
406
+ const trailingPage = candlePageAt(this.resolution, nowMs);
145
407
 
146
408
  const wanted: number[] = [];
147
409
  for (let p = startPage; p <= endPage; p++) {
@@ -150,42 +412,32 @@ export class CandleSeries implements SeriesResource<Bar> {
150
412
  await this.fetchPages(wanted);
151
413
  }
152
414
 
415
+ /** The oldest page loaded — `loadOlder` walks down from it. */
416
+ private notePage(page: number): void {
417
+ this.minPage = Math.min(this.minPage ?? page, page);
418
+ }
419
+
153
420
  private async fetchPages(pageIndices: number[]): Promise<void> {
154
421
  if (!pageIndices.length) { this.rebuild(); return; }
155
422
  this._loading = true;
156
423
  this.rebuild(); // surface loading state
157
424
  try {
158
- // The trailing page's window is clamped to the last closed bucket: the
159
- // server returns only closed bars either way, so the content is
160
- // identical — but a fully-elapsed window is served `immutable`
161
- // (browser/CDN-cacheable; its URL rotates once per bucket close), while
162
- // a `to` in the future would be `no-store` on every open. The forming
163
- // bucket comes from the tick subscription (see prepareLiveEdge).
164
- const lastClosedMs = Math.floor(Date.now() / 1000 / this.resSecs) * this.resSecs * 1000;
425
+ const nowMs = Date.now(); // one clock read, so every page agrees on it
165
426
  await Promise.all(pageIndices.map(async (p) => {
166
- const fromMs = p * this.pageSpanSecs * 1000;
167
- const toMs = Math.min((p + 1) * this.pageSpanSecs * 1000, lastClosedMs);
168
- if (toMs <= fromMs) {
169
- // Page holds nothing but the forming bucket (it just started) —
170
- // nothing closed to fetch yet; keep bookkeeping consistent.
171
- this.pages.set(p, this.pages.get(p) ?? []);
172
- this.minPage = this.minPage === undefined ? p : Math.min(this.minPage, p);
173
- this.maxPage = this.maxPage === undefined ? p : Math.max(this.maxPage, p);
174
- return;
175
- }
427
+ const window = candlePageWindow(this.resolution, p, nowMs);
428
+ if (!window) { this.notePage(p); return; }
176
429
  try {
177
- const page = await this.ctx.rest.candles(this.id, {
178
- resolution: this.resolution,
179
- from: fromMs,
180
- to: toMs,
181
- limit: this.pageBuckets,
182
- });
183
- this.pages.set(p, page.bars);
184
- this.minPage = this.minPage === undefined ? p : Math.min(this.minPage, p);
185
- this.maxPage = this.maxPage === undefined ? p : Math.max(this.maxPage, p);
186
- if (page.bars.length === 0 && this.minPage === p) this._hasMore = false;
430
+ const { bars } = await fetchCandlePage(this.ctx.rest, this.id, this.resolution, window);
431
+ this.pages.set(p, bars);
432
+ this.notePage(p);
433
+ if (bars.length === 0 && this.minPage === p) this._hasMore = false;
187
434
  } catch {
188
- this.pages.set(p, this.pages.get(p) ?? []);
435
+ // A live series tolerates a missing page where `fetchCandleHistory`
436
+ // rejects: it will ask again. But leave the page MISSING rather than
437
+ // storing it empty — a stored empty page is indistinguishable from
438
+ // "no bars in this span", so a transient failure would become a
439
+ // permanent hole, since `loadWindow` only fetches pages it does not
440
+ // already have.
189
441
  }
190
442
  }));
191
443
  } finally {
@@ -14,7 +14,7 @@
14
14
  // REST re-seed via `onError` when `since` is too old (down too long).
15
15
 
16
16
  import type {
17
- Address, Balances, Market, MarketId, Orderbook, PositionsSnapshot, Status, Trigger,
17
+ Address, Balances, BridgeConfig, Market, MarketId, Orderbook, PositionsSnapshot, Status, Trigger,
18
18
  } from "../types/public.js";
19
19
  import type {
20
20
  WireMarketDynamics, WireOrderbook, WirePositionsPush, WireTriggersPush,
@@ -84,6 +84,21 @@ export function statusSource({ rest, ws }: SyncContext): ResourceSource<Status>
84
84
  };
85
85
  }
86
86
 
87
+ /** Static bridge config (ADR 0033 §5). Re-seeded on reconnect because an
88
+ * operator can change the token set or the withdraw limits under a long-lived
89
+ * tab, and a stale window would offer amounts the node now refuses. */
90
+ export function bridgeConfigSource({ rest, ws }: SyncContext): ResourceSource<BridgeConfig> {
91
+ return (h) => {
92
+ let alive = true;
93
+ const off = seedNowAndOnReconnect(ws, () => {
94
+ rest.bridgeConfig()
95
+ .then((c) => { if (alive) h.set(c); })
96
+ .catch((e) => { if (!h.current()) h.fail(e as Error); });
97
+ });
98
+ return () => { alive = false; off(); };
99
+ };
100
+ }
101
+
87
102
  export function marketsSource(
88
103
  { rest, ws, marketResyncMs, marketsCache }: SyncContext,
89
104
  ): ResourceSource<Market[]> {
@@ -0,0 +1,177 @@
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
3
+ // `pod_withdrawals` subscription.
4
+ //
5
+ // The two surfaces serve the identical shape, so a backfilled outcome is
6
+ // indistinguishable from one that arrived live — which is what lets a reconnect
7
+ // be a plain "fetch the gap" rather than a separate code path.
8
+ //
9
+ // Outcomes are terminal and immutable: an id appears once and never changes, so
10
+ // merging is last-write-wins on the id with no reconciliation.
11
+
12
+ import type { Address, Withdrawal } from "../types/public.js";
13
+ import type { WireWithdrawal } from "../types/wire.js";
14
+ import { decodeWithdrawal } from "../codec/decode.js";
15
+ import type { ResourceSource } from "../stores/resource.js";
16
+ import { seedNowAndOnReconnect, type SyncContext } from "./sources.js";
17
+
18
+ /** Page size for the backfill. The server caps at 1000 and defaults to 500. */
19
+ const PAGE_LIMIT = 500;
20
+
21
+ /** Pages to walk in one backfill before giving up, so a bad cursor can't spin
22
+ * forever. 50 pages × 500 covers 25k outcomes — far past any real account. */
23
+ const MAX_PAGES = 50;
24
+
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
+ export function withdrawalsSource(
30
+ { rest, ws }: SyncContext,
31
+ account: Address,
32
+ ): ResourceSource<Withdrawal[]> {
33
+ return (h) => {
34
+ let alive = true;
35
+ const byId = new Map<string, Withdrawal>();
36
+ // Cursor into the outcome log: the newest tick fully absorbed, plus the last
37
+ // id seen inside it. Both are needed because one tick can span a page — the
38
+ // deadline alone can only re-serve the tick's earlier rows or skip its later
39
+ // ones.
40
+ let sinceUs = 0;
41
+ let sinceId: Withdrawal["id"] | undefined;
42
+ let retries = 0;
43
+ let retryTimer: ReturnType<typeof setTimeout> | undefined;
44
+
45
+ const publish = () => {
46
+ // Newest first: a user reads their most recent withdrawal at the top, and
47
+ // the id tiebreak keeps a same-tick pair from reordering between renders.
48
+ h.set([...byId.values()].sort((a, b) => b.timeUs - a.timeUs || b.id.localeCompare(a.id)));
49
+ };
50
+
51
+ const absorb = (items: Withdrawal[]) => {
52
+ for (const w of items) {
53
+ byId.set(w.id, w);
54
+ // Never move the cursor backwards: an out-of-order arrival would
55
+ // otherwise re-serve ticks we already hold.
56
+ if (w.timeUs >= sinceUs) { sinceUs = w.timeUs; sinceId = w.id; }
57
+ }
58
+ };
59
+
60
+ /**
61
+ * Walk forward from the cursor until the log is exhausted.
62
+ *
63
+ * Serialised on `inflight` because two callers race by construction: the
64
+ * immediate seed and the socket's `open` overlap on a cold start, and a
65
+ * reconnect can fire while a retry's backfill is still paging. Both share
66
+ * the cursor, so concurrent loops would re-request each other's pages.
67
+ */
68
+ let inflight: Promise<void> | undefined;
69
+ const backfill = (): Promise<void> => (inflight ??= run().finally(() => { inflight = undefined; }));
70
+
71
+ const run = async () => {
72
+ try {
73
+ // Page against a cursor local to this run. The shared one is also moved
74
+ // by live pushes, and a push landing mid-backfill would jump the next
75
+ // page past the rest of an older tick — rows the forward-only cursor
76
+ // could then never come back for.
77
+ let pageSince = sinceUs;
78
+ let pageSinceId = sinceId;
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;
87
+ absorb(rows);
88
+ // Rows come back ascending, so the last one is this page's high-water
89
+ // mark — regardless of what the stream did to the shared cursor.
90
+ // Non-empty by the check above.
91
+ const last = rows[rows.length - 1]!;
92
+ pageSince = last.timeUs;
93
+ pageSinceId = last.id;
94
+ if (rows.length < PAGE_LIMIT) break;
95
+ }
96
+ // Once, after paging: publishing per page re-copies and re-sorts
97
+ // everything accumulated so far for a list the user sees for
98
+ // milliseconds — O(pages²) on exactly the accounts paging exists for.
99
+ //
100
+ // Unconditional, including when nothing was found. An account with no
101
+ // withdrawals must still reach a defined `[]`, or every consumer stays
102
+ // on "not loaded yet" and treats the first live outcome as its initial
103
+ // snapshot — silently swallowing a user's first-ever withdrawal.
104
+ publish();
105
+ } catch (e) {
106
+ // Publish on the failure path too, for exactly the reason the success
107
+ // path publishes unconditionally: a consumer left on "not loaded yet"
108
+ // treats the first live outcome as its initial snapshot and swallows it.
109
+ // A failed backfill is a reason to have no history — not a reason to
110
+ // misread the next thing that happens. `fail` records the error beside
111
+ // the value rather than replacing it, so a caller can read both.
112
+ publish();
113
+ // Only surface the failure when there is nothing to show; otherwise the
114
+ // stream is still feeding a usable list and a toast would be noise.
115
+ if (byId.size === 0) h.fail(e as Error);
116
+ }
117
+ };
118
+
119
+ const sub = ws.subscribe(
120
+ "pod_withdrawals",
121
+ // Live-only until a cursor exists. This is a replay channel, so the server
122
+ // accepts `since` only when its buffer still reaches back that far — and
123
+ // `since: 0` never does, so sending it would fail the subscribe every time
124
+ // and burn the retry budget below on a self-inflicted rejection. (The
125
+ // `since: 0` idiom belongs to the *state* channels, which answer it with a
126
+ // snapshot.) REST backfill covers history either way.
127
+ { account },
128
+ (result) => {
129
+ retries = 0;
130
+ // A frame means the subscription is healthy, so a retry armed by an
131
+ // earlier rejection has nothing left to fix. Letting it fire would call
132
+ // `resubscribe()` on a live subscription, which drops the server's id
133
+ // without an `eth_unsubscribe` and leaks one subscription per occurrence.
134
+ if (retryTimer) { clearTimeout(retryTimer); retryTimer = undefined; }
135
+ // One message per tick carrying that tick's outcomes for this account.
136
+ absorb((result as WireWithdrawal[]).map(decodeWithdrawal));
137
+ publish();
138
+ sub.update({ since: sinceUs }); // keep the resume point fresh for a reconnect
139
+ },
140
+ () => {
141
+ // Rejected — usually a `since` older than the replay buffer. Back off,
142
+ // re-seed over REST (which has no such horizon), and resubscribe; after
143
+ // a couple of failures drop `since` and settle for live-only.
144
+ //
145
+ // Bounded, because the other reason for a rejection is a node that
146
+ // doesn't serve this channel at all — an older build, since the app
147
+ // ships ahead of the fleet. Retrying that forever is a request every
148
+ // 30s for the lifetime of the tab, so give up and leave the REST-seeded
149
+ // list in place rather than polling a node that will never answer.
150
+ if (!alive || retries >= MAX_SUB_RETRIES) return;
151
+ retries++;
152
+ if (retryTimer) clearTimeout(retryTimer);
153
+ retryTimer = setTimeout(() => {
154
+ void backfill().then(() => {
155
+ if (!alive) return;
156
+ // Live-only until a real cursor exists (see the subscribe above), and
157
+ // dropped again after a couple of failures in case the replay buffer
158
+ // has outrun it.
159
+ sub.update({ since: retries > 2 || sinceUs === 0 ? undefined : sinceUs });
160
+ sub.resubscribe();
161
+ });
162
+ }, Math.min(30_000, 500 * 2 ** (retries - 1)));
163
+ },
164
+ );
165
+
166
+ // Seed immediately — REST needs no socket, so history paints without waiting
167
+ // on the handshake — and fill the gap again on every reconnect.
168
+ const offOpen = seedNowAndOnReconnect(ws, () => { if (alive) void backfill(); });
169
+
170
+ return () => {
171
+ alive = false;
172
+ offOpen();
173
+ if (retryTimer) clearTimeout(retryTimer);
174
+ sub.unsubscribe();
175
+ };
176
+ };
177
+ }