@pod-network/trade-sdk 0.8.0 → 0.10.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/dist/client.d.ts +18 -0
- package/dist/client.d.ts.map +1 -1
- package/dist/client.js +30 -0
- package/dist/client.js.map +1 -1
- package/dist/codec/decode.d.ts.map +1 -1
- package/dist/codec/decode.js +4 -0
- package/dist/codec/decode.js.map +1 -1
- package/dist/index.d.ts +1 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +1 -0
- package/dist/index.js.map +1 -1
- 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/pnl-history.d.ts +121 -0
- package/dist/sync/pnl-history.d.ts.map +1 -0
- package/dist/sync/pnl-history.js +427 -0
- package/dist/sync/pnl-history.js.map +1 -0
- package/dist/sync/positions-live.d.ts.map +1 -1
- package/dist/sync/positions-live.js +17 -14
- package/dist/sync/positions-live.js.map +1 -1
- package/dist/transport/jsonrpc.d.ts +5 -0
- package/dist/transport/jsonrpc.d.ts.map +1 -1
- package/dist/transport/jsonrpc.js +20 -0
- package/dist/transport/jsonrpc.js.map +1 -1
- package/dist/types/public.d.ts +13 -1
- package/dist/types/public.d.ts.map +1 -1
- package/dist/types/wire.d.ts +11 -0
- package/dist/types/wire.d.ts.map +1 -1
- package/package.json +1 -1
- package/src/client.ts +32 -0
- package/src/codec/decode.ts +4 -0
- package/src/index.ts +4 -0
- package/src/sync/order-preview.ts +63 -0
- package/src/sync/pnl-history.ts +470 -0
- package/src/sync/positions-live.ts +17 -18
- package/src/transport/jsonrpc.ts +23 -0
- package/src/types/public.ts +13 -1
- package/src/types/wire.ts +11 -0
|
@@ -0,0 +1,470 @@
|
|
|
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 } from "../types/public.js";
|
|
15
|
+
import { div, mul } from "../codec/fixed.js";
|
|
16
|
+
import { dec } from "../codec/units.js";
|
|
17
|
+
import { rpc, rpcBatch, type RpcOptions } from "../transport/jsonrpc.js";
|
|
18
|
+
import type { PodRestClient } from "../transport/rest.js";
|
|
19
|
+
|
|
20
|
+
export interface PnlPoint { time: number; pnl: bigint }
|
|
21
|
+
export interface PnlHistory { points: PnlPoint[]; warnings: string[] }
|
|
22
|
+
export interface PnlHistoryQuery {
|
|
23
|
+
/** ms */
|
|
24
|
+
from: number;
|
|
25
|
+
/** ms; defaults to the engine's current tick */
|
|
26
|
+
to?: number;
|
|
27
|
+
/** Sample count, at most 500 (the default). The step is the window divided
|
|
28
|
+
* by it, rounded up to a whole batch interval. */
|
|
29
|
+
points?: number;
|
|
30
|
+
}
|
|
31
|
+
/** One step of the backward walk. Chunks arrive newest-first; within a chunk
|
|
32
|
+
* points are ascending. `pnl` is relative to the reference tick (0 at the
|
|
33
|
+
* newest point), so a chart anchored at `from` shifts by the last chunk's
|
|
34
|
+
* first point once `done`. */
|
|
35
|
+
export interface PnlHistoryChunk { points: PnlPoint[]; done: boolean; warnings: string[] }
|
|
36
|
+
|
|
37
|
+
export interface PnlLeg {
|
|
38
|
+
market: MarketId;
|
|
39
|
+
kind: "perp" | "spot";
|
|
40
|
+
size: bigint;
|
|
41
|
+
/** perp: fundingBasis − costBasis; spot: costBasis. Absent when the node
|
|
42
|
+
* does not serve the bases; the residual check is then skipped. */
|
|
43
|
+
basis?: bigint;
|
|
44
|
+
}
|
|
45
|
+
export interface PnlEvent {
|
|
46
|
+
market: MarketId;
|
|
47
|
+
timeUs: number;
|
|
48
|
+
deltaSize: bigint;
|
|
49
|
+
/** Fill price; unused for withdrawals. */
|
|
50
|
+
price: bigint;
|
|
51
|
+
kind: "fill" | "withdraw" | "sweep";
|
|
52
|
+
}
|
|
53
|
+
export interface PnlTick { mark: bigint; funding: bigint }
|
|
54
|
+
export interface PnlFoldInput {
|
|
55
|
+
refTimeUs: number;
|
|
56
|
+
/** One per market touched by legs or events. */
|
|
57
|
+
legs: PnlLeg[];
|
|
58
|
+
events: PnlEvent[];
|
|
59
|
+
/** Ascending, all ≤ refTimeUs. */
|
|
60
|
+
gridUs: number[];
|
|
61
|
+
/** Newest tick at or before `timeUs`. */
|
|
62
|
+
tickAt: (market: MarketId, timeUs: number) => PnlTick | undefined;
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
const RESIDUAL_TOLERANCE = 10n ** 12n;
|
|
66
|
+
// Within a tick the engine runs sweeps, then matching, then withdrawals;
|
|
67
|
+
// walking backwards undoes them in the opposite order.
|
|
68
|
+
const RANK = { withdraw: 0, fill: 1, sweep: 2 } as const;
|
|
69
|
+
const newestFirst = (a: PnlEvent, b: PnlEvent) => b.timeUs - a.timeUs || RANK[a.kind] - RANK[b.kind];
|
|
70
|
+
|
|
71
|
+
interface LegState { kind: "perp" | "spot"; size: bigint; basis: bigint; basisKnown: boolean }
|
|
72
|
+
|
|
73
|
+
/** The backward walk. Feed events newest-first, ask for points newest-first;
|
|
74
|
+
* every event after a point must have been fed before the point is asked. */
|
|
75
|
+
export class PnlWalker {
|
|
76
|
+
readonly warnings: string[] = [];
|
|
77
|
+
private readonly state = new Map<MarketId, LegState>();
|
|
78
|
+
private pending: PnlEvent[] = [];
|
|
79
|
+
private acc = 0n;
|
|
80
|
+
private refValue?: bigint;
|
|
81
|
+
|
|
82
|
+
constructor(
|
|
83
|
+
legs: PnlLeg[],
|
|
84
|
+
private readonly tickAt: (market: MarketId, timeUs: number) => PnlTick | undefined,
|
|
85
|
+
private readonly refTimeUs: number,
|
|
86
|
+
) {
|
|
87
|
+
for (const l of legs) this.state.set(l.market, { kind: l.kind, size: l.size, basis: l.basis ?? 0n, basisKnown: l.basis !== undefined });
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
/** A market first seen in an old fill: flat at the reference. */
|
|
91
|
+
touch(market: MarketId, kind: "perp" | "spot"): void {
|
|
92
|
+
if (!this.state.has(market)) this.state.set(market, { kind, size: 0n, basis: 0n, basisKnown: true });
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
feed(events: PnlEvent[]): void {
|
|
96
|
+
this.pending = this.pending.concat(events).sort(newestFirst);
|
|
97
|
+
}
|
|
98
|
+
|
|
99
|
+
point(t: number): PnlPoint {
|
|
100
|
+
this.refValue ??= this.value(this.refTimeUs);
|
|
101
|
+
for (let e = this.pending[0]; e && e.timeUs > t; e = this.pending[0]) {
|
|
102
|
+
this.pending.shift();
|
|
103
|
+
this.acc += this.unapply(e);
|
|
104
|
+
}
|
|
105
|
+
return { time: t / 1000, pnl: this.value(t) - this.refValue - this.acc };
|
|
106
|
+
}
|
|
107
|
+
|
|
108
|
+
private value(t: number): bigint {
|
|
109
|
+
let sum = 0n;
|
|
110
|
+
for (const [m, st] of this.state) {
|
|
111
|
+
if (st.size === 0n) continue;
|
|
112
|
+
const tick = this.tickAt(m, t);
|
|
113
|
+
if (!tick) { this.warnings.push(`${m}: no tick at or before ${t}`); continue; }
|
|
114
|
+
sum += mul(tick.mark - tick.funding, st.size);
|
|
115
|
+
}
|
|
116
|
+
return sum;
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
private unapply(e: PnlEvent): bigint {
|
|
120
|
+
const st = this.state.get(e.market);
|
|
121
|
+
if (!st) throw new Error(`pnlHistory: event on unknown market ${e.market}`);
|
|
122
|
+
const tick = this.tickAt(e.market, e.timeUs);
|
|
123
|
+
const F = tick?.funding ?? 0n;
|
|
124
|
+
const sizeBefore = st.size - e.deltaSize;
|
|
125
|
+
let price = e.price;
|
|
126
|
+
|
|
127
|
+
if (st.kind === "spot") {
|
|
128
|
+
const average = st.size !== 0n && st.basisKnown ? div(st.basis, st.size) : undefined;
|
|
129
|
+
if (e.kind === "withdraw") {
|
|
130
|
+
if (average === undefined) {
|
|
131
|
+
this.warnings.push(`${e.market}: withdrawal at ${e.timeUs} with unknown cost basis, treated as neutral`);
|
|
132
|
+
price = tick?.mark ?? 0n;
|
|
133
|
+
} else price = average;
|
|
134
|
+
}
|
|
135
|
+
if (sizeBefore === 0n) { st.basis = 0n; st.basisKnown = true; }
|
|
136
|
+
else if (e.deltaSize > 0n) st.basis -= mul(e.price, e.deltaSize);
|
|
137
|
+
else if (average !== undefined) st.basis = mul(average, sizeBefore);
|
|
138
|
+
else st.basisKnown = false;
|
|
139
|
+
} else {
|
|
140
|
+
const crossed = st.size !== 0n && sizeBefore !== 0n && (st.size > 0n) !== (sizeBefore > 0n);
|
|
141
|
+
if (st.size === 0n || crossed) st.basisKnown = false;
|
|
142
|
+
else if (st.basisKnown) st.basis -= mul(F - price, e.deltaSize);
|
|
143
|
+
if (sizeBefore === 0n && st.basisKnown) {
|
|
144
|
+
const r = st.basis < 0n ? -st.basis : st.basis;
|
|
145
|
+
if (r > RESIDUAL_TOLERANCE) this.warnings.push(`${e.market}: basis residual ${st.basis} at flat ${e.timeUs}`);
|
|
146
|
+
st.basis = 0n;
|
|
147
|
+
}
|
|
148
|
+
}
|
|
149
|
+
|
|
150
|
+
st.size = sizeBefore;
|
|
151
|
+
return mul(F - price, e.deltaSize);
|
|
152
|
+
}
|
|
153
|
+
}
|
|
154
|
+
|
|
155
|
+
export function foldPnlHistory(input: PnlFoldInput): PnlHistory {
|
|
156
|
+
const walker = new PnlWalker(input.legs, input.tickAt, input.refTimeUs);
|
|
157
|
+
walker.feed(input.events);
|
|
158
|
+
const points = [...input.gridUs].reverse().map((t) => walker.point(t)).reverse();
|
|
159
|
+
const base = points[0]?.pnl ?? 0n;
|
|
160
|
+
return { points: points.map((p) => ({ time: p.time, pnl: p.pnl - base })), warnings: walker.warnings };
|
|
161
|
+
}
|
|
162
|
+
|
|
163
|
+
// --- fetch ---
|
|
164
|
+
|
|
165
|
+
interface WireFill {
|
|
166
|
+
orderbook_id: string;
|
|
167
|
+
order_id: string;
|
|
168
|
+
initial_size: string;
|
|
169
|
+
base_amount: string;
|
|
170
|
+
timestamp: number;
|
|
171
|
+
price: string;
|
|
172
|
+
}
|
|
173
|
+
interface WireSolution {
|
|
174
|
+
orderbook_id: string;
|
|
175
|
+
timestamp: number;
|
|
176
|
+
clearing_price?: string;
|
|
177
|
+
mark_price: string;
|
|
178
|
+
funding_index?: string;
|
|
179
|
+
}
|
|
180
|
+
|
|
181
|
+
/** Immutable inputs shared by every window size and every refresh: fills as
|
|
182
|
+
* events keyed by the time ranges they cover, and ticks keyed by market and
|
|
183
|
+
* time. The fold is recomputed per request; only uncovered ranges and unseen
|
|
184
|
+
* ticks are fetched. */
|
|
185
|
+
export class PnlHistoryCache {
|
|
186
|
+
readonly ticks = new Map<string, PnlTick>();
|
|
187
|
+
/** Times at which every market's row was fetched at once. */
|
|
188
|
+
readonly tickTimes = new Set<number>();
|
|
189
|
+
private events: PnlEvent[] = [];
|
|
190
|
+
private coverage: { from: number; to: number }[] = [];
|
|
191
|
+
|
|
192
|
+
/** About 150 bytes per event and per tick, so the default cap is on the
|
|
193
|
+
* order of 50 MB with its ticks. */
|
|
194
|
+
constructor(readonly maxEvents = 250_000) {}
|
|
195
|
+
|
|
196
|
+
clear(): void {
|
|
197
|
+
this.ticks.clear();
|
|
198
|
+
this.tickTimes.clear();
|
|
199
|
+
this.events = [];
|
|
200
|
+
this.coverage = [];
|
|
201
|
+
}
|
|
202
|
+
|
|
203
|
+
/** Sub-ranges of [from, to) not yet covered. */
|
|
204
|
+
missing(from: number, to: number): { from: number; to: number }[] {
|
|
205
|
+
const out: { from: number; to: number }[] = [];
|
|
206
|
+
let cursor = from;
|
|
207
|
+
for (const c of this.coverage) {
|
|
208
|
+
if (c.to <= cursor) continue;
|
|
209
|
+
if (c.from >= to) break;
|
|
210
|
+
if (c.from > cursor) out.push({ from: cursor, to: c.from });
|
|
211
|
+
cursor = Math.max(cursor, c.to);
|
|
212
|
+
}
|
|
213
|
+
if (cursor < to) out.push({ from: cursor, to });
|
|
214
|
+
return out;
|
|
215
|
+
}
|
|
216
|
+
|
|
217
|
+
add(from: number, to: number, events: PnlEvent[]): void {
|
|
218
|
+
this.events = this.events.concat(events).sort(newestFirst);
|
|
219
|
+
this.coverage.push({ from, to });
|
|
220
|
+
this.coverage.sort((a, b) => a.from - b.from);
|
|
221
|
+
const merged: { from: number; to: number }[] = [];
|
|
222
|
+
for (const c of this.coverage) {
|
|
223
|
+
const last = merged[merged.length - 1];
|
|
224
|
+
if (last && c.from <= last.to) last.to = Math.max(last.to, c.to);
|
|
225
|
+
else merged.push({ ...c });
|
|
226
|
+
}
|
|
227
|
+
this.coverage = merged;
|
|
228
|
+
if (this.events.length > this.maxEvents) {
|
|
229
|
+
// ponytail: evict the oldest events, their ticks, and coverage below them.
|
|
230
|
+
const cut = this.events[this.maxEvents - 1]?.timeUs ?? 0;
|
|
231
|
+
this.events = this.events.filter((e) => e.timeUs >= cut);
|
|
232
|
+
this.coverage = this.coverage.filter((c) => c.to > cut).map((c) => ({ from: Math.max(c.from, cut), to: c.to }));
|
|
233
|
+
for (const k of this.ticks.keys()) if (Number(k.slice(k.indexOf(":") + 1)) < cut) this.ticks.delete(k);
|
|
234
|
+
for (const t of this.tickTimes) if (t < cut) this.tickTimes.delete(t);
|
|
235
|
+
}
|
|
236
|
+
}
|
|
237
|
+
|
|
238
|
+
/** Events with from ≤ time < to, newest first. */
|
|
239
|
+
slice(from: number, to: number): PnlEvent[] {
|
|
240
|
+
return this.events.filter((e) => e.timeUs >= from && e.timeUs < to);
|
|
241
|
+
}
|
|
242
|
+
}
|
|
243
|
+
|
|
244
|
+
export interface PnlHistoryDeps { rest: PodRestClient; rpcUrl: string; fetch?: typeof fetch; cache?: PnlHistoryCache }
|
|
245
|
+
|
|
246
|
+
const MAX_POINTS = 500;
|
|
247
|
+
const CHUNK_POINTS = 50;
|
|
248
|
+
const IN_FLIGHT = 4;
|
|
249
|
+
const WIDE_ACCOUNT_MARKETS = 10;
|
|
250
|
+
const RPC_BATCH = 200;
|
|
251
|
+
const FILLS_PAGE = 500;
|
|
252
|
+
|
|
253
|
+
/** Pages newest-first. A full page may cut a batch in half, so its oldest
|
|
254
|
+
* batch is dropped and refetched whole with the next page; rows are never
|
|
255
|
+
* keyed, since one order can legitimately fill several times in one batch
|
|
256
|
+
* (ADL slices). */
|
|
257
|
+
class FillsCursor {
|
|
258
|
+
done = false;
|
|
259
|
+
readonly warnings: string[] = [];
|
|
260
|
+
private to: number;
|
|
261
|
+
constructor(private readonly rpcUrl: string, private readonly account: Address, private readonly fromUs: number, toUs: number, private readonly opts: RpcOptions) {
|
|
262
|
+
this.to = toUs;
|
|
263
|
+
}
|
|
264
|
+
|
|
265
|
+
async next(): Promise<WireFill[]> {
|
|
266
|
+
const page = await rpc<{ fills: WireFill[] }>(this.rpcUrl, "ob_getFills", [this.account, { from_ts: this.fromUs, to_ts: this.to, limit: FILLS_PAGE }], this.opts);
|
|
267
|
+
if (page.fills.length < FILLS_PAGE) {
|
|
268
|
+
this.done = true;
|
|
269
|
+
return page.fills;
|
|
270
|
+
}
|
|
271
|
+
const oldest = Math.min(...page.fills.map((f) => f.timestamp));
|
|
272
|
+
if (oldest + 1 === this.to) {
|
|
273
|
+
// ponytail: a single batch with more than FILLS_PAGE fills is truncated here.
|
|
274
|
+
this.warnings.push(`batch ${oldest} has more than ${FILLS_PAGE} fills; only the first page is used`);
|
|
275
|
+
this.to = oldest;
|
|
276
|
+
return page.fills;
|
|
277
|
+
}
|
|
278
|
+
this.to = oldest + 1;
|
|
279
|
+
return page.fills.filter((f) => f.timestamp !== oldest);
|
|
280
|
+
}
|
|
281
|
+
}
|
|
282
|
+
|
|
283
|
+
async function drainFills(rpcUrl: string, account: Address, fromUs: number, toUs: number, opts: RpcOptions): Promise<{ fills: WireFill[]; warnings: string[] }> {
|
|
284
|
+
const cursor = new FillsCursor(rpcUrl, account, fromUs, toUs, opts);
|
|
285
|
+
const fills: WireFill[] = [];
|
|
286
|
+
while (!cursor.done) fills.push(...(await cursor.next()));
|
|
287
|
+
return { fills, warnings: cursor.warnings };
|
|
288
|
+
}
|
|
289
|
+
|
|
290
|
+
export async function fetchFills(rpcUrl: string, account: Address, fromUs: number, toUs: number, opts: RpcOptions): Promise<WireFill[]> {
|
|
291
|
+
return (await drainFills(rpcUrl, account, fromUs, toUs, opts)).fills;
|
|
292
|
+
}
|
|
293
|
+
|
|
294
|
+
export async function* streamPnlHistory(
|
|
295
|
+
deps: PnlHistoryDeps,
|
|
296
|
+
account: Address,
|
|
297
|
+
q: PnlHistoryQuery,
|
|
298
|
+
): AsyncGenerator<PnlHistoryChunk> {
|
|
299
|
+
const rpcOpts: RpcOptions = { fetch: deps.fetch };
|
|
300
|
+
|
|
301
|
+
// The snapshot is served from the live engine, fills and ticks from the
|
|
302
|
+
// indexer. Pair them: the engine's last executed batch is read together with
|
|
303
|
+
// the snapshot, one request sent just before it and one just after, and the
|
|
304
|
+
// read is retried when the two disagree. Sequential reads would be exact but
|
|
305
|
+
// straddle a 500 ms tick on every attempt from far away; concurrent ones
|
|
306
|
+
// land within a few ms of server time, so a boundary inside that gap is rare
|
|
307
|
+
// and the next refresh heals it.
|
|
308
|
+
const engineTick = async (): Promise<number> => {
|
|
309
|
+
const st = await rpc<{ last_executed_batch?: { deadline: string | number } | null }>(deps.rpcUrl, "pod_getSolverState", [], rpcOpts);
|
|
310
|
+
return Number(st.last_executed_batch?.deadline ?? 0);
|
|
311
|
+
};
|
|
312
|
+
const readSnapshot = async () => {
|
|
313
|
+
for (let attempt = 0; ; attempt++) {
|
|
314
|
+
const [before, snap, balances, after] = await Promise.all([engineTick(), deps.rest.positions(account), deps.rest.balances(account), engineTick()]);
|
|
315
|
+
if (before === after || attempt >= 4) return { nowUs: before, snap, balances };
|
|
316
|
+
}
|
|
317
|
+
};
|
|
318
|
+
const [markets, snapshot] = await Promise.all([deps.rest.markets(), readSnapshot()]);
|
|
319
|
+
const { snap, balances } = snapshot;
|
|
320
|
+
let nowUs = snapshot.nowUs;
|
|
321
|
+
const batchUs = Math.max(500, ...markets.map((m) => m.auctionIntervalMs)) * 1000;
|
|
322
|
+
// Grid points sit on batch ticks so one range call per point serves every market.
|
|
323
|
+
const fromUs = Math.ceil((q.from * 1000) / batchUs) * batchUs;
|
|
324
|
+
|
|
325
|
+
const indexerCaughtUp = async () => {
|
|
326
|
+
if (nowUs === 0) { nowUs = (await deps.rest.status()).solutionNow * 1000; return; }
|
|
327
|
+
for (let i = 0; i < 30 && (await deps.rest.status()).solutionNow * 1000 < nowUs; i++) {
|
|
328
|
+
await new Promise((r) => setTimeout(r, 100));
|
|
329
|
+
}
|
|
330
|
+
};
|
|
331
|
+
const [backstop, withdrawals] = await Promise.all([
|
|
332
|
+
deps.rest.backstopTransfers(account),
|
|
333
|
+
deps.rest.bridgeWithdrawals(account, { since: fromUs - 1 }),
|
|
334
|
+
indexerCaughtUp(),
|
|
335
|
+
]);
|
|
336
|
+
const toUs = Math.min(q.to === undefined ? nowUs : Math.floor((q.to * 1000) / batchUs) * batchUs, nowUs);
|
|
337
|
+
if (fromUs >= toUs) throw new Error("pnlHistory: from must be before to");
|
|
338
|
+
|
|
339
|
+
const points = Math.min(Math.max(2, Math.floor(q.points ?? MAX_POINTS)), MAX_POINTS);
|
|
340
|
+
const stepUs = Math.ceil((toUs - fromUs) / (points - 1) / batchUs) * batchUs;
|
|
341
|
+
// The series starts at `from` and ends at `to`; the points between sit on
|
|
342
|
+
// epoch multiples of the step, so a refreshed window shares them, and their
|
|
343
|
+
// ticks, with the previous one.
|
|
344
|
+
const gridUs: number[] = [fromUs];
|
|
345
|
+
for (let t = (Math.floor(fromUs / stepUs) + 1) * stepUs; t < toUs; t += stepUs) gridUs.push(t);
|
|
346
|
+
gridUs.push(toUs);
|
|
347
|
+
|
|
348
|
+
const byId = new Map(markets.map((m) => [m.id, m]));
|
|
349
|
+
const spotByToken = new Map(markets.filter((m) => m.type === "spot").map((m) => [m.base.address, m]));
|
|
350
|
+
const kindOf = (id: MarketId): "perp" | "spot" => (byId.get(id)?.type === "spot" ? "spot" : "perp");
|
|
351
|
+
const legs: PnlLeg[] = [];
|
|
352
|
+
for (const p of snap.positions) {
|
|
353
|
+
if (p.kind !== "perp") continue;
|
|
354
|
+
const basis = p.fundingBasis !== undefined && p.costBasis !== undefined ? p.fundingBasis - p.costBasis : undefined;
|
|
355
|
+
legs.push({ market: p.orderbookId, kind: "perp", size: p.size, basis });
|
|
356
|
+
}
|
|
357
|
+
for (const h of balances.holdings) legs.push({ market: h.orderbookId, kind: "spot", size: h.balance, basis: h.costBasis });
|
|
358
|
+
|
|
359
|
+
const cache = deps.cache ?? new PnlHistoryCache();
|
|
360
|
+
const ticks = cache.ticks;
|
|
361
|
+
const key = (m: MarketId, t: number) => `${m}:${t}`;
|
|
362
|
+
const walker = new PnlWalker(legs, (m, t) => ticks.get(key(m, t)), nowUs);
|
|
363
|
+
const known = new Set<MarketId>(legs.map((l) => l.market));
|
|
364
|
+
const use = (id: MarketId) => { if (!known.has(id)) { known.add(id); walker.touch(id, kindOf(id)); } };
|
|
365
|
+
|
|
366
|
+
const store = (row: WireSolution, t: number) => {
|
|
367
|
+
const id = row.orderbook_id as MarketId;
|
|
368
|
+
const perp = kindOf(id) === "perp";
|
|
369
|
+
const window = byId.get(id)?.fundingWindowUs ?? 0;
|
|
370
|
+
ticks.set(key(id, t), {
|
|
371
|
+
mark: perp ? dec(row.mark_price) : dec(row.clearing_price),
|
|
372
|
+
funding: perp && row.funding_index !== undefined && window > 0 ? dec(row.funding_index) / BigInt(window) : 0n,
|
|
373
|
+
});
|
|
374
|
+
};
|
|
375
|
+
// Every batch of 200 calls goes out at once; the node runs them concurrently.
|
|
376
|
+
const solutions = async (params: object[]): Promise<WireSolution[][]> => {
|
|
377
|
+
const batches: object[][] = [];
|
|
378
|
+
for (let i = 0; i < params.length; i += RPC_BATCH) batches.push(params.slice(i, i + RPC_BATCH));
|
|
379
|
+
const res = await Promise.all(batches.map((b) => rpcBatch<{ solutions: WireSolution[] }>(deps.rpcUrl, b.map((p) => ({ method: "ob_getSolutions", params: [p] })), rpcOpts)));
|
|
380
|
+
return res.flat().map((r) => r.solutions);
|
|
381
|
+
};
|
|
382
|
+
/** All markets' rows at each tick, one call per tick. */
|
|
383
|
+
const fetchAllAt = async (times: number[]) => {
|
|
384
|
+
const wanted = times.filter((t) => !cache.tickTimes.has(t));
|
|
385
|
+
const rows = await solutions(wanted.map((t) => ({ since: t, until: t + 1, limit: RPC_BATCH })));
|
|
386
|
+
rows.forEach((rs, i) => { const t = wanted[i] ?? 0; cache.tickTimes.add(t); for (const r of rs) store(r, t); });
|
|
387
|
+
};
|
|
388
|
+
/** Ticks for every known market at the grid points. One call per tick when
|
|
389
|
+
* the account spans many markets, else one lookup per market: the wide call
|
|
390
|
+
* returns every market's row whether needed or not. */
|
|
391
|
+
const fetchTicks = async (times: number[]) => {
|
|
392
|
+
if (known.size >= WIDE_ACCOUNT_MARKETS) await fetchAllAt(times);
|
|
393
|
+
else await fetchPairs(times.flatMap((t) => [...known].map((market) => ({ market, timeUs: t }))));
|
|
394
|
+
};
|
|
395
|
+
/** Newest row at or before the time, per pair; the fallback and the per-fill path. */
|
|
396
|
+
const fetchPairs = async (pairs: { market: MarketId; timeUs: number }[]) => {
|
|
397
|
+
const wanted = pairs.filter((n, i, all) => !ticks.has(key(n.market, n.timeUs)) && all.findIndex((o) => o.market === n.market && o.timeUs === n.timeUs) === i);
|
|
398
|
+
const rows = await solutions(wanted.map((n) => ({ orderbook_id: n.market, until: n.timeUs + 1, limit: 1 })));
|
|
399
|
+
rows.forEach((rs, i) => { const r = rs[0]; const n = wanted[i]; if (r && n) store(r, n.timeUs); });
|
|
400
|
+
};
|
|
401
|
+
|
|
402
|
+
const fixed: PnlEvent[] = [];
|
|
403
|
+
for (const b of backstop.transfers) {
|
|
404
|
+
const timeUs = b.time * 1000;
|
|
405
|
+
if (!b.orderbookId || b.size === 0n || timeUs < fromUs || timeUs > nowUs) continue;
|
|
406
|
+
use(b.orderbookId);
|
|
407
|
+
fixed.push({ market: b.orderbookId, timeUs, deltaSize: -b.size, price: b.markPrice, kind: "sweep" });
|
|
408
|
+
}
|
|
409
|
+
for (const w of withdrawals) {
|
|
410
|
+
if (w.error || w.timeUs < fromUs || w.timeUs > nowUs) continue;
|
|
411
|
+
const m = spotByToken.get(w.token);
|
|
412
|
+
if (!m) continue;
|
|
413
|
+
use(m.id);
|
|
414
|
+
fixed.push({ market: m.id, timeUs: w.timeUs, deltaSize: -w.amount, price: 0n, kind: "withdraw" });
|
|
415
|
+
}
|
|
416
|
+
walker.feed(fixed);
|
|
417
|
+
const preface = Promise.all([fetchTicks([nowUs]), fetchPairs(fixed.map((e) => ({ market: e.market, timeUs: e.timeUs })))]);
|
|
418
|
+
|
|
419
|
+
const toEvent = (f: WireFill): PnlEvent => {
|
|
420
|
+
const base = dec(f.base_amount);
|
|
421
|
+
return { market: f.orderbook_id as MarketId, timeUs: f.timestamp, deltaSize: dec(f.initial_size) < 0n ? -base : base, price: dec(f.price), kind: "fill" };
|
|
422
|
+
};
|
|
423
|
+
// Chunks newest-first. Chunk k needs the events in (oldest_k, oldest_{k−1}],
|
|
424
|
+
// an explicit window, so the next windows load while earlier ones are folded.
|
|
425
|
+
const chunks: number[][] = [];
|
|
426
|
+
const newestFirstGrid = [...gridUs].reverse();
|
|
427
|
+
for (let i = 0; i < newestFirstGrid.length; i += CHUNK_POINTS) chunks.push(newestFirstGrid.slice(i, i + CHUNK_POINTS));
|
|
428
|
+
const prep = async (k: number): Promise<{ events: PnlEvent[]; warnings: string[] }> => {
|
|
429
|
+
const pts = chunks[k] ?? [];
|
|
430
|
+
const oldest = pts[pts.length - 1] ?? 0;
|
|
431
|
+
const bound = k === 0 ? nowUs : (chunks[k - 1]?.at(-1) ?? nowUs);
|
|
432
|
+
const warnings: string[] = [];
|
|
433
|
+
await Promise.all(cache.missing(oldest + 1, bound + 1).map(async (r) => {
|
|
434
|
+
const page = await drainFills(deps.rpcUrl, account, r.from, r.to, rpcOpts);
|
|
435
|
+
cache.add(r.from, r.to, page.fills.map(toEvent));
|
|
436
|
+
warnings.push(...page.warnings);
|
|
437
|
+
}));
|
|
438
|
+
const events = cache.slice(oldest + 1, bound + 1);
|
|
439
|
+
await Promise.all([fetchTicks(pts), fetchPairs(events.map((e) => ({ market: e.market, timeUs: e.timeUs })))]);
|
|
440
|
+
return { events, warnings };
|
|
441
|
+
};
|
|
442
|
+
const queue: Promise<{ events: PnlEvent[]; warnings: string[] }>[] = [];
|
|
443
|
+
let nextPrep = 0;
|
|
444
|
+
for (let k = 0; k < chunks.length; k++) {
|
|
445
|
+
while (queue.length < IN_FLIGHT && nextPrep < chunks.length) {
|
|
446
|
+
const p = prep(nextPrep++);
|
|
447
|
+
p.catch(() => {});
|
|
448
|
+
queue.push(p);
|
|
449
|
+
}
|
|
450
|
+
const { events, warnings } = await (queue.shift() as Promise<{ events: PnlEvent[]; warnings: string[] }>);
|
|
451
|
+
await preface;
|
|
452
|
+
for (const e of events) use(e.market);
|
|
453
|
+
walker.feed(events);
|
|
454
|
+
const pts = chunks[k] ?? [];
|
|
455
|
+
await fetchPairs(pts.flatMap((t) => [...known].map((market) => ({ market, timeUs: t }))));
|
|
456
|
+
const out = pts.map((t) => walker.point(t)).reverse();
|
|
457
|
+
yield { points: out, done: k === chunks.length - 1, warnings: [...walker.warnings.splice(0), ...warnings] };
|
|
458
|
+
}
|
|
459
|
+
}
|
|
460
|
+
|
|
461
|
+
export async function fetchPnlHistory(deps: PnlHistoryDeps, account: Address, q: PnlHistoryQuery): Promise<PnlHistory> {
|
|
462
|
+
let points: PnlPoint[] = [];
|
|
463
|
+
const warnings: string[] = [];
|
|
464
|
+
for await (const c of streamPnlHistory(deps, account, q)) {
|
|
465
|
+
points = c.points.concat(points);
|
|
466
|
+
warnings.push(...c.warnings);
|
|
467
|
+
}
|
|
468
|
+
const base = points[0]?.pnl ?? 0n;
|
|
469
|
+
return { points: points.map((p) => ({ time: p.time, pnl: p.pnl - base })), warnings };
|
|
470
|
+
}
|
|
@@ -9,19 +9,20 @@
|
|
|
9
9
|
//
|
|
10
10
|
// EXACT replication of pod — see the cross-reference notes in pod at:
|
|
11
11
|
// trading/src/perps/mod.rs `cross_budgets` (withdrawable / equity)
|
|
12
|
-
// trading/src/perps/mod.rs `
|
|
13
|
-
// trading/src/perps/config.rs `into_market` (margin-rate derivation)
|
|
12
|
+
// trading/src/perps/mod.rs `pending_funding` (funding)
|
|
14
13
|
// Integer semantics match trading/src/decimal.rs:
|
|
15
14
|
// mul(a,b) = (a*b)/1e18 truncated toward zero (Decimal `*`)
|
|
16
15
|
// mulFloor(a,b) = (a*b)/1e18 rounded toward -infinity (`mul_floor`)
|
|
17
|
-
//
|
|
18
|
-
//
|
|
19
|
-
// funding_accrued = mulDivCeil(funding_index - entry_funding, size, window_us*1e18)
|
|
16
|
+
// funding_accrued = mul(funding_settling_index, size) - funding_basis
|
|
17
|
+
// unrealized_pnl = mul(mark, size) - cost_basis
|
|
20
18
|
// cash_with_funding = native_cash - Σ funding_accrued
|
|
19
|
+
//
|
|
20
|
+
// Nothing is reconstructed here. `funding_index` is a different base — the
|
|
21
|
+
// undivided accumulator, window_us times the index positions settle on — so it
|
|
22
|
+
// can never be subtracted from a position's entry figure.
|
|
21
23
|
|
|
22
24
|
import type { Market, MarketId, Position, PositionsSnapshot } from "../types/public.js";
|
|
23
|
-
import {
|
|
24
|
-
import { imRate, mul, mulDivCeil, mulFloor } from "../codec/fixed.js";
|
|
25
|
+
import { imRate, mul, mulFloor } from "../codec/fixed.js";
|
|
25
26
|
|
|
26
27
|
const absB = (x: bigint) => (x < 0n ? -x : x);
|
|
27
28
|
const maxB = (a: bigint, b: bigint) => (a > b ? a : b);
|
|
@@ -46,24 +47,22 @@ export function enrichPositions(snap: PositionsSnapshot, markets: Market[]): Pos
|
|
|
46
47
|
// than a spurious −entry·size that would wrongly zero withdrawable cash.
|
|
47
48
|
const liveMark = market?.markPrice && market.markPrice > 0n ? market.markPrice : p.markPrice;
|
|
48
49
|
const mark = liveMark > 0n ? liveMark : p.entryPrice;
|
|
49
|
-
|
|
50
|
+
// The entry-price fallback rounds against the holder.
|
|
51
|
+
const upnl = p.costBasis !== undefined
|
|
52
|
+
? mul(mark, p.size) - p.costBasis
|
|
53
|
+
: mulFloor(mark - p.entryPrice, p.size); // pure price drift (signed)
|
|
50
54
|
const sizeQuote = mul(absB(p.size), mark); // = notional
|
|
51
|
-
const imr = imRate(market?.maxLeverage ?? 0);
|
|
55
|
+
const imr = market?.initialMargin ?? imRate(market?.maxLeverage ?? 0);
|
|
52
56
|
im += mul(sizeQuote, imr);
|
|
53
57
|
mm += mul(sizeQuote, imr / 2n);
|
|
54
58
|
priceUpnl += upnl;
|
|
55
59
|
priceUpnlSnap += p.unrealizedPnl;
|
|
56
60
|
|
|
57
|
-
//
|
|
58
|
-
//
|
|
59
|
-
// hold the snapshot value (re-aligned by the periodic REST resync).
|
|
61
|
+
// The settling index streams via pod_markets, the basis is frozen in the
|
|
62
|
+
// snapshot. Without both, hold the snapshot's figure.
|
|
60
63
|
let funding = p.fundingAccrued;
|
|
61
|
-
if (market?.
|
|
62
|
-
funding =
|
|
63
|
-
market.fundingIndex - p.entryFunding,
|
|
64
|
-
p.size,
|
|
65
|
-
BigInt(market.fundingWindowUs) * WAD,
|
|
66
|
-
);
|
|
64
|
+
if (market?.fundingSettlingIndex !== undefined && p.fundingBasis !== undefined) {
|
|
65
|
+
funding = mul(market.fundingSettlingIndex, p.size) - p.fundingBasis;
|
|
67
66
|
}
|
|
68
67
|
fundingLiveTotal += funding;
|
|
69
68
|
fundingSnapTotal += p.fundingAccrued;
|
package/src/transport/jsonrpc.ts
CHANGED
|
@@ -52,3 +52,26 @@ export async function tryRpc<T>(
|
|
|
52
52
|
return undefined;
|
|
53
53
|
}
|
|
54
54
|
}
|
|
55
|
+
|
|
56
|
+
/** One HTTP round trip carrying many calls; results come back in call order. */
|
|
57
|
+
export async function rpcBatch<T>(
|
|
58
|
+
rpcUrl: string,
|
|
59
|
+
calls: { method: string; params: unknown[] }[],
|
|
60
|
+
opts?: RpcOptions,
|
|
61
|
+
): Promise<T[]> {
|
|
62
|
+
const doFetch = opts?.fetch ?? fetch;
|
|
63
|
+
const res = await doFetch(rpcUrl, {
|
|
64
|
+
method: "POST",
|
|
65
|
+
headers: { "content-type": "application/json" },
|
|
66
|
+
body: JSON.stringify(calls.map((c, id) => ({ jsonrpc: "2.0", id, ...c }))),
|
|
67
|
+
signal: opts?.signal,
|
|
68
|
+
});
|
|
69
|
+
const json = (await res.json()) as { id: number; result?: T; error?: { code?: number; message?: string } }[];
|
|
70
|
+
if (!Array.isArray(json)) throw new PodRpcError(undefined, "batch response is not an array");
|
|
71
|
+
const out = new Array<T>(calls.length);
|
|
72
|
+
for (const r of json) {
|
|
73
|
+
if (r.error) throw new PodRpcError(r.error.code, r.error.message ?? `${calls[r.id]?.method} failed`);
|
|
74
|
+
out[r.id] = r.result as T;
|
|
75
|
+
}
|
|
76
|
+
return out;
|
|
77
|
+
}
|
package/src/types/public.ts
CHANGED
|
@@ -170,6 +170,9 @@ export interface Market {
|
|
|
170
170
|
/** Floor on an order's notional, 0 when the market sets none. */
|
|
171
171
|
minNotional: bigint;
|
|
172
172
|
maxLeverage: number;
|
|
173
|
+
/** Initial-margin rate as the engine charges it, maintenance being half of
|
|
174
|
+
* it; `maxLeverage` is rounded to an integer, this is not. */
|
|
175
|
+
initialMargin?: bigint;
|
|
173
176
|
fundingWindowUs: number; // funding-accrual divisor (micros)
|
|
174
177
|
makerFee: bigint;
|
|
175
178
|
takerFee: bigint;
|
|
@@ -185,6 +188,10 @@ export interface Market {
|
|
|
185
188
|
markPrice?: bigint;
|
|
186
189
|
fundingRate?: bigint;
|
|
187
190
|
fundingIndex?: bigint;
|
|
191
|
+
/** The index positions settle against: `mul(fundingSettlingIndex, size) −
|
|
192
|
+
* fundingBasis` is a position's accrual. `fundingIndex` is a different
|
|
193
|
+
* base and cannot stand in for it. */
|
|
194
|
+
fundingSettlingIndex?: bigint;
|
|
188
195
|
fundingLastUpdatedMs?: number;
|
|
189
196
|
openInterest?: bigint;
|
|
190
197
|
}
|
|
@@ -306,7 +313,12 @@ export interface PerpPosition {
|
|
|
306
313
|
margin: bigint;
|
|
307
314
|
leverage: number;
|
|
308
315
|
fundingAccrued: bigint;
|
|
309
|
-
/**
|
|
316
|
+
/** `Σ settlingIndex × Δsize`; absent on older nodes. */
|
|
317
|
+
fundingBasis?: bigint;
|
|
318
|
+
/** `Σ clearing × Δsize`; absent on older nodes. */
|
|
319
|
+
costBasis?: bigint;
|
|
320
|
+
/** Funding accumulator at entry, on `fundingIndex`'s base. Truncating, so
|
|
321
|
+
* estimates from it are within a grid step × size. */
|
|
310
322
|
entryFunding: bigint;
|
|
311
323
|
liquidationPrice: bigint;
|
|
312
324
|
unrealizedPnl: bigint;
|
package/src/types/wire.ts
CHANGED
|
@@ -30,6 +30,9 @@ export interface WireMarketStatic {
|
|
|
30
30
|
lot_size: WireDecimal; // 1e18-scaled size increment
|
|
31
31
|
min_notional: WireDecimal; // 1e18-scaled notional floor ("0" = none)
|
|
32
32
|
max_leverage: number;
|
|
33
|
+
/** Initial-margin rate as the engine charges it (maintenance is half of
|
|
34
|
+
* it); absent on older nodes. */
|
|
35
|
+
initial_margin?: WireDecimal;
|
|
33
36
|
funding_window_us: number; // funding-accrual divisor (micros)
|
|
34
37
|
}
|
|
35
38
|
|
|
@@ -44,6 +47,10 @@ export interface WireMarketDynamics {
|
|
|
44
47
|
mark_price?: WireDecimal | null;
|
|
45
48
|
funding_rate?: WireDecimal | null;
|
|
46
49
|
funding_index?: WireDecimal | null;
|
|
50
|
+
/** The index positions settle against; pairs with a position's
|
|
51
|
+
* `funding_basis`. Absent on older nodes, and until the market's first perp
|
|
52
|
+
* batch after a node start. */
|
|
53
|
+
funding_settling_index?: WireDecimal | null;
|
|
47
54
|
funding_last_updated_us?: number | null;
|
|
48
55
|
open_interest?: WireDecimal | null;
|
|
49
56
|
}
|
|
@@ -172,6 +179,10 @@ export interface WirePerpPosition {
|
|
|
172
179
|
margin: WireDecimal;
|
|
173
180
|
leverage: WireDecimal;
|
|
174
181
|
funding_accrued: WireDecimal;
|
|
182
|
+
/** `Σ settling_index × Δsize`; absent on older nodes. */
|
|
183
|
+
funding_basis?: WireDecimal;
|
|
184
|
+
/** `Σ clearing × Δsize`; absent on older nodes. */
|
|
185
|
+
cost_basis?: WireDecimal;
|
|
175
186
|
entry_funding: WireDecimal;
|
|
176
187
|
liquidation_price: WireDecimal;
|
|
177
188
|
unrealized_pnl: WireDecimal;
|