@pod-network/trade-sdk 0.11.0 → 0.13.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.
@@ -8,8 +8,8 @@
8
8
  // implied_leverage = (Σ current perp notional + notional) / perps_equity
9
9
  // liquidation = mark where equity falls to Σ maintenance margin (im/2)
10
10
 
11
- import type { Market, PerpPosition, PositionsSnapshot, Trigger } from "../types/public.js";
12
- import { div, imRate, mul } from "../codec/fixed.js";
11
+ import type { Market, Orderbook, PerpPosition, PositionsSnapshot, Trigger } from "../types/public.js";
12
+ import { div, imRate, min, mul } from "../codec/fixed.js";
13
13
  import { alignSize, parseAmount, toNumber, WAD } from "../codec/units.js";
14
14
 
15
15
  export interface ReturnPriceInput {
@@ -220,3 +220,57 @@ export function closePreview(
220
220
  fee: mul(notional, input.feeRate ?? 0n),
221
221
  };
222
222
  }
223
+
224
+ export interface FillEstimate {
225
+ /** Base size the book fills within `limit` (≤ `size`). */
226
+ filled: bigint;
227
+ /** The price the whole fill clears at were this the batch's only order;
228
+ * undefined when nothing fills. A batch clears every match at one price and
229
+ * a market order never sets it, so this is at least the last level reached —
230
+ * not an average across the levels. */
231
+ price?: bigint;
232
+ /** How much worse `price` is than the best level, in percent — the cost of
233
+ * the size alone, spread excluded. */
234
+ slippagePct?: number;
235
+ /** The walk ran off the last level given while still inside `limit`. On a
236
+ * depth-truncated book `filled` is then a floor, not an estimate. */
237
+ exhausted: boolean;
238
+ }
239
+
240
+ /**
241
+ * What a taker order of `size` (base, magnitude) would fill against `book`:
242
+ * walks the opposite side best-first — asks for a long, bids for a short — and
243
+ * stops at `limit`, a market order's protective price. Grouped levels make the
244
+ * prices approximate to the grouping.
245
+ */
246
+ export function estimateFill(
247
+ book: Pick<Orderbook, "bids" | "asks">,
248
+ side: "long" | "short",
249
+ size: bigint,
250
+ limit?: bigint,
251
+ ): FillEstimate {
252
+ const levels = side === "long" ? book.asks : book.bids;
253
+ const within = (p: bigint) => limit === undefined || (side === "long" ? p <= limit : p >= limit);
254
+ let filled = 0n;
255
+ let left = 0n; // volume the last level reached still holds
256
+ let i = 0;
257
+ for (; i < levels.length && filled < size; i++) {
258
+ const l = levels[i]!;
259
+ if (!within(l.price)) break;
260
+ const take = min(l.volume, size - filled);
261
+ filled += take;
262
+ left = l.volume - take;
263
+ }
264
+ const exhausted = filled < size && i === levels.length;
265
+ if (filled === 0n) return { filled, exhausted };
266
+ // The clearing range runs from the last level matched to the first level left
267
+ // unmatched — that same level when only part of it was taken — and settles at
268
+ // its midpoint, never past the order's own limit (doc/protocol/orderbook.md, Clearing).
269
+ const last = levels[i - 1]!.price;
270
+ const unmatched = left > 0n ? last : levels[i]?.price;
271
+ let price = unmatched === undefined ? last : (last + unmatched) / 2n;
272
+ if (limit !== undefined && !within(price)) price = limit;
273
+ const best = levels[0]!.price;
274
+ const worse = side === "long" ? price - best : best - price;
275
+ return { filled, price, slippagePct: (Number(worse) / Number(best)) * 100, exhausted };
276
+ }
@@ -5,7 +5,7 @@
5
5
  import type { Address, Order, OrderEvent, OrdersQuery } from "../types/public.js";
6
6
  import type { WireOrdersFrame } from "../types/wire.js";
7
7
  import { applyOrdersFrame } from "../codec/orders-v2.js";
8
- import { BaseResource, type ResourceHandle } from "../stores/resource.js";
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
11
  import type { SyncContext } from "./sources.js";
