@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
package/src/client.ts CHANGED
@@ -1,15 +1,17 @@
1
1
  import type {
2
- Address, BackstopTransfer, Balances, LeaderboardPage, LeaderboardQuery, Market, MarketId,
3
- PositionsSnapshot, Resolution, Status, TimeRange, Trigger, TriggersQuery, TxExplorer, OrdersQuery,
2
+ Address, BackstopTransfer, Balances, Bar, BridgeConfig, LeaderboardPage, LeaderboardQuery, Market,
3
+ MarketId, PositionsSnapshot, Resolution, Status, TimeRange, Trigger, TriggersQuery, TxExplorer,
4
+ OrdersQuery, Withdrawal,
4
5
  } from "./types/public.js";
5
6
  import { PodRestClient } from "./transport/rest.js";
6
7
  import { PodWsClient, type WebSocketCtor } from "./transport/ws.js";
7
8
  import { BaseResource, combineResources, derivedResource, type Resource } from "./stores/resource.js";
8
9
  import {
9
- balancesSource, marketsSource, orderbookSource, positionsSource, statusSource, triggersSource,
10
- type MarketsCache, type SyncContext,
10
+ balancesSource, bridgeConfigSource, marketsSource, orderbookSource, positionsSource,
11
+ statusSource, triggersSource, type MarketsCache, type SyncContext,
11
12
  } from "./sync/sources.js";
12
- import { CandleSeries } from "./sync/candles.js";
13
+ import { withdrawalsSource } from "./sync/withdrawals.js";
14
+ import { CandleSeries, candleTailFrom, fetchCandleHistory } from "./sync/candles.js";
13
15
  import { OrderHistory } from "./sync/orders.js";
14
16
  import { enrichPositions } from "./sync/positions-live.js";
15
17
 
@@ -178,6 +180,32 @@ export class PodTradeClient {
178
180
  );
179
181
  }
180
182
 
183
+ /**
184
+ * Static bridge config: the claim chain, and each bridged token's L1 address,
185
+ * decimals and withdraw window (ADR 0033 §5). Everything a client needs to
186
+ * build an admissible withdrawal — see `maxWithdrawable` / `checkWithdrawAmount`.
187
+ *
188
+ * Re-seeded on reconnect rather than fetched once: an operator can change the
189
+ * token set or the limits under a long-lived tab, and a stale window would
190
+ * quietly offer amounts the node now refuses.
191
+ */
192
+ get bridgeConfig(): Resource<BridgeConfig> {
193
+ return this.memo("bridgeConfig", () => new BaseResource(bridgeConfigSource(this.ctx)));
194
+ }
195
+
196
+ /**
197
+ * This account's terminal withdrawal outcomes, newest first — live off
198
+ * `pod_withdrawals`, gap-filled over REST on every reconnect.
199
+ *
200
+ * Scoped to the **debited** account, which is the master for a delegated
201
+ * withdrawal, so pass the master address rather than the session key.
202
+ */
203
+ withdrawals(account: Address): Resource<Withdrawal[]> {
204
+ return this.memo(`withdrawals:${account}`, () =>
205
+ new BaseResource(withdrawalsSource(this.ctx, account)),
206
+ );
207
+ }
208
+
181
209
  /** Leaderboard (ranked accounts by net PnL). One-shot REST; paginate via
182
210
  * `{ limit, offset }`. Not a stream — call again to refresh. */
