@arca-network/sdk 1.14.0 → 1.16.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/streams.js CHANGED
@@ -1,6 +1,6 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
- exports.FundingWatchStream = exports.FillWatchStream = exports.TwapWatchStream = exports.ExchangeWatchStream = exports.CandleChartStream = exports.CoverageTracker = exports.TradeWatchStream = exports.OIWatchStream = exports.CandleWatchStream = exports.PriceWatchStream = exports.MaxOrderSizeWatchStream = exports.PnlChartStream = exports.EquityChartStream = exports.AggregationWatchStream = exports.ObjectsWatchStream = exports.ObjectWatchStream = exports.BalanceWatchStream = exports.OperationWatchStream = exports.WatchStreamReadyTimeoutError = void 0;
3
+ exports.FundingWatchStream = exports.RealmFillWatchStream = exports.FillWatchStream = exports.TwapWatchStream = exports.ExchangeWatchStream = exports.CandleChartStream = exports.CoverageTracker = exports.TradeWatchStream = exports.OIWatchStream = exports.CandleWatchStream = exports.PriceWatchStream = exports.MaxOrderSizeWatchStream = exports.PnlChartStream = exports.EquityChartStream = exports.ProjectionWatchStream = exports.AggregationWatchStream = exports.ObjectsWatchStream = exports.ObjectWatchStream = exports.BalanceWatchStream = exports.OperationWatchStream = exports.WatchStreamReadyTimeoutError = void 0;
4
4
  exports.deriveActiveAssetDataFromState = deriveActiveAssetDataFromState;
5
5
  const revalue_1 = require("./revalue");
