@lifi/perps-types 3.3.2 → 4.0.1

package/src/market.ts

@@ -1,22 +1,34 @@
 import type { Asset } from './asset.js'
+import type { PositionMarginAdjustment } from './enums.js'
 
-/** @public */
+/**
+ * Current funding rate and next funding timestamp for a perpetual market.
+ * `rate` is a decimal fraction; `nextFundingTime` is Unix milliseconds.
+ *
+ * @public
+ */
 export interface FundingInfo {
+  /** Funding rate as a decimal fraction. */
   rate: string
+  /** Next funding timestamp in Unix milliseconds. */
   nextFundingTime: number
 }
 
-/** @public */
+/**
+ * Shared market metadata for perpetual and spot instruments.
+ *
+ * @public
+ */
 export interface BaseMarket {
   providerId: string
   /** Opaque provider market id; referenced elsewhere as `marketId`. */
   id: string
-  /** Whether the venue has delisted this market. */
   isDelisted?: boolean
   /** References a {@link ProviderCategory} by id. */
   categoryId: string
   baseAsset: Asset
   quoteAsset: Asset
+  /** Maximum fractional precision accepted for order sizes. */
   szDecimals: number
   /**
    * Maximum decimal places the venue accepts for order prices on this market.
@@ -41,10 +53,16 @@ export interface BaseMarket {
   sizeIncrement?: string
 }
 
-/** @public */
+/**
+ * Perpetual market metadata, including leverage and margin constraints.
+ *
+ * @public
+ */
 export interface PerpsMarket extends BaseMarket {
   maxLeverage: number
   onlyIsolated: boolean
+  /** Whether individual position margin can be added and/or removed. */
+  positionMarginAdjustment: PositionMarginAdjustment
   /**
    * Venue maintenance margin rate for this market as a fraction (e.g. `0.012`
    * = 1.2%). Feeds client-side liquidation-price estimates via the provider's
@@ -53,18 +71,40 @@ export interface PerpsMarket extends BaseMarket {
   maintenanceMarginRate?: number
 }
 
-/** @public */
-export interface SpotMarket extends BaseMarket {}
+/**
+ * Spot markets cannot expose perpetual-position margin capabilities.
+ * @public
+ */
+export interface SpotMarket extends BaseMarket {
+  positionMarginAdjustment?: never
+}
 
-/** @public */
+/** Union of perpetual and spot market representations. @public */
 export type Market = PerpsMarket | SpotMarket
 
-/** @public */
+/**
+ * UI-safe market projection containing identity, category, assets, and
+ * delisting state without provider-specific trading constraints.
+ *
+ * @public
+ */
 export type MarketDisplay = Pick<
   BaseMarket,
   'providerId' | 'id' | 'categoryId' | 'baseAsset' | 'quoteAsset' | 'isDelisted'
 >
 
+/** Perpetual-market identity embedded on an open {@link Position}. @public */
+export type PerpsMarketDisplay = Pick<
+  PerpsMarket,
+  | 'providerId'
+  | 'id'
+  | 'categoryId'
+  | 'baseAsset'
+  | 'quoteAsset'
+  | 'isDelisted'
+  | 'positionMarginAdjustment'
+>
+
 /**
  * Minimal market reference for write-action params: identifies a market by
  * its opaque `marketId` within a `categoryId`. Embeds no Assets — write
@@ -76,7 +116,7 @@ export interface MarketRef {
   categoryId: string
 }
 
-/** @public */
+/** Response containing all markets returned for a provider. @public */
 export interface MarketsResponse {
   markets: Market[]
 }
@@ -91,8 +131,11 @@ export interface MarketsResponse {
  * @public
  */
 export interface MarketContext {
+  /** Opaque provider market identifier for this context frame. */
   marketId: string
+  /** Current order-book midpoint, as a decimal quote string. */
   midPrice: string
+  /** Provider mark price, as a decimal quote string. */
   markPrice: string
   oraclePrice?: string
   prevDayPrice?: string
@@ -103,12 +146,17 @@ export interface MarketContext {
   funding?: FundingInfo
 }
 
-/** @public */
+/** Response containing live context for requested markets. @public */
 export interface PricesResponse {
   prices: MarketContext[]
 }
 
-/** @public */
+/**
+ * OHLCV candle with Unix-millisecond open time and decimal-string OHLCV
+ * values. Field names follow the compact provider response shape.
+ *
+ * @public
+ */
 export interface Candle {
   t: number
   o: string
@@ -118,7 +166,7 @@ export interface Candle {
   v: string
 }
 
-/** @public */
+/** Response containing candles for one provider market and interval. @public */
 export interface OhlcvResponse {
   provider: string
   marketId: string
@@ -126,7 +174,12 @@ export interface OhlcvResponse {
   candles: Candle[]
 }
 
-/** @public */
+/**
+ * Supported OHLCV intervals. Values are wire interval strings (`1M` is one
+ * month; lowercase `m` values are minutes).
+ *
+ * @public
+ */
 export type OhlcvInterval =
   | '1m'
   | '3m'
@@ -143,13 +196,13 @@ export type OhlcvInterval =
   | '1w'
   | '1M'
 
-/** @public */
+/** One price/size level in an order book; both values are decimal strings. @public */
 export interface OrderbookLevel {
   price: string
   size: string
 }
 
-/** @public */
+/** Snapshot of bids and asks for one market. `timestamp` is Unix milliseconds. @public */
 export interface OrderbookResponse {
   provider: string
   marketId: string
@@ -158,7 +211,7 @@ export interface OrderbookResponse {
   timestamp: number
 }
 
-/** @public */
+/** Recent trade normalized for a market; `timestamp` is Unix milliseconds. @public */
 export interface Trade {
   provider: string
   marketId: string

package/src/primitives.ts

@@ -1,5 +1,15 @@
-/** @public */
+/**
+ * Hex-prefixed EVM address string. The type validates only the `0x` prefix;
+ * checksum and byte-length validation remain runtime/provider concerns.
+ *
+ * @public
+ */
 export type Address = `0x${string}`
 
-/** @public */
+/**
+ * Hex-prefixed byte string used for hashes, signatures, salts, and other EVM
+ * wire values. The type does not constrain byte length.
+ *
+ * @public
+ */
 export type Hex = `0x${string}`

package/src/providers.ts

@@ -2,13 +2,17 @@ import type { Asset, DepositAsset } from './asset.js'
 import type { ActionType, PerpsSigner, SigningMethod } from './enums.js'
 import type { OhlcvInterval } from './market.js'
 
-/** @public */
+/** A fixed option value presented for a provider action parameter. @public */
 export interface ParamOption {
   value: string
   label: string
 }
 
-/** @public */
+/**
+ * Metadata describing one provider action parameter and its UI constraints.
+ *
+ * @public
+ */
 export interface Param {
   /** Wire key for the action params object: `{ [param.name]: value }`. */
   name: string
@@ -60,7 +64,11 @@ export interface TradeNotice {
   message: string
 }
 
-/** @public */
+/**
+ * Provider category metadata, including quote asset and optional market notice.
+ *
+ * @public
+ */
 export interface ProviderCategory {
   id: string
   logoURI?: string
@@ -69,7 +77,7 @@ export interface ProviderCategory {
   tradeNotice?: TradeNotice
 }
 
-/** @public */
+/** Provider-wide funding cadence metadata, expressed in seconds. @public */
 export interface ProviderFunding {
   /** Number of seconds represented by the provider's funding rate. */
   ratePeriodSeconds: number
@@ -77,7 +85,12 @@ export interface ProviderFunding {
   payoutCadenceSeconds: number
 }
 
-/** @public */
+/**
+ * Provider descriptor containing capabilities, actions, categories, and
+ * optional deposit/trading limits.
+ *
+ * @public
+ */
 export interface Provider {
   key: string
   name: string
@@ -142,7 +155,7 @@ export interface Provider {
   supportedIntervals: OhlcvInterval[]
 }
 
-/** @public */
+/** Response containing provider descriptors available to the client. @public */
 export interface ProvidersResponse {
   providers: Provider[]
 }

package/src/quote.ts

@@ -1,10 +1,10 @@
 import type { FeeTier } from './account.js'
 import type { FundingInfo } from './market.js'
 
-/** @public */
+/** Side of the quoted market order, using lowercase wire values. @public */
 export type QuoteSide = 'buy' | 'sell'
 
-/** @public */
+/** Trade instrument kind represented by the quote. @public */
 export type TradeType = 'perps' | 'spot'
 
 /**

package/src/subscriptions.ts

@@ -15,18 +15,18 @@ import type {
 } from './market.js'
 import type { Address } from './primitives.js'
 
-/** @public */
+/** Subscription for the provider's aggregate market-context stream. @public */
 export type MarketsContextSubscription = {
   channel: 'marketsContext'
   dex: string
 }
-/** @public */
+/** Subscription for one market's live context stream. @public */
 export type MarketContextSubscription = {
   channel: 'marketContext'
   dex: string
   marketId: string
 }
-/** @public */
+/** Subscription for streamed order-book updates for one market. @public */
 export type OrderbookSubscription = {
   channel: 'orderbook'
   dex: string
@@ -40,51 +40,55 @@ export type OrderbookSubscription = {
    */
   priceStep?: number
 }
-/** @public */
+/** Subscription for OHLCV candle updates for one market and interval. @public */
 export type CandleSubscription = {
   channel: 'candle'
   dex: string
   marketId: string
   interval: OhlcvInterval
 }
-/** @public */
+/** Subscription for recent trade updates for one market. @public */
 export type TradesSubscription = {
   channel: 'trades'
   dex: string
   marketId: string
 }
-/** @public */
+/** Subscription for order lifecycle updates for one account. @public */
 export type OrderUpdatesSubscription = {
   channel: 'orderUpdates'
   dex: string
   address: Address
 }
-/** @public */
+/** Subscription for execution/fill updates for one account. @public */
 export type FillsSubscription = {
   channel: 'fills'
   dex: string
   address: Address
 }
-/** @public */
+/** Subscription for the full open-position set for one account. @public */
 export type PositionsSubscription = {
   channel: 'positions'
   dex: string
   address: Address
 }
-/** @public */
+/** Subscription for spot-balance updates for one account. @public */
 export type SpotBalancesSubscription = {
   channel: 'spotBalances'
   dex: string
   address: Address
 }
-/** @public */
+/** Subscription for aggregate account-summary updates for one account. @public */
 export type AccountSummarySubscription = {
   channel: 'accountSummary'
   dex: string
   address: Address
 }
 
-/** @public */
+/**
+ * Union of all websocket subscription request shapes.
+ *
+ * @public
+ */
 export type Subscription =
   | MarketsContextSubscription
   | MarketContextSubscription
@@ -97,23 +101,23 @@ export type Subscription =
   | SpotBalancesSubscription
   | AccountSummarySubscription
 
-/** @public */
+/** Event containing the provider's aggregate market contexts. @public */
 export type MarketsContextEvent = {
   channel: 'marketsContext'
   data: Record<string, MarketContext>
 }
-/** @public */
+/** Event containing one market's live context. @public */
 export type MarketContextEvent = {
   channel: 'marketContext'
   data: MarketContext
 }
-/** @public */
+/** Event containing an order-book snapshot or update. @public */
 export type OrderbookEvent = { channel: 'orderbook'; data: OrderbookResponse }
-/** @public */
+/** Event containing one OHLCV candle. @public */
 export type CandleEvent = { channel: 'candle'; data: Candle }
-/** @public */
+/** Event containing recent trades. @public */
 export type TradesEvent = { channel: 'trades'; data: Trade[] }
-/** @public */
+/** Event containing order upserts and terminal order ids. @public */
 export type OrderUpdatesEvent = {
   channel: 'orderUpdates'
   data: {
@@ -128,7 +132,7 @@ export type OrderUpdatesEvent = {
     terminated: string[]
   }
 }
-/** @public */
+/** Event containing newly observed executions/fills. @public */
 export type FillsEvent = { channel: 'fills'; data: Fill[] }
 /**
  * Positions stream frame. `data` is always the full set of currently open
@@ -159,7 +163,11 @@ export type AccountSummaryEvent = {
   data: AccountSummary
 }
 
-/** @public */
+/**
+ * Union of all websocket event frame shapes emitted for subscriptions.
+ *
+ * @public
+ */
 export type SubscriptionEvent =
   | MarketsContextEvent
   | MarketContextEvent

package/src/typedData.ts

@@ -1,6 +1,11 @@
 import type { Address, Hex } from './primitives.js'
 
-/** @public */
+/**
+ * EIP-712 domain fields used to identify a signing domain. `chainId` is the
+ * numeric EVM chain id when present.
+ *
+ * @public
+ */
 export interface TypedDataDomain {
   name?: string
   version?: string
@@ -9,16 +14,21 @@ export interface TypedDataDomain {
   salt?: Hex
 }
 
-/** @public */
+/** One named field in an EIP-712 primary type definition. @public */
 export interface TypedDataParameter {
   name: string
   type: string
 }
 
-/** @public */
+/** Primary-type name used by a perps EIP-712 payload. @public */
 export type PerpsPrimaryType = string
 
-/** @public */
+/**
+ * Provider-neutral EIP-712 payload passed between backend and SDK. `message`
+ * intentionally remains open because each action defines its own fields.
+ *
+ * @public
+ */
 export type PerpsTypedData = {
   domain: TypedDataDomain
   types: Record<string, readonly TypedDataParameter[]>
@@ -26,7 +36,7 @@ export type PerpsTypedData = {
   message: Record<string, any>
 }
 
-/** @public */
+/** EIP-712 payload accompanied by its client-produced signature. @public */
 export type PerpsSignedTypedData = PerpsTypedData & {
   signature: Hex
 }

package/src/vote.ts

@@ -9,7 +9,7 @@ import type { PerpsTypedData, TypedDataParameter } from './typedData.js'
  */
 export const META_PROVIDER = 'meta'
 
-/** @public */
+/** Type alias for the {@link META_PROVIDER} provider-independent sentinel. @public */
 export type MetaProvider = typeof META_PROVIDER
 
 /**
@@ -34,7 +34,6 @@ export type VoteType = 'provider'
  * @public
  */
 export interface VoteParams {
-  /** Key of the inactive provider being voted on (the voted-on subject). */
   targetProvider: string
   direction: VoteDirection
   voteType: VoteType
@@ -45,7 +44,6 @@ export interface VoteParams {
  * @public
  */
 export interface VoteMessage {
-  /** Key of the inactive provider being voted on. */
   targetProvider: string
   direction: VoteDirection
   voteType: VoteType