183
211
  leaderboard(query?: LeaderboardQuery): Promise<LeaderboardPage> {
@@ -209,6 +237,50 @@ export class PodTradeClient {
209
237
  return series;
210
238
  }
211
239
 
240
+ /**
241
+ * Closed bars for a window — a one-shot read, not a live resource.
242
+ *
243
+ * Chart history belongs here rather than on a `CandleSeries`: series are
244
+ * memoised per (market, resolution) and shared with whatever else is watching
245
+ * that market, so a history read that waited on the series' loading state
246
+ * could be resolved by an unrelated load finishing and report "no bars" for a
247
+ * window whose own pages were still in flight. This read owns its request:
248
+ * it resolves with the window's bars or rejects.
249
+ */
250
+ candleHistory(id: MarketId, resolution: Resolution, range: TimeRange): Promise<Bar[]> {
251
+ return fetchCandleHistory(this.ctx.rest, id, resolution, range);
252
+ }
253
+
254
+ /**
255
+ * The bars the live tick fold currently holds inside `range`, the forming
256
+ * bucket included — the other half of `candleHistory`, which can only ever
257
+ * return closed bars because REST withholds the open bucket.
258
+ *
259
+ * A chart asking for a window that reaches "now" on a market whose only
260
+ * activity is in that bucket has no closed history at all, and answering it
261
+ * "no bars" makes the chart latch the range as empty. Both datafeeds fall
262
+ * back to this instead.
263
+ *
264
+ * Subscribes for the wait rather than calling `ready()`, which both starts the
265
+ * resource without registering a listener (nothing would ever stop its WS fold
266
+ * again) and resolves on the empty seed — see `candleTailFrom`.
267
+ */
268
+ async candleTail(
269
+ id: MarketId,
270
+ resolution: Resolution,
271
+ range: TimeRange,
272
+ timeoutMs = 1_500,
273
+ ): Promise<Bar[]> {
274
+ // No range: this must not call setWindow on a series someone else is live on.
275
+ const series = this.candles(id, resolution);
276
+ const release = series.subscribe(() => {});
277
+ try {
278
+ return await candleTailFrom(series, range, timeoutMs);
279
+ } finally {
280
+ release();
281
+ }
282
+ }
283
+
212
284
  orders(account: Address, query?: OrdersQuery): OrderHistory {
213
285
  const key = `orders:${account}:${query ? JSON.stringify(query) : ""}`;
214
286
  return this.memo(key, () => new OrderHistory(this.ctx, account, query));
@@ -0,0 +1,138 @@
1
+ // Withdrawal amount arithmetic (ADR 0033 §2), mirroring the node's
2
+ // `WithdrawRules::check_clob_withdraw`.
3
+ //
4
+ // A CLOB withdrawal's `amount` is in pod's 18 decimals, but it settles on the
5
+ // claim chain in that token's decimals — so it has to be a WHOLE number of
6
+ // claim-chain units. The node rejects a remainder at admission rather than
7
+ // truncating it, which removes dust by construction; these helpers exist so a
8
+ // client never offers an amount that will be refused.
9
+ //
10
+ // The case that bites: pod's native USD maps to 6-decimal L1 USDC on devnet, so
11
+ // every native withdrawal must be a multiple of 1e12 wei and the per-token
12
+ // `min`/`max` from `/v1/bridge/config` are in those 6 decimals, not 18. A MAX
13
+ // button that keeps 18 decimals of precision produces amounts the node refuses.
14
+
15
+ import type { Address, BridgeConfig, BridgeToken } from "../types/public.js";
16
+ import { WAD_DECIMALS } from "./units.js";
17
+
18
+ /**
19
+ * The 18-decimal step a withdrawal of this token must be a multiple of:
20
+ * `10^(18 − decimals)`, or 1 for a token at least as fine as pod (which can
21
+ * represent every 18-decimal amount, so nothing is quantized away).
22
+ */
23
+ export function withdrawStep(decimals: number): bigint {
24
+ return decimals >= WAD_DECIMALS ? 1n : 10n ** BigInt(WAD_DECIMALS - decimals);
25
+ }
26
+
27
+ /** Floor an 18-decimal amount to a whole number of claim-chain units. Never negative. */
28
+ export function quantizeWithdrawAmount(amount: bigint, decimals: number): bigint {
29
+ if (amount <= 0n) return 0n;
30
+ const step = withdrawStep(decimals);
31
+ return (amount / step) * step;
32
+ }
33
+
34
+ /**
35
+ * Pod's 18 decimals → the token's claim-chain decimals: what the L1 `claim` call
36
+ * carries and what the claim hash commits to.
37
+ *
38
+ * Throws on a remainder rather than truncating, matching the node's admission
39
+ * check — silently flooring here is exactly the dust this design avoids. Use
40
+ * {@link quantizeWithdrawAmount} when rounding down is what you want.
41
+ */
42
+ export function toClaimAmount(amount: bigint, decimals: number): bigint {
43
+ if (decimals > WAD_DECIMALS) return amount * 10n ** BigInt(decimals - WAD_DECIMALS);
44
+ const step = withdrawStep(decimals);
45
+ const remainder = amount % step;
46
+ if (remainder !== 0n) {
47
+ throw new Error(
48
+ `withdraw amount ${amount} is not exactly representable in ${decimals} decimals ` +
49
+ `(remainder ${remainder}); use a multiple of ${step}`,
50
+ );
51
+ }
52
+ return amount / step;
53
+ }
54
+
55
+ /**
56
+ * The claim chain's decimals → pod's 18. Exact by construction: only amounts
57
+ * that were a whole number of claim-chain units are ever admitted, so scaling
58
+ * back up recovers the original.
59
+ */
60
+ export function toPodAmount(claimAmount: bigint, decimals: number): bigint {
61
+ if (decimals > WAD_DECIMALS) return claimAmount / 10n ** BigInt(decimals - WAD_DECIMALS);
62
+ return claimAmount * withdrawStep(decimals);
63
+ }
64
+
65
+ /**
66
+ * The largest amount of `balance` that this token's rules actually admit, in
67
+ * pod's 18 decimals: quantized down to a whole claim-chain unit, then clamped
68
+ * into `[min, max]` — which are in claim decimals, so the clamp has to happen
69
+ * after the conversion, not before.
70
+ *
71
+ * `0n` when the balance cannot clear `min`, which is the honest answer: there is
72
+ * no admissible withdrawal at all, and MAX should be disabled rather than
73
+ * offering an amount the node refuses.
74
+ */
75
+ export function maxWithdrawable(balance: bigint, token: BridgeToken): bigint {
76
+ if (balance <= 0n) return 0n;
77
+ const claim = toClaimAmount(quantizeWithdrawAmount(balance, token.decimals), token.decimals);
78
+ if (claim < token.min) return 0n;
79
+ return toPodAmount(claim > token.max ? token.max : claim, token.decimals);
80
+ }
81
+
82
+ /**
83
+ * Why the node would refuse a withdrawal, as a code plus the numbers behind it.
84
+ *
85
+ * A code rather than a sentence: this is a published, framework-agnostic
86
+ * package, so the wording belongs to the consumer that renders it — the same
87
+ * way `WithdrawalError` is a code the app turns into words. Each variant carries
88
+ * exactly the numbers its message needs, so a renderer quotes the real bound
89
+ * without re-deriving it and without defaulting fields that cannot be absent.
90
+ */
91
+ export type WithdrawRejection =
92
+ /** The token is not in the bridge's set, so it has no claim chain at all. */
93
+ | { code: "not_bridged" }
94
+ | { code: "non_positive"; decimals: number }
95
+ /** `step` is the 18-decimal multiple the amount must be of. */
96
+ | { code: "not_representable"; decimals: number; step: bigint }
97
+ /** `bound` is the limit that was crossed, in claim-chain decimals. */
98
+ | { code: "below_min" | "above_max"; decimals: number; bound: bigint };
99
+
100
+ /**
101
+ * Why the node would refuse this 18-decimal withdrawal, or `undefined` when it
102
+ * is admissible — the same checks `WithdrawRules::check_clob_withdraw` runs, so
103
+ * a client can disable the button and say why instead of discovering it from a
104
+ * revert.
105
+ *
106
+ * Mirroring the node's rules is deliberate and unlike the claim hash, which the
107
+ * ADR insists on fetching: the values here (`decimals`, `min`, `max`) all come
108
+ * from `/v1/bridge/config`, so only the rule *shape* could drift, and a client
109
+ * has to predict admissibility anyway to render MAX and enable the button.
110
+ *
111
+ * A missing `token` is itself a refusal: with no bridge configured for it there
112
+ * is no chain for the withdrawal to be claimed on.
113
+ */
114
+ export function checkWithdrawAmount(
115
+ amount: bigint,
116
+ token: BridgeToken | undefined,
117
+ ): WithdrawRejection | undefined {
118
+ if (!token) return { code: "not_bridged" };
119
+ const { decimals } = token;
120
+ if (amount <= 0n) return { code: "non_positive", decimals };
121
+ const step = withdrawStep(decimals);
122
+ if (amount % step !== 0n) return { code: "not_representable", decimals, step };
123
+ // Not `amount / step`: a token finer than pod's 18 scales *up*, so the step
124
+ // is 1 and the division would compare the wrong number against the bounds.
125
+ const claim = toClaimAmount(amount, decimals);
126
+ if (claim < token.min) return { code: "below_min", decimals, bound: token.min };
127
+ if (claim > token.max) return { code: "above_max", decimals, bound: token.max };
128
+ return undefined;
129
+ }
130
+
131
+ /** The bridge rules for a pod-side token, or undefined when it isn't bridged. */
132
+ export function bridgeTokenFor(
133
+ config: BridgeConfig | undefined,
134
+ podToken: Address,
135
+ ): BridgeToken | undefined {
136
+ const want = podToken.toLowerCase();
137
+ return config?.tokens.find((t) => t.podToken.toLowerCase() === want);
138
+ }
@@ -2,14 +2,16 @@
2
2
  // representations are normalized into bigint + millisecond numbers.
3
3
 
4
4
  import type {
5
- Bar, BackstopTransfer, Balances, LeaderboardEntry, LeaderboardPage, Market, Order,
5
+ Bar, BackstopTransfer, Balances, BridgeConfig, LeaderboardEntry, LeaderboardPage, Market, Order,
6
6
  Orderbook, PartialFill, PerpPosition, Position, PositionsSnapshot, SpotHolding,
7
7
  SpotPosition, Status, Trigger, MarketType, OrderDirection, OrderKind, OrderStatus, TriggerType,
8
+ Withdrawal,
8
9
  } from "../types/public.js";
9
10
  import type {
10
- WireBackstopTransfer, WireBalances, WireCandle, WireLeaderboard, WireMarketDynamics,
11
- WireMarketStatic, WireOrder, WireOrderbook, WirePartialFill, WirePerpPosition, WirePosition,
12
- WirePositionsSnapshot, WireSpotHolding, WireSpotPosition, WireStatus, WireTrigger,
11
+ WireBackstopTransfer, WireBalances, WireBridgeConfig, WireCandle, WireLeaderboard,
12
+ WireMarketDynamics, WireMarketStatic, WireOrder, WireOrderbook, WirePartialFill,
13
+ WirePerpPosition, WirePosition, WirePositionsSnapshot, WireSpotHolding, WireSpotPosition,
14
+ WireStatus, WireTrigger, WireWithdrawal,
13
15
  } from "../types/wire.js";
14
16
  import { dec, decOpt, endMsFromUs, toNumber, usToMs, usToMsOpt } from "./units.js";
15
17
 
@@ -276,3 +278,44 @@ export function decodeBackstopTransfer(w: WireBackstopTransfer): BackstopTransfe
276
278
  time: usToMs(w.timestamp_us),
277
279
  };
278
280
  }
