@pod-network/trade-sdk 0.9.0 → 0.11.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.
- package/README.md +6 -4
- package/dist/client.d.ts +32 -4
- package/dist/client.d.ts.map +1 -1
- package/dist/client.js +50 -5
- package/dist/client.js.map +1 -1
- package/dist/codec/activity.d.ts +11 -0
- package/dist/codec/activity.d.ts.map +1 -0
- package/dist/codec/activity.js +33 -0
- package/dist/codec/activity.js.map +1 -0
- package/dist/codec/decode.d.ts +14 -6
- package/dist/codec/decode.d.ts.map +1 -1
- package/dist/codec/decode.js +58 -24
- package/dist/codec/decode.js.map +1 -1
- package/dist/codec/orders-v2.d.ts +9 -3
- package/dist/codec/orders-v2.d.ts.map +1 -1
- package/dist/codec/orders-v2.js +12 -9
- package/dist/codec/orders-v2.js.map +1 -1
- package/dist/index.d.ts +3 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +2 -0
- package/dist/index.js.map +1 -1
- package/dist/sync/activity.d.ts +58 -0
- package/dist/sync/activity.d.ts.map +1 -0
- package/dist/sync/activity.js +259 -0
- package/dist/sync/activity.js.map +1 -0
- package/dist/sync/order-preview.d.ts +3 -0
- package/dist/sync/order-preview.d.ts.map +1 -1
- package/dist/sync/order-preview.js +56 -0
- package/dist/sync/order-preview.js.map +1 -1
- package/dist/sync/orders.d.ts +4 -64
- package/dist/sync/orders.d.ts.map +1 -1
- package/dist/sync/orders.js +40 -190
- package/dist/sync/orders.js.map +1 -1
- package/dist/sync/pnl-history.d.ts +140 -0
- package/dist/sync/pnl-history.d.ts.map +1 -0
- package/dist/sync/pnl-history.js +617 -0
- package/dist/sync/pnl-history.js.map +1 -0
- package/dist/sync/stream.d.ts +101 -0
- package/dist/sync/stream.d.ts.map +1 -0
- package/dist/sync/stream.js +243 -0
- package/dist/sync/stream.js.map +1 -0
- package/dist/transport/rest.d.ts +36 -4
- package/dist/transport/rest.d.ts.map +1 -1
- package/dist/transport/rest.js +43 -10
- package/dist/transport/rest.js.map +1 -1
- package/dist/transport/ws.d.ts +5 -1
- package/dist/transport/ws.d.ts.map +1 -1
- package/dist/transport/ws.js.map +1 -1
- package/dist/types/public.d.ts +62 -23
- package/dist/types/public.d.ts.map +1 -1
- package/dist/types/wire.d.ts +98 -16
- package/dist/types/wire.d.ts.map +1 -1
- package/dist/write/index.d.ts +3 -3
- package/dist/write/index.d.ts.map +1 -1
- package/dist/write/index.js +0 -3
- package/dist/write/index.js.map +1 -1
- package/package.json +1 -1
- package/src/client.ts +54 -7
- package/src/codec/activity.ts +46 -0
- package/src/codec/decode.ts +65 -30
- package/src/codec/orders-v2.ts +24 -11
- package/src/index.ts +7 -1
- package/src/sync/activity.ts +266 -0
- package/src/sync/order-preview.ts +63 -0
- package/src/sync/orders.ts +41 -187
- package/src/sync/pnl-history.ts +639 -0
- package/src/sync/stream.ts +270 -0
- package/src/transport/rest.ts +62 -14
- package/src/transport/ws.ts +5 -1
- package/src/types/public.ts +62 -26
- package/src/types/wire.ts +105 -18
- package/src/write/index.ts +3 -6
|
@@ -0,0 +1,639 @@
|
|
|
1
|
+
// PnL change over a past window, folded backwards from the live snapshot.
|
|
2
|
+
//
|
|
3
|
+
// Total PnL is continuous through banking (realized ⇄ unrealized), so the
|
|
4
|
+
// change between a past point t and the reference tick needs no leg
|
|
5
|
+
// boundaries and no banked amounts:
|
|
6
|
+
// D(t) = Σ value_m(t) − Σ value_m(ref) − Σ_{events in (t, ref]} (F_b − p_b)·Δs_b
|
|
7
|
+
// value_m = (mark − F)·size spot: F = 0, mark = last clearing
|
|
8
|
+
// A spot withdrawal removes proportional cost without realizing, i.e. it is a
|
|
9
|
+
// sell at the holding's average cost.
|
|
10
|
+
//
|
|
11
|
+
// Fills page newest-first, so the walk streams: the newest points only need
|
|
12
|
+
// the newest pages, and each chunk is yielded as soon as its fills are in.
|
|
13
|
+
|
|
14
|
+
import type { Address, MarketId, MoneyActivity } from "../types/public.js";
|
|
15
|
+
import { div, mul } from "../codec/fixed.js";
|
|
16
|
+
import { dec } from "../codec/units.js";
|
|
17
|
+
import type { WireFillRow, WireSolutionRow } from "../types/wire.js";
|
|
18
|
+
import { rpc, type RpcOptions } from "../transport/jsonrpc.js";
|
|
19
|
+
import { PodHttpError, type PodRestClient } from "../transport/rest.js";
|
|
20
|
+
|
|
21
|
+
export interface PnlPoint {
|
|
22
|
+
time: number;
|
|
23
|
+
pnl: bigint;
|
|
24
|
+
/** Absolute account value at the point; absent when the node does not
|
|
25
|
+
* serve the activity feed the deposits and transfers come from. */
|
|
26
|
+
accountValue?: bigint;
|
|
27
|
+
}
|
|
28
|
+
export interface PnlHistory { points: PnlPoint[]; warnings: string[] }
|
|
29
|
+
export interface PnlHistoryQuery {
|
|
30
|
+
/** ms */
|
|
31
|
+
from: number;
|
|
32
|
+
/** ms; defaults to the engine's current tick */
|
|
33
|
+
to?: number;
|
|
34
|
+
/** Sample count, at most 500 (the default). The step is the window divided
|
|
35
|
+
* by it, rounded up to a whole batch interval. */
|
|
36
|
+
points?: number;
|
|
37
|
+
}
|
|
38
|
+
/** One step of the backward walk. Chunks arrive newest-first; within a chunk
|
|
39
|
+
* points are ascending. `pnl` is relative to the reference tick (0 at the
|
|
40
|
+
* newest point), so a chart anchored at `from` shifts by the last chunk's
|
|
41
|
+
* first point once `done`. */
|
|
42
|
+
export interface PnlHistoryChunk { points: PnlPoint[]; done: boolean; warnings: string[] }
|
|
43
|
+
|
|
44
|
+
export interface PnlLeg {
|
|
45
|
+
market: MarketId;
|
|
46
|
+
kind: "perp" | "spot";
|
|
47
|
+
size: bigint;
|
|
48
|
+
/** perp: fundingBasis − costBasis; spot: costBasis. Absent when the node
|
|
49
|
+
* does not serve the bases; the residual check is then skipped. */
|
|
50
|
+
basis?: bigint;
|
|
51
|
+
}
|
|
52
|
+
export interface PnlEvent {
|
|
53
|
+
/** Absent on a cash movement. */
|
|
54
|
+
market?: MarketId;
|
|
55
|
+
timeUs: number;
|
|
56
|
+
/** Signed size for a market event; the signed native amount for `cash`. */
|
|
57
|
+
deltaSize: bigint;
|
|
58
|
+
/** Fill price; unused for withdrawals, deposits and cash. */
|
|
59
|
+
price: bigint;
|
|
60
|
+
/** `withdraw` and `deposit` are spot token movements: a withdrawal leaves at
|
|
61
|
+
* the average cost, a deposit arrives marked at the tick's clearing price.
|
|
62
|
+
* `cash` is native money in or out, which moves account value only. */
|
|
63
|
+
kind: "fill" | "withdraw" | "deposit" | "sweep" | "cash";
|
|
64
|
+
}
|
|
65
|
+
export interface PnlTick { mark: bigint; funding: bigint }
|
|
66
|
+
export interface PnlFoldInput {
|
|
67
|
+
refTimeUs: number;
|
|
68
|
+
/** One per market touched by legs or events. */
|
|
69
|
+
legs: PnlLeg[];
|
|
70
|
+
events: PnlEvent[];
|
|
71
|
+
/** Ascending, all ≤ refTimeUs. */
|
|
72
|
+
gridUs: number[];
|
|
73
|
+
/** Newest tick at or before `timeUs`. */
|
|
74
|
+
tickAt: (market: MarketId, timeUs: number) => PnlTick | undefined;
|
|
75
|
+
/** Account value at the reference tick; points carry `accountValue` when given. */
|
|
76
|
+
accountValueRef?: bigint;
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
const RESIDUAL_TOLERANCE = 10n ** 12n;
|
|
80
|
+
// Within a tick the engine runs sweeps, then deposits, then matching, then
|
|
81
|
+
// transfers and withdrawals; walking backwards undoes them in the opposite
|
|
82
|
+
// order. Cash never touches a size, so its place only has to be consistent.
|
|
83
|
+
const RANK = { withdraw: 0, cash: 1, fill: 2, deposit: 3, sweep: 4 } as const;
|
|
84
|
+
const newestFirst = (a: PnlEvent, b: PnlEvent) => b.timeUs - a.timeUs || RANK[a.kind] - RANK[b.kind];
|
|
85
|
+
|
|
86
|
+
interface LegState { kind: "perp" | "spot"; size: bigint; basis: bigint; basisKnown: boolean }
|
|
87
|
+
|
|
88
|
+
/** The backward walk. Feed events newest-first, ask for points newest-first;
|
|
89
|
+
* every event after a point must have been fed before the point is asked. */
|
|
90
|
+
export class PnlWalker {
|
|
91
|
+
readonly warnings: string[] = [];
|
|
92
|
+
private readonly state = new Map<MarketId, LegState>();
|
|
93
|
+
private pending: PnlEvent[] = [];
|
|
94
|
+
private acc = 0n;
|
|
95
|
+
private flows = 0n;
|
|
96
|
+
private refValue?: bigint;
|
|
97
|
+
|
|
98
|
+
constructor(
|
|
99
|
+
legs: PnlLeg[],
|
|
100
|
+
private readonly tickAt: (market: MarketId, timeUs: number) => PnlTick | undefined,
|
|
101
|
+
private readonly refTimeUs: number,
|
|
102
|
+
private readonly accountValueRef?: bigint,
|
|
103
|
+
) {
|
|
104
|
+
for (const l of legs) this.state.set(l.market, { kind: l.kind, size: l.size, basis: l.basis ?? 0n, basisKnown: l.basis !== undefined });
|
|
105
|
+
}
|
|
106
|
+
|
|
107
|
+
/** A market first seen in an old fill: flat at the reference. */
|
|
108
|
+
touch(market: MarketId, kind: "perp" | "spot"): void {
|
|
109
|
+
if (!this.state.has(market)) this.state.set(market, { kind, size: 0n, basis: 0n, basisKnown: true });
|
|
110
|
+
}
|
|
111
|
+
|
|
112
|
+
feed(events: PnlEvent[]): void {
|
|
113
|
+
this.pending = this.pending.concat(events).sort(newestFirst);
|
|
114
|
+
}
|
|
115
|
+
|
|
116
|
+
point(t: number): PnlPoint {
|
|
117
|
+
this.refValue ??= this.value(this.refTimeUs);
|
|
118
|
+
for (let e = this.pending[0]; e && e.timeUs > t; e = this.pending[0]) {
|
|
119
|
+
this.pending.shift();
|
|
120
|
+
const u = this.unapply(e);
|
|
121
|
+
this.acc += u.pnl;
|
|
122
|
+
this.flows += u.flow;
|
|
123
|
+
}
|
|
124
|
+
const pnl = this.value(t) - this.refValue - this.acc;
|
|
125
|
+
const point: PnlPoint = { time: t / 1000, pnl };
|
|
126
|
+
// Account value is PnL plus every movement that is not PnL.
|
|
127
|
+
if (this.accountValueRef !== undefined) point.accountValue = this.accountValueRef + pnl - this.flows;
|
|
128
|
+
return point;
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
private value(t: number): bigint {
|
|
132
|
+
let sum = 0n;
|
|
133
|
+
for (const [m, st] of this.state) {
|
|
134
|
+
if (st.size === 0n) continue;
|
|
135
|
+
const tick = this.tickAt(m, t);
|
|
136
|
+
if (!tick) { this.warnings.push(`${m}: no tick at or before ${t}`); continue; }
|
|
137
|
+
sum += mul(tick.mark - tick.funding, st.size);
|
|
138
|
+
}
|
|
139
|
+
return sum;
|
|
140
|
+
}
|
|
141
|
+
|
|
142
|
+
/** The PnL adjustment and the non-PnL money value carried by the event. */
|
|
143
|
+
private unapply(e: PnlEvent): { pnl: bigint; flow: bigint } {
|
|
144
|
+
if (e.kind === "cash" || e.market === undefined) return { pnl: 0n, flow: e.deltaSize };
|
|
145
|
+
const st = this.state.get(e.market);
|
|
146
|
+
if (!st) throw new Error(`pnlHistory: event on unknown market ${e.market}`);
|
|
147
|
+
const tick = this.tickAt(e.market, e.timeUs);
|
|
148
|
+
const F = tick?.funding ?? 0n;
|
|
149
|
+
const sizeBefore = st.size - e.deltaSize;
|
|
150
|
+
let price = e.price;
|
|
151
|
+
let flow = 0n;
|
|
152
|
+
|
|
153
|
+
if (st.kind === "spot") {
|
|
154
|
+
const average = st.size !== 0n && st.basisKnown ? div(st.basis, st.size) : undefined;
|
|
155
|
+
if (e.kind === "withdraw") {
|
|
156
|
+
if (average === undefined) {
|
|
157
|
+
this.warnings.push(`${e.market}: withdrawal at ${e.timeUs} with unknown cost basis, treated as neutral`);
|
|
158
|
+
price = tick?.mark ?? 0n;
|
|
159
|
+
} else price = average;
|
|
160
|
+
}
|
|
161
|
+
if (e.kind === "deposit") price = tick?.mark ?? 0n;
|
|
162
|
+
// Tokens leave at their cost and arrive at the clearing price; either
|
|
163
|
+
// way the value that moved is what the event is priced at.
|
|
164
|
+
if (e.kind === "withdraw" || e.kind === "deposit") flow = mul(price, e.deltaSize);
|
|
165
|
+
if (sizeBefore === 0n) { st.basis = 0n; st.basisKnown = true; }
|
|
166
|
+
else if (e.deltaSize > 0n) st.basis -= mul(price, e.deltaSize);
|
|
167
|
+
else if (average !== undefined) st.basis = mul(average, sizeBefore);
|
|
168
|
+
else st.basisKnown = false;
|
|
169
|
+
} else {
|
|
170
|
+
const crossed = st.size !== 0n && sizeBefore !== 0n && (st.size > 0n) !== (sizeBefore > 0n);
|
|
171
|
+
if (st.size === 0n || crossed) st.basisKnown = false;
|
|
172
|
+
else if (st.basisKnown) st.basis -= mul(F - price, e.deltaSize);
|
|
173
|
+
if (sizeBefore === 0n && st.basisKnown) {
|
|
174
|
+
const r = st.basis < 0n ? -st.basis : st.basis;
|
|
175
|
+
if (r > RESIDUAL_TOLERANCE) this.warnings.push(`${e.market}: basis residual ${st.basis} at flat ${e.timeUs}`);
|
|
176
|
+
st.basis = 0n;
|
|
177
|
+
}
|
|
178
|
+
}
|
|
179
|
+
|
|
180
|
+
st.size = sizeBefore;
|
|
181
|
+
return { pnl: mul(F - price, e.deltaSize), flow };
|
|
182
|
+
}
|
|
183
|
+
}
|
|
184
|
+
|
|
185
|
+
export function foldPnlHistory(input: PnlFoldInput): PnlHistory {
|
|
186
|
+
const walker = new PnlWalker(input.legs, input.tickAt, input.refTimeUs, input.accountValueRef);
|
|
187
|
+
walker.feed(input.events);
|
|
188
|
+
const points = [...input.gridUs].reverse().map((t) => walker.point(t)).reverse();
|
|
189
|
+
const base = points[0]?.pnl ?? 0n;
|
|
190
|
+
return { points: points.map((p) => ({ ...p, pnl: p.pnl - base })), warnings: walker.warnings };
|
|
191
|
+
}
|
|
192
|
+
|
|
193
|
+
// --- fetch ---
|
|
194
|
+
|
|
195
|
+
type WireFill = WireFillRow;
|
|
196
|
+
type WireSolution = WireSolutionRow;
|
|
197
|
+
|
|
198
|
+
/** The REST reads, with the `ob_*` JSON-RPC twins behind them for nodes that
|
|
199
|
+
* predate the routes. ponytail: drop the fallback once every network serves
|
|
200
|
+
* /clob/solutions and /clob/fills. */
|
|
201
|
+
function reads(rest: PodRestClient, rpcUrl: string, opts: RpcOptions) {
|
|
202
|
+
const missing = (e: unknown) => e instanceof PodHttpError && e.status === 404;
|
|
203
|
+
return {
|
|
204
|
+
async fills(account: Address, q: { fromUs: number; toUs: number; limit: number }): Promise<WireFill[]> {
|
|
205
|
+
try { return await rest.fills(account, q); }
|
|
206
|
+
catch (e) {
|
|
207
|
+
if (!missing(e)) throw e;
|
|
208
|
+
return (await rpc<{ fills: WireFill[] }>(rpcUrl, "ob_getFills", [account, { from_ts: q.fromUs, to_ts: q.toUs, limit: q.limit }], opts)).fills;
|
|
209
|
+
}
|
|
210
|
+
},
|
|
211
|
+
async solutions(q: { orderbook?: MarketId; sinceUs?: number; untilUs?: number; limit?: number }): Promise<WireSolution[]> {
|
|
212
|
+
try { return await rest.solutions(q); }
|
|
213
|
+
catch (e) {
|
|
214
|
+
if (!missing(e)) throw e;
|
|
215
|
+
// Older nodes count rows, not ticks: ask for enough rows to cover every market of one tick.
|
|
216
|
+
return (await rpc<{ solutions: WireSolution[] }>(rpcUrl, "ob_getSolutions", [{ orderbook_id: q.orderbook, since: q.sinceUs, until: q.untilUs, limit: q.orderbook ? q.limit : 200 }], opts)).solutions;
|
|
217
|
+
}
|
|
218
|
+
},
|
|
219
|
+
};
|
|
220
|
+
}
|
|
221
|
+
type Reads = ReturnType<typeof reads>;
|
|
222
|
+
|
|
223
|
+
/** Run `fn` over `items` with at most `n` in flight, keeping order. */
|
|
224
|
+
async function mapLimit<A, B>(items: A[], n: number, fn: (a: A) => Promise<B>): Promise<B[]> {
|
|
225
|
+
const out = new Array<B>(items.length);
|
|
226
|
+
let next = 0;
|
|
227
|
+
const worker = async () => {
|
|
228
|
+
for (let i = next++; i < items.length; i = next++) out[i] = await fn(items[i] as A);
|
|
229
|
+
};
|
|
230
|
+
await Promise.all(Array.from({ length: Math.min(n, items.length) }, worker));
|
|
231
|
+
return out;
|
|
232
|
+
}
|
|
233
|
+
|
|
234
|
+
/** Immutable inputs shared by every window size and every refresh: fills as
|
|
235
|
+
* events keyed by the time ranges they cover, and ticks keyed by market and
|
|
236
|
+
* time. The fold is recomputed per request; only uncovered ranges and unseen
|
|
237
|
+
* ticks are fetched. */
|
|
238
|
+
export class PnlHistoryCache {
|
|
239
|
+
readonly ticks = new Map<string, PnlTick>();
|
|
240
|
+
/** Times at which every market's row was fetched at once. */
|
|
241
|
+
readonly tickTimes = new Set<number>();
|
|
242
|
+
/** Per market, the latest time known to have no row at or before it. A
|
|
243
|
+
* market has no rows before its first tick, so one empty answer rules out
|
|
244
|
+
* every earlier point without a call. */
|
|
245
|
+
readonly noRowBefore = new Map<MarketId, number>();
|
|
246
|
+
/** Set when a range was cached from a node without the activity feed; the
|
|
247
|
+
* next run that does get flows drops the cache so those ranges are refetched. */
|
|
248
|
+
flowsMissing = false;
|
|
249
|
+
private events: PnlEvent[] = [];
|
|
250
|
+
private coverage: { from: number; to: number }[] = [];
|
|
251
|
+
|
|
252
|
+
/** About 150 bytes per event and per tick, so the default cap is on the
|
|
253
|
+
* order of 50 MB with its ticks. */
|
|
254
|
+
constructor(readonly maxEvents = 250_000) {}
|
|
255
|
+
|
|
256
|
+
clear(): void {
|
|
257
|
+
this.ticks.clear();
|
|
258
|
+
this.tickTimes.clear();
|
|
259
|
+
this.noRowBefore.clear();
|
|
260
|
+
this.flowsMissing = false;
|
|
261
|
+
this.events = [];
|
|
262
|
+
this.coverage = [];
|
|
263
|
+
}
|
|
264
|
+
|
|
265
|
+
/** Whether a tick for the market at the time can exist at all. */
|
|
266
|
+
mayHaveTick(market: MarketId, timeUs: number): boolean {
|
|
267
|
+
return timeUs > (this.noRowBefore.get(market) ?? -1);
|
|
268
|
+
}
|
|
269
|
+
|
|
270
|
+
noteEmpty(market: MarketId, timeUs: number): void {
|
|
271
|
+
if (timeUs > (this.noRowBefore.get(market) ?? -1)) this.noRowBefore.set(market, timeUs);
|
|
272
|
+
}
|
|
273
|
+
|
|
274
|
+
/** Sub-ranges of [from, to) not yet covered. */
|
|
275
|
+
missing(from: number, to: number): { from: number; to: number }[] {
|
|
276
|
+
const out: { from: number; to: number }[] = [];
|
|
277
|
+
let cursor = from;
|
|
278
|
+
for (const c of this.coverage) {
|
|
279
|
+
if (c.to <= cursor) continue;
|
|
280
|
+
if (c.from >= to) break;
|
|
281
|
+
if (c.from > cursor) out.push({ from: cursor, to: c.from });
|
|
282
|
+
cursor = Math.max(cursor, c.to);
|
|
283
|
+
}
|
|
284
|
+
if (cursor < to) out.push({ from: cursor, to });
|
|
285
|
+
return out;
|
|
286
|
+
}
|
|
287
|
+
|
|
288
|
+
add(from: number, to: number, events: PnlEvent[]): void {
|
|
289
|
+
this.events = this.events.concat(events).sort(newestFirst);
|
|
290
|
+
this.coverage.push({ from, to });
|
|
291
|
+
this.coverage.sort((a, b) => a.from - b.from);
|
|
292
|
+
const merged: { from: number; to: number }[] = [];
|
|
293
|
+
for (const c of this.coverage) {
|
|
294
|
+
const last = merged[merged.length - 1];
|
|
295
|
+
if (last && c.from <= last.to) last.to = Math.max(last.to, c.to);
|
|
296
|
+
else merged.push({ ...c });
|
|
297
|
+
}
|
|
298
|
+
this.coverage = merged;
|
|
299
|
+
if (this.events.length > this.maxEvents) {
|
|
300
|
+
// ponytail: evict the oldest events, their ticks, and coverage below them.
|
|
301
|
+
const cut = this.events[this.maxEvents - 1]?.timeUs ?? 0;
|
|
302
|
+
this.events = this.events.filter((e) => e.timeUs >= cut);
|
|
303
|
+
this.coverage = this.coverage.filter((c) => c.to > cut).map((c) => ({ from: Math.max(c.from, cut), to: c.to }));
|
|
304
|
+
for (const k of this.ticks.keys()) if (Number(k.slice(k.indexOf(":") + 1)) < cut) this.ticks.delete(k);
|
|
305
|
+
for (const t of this.tickTimes) if (t < cut) this.tickTimes.delete(t);
|
|
306
|
+
}
|
|
307
|
+
}
|
|
308
|
+
|
|
309
|
+
/** Events with from ≤ time < to, newest first. */
|
|
310
|
+
slice(from: number, to: number): PnlEvent[] {
|
|
311
|
+
return this.events.filter((e) => e.timeUs >= from && e.timeUs < to);
|
|
312
|
+
}
|
|
313
|
+
|
|
314
|
+
/** Drop a range so it is fetched again. */
|
|
315
|
+
forget(from: number, to: number): void {
|
|
316
|
+
this.events = this.events.filter((e) => e.timeUs < from || e.timeUs >= to);
|
|
317
|
+
this.coverage = this.coverage.flatMap((c) => {
|
|
318
|
+
if (c.to <= from || c.from >= to) return [c];
|
|
319
|
+
const kept: { from: number; to: number }[] = [];
|
|
320
|
+
if (c.from < from) kept.push({ from: c.from, to: from });
|
|
321
|
+
if (c.to > to) kept.push({ from: to, to: c.to });
|
|
322
|
+
return kept;
|
|
323
|
+
});
|
|
324
|
+
}
|
|
325
|
+
}
|
|
326
|
+
|
|
327
|
+
export interface PnlHistoryDeps { rest: PodRestClient; rpcUrl: string; fetch?: typeof fetch; cache?: PnlHistoryCache }
|
|
328
|
+
|
|
329
|
+
const MAX_POINTS = 500;
|
|
330
|
+
// The first chunks are small so the newest points draw after one window's
|
|
331
|
+
// fetch; later ones grow to keep the call count down.
|
|
332
|
+
const CHUNK_SIZES = [10, 20, 40, 50];
|
|
333
|
+
const IN_FLIGHT = 4;
|
|
334
|
+
const WIDE_ACCOUNT_MARKETS = 10;
|
|
335
|
+
const LOOKUPS_IN_FLIGHT = 24;
|
|
336
|
+
const FILLS_PAGE = 500;
|
|
337
|
+
|
|
338
|
+
/** Pages newest-first. A full page may cut a batch in half, so its oldest
|
|
339
|
+
* batch is dropped and refetched whole with the next page; rows are never
|
|
340
|
+
* keyed, since one order can legitimately fill several times in one batch
|
|
341
|
+
* (ADL slices). */
|
|
342
|
+
class FillsCursor {
|
|
343
|
+
done = false;
|
|
344
|
+
readonly warnings: string[] = [];
|
|
345
|
+
private to: number;
|
|
346
|
+
constructor(private readonly reads: Reads, private readonly account: Address, private readonly fromUs: number, toUs: number) {
|
|
347
|
+
this.to = toUs;
|
|
348
|
+
}
|
|
349
|
+
|
|
350
|
+
async next(): Promise<WireFill[]> {
|
|
351
|
+
const fills = await this.reads.fills(this.account, { fromUs: this.fromUs, toUs: this.to, limit: FILLS_PAGE });
|
|
352
|
+
if (fills.length < FILLS_PAGE) {
|
|
353
|
+
this.done = true;
|
|
354
|
+
return fills;
|
|
355
|
+
}
|
|
356
|
+
const oldest = Math.min(...fills.map((f) => f.timestamp));
|
|
357
|
+
if (oldest + 1 === this.to) {
|
|
358
|
+
// ponytail: a single batch with more than FILLS_PAGE fills is truncated here.
|
|
359
|
+
this.warnings.push(`batch ${oldest} has more than ${FILLS_PAGE} fills; only the first page is used`);
|
|
360
|
+
this.to = oldest;
|
|
361
|
+
return fills;
|
|
362
|
+
}
|
|
363
|
+
this.to = oldest + 1;
|
|
364
|
+
return fills.filter((f) => f.timestamp !== oldest);
|
|
365
|
+
}
|
|
366
|
+
}
|
|
367
|
+
|
|
368
|
+
async function drainFills(r: Reads, account: Address, fromUs: number, toUs: number): Promise<{ fills: WireFill[]; warnings: string[] }> {
|
|
369
|
+
const cursor = new FillsCursor(r, account, fromUs, toUs);
|
|
370
|
+
const fills: WireFill[] = [];
|
|
371
|
+
while (!cursor.done) fills.push(...(await cursor.next()));
|
|
372
|
+
return { fills, warnings: cursor.warnings };
|
|
373
|
+
}
|
|
374
|
+
|
|
375
|
+
export async function fetchFills(rest: PodRestClient, account: Address, fromUs: number, toUs: number, rpcUrl = "", opts: RpcOptions = {}): Promise<WireFill[]> {
|
|
376
|
+
return (await drainFills(reads(rest, rpcUrl, opts), account, fromUs, toUs)).fills;
|
|
377
|
+
}
|
|
378
|
+
|
|
379
|
+
const FLOW_TYPES = ["backstop", "bridge_transfer", "transfer"] as const;
|
|
380
|
+
|
|
381
|
+
/** Money movements in [fromUs, toUs) from the activity feed, or `undefined`
|
|
382
|
+
* when the node does not serve it. */
|
|
383
|
+
async function drainFlows(rest: PodRestClient, account: Address, fromUs: number, toUs: number): Promise<MoneyActivity[] | undefined> {
|
|
384
|
+
const out: MoneyActivity[] = [];
|
|
385
|
+
let cursor: string | undefined;
|
|
386
|
+
try {
|
|
387
|
+
do {
|
|
388
|
+
const page = await rest.activity(account, { types: [...FLOW_TYPES], from: fromUs / 1000, to: toUs / 1000, limit: 200, cursor });
|
|
389
|
+
for (const e of page.activity) if (e.activityType !== "order") out.push(e);
|
|
390
|
+
cursor = page.nextCursor ?? undefined;
|
|
391
|
+
} while (cursor);
|
|
392
|
+
} catch (e) {
|
|
393
|
+
// Only a missing route means the node has no feed. Anything else (a 503,
|
|
394
|
+
// a timeout) must fail the run, or the range would be cached without
|
|
395
|
+
// its flows and every later account value would be wrong and silent.
|
|
396
|
+
if (e instanceof PodHttpError && e.status === 404) return undefined;
|
|
397
|
+
throw e;
|
|
398
|
+
}
|
|
399
|
+
return out;
|
|
400
|
+
}
|
|
401
|
+
|
|
402
|
+
export async function* streamPnlHistory(
|
|
403
|
+
deps: PnlHistoryDeps,
|
|
404
|
+
account: Address,
|
|
405
|
+
q: PnlHistoryQuery,
|
|
406
|
+
): AsyncGenerator<PnlHistoryChunk> {
|
|
407
|
+
const rpcOpts: RpcOptions = { fetch: deps.fetch };
|
|
408
|
+
const io = reads(deps.rest, deps.rpcUrl, rpcOpts);
|
|
409
|
+
|
|
410
|
+
// The snapshot is served from the live engine, fills and ticks from the
|
|
411
|
+
// indexer. Pair them: the engine's last executed batch is read together with
|
|
412
|
+
// the snapshot, one request sent just before it and one just after, and the
|
|
413
|
+
// read is retried when the two disagree. Sequential reads would be exact but
|
|
414
|
+
// straddle a 500 ms tick on every attempt from far away; concurrent ones
|
|
415
|
+
// land within a few ms of server time, so a boundary inside that gap is rare
|
|
416
|
+
// and the next refresh heals it.
|
|
417
|
+
const engineTick = async (): Promise<number> => {
|
|
418
|
+
const st = await rpc<{ last_executed_batch?: { deadline: string | number } | null }>(deps.rpcUrl, "pod_getSolverState", [], rpcOpts);
|
|
419
|
+
return Number(st.last_executed_batch?.deadline ?? 0);
|
|
420
|
+
};
|
|
421
|
+
const readSnapshot = async () => {
|
|
422
|
+
for (let attempt = 0; ; attempt++) {
|
|
423
|
+
const [before, snap, balances, after] = await Promise.all([engineTick(), deps.rest.positions(account), deps.rest.balances(account), engineTick()]);
|
|
424
|
+
if (before === after || attempt >= 4) return { nowUs: before, snap, balances };
|
|
425
|
+
}
|
|
426
|
+
};
|
|
427
|
+
const [markets, snapshot, backstop, withdrawals] = await Promise.all([
|
|
428
|
+
deps.rest.markets(),
|
|
429
|
+
readSnapshot(),
|
|
430
|
+
deps.rest.backstopTransfers(account),
|
|
431
|
+
deps.rest.bridgeWithdrawals(account, { since: q.from * 1000 - 1 }),
|
|
432
|
+
]);
|
|
433
|
+
const { snap, balances } = snapshot;
|
|
434
|
+
let nowUs = snapshot.nowUs;
|
|
435
|
+
const batchUs = Math.max(500, ...markets.map((m) => m.auctionIntervalMs)) * 1000;
|
|
436
|
+
// Grid points sit on batch ticks so one range call per point serves every market.
|
|
437
|
+
const fromUs = Math.ceil((q.from * 1000) / batchUs) * batchUs;
|
|
438
|
+
if (nowUs === 0) nowUs = (await deps.rest.status()).solutionNow * 1000;
|
|
439
|
+
|
|
440
|
+
// The indexer is normally at the engine's tick already, so the first windows
|
|
441
|
+
// are fetched while this checks; if it was behind, the newest window is
|
|
442
|
+
// fetched again once it has caught up.
|
|
443
|
+
const indexerLagged = (async () => {
|
|
444
|
+
let lagged = false;
|
|
445
|
+
for (let i = 0; i < 30 && (await deps.rest.status()).solutionNow * 1000 < nowUs; i++) {
|
|
446
|
+
lagged = true;
|
|
447
|
+
await new Promise((r) => setTimeout(r, 100));
|
|
448
|
+
}
|
|
449
|
+
return lagged;
|
|
450
|
+
})();
|
|
451
|
+
const toUs = Math.min(q.to === undefined ? nowUs : Math.floor((q.to * 1000) / batchUs) * batchUs, nowUs);
|
|
452
|
+
if (fromUs >= toUs) throw new Error("pnlHistory: from must be before to");
|
|
453
|
+
|
|
454
|
+
const points = Math.min(Math.max(2, Math.floor(q.points ?? MAX_POINTS)), MAX_POINTS);
|
|
455
|
+
const stepUs = Math.ceil((toUs - fromUs) / (points - 1) / batchUs) * batchUs;
|
|
456
|
+
// The series starts at `from` and ends at `to`; the points between sit on
|
|
457
|
+
// epoch multiples of the step, so a refreshed window shares them, and their
|
|
458
|
+
// ticks, with the previous one.
|
|
459
|
+
const gridUs: number[] = [fromUs];
|
|
460
|
+
for (let t = (Math.floor(fromUs / stepUs) + 1) * stepUs; t < toUs; t += stepUs) gridUs.push(t);
|
|
461
|
+
gridUs.push(toUs);
|
|
462
|
+
|
|
463
|
+
const byId = new Map(markets.map((m) => [m.id, m]));
|
|
464
|
+
const spotByToken = new Map(markets.filter((m) => m.type === "spot").map((m) => [m.base.address, m]));
|
|
465
|
+
const kindOf = (id: MarketId): "perp" | "spot" => (byId.get(id)?.type === "spot" ? "spot" : "perp");
|
|
466
|
+
const legs: PnlLeg[] = [];
|
|
467
|
+
for (const p of snap.positions) {
|
|
468
|
+
if (p.kind !== "perp") continue;
|
|
469
|
+
const basis = p.fundingBasis !== undefined && p.costBasis !== undefined ? p.fundingBasis - p.costBasis : undefined;
|
|
470
|
+
legs.push({ market: p.orderbookId, kind: "perp", size: p.size, basis });
|
|
471
|
+
}
|
|
472
|
+
for (const h of balances.holdings) legs.push({ market: h.orderbookId, kind: "spot", size: h.balance, basis: h.costBasis });
|
|
473
|
+
|
|
474
|
+
const cache = deps.cache ?? new PnlHistoryCache();
|
|
475
|
+
const ticks = cache.ticks;
|
|
476
|
+
const key = (m: MarketId, t: number) => `${m}:${t}`;
|
|
477
|
+
const walker = new PnlWalker(legs, (m, t) => ticks.get(key(m, t)), nowUs, snap.accountValue);
|
|
478
|
+
const known = new Set<MarketId>(legs.map((l) => l.market));
|
|
479
|
+
const use = (id: MarketId) => { if (!known.has(id)) { known.add(id); walker.touch(id, kindOf(id)); } };
|
|
480
|
+
|
|
481
|
+
const store = (row: WireSolution, t: number) => {
|
|
482
|
+
const id = row.orderbook_id as MarketId;
|
|
483
|
+
const perp = kindOf(id) === "perp";
|
|
484
|
+
const window = byId.get(id)?.fundingWindowUs ?? 0;
|
|
485
|
+
ticks.set(key(id, t), {
|
|
486
|
+
mark: perp ? dec(row.mark_price) : dec(row.clearing_price),
|
|
487
|
+
funding: perp && row.funding_index !== undefined && window > 0 ? dec(row.funding_index) / BigInt(window) : 0n,
|
|
488
|
+
});
|
|
489
|
+
};
|
|
490
|
+
type SolutionsQuery = Parameters<Reads["solutions"]>[0];
|
|
491
|
+
// A "newest row at or before t" answer is only right once the indexer has
|
|
492
|
+
// reached t, so no tick lookup goes out before the watermark check resolves.
|
|
493
|
+
// Fills do not wait: the lag retry below fetches the newest window again.
|
|
494
|
+
const solutions = async (queries: SolutionsQuery[]): Promise<WireSolution[][]> => {
|
|
495
|
+
await indexerLagged;
|
|
496
|
+
return mapLimit(queries, LOOKUPS_IN_FLIGHT, (q) => io.solutions(q));
|
|
497
|
+
};
|
|
498
|
+
/** All markets' rows at each tick, one call per tick; skipped before every
|
|
499
|
+
* known market's first tick. */
|
|
500
|
+
const fetchAllAt = async (times: number[]) => {
|
|
501
|
+
const wanted = times.filter((t) => !cache.tickTimes.has(t) && [...known].some((m) => cache.mayHaveTick(m, t)));
|
|
502
|
+
const rows = await solutions(wanted.map((t) => ({ sinceUs: t, untilUs: t + 1, limit: 1 })));
|
|
503
|
+
rows.forEach((rs, i) => { const t = wanted[i] ?? 0; cache.tickTimes.add(t); for (const r of rs) store(r, t); });
|
|
504
|
+
};
|
|
505
|
+
/** Ticks for every known market at the grid points. One call per tick when
|
|
506
|
+
* the account spans many markets, else one lookup per market: the wide call
|
|
507
|
+
* returns every market's row whether needed or not. */
|
|
508
|
+
const fetchTicks = async (times: number[]) => {
|
|
509
|
+
if (known.size >= WIDE_ACCOUNT_MARKETS) await fetchAllAt(times);
|
|
510
|
+
else await fetchPairs(times.flatMap((t) => [...known].map((market) => ({ market, timeUs: t }))));
|
|
511
|
+
};
|
|
512
|
+
/** Newest row at or before the time, per pair; the fallback and the per-fill path. */
|
|
513
|
+
const fetchPairs = async (pairs: { market: MarketId; timeUs: number }[]) => {
|
|
514
|
+
const seen = new Set<string>();
|
|
515
|
+
const wanted = pairs.filter((n) => {
|
|
516
|
+
const k = key(n.market, n.timeUs);
|
|
517
|
+
if (ticks.has(k) || seen.has(k) || !cache.mayHaveTick(n.market, n.timeUs)) return false;
|
|
518
|
+
seen.add(k);
|
|
519
|
+
return true;
|
|
520
|
+
});
|
|
521
|
+
const rows = await solutions(wanted.map((n) => ({ orderbook: n.market, untilUs: n.timeUs + 1, limit: 1 })));
|
|
522
|
+
rows.forEach((rs, i) => {
|
|
523
|
+
const n = wanted[i];
|
|
524
|
+
if (!n) return;
|
|
525
|
+
const r = rs[0];
|
|
526
|
+
if (r) store(r, n.timeUs);
|
|
527
|
+
else cache.noteEmpty(n.market, n.timeUs);
|
|
528
|
+
});
|
|
529
|
+
};
|
|
530
|
+
|
|
531
|
+
const fixed: PnlEvent[] = [];
|
|
532
|
+
for (const b of backstop.transfers) {
|
|
533
|
+
const timeUs = b.time * 1000;
|
|
534
|
+
if (!b.orderbookId || b.size === 0n || timeUs < fromUs || timeUs > nowUs) continue;
|
|
535
|
+
use(b.orderbookId);
|
|
536
|
+
fixed.push({ market: b.orderbookId, timeUs, deltaSize: -b.size, price: b.markPrice, kind: "sweep" });
|
|
537
|
+
}
|
|
538
|
+
for (const w of withdrawals) {
|
|
539
|
+
if (w.error || w.timeUs < fromUs || w.timeUs > nowUs) continue;
|
|
540
|
+
const m = spotByToken.get(w.token);
|
|
541
|
+
if (!m) { fixed.push({ timeUs: w.timeUs, deltaSize: -w.amount, price: 0n, kind: "cash" }); continue; }
|
|
542
|
+
use(m.id);
|
|
543
|
+
fixed.push({ market: m.id, timeUs: w.timeUs, deltaSize: -w.amount, price: 0n, kind: "withdraw" });
|
|
544
|
+
}
|
|
545
|
+
walker.feed(fixed);
|
|
546
|
+
// Ranges cached from a node without the activity feed hold no flows. If the
|
|
547
|
+
// feed is there now, drop them so this run fetches everything with it.
|
|
548
|
+
if (cache.flowsMissing && (await drainFlows(deps.rest, account, nowUs, nowUs + 1)) !== undefined) {
|
|
549
|
+
cache.flowsMissing = false;
|
|
550
|
+
cache.forget(0, Number.MAX_SAFE_INTEGER);
|
|
551
|
+
}
|
|
552
|
+
// Deposits, transfers and backstop cash sweeps come from the activity feed;
|
|
553
|
+
// withdrawals and sweep legs already arrived above, so those rows are skipped.
|
|
554
|
+
let flowsAvailable = true;
|
|
555
|
+
const toFlowEvents = (rows: MoneyActivity[]): PnlEvent[] => {
|
|
556
|
+
const out: PnlEvent[] = [];
|
|
557
|
+
for (const r of rows) {
|
|
558
|
+
const timeUs = r.timeMs * 1000;
|
|
559
|
+
if (r.activityType === "backstop") {
|
|
560
|
+
if (!r.orderbookId) out.push({ timeUs, deltaSize: -r.cash, price: 0n, kind: "cash" });
|
|
561
|
+
continue;
|
|
562
|
+
}
|
|
563
|
+
if (r.error || (r.activityType === "bridge_transfer" && r.amount < 0n)) continue;
|
|
564
|
+
const m = spotByToken.get(r.token);
|
|
565
|
+
if (!m) { out.push({ timeUs, deltaSize: r.amount, price: 0n, kind: "cash" }); continue; }
|
|
566
|
+
use(m.id);
|
|
567
|
+
out.push({ market: m.id, timeUs, deltaSize: r.amount, price: 0n, kind: r.amount < 0n ? "withdraw" : "deposit" });
|
|
568
|
+
}
|
|
569
|
+
return out;
|
|
570
|
+
};
|
|
571
|
+
const pairsOf = (events: PnlEvent[]) => events.flatMap((e) => (e.market ? [{ market: e.market, timeUs: e.timeUs }] : []));
|
|
572
|
+
const preface = Promise.all([fetchTicks([nowUs]), fetchPairs(pairsOf(fixed))]);
|
|
573
|
+
|
|
574
|
+
const toEvent = (f: WireFill): PnlEvent => {
|
|
575
|
+
const base = dec(f.base_amount);
|
|
576
|
+
return { market: f.orderbook_id as MarketId, timeUs: f.timestamp, deltaSize: dec(f.initial_size) < 0n ? -base : base, price: dec(f.price), kind: "fill" };
|
|
577
|
+
};
|
|
578
|
+
// Chunks newest-first. Chunk k needs the events in (oldest_k, oldest_{k−1}],
|
|
579
|
+
// an explicit window, so the next windows load while earlier ones are folded.
|
|
580
|
+
const chunks: number[][] = [];
|
|
581
|
+
const newestFirstGrid = [...gridUs].reverse();
|
|
582
|
+
for (let i = 0, n = 0; i < newestFirstGrid.length; n++) {
|
|
583
|
+
const size = CHUNK_SIZES[Math.min(n, CHUNK_SIZES.length - 1)] ?? 50;
|
|
584
|
+
chunks.push(newestFirstGrid.slice(i, i + size));
|
|
585
|
+
i += size;
|
|
586
|
+
}
|
|
587
|
+
const prep = async (k: number): Promise<{ events: PnlEvent[]; warnings: string[] }> => {
|
|
588
|
+
const pts = chunks[k] ?? [];
|
|
589
|
+
const oldest = pts[pts.length - 1] ?? 0;
|
|
590
|
+
const bound = k === 0 ? nowUs : (chunks[k - 1]?.at(-1) ?? nowUs);
|
|
591
|
+
const warnings: string[] = [];
|
|
592
|
+
await Promise.all(cache.missing(oldest + 1, bound + 1).map(async (r) => {
|
|
593
|
+
const [page, flows] = await Promise.all([drainFills(io, account, r.from, r.to), drainFlows(deps.rest, account, r.from, r.to)]);
|
|
594
|
+
if (flows === undefined) { flowsAvailable = false; cache.flowsMissing = true; }
|
|
595
|
+
cache.add(r.from, r.to, page.fills.map(toEvent).concat(toFlowEvents(flows ?? [])));
|
|
596
|
+
warnings.push(...page.warnings);
|
|
597
|
+
}));
|
|
598
|
+
const events = cache.slice(oldest + 1, bound + 1);
|
|
599
|
+
await Promise.all([fetchTicks(pts), fetchPairs(pairsOf(events))]);
|
|
600
|
+
return { events, warnings };
|
|
601
|
+
};
|
|
602
|
+
const queue: Promise<{ events: PnlEvent[]; warnings: string[] }>[] = [];
|
|
603
|
+
let nextPrep = 0;
|
|
604
|
+
for (let k = 0; k < chunks.length; k++) {
|
|
605
|
+
while (queue.length < IN_FLIGHT && nextPrep < chunks.length) {
|
|
606
|
+
const p = prep(nextPrep++);
|
|
607
|
+
p.catch(() => {});
|
|
608
|
+
queue.push(p);
|
|
609
|
+
}
|
|
610
|
+
let first = await (queue.shift() as Promise<{ events: PnlEvent[]; warnings: string[] }>);
|
|
611
|
+
if (k === 0 && (await indexerLagged)) {
|
|
612
|
+
cache.forget((chunks[0]?.at(-1) ?? 0) + 1, nowUs + 1);
|
|
613
|
+
first = await prep(0);
|
|
614
|
+
}
|
|
615
|
+
const { events, warnings } = first;
|
|
616
|
+
await preface;
|
|
617
|
+
for (const e of events) if (e.market) use(e.market);
|
|
618
|
+
walker.feed(events);
|
|
619
|
+
const pts = chunks[k] ?? [];
|
|
620
|
+
await fetchPairs(pts.flatMap((t) => [...known].map((market) => ({ market, timeUs: t }))));
|
|
621
|
+
const out = pts.map((t) => walker.point(t)).reverse();
|
|
622
|
+
if (!flowsAvailable) {
|
|
623
|
+
for (const p of out) delete p.accountValue;
|
|
624
|
+
if (k === 0) warnings.push("account value unavailable: the node does not serve the activity feed");
|
|
625
|
+
}
|
|
626
|
+
yield { points: out, done: k === chunks.length - 1, warnings: [...walker.warnings.splice(0), ...warnings] };
|
|
627
|
+
}
|
|
628
|
+
}
|
|
629
|
+
|
|
630
|
+
export async function fetchPnlHistory(deps: PnlHistoryDeps, account: Address, q: PnlHistoryQuery): Promise<PnlHistory> {
|
|
631
|
+
let points: PnlPoint[] = [];
|
|
632
|
+
const warnings: string[] = [];
|
|
633
|
+
for await (const c of streamPnlHistory(deps, account, q)) {
|
|
634
|
+
points = c.points.concat(points);
|
|
635
|
+
warnings.push(...c.warnings);
|
|
636
|
+
}
|
|
637
|
+
const base = points[0]?.pnl ?? 0n;
|
|
638
|
+
return { points: points.map((p) => ({ ...p, pnl: p.pnl - base })), warnings };
|
|
639
|
+
}
|