@lifi/perps-sdk-provider-ondo 0.0.0-preview-7ff840c

package/src/utils/index.ts

@@ -0,0 +1,35 @@
+// biome-ignore-all lint/performance/noBarrelFile: module public entry point.
+
+export {
+  decodeActivityCursor,
+  encodeActivityCursor,
+  type OndoActivityCursor,
+} from './activityCursor.js'
+export {
+  type ApiParams,
+  ONDO_RETRY_DEFAULTS,
+  OndoApiClient,
+  type OndoApiClientOptions,
+  OndoApiError,
+  type OndoHttpMethod,
+  type OndoPage,
+  type OndoRequestOptions,
+  OndoSessionExpiredError,
+} from './apiClient.js'
+export { estimateLiquidationPrice } from './liquidation.js'
+export { mapFundingActivity, mapLiquidationActivity } from './mapActivity.js'
+export { mapFill } from './mapFill.js'
+export {
+  classifyAndMapOrders,
+  isTriggerOrder,
+  mapOrder,
+  mapOrderDetail,
+  mapOrderStatus,
+  mapOrderType,
+  mapStatusReason,
+  mapTriggerOrder,
+} from './mapOrder.js'
+export { mapOpenPositions, mapPosition } from './mapPosition.js'
+export { intervalFromBarSpan, mapInterval } from './ohlcvInterval.js'
+export { ondoAsset } from './ondoAsset.js'
+export { formatOrderPrice, formatOrderSize } from './orderFormatting.js'

package/src/utils/liquidation.ts

@@ -0,0 +1,37 @@
+/**
+ * Ondo liquidation price estimation.
+ *
+ * The LI.FI backend surfaces Ondo's per-market maintenance margin rate on the
+ * generic {@link PerpsMarket} as `maintenanceMarginRate`. The estimate is the
+ * standard isolated-margin model parameterised by that rate.
+ */
+
+import {
+  estimateIsolatedLiquidationPrice,
+  type LiquidationEstimateParams,
+} from '@lifi/perps-sdk'
+import type { PerpsMarket } from '@lifi/perps-types'
+
+/**
+ * Estimate the liquidation price of a new position on an Ondo market.
+ *
+ * @returns The estimated liquidation price, or `undefined` when
+ *   `market.maintenanceMarginRate` is absent (the model cannot be evaluated
+ *   without the venue's maintenance margin rate) or the inputs are
+ *   degenerate.
+ * @public
+ */
+export function estimateLiquidationPrice(
+  market: PerpsMarket,
+  params: LiquidationEstimateParams
+): number | undefined {
+  if (market.maintenanceMarginRate === undefined) {
+    return undefined
+  }
+  return estimateIsolatedLiquidationPrice({
+    entryPrice: params.entryPrice,
+    leverage: params.leverage,
+    isLong: params.isLong,
+    maintenanceMarginRate: market.maintenanceMarginRate,
+  })
+}

package/src/utils/mapActivity.ts

@@ -0,0 +1,61 @@
+import type {
+  FundingActivity,
+  LiquidationActivity,
+  MarketDisplay,
+} from '@lifi/perps-types'
+import { ActivityType } from '@lifi/perps-types'
+import { ONDO_PROVIDER_KEY } from '../constants.js'
+import type {
+  OndoFundingFeeTransfer,
+  OndoLiquidationEvent,
+} from '../types/wire.js'
+
+/**
+ * Map an Ondo funding-fee transfer to a {@link FundingActivity}. Ondo carries
+ * no transfer id on the wire, so a deterministic `funding:<market>:<ISO time>`
+ * id is synthesized — funding settles at most once per market per interval,
+ * so the pair is unique.
+ *
+ * @param market - Backend-resolved market identity for `transfer.market`.
+ * @public
+ */
+export const mapFundingActivity = (
+  transfer: OndoFundingFeeTransfer,
+  market: MarketDisplay
+): FundingActivity => {
+  const timestamp = new Date(transfer.time).toISOString()
+  return {
+    id: `funding:${transfer.market}:${timestamp}`,
+    provider: ONDO_PROVIDER_KEY,
+    timestamp,
+    type: ActivityType.FUNDING,
+    market,
+    amount: transfer.amount,
+    positionSize: transfer.positionSize,
+    fundingRate: transfer.rate,
+  }
+}
+
+/**
+ * Map an Ondo liquidation event to a {@link LiquidationActivity}. Ondo does
+ * not report the account value at liquidation time, and its margin accounts
+ * are cross-only, so `accountValue` is `'0'` and `leverageType` is `'cross'`.
+ *
+ * @public
+ */
+export const mapLiquidationActivity = (
+  event: OndoLiquidationEvent,
+  resolveMarket: (market: string) => MarketDisplay
+): LiquidationActivity => ({
+  id: event.id,
+  provider: ONDO_PROVIDER_KEY,
+  timestamp: new Date(event.time).toISOString(),
+  type: ActivityType.LIQUIDATION,
+  liquidatedNotionalPosition: event.filledQuoteSize ?? '0',
+  accountValue: '0',
+  leverageType: 'cross',
+  liquidatedPositions: (event.triggeringPositions ?? []).map((p) => ({
+    market: resolveMarket(p.market),
+    size: p.netQuantity,
+  })),
+})

