@pod-network/trade-sdk 0.2.0 → 0.3.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.map +1 -1
- package/dist/client.js +1 -12
- package/dist/client.js.map +1 -1
- package/dist/codec/decode.d.ts.map +1 -1
- package/dist/codec/decode.js +7 -6
- package/dist/codec/decode.js.map +1 -1
- package/dist/codec/direction.d.ts +10 -0
- package/dist/codec/direction.d.ts.map +1 -0
- package/dist/codec/direction.js +46 -0
- package/dist/codec/direction.js.map +1 -0
- package/dist/codec/orders-v2.d.ts +19 -0
- package/dist/codec/orders-v2.d.ts.map +1 -0
- package/dist/codec/orders-v2.js +200 -0
- package/dist/codec/orders-v2.js.map +1 -0
- package/dist/codec/units.d.ts +10 -0
- package/dist/codec/units.d.ts.map +1 -1
- package/dist/codec/units.js +16 -0
- package/dist/codec/units.js.map +1 -1
- package/dist/sync/orders.d.ts +71 -16
- package/dist/sync/orders.d.ts.map +1 -1
- package/dist/sync/orders.js +202 -83
- package/dist/sync/orders.js.map +1 -1
- package/dist/transport/ws.d.ts +19 -2
- package/dist/transport/ws.d.ts.map +1 -1
- package/dist/transport/ws.js +14 -2
- package/dist/transport/ws.js.map +1 -1
- package/dist/types/public.d.ts +125 -9
- package/dist/types/public.d.ts.map +1 -1
- package/dist/types/wire.d.ts +104 -40
- package/dist/types/wire.d.ts.map +1 -1
- package/dist/write/index.d.ts +1 -1
- package/dist/write/index.js +1 -1
- package/package.json +1 -1
- package/src/client.ts +1 -14
- package/src/codec/decode.ts +7 -6
- package/src/codec/direction.ts +36 -0
- package/src/codec/orders-v2.ts +222 -0
- package/src/codec/units.ts +16 -0
- package/src/sync/orders.ts +203 -83
- package/src/transport/ws.ts +26 -3
- package/src/types/public.ts +139 -7
- package/src/types/wire.ts +114 -28
- package/src/write/index.ts +1 -1
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
// What a perp fill did to the owner's position: opened, added to, reduced, closed
|
|
2
|
+
// or flipped it.
|
|
3
|
+
//
|
|
4
|
+
// A port of `classify_perp_order_direction` in `node/src/rpc/types.rs`, branch for
|
|
5
|
+
// branch and in the same order. It exists because the two sources of an order's
|
|
6
|
+
// direction have to agree: REST sends the server's label on `OrderResponse`, while
|
|
7
|
+
// `pod_orders_v2` sends the raw position and leaves the classification to the
|
|
8
|
+
// client. A divergence here would show one label on a streamed row and another after
|
|
9
|
+
// a refetch — so this file is a transcription, not an interpretation, and the test
|
|
10
|
+
// pins every branch.
|
|
11
|
+
|
|
12
|
+
import type { OrderDirection } from "../types/public.js";
|
|
13
|
+
|
|
14
|
+
/**
|
|
15
|
+
* Classify a position transition.
|
|
16
|
+
*
|
|
17
|
+
* `before` is not on the wire: it is `after - sign(size) * filledThisFill`, which is
|
|
18
|
+
* the same arithmetic the engine used to produce the pair (`buy_bookends` /
|
|
19
|
+
* `sell_bookends` in `trading/src/book.rs`), so deriving it loses nothing.
|
|
20
|
+
*/
|
|
21
|
+
export function classifyPerpDirection(before: bigint, after: bigint): OrderDirection {
|
|
22
|
+
if (before === 0n && after === 0n) return "reduce_long";
|
|
23
|
+
if (before === after) return before > 0n ? "reduce_long" : "reduce_short";
|
|
24
|
+
if (before === 0n && after > 0n) return "open_long";
|
|
25
|
+
if (before === 0n && after < 0n) return "open_short";
|
|
26
|
+
if (before > 0n && after === 0n) return "close_long";
|
|
27
|
+
if (before < 0n && after === 0n) return "close_short";
|
|
28
|
+
if (before > 0n && after < 0n) return "long_to_short";
|
|
29
|
+
if (before < 0n && after > 0n) return "short_to_long";
|
|
30
|
+
if (before > 0n && after > before) return "add_long";
|
|
31
|
+
if (before > 0n && after < before) return "reduce_long";
|
|
32
|
+
if (before < 0n && after < before) return "add_short";
|
|
33
|
+
if (before < 0n && after > before) return "reduce_short";
|
|
34
|
+
// Unreachable, and the Rust returns the same rather than erroring.
|
|
35
|
+
return "open_long";
|
|
36
|
+
}
|
|
@@ -0,0 +1,222 @@
|
|
|
1
|
+
// `pod_orders_v2` frames -> the public `Order` map (ADR 0029).
|
|
2
|
+
//
|
|
3
|
+
// A frame is entity/event shaped: identity and terms cross the wire once, in
|
|
4
|
+
// `orders`, and everything after that is a reference. So decoding is two passes —
|
|
5
|
+
// materialize this batch's entities, then let the events say what happened to
|
|
6
|
+
// them and to orders already held. Status lives only in the events, which is what
|
|
7
|
+
// lets the server add transition kinds without changing the entity.
|
|
8
|
+
|
|
9
|
+
import type {
|
|
10
|
+
Address, AmendRejection, Order, OrderEvent, OrderEventFill, OrderEventKind, OrderStatus,
|
|
11
|
+
PartialFill, RejectCode, TerminalStatus,
|
|
12
|
+
} from "../types/public.js";
|
|
13
|
+
import type { WireOrderEntity, WireOrderEvent, WireOrdersFrame } from "../types/wire.js";
|
|
14
|
+
import { dec, endMsFromUs, usToMs } from "./units.js";
|
|
15
|
+
import { div } from "./fixed.js";
|
|
16
|
+
import { classifyPerpDirection } from "./direction.js";
|
|
17
|
+
|
|
18
|
+
export interface OrdersFrameContext {
|
|
19
|
+
/** The account the subscription is filtered to, used when the frame omits `accts`. */
|
|
20
|
+
account: Address;
|
|
21
|
+
}
|
|
22
|
+
|
|
23
|
+
/** Per-frame facts the events need. */
|
|
24
|
+
interface FrameFacts {
|
|
25
|
+
batchMs: number;
|
|
26
|
+
accts?: WireOrdersFrame["accts"];
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
/**
|
|
30
|
+
* Fold one frame into `byId`, in place, and report the transitions it applied.
|
|
31
|
+
*
|
|
32
|
+
* Events naming an order that is not in `byId` and not in this frame are skipped:
|
|
33
|
+
* they belong to an order resting outside the caller's window, and its terms have
|
|
34
|
+
* never been on the wire, so there is nothing to display — and nothing to report.
|
|
35
|
+
*
|
|
36
|
+
* The returned events carry the order as the *whole* frame left it, not as it stood
|
|
37
|
+
* mid-frame: they are collected while applying but the rows are mutated in place, so a
|
|
38
|
+
* consumer never sees a half-applied order.
|
|
39
|
+
*/
|
|
40
|
+
export function applyOrdersFrame(frame: WireOrdersFrame, byId: Map<string, Order>, ctx: OrdersFrameContext): OrderEvent[] {
|
|
41
|
+
// The book and the batch are frame constants: resolved once, not per entity.
|
|
42
|
+
const batchMs = usToMs(frame.batch);
|
|
43
|
+
const facts: FrameFacts = { batchMs, accts: frame.accts };
|
|
44
|
+
const created = frame.orders.map((e) => decodeEntity(e, frame, batchMs, ctx.account));
|
|
45
|
+
|
|
46
|
+
const applied: OrderEvent[] = [];
|
|
47
|
+
for (const event of frame.events) {
|
|
48
|
+
// `o` indexes this frame's entities and `id` names one resting from an earlier
|
|
49
|
+
// batch — but an event kind added later (ADR 0029 §6 reserves several) may name
|
|
50
|
+
// an entity from *this* frame by id, so try both before giving up. `created` is
|
|
51
|
+
// not in `byId` yet: entities are inserted after the events, so their own
|
|
52
|
+
// `new`/`reject` decides the status they land with.
|
|
53
|
+
const target = event.o !== undefined
|
|
54
|
+
? created[event.o]
|
|
55
|
+
: byId.get(event.id ?? "") ?? created.find((o) => o.id === event.id);
|
|
56
|
+
if (!target) continue;
|
|
57
|
+
// `undefined` means a kind this version does not know, which is ignored rather than
|
|
58
|
+
// handed on as an event a consumer cannot act on (ADR 0029 §6). The switch is the
|
|
59
|
+
// only list of what is recognised — a separate one could disagree with it.
|
|
60
|
+
const outcome = applyEvent(event, target, facts);
|
|
61
|
+
if (outcome) {
|
|
62
|
+
applied.push({
|
|
63
|
+
kind: event.k as OrderEventKind,
|
|
64
|
+
order: target,
|
|
65
|
+
batchMs,
|
|
66
|
+
fill: outcome.fill,
|
|
67
|
+
amendRejection: outcome.amendRejection,
|
|
68
|
+
});
|
|
69
|
+
}
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
// After the events, not before: an entity's own `new`/`reject` decides the
|
|
73
|
+
// status it lands with. Entities left untouched by every event this version
|
|
74
|
+
// understands are still inserted — the frame said the order exists, and a
|
|
75
|
+
// transition from a newer server is no reason to drop the row.
|
|
76
|
+
for (const order of created) byId.set(order.id, order);
|
|
77
|
+
return applied;
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
function decodeEntity(e: WireOrderEntity, frame: WireOrdersFrame, batchMs: number, account: Address): Order {
|
|
81
|
+
const initialSize = dec(e.sz);
|
|
82
|
+
return {
|
|
83
|
+
id: e.id,
|
|
84
|
+
txHash: e.tx,
|
|
85
|
+
// The frame names the book, so this is exact rather than inferred. Whether
|
|
86
|
+
// that book is spot or perp is static market metadata, joined at read time by
|
|
87
|
+
// whoever needs it — freezing it here would strand every order decoded before
|
|
88
|
+
// the markets list loaded.
|
|
89
|
+
orderbookId: frame.book,
|
|
90
|
+
side: initialSize < 0n ? "sell" : "buy",
|
|
91
|
+
orderType: e.type === "market" ? "market" : "limit",
|
|
92
|
+
// Not on the entity: an order that rests is `active`, and the events below
|
|
93
|
+
// move it from there.
|
|
94
|
+
status: "active",
|
|
95
|
+
kind: (e.kind ?? "user_signed") as Order["kind"],
|
|
96
|
+
nonce: e.n,
|
|
97
|
+
// A frame with no `accts` covers exactly one account, so every row is its. An
|
|
98
|
+
// index the table does not reach falls back the same way rather than becoming an
|
|
99
|
+
// `undefined` typed as an address.
|
|
100
|
+
bidder: (e.a !== undefined ? frame.accts?.[e.a] : undefined) ?? account,
|
|
101
|
+
price: dec(e.px),
|
|
102
|
+
initialSize,
|
|
103
|
+
filledBase: 0n,
|
|
104
|
+
filledQuote: 0n,
|
|
105
|
+
fee: 0n,
|
|
106
|
+
endMs: endMsFromUs(e.end),
|
|
107
|
+
// When the order became real. The signed deadline is not on this wire and is
|
|
108
|
+
// deliberately not invented from the batch: REST reports both separately, so
|
|
109
|
+
// inclusion time is the one thing every source agrees on and the only honest
|
|
110
|
+
// key to order by.
|
|
111
|
+
includedMs: batchMs,
|
|
112
|
+
fills: [],
|
|
113
|
+
reduceOnly: e.reduce_only ?? false,
|
|
114
|
+
ioc: e.ioc ?? false,
|
|
115
|
+
triggerType: e.trigger as Order["triggerType"],
|
|
116
|
+
};
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
/**
|
|
120
|
+
* Take the order's life-to-date totals off the event that reports them.
|
|
121
|
+
*
|
|
122
|
+
* Every fill, cancel and expiry carries all three, zero included (ADR 0029 §4.1) —
|
|
123
|
+
* so they are read unconditionally, and an order that leaves the book reports what
|
|
124
|
+
* it filled rather than keeping whatever it last had. Authoritative rather than
|
|
125
|
+
* accumulated, so a client that missed a fill cannot drift.
|
|
126
|
+
*/
|
|
127
|
+
function applyTotals(event: WireOrderEvent, order: Order): void {
|
|
128
|
+
order.filledBase = dec(event.tb);
|
|
129
|
+
order.filledQuote = dec(event.tq);
|
|
130
|
+
order.fee = dec(event.tf);
|
|
131
|
+
// Cleared, not skipped, when nothing is filled: a row reporting zero filled beside
|
|
132
|
+
// a fill price from before is worse than one with no fill price.
|
|
133
|
+
order.effectivePrice = order.filledBase > 0n ? div(order.filledQuote, order.filledBase) : undefined;
|
|
134
|
+
}
|
|
135
|
+
|
|
136
|
+
/**
|
|
137
|
+
* Apply one event. `undefined` when the kind is not one this version knows; otherwise what
|
|
138
|
+
* the event contributed beyond the order's own state — the fill, or the refused amendment.
|
|
139
|
+
*/
|
|
140
|
+
function applyEvent(
|
|
141
|
+
event: WireOrderEvent,
|
|
142
|
+
order: Order,
|
|
143
|
+
facts: FrameFacts,
|
|
144
|
+
): { fill?: OrderEventFill; amendRejection?: AmendRejection } | undefined {
|
|
145
|
+
switch (event.k) {
|
|
146
|
+
case "new":
|
|
147
|
+
order.status = "active";
|
|
148
|
+
return {};
|
|
149
|
+
case "reject":
|
|
150
|
+
order.status = "invalid";
|
|
151
|
+
order.rejectReason = event.why;
|
|
152
|
+
return {};
|
|
153
|
+
case "cancel":
|
|
154
|
+
order.status = "canceled";
|
|
155
|
+
applyTotals(event, order);
|
|
156
|
+
return {};
|
|
157
|
+
case "expire":
|
|
158
|
+
order.status = "expired";
|
|
159
|
+
applyTotals(event, order);
|
|
160
|
+
return {};
|
|
161
|
+
case "modify": {
|
|
162
|
+
order.price = dec(event.px);
|
|
163
|
+
// `sz` is an unsigned magnitude, so the side comes from the order we hold.
|
|
164
|
+
const sign = order.initialSize < 0n ? -1n : 1n;
|
|
165
|
+
order.initialSize = sign * dec(event.sz);
|
|
166
|
+
return {};
|
|
167
|
+
}
|
|
168
|
+
case "fill": {
|
|
169
|
+
applyTotals(event, order);
|
|
170
|
+
// `b`/`q` are this fill alone, and its time is the batch it cleared in — the
|
|
171
|
+
// auction's own timestamp rather than when this client happened to read it.
|
|
172
|
+
const base = dec(event.b);
|
|
173
|
+
const quote = dec(event.q);
|
|
174
|
+
const fill: PartialFill = { base, quote, price: div(quote, base), time: facts.batchMs };
|
|
175
|
+
// A real fill always has size. A zero-size one is the engine flipping status: the
|
|
176
|
+
// cap-to-filled amendment fabricates it so `st: filled` reaches the indexer, which
|
|
177
|
+
// reads status from fills alone. Its totals and status count; adding a
|
|
178
|
+
// `0.0000 @ $0.00` row to the order's fill history would only invent a trade.
|
|
179
|
+
if (base !== 0n) order.fills = [...order.fills, fill];
|
|
180
|
+
// A perp fill reports the position it left. The position it started from is
|
|
181
|
+
// that minus what this fill moved it — a buy raises it, a sell lowers it — and
|
|
182
|
+
// the transition is what says whether the order opened, added to, reduced,
|
|
183
|
+
// closed or flipped. Without it a client can only guess from the order's own
|
|
184
|
+
// side and `reduceOnly`, which calls a plain sell that closed a long an
|
|
185
|
+
// "Open Short".
|
|
186
|
+
if (event.pa !== undefined) {
|
|
187
|
+
const after = dec(event.pa);
|
|
188
|
+
const before = after - (order.initialSize < 0n ? -base : base);
|
|
189
|
+
// A forced close is labelled by how it came about, not by the transition it
|
|
190
|
+
// made — `order_direction_for_response` overrides the classifier the same way,
|
|
191
|
+
// and without this a liquidation reads `close_long` here and `liquidation`
|
|
192
|
+
// after a REST refetch.
|
|
193
|
+
order.direction = order.kind === "liquidation" ? "liquidation" : classifyPerpDirection(before, after);
|
|
194
|
+
}
|
|
195
|
+
// Present only on the fill that closed the order.
|
|
196
|
+
if (event.st) order.status = event.st as OrderStatus;
|
|
197
|
+
// Copied rather than shared: the same object is in `order.fills`, and attaching a
|
|
198
|
+
// per-event field to it would leak the event into the order's fill history.
|
|
199
|
+
return {
|
|
200
|
+
fill: { ...fill, totalBase: dec(event.tb), closedAs: event.st as TerminalStatus | undefined },
|
|
201
|
+
};
|
|
202
|
+
}
|
|
203
|
+
case "modify_reject":
|
|
204
|
+
// Reported, not applied: this answers an amendment that did not happen, so the order
|
|
205
|
+
// is left exactly as it was — which is also why it belongs to the event and not to
|
|
206
|
+
// the order. Without it a refused price change looks like one still in flight.
|
|
207
|
+
// `by` is the requester, not the owner — on `not_order_owner` it is precisely who
|
|
208
|
+
// does not own the order — so it is resolved separately from `a`.
|
|
209
|
+
return {
|
|
210
|
+
amendRejection: {
|
|
211
|
+
requestedPrice: dec(event.req_px),
|
|
212
|
+
requestedSize: dec(event.req_sz),
|
|
213
|
+
code: (event.code ?? "unspecified") as RejectCode,
|
|
214
|
+
message: event.why,
|
|
215
|
+
requestedBy: event.by !== undefined ? facts.accts?.[event.by] : undefined,
|
|
216
|
+
batchMs: facts.batchMs,
|
|
217
|
+
},
|
|
218
|
+
};
|
|
219
|
+
// ADR 0029 §6: kinds are open, so an unrecognised one falls through to
|
|
220
|
+
// `undefined` — applied to nothing, reported to nobody.
|
|
221
|
+
}
|
|
222
|
+
}
|
package/src/codec/units.ts
CHANGED
|
@@ -34,6 +34,22 @@ export function usToMsOpt(us: number | string | null | undefined): number | unde
|
|
|
34
34
|
return us === null || us === undefined ? undefined : usToMs(us);
|
|
35
35
|
}
|
|
36
36
|
|
|
37
|
+
/**
|
|
38
|
+
* An order's TTL expiry: microseconds -> milliseconds, or undefined when it never
|
|
39
|
+
* expires.
|
|
40
|
+
*
|
|
41
|
+
* "Never" has two spellings on the wire. `pod_orders_v2` omits the field; REST
|
|
42
|
+
* sends the engine's `Timestamp::MAX` sentinel, a u128 that arrives as a 39-digit
|
|
43
|
+
* number no JS number can hold exactly. Anything past `Number.MAX_SAFE_INTEGER`
|
|
44
|
+
* micros — the year 2255 — is that sentinel rather than a TTL someone signed.
|
|
45
|
+
*/
|
|
46
|
+
export function endMsFromUs(us: number | string | null | undefined): number | undefined {
|
|
47
|
+
if (us === null || us === undefined) return undefined;
|
|
48
|
+
const n = typeof us === "string" ? Number(us) : us;
|
|
49
|
+
// `NaN` and `Infinity` both fail this comparison, so it is the whole guard.
|
|
50
|
+
return n <= Number.MAX_SAFE_INTEGER ? usToMs(n) : undefined;
|
|
51
|
+
}
|
|
52
|
+
|
|
37
53
|
/** Milliseconds -> microseconds (for request params that take micros). */
|
|
38
54
|
export function msToUs(ms: number): number {
|
|
39
55
|
return ms * 1000;
|
package/src/sync/orders.ts
CHANGED
|
@@ -1,39 +1,97 @@
|
|
|
1
1
|
// OrderHistory: a SeriesResource<Order> seeded from the warm first page, kept
|
|
2
|
-
// live by the
|
|
3
|
-
//
|
|
2
|
+
// live by the pod_orders_v2 stream (bidder-filtered, resumed from a (batch, book)
|
|
3
|
+
// cursor), and paged backwards by cursor for deep history.
|
|
4
4
|
//
|
|
5
5
|
// Reconnect: on every (re)connect we re-seed the first page (authoritative open
|
|
6
|
-
// orders) and refresh
|
|
7
|
-
// if
|
|
6
|
+
// orders) and refresh the cursor from its watermark; the WS auto-resubscribes,
|
|
7
|
+
// and if the cursor is too old (down too long) `onError` re-seeds and
|
|
8
|
+
// resubscribes. A server-initiated close is not the same as a rejection: it
|
|
9
|
+
// reports where delivery stopped, so resuming from one is a bare `resubscribe()`
|
|
10
|
+
// with no re-seed.
|
|
8
11
|
|
|
9
|
-
import type { Address, MarketId, Order,
|
|
10
|
-
import type {
|
|
11
|
-
import {
|
|
12
|
-
import { decodeOrder } from "../codec/decode.js";
|
|
12
|
+
import type { Address, MarketId, Order, OrderEvent, OrdersQuery } from "../types/public.js";
|
|
13
|
+
import type { WireOrdersFrame } from "../types/wire.js";
|
|
14
|
+
import { applyOrdersFrame } from "../codec/orders-v2.js";
|
|
13
15
|
import { BaseResource, type ResourceHandle } from "../stores/resource.js";
|
|
14
|
-
import type
|
|
16
|
+
import { PodSubscriptionClosedError, type SubParams, type Subscription } from "../transport/ws.js";
|
|
15
17
|
import type { SeriesResource } from "./candles.js";
|
|
16
18
|
import type { SyncContext } from "./sources.js";
|
|
17
19
|
|
|
20
|
+
/**
|
|
21
|
+
* Consecutive server closes we resume from before falling back to the re-seed
|
|
22
|
+
* path. A lagged close is recoverable by resubscribing, so the fast path is the
|
|
23
|
+
* right default — but a stream that keeps closing is one we are not keeping up
|
|
24
|
+
* with, and re-seeding beats replaying a growing backlog on every attempt.
|
|
25
|
+
*/
|
|
26
|
+
const FAST_RESUMES_BEFORE_RESEED = 3;
|
|
27
|
+
|
|
28
|
+
/**
|
|
29
|
+
* Re-seed attempts that keep the cursor before we conclude the cursor is what the
|
|
30
|
+
* server is rejecting, drop it, and settle for streaming live.
|
|
31
|
+
*/
|
|
32
|
+
const RETRIES_BEFORE_DROPPING_CURSOR = 2;
|
|
33
|
+
|
|
34
|
+
/** The largest book id, which is what an absent `sinceBook` means. */
|
|
35
|
+
const WHOLE_BATCH = `0x${"ff".repeat(32)}` as MarketId;
|
|
36
|
+
|
|
37
|
+
/**
|
|
38
|
+
* Order two positions in the stream, the way the server does.
|
|
39
|
+
*
|
|
40
|
+
* A batch is delivered as one frame per book, so a position is the pair
|
|
41
|
+
* `(batch, book)` — and an absent book means the whole batch, which sorts *above*
|
|
42
|
+
* every book in it. This mirrors `already_delivered` in
|
|
43
|
+
* `node/src/rpc/orders_v2.rs`: `(frame_batch, frame_book) <= (since,
|
|
44
|
+
* since_book.unwrap_or(0xff…))`. Getting the absent case wrong turns "all of batch
|
|
45
|
+
* N" into "up to book B of batch N", which asks the server to re-send the rest.
|
|
46
|
+
*
|
|
47
|
+
* Book ids are fixed-width lowercase hex, so comparing them as strings is
|
|
48
|
+
* comparing their bytes.
|
|
49
|
+
*/
|
|
50
|
+
export function compareCursor(a: SubParams, b: SubParams): number {
|
|
51
|
+
const aBatch = a.since ?? 0;
|
|
52
|
+
const bBatch = b.since ?? 0;
|
|
53
|
+
if (aBatch !== bBatch) return aBatch < bBatch ? -1 : 1;
|
|
54
|
+
const aBook = a.sinceBook ?? WHOLE_BATCH;
|
|
55
|
+
const bBook = b.sinceBook ?? WHOLE_BATCH;
|
|
56
|
+
return aBook === bBook ? 0 : aBook < bBook ? -1 : 1;
|
|
57
|
+
}
|
|
58
|
+
|
|
18
59
|
export class OrderHistory implements SeriesResource<Order> {
|
|
19
60
|
private readonly base: BaseResource<Order[]>;
|
|
20
61
|
private handle: ResourceHandle<Order[]> | undefined;
|
|
21
62
|
private readonly byId = new Map<string, Order>();
|
|
22
63
|
private nextCursor: string | null = null;
|
|
23
64
|
private sub: Subscription | undefined;
|
|
24
|
-
private watermarkUs = 0;
|
|
25
65
|
private alive = false;
|
|
26
66
|
private _hasMore = true;
|
|
27
67
|
private _loading = false;
|
|
28
68
|
private subRetries = 0;
|
|
69
|
+
private fastResumes = 0;
|
|
29
70
|
private retryTimer?: ReturnType<typeof setTimeout>;
|
|
71
|
+
private readonly eventListeners = new Set<(events: OrderEvent[]) => void>();
|
|
72
|
+
/**
|
|
73
|
+
* Where the stream is: the last frame accepted, as the `(batch, book)` pair the
|
|
74
|
+
* channel resumes from. Replaced whole rather than patched half at a time —
|
|
75
|
+
* `sinceBook` names a book *within* `since`, so the two are one fact and a
|
|
76
|
+
* mismatched pair asks the server to skip books we never saw.
|
|
77
|
+
*/
|
|
78
|
+
private cursor: SubParams = { since: 0, sinceBook: undefined };
|
|
79
|
+
|
|
80
|
+
/**
|
|
81
|
+
* Push the cursor to the transport, both halves.
|
|
82
|
+
*
|
|
83
|
+
* `update` merges, so sending `{ since }` alone would leave whatever `sinceBook` was
|
|
84
|
+
* there before — a book from an older batch beside a newer `since`, which asks the
|
|
85
|
+
* server to skip less than it should and re-send the difference.
|
|
86
|
+
*/
|
|
87
|
+
private pushCursor(): void {
|
|
88
|
+
this.sub?.update({ since: this.cursor.since, sinceBook: this.cursor.sinceBook });
|
|
89
|
+
}
|
|
30
90
|
|
|
31
91
|
constructor(
|
|
32
92
|
private readonly ctx: SyncContext,
|
|
33
93
|
private readonly account: Address,
|
|
34
94
|
private readonly query: OrdersQuery = {},
|
|
35
|
-
/** Maps a WS order's token pair to its orderbook id (see rebuild). */
|
|
36
|
-
private readonly resolveOrderbookId?: (pair: { base: Address; quote: Address }) => MarketId | undefined,
|
|
37
95
|
) {
|
|
38
96
|
this.base = new BaseResource<Order[]>((h) => {
|
|
39
97
|
this.handle = h;
|
|
@@ -59,6 +117,26 @@ export class OrderHistory implements SeriesResource<Order> {
|
|
|
59
117
|
loading(): boolean { return this._loading; }
|
|
60
118
|
destroy(): void { this.base.destroy(); }
|
|
61
119
|
|
|
120
|
+
/**
|
|
121
|
+
* Observe the transitions the stream reports, as they arrive — a frame at a time, in
|
|
122
|
+
* the order the engine caused them.
|
|
123
|
+
*
|
|
124
|
+
* The snapshot (`get`/`subscribe`) is what to render; this is what *happened*, which
|
|
125
|
+
* a snapshot cannot express: two fills in one batch are one state change, and a
|
|
126
|
+
* refused amendment is none at all. Nothing is emitted for the REST seed, so a
|
|
127
|
+
* consumer never has to filter out a backlog of history as if it were live.
|
|
128
|
+
*/
|
|
129
|
+
onEvent(listener: (events: OrderEvent[]) => void): () => void {
|
|
130
|
+
this.eventListeners.add(listener);
|
|
131
|
+
// Listening starts the stream, like subscribing does. The resource is ref-counted
|
|
132
|
+
// from `subscribe`/`ready` alone, so without holding one an event-only consumer
|
|
133
|
+
// would wait forever — and would fall silent the moment the last snapshot
|
|
134
|
+
// subscriber left, since teardown drops the websocket subscription and leaves the
|
|
135
|
+
// listeners registered.
|
|
136
|
+
const release = this.base.subscribe(() => {});
|
|
137
|
+
return () => { this.eventListeners.delete(listener); release(); };
|
|
138
|
+
}
|
|
139
|
+
|
|
62
140
|
setWindow(): void { /* order history pages by cursor, not by time window */ }
|
|
63
141
|
|
|
64
142
|
async loadOlder(): Promise<void> {
|
|
@@ -82,13 +160,27 @@ export class OrderHistory implements SeriesResource<Order> {
|
|
|
82
160
|
// --- internals ---
|
|
83
161
|
|
|
84
162
|
private async fetchFirstPage(): Promise<boolean> {
|
|
163
|
+
const before = this.cursor;
|
|
85
164
|
try {
|
|
86
165
|
const page = await this.ctx.rest.orders(this.account, { limit: this.query.limit ?? 100 });
|
|
87
166
|
if (!this.alive) return false;
|
|
88
|
-
|
|
167
|
+
// The transport resubscribes synchronously right after the `open` event that
|
|
168
|
+
// starts this fetch, so replayed frames can land while it is still in flight —
|
|
169
|
+
// and the indexer trails the stream by design. Overwriting a row the stream has
|
|
170
|
+
// already advanced would revert it, permanently: the cursor below refuses to
|
|
171
|
+
// rewind and `onFrame` drops a re-delivery, so nothing would repair it.
|
|
172
|
+
const streamMovedOn = compareCursor(this.cursor, before) > 0;
|
|
173
|
+
for (const o of page.orders) {
|
|
174
|
+
if (streamMovedOn && this.byId.has(o.id)) continue;
|
|
175
|
+
this.byId.set(o.id, o);
|
|
176
|
+
}
|
|
89
177
|
this.nextCursor = page.nextCursor;
|
|
90
178
|
this._hasMore = page.nextCursor !== null;
|
|
91
|
-
|
|
179
|
+
// Only ever forward, and a page settles whole batches, so its watermark
|
|
180
|
+
// carries no book — which makes it *ahead* of a stream position in the same
|
|
181
|
+
// batch, not equal to it.
|
|
182
|
+
const settled: SubParams = { since: page.solutionNow * 1000, sinceBook: undefined };
|
|
183
|
+
if (compareCursor(settled, this.cursor) > 0) this.cursor = settled;
|
|
92
184
|
this.rebuild();
|
|
93
185
|
return true;
|
|
94
186
|
} catch (e) {
|
|
@@ -102,104 +194,132 @@ export class OrderHistory implements SeriesResource<Order> {
|
|
|
102
194
|
if (!ok || !this.alive) return;
|
|
103
195
|
if (!this.sub) {
|
|
104
196
|
this.sub = this.ctx.ws.subscribe(
|
|
105
|
-
"
|
|
106
|
-
{ account: this.account,
|
|
107
|
-
(r) => this.
|
|
108
|
-
() => this.onSubError(),
|
|
197
|
+
"pod_orders_v2",
|
|
198
|
+
{ account: this.account, ...this.cursor },
|
|
199
|
+
(r) => this.onFrame(r),
|
|
200
|
+
(e) => this.onSubError(e),
|
|
109
201
|
);
|
|
110
202
|
} else {
|
|
111
|
-
this.
|
|
203
|
+
this.pushCursor(); // refresh for the next reconnect
|
|
112
204
|
}
|
|
113
205
|
});
|
|
114
206
|
}
|
|
115
207
|
|
|
116
208
|
/**
|
|
117
|
-
*
|
|
118
|
-
*
|
|
119
|
-
*
|
|
120
|
-
*
|
|
209
|
+
* The subscription is not running: `eth_subscribe` was rejected, or the server
|
|
210
|
+
* closed it.
|
|
211
|
+
*
|
|
212
|
+
* A resumable close needs neither a re-seed nor a delay: the server reports where
|
|
213
|
+
* it stopped, so resubscribing from that delivers exactly the frames we never got.
|
|
214
|
+
* That fast path is only taken while the socket is actually open — `resubscribe()`
|
|
215
|
+
* is a no-op otherwise, which would spend the budget without an attempt and leave
|
|
216
|
+
* nothing scheduled, and `-32021` (node shutting down) arrives exactly as the
|
|
217
|
+
* socket goes away.
|
|
218
|
+
*
|
|
219
|
+
* Everything else (a rejection, a server bug, a close with the socket already
|
|
220
|
+
* gone, or closes that keep coming) takes the slow path: backed off and capped, so
|
|
221
|
+
* a server that keeps refusing cannot spin this into a tight re-seed loop, and
|
|
222
|
+
* eventually the cursor is dropped (the likely culprit) to just stream live. Both
|
|
223
|
+
* counters reset once live data flows (`onFrame`).
|
|
121
224
|
*/
|
|
122
|
-
private onSubError(): void {
|
|
225
|
+
private onSubError(err: unknown): void {
|
|
123
226
|
if (!this.alive) return;
|
|
227
|
+
const canFastResume = err instanceof PodSubscriptionClosedError && err.resumable
|
|
228
|
+
&& this.fastResumes < FAST_RESUMES_BEFORE_RESEED && this.ctx.ws.state === "open";
|
|
229
|
+
if (canFastResume) {
|
|
230
|
+
this.fastResumes++;
|
|
231
|
+
// Adopt the server's watermark only when it is ahead of ours: it knows which
|
|
232
|
+
// frames it handed over, but a re-seed may already have carried us past it,
|
|
233
|
+
// and rewinding would re-deliver frames we have applied.
|
|
234
|
+
const reported: SubParams = { since: err.resumeSince, sinceBook: err.resumeSinceBook };
|
|
235
|
+
if (err.resumeSince !== undefined && compareCursor(reported, this.cursor) > 0) this.cursor = reported;
|
|
236
|
+
// The transport rewrote `sub.params` from the close before this ran, so without
|
|
237
|
+
// pushing our own decision back the wire resumes from the server's point
|
|
238
|
+
// regardless and the guard above protects nothing.
|
|
239
|
+
this.pushCursor();
|
|
240
|
+
this.sub?.resubscribe();
|
|
241
|
+
return;
|
|
242
|
+
}
|
|
243
|
+
// The slow path, and the one that answers "what if we fell behind the server's
|
|
244
|
+
// replay buffer": `eth_subscribe` rejects a `since` older than what the buffer
|
|
245
|
+
// retains, and the prescribed recovery is to backfill over REST and resubscribe.
|
|
246
|
+
// That is what this is. `fetchFirstPage` also *replaces the cursor* with the
|
|
247
|
+
// page's watermark, so the position that was too old is gone by the first retry
|
|
248
|
+
// and the resubscribe is accepted with no gap — the server replays from the page
|
|
249
|
+
// forward. Dropping the cursor below is the backstop for when even that fresh
|
|
250
|
+
// watermark is refused (the indexer further behind than the buffer retains):
|
|
251
|
+
// live-only resubscribe, trading the unreplayable window for a working stream.
|
|
252
|
+
this.scheduleReseed();
|
|
253
|
+
}
|
|
254
|
+
|
|
255
|
+
/**
|
|
256
|
+
* Back off, re-seed over REST, then resubscribe — and keep trying.
|
|
257
|
+
*
|
|
258
|
+
* The re-seed can fail too (the same node is usually behind both the stream and the
|
|
259
|
+
* indexer), and a failure has to re-arm here: not resubscribing means no further
|
|
260
|
+
* close or rejection arrives, so nothing else would ever schedule another attempt and
|
|
261
|
+
* the stream would stay down with no error surfaced. Capped, so a node that keeps
|
|
262
|
+
* refusing cannot spin this.
|
|
263
|
+
*/
|
|
264
|
+
private scheduleReseed(): void {
|
|
124
265
|
this.subRetries++;
|
|
125
266
|
const delay = Math.min(30_000, 500 * 2 ** (this.subRetries - 1));
|
|
126
267
|
if (this.retryTimer) clearTimeout(this.retryTimer);
|
|
127
268
|
this.retryTimer = setTimeout(() => {
|
|
128
269
|
void this.fetchFirstPage().then((ok) => {
|
|
129
|
-
if (!
|
|
130
|
-
|
|
270
|
+
if (!this.alive) return;
|
|
271
|
+
if (!ok) { this.scheduleReseed(); return; }
|
|
272
|
+
const tooOld = this.subRetries > RETRIES_BEFORE_DROPPING_CURSOR;
|
|
273
|
+
if (tooOld) this.sub?.update({ since: undefined, sinceBook: undefined });
|
|
274
|
+
else this.pushCursor();
|
|
131
275
|
this.sub?.resubscribe();
|
|
132
276
|
});
|
|
133
277
|
}, delay);
|
|
134
278
|
}
|
|
135
279
|
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
this.
|
|
141
|
-
|
|
280
|
+
/** One frame: everything that happened to one book in one auction batch. */
|
|
281
|
+
private onFrame(result: unknown): void {
|
|
282
|
+
// Live data flowing → the subscription is healthy on both paths.
|
|
283
|
+
this.subRetries = 0;
|
|
284
|
+
this.fastResumes = 0;
|
|
285
|
+
const frame = result as WireOrdersFrame;
|
|
286
|
+
if (!frame || !Array.isArray(frame.orders) || !Array.isArray(frame.events)) return;
|
|
142
287
|
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
const base = dec(u.base_amount);
|
|
162
|
-
const quote = dec(u.quote_amount);
|
|
163
|
-
e.fills = [...e.fills, { base, quote, price: base > 0n ? (quote * WAD) / base : 0n, time: Date.now() }];
|
|
164
|
-
}
|
|
165
|
-
break;
|
|
166
|
-
}
|
|
167
|
-
case "modified": {
|
|
168
|
-
const e = this.byId.get(u.order_id);
|
|
169
|
-
if (e) {
|
|
170
|
-
e.price = dec(u.new_price);
|
|
171
|
-
const sign = e.initialSize < 0n ? -1n : 1n;
|
|
172
|
-
e.initialSize = sign * dec(u.new_size); // new_size is an unsigned magnitude
|
|
173
|
-
}
|
|
174
|
-
break;
|
|
175
|
-
}
|
|
176
|
-
case "expired": {
|
|
177
|
-
const e = this.byId.get(u.order_id);
|
|
178
|
-
if (e) e.status = "expired";
|
|
179
|
-
break;
|
|
180
|
-
}
|
|
181
|
-
case "canceled": {
|
|
182
|
-
const e = this.byId.get(u.order_id);
|
|
183
|
-
if (e) e.status = "canceled";
|
|
184
|
-
break;
|
|
288
|
+
// Drop what we already hold. Applying a frame is not idempotent — a fill event
|
|
289
|
+
// appends to `order.fills`, and re-creating an entity resets its totals — and
|
|
290
|
+
// re-delivery is designed in: a resumed subscription replays from a cursor, and
|
|
291
|
+
// the replay boundary is a whole batch. Same predicate as the server's
|
|
292
|
+
// `already_delivered`, so client and server agree on what "already sent" means.
|
|
293
|
+
const at: SubParams = { since: frame.batch, sinceBook: frame.book };
|
|
294
|
+
if (compareCursor(at, this.cursor) <= 0) return;
|
|
295
|
+
|
|
296
|
+
const events = applyOrdersFrame(frame, this.byId, { account: this.account });
|
|
297
|
+
// A socket-level reconnect resubscribes from whatever is stored here.
|
|
298
|
+
this.cursor = at;
|
|
299
|
+
this.sub?.update(at);
|
|
300
|
+
this.rebuild();
|
|
301
|
+
// Strictly after `rebuild()`: a listener that reads the resource in response to an
|
|
302
|
+
// event must see the state that event produced, not the state before it.
|
|
303
|
+
if (events.length) {
|
|
304
|
+
for (const listener of this.eventListeners) {
|
|
305
|
+
try { listener(events); } catch { /* a listener's failure is not the stream's */ }
|
|
185
306
|
}
|
|
186
307
|
}
|
|
187
308
|
}
|
|
188
309
|
|
|
189
310
|
private rebuild(): void {
|
|
190
311
|
if (!this.handle) return;
|
|
191
|
-
// WS stream orders carry a token `pair` instead of orderbook_id — resolve
|
|
192
|
-
// it here so consumers can always filter by market. Retried every rebuild,
|
|
193
|
-
// so orders that streamed in before the markets list loaded still resolve.
|
|
194
|
-
if (this.resolveOrderbookId) {
|
|
195
|
-
for (const o of this.byId.values()) {
|
|
196
|
-
if (o.orderbookId === undefined && o.pair) o.orderbookId = this.resolveOrderbookId(o.pair);
|
|
197
|
-
}
|
|
198
|
-
}
|
|
199
312
|
let arr = [...this.byId.values()];
|
|
200
313
|
if (this.query.status) arr = arr.filter((o) => o.status === this.query.status);
|
|
201
314
|
if (this.query.orderbookId) arr = arr.filter((o) => o.orderbookId === this.query.orderbookId);
|
|
202
|
-
|
|
315
|
+
// Newest first by when the order became real. Inclusion time is the key both
|
|
316
|
+
// sources report — REST sends it alongside the signed deadline, and a frame's
|
|
317
|
+
// batch *is* it — so a REST row and a streamed row sort against each other. An
|
|
318
|
+
// order with none has not been in a batch yet, so it is newer than every order
|
|
319
|
+
// that has; the signed deadline is deliberately not a fallback, since it is a
|
|
320
|
+
// future time and would sort on a different clock.
|
|
321
|
+
const at = (o: Order) => o.includedMs ?? Number.MAX_SAFE_INTEGER;
|
|
322
|
+
arr.sort((a, b) => at(b) - at(a) || b.nonce - a.nonce);
|
|
203
323
|
this.handle.set(arr);
|
|
204
324
|
}
|
|
205
325
|
}
|