281
+
282
+ export function decodeBridgeConfig(w: WireBridgeConfig): BridgeConfig {
283
+ return {
284
+ claimChainId: w.claim_chain_id,
285
+ sourceContract: w.source_contract,
286
+ version: w.version,
287
+ tokens: w.tokens.map((t) => ({
288
+ podToken: t.pod_token,
289
+ l1Token: t.l1_token,
290
+ decimals: t.decimals,
291
+ min: dec(t.min),
292
+ max: dec(t.max),
293
+ })),
294
+ };
295
+ }
296
+
297
+ /**
298
+ * One withdrawal outcome.
299
+ *
300
+ * An unrecognised `error` spelling is carried through **verbatim**, never
301
+ * dropped. The node's reason enum is extensible and this app ships ahead of the
302
+ * fleet, so filtering to the spellings this build knows would turn a *failed*
303
+ * withdrawal into a claimable-looking one: the caller announces that the money
304
+ * is on its way and then waits for an L1 event that can never fire. Presence is
305
+ * what carries the meaning here — any reason at all means no claim — so only
306
+ * presence is decoded, and naming the reason is left to whatever renders it.
307
+ */
308
+ export function decodeWithdrawal(w: WireWithdrawal): Withdrawal {
309
+ return {
310
+ id: w.withdrawal_id,
311
+ withdrawer: w.withdrawer,
312
+ to: w.to,
313
+ token: w.token,
314
+ amount: dec(w.amount),
315
+ // `||`, not `??`: an empty string is the wire saying "no reason", and it
316
+ // would otherwise be a present-but-falsy value that every `if (w.error)`
317
+ // reads as success while `error !== undefined` reads as failure.
318
+ error: w.error || undefined,
319
+ timeUs: w.timestamp_us,
320
+ };
321
+ }
@@ -1,6 +1,9 @@
1
1
  import type { Resolution } from "../types/public.js";
