@lifi/perps-sdk-provider-lighter 16.0.0 → 17.0.0

package/src/types/fill.ts

@@ -3,8 +3,13 @@
 /**
  * Public trade/fill row returned by Lighter's `/api/v1/trades` endpoint.
  * Size, price, and notional fields are decimal strings in market precision;
- * `timestamp` and `transaction_time` are Unix millisecond timestamps. The
- * optional fee fields are integer fee ticks and may be absent on older rows.
+ * `timestamp` is a Unix millisecond timestamp; `transaction_time` is a Unix
+ * microsecond timestamp. The optional fee fields are the side's fee *rate* as
+ * an integer tick on `LIGHTER_FEE_TICK_SCALE` (1e6), not the amount charged,
+ * and may be absent on older rows. A row can also carry
+ * `integrator_maker_fee` or `integrator_taker_fee`: a second optional rate for
+ * the same side, on the same 1e6 tick scale. The mapper adds that second rate
+ * to the side's own rate.
  *
  * @public
  */
@@ -28,6 +33,10 @@ export type LtTrade = {
   // on older trades) — keep optional and let the mapper emit `undefined`.
   taker_fee?: number
   maker_fee?: number
+  // A second fee tick that a row can carry for the same side, on the same 1e6
+  // tick scale as `taker_fee` / `maker_fee`.
+  integrator_taker_fee?: number
+  integrator_maker_fee?: number
   transaction_time: number
   // Per-counterparty position snapshot BEFORE the trade is applied. Signed
   // strings: positive = long, negative = short, "0" / "0.00000" = flat.

package/src/types/order.ts

@@ -3,9 +3,10 @@
 /**
  * Order payload returned by Lighter's REST API. Amounts and prices are decimal
  * strings in market precision. `order_expiry` is an absolute Unix-millisecond
- * expiry; `created_at`, `updated_at`, and `transaction_time` are Unix seconds.
- * Enum-like side, type, time-in-force, status, and trigger fields retain
- * Lighter's wire strings.
+ * expiry; `created_at` and `updated_at` are Unix seconds. `timestamp` and
+ * `transaction_time` carry their unit on the member; `trigger_time` has no
+ * documented unit. Enum-like side, type, time-in-force, status, and trigger
+ * fields retain Lighter's wire strings.
  *
  * @public
  */
@@ -38,9 +39,18 @@ export type LtOrder = {
   to_trigger_order_id_1: string
   to_cancel_order_id_0: string
   block_height: number
+  /**
+   * Unit unproven. Lighter documents no unit, and every endpoint that returns
+   * this row is auth-gated, so no public probe can observe a value.
+   */
   timestamp: number
   created_at: number
   updated_at: number
+  /**
+   * Unix timestamp in microseconds. Lighter documents no unit, and its public
+   * trade rows report this member in microseconds while the sibling
+   * `created_at` and `updated_at` stay in seconds.
+   */
   transaction_time: number
 }
 
@@ -58,8 +68,8 @@ export interface LtOrdersResponse {
 
 /**
  * Single order-book level returned by Lighter. Amounts and prices are decimal
- * strings in the market's native precision; expiry and transaction time are
- * Unix milliseconds.
+ * strings in the market's native precision; `order_expiry` is an absolute
+ * Unix-millisecond expiry.
  *
  * @public
  */
@@ -71,6 +81,10 @@ export interface LtOrderBookOrder {
   remaining_base_amount: string
   price: string
   order_expiry: number
+  /**
+   * Unit unproven. Lighter documents no unit, and every resting order this
+   * endpoint returns reports the member as zero.
+   */
   transaction_time: number
 }
 

package/src/utils/mapFill.ts

@@ -11,8 +11,30 @@ import {
   OrderType,
 } from '@lifi/perps-types'
 import Big from 'big.js'
+import { LIGHTER_FEE_TICK_SCALE } from '../constants.js'
 import type { LtTrade } from '../types/index.js'
 
+/**
+ * Fee charged on a fill, in the market's quote asset. Lighter publishes the
+ * side's fee *rate* as an integer tick on `LIGHTER_FEE_TICK_SCALE` rather than
+ * the amount it charged. A row can carry more than one tick for the same side,
+ * so `amount = notional * sum(side ticks) / LIGHTER_FEE_TICK_SCALE`.
+ *
+ * The product keeps the sign of both inputs. A rebate tick therefore maps to a
+ * negative amount, which `Fee.amount` permits and the Ondo mapper already emits
+ * when a rebate exceeds the fee, so this helper never clamps the sign. A zero
+ * notional charges a zero fee at every tick.
+ */
+const tickToFeeAmount = (
+  notional: string,
+  ownTick: number,
+  integratorTick: number | undefined
+): string =>
+  new Big(notional)
+    .times(new Big(ownTick).plus(integratorTick ?? 0))
+    .div(LIGHTER_FEE_TICK_SCALE)
+    .toFixed()
+
 /**
  * Realized PnL on a position-reducing fill, derived from the pre-trade entry
  * basis. Returns `undefined` for opens/increases (nothing closes) or when the
@@ -75,9 +97,10 @@ export const mapFill = (
   const entryQuoteBefore = isMaker
     ? trade.maker_entry_quote_before
     : trade.taker_entry_quote_before
-  const feeAmount = isMaker
-    ? trade.maker_fee?.toString()
-    : trade.taker_fee?.toString()
+  const feeTick = isMaker ? trade.maker_fee : trade.taker_fee
+  const integratorFeeTick = isMaker
+    ? trade.integrator_maker_fee
+    : trade.integrator_taker_fee
 
   return {
     id: trade.trade_id.toString(),
@@ -91,9 +114,16 @@ export const mapFill = (
     liquidity: isMaker ? LiquidityRole.MAKER : LiquidityRole.TAKER,
     // Lighter charges the fill fee in the market's quote asset.
     fee:
-      feeAmount === undefined
+      feeTick === undefined
         ? undefined
-        : { amount: feeAmount, asset: market.quoteAsset.displaySymbol },
+        : {
+            amount: tickToFeeAmount(
+              trade.usd_amount,
+              feeTick,
+              integratorFeeTick
+            ),
+            asset: market.quoteAsset.displaySymbol,
+          },
     realizedPnl: deriveRealizedPnl(
       startPosition,
       entryQuoteBefore,