@arca-network/sdk 1.21.0 → 1.23.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,7 +1,9 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
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;
3
+ exports.FundingWatchStream = exports.RealmExchangeWatchStream = 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
+ exports.getMarketAvailability = getMarketAvailability;
4
5
  exports.deriveActiveAssetDataFromState = deriveActiveAssetDataFromState;
6
+ const types_1 = require("./types");
5
7
  const revalue_1 = require("./revalue");
6
8
  /**
7
9
  * Thrown by `WatchStream.ready(timeoutMs)` when the stream does not reach
@@ -1383,6 +1385,113 @@ function toDecimalString(value, decimals = 8) {
1383
1385
  return '0';
1384
1386
  return value.toFixed(decimals).replace(/\.?0+$/, '');
1385
1387
  }
1388
+ /** Perp-dex index of a canonical market id (`hl:<dexIndex>:<symbol>`), or null
1389
+ * when the id is not in the three-segment form (a bare symbol, or a venue that
1390
+ * does not carry a dex index). */
1391
+ function perpDexIndexOf(market) {
1392
+ if (!market)
1393
+ return null;
1394
+ const parts = market.split(':');
1395
+ if (parts.length < 3)
1396
+ return null;
1397
+ const idx = Number.parseInt(parts[1], 10);
1398
+ return Number.isInteger(idx) && idx >= 0 ? idx : null;
1399
+ }
1400
+ /**
1401
+ * Both of an account's buying-power numbers, from an {@link ExchangeState} you
1402
+ * already have. No network call.
1403
+ *
1404
+ * `watchMaxOrderSize` reports this on every tick as
1405
+ * {@link ActiveAssetData.availability}; this is the same computation for
1406
+ * callers holding a one-shot `getExchangeState` result — a market list, a
1407
+ * portfolio header, or an order ticket that is not driving a live slider.
1408
+ *
1409
+ * ```ts
1410
+ * const state = await arca.getExchangeState(objectId);
1411
+ * const a = getMarketAvailability(state, 'hl:1:NVDA');
1412
+ * a.crossDexAvailableUsd; // buying power on NVIDIA (and every non-native dex)
1413
+ * a.nativeAvailableUsd; // buying power on hl:0:* — larger when native is >10x
1414
+ * a.reservationEnforced; // whether THIS market draws on the shared pool
1415
+ * ```
1416
+ *
1417
+ * On a venue that declares no reservation both numbers are equal and
1418
+ * `reservationEnforced` is false, so a caller can render one code path.
1419
+ */
1420
+ function getMarketAvailability(exchangeState, market) {
1421
+ const summary = exchangeState.crossMarginSummary ?? exchangeState.marginSummary;
1422
+ const a = availabilityFor(exchangeState, market, parsePositiveNumber(summary?.equity), parsePositiveNumber(summary?.initialMarginUsed));
1423
+ return {
1424
+ reservationEnforced: a.enforced,
1425
+ crossDexAvailableUsd: toDecimalString(a.crossDex, 8),
1426
+ nativeAvailableUsd: toDecimalString(a.native, 8),
1427
+ reservationRate: toDecimalString(a.rate, 8),
1428
+ };
1429
+ }
1430
+ /**
1431
+ * An account on a venue with a cross-dex reservation has exactly TWO buying
1432
+ * power numbers, and this returns both.
1433
+ *
1434
+ * native = equity − totalMargin (the venue-native dex)
1435
+ * crossDex = totalCollateral − reserved (shared by EVERY other perp dex)
1436
+ * reserved = max(marginNative, rate × notionalNative) + marginOnOtherDexes
1437
+ *
1438
+ * Pinned against Hyperliquid mainnet on 2026-08-28 across three live accounts
1439
+ * and nine constructed states. Two properties are load-bearing and an earlier
1440
+ * revision of this function got both wrong:
1441
+ *
1442
+ * - The notional floor applies to the VENUE-NATIVE dex only. A position on any
1443
+ * other dex contributes exactly its own initial margin and is never charged
1444
+ * the floor.
1445
+ * - Every non-native dex shares the ONE `crossDex` number. A position on one
1446
+ * of them costs its margin uniformly — on the native dex, on itself, and on
1447
+ * every sibling alike. Only a native position is asymmetric, and only above
1448
+ * `1/rate` leverage, where the floor exceeds the margin it posted.
1449
+ *
1450
+ * The intuition: the shared pool is charged as if the native position had been
1451
+ * opened at `1/rate` leverage. Native leverage beyond that is invisible to the
1452
+ * native dex's own budget and charged in full to every other dex.
1453
+ */
1454
+ function availabilityFor(exchangeState, market, equity, initialMarginUsed) {
1455
+ const native = Math.max(0, equity - initialMarginUsed);
1456
+ const model = exchangeState.collateralModel;
1457
+ const rate = parsePositiveNumber(model?.crossDexReservationRate);
1458
+ const total = parsePositiveNumber(model?.totalCollateralUsd);
1459
+ const targetDex = perpDexIndexOf(market);
1460
+ // No declared rule (a single-pool venue), or a term the venue did not send:
1461
+ // there is one budget and it is the ordinary one. Never guess a reservation.
1462
+ if (!model?.crossDexReservationEnforced || rate <= 0 || total <= 0) {
1463
+ return { available: native, crossDex: native, native, enforced: false, rate };
1464
+ }
1465
+ let marginNative = 0;
1466
+ let notionalNative = 0;
1467
+ let marginOtherDexes = 0;
1468
+ for (const p of exchangeState.positions ?? []) {
1469
+ const d = perpDexIndexOf(p.market);
1470
+ if (d === null)
1471
+ continue;
1472
+ const mu = parsePositiveNumber(p.marginUsed);
1473
+ if (d === 0) {
1474
+ marginNative += mu;
1475
+ notionalNative += parsePositiveNumber(p.positionValue);
1476
+ }
1477
+ else {
1478
+ marginOtherDexes += mu;
1479
+ }
1480
+ }
1481
+ const reserved = Math.max(marginNative, rate * notionalNative) + marginOtherDexes;
1482
+ const crossDex = Math.max(0, total - reserved);
1483
+ // The native dex keeps the ordinary budget; every other dex draws on the
1484
+ // shared pool — including one this account already holds a position on,
1485
+ // because adding there still has to move collateral into it.
1486
+ const onNativeDex = targetDex === 0;
1487
+ return {
1488
+ available: onNativeDex ? native : crossDex,
1489
+ crossDex,
1490
+ native,
1491
+ enforced: !onNativeDex,
1492
+ rate,
1493
+ };
1494
+ }
1386
1495
  function deriveActiveAssetDataFromState(exchangeState, market, markPx, leverage, side, builderFeeBps = 0, szDecimals = 5, feeScale = 1,
1387
1496
  // Per-asset base MMR resolved by the caller (e.g. from the initial
1388
1497
  // `getActiveAssetData` fetch). Server derives this from the asset's margin
@@ -1410,7 +1519,8 @@ askRatio = 1, bidRatio = 1) {
1410
1519
  const initialMarginUsed = parsePositiveNumber(summary?.initialMarginUsed);
1411
1520
  const hasPositions = (exchangeState.positions?.length ?? 0) > 0;
1412
1521
  const availableGuard = hasPositions ? 0.97 : 1.0;
1413
- const available = Math.max(0, (equity - initialMarginUsed) * availableGuard);
1522
+ const avail = availabilityFor(exchangeState, market, equity, initialMarginUsed);
1523
+ const available = Math.max(0, avail.available * availableGuard);
1414
1524
  const takerRate = parsePositiveNumber(exchangeState.feeRates?.taker);
1415
1525
  const effectiveScale = Number.isFinite(feeScale) && feeScale > 0 ? feeScale : 1;
1416
1526
  const platformRate = parsePositiveNumber(exchangeState.feeRates?.platformFee) || DEFAULT_PLATFORM_FEE_RATE;
@@ -1508,7 +1618,7 @@ askRatio = 1, bidRatio = 1) {
1508
1618
  const buyMax = buyReduce + buyOpen;
1509
1619
  const sellMax = sellReduce + sellOpen;
1510
1620
  const leverageInfo = { type: 'cross', value: leverage };
1511
- const rawAvailableUsd = Math.max(0, equity - initialMarginUsed);
1621
+ const rawAvailableUsd = avail.available;
1512
1622
  return {
1513
1623
  market,
1514
1624
  leverage: leverageInfo,
@@ -1521,6 +1631,12 @@ askRatio = 1, bidRatio = 1) {
1521
1631
  maxSellReduceSize: toDecimalString(sellReduce, szDecimals),
1522
1632
  maxSellOpenSize: toDecimalString(sellOpen, szDecimals),
1523
1633
  availableToTrade: toDecimalString(rawAvailableUsd, 8),
1634
+ availability: {
1635
+ reservationEnforced: avail.enforced,
1636
+ crossDexAvailableUsd: toDecimalString(avail.crossDex, 8),
1637
+ nativeAvailableUsd: toDecimalString(avail.native, 8),
1638
+ reservationRate: toDecimalString(avail.rate, 8),
1639
+ },
1524
1640
  markPx: toDecimalString(markPx, 8),
1525
1641
  feeRate: toDecimalString(feeRate, 8),
1526
1642
  maintenanceMarginRate: maintenanceMarginRate ?? '0.03',
@@ -2831,6 +2947,74 @@ class RealmFillWatchStream extends WatchStream {
2831
2947
  }
2832
2948
  }
2833
2949
  exports.RealmFillWatchStream = RealmFillWatchStream;
2950
+ /**
2951
+ * Realm-wide live-tail of `exchange.updated`. See `arca.watchRealmExchange`.
2952
+ *
2953
+ * Delivery model — live-tail, not catch-up-then-tail:
2954
+ * 1. Live events carry the serve-path open book (`state`), including
2955
+ * `liquidationPrice`. Rewrite every open row on that account.
2956
+ * 2. There is no durable log. A delivery gap or reconnect emits one
2957
+ * update with `resync: true`; re-seed the books you already hold
2958
+ * (one GET per object, not a realm walk). This stream never fans
2959
+ * out `getExchangeState`.
2960
+ * 3. A name-only event (`state` absent, `resync: false`) is degraded
2961
+ * for that one object.
2962
+ *
2963
+ * Delivery begins when the first consumer attaches (`onUpdate`). Events
2964
+ * before that attach are dropped.
2965
+ */
2966
+ class RealmExchangeWatchStream extends WatchStream {
2967
+ ws;
2968
+ unsubs = [];
2969
+ started = false;
2970
+ haveAuth = false;
2971
+ constructor(ws) {
2972
+ super();
2973
+ this.ws = ws;
2974
+ this.ws.subscribeEvents([types_1.EventType.ExchangeUpdated]);
2975
+ this.unsubs.push(this.ws.onExchangeNotification((event) => this.onEvent(event)), this.ws.onGap(() => this.onLoss()), this.ws.onAuthenticated(() => this.onAuthenticated()));
2976
+ }
2977
+ start() {
2978
+ this.started = true;
2979
+ }
2980
+ onUpdate(cb) {
2981
+ const unsub = super.onUpdate(cb);
2982
+ this.start();
2983
+ return unsub;
2984
+ }
2985
+ ready(timeoutMs) {
2986
+ this.start();
2987
+ return super.ready(timeoutMs);
2988
+ }
2989
+ onEvent(event) {
2990
+ if (!this.started)
2991
+ return;
2992
+ this.emit({
2993
+ objectId: event.entityId ?? '',
2994
+ objectPath: event.entityPath ?? '',
2995
+ state: event.exchangeState,
2996
+ resync: false,
2997
+ });
2998
+ this.setState('connected');
2999
+ }
3000
+ onAuthenticated() {
3001
+ const first = !this.haveAuth;
3002
+ this.haveAuth = true;
3003
+ if (!this.started || first)
3004
+ return;
3005
+ this.emit({ objectId: '', objectPath: '', resync: true });
3006
+ }
3007
+ onLoss() {
3008
+ if (!this.started)
3009
+ return;
3010
+ this.emit({ objectId: '', objectPath: '', resync: true });
3011
+ }
3012
+ doClose() {
3013
+ this.unsubs.forEach(u => u());
3014
+ this.ws.unsubscribeEvents([types_1.EventType.ExchangeUpdated]);
3015
+ }
3016
+ }
3017
+ exports.RealmExchangeWatchStream = RealmExchangeWatchStream;
2834
3018
  /**
2835
3019
  * Live funding payment stream for an exchange Arca object.
2836
3020
  * Yields each funding payment with its {@link EventEnvelope} for correlation.