2
2
 
3
- /** Bucket width per resolution, in seconds. 1M is calendar-variable; see pages. */
3
+ /**
4
+ * Bucket width per resolution, in seconds — the widths the server buckets by,
5
+ * which every page boundary here is derived from.
6
+ */
4
7
  export const RESOLUTION_SECONDS: Record<Resolution, number> = {
5
8
  "1m": 60,
6
9
  "5m": 300,
@@ -10,7 +13,7 @@ export const RESOLUTION_SECONDS: Record<Resolution, number> = {
10
13
  "4h": 14_400,
11
14
  "1d": 86_400,
12
15
  "1W": 604_800,
13
- "1M": 2_592_000, // nominal 30d; only used as a hint, pages use calendar months
16
+ "1M": 2_592_000, // a nominal 30d month: what the indexer buckets by, not calendar months
14
17
  };
15
18
 
16
19
  /**
@@ -29,7 +32,7 @@ export const RESOLUTION_PAGE_BUCKETS: Record<Resolution, number> = {
29
32
  "4h": 180, // ~30 days
30
33
  "1d": 365, // ~1 year
31
34
  "1W": 260, // ~5 years
32
- "1M": 120, // ~decade (calendar-month buckets)
35
+ "1M": 120, // ~decade (nominal 30-day buckets, epoch-anchored — see above)
33
36
  };
34
37
 
35
38
  export const RESOLUTIONS = Object.keys(RESOLUTION_SECONDS) as Resolution[];
@@ -2,6 +2,11 @@
2
2
  // strings; wire timestamps are microseconds. Public surface uses `bigint`
3
3
  // (1e18-scaled) and millisecond `number` timestamps.
4
4
 
5
+ // "wad" is the DappHub/MakerDAO name for a fixed-point number carrying 18
6
+ // digits of precision, which is the scale every pod amount is in. Spelled out
7
+ // because the term is only obvious if you have met it before, and code that
8
+ // mixes scales — bridge withdrawals settle in the claim-chain token's decimals,
9
+ // not pod's — reads very differently depending on whether you know that.
5
10
  export const WAD = 1_000_000_000_000_000_000n; // 1e18
6
11
  export const WAD_DECIMALS = 18;
7
12
 
@@ -110,7 +115,9 @@ export function parseAmount(value: string, decimals: number = WAD_DECIMALS): big
110
115
  const neg = value.trim().startsWith("-");
111
116
  const clean = neg ? value.trim().slice(1) : value.trim();
112
117
  const [whole = "0", frac = ""] = clean.split(".");
118
+ if (whole === "" && frac === "") throw new SyntaxError("Cannot convert empty amount to a BigInt");
113
119
  const fracPadded = (frac + "0".repeat(decimals)).slice(0, decimals);
114
- const scaled = BigInt(whole) * 10n ** BigInt(decimals) + BigInt(fracPadded || "0");
120
+ const wholePart = whole === "" && frac !== "" ? "0" : whole;
121
+ const scaled = BigInt(wholePart) * 10n ** BigInt(decimals) + BigInt(fracPadded || "0");
115
122
  return neg ? -scaled : scaled;
116
123
  }
package/src/datafeed.ts CHANGED
@@ -5,6 +5,7 @@
5
5
  import type { PodTradeClient } from "./client.js";
6
6
  import type { Bar, MarketId, Resolution } from "./types/public.js";
7
7
  import { toNumber } from "./codec/units.js";
8
+ import { RESOLUTION_SECONDS } from "./codec/resolution.js";
8
9
 
9
10
  const TV_TO_RESOLUTION: Record<string, Resolution> = {
10
11
  "1": "1m", "5": "5m", "15": "15m", "30": "30m",
@@ -56,15 +57,20 @@ export function createPodDatafeed(client: PodTradeClient): unknown {
56
57
  try {
57
58
  const id = (symbolInfo.ticker ?? symbolInfo.name) as MarketId;
58
59
  const res = TV_TO_RESOLUTION[resolution] ?? "1h";
59
- const series = client.candles(id, res, {
60
- from: periodParams.from * 1000,
61
- to: periodParams.to * 1000,
62
- });
63
- const bars = await series.ready();
64
- const inRange = bars
65
- .filter((b) => b.time >= periodParams.from * 1000 && b.time < periodParams.to * 1000)
66
- .map((b) => toTvBar(b));
67
- onResult(inRange, { noData: inRange.length === 0 });
60
+ // One-shot read, never the memoised series — see client.candleHistory.
61
+ const range = { from: periodParams.from * 1000, to: periodParams.to * 1000 };
62
+ let bars = await client.candleHistory(id, res, range);
63
+ // Nothing closed in a window that reaches into the forming bucket: that
64
+ // bucket is all this market has, and `noData` would make TV stop asking
65
+ // for it. Tested against the bucket, not `Date.now()`: TV rounds `to` to
66
+ // whole seconds, so a window covering the open bucket can still end a
67
+ // few hundred ms in the past.
68
+ const bucketMs = RESOLUTION_SECONDS[res] * 1000;
69
+ if (!bars.length && range.to > Math.floor(Date.now() / bucketMs) * bucketMs) {
70
+ bars = await client.candleTail(id, res, range);
71
+ }
72
+ const tv = bars.map((b) => toTvBar(b));
73
+ onResult(tv, { noData: tv.length === 0 });
68
74
  } catch (e) {
69
75
  onError(String(e));
70
76
  }
package/src/index.ts CHANGED
@@ -47,3 +47,19 @@ export {
47
47
  export {
48
48
  RESOLUTION_SECONDS, RESOLUTION_PAGE_BUCKETS, RESOLUTIONS, isResolution,
49
49
  } from "./codec/resolution.js";
50
+
51
+ // Withdrawal amount arithmetic (ADR 0033). Read-side, so a UI can size and
52
+ // validate a withdrawal without pulling the signing entry.
53
+ export {
54
+ withdrawStep, quantizeWithdrawAmount, toClaimAmount, toPodAmount,
55
+ maxWithdrawable, checkWithdrawAmount, type WithdrawRejection, bridgeTokenFor,
56
+ } from "./codec/bridge.js";
57
+ // Following a withdrawal onto the claim chain.
58
+ export {
59
+ fetchClaimStatus, waitForClaim, watchClaims, CLAIM_TOPIC,
60
+ type ClaimStatus, type ClaimOutcome, type WaitForClaimOptions,
61
+ type ClaimWatcher, type WatchClaimsOptions,
62
+ } from "./transport/claim.js";
63
+ // Only the options type: `WaitForClaimOptions` extends it, so declaration emit
64
+ // needs it public. The functions themselves stay internal.
65
+ export type { RpcOptions } from "./transport/jsonrpc.js";
@@ -5,6 +5,13 @@
5
5
  export interface Resource<T> {
6
6
  get(): T | undefined;
7
7
  subscribe(listener: () => void): () => void;
8
+ /**
9
+ * Resolves on the FIRST value the source commits — which for a resource that
10
+ * seeds progressively is the initial, possibly empty, seed and not "fully
11
+ * loaded". Do not use it to decide that a window has finished loading (that
12
+ * mistake drew empty charts); for a bounded read that must be complete, use a
13
+ * one-shot call such as `client.candleHistory`.
14
+ */
8
15
  ready(): Promise<T>;
9
16
  /** Restart the source for a fresh seed (optional — see BaseResource). */
10
17
  refresh?(): void;
@@ -62,7 +69,13 @@ export class BaseResource<T> implements Resource<T> {
62
69
  return this.readyPromise;
63
70
  }
64
71
 
65
- /** Force teardown (used by the client on close). */
72
+ /**
73
+ * Force teardown, ignoring the subscriber count — for `client.close()`, not
74
+ * for one consumer that is done with a shared resource. Resources are
75
+ * memoised per key, so destroying one another consumer still holds stops its
76
+ * source underneath it; releasing your `subscribe()` teardown is enough,
77
+ * since the last one out stops the source anyway.
78
+ */
66
79
  destroy(): void {
67
80
  this.stop();
68
81
  }