@lifi/perps-sdk-provider-lighter 21.0.0 → 22.0.0

package/src/LighterProvider.ts

@@ -4,6 +4,7 @@ import {
   getAssetRegistry,
   getMarketRegistry,
   getProviders,
+  isActiveOrderStatus,
   localStorageAdapter,
   PerpsError,
   type PerpsProviderPlugin,
@@ -66,6 +67,7 @@ import {
   DEFAULT_TRADES_LIMIT,
   LIGHTER_ALL_MARKETS_WILDCARD,
   LIGHTER_BASE_FEE_TIER,
+  LIGHTER_CLIENT_ORDER_INDEX_ID_PREFIX,
   LIGHTER_FEE_TICK_SCALE,
   LIGHTER_HISTORY_PAGE_SIZE,
   LIGHTER_MAINNET_DEPLOYMENT,
@@ -88,6 +90,7 @@ import {
 import type {
   LtAccount,
   LtAccountLimits,
+  LtAccountOrdersResponse,
   LtDepositHistoryItem,
   LtDepositHistoryResponse,
   LtDetailedAccountPosition,
@@ -165,6 +168,13 @@ const orderCountFor = (p: LtDetailedAccountPosition): number =>
  */
 const TX_HASH_PATTERN = /^[0-9a-f]{80}$/
 
+/**
+ * Lighter's `client_order_index` is an int64 and `accountOrders` takes it as a
+ * decimal string, so a prefixed id's suffix goes to the venue verbatim rather
+ * than through a lossy JS number.
+ */
+const CLIENT_ORDER_INDEX_PATTERN = /^\d+$/
+
 const INACTIVE_ORDERS_LOOKUP_LIMIT = 100
 
 /** Activity surfaces whose rows name a market, so they need the market registry. */
@@ -567,7 +577,7 @@ export const createLighterProvider = (
       account_index: accountIndex,
     })
 
-  const fetchActiveOrdersForMarket = async (
+  const fetchActiveOrders = async (
     client: LighterApiClient,
     authToken: string,
     accountIndex: number,
@@ -581,6 +591,20 @@ export const createLighterProvider = (
     return { ...response, orders: wireList(response.orders) }
   }
 
+  const fetchOrdersByClientOrderIndex = async (
+    client: LighterApiClient,
+    authToken: string,
+    accountIndex: number,
+    clientOrderIndex: string
+  ): Promise<LtOrder[]> => {
+    const response = await client.getAuthed<LtAccountOrdersResponse>(
+      '/api/v1/accountOrders',
+      authToken,
+      { account_index: accountIndex, client_order_indexes: clientOrderIndex }
+    )
+    return wireList(response.orders)
+  }
+
   const deriveOrderBearingMarketIds = (account: LtAccount): number[] =>
     account.positions
       .filter((p) => orderCountFor(p) > 0)
@@ -1017,21 +1041,17 @@ export const createLighterProvider = (
         registry.sync(),
       ])
 
-      const marketIds =
+      const marketId =
         params.marketId === undefined
-          ? deriveOrderBearingMarketIds(account)
-          : [Number(registry.require(params.marketId).id)]
+          ? LIGHTER_ALL_MARKETS_WILDCARD
+          : Number(registry.require(params.marketId).id)
 
-      const responses = await retryOnRevoked(opts, params.address, token, (t) =>
-        Promise.all(
-          marketIds.map((id) =>
-            fetchActiveOrdersForMarket(client, t, account.index, id)
-          )
-        )
+      const response = await retryOnRevoked(opts, params.address, token, (t) =>
+        fetchActiveOrders(client, t, account.index, marketId)
       )
 
       const { openOrders, triggerOrders } = classifyAndMapOrders(
-        responses.flatMap((r) => r.orders),
+        response.orders,
         (marketIndex) => registry.require(String(marketIndex))
       )
 
@@ -1065,9 +1085,7 @@ export const createLighterProvider = (
           : [Number(registry.require(params.marketId).id)]
       const responses = await retryOnRevoked(opts, params.address, token, (t) =>
         Promise.all(
-          marketIds.map((id) =>
-            fetchActiveOrdersForMarket(client, t, account.index, id)
-          )
+          marketIds.map((id) => fetchActiveOrders(client, t, account.index, id))
         )
       )
 
@@ -1087,6 +1105,14 @@ export const createLighterProvider = (
       return twaps
     },
 
+    /**
+     * Resolves either reference Lighter hands out for an order: a bare
+     * `order_index` — the value `Order.orderId` carries, as streamed by
+     * `orderUpdates` / `fills` — or a `client_order_index` prefixed with
+     * {@link LIGHTER_CLIENT_ORDER_INDEX_ID_PREFIX}, which a signed placement
+     * step returns and which resolves before the venue has assigned an
+     * `order_index`.
+     */
     async getOrder(
       params: ProviderGetOrderParams,
       opts?: SDKRequestOptions
@@ -1108,41 +1134,75 @@ export const createLighterProvider = (
         registry.sync(),
       ])
 
-      // Native `order_index` route only. The cross-provider `Order.orderId`
-      // for Lighter is `String(order_index)` — see `mapOrder`. A tx-hash route
-      // would require mapping the caller's executeAction tx hash → wasm nonce
-      // → matching order, which the LI.FI backend did via its `UserAction`
-      // table; the SDK has no equivalent persistence, so we refuse rather
-      // than mis-resolve.
+      const notFound = (): PerpsError =>
+        new PerpsError(
+          PerpsErrorCode.OrderNotFound,
+          `Lighter order ${params.id} not found for ${params.address}`
+        )
+      const detail = (order: LtOrder): Order =>
+        mapOrderDetail(order, registry.require(String(order.market_index)))
+
+      // A tx-hash route would require mapping the caller's executeAction tx
+      // hash → wasm nonce → matching order, which the LI.FI backend did via
+      // its `UserAction` table; the SDK has no equivalent persistence, so we
+      // refuse rather than mis-resolve.
       if (TX_HASH_PATTERN.test(params.id)) {
         throw new PerpsError(
           PerpsErrorCode.OrderNotFound,
           `Lighter order id "${params.id}" looks like a tx hash. The SDK ` +
-            `resolves orders by Lighter \`order_index\` only — surface the orderId ` +
-            `from the orderUpdates / fills WS stream and pass it here.`
+            `resolves orders by Lighter \`order_index\` or by a ` +
+            `\`${LIGHTER_CLIENT_ORDER_INDEX_ID_PREFIX}<index>\` id — surface the ` +
+            `orderId from the orderUpdates / fills WS stream, or the ` +
+            `clientOrderIndex from the signed placement step, and pass it here.`
         )
       }
-      const predicate: (o: { order_index: number }) => boolean = (o) =>
-        String(o.order_index) === params.id
 
-      const marketIds = deriveOrderBearingMarketIds(account)
-      const activeResponses = await retryOnRevoked(
-        opts,
-        params.address,
-        token,
-        (t) =>
-          Promise.all(
-            marketIds.map((id) =>
-              fetchActiveOrdersForMarket(client, t, account.index, id)
-            )
+      if (params.id.startsWith(LIGHTER_CLIENT_ORDER_INDEX_ID_PREFIX)) {
+        const clientOrderIndex = params.id.slice(
+          LIGHTER_CLIENT_ORDER_INDEX_ID_PREFIX.length
+        )
+        if (!CLIENT_ORDER_INDEX_PATTERN.test(clientOrderIndex)) {
+          throw new PerpsError(
+            PerpsErrorCode.SDKError,
+            `Lighter order id "${params.id}" names a client order index, but ` +
+              `"${clientOrderIndex}" is not a decimal integer.`
           )
-      )
-
-      for (const response of activeResponses) {
-        const hit = response.orders.find(predicate as (o: unknown) => boolean)
-        if (hit !== undefined) {
-          return mapOrderDetail(hit, registry.require(String(hit.market_index)))
         }
+        const orders = await retryOnRevoked(opts, params.address, token, (t) =>
+          fetchOrdersByClientOrderIndex(
+            client,
+            t,
+            account.index,
+            clientOrderIndex
+          )
+        )
+        // `accountOrders` reaches active and inactive rows alike, so a reused
+        // client order index can match more than one row. Prefer the live one.
+        const matches = orders
+          .filter((o) => String(o.client_order_index) === clientOrderIndex)
+          .map(detail)
+        const hit =
+          matches.find((o) => isActiveOrderStatus(o.status)) ?? matches[0]
+        if (hit === undefined) {
+          throw notFound()
+        }
+        return hit
+      }
+
+      const byOrderIndex = (o: LtOrder): boolean =>
+        String(o.order_index) === params.id
+
+      const active = await retryOnRevoked(opts, params.address, token, (t) =>
+        fetchActiveOrders(
+          client,
+          t,
+          account.index,
+          LIGHTER_ALL_MARKETS_WILDCARD
+        )
+      )
+      const activeHit = active.orders.find(byOrderIndex)
+      if (activeHit !== undefined) {
+        return detail(activeHit)
       }
 
       const inactive = await retryOnRevoked(opts, params.address, token, (t) =>
@@ -1152,17 +1212,11 @@ export const createLighterProvider = (
           limit: INACTIVE_ORDERS_LOOKUP_LIMIT,
         })
       )
-      const hit = wireList(inactive.orders).find(
-        predicate as (o: unknown) => boolean
-      )
-      if (hit !== undefined) {
-        return mapOrderDetail(hit, registry.require(String(hit.market_index)))
+      const inactiveHit = wireList(inactive.orders).find(byOrderIndex)
+      if (inactiveHit === undefined) {
+        throw notFound()
       }
-
-      throw new PerpsError(
-        PerpsErrorCode.OrderNotFound,
-        `Lighter order ${params.id} not found for ${params.address}`
-      )
+      return detail(inactiveHit)
     },
 
     async getFills(

package/src/constants.ts

@@ -204,13 +204,26 @@ export const LIGHTER_BASE_FEE_TIER: FeeTier = { maker: '0', taker: '0' }
 
 /**
  * Wildcard `market_id` accepted by Lighter's per-market account endpoints to
- * indicate "every market". Used on `accountInactiveOrders` and
- * `liquidations`.
+ * indicate "every market". Used on `accountActiveOrders`,
+ * `accountInactiveOrders` and `liquidations`. It is also the venue's own
+ * documented default for `accountActiveOrders.market_id`.
  *
  * @internal
  */
 export const LIGHTER_ALL_MARKETS_WILDCARD = 255
 
+/**
+ * Prefix that marks a `getOrder` id as a Lighter `client_order_index` rather
+ * than an `order_index`. Compose the id as
+ * `` `${LIGHTER_CLIENT_ORDER_INDEX_ID_PREFIX}${clientOrderIndex}` `` from the
+ * `clientOrderIndex` a signed placement step returns. Both references are
+ * decimal integers, so without the prefix `getOrder` could resolve one as the
+ * other and return an unrelated order.
+ *
+ * @public
+ */
+export const LIGHTER_CLIENT_ORDER_INDEX_ID_PREFIX = 'client_order_index:'
+
 /**
  * Lighter caps `limit` at 100 on positionFunding/liquidations endpoints.
  *

package/src/index.ts

@@ -23,6 +23,7 @@ export {
   DEFAULT_LIGHTER_EXPLORER_TX_BASE_URL,
   DEFAULT_LIGHTER_REST_URL,
   DEFAULT_LIGHTER_WS_URL,
+  LIGHTER_CLIENT_ORDER_INDEX_ID_PREFIX,
   LIGHTER_COLLATERAL_ASSETS,
   LIGHTER_MAINNET_DEPLOYMENT,
   LIGHTER_MAINNET_SIGNER_CHAIN_ID,

package/src/signers/signActions.ts

@@ -230,13 +230,30 @@ async function signStandardWasmAction(
     apiKeyIndex: apiKey.apiKeyIndex,
     accountIndex: apiKey.accountIndex,
   })
+  const clientOrderIndex = clientOrderIndexOf(step.wasmSignParams)
   return {
     action: step.action,
     wasmSignParams: step.wasmSignParams,
     signedTx,
+    ...(clientOrderIndex === undefined ? {} : { clientOrderIndex }),
   }
 }
 
+/**
+ * Project the signed order's `client_order_index` so the caller can resolve it
+ * through `getOrder` before the venue assigns an `order_index`. Only the
+ * order-placing actions carry one, and the value is read back off the params
+ * that were signed rather than generated a second time.
+ */
+function clientOrderIndexOf(
+  wasmSignParams: Record<string, unknown>
+): string | undefined {
+  const value = wasmSignParams.client_order_index
+  return typeof value === 'number' && Number.isInteger(value)
+    ? String(value)
+    : undefined
+}
+
 /**
  * REGISTER_API_KEY flow:
  *   1. Look up the user's Lighter accountIndex (Lighter REST).
@@ -484,11 +501,11 @@ async function executeTokenAuthMutation(
     }
   }
 
-  const { path, params } = buildTokenAuthMutationRequest(step, authToken)
+  const { path, params } = buildTokenAuthMutationRequest(step)
   const { status, data } = await deps.apiClient.postForm<{
     code?: number
     message?: string
-  }>(path, params)
+  }>(path, authToken, params)
 
   const code = data?.code
   const referralAlreadyApplied =
@@ -533,14 +550,14 @@ async function readAppliedReferralCode(
 }
 
 /**
- * Map a token-authenticated mutation step to its Lighter endpoint and
- * form body, mirroring the backend's request contract. The auth token is the
- * `auth` field; the remaining fields come from `wasmSignParams`.
+ * Map a token-authenticated mutation step to its Lighter endpoint and form
+ * body. The fields come from `wasmSignParams`; the auth token travels in the
+ * `Authorization` header, not the body.
  */
-function buildTokenAuthMutationRequest(
-  step: WasmBlobActionStep,
-  authToken: string
-): { path: string; params: ApiParams } {
+function buildTokenAuthMutationRequest(step: WasmBlobActionStep): {
+  path: string
+  params: ApiParams
+} {
   const kind = step.wasmSignParams.kind
   if (kind === 'changeAccountTier') {
     const { account_index, new_tier } = step.wasmSignParams as {
@@ -555,7 +572,7 @@ function buildTokenAuthMutationRequest(
     }
     return {
       path: '/api/v1/changeAccountTier',
-      params: { auth: authToken, account_index, new_tier },
+      params: { account_index, new_tier },
     }
   }
   if (kind === 'referralUse') {
@@ -572,7 +589,7 @@ function buildTokenAuthMutationRequest(
     }
     return {
       path: '/api/v1/referral/use',
-      params: { auth: authToken, l1_address, referral_code, x },
+      params: { l1_address, referral_code, x },
     }
   }
   throw new PerpsError(

package/src/types/order.ts

@@ -69,6 +69,19 @@ export interface LtOrdersResponse {
   orders: LtOrder[] | null
 }
 
+/**
+ * Order-lookup response from Lighter's `accountOrders` path. The lookup takes
+ * up to 20 `client_order_indexes` rather than a page, so it carries no cursor.
+ * It reaches the last 10K active orders with no time bound, and the last 1K
+ * inactive orders from the past 24 hours.
+ *
+ * @public
+ */
+export interface LtAccountOrdersResponse {
+  code: number
+  orders: LtOrder[] | null
+}
+
 /**
  * Single order-book level returned by Lighter. Amounts and prices are decimal
  * strings in the market's native precision; `order_expiry` is an absolute

package/src/utils/apiClient.ts

@@ -9,6 +9,7 @@ import {
   LIGHTER_SUCCESS_CODES,
   LIGHTER_TOKEN_REVOKED_CODE,
 } from '../constants.js'
+import { lighterErrorCodeFromBody } from './lighterErrorCode.js'
 
 /** @internal */
 export type ApiParams = Record<string, string | number | boolean>
@@ -50,9 +51,17 @@ const isLighterTokenRevoked = (data: unknown): boolean =>
 
 /**
  * A CR or LF in a token would split the request when it reaches a
- * `fetchImpl` that does not validate header values itself.
+ * `fetchImpl` that does not validate header values itself. A blank token
+ * would dispatch an `Authorization` header that carries no credential at
+ * all, which Lighter answers as a generic rejection.
  */
 const assertHeaderSafe = (authToken: string): string => {
+  if (authToken.trim().length === 0) {
+    throw new PerpsError(
+      PerpsErrorCode.ValidationError,
+      'Lighter auth token is blank and cannot go in a header'
+    )
+  }
   if (/[\r\n]/.test(authToken)) {
     throw new PerpsError(
       PerpsErrorCode.ValidationError,
@@ -136,6 +145,11 @@ export interface LighterApiClientOptions {
  * `Access-Control-Max-Age: 86400`, so a browser sends one preflight per day
  * per origin.
  *
+ * The `/api/v1/changeAccountTier` and `/api/v1/referral/use` mutations send
+ * the same header with a fresh per-call token. Their `OPTIONS` response is
+ * not yet probed against a live host, so a browser may reject the preflight
+ * even though the GET paths pass.
+ *
  * Lighter signals rate limits through HTTP 429 or HTTP 405. This client never
  * retries such a response. It throws `RateLimitExceeded` and holds all network
  * dispatch until `Retry-After` expires (capped at five minutes), or for 60
@@ -226,13 +240,13 @@ export class LighterApiClient {
     })
     if (isLighterTokenRevoked(data)) {
       throw new LighterTokenRevokedError(
-        PerpsErrorCode.ThirdPartyError,
+        PerpsErrorCode.Unauthorized,
         `Lighter reports a revoked auth token for ${path}`
       )
     }
     if (isLighterAuthRejection(status, data)) {
       throw new LighterAuthRejectedError(
-        PerpsErrorCode.ThirdPartyError,
+        PerpsErrorCode.Unauthorized,
         `Lighter rejected the auth token for ${path}`
       )
     }
@@ -274,13 +288,15 @@ export class LighterApiClient {
   }
 
   /**
-   * Form-encoded POST to a Lighter mutation endpoint. Single-shot — never
-   * retried, since these are money/state writes whose outcome is unknown on a
-   * transport failure. Surfaces the raw `{status, body}` pair so the caller can
-   * map Lighter's per-endpoint business-rule `code` to a domain error verbatim.
+   * Form-encoded POST to a Lighter mutation endpoint, carrying the Lighter
+   * token in the `Authorization` header. Single-shot — never retried, since
+   * these are money/state writes whose outcome is unknown on a transport
+   * failure. Surfaces the raw `{status, body}` pair so the caller can map
+   * Lighter's per-endpoint business-rule `code` to a domain error verbatim.
    */
   async postForm<T>(
     path: string,
+    authToken: string,
     params: ApiParams
   ): Promise<{ status: number; data: T }> {
     const body = new URLSearchParams()
@@ -289,7 +305,10 @@ export class LighterApiClient {
     }
     const response = await this.fetchWithHold(`${this.baseUrl}${path}`, {
       method: 'POST',
-      headers: { 'content-type': 'application/x-www-form-urlencoded' },
+      headers: {
+        'content-type': 'application/x-www-form-urlencoded',
+        Authorization: assertHeaderSafe(authToken),
+      },
       body: body.toString(),
       signal: this.signal,
     })
@@ -306,20 +325,24 @@ export class LighterApiClient {
 
   /**
    * Post-parse validation shared by every checked read: rejects a non-2xx HTTP
-   * status and a 200 body carrying a non-success `code`. Callers that surface a
-   * distinct auth-rejection error must run that check before this one.
+   * status and a 200 body carrying a non-success `code`. A body `code` that
+   * names a nonce, margin, or balance rejection sets the matching
+   * `PerpsErrorCode`; every other rejection is `ThirdPartyError`. Callers that
+   * surface a distinct auth-rejection error must run that check before this one.
    */
   private assertOk(path: string, status: number, data: unknown): void {
+    const errorCode = lighterBodyErrorCode(data)
+    const code =
+      lighterErrorCodeFromBody(errorCode) ?? PerpsErrorCode.ThirdPartyError
     if (status < 200 || status >= 300) {
       throw new PerpsError(
-        PerpsErrorCode.ThirdPartyError,
+        code,
         `Lighter API request failed: ${status} — ${JSON.stringify(data).slice(0, 200)}`
       )
     }
-    const errorCode = lighterBodyErrorCode(data)
     if (errorCode !== undefined) {
       throw new PerpsError(
-        PerpsErrorCode.ThirdPartyError,
+        code,
         `Lighter API error for ${path}: code ${errorCode} — ${JSON.stringify(data).slice(0, 200)}`
       )
     }

package/src/utils/lighterErrorCode.ts

@@ -0,0 +1,30 @@
+import { PerpsErrorCode } from '@lifi/perps-types'
+
+/** Lighter body `code` values that name a rejection a `PerpsErrorCode` describes. */
+const LIGHTER_BODY_ERROR_CODES: ReadonlyMap<number, PerpsErrorCode> = new Map([
+  // invalid nonce
+  [21104, PerpsErrorCode.InvalidNonce],
+  // batch transaction nonce is not increasing
+  [21105, PerpsErrorCode.InvalidNonce],
+  // not enough collateral
+  [21301, PerpsErrorCode.InsufficientBalance],
+  // not enough asset balance
+  [21304, PerpsErrorCode.InsufficientBalance],
+  // not enough asset balance for fee
+  [21305, PerpsErrorCode.InsufficientBalance],
+  // account is below maintenance margin
+  [21507, PerpsErrorCode.InsufficientMargin],
+  // account is below initial margin
+  [21508, PerpsErrorCode.InsufficientMargin],
+  // not enough margin to create the order
+  [21739, PerpsErrorCode.InsufficientMargin],
+])
+
+/**
+ * Maps a Lighter body error `code` to the `PerpsErrorCode` it names. Returns
+ * `undefined` for every other code so the status-driven layer decides.
+ */
+export const lighterErrorCodeFromBody = (
+  code: number | undefined
+): PerpsErrorCode | undefined =>
+  code === undefined ? undefined : LIGHTER_BODY_ERROR_CODES.get(code)