6
6
  /**
@@ -673,6 +673,112 @@ class AggregationWatchStream extends WatchStream {
673
673
  }
674
674
  }
675
675
  exports.AggregationWatchStream = AggregationWatchStream;
676
+ /**
677
+ * A live batched projection subscription: path-keyed redacted valuations
678
+ * for every object a registered projection covers, re-marked client-side
679
+ * against the mids feed between server deltas.
680
+ *
681
+ * Server frames are true deltas — they carry only the accounts that
682
+ * changed, plus a `removed` list for deleted objects — and this stream
683
+ * merges them into its map (and drops removed rows) before emitting.
684
+ * Emits the full path-keyed map on every change (server delta or mid
685
+ * tick). Rows never carry balances, reserved balances, or any field
686
+ * outside the projection's registered set — redaction is server-side; the
687
+ * client only re-marks what it was given.
688
+ */
689
+ class ProjectionWatchStream extends WatchStream {
690
+ ws;
691
+ projection;
692
+ fields;
693
+ refreshWatch;
694
+ /** Latest re-marked valuations, keyed by object path. */
695
+ valuations = {};
696
+ _watchId;
697
+ unsubs = [];
698
+ latestMids = {};
699
+ /** Server-delivered (un-re-marked) rows, keyed by path. */
700
+ structural = {};
701
+ destroyWatch;
702
+ refreshing = false;
703
+ get watchId() { return this._watchId; }
704
+ constructor(ws, projection, fields, watchId, initialValuations, destroyWatch, refreshWatch, exchange = 'sim') {
705
+ super();
706
+ this.ws = ws;
707
+ this.projection = projection;
708
+ this.fields = fields;
709
+ this.refreshWatch = refreshWatch;
710
+ this._watchId = watchId;
711
+ for (const v of initialValuations)
712
+ this.structural[v.path] = v;
713
+ this.destroyWatch = destroyWatch;
714
+ this.ws.acquireMids(exchange);
715
+ this.unsubs.push(this.ws.onStatus((status) => {
716
+ if (status === 'disconnected' && this.state !== 'loading') {
717
+ this.setState('reconnecting');
718
+ }
719
+ else if (status === 'connected' && this.state === 'reconnecting') {
720
+ this.handleReconnect();
721
+ }
722
+ }),
723
+ // A rotation swaps the socket without an outage; this watch lives on
724
+ // the retiring connection's server side, so recreate it on the new one.
725
+ this.ws.onRotated(() => this.handleReconnect()), this.ws.onProjectionValuations((eventWatchId, vals, _event, removed) => {
726
+ if (eventWatchId !== this._watchId)
727
+ return;
728
+ for (const [path, v] of Object.entries(vals))
729
+ this.structural[path] = v;
730
+ if (removed) {
731
+ for (const path of removed)
732
+ delete this.structural[path];
733
+ }
734
+ this.remarkAndEmit();
735
+ }), this.ws.onMidsUpdated((mids) => {
736
+ Object.assign(this.latestMids, mids);
737
+ this.remarkAndEmit();
738
+ }));
739
+ this.remarkAndEmit();
740
+ this.setState('connected');
741
+ }
742
+ remarkAndEmit() {
743
+ const hasPrice = Object.keys(this.latestMids).length > 0;
744
+ const out = {};
745
+ for (const [path, v] of Object.entries(this.structural)) {
746
+ out[path] = hasPrice ? (0, revalue_1.revalueProjectedValuation)(v, this.latestMids) : v;
747
+ }
748
+ this.valuations = out;
749
+ this.emit(out);
750
+ }
751
+ handleReconnect() {
752
+ if (this.refreshing)
753
+ return;
754
+ this.refreshing = true;
755
+ this.refreshWatch()
756
+ .then(({ watchId: newId, valuations, destroyWatch: newDestroy }) => {
757
+ this.destroyWatch?.();
758
+ if (this.isClosed) {
759
+ newDestroy();
760
+ return;
761
+ }
762
+ this._watchId = newId;
763
+ this.destroyWatch = newDestroy;
764
+ this.structural = {};
765
+ for (const v of valuations)
766
+ this.structural[v.path] = v;
767
+ this.remarkAndEmit();
768
+ this.setState('connected');
769
+ })
770
+ .catch(() => {
771
+ this.setState('connected');
772
+ })
773
+ .finally(() => { this.refreshing = false; });
774
+ }
775
+ doClose() {
776
+ this.unsubs.forEach(u => u());
777
+ this.ws.releaseMids();
778
+ this.destroyWatch?.();
779
+ }
780
+ }
781
+ exports.ProjectionWatchStream = ProjectionWatchStream;
676
782
  function resolutionToMs(resolution) {
677
783
  switch (resolution) {
678
784
  case '15s': return 15_000;
@@ -2417,6 +2523,226 @@ class FillWatchStream extends WatchStream {
2417
2523
  }
2418
2524
  }
2419
2525
  exports.FillWatchStream = FillWatchStream;
2526
+ // ── RealmFillWatchStream ───────────────────────────────────────────
2527
+ /**
2528
+ * Mints the opaque resume cursor for a fill from its (createdAt, id) keyset
2529
+ * position — the same encoding the server's realm-wide fills listing
2530
+ * returns. `createdAt` on both REST fills and `fill.recorded` events is the
2531
+ * position-ledger row's commit timestamp in the canonical layout, which is
2532
+ * what makes a client-minted cursor byte-identical to a server-minted one.
2533
+ */
2534
+ function encodeRealmFillCursor(createdAt, id) {
2535
+ if (!createdAt || !id)
2536
+ return '';
2537
+ return `${createdAt}|${id}`;
2538
+ }
2539
+ /**
2540
+ * Realm-wide fill stream with at-least-once delivery — see
2541
+ * `arca.watchRealmFills`.
2542
+ *
2543
+ * Delivery model — catch-up-then-tail:
2544
+ * 1. Catch-up: fills after the resume cursor are replayed in order from
2545
+ * the durable log (the realm-wide fills listing).
2546
+ * 2. Tail: live `fill.recorded` events are delivered as they happen.
2547
+ * 3. Self-heal: on a detected delivery gap, a server resync marker, or a
2548
+ * reconnect, the stream silently re-runs catch-up from its last durable
2549
+ * position.
2550
+ *
2551
+ * Consumer contract: process each fill idempotently keyed on `fill.id`,
2552
+ * then persist `cursor`. Duplicates are possible by design (a small
2553
+ * recent-id window drops most catch-up/tail overlap); missing a fill is
2554
+ * not, as long as the consumer resumes from its persisted cursor.
2555
+ * `fill.objectId` carries the owning exchange object.
2556
+ */
2557
+ class RealmFillWatchStream extends WatchStream {
2558
+ ws;
2559
+ listRealmFills;
2560
+ unsubs = [];
2561
+ startedFlag = false;
2562
+ cursorPos;
2563
+ replaying = false;
2564
+ replayQueued = false;
2565
+ replayRunning = false;
2566
+ retryTimer = null;
2567
+ seen = new Set();
2568
+ seenOrder = [];
2569
+ /**
2570
+ * Replay page size — matches the server maximum, so "partial page"
2571
+ * reliably means "head of the log reached".
2572
+ */
2573
+ static PAGE_LIMIT = 500;
2574
+ /**
2575
+ * Bound on the recent-fill-id window used to drop duplicates in the
2576
+ * catch-up/tail overlap. Best-effort only: the stream's contract is
2577
+ * at-least-once, so a duplicate escaping the window is allowed.
2578
+ */
2579
+ static DEDUPE_WINDOW = 512;
2580
+ static RETRY_BACKOFF_MAX_MS = 30_000;
2581
+ constructor(ws, listRealmFills, fromCursor) {
2582
+ super();
2583
+ this.ws = ws;
2584
+ this.listRealmFills = listRealmFills;
2585
+ this.cursorPos = fromCursor;
2586
+ this.unsubs.push(this.ws.onFillRecorded((fill, event) => this.onLiveFill(fill, event)),
2587
+ // Both loss signals funnel into the same recovery: replay the
2588
+ // durable log from the last cursor. onGap covers observed
2589
+ // deliverySeq holes and server-announced resync markers;
2590
+ // onAuthenticated covers reconnects (everything during the outage
2591
+ // was lost without a gap to observe).
2592
+ this.ws.onGap(() => this.scheduleReplay()), this.ws.onAuthenticated(() => this.scheduleReplay()));
2593
+ this.ws.watchPath('/').catch(() => { });
2594
+ // The initial catch-up (which also closes the seam between the
2595
+ // head-seed read and the live subscription) is deferred to start(),
2596
+ // on the first consumer attach — see the delivery-start note there.
2597
+ }
2598
+ /** The stream's current durable resume position. */
2599
+ get cursor() {
2600
+ return this.cursorPos;
2601
+ }
2602
+ /**
2603
+ * Begins delivery on the first consumer attach. Deferring the initial
2604
+ * catch-up (and live-tail delivery) until a consumer exists is what
2605
+ * makes `onUpdate` loss-free even when the caller attaches after an
2606
+ * intervening `await`: an emission with no callbacks registered would
2607
+ * be dropped by the base stream, and because it advances the internal
2608
+ * cursor, the next persisted position would silently skip past it — an
2609
+ * at-least-once violation. Pre-start live fills are deliberately
2610
+ * ignored; they are in the durable log, and the first replay (from a
2611
+ * cursor no delivery has advanced) re-covers them.
2612
+ */
2613
+ start() {
2614
+ if (this.startedFlag)
2615
+ return;
2616
+ this.startedFlag = true;
2617
+ this.scheduleReplay();
2618
+ }
2619
+ /** Registers an update callback and starts delivery on first attach. */
2620
+ onUpdate(cb) {
2621
+ const unsub = super.onUpdate(cb);
2622
+ this.start();
2623
+ return unsub;
2624
+ }
2625
+ /** Resolves on the first delivery, starting the stream if needed. */
2626
+ ready(timeoutMs) {
2627
+ this.start();
2628
+ return super.ready(timeoutMs);
2629
+ }
2630
+ onLiveFill(fill, event) {
2631
+ // No consumer yet: ignore rather than deliver-to-nobody. The fill is
2632
+ // in the durable log and the cursor has not moved, so the first
2633
+ // replay after start() re-covers it.
2634
+ if (!this.startedFlag)
2635
+ return;
2636
+ if (!fill.id)
2637
+ return;
2638
+ const enriched = fill.objectId || !event.entityId
2639
+ ? fill
2640
+ : { ...fill, objectId: event.entityId };
2641
+ // createdAt is empty on events from workers predating the enrichment;
2642
+ // the fill is still delivered, the cursor just doesn't advance (the
2643
+ // next replay re-covers it — duplicates over loss).
2644
+ this.deliver(enriched, encodeRealmFillCursor(fill.createdAt, fill.id), false);
2645
+ }
2646
+ /**
2647
+ * Single delivery point for both the live tail and the replay loop:
2648
+ * dedupe by fill id, advance the durable cursor, emit.
2649
+ *
2650
+ * The cursor only advances from a live fill when no replay is active or
2651
+ * queued. A live fill can arrive ahead of rows a replay hasn't scanned
2652
+ * yet; letting it advance the cursor mid-replay would let a
2653
+ * crash-then-resume skip those rows — the one failure the at-least-once
2654
+ * contract forbids.
2655
+ */
2656
+ deliver(fill, cursor, replayed) {
2657
+ const dup = this.seen.has(fill.id);
2658
+ if (!dup) {
2659
+ this.seen.add(fill.id);
2660
+ this.seenOrder.push(fill.id);
2661
+ if (this.seenOrder.length > RealmFillWatchStream.DEDUPE_WINDOW) {
2662
+ this.seen.delete(this.seenOrder.shift());
2663
+ }
2664
+ }
2665
+ if (cursor && (replayed || (!this.replaying && !this.replayQueued))) {
2666
+ this.cursorPos = cursor;
2667
+ }
2668
+ if (dup)
2669
+ return;
2670
+ this.setState('connected');
2671
+ this.emit({ fill, cursor: this.cursorPos, replayed });
2672
+ }
2673
+ scheduleReplay() {
2674
+ this.replayQueued = true;
2675
+ // Pre-start signals (a reconnect or gap before any consumer attached)
2676
+ // stay queued; start() re-invokes this once delivery may begin.
2677
+ if (!this.startedFlag || this.replayRunning || this.isClosed)
2678
+ return;
2679
+ this.replayRunning = true;
2680
+ void this.runReplay().finally(() => {
2681
+ this.replayRunning = false;
2682
+ // Lost-wakeup guard: a signal that landed between runReplay's final
2683
+ // queue check and this cleanup would otherwise sit queued forever.
2684
+ if (this.replayQueued)
2685
+ this.scheduleReplay();
2686
+ });
2687
+ }
2688
+ /**
2689
+ * Drains the durable log from the stream's cursor to the head,
2690
+ * delivering every row. REST failures retry with capped backoff —
2691
+ * streams never terminally error. Loops while further replays were
2692
+ * queued during the run.
2693
+ */
2694
+ async runReplay() {
2695
+ while (this.replayQueued && !this.isClosed) {
2696
+ this.replayQueued = false;
2697
+ this.replaying = true;
2698
+ let local = this.cursorPos;
2699
+ let backoff = 1_000;
2700
+ for (;;) {
2701
+ if (this.isClosed) {
2702
+ this.replaying = false;
2703
+ return;
2704
+ }
2705
+ let resp;
2706
+ try {
2707
+ resp = await this.listRealmFills(local, RealmFillWatchStream.PAGE_LIMIT);
2708
+ }
2709
+ catch {
2710
+ this.setState('reconnecting');
2711
+ await new Promise((resolve) => {
2712
+ this.retryTimer = setTimeout(resolve, backoff);
2713
+ });
2714
+ this.retryTimer = null;
2715
+ backoff = Math.min(backoff * 2, RealmFillWatchStream.RETRY_BACKOFF_MAX_MS);
2716
+ continue;
2717
+ }
2718
+ backoff = 1_000;
2719
+ for (const f of resp.fills) {
2720
+ this.deliver(f, encodeRealmFillCursor(f.createdAt, f.id), true);
2721
+ }
2722
+ if (resp.cursor) {
2723
+ // Ascending pages always carry the resume position (echoed on
2724
+ // an empty page), which also skips over trailing non-fill
2725
+ // ledger rows the server filtered out.
2726
+ local = resp.cursor;
2727
+ }
2728
+ if (resp.fills.length < RealmFillWatchStream.PAGE_LIMIT) {
2729
+ break; // head of the log reached
2730
+ }
2731
+ }
2732
+ if (local)
2733
+ this.cursorPos = local;
2734
+ this.replaying = false;
2735
+ this.setState('connected');
2736
+ }
2737
+ }
2738
+ doClose() {
2739
+ this.unsubs.forEach(u => u());
2740
+ if (this.retryTimer)
2741
+ clearTimeout(this.retryTimer);
2742
+ this.ws.unwatchPath('/');
2743
+ }
2744
+ }
2745
+ exports.RealmFillWatchStream = RealmFillWatchStream;
2420
2746
  /**
2421
2747
  * Live funding payment stream for an exchange Arca object.
2422
2748
  * Yields each funding payment with its {@link EventEnvelope} for correlation.