@lifi/perps-sdk-provider-ondo 9.0.0 → 11.0.0

package/src/OndoProvider.ts

@@ -17,6 +17,7 @@ import {
   type ProviderGetPositionsParams,
   type ProviderGetQuoteParams,
   type ProviderGetRunningTwapsParams,
+  paginateActivity,
   resolveQuote,
   resolveRetryPolicy,
   type SDKRequestOptions,
@@ -34,7 +35,10 @@ import type {
   ActionStep,
   ActivitiesResponse,
   ActivityItem,
+  Fill,
   FillsResponse,
+  FundingActivity,
+  LiquidationActivity,
   MarketDisplay,
   OndoAccountConfig,
   Order,
@@ -47,6 +51,7 @@ import type {
   SignedActionStep,
   SigningMethod,
   TwapOrder,
+  WithdrawalActivity,
 } from '@lifi/perps-types'
 import { ActionType, ActivityType, PerpsErrorCode } from '@lifi/perps-types'
 import type { Address } from 'viem'
@@ -73,11 +78,12 @@ import type {
   OndoOrder,
   OndoPosition,
   OndoTwapOrder,
+  OndoWalletDeposit,
+  OndoWalletWithdrawal,
 } from './types/wire.js'
 import {
   decodeActivityCursor,
   encodeActivityCursor,
-  type OndoActivityCursor,
 } from './utils/activityCursor.js'
 import {
   type ApiParams,
@@ -92,11 +98,13 @@ import {
   formatOrderPrice,
   formatOrderSize,
   listOndoDepositAddress,
+  mapDepositActivity,
   mapFill,
   mapFundingActivity,
   mapLiquidationActivity,
   mapOpenPositions,
   mapOrderDetail,
+  mapWithdrawalActivity,
   positionMarginConstraints,
 } from './utils/index.js'
 import { mapRunningTwap } from './utils/mapTwap.js'
@@ -173,6 +181,13 @@ export const ondoProvider = (
 
   const requireMarketDisplay = (marketId: string): MarketDisplay =>
     toMarketDisplay(marketRegistry().require(marketId))
+  // The droppable-row counterpart of `requireMarketDisplay`, for the history
+  // surfaces where an id the backend market list does not hold must cost only
+  // its own row. The registry warns once per unresolved id.
+  const marketDisplay = (marketId: string): MarketDisplay | undefined => {
+    const market = marketRegistry().get(marketId)
+    return market === undefined ? undefined : toMarketDisplay(market)
+  }
   const requirePerpsMarketDisplay = (marketId: string): PerpsMarketDisplay =>
     toPerpsMarketDisplay(marketRegistry().require(marketId))
 
@@ -258,7 +273,7 @@ export const ondoProvider = (
             client.get<OndoBalanceSummary>('/v1/perps/balance', {
               authToken: token.token,
             }),
-            client.get<OndoPosition[]>('/v1/perps/positions', {
+            client.get<OndoPosition[] | null>('/v1/perps/positions', {
               authToken: token.token,
             }),
             client.get<OndoAccountReferral | null>('/v1/account/referral', {
@@ -286,7 +301,7 @@ export const ondoProvider = (
           }
 
           const positions: Position[] = mapOpenPositions(
-            rawPositions,
+            rawPositions ?? [],
             requirePerpsMarketDisplay
           )
 
@@ -385,14 +400,14 @@ export const ondoProvider = (
         async (token) => {
           const client = apiClient(opts)
           const [rawPositions] = await Promise.all([
-            client.get<OndoPosition[]>('/v1/perps/positions', {
+            client.get<OndoPosition[] | null>('/v1/perps/positions', {
               authToken: token.token,
             }),
             marketRegistry().sync(),
           ])
 
           let positions: Position[] = mapOpenPositions(
-            rawPositions,
+            rawPositions ?? [],
             requirePerpsMarketDisplay
           )
           if (params.marketId !== undefined) {
@@ -443,13 +458,9 @@ export const ondoProvider = (
             marketRegistry().sync(),
           ])
 
-          const registry = marketRegistry()
           const { openOrders, triggerOrders } = classifyAndMapOrders(
             page.result,
-            (marketId) => {
-              const market = registry.get(marketId)
-              return market === undefined ? undefined : toMarketDisplay(market)
-            }
+            marketDisplay
           )
 
           const nextCursor = page.pageInfo?.nextCursor
@@ -547,9 +558,10 @@ export const ondoProvider = (
             marketRegistry().sync(),
           ])
 
-          const items = page.result.map((fill) =>
-            mapFill(fill, requireMarketDisplay(fill.market))
-          )
+          const items = page.result.flatMap((fill): Fill[] => {
+            const market = marketDisplay(fill.market)
+            return market === undefined ? [] : [mapFill(fill, market)]
+          })
 
           const nextCursor = page.pageInfo?.nextCursor
           return {
@@ -580,6 +592,9 @@ export const ondoProvider = (
           const inputCursor = decodeActivityCursor(params.cursor)
           const client = apiClient(opts)
 
+          // Ondo publishes no account-to-account transfer history. Its
+          // transfer surface moves value between the main and margin wallets
+          // of one account, which `TransferActivity` excludes.
           const wantsType = (t: ActivityType): boolean =>
             params.type === undefined || params.type.includes(t)
           const shouldFetch = (
@@ -595,6 +610,13 @@ export const ondoProvider = (
             const v = inputCursor[key]
             return typeof v === 'string' && v.length > 0
           }
+          // `/v1/wallet/deposits` and `/v1/wallet/withdrawals` accept no
+          // cursor and return the whole history in one response, so each is
+          // fetched on the first page only. Its tail rides the cursor's
+          // `overflow` list, which is what keeps a later page from either
+          // re-fetching the list or losing the rows past the limit.
+          const shouldFetchOnce = (t: ActivityType): boolean =>
+            wantsType(t) && inputCursor === undefined
           const cursorParams = (
             key: 'fundings' | 'liquidations'
           ): ApiParams => {
@@ -606,77 +628,82 @@ export const ondoProvider = (
             pageInfo: undefined,
           })
 
-          const [fundings, liquidations] = await Promise.all([
-            shouldFetch(ActivityType.FUNDING, 'fundings')
-              ? client.getPage<OndoFundingFeeTransfer>(
-                  '/v1/perps/funding_fees',
-                  {
-                    params: cursorParams('fundings'),
-                    authToken: token.token,
-                  }
-                )
-              : Promise.resolve(emptyPage<OndoFundingFeeTransfer>()),
-            shouldFetch(ActivityType.LIQUIDATION, 'liquidations')
-              ? client.getPage<OndoLiquidationEvent>(
-                  '/v1/perps/liquidation_history',
-                  {
-                    params: cursorParams('liquidations'),
-                    authToken: token.token,
-                  }
-                )
-              : Promise.resolve(emptyPage<OndoLiquidationEvent>()),
-            marketRegistry().sync(),
-          ])
+          const [fundings, liquidations, deposits, withdrawals] =
+            await Promise.all([
+              shouldFetch(ActivityType.FUNDING, 'fundings')
+                ? client.getPage<OndoFundingFeeTransfer>(
+                    '/v1/perps/funding_fees',
+                    {
+                      params: cursorParams('fundings'),
+                      authToken: token.token,
+                    }
+                  )
+                : Promise.resolve(emptyPage<OndoFundingFeeTransfer>()),
+              shouldFetch(ActivityType.LIQUIDATION, 'liquidations')
+                ? client.getPage<OndoLiquidationEvent>(
+                    '/v1/perps/liquidation_history',
+                    {
+                      params: cursorParams('liquidations'),
+                      authToken: token.token,
+                    }
+                  )
+                : Promise.resolve(emptyPage<OndoLiquidationEvent>()),
+              shouldFetchOnce(ActivityType.DEPOSIT)
+                ? client.get<OndoWalletDeposit[] | null>(
+                    '/v1/wallet/deposits',
+                    {
+                      authToken: token.token,
+                    }
+                  )
+                : Promise.resolve(null),
+              shouldFetchOnce(ActivityType.WITHDRAWAL)
+                ? client.get<OndoWalletWithdrawal[] | null>(
+                    '/v1/wallet/withdrawals',
+                    { authToken: token.token }
+                  )
+                : Promise.resolve(null),
+              // Only the funding and liquidation rows name a market. A ledger
+              // request alone must not pull the market list.
+              wantsType(ActivityType.FUNDING) ||
+              wantsType(ActivityType.LIQUIDATION)
+                ? marketRegistry().sync()
+                : Promise.resolve(),
+            ])
 
           const items: ActivityItem[] = [
-            ...fundings.result.map((f) =>
-              mapFundingActivity(f, requireMarketDisplay(f.market))
-            ),
-            ...liquidations.result.map((l) =>
-              mapLiquidationActivity(l, requireMarketDisplay)
-            ),
+            ...fundings.result.flatMap((f): FundingActivity[] => {
+              const market = marketDisplay(f.market)
+              return market === undefined ? [] : [mapFundingActivity(f, market)]
+            }),
+            // A liquidation event that names no position is dropped: the
+            // public contract guarantees a non-empty `liquidatedPositions`.
+            ...liquidations.result
+              .map((l) => mapLiquidationActivity(l, marketDisplay))
+              .filter((a): a is LiquidationActivity => a !== null),
+            ...(deposits ?? []).map(mapDepositActivity),
+            // A withdrawal Ondo reports as failed or cancelled moved no value,
+            // and `WithdrawalActivity` carries no status to say so.
+            ...(withdrawals ?? [])
+              .map(mapWithdrawalActivity)
+              .filter((a): a is WithdrawalActivity => a !== null),
           ]
 
-          const merged = [...(inputCursor?.overflow ?? []), ...items]
-
-          const filtered = merged.filter((it) => {
-            const ts = new Date(it.timestamp).getTime()
-            if (params.startTime !== undefined && ts < params.startTime) {
-              return false
-            }
-            if (params.endTime !== undefined && ts > params.endTime) {
-              return false
-            }
-            return true
-          })
-
-          filtered.sort(
-            (a, b) =>
-              new Date(b.timestamp).getTime() - new Date(a.timestamp).getTime()
+          const page = paginateActivity(
+            items,
+            inputCursor?.overflow ?? [],
+            params,
+            (overflowTail) =>
+              encodeActivityCursor({
+                fundings: fundings.pageInfo?.nextCursor,
+                liquidations: liquidations.pageInfo?.nextCursor,
+                overflow: overflowTail,
+              })
           )
 
-          const limit = params.limit ?? filtered.length
-          const emitted = filtered.slice(0, limit)
-          const overflow = filtered.slice(limit)
-
-          const nextCursorEnvelope: OndoActivityCursor = {
-            fundings: fundings.pageInfo?.nextCursor,
-            liquidations: liquidations.pageInfo?.nextCursor,
-            overflow,
-          }
-          const responseCursor = encodeActivityCursor(nextCursorEnvelope)
-          const hasMore = responseCursor !== undefined
-
           return {
             provider: ONDO_PROVIDER_KEY,
-            items: emitted,
-            pagination: {
-              limit,
-              hasMore,
-              ...(responseCursor === undefined
-                ? {}
-                : { cursor: responseCursor }),
-            },
+            items: page.items,
+            pagination: page.pagination,
           }
         }
       )

package/src/types/wire.ts

@@ -274,3 +274,66 @@ export interface OndoAccountInfo {
   privacyUnixSecs: number
   marketingConsent: string
 }
+
+/** @public */
+export type OndoDepositStatus = 'pending' | 'confirmed'
+
+/**
+ * Mirrors Ondo's `WalletDeposit` (the `GET /v1/wallet/deposits` result).
+ * Carries no id of its own — Ondo addresses a single deposit by `txid`.
+ * @public
+ */
+export interface OndoWalletDeposit {
+  coin: string
+  size: string
+  status: OndoDepositStatus
+  txid: string
+  fromAddress: string
+  time: string
+  chainId: string
+  usdValue: string
+  currentConfirmations?: number
+  requiredConfirmations?: number
+  accountId?: string
+  /** Disambiguates two deposits carried by one transaction. */
+  logIndex?: string
+}
+
+/** @public */
+export type OndoWithdrawalStatus =
+  | 'complete'
+  | 'failure'
+  | 'pending'
+  | 'cancelled'
+  | 'unknown'
+
+/**
+ * Mirrors Ondo's `WalletWithdrawal` (the `GET /v1/wallet/withdrawals` result).
+ * @public
+ */
+export interface OndoWalletWithdrawal {
+  coin: string
+  size: string
+  status: OndoWithdrawalStatus
+  address: string
+  withdrawal_id: string
+  txid: string
+  customer_withdrawal_id: string
+  time: string
+  chainId: string
+  accountId?: string
+  usdValue?: string
+  /** Fee in USD, not in the withdrawn asset. */
+  usdFee?: string
+  from?: OndoAccountWalletKey
+}
+
+/**
+ * One side of an Ondo value movement: an account id plus which of that
+ * account's two wallets held the value.
+ * @public
+ */
+export interface OndoAccountWalletKey {
+  id: string
+  wallet: 'main' | 'margin'
+}

package/src/utils/depositAddress.ts

@@ -30,6 +30,9 @@ const malformed = (message: string): OndoApiError =>
   new OndoApiError(`Ondo deposit-address response is malformed: ${message}`)
 
 const entriesFromResult = (result: unknown): unknown[] => {
+  if (result === null) {
+    return []
+  }
   if (Array.isArray(result)) {
     return result
   }
@@ -45,8 +48,9 @@ const entriesFromResult = (result: unknown): unknown[] => {
 
 /**
  * Extract the canonical Ethereum USDC address from Ondo's list response.
- * An empty list is a valid, unsatisfied setup state; malformed records are
- * errors so an API/schema failure cannot be mistaken for an absent address.
+ * A `null` result and an empty list are both valid, unsatisfied setup states;
+ * malformed records are errors so an API/schema failure cannot be mistaken for
+ * an absent address.
  */
 export const parseOndoDepositAddress = (result: unknown): Address | null => {
   const entries = entriesFromResult(result)

package/src/utils/index.ts

@@ -25,7 +25,12 @@ export {
   parseOndoDepositAddress,
 } from './depositAddress.js'
 export { estimateLiquidationPrice } from './liquidation.js'
-export { mapFundingActivity, mapLiquidationActivity } from './mapActivity.js'
+export {
+  mapDepositActivity,
+  mapFundingActivity,
+  mapLiquidationActivity,
+  mapWithdrawalActivity,
+} from './mapActivity.js'
 export { mapFill } from './mapFill.js'
 export {
   classifyAndMapOrders,

package/src/utils/mapActivity.ts

@@ -1,13 +1,17 @@
 import type {
+  DepositActivity,
   FundingActivity,
   LiquidationActivity,
   MarketDisplay,
+  WithdrawalActivity,
 } from '@lifi/perps-types'
 import { ActivityType } from '@lifi/perps-types'
 import { ONDO_PROVIDER_KEY } from '../constants.js'
 import type {
   OndoFundingFeeTransfer,
   OndoLiquidationEvent,
+  OndoWalletDeposit,
+  OndoWalletWithdrawal,
 } from '../types/wire.js'
 
 /**
@@ -37,25 +41,118 @@ export const mapFundingActivity = (
 }
 
 /**
- * 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'`.
+ * Map an Ondo liquidation event to a {@link LiquidationActivity}, or `null`
+ * when the event names no triggering position. Ondo margin accounts are
+ * cross-only, so `leverageType` is always `'cross'`. Ondo reports no account
+ * value at liquidation time, so `accountValue` stays absent. One Ondo event
+ * carries the whole cross-margin cascade in `triggeringPositions`, so every
+ * resolvable liquidated market and size reaches `liquidatedPositions`.
  *
+ * @param resolveMarket - Market identity for an Ondo market id, or `undefined`
+ * when the backend market list does not hold it. A triggering position the
+ * resolver cannot identify is dropped.
  * @public
  */
 export const mapLiquidationActivity = (
   event: OndoLiquidationEvent,
-  resolveMarket: (market: string) => MarketDisplay
-): LiquidationActivity => ({
-  id: event.id,
+  resolveMarket: (market: string) => MarketDisplay | undefined
+): LiquidationActivity | null => {
+  const resolvedPositions = (event.triggeringPositions ?? []).flatMap((p) => {
+    const market = resolveMarket(p.market)
+    return market === undefined ? [] : [{ market, size: p.netQuantity }]
+  })
+  const [firstPosition, ...restPositions] = resolvedPositions
+  if (firstPosition === undefined) {
+    return null
+  }
+  return {
+    id: event.id,
+    provider: ONDO_PROVIDER_KEY,
+    timestamp: new Date(event.time).toISOString(),
+    type: ActivityType.LIQUIDATION,
+    ...(event.filledQuoteSize === undefined
+      ? {}
+      : { liquidatedNotionalPosition: event.filledQuoteSize }),
+    leverageType: 'cross',
+    liquidatedPositions: [firstPosition, ...restPositions],
+  }
+}
+
+// Ondo reports no transaction id on a deposit it has not yet matched to a
+// chain transaction, so two such deposits would share the bare `deposit:`
+// key. Fall back to the fields the venue does report.
+const depositId = (deposit: OndoWalletDeposit): string => {
+  if (deposit.txid === '') {
+    return `deposit:${deposit.time}:${deposit.coin}:${deposit.size}`
+  }
+  return deposit.logIndex === undefined
+    ? `deposit:${deposit.txid}`
+    : `deposit:${deposit.txid}:${deposit.logIndex}`
+}
+
+/**
+ * Map an Ondo wallet deposit to a {@link DepositActivity}. Ondo carries no
+ * deposit id on the wire and addresses a single deposit by transaction id, so
+ * the id is `deposit:<txid>`, suffixed with `logIndex` when one transaction
+ * carried several deposits. `coin` is already a display symbol, so it is the
+ * normalized asset identity.
+ *
+ * @public
+ */
+export const mapDepositActivity = (
+  deposit: OndoWalletDeposit
+): DepositActivity => ({
+  id: depositId(deposit),
   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,
-  })),
+  timestamp: new Date(deposit.time).toISOString(),
+  type: ActivityType.DEPOSIT,
+  asset: deposit.coin,
+  amount: deposit.size,
+  ...(deposit.txid === ''
+    ? {}
+    : { explorerLink: `https://scan.li.fi/tx/${deposit.txid}` }),
 })
+
+const SETTLING_WITHDRAWAL_STATUSES = new Set<string>([
+  'complete',
+  'pending',
+  'unknown',
+])
+
+/** Ondo denominates a withdrawal fee in USD, whatever asset it withdraws. */
+const ONDO_WITHDRAWAL_FEE_SYMBOL = 'USD'
+
+/**
+ * Map an Ondo wallet withdrawal to a {@link WithdrawalActivity}, or `null`
+ * when the venue reports a status under which no value left the account. Ondo
+ * charges the fee in USD, so `fee.asset` is `USD` and not the withdrawn asset.
+ *
+ * @public
+ */
+export const mapWithdrawalActivity = (
+  withdrawal: OndoWalletWithdrawal
+): WithdrawalActivity | null => {
+  if (!SETTLING_WITHDRAWAL_STATUSES.has(withdrawal.status)) {
+    return null
+  }
+  return {
+    id: withdrawal.withdrawal_id,
+    provider: ONDO_PROVIDER_KEY,
+    timestamp: new Date(withdrawal.time).toISOString(),
+    type: ActivityType.WITHDRAWAL,
+    asset: withdrawal.coin,
+    amount: withdrawal.size,
+    // Loose equality also drops a `null` the live API may send for "no fee".
+    ...(withdrawal.usdFee == null
+      ? {}
+      : {
+          fee: {
+            amount: withdrawal.usdFee,
+            asset: ONDO_WITHDRAWAL_FEE_SYMBOL,
+          },
+        }),
+    ...(withdrawal.txid === ''
+      ? {}
+      : { explorerLink: `https://scan.li.fi/tx/${withdrawal.txid}` }),
+  }
+}

package/src/utils/mapFill.ts

@@ -35,7 +35,11 @@ export const mapFill = (fill: OndoFill, market: MarketDisplay): Fill => ({
   price: fill.price,
   status: FillStatus.FILLED,
   liquidity: fill.isMaker ? LiquidityRole.MAKER : LiquidityRole.TAKER,
-  fee: new Big(fill.fee).minus(fill.feeRebate ?? '0').toFixed(),
+  // Ondo charges the fill fee in the market's quote asset.
+  fee: {
+    amount: new Big(fill.fee).minus(fill.feeRebate ?? '0').toFixed(),
+    asset: market.quoteAsset.displaySymbol,
+  },
   realizedPnl: fill.pnl,
   classification:
     fill.direction !== undefined

package/src/utils/mapOrder.ts

@@ -22,6 +22,10 @@ const toIso = (time: string): string => new Date(time).toISOString()
 const mapSide = (side: OndoOrder['side']): OrderSide =>
   side === 'buy' ? OrderSide.BUY : OrderSide.SELL
 
+/** Resting quantity: submitted size minus filled size, in base-asset units. */
+const deriveRemainingSize = (size: string, filledSize: string): string =>
+  new Big(size).minus(filledSize).toFixed()
+
 /** @public */
 export const mapOrderType = (type: OndoOrderType): OrderType => {
   switch (type) {
@@ -88,7 +92,11 @@ export const isTriggerOrder = (order: OndoOrder): boolean =>
   order.stopOrderType !== undefined ||
   order.triggerPrice !== undefined
 
-/** Map an active non-trigger Ondo order to an {@link OpenOrder}. @public */
+/**
+ * Map an active non-trigger Ondo order to an {@link OpenOrder}. Ondo reports
+ * the submitted and filled quantities only, so `remainingSize` is derived.
+ * @public
+ */
 export const mapOrder = (
   order: OndoOrder,
   market: MarketDisplay
@@ -97,7 +105,8 @@ export const mapOrder = (
   market,
   side: mapSide(order.side),
   type: mapOrderType(order.type),
-  size: order.size,
+  originalSize: new Big(order.size).toFixed(),
+  remainingSize: deriveRemainingSize(order.size, order.filledSize),
   price: order.price,
   filledSize: order.filledSize,
   reduceOnly: order.reduceOnly ?? false,
@@ -177,7 +186,7 @@ export const mapOrderDetail = (
     type: mapOrderType(order.type),
     price: order.price,
     originalSize: order.size,
-    remainingSize: new Big(order.size).minus(filled).toFixed(),
+    remainingSize: deriveRemainingSize(order.size, order.filledSize),
     filledSize: order.filledSize,
     timeInForce:
       order.timeInForce === undefined