package/src/utils/mapFill.ts

@@ -0,0 +1,47 @@
+import type { Fill, MarketDisplay } from '@lifi/perps-types'
+import {
+  FillClassification,
+  FillStatus,
+  LiquidityRole,
+  OrderSide,
+} from '@lifi/perps-types'
+import Big from 'big.js'
+import type { OndoFill, OndoFillDirection } from '../types/wire.js'
+
+const DIRECTION_CLASSIFICATIONS: Record<OndoFillDirection, FillClassification> =
+  {
+    openLong: FillClassification.OPENED_LONG,
+    openShort: FillClassification.OPENED_SHORT,
+    closeLong: FillClassification.CLOSED_LONG,
+    closeShort: FillClassification.CLOSED_SHORT,
+    flipLongToShort: FillClassification.SWITCHED_SHORT,
+    flipShortToLong: FillClassification.SWITCHED_LONG,
+  }
+
+/**
+ * Map a raw Ondo fill to the generic {@link Fill}. The fee is netted against
+ * Ondo's `feeRebate`; when the wire `direction` is absent the classification
+ * falls back to the fill side.
+ *
+ * @param market - Backend-resolved market identity for `fill.market`.
+ * @public
+ */
+export const mapFill = (fill: OndoFill, market: MarketDisplay): Fill => ({
+  id: fill.id,
+  orderId: fill.orderId,
+  market,
+  side: fill.side === 'buy' ? OrderSide.BUY : OrderSide.SELL,
+  size: fill.size,
+  price: fill.price,
+  status: FillStatus.FILLED,
+  liquidity: fill.isMaker ? LiquidityRole.MAKER : LiquidityRole.TAKER,
+  fee: new Big(fill.fee).minus(fill.feeRebate ?? '0').toFixed(),
+  realizedPnl: fill.pnl,
+  classification:
+    fill.direction !== undefined
+      ? DIRECTION_CLASSIFICATIONS[fill.direction]
+      : fill.side === 'buy'
+        ? FillClassification.OPENED_LONG
+        : FillClassification.OPENED_SHORT,
+  createdAt: new Date(fill.time).toISOString(),
+})

package/src/utils/mapOrder.ts

@@ -0,0 +1,201 @@
+import type {
+  MarketDisplay,
+  OpenOrder,
+  Order,
+  TriggerOrder,
+} from '@lifi/perps-types'
+import {
+  OrderSide,
+  OrderStatus,
+  OrderType,
+  TimeInForce,
+} from '@lifi/perps-types'
+import Big from 'big.js'
+import type {
+  OndoOrder,
+  OndoOrderStatus,
+  OndoOrderType,
+} from '../types/wire.js'
+
+const toIso = (time: string): string => new Date(time).toISOString()
+
+const mapSide = (side: OndoOrder['side']): OrderSide =>
+  side === 'buy' ? OrderSide.BUY : OrderSide.SELL
+
+/** @public */
+export const mapOrderType = (type: OndoOrderType): OrderType => {
+  switch (type) {
+    case 'limit':
+      return OrderType.LIMIT
+    case 'market':
+      return OrderType.MARKET
+    case 'stopMarket':
+      return OrderType.STOP_MARKET
+    case 'takeProfitMarket':
+      return OrderType.TAKE_PROFIT_MARKET
+  }
+}
+
+/**
+ * Map Ondo's order status onto the generic enum. `untriggered` stop orders
+ * are active resting orders from the trader's point of view, so they map to
+ * OPEN.
+ * @public
+ */
+export const mapOrderStatus = (status: OndoOrderStatus): OrderStatus => {
+  switch (status) {
+    case 'open':
+    case 'untriggered':
+      return OrderStatus.OPEN
+    case 'pending':
+      return OrderStatus.PENDING
+    case 'fullyfilled':
+      return OrderStatus.FILLED
+    case 'canceled':
+      return OrderStatus.CANCELLED
+  }
+}
+
+const CANCEL_REASON_SENTENCES: Record<string, string> = {
+  liquidation: 'Order cancelled: position was liquidated.',
+  selfMatchPrevention:
+    'Order cancelled: would self-match against your own resting order.',
+  immediateOrCancel: 'Order cancelled: immediate-or-cancel remainder.',
+}
+
+/**
+ * Plain-English `statusReason` for a cancelled order; `undefined` for every
+ * other status. Unknown wire reasons fall back to the generic sentence rather
+ * than leaking raw enum values into the UI.
+ * @public
+ */
+export const mapStatusReason = (order: OndoOrder): string | undefined => {
+  if (order.status !== 'canceled') {
+    return undefined
+  }
+  return CANCEL_REASON_SENTENCES[order.cancelReason ?? ''] ?? 'Order cancelled.'
+}
+
+/**
+ * Whether an order rests on a trigger. Checks `stopOrderType` and
+ * `triggerPrice` besides the type so a lagging `type` field cannot
+ * misclassify a trigger as a plain order.
+ * @public
+ */
+export const isTriggerOrder = (order: OndoOrder): boolean =>
+  order.type === 'stopMarket' ||
+  order.type === 'takeProfitMarket' ||
+  order.stopOrderType !== undefined ||
+  order.triggerPrice !== undefined
+
+/** Map an active non-trigger Ondo order to an {@link OpenOrder}. @public */
+export const mapOrder = (
+  order: OndoOrder,
+  market: MarketDisplay
+): OpenOrder => ({
+  orderId: order.orderId,
+  market,
+  side: mapSide(order.side),
+  type: mapOrderType(order.type),
+  size: order.size,
+  price: order.price,
+  filledSize: order.filledSize,
+  reduceOnly: order.reduceOnly ?? false,
+  createdAt: toIso(order.createdAt),
+})
+
+/** Map an active trigger Ondo order to a {@link TriggerOrder}. @public */
+export const mapTriggerOrder = (
+  order: OndoOrder,
+  market: MarketDisplay
+): TriggerOrder => ({
+  orderId: order.orderId,
+  market,
+  type: mapOrderType(order.type),
+  size: order.size,
+  triggerPrice: order.triggerPrice ?? '0',
+  createdAt: toIso(order.createdAt),
+})
+
+const TERMINAL_STATUSES: ReadonlySet<OndoOrderStatus> = new Set([
+  'canceled',
+  'fullyfilled',
+])
+
+/**
+ * Bucket a venue order list into active open/trigger orders (mapped) and
+ * terminal order ids. Orders whose market the resolver does not know are
+ * skipped.
+ * @public
+ */
+export const classifyAndMapOrders = (
+  orders: OndoOrder[],
+  resolveMarket: (market: string) => MarketDisplay | undefined
+): {
+  openOrders: OpenOrder[]
+  triggerOrders: TriggerOrder[]
+  terminated: string[]
+} => {
+  const openOrders: OpenOrder[] = []
+  const triggerOrders: TriggerOrder[] = []
+  const terminated: string[] = []
+  for (const order of orders) {
+    if (TERMINAL_STATUSES.has(order.status)) {
+      terminated.push(order.orderId)
+      continue
+    }
+    const market = resolveMarket(order.market)
+    if (market === undefined) {
+      continue
+    }
+    if (isTriggerOrder(order)) {
+      triggerOrders.push(mapTriggerOrder(order, market))
+    } else {
+      openOrders.push(mapOrder(order, market))
+    }
+  }
+  return { openOrders, triggerOrders, terminated }
+}
+
+/**
+ * Map a single venue order onto the rich {@link Order} detail shape.
+ * `remainingSize` and `averagePrice` are derived (`size − filledSize`,
+ * `filledCost ÷ filledSize`); `updatedAt` is the latest transition timestamp
+ * Ondo exposes, falling back to `createdAt`.
+ * @public
+ */
+export const mapOrderDetail = (
+  order: OndoOrder,
+  market: MarketDisplay
+): Order => {
+  const filled = new Big(order.filledSize)
+  const trigger = isTriggerOrder(order)
+  return {
+    orderId: order.orderId,
+    market,
+    side: mapSide(order.side),
+    type: mapOrderType(order.type),
+    price: order.price,
+    originalSize: order.size,
+    remainingSize: new Big(order.size).minus(filled).toFixed(),
+    filledSize: order.filledSize,
+    timeInForce:
+      order.timeInForce === undefined
+        ? undefined
+        : TimeInForce[order.timeInForce],
+    reduceOnly: order.reduceOnly ?? false,
+    isTrigger: trigger,
+    ...(trigger && order.triggerPrice !== undefined
+      ? { triggerPrice: order.triggerPrice }
+      : {}),
+    status: mapOrderStatus(order.status),
+    ...(mapStatusReason(order) !== undefined
+      ? { statusReason: mapStatusReason(order) }
+      : {}),
+    ...(filled.gt(0)
+      ? { averagePrice: new Big(order.filledCost).div(filled).toFixed() }
+      : {}),
+    createdAt: toIso(order.createdAt),
+    updatedAt: toIso(order.canceledAt ?? order.filledAt ?? order.createdAt),
+  }
+}

package/src/utils/mapPosition.ts

@@ -0,0 +1,44 @@
+import type { MarketDisplay, Position } from '@lifi/perps-types'
+import { MarginMode, PositionSide } from '@lifi/perps-types'
+import Big from 'big.js'
+import type { OndoPosition } from '../types/wire.js'
+
+/**
+ * Map a raw Ondo position to the generic Position type. Ondo margin accounts
+ * are cross-margined only.
+ *
+ * @param market - Backend-resolved market identity for `pos.market`.
+ * @public
+ */
+export const mapPosition = (
+  pos: OndoPosition,
+  market: MarketDisplay
+): Position => ({
+  market,
+  side: pos.direction === 'short' ? PositionSide.SHORT : PositionSide.LONG,
+  size: new Big(pos.netQuantity).abs().toFixed(),
+  entryPrice: pos.averageEntryPrice,
+  markPrice: pos.markPrice,
+  liquidationPrice: pos.liquidationPrice,
+  unrealizedPnl: pos.unrealizedPnl,
+  leverage: Number.parseFloat(pos.leverage),
+  marginUsed: pos.usedMargin,
+  marginMode: MarginMode.CROSS,
+})
+
+/**
+ * Map raw Ondo positions to open {@link Position}s, dropping neutral and
+ * zero-quantity rows. Only valid for payloads carrying the full position
+ * set — dropping zeros from a partial frame would make closes unobservable.
+ *
+ * @public
+ */
+export const mapOpenPositions = (
+  positions: OndoPosition[],
+  resolveMarket: (market: string) => MarketDisplay
+): Position[] =>
+  positions
+    .filter(
+      (p) => p.direction !== 'neutral' && Number.parseFloat(p.netQuantity) !== 0
+    )
+    .map((p) => mapPosition(p, resolveMarket(p.market)))

package/src/utils/ohlcvInterval.ts

@@ -0,0 +1,69 @@
+import { PerpsError } from '@lifi/perps-sdk'
+import type { OhlcvInterval } from '@lifi/perps-types'
+import { PerpsErrorCode } from '@lifi/perps-types'
+
+/**
+ * Map our `OhlcvInterval` literal to Ondo's kline `resolution` enum.
+ *
+ * Ondo exposes only the timeframes listed below. SDK intervals without a
+ * direct match (3m, 2h, 8h, 12h, 3d) raise a validation error rather than
+ * silently rounding — the caller picks a supported timeframe.
+ */
+const ONDO_SUPPORTED_INTERVALS: Record<string, string> = {
+  '1m': '1',
+  '5m': '5',
+  '15m': '15',
+  '30m': '30',
+  '1h': '1H',
+  '4h': '4H',
+  '1d': '1D',
+  '1w': '1W',
+  '1M': '1M',
+}
+
+const INTERVAL_SECONDS: Record<string, OhlcvInterval> = {
+  60: '1m',
+  300: '5m',
+  900: '15m',
+  1800: '30m',
+  3600: '1h',
+  14400: '4h',
+  86400: '1d',
+  604800: '1w',
+}
+
+const MONTH_MIN_SECS = 28 * 86400
+const MONTH_MAX_SECS = 31 * 86400
+
+/** @public */
+export const mapInterval = (interval: string): string => {
+  const resolution = ONDO_SUPPORTED_INTERVALS[interval]
+  if (!resolution) {
+    throw new PerpsError(
+      PerpsErrorCode.ValidationError,
+      `Ondo does not support OHLCV interval '${interval}'. ` +
+        `Supported: ${Object.keys(ONDO_SUPPORTED_INTERVALS).join(', ')}.`
+    )
+  }
+  return resolution
+}
+
+/**
+ * Recover the SDK interval from a kline frame's bar span in seconds. Ondo's
+ * kline updates carry no resolution field — only the interval start/end —
+ * so the span is the only way to route a frame to its subscription.
+ * @public
+ */
+export const intervalFromBarSpan = (
+  spanSecs: number
+): OhlcvInterval | undefined => {
+  const fixed = INTERVAL_SECONDS[spanSecs]
+  if (fixed !== undefined) {
+    return fixed
+  }
+  // Monthly bars span a calendar month, so their second-count varies by month.
+  if (spanSecs >= MONTH_MIN_SECS && spanSecs <= MONTH_MAX_SECS) {
+    return '1M'
+  }
+  return undefined
+}

package/src/utils/ondoAsset.ts

@@ -0,0 +1,10 @@
+import type { Asset } from '@lifi/perps-types'
+import { ONDO_PROVIDER_KEY } from '../constants.js'
+
+/** @public */
+export const ondoAsset = (id: string, displaySymbol: string): Asset => ({
+  providerId: ONDO_PROVIDER_KEY,
+  id,
+  displaySymbol,
+  logoURI: '',
+})

package/src/utils/orderFormatting.ts

@@ -0,0 +1,70 @@
+/**
+ * Ondo order size and price formatting for exchange submission.
+ *
+ * Ondo's tick and lot grids are exact contract increments (`quoteIncrement` /
+ * `baseIncrement`) that need not be powers of ten. When the generic
+ * {@link Market} carries the raw increment (`priceIncrement` / `sizeIncrement`)
+ * these helpers snap onto that grid; otherwise they fall back to the
+ * power-of-ten grid implied by `priceDecimals` / `szDecimals`. Prices round
+ * half-up to the nearest tick; sizes truncate toward zero to the lot.
+ */
+
+import { PerpsError } from '@lifi/perps-sdk'
+import { type Market, PerpsErrorCode } from '@lifi/perps-types'
+import Big from 'big.js'
+
+const powerOfTenIncrement = (decimals: number): Big => new Big(`1e-${decimals}`)
+
+const priceGrid = (market: Market): Big => {
+  if (market.priceIncrement !== undefined) {
+    return new Big(market.priceIncrement)
+  }
+  if (market.priceDecimals !== undefined) {
+    return powerOfTenIncrement(market.priceDecimals)
+  }
+  throw new PerpsError(
+    PerpsErrorCode.ValidationError,
+    `Market '${market.id}' carries no price grid; Ondo order prices cannot ` +
+      `be formatted without the market's tick increment.`
+  )
+}
+
+/**
+ * Format a price onto an Ondo market's tick grid: snapped half-up to the
+ * nearest `priceIncrement` (or the grid implied by `priceDecimals`), trailing
+ * zeros stripped.
+ *
+ * @throws {PerpsError} `ValidationError` when the market carries neither
+ *   `priceIncrement` nor `priceDecimals` — without the venue's tick grid no
+ *   correct price can be produced.
+ * @public
+ */
+export function formatOrderPrice(market: Market, price: number): string {
+  const increment = priceGrid(market)
+  const snapped = new Big(price)
+    .div(increment)
+    .round(0, Big.roundHalfUp)
+    .times(increment)
+  return snapped.eq(0) ? '0' : snapped.toFixed()
+}
+
+/**
+ * Format a size onto an Ondo market's lot grid: truncated toward zero (never
+ * rounded up, so the size cannot exceed the user's balance) to the market's
+ * `sizeIncrement` (or the grid implied by `szDecimals`), trailing zeros
+ * stripped.
+ *
+ * @param size - Size in base-asset units as a non-negative magnitude.
+ * @public
+ */
+export function formatOrderSize(market: Market, size: number): string {
+  const increment =
+    market.sizeIncrement !== undefined
+      ? new Big(market.sizeIncrement)
+      : powerOfTenIncrement(market.szDecimals)
+  const snapped = new Big(size)
+    .div(increment)
+    .round(0, Big.roundDown)
+    .times(increment)
+  return snapped.eq(0) ? '0' : snapped.toFixed()
+}