@@ -29,6 +29,7 @@ export class OrderHistory implements SeriesResource<Order> {
29
29
  private readonly ctx: SyncContext,
30
30
  private readonly account: Address,
31
31
  private readonly query: OrdersQuery = {},
32
+ slot?: SnapshotSlot,
32
33
  ) {
33
34
  this.stream = new ResumableStream({
34
35
  ws: ctx.ws,
@@ -44,10 +45,12 @@ export class OrderHistory implements SeriesResource<Order> {
44
45
  this.stream.stop();
45
46
  this.handle = undefined;
46
47
  };
47
- });
48
+ }, slot);
48
49
  }
49
50
 
50
51
  get(): Order[] | undefined { return this.base.get(); }
52
+ lastKnown(): Snapshot<Order[]> | undefined { return this.base.lastKnown(); }
53
+ isProvisional(): boolean { return this.base.isProvisional(); }
51
54
  subscribe(listener: () => void): () => void { return this.base.subscribe(listener); }
52
55
  ready(): Promise<Order[]> { return this.base.ready(); }
53
56
  get error(): Error | undefined { return this.base.error; }
@@ -22,6 +22,7 @@ import type {
22
22
  import {
23
23
  decodeMarketDynamics, decodeOrderbook, decodePositions, decodeTrigger,
24
24
  } from "../codec/decode.js";
25
+ import { parseBig, stringifyBig } from "../codec/json.js";
25
26
  import type { PodRestClient } from "../transport/rest.js";
26
27
  import type { PodWsClient } from "../transport/ws.js";
27
28
  import type { ResourceSource } from "../stores/resource.js";
@@ -51,15 +52,15 @@ export interface MarketsCache {
51
52
 
52
53
  // Static-list serialization for MarketsCache. Version is embedded in the
53
54
  // payload: a mismatch after an SDK format change just falls back to a cold
54
- // start. bigints round-trip as "<digits>n" strings.
55
+ // start.
55
56
  // 2: `status`/`minNotional` became required and the fees stopped decoding to 0.
56
- const MARKETS_CACHE_VERSION = 2;
57
+ // 3: bigints are tagged objects, not "<digits>n" strings (see codec/json).
58
+ const MARKETS_CACHE_VERSION = 3;
57
59
  const serializeMarkets = (markets: Market[]): string =>
58
- JSON.stringify({ v: MARKETS_CACHE_VERSION, markets }, (_k, v: unknown) => (typeof v === "bigint" ? `${v}n` : v));
60
+ stringifyBig({ v: MARKETS_CACHE_VERSION, markets });
59
61
  const parseCachedMarkets = (raw: string | null): Market[] | undefined => {
60
62
  if (!raw) return undefined;
61
- const data = JSON.parse(raw, (_k, v: unknown) =>
62
- typeof v === "string" && /^-?\d+n$/.test(v) ? BigInt(v.slice(0, -1)) : v) as { v: number; markets: Market[] };
63
+ const data = parseBig<{ v: number; markets: Market[] }>(raw);
63
64
  return data?.v === MARKETS_CACHE_VERSION ? data.markets : undefined;
64
65
  };
65
66
 
@@ -109,7 +110,11 @@ export function marketsSource(
109
110
  // Stable display order = the static /clob/markets order, so the list never
110
111
  // reshuffles as dynamics arrive (markets not yet in the static list sort last).
111
112
  const orderIndex = new Map<string, number>();
112
- const publish = () => h.set(
113
+ // Until REST's static list lands, anything published is built on the cached
114
+ // list (possibly delisted markets, partial prices) and must stay provisional,
115
+ // whichever path — cache, WS dynamics or stats — happens to publish it.
116
+ let staticLoaded = false;
117
+ const publish = () => (staticLoaded ? h.set : h.seed)(
113
118
  [...byId.values()]
114
119
  // pod_markets dynamics can arrive (and create an entry) before the static
115
120
  // /clob/markets seed — those lack base/quote/name. Don't expose a market
@@ -147,6 +152,7 @@ export function marketsSource(
147
152
  orderIndex.set(m.id, i);
148
153
  byId.set(m.id, { ...byId.get(m.id), ...m });
149
154
  });
155
+ staticLoaded = true;
150
156
  publish();
151
157
  try { marketsCache?.set(serializeMarkets(markets)); } catch { /* storage denied/full */ }
152
158
  }).catch((e) => { if (!byId.size) h.fail(e); });