@lifi/perps-sdk-provider-lighter 21.0.0 → 22.1.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,
@@ -103,7 +106,11 @@ import type {
   LtWithdrawHistoryItem,
   LtWithdrawHistoryResponse,
 } from './types/index.js'
-import { LT_MARGIN_MODE_CROSS, LT_MARGIN_MODE_ISOLATED } from './types/index.js'
+import {
+  LT_ACCOUNT_TRADING_MODE_SIMPLE,
+  LT_MARGIN_MODE_CROSS,
+  LT_MARGIN_MODE_ISOLATED,
+} from './types/index.js'
 import {
   decodeActivityCursor,
   encodeActivityCursor,
@@ -165,6 +172,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. */
@@ -255,6 +269,12 @@ interface CachedStandardToken {
   token: string
   /** Unix seconds — re-create when `Date.now()/1000 + renewBuffer >= expiresAt`. */
   expiresAt: number
+  /**
+   * Slot and key material that signed `token`, as
+   * `apiKeyIndex:accountIndex:apiKeyPrivateKey`. `REGISTER_API_KEY` rotates the
+   * stored key, and Lighter rejects a token the superseded key signed.
+   */
+  signingKey: string
 }
 
 /**
@@ -359,10 +379,12 @@ export const createLighterProvider = (
     indices: { apiKeyIndex: number; accountIndex: number }
   ): Promise<string> => {
     const cacheKey = address.toLowerCase()
+    const signingKey = `${indices.apiKeyIndex}:${indices.accountIndex}:${apiKeyPrivateKey}`
     const nowSec = Math.floor(Date.now() / 1000)
     const cached = standardTokenByAddress.get(cacheKey)
     if (
       cached !== undefined &&
+      cached.signingKey === signingKey &&
       cached.expiresAt - nowSec > tokenRenewBufferSeconds
     ) {
       return cached.token
@@ -377,7 +399,7 @@ export const createLighterProvider = (
       lifetimeSeconds: tokenLifetimeSeconds,
     })
     const expiresAt = nowSec + tokenLifetimeSeconds
-    standardTokenByAddress.set(cacheKey, { token, expiresAt })
+    standardTokenByAddress.set(cacheKey, { token, expiresAt, signingKey })
     return token
   }
 
@@ -415,11 +437,17 @@ export const createLighterProvider = (
       return undefined
     }
 
-    const standardToken = (): Promise<string> =>
-      getStandardAuthToken(address, apiKey.apiKeyPrivateKey, {
-        apiKeyIndex: apiKey.apiKeyIndex,
-        accountIndex: apiKey.accountIndex,
+    // Sign with the key registered at call time, not the one read on entry:
+    // `REGISTER_API_KEY` can rotate the store while an await below is pending,
+    // and Lighter rejects a token the superseded key signed. The entry value
+    // stands in only when the record is gone, which no key can re-sign.
+    const standardToken = async (): Promise<string> => {
+      const current = (await keyStore.get(address)) ?? apiKey
+      return getStandardAuthToken(address, current.apiKeyPrivateKey, {
+        apiKeyIndex: current.apiKeyIndex,
+        accountIndex: current.accountIndex,
       })
+    }
 
     const stored = await readOnlyTokenManager.get(address, apiKey.accountIndex)
     if (stored !== undefined) {
@@ -567,7 +595,7 @@ export const createLighterProvider = (
       account_index: accountIndex,
     })
 
-  const fetchActiveOrdersForMarket = async (
+  const fetchActiveOrders = async (
     client: LighterApiClient,
     authToken: string,
     accountIndex: number,
@@ -581,6 +609,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)
@@ -863,7 +905,8 @@ export const createLighterProvider = (
         apiKeyRegistered,
         accountType: account.account_type,
         userTierName: limitsResult?.user_tier_name,
-        accountTradingMode: account.account_trading_mode,
+        accountTradingMode:
+          account.account_trading_mode ?? LT_ACCOUNT_TRADING_MODE_SIMPLE,
         assetCollateral,
         // Satisfied when a non-expired read-only token is stored locally
         // (`readOnlyTokenManager.get` filters out expired ones).
@@ -1017,21 +1060,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 +1104,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 +1124,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 +1153,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 +1231,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/accountConfig.ts

@@ -5,6 +5,10 @@ import type {
   ProviderAction,
 } from '@lifi/perps-types'
 import { ActionType, PerpsErrorCode } from '@lifi/perps-types'
+import {
+  LT_ACCOUNT_TRADING_MODE_SIMPLE,
+  LT_ACCOUNT_TRADING_MODE_UNIFIED,
+} from './types/action.js'
 
 function assertNever(value: never): never {
   throw new Error(
@@ -27,15 +31,11 @@ const ACCOUNT_TYPE_INT_TO_WIRE: Readonly<Record<number, string>> = {
   [LIGHTER_ACCOUNT_TYPE_PREMIUM]: 'premium',
 }
 
-// `account_trading_mode` on `DetailedAccount`: 0 = Classic/Simple (segregated
-// margin), 1 = Unified Trading Account (cross-asset margin). Wire strings match
-// the backend descriptor's ParamOption values. An unmapped int projects to null.
-const LIGHTER_ACCOUNT_MODE_SIMPLE = 0
-const LIGHTER_ACCOUNT_MODE_UNIFIED = 1
-
+// Wire strings match the backend descriptor's ParamOption values. An unmapped
+// int projects to null.
 const ACCOUNT_MODE_INT_TO_WIRE: Readonly<Record<number, string>> = {
-  [LIGHTER_ACCOUNT_MODE_SIMPLE]: 'simpleTradingAccount',
-  [LIGHTER_ACCOUNT_MODE_UNIFIED]: 'unifiedTradingAccount',
+  [LT_ACCOUNT_TRADING_MODE_SIMPLE]: 'simpleTradingAccount',
+  [LT_ACCOUNT_TRADING_MODE_UNIFIED]: 'unifiedTradingAccount',
 }
 
 /**

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.
  *
@@ -235,6 +248,16 @@ const LIGHTER_INVALID_AUTH_CODE = 20013
  */
 const LIGHTER_TOKEN_REVOKED_CODE = 61006
 
+/**
+ * Lighter body `code` for the internal-error envelope it answers when a token's
+ * signature does not verify — the message reads `invalid signature`. Only the
+ * auth-gated read path treats it as an auth failure; a public read keeps the
+ * venue-error classification.
+ *
+ * @internal
+ */
+const LIGHTER_INVALID_SIGNATURE_CODE = 29500
+
 /**
  * Lighter body `code` values that mean success. Lighter is inconsistent per
  * endpoint: `/api/v1/account` returns `code: 200`, most others return `code: 0`.
@@ -266,6 +289,7 @@ const LIGHTER_REFERRAL_ALREADY_USED_CODE = 41003
 export {
   LIGHTER_CODE_ACCOUNT_NOT_FOUND,
   LIGHTER_INVALID_AUTH_CODE,
+  LIGHTER_INVALID_SIGNATURE_CODE,
   LIGHTER_MUTATION_SUCCESS_CODE,
   LIGHTER_REFERRAL_ALREADY_USED_CODE,
   LIGHTER_SUCCESS_CODES,

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/account.ts

@@ -30,12 +30,18 @@ export type LtAccountPosition = {
   /**
    * Funding accrued since the position opened, signed from the account's point
    * of view despite the field name: negative is funding the account paid and
-   * positive is funding it received. Lighter resets it to `"0"` on close.
+   * positive is funding it received. Lighter resets it to `"0"` on close, and
+   * marks it `omitempty`, so a position that accrued no funding yet omits the
+   * field entirely; an absent value means zero.
    */
-  total_funding_paid_out: string
+  total_funding_paid_out?: string
   margin_mode: number
   allocated_margin: string
-  total_discount: string
+  /**
+   * Funding-fee discount accrued on the position. Lighter marks it
+   * `omitempty`, so an absent field means zero.
+   */
+  total_discount?: string
   /** Lighter bit flags recording which margin settings the account set itself. */
   margin_set_flag?: number
 }
@@ -125,7 +131,12 @@ export interface LtDetailedAccount {
    * treat `0` as "no transaction" and not as the Unix epoch.
    */
   transaction_time: number
-  account_trading_mode: number
+  /**
+   * Lighter marks it `omitempty` here, so an absent field means
+   * `LT_ACCOUNT_TRADING_MODE_SIMPLE`, the wire zero value. `LtSubAccount`
+   * reports the same member without the omission.
+   */
+  account_trading_mode?: number
   account_index: number
   name: string
   description: string

package/src/types/action.ts

@@ -184,6 +184,21 @@ export const LT_MARGIN_MODE_CROSS = 0
  */
 export const LT_MARGIN_MODE_ISOLATED = 1
 
+/**
+ * Lighter account-trading-mode value for the Classic/Simple account, which
+ * segregates margin per market. The wire zero value, so an omitted
+ * `account_trading_mode` means this mode.
+ * @public
+ */
+export const LT_ACCOUNT_TRADING_MODE_SIMPLE = 0
+
+/**
+ * Lighter account-trading-mode value for the Unified Trading Account, which
+ * margins across assets.
+ * @public
+ */
+export const LT_ACCOUNT_TRADING_MODE_UNIFIED = 1
+
 /**
  * Lighter margin-direction value for removing margin.
  * @public

package/src/types/fill.ts

@@ -41,8 +41,9 @@ export type LtTrade = {
   transaction_time: number
   // Per-counterparty position snapshot BEFORE the trade is applied. Signed
   // strings: positive = long, negative = short, "0" / "0.00000" = flat.
-  taker_position_size_before: string
-  maker_position_size_before: string
+  // Lighter marks both `omitempty`, so an absent key means flat.
+  taker_position_size_before?: string
+  maker_position_size_before?: string
   // Per-counterparty entry-quote (notional cost basis) snapshot BEFORE the
   // trade. Paired with `*_position_size_before`, avg entry =
   // entry_quote_before / |position_size_before|. Optional: absent on older

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