@lifi/perps-sdk-provider-lighter 17.3.0 → 18.0.0

package/src/signers/LighterKeyStore.ts

@@ -1,5 +1,9 @@
-import { readValidatedRecord, type StorageAdapter } from '@lifi/perps-sdk'
-import type { LighterProviderKey } from '@lifi/perps-types'
+import {
+  PerpsError,
+  readValidatedRecord,
+  type StorageAdapter,
+} from '@lifi/perps-sdk'
+import { type LighterProviderKey, PerpsErrorCode } from '@lifi/perps-types'
 import type { Address } from 'viem'
 import { LIGHTER_PROVIDER_KEY } from '../constants.js'
 
@@ -30,6 +34,8 @@ export interface LighterApiKey {
   apiKeyPrivateKey: string
   /** Corresponding public key, registered via ChangePubKey. */
   apiKeyPublicKey: string
+  /** Referral code confirmed by the standard-token SET_REFERRAL action. */
+  appliedReferralCode?: string
 }
 
 const isLighterApiKeyOf =
@@ -44,6 +50,7 @@ const isLighterApiKeyOf =
       apiKeyIndex,
       apiKeyPrivateKey,
       apiKeyPublicKey,
+      appliedReferralCode,
     } = value as Record<string, unknown>
     return (
       providerKey === owner &&
@@ -54,7 +61,10 @@ const isLighterApiKeyOf =
       typeof apiKeyPrivateKey === 'string' &&
       apiKeyPrivateKey.length > 0 &&
       typeof apiKeyPublicKey === 'string' &&
-      apiKeyPublicKey.length > 0
+      apiKeyPublicKey.length > 0 &&
+      (appliedReferralCode === undefined ||
+        (typeof appliedReferralCode === 'string' &&
+          appliedReferralCode.length > 0))
     )
   }
 
@@ -140,6 +150,21 @@ export class LighterKeyStore {
     await this.storage.set(key, JSON.stringify(record))
   }
 
+  async markReferralApplied(
+    address: Address,
+    appliedReferralCode: string
+  ): Promise<void> {
+    const current = await this.get(address)
+    if (current === null) {
+      throw new PerpsError(
+        PerpsErrorCode.SDKError,
+        `Cannot persist the Lighter referral marker without an API key for ${address}`
+      )
+    }
+    const { providerKey: _providerKey, ...value } = current
+    await this.set(address, { ...value, appliedReferralCode })
+  }
+
   /**
    * Remove the persisted API key for an L1 address and clear its in-memory
    * cache entry.

package/src/signers/LighterReadOnlyTokenManager.ts

@@ -75,6 +75,7 @@ export type LighterTokenFetcher = (params: {
   expiry: number
   subAccountAccess: boolean
   scopes: string
+  fetchImpl?: typeof fetch
 }) => Promise<LighterCreateTokenResponse>
 
 /**
@@ -127,6 +128,7 @@ export type LighterTokenListFetcher = (params: {
   url: string
   authorization: string
   accountIndex: number
+  fetchImpl?: typeof fetch
 }) => Promise<LighterListTokensResponse>
 
 /**
@@ -139,6 +141,7 @@ export type LighterTokenRevokeFetcher = (params: {
   authorization: string
   tokenId: number
   accountIndex: number
+  fetchImpl?: typeof fetch
 }) => Promise<LighterRevokeTokenResponse>
 
 /**
@@ -165,6 +168,8 @@ export interface LighterReadOnlyTokenManagerOptions {
   listFetcher?: LighterTokenListFetcher
   /** Override the revoke POST. Defaults to a `fetch`-based implementation. */
   revokeFetcher?: LighterTokenRevokeFetcher
+  /** Transport used by the default endpoint fetchers. Defaults to `fetch`. */
+  fetchImpl?: typeof fetch
   /** Clock injection for testing expiry logic. Defaults to `Date.now`. */
   now?: () => number
 }
@@ -259,6 +264,7 @@ export class LighterReadOnlyTokenManager {
   private readonly fetcher: LighterTokenFetcher
   private readonly listFetcher: LighterTokenListFetcher
   private readonly revokeFetcher: LighterTokenRevokeFetcher
+  private readonly fetchImpl: typeof fetch | undefined
   private readonly now: () => number
   private readonly cache = new Map<string, LighterReadOnlyToken>()
 
@@ -270,6 +276,7 @@ export class LighterReadOnlyTokenManager {
     this.listFetcher = options.listFetcher ?? defaultLighterTokenListFetcher
     this.revokeFetcher =
       options.revokeFetcher ?? defaultLighterTokenRevokeFetcher
+    this.fetchImpl = options.fetchImpl
     this.now = options.now ?? (() => Date.now())
   }
 
@@ -398,10 +405,31 @@ export class LighterReadOnlyTokenManager {
     authorization: string,
     inputs: ApproveReadOnlyTokenInputs
   ): Promise<ApproveReadOnlyTokenResult> {
-    const { address, accountIndex, expirySeconds, scope } = inputs
+    await this.revokeStaleOwnTokens(
+      authorization,
+      inputs.address,
+      inputs.accountIndex
+    )
+    return this.createAndPersist(authorization, inputs)
+  }
 
-    await this.revokeStaleOwnTokens(authorization, address, accountIndex)
+  /**
+   * Replace a token that Lighter explicitly reports as revoked.
+   * The venue already revoked the row, so this path skips registry cleanup.
+   */
+  async replaceRevoked(
+    authorization: string,
+    inputs: ApproveReadOnlyTokenInputs
+  ): Promise<ApproveReadOnlyTokenResult> {
+    await this.remove(inputs.address, inputs.accountIndex)
+    return this.createAndPersist(authorization, inputs)
+  }
 
+  private async createAndPersist(
+    authorization: string,
+    inputs: ApproveReadOnlyTokenInputs
+  ): Promise<ApproveReadOnlyTokenResult> {
+    const { address, accountIndex, expirySeconds, scope } = inputs
     const response = await this.fetcher({
       url: `${this.lighterApiUrl}/api/v1/tokens/create`,
       authorization,
@@ -410,6 +438,7 @@ export class LighterReadOnlyTokenManager {
       expiry: expirySeconds,
       subAccountAccess: scope === 'all',
       scopes: 'read.*',
+      fetchImpl: this.fetchImpl,
     })
 
     const token: LighterReadOnlyToken = {
@@ -457,6 +486,7 @@ export class LighterReadOnlyTokenManager {
         url: `${this.lighterApiUrl}/api/v1/tokens`,
         authorization,
         accountIndex,
+        fetchImpl: this.fetchImpl,
       })
       const nowSeconds = Math.floor(this.now() / 1000)
       const stale = rows
@@ -476,6 +506,7 @@ export class LighterReadOnlyTokenManager {
             authorization,
             tokenId: row.token_id,
             accountIndex,
+            fetchImpl: this.fetchImpl,
           })
         } catch (err) {
           console.warn(
@@ -508,6 +539,7 @@ export const defaultLighterTokenFetcher: LighterTokenFetcher = async ({
   expiry,
   subAccountAccess,
   scopes,
+  fetchImpl,
 }) => {
   const form = new FormData()
   form.set('name', name)
@@ -516,7 +548,7 @@ export const defaultLighterTokenFetcher: LighterTokenFetcher = async ({
   form.set('sub_account_access', String(subAccountAccess))
   form.set('scopes', scopes)
 
-  const response = await fetch(url, {
+  const response = await (fetchImpl ?? fetch)(url, {
     method: 'POST',
     headers: { authorization },
     body: form,
@@ -544,10 +576,11 @@ export const defaultLighterTokenListFetcher: LighterTokenListFetcher = async ({
   url,
   authorization,
   accountIndex,
+  fetchImpl,
 }) => {
   const query = new URLSearchParams({ account_index: String(accountIndex) })
 
-  const response = await fetch(`${url}?${query.toString()}`, {
+  const response = await (fetchImpl ?? fetch)(`${url}?${query.toString()}`, {
     headers: { authorization },
   })
 
@@ -570,13 +603,13 @@ export const defaultLighterTokenListFetcher: LighterTokenListFetcher = async ({
  * @internal
  */
 export const defaultLighterTokenRevokeFetcher: LighterTokenRevokeFetcher =
-  async ({ url, authorization, tokenId, accountIndex }) => {
+  async ({ url, authorization, tokenId, accountIndex, fetchImpl }) => {
     const form = new URLSearchParams({
       token_id: String(tokenId),
       account_index: String(accountIndex),
     })
 
-    const response = await fetch(url, {
+    const response = await (fetchImpl ?? fetch)(url, {
       method: 'POST',
       headers: {
         authorization,

package/src/signers/signActions.ts

@@ -304,11 +304,14 @@ async function signRegisterApiKey(
     l1Signature
   )
 
+  // The referral marker belongs to the L1 address, not to the key slot.
+  const previousKey = await deps.keyStore.get(address)
   await deps.keyStore.set(address, {
     accountIndex,
     apiKeyIndex,
     apiKeyPrivateKey: keypair.privateKey,
     apiKeyPublicKey: keypair.publicKey,
+    appliedReferralCode: previousKey?.appliedReferralCode,
   })
 
   return {
@@ -461,12 +464,15 @@ async function executeTokenAuthMutation(
     accountIndex: apiKey.accountIndex,
   })
 
+  let appliedReferralCode: string | undefined
   if (step.wasmSignParams.kind === 'referralUse') {
     const { referral_code } = step.wasmSignParams as { referral_code?: string }
+    appliedReferralCode = referral_code
     if (
       typeof referral_code === 'string' &&
       (await isReferralAlreadyApplied(deps, address, authToken, referral_code))
     ) {
+      await deps.keyStore.markReferralApplied(address, referral_code)
       return
     }
   }
@@ -485,6 +491,10 @@ async function executeTokenAuthMutation(
       `Lighter ${step.action} rejected (code ${code ?? status})${suffix}`
     )
   }
+
+  if (appliedReferralCode !== undefined) {
+    await deps.keyStore.markReferralApplied(address, appliedReferralCode)
+  }
 }
 
 /**

package/src/utils/apiClient.ts

@@ -7,6 +7,7 @@ import { PerpsErrorCode } from '@lifi/perps-types'
 import {
   LIGHTER_INVALID_AUTH_CODE,
   LIGHTER_SUCCESS_CODES,
+  LIGHTER_TOKEN_REVOKED_CODE,
 } from '../constants.js'
 
 /** @internal */
@@ -26,19 +27,27 @@ const lighterBodyErrorCode = (data: unknown): number | undefined => {
 }
 
 /**
- * Auth-gated read whose token Lighter rejected. Distinct from a generic
- * {@link PerpsError} so callers can evict the stored read-only token and retry
- * with a freshly-created one. Lighter signals this on either channel: an HTTP
- * 401/403, or an HTTP 200 carrying an error `code` in the body.
+ * Auth-gated read whose token format Lighter rejected.
+ *
  * @internal
  */
 export class LighterAuthRejectedError extends PerpsError {}
 
+/**
+ * Auth-gated read whose read-only token Lighter reports as revoked.
+ *
+ * @internal
+ */
+export class LighterTokenRevokedError extends PerpsError {}
+
 const isLighterAuthRejection = (status: number, data: unknown): boolean =>
   status === 401 ||
   status === 403 ||
   lighterBodyErrorCode(data) === LIGHTER_INVALID_AUTH_CODE
 
+const isLighterTokenRevoked = (data: unknown): boolean =>
+  lighterBodyErrorCode(data) === LIGHTER_TOKEN_REVOKED_CODE
+
 /** @internal */
 export const LIGHTER_RETRY_DEFAULTS: ResolvedRetryPolicy = {
   enabled: true,
@@ -47,9 +56,6 @@ export const LIGHTER_RETRY_DEFAULTS: ResolvedRetryPolicy = {
   maxDelayMs: 60_000,
   respectRetryAfter: true,
   classify: ({ response }) => {
-    if (response.status === 429 || response.status === 405) {
-      return 'retry-rate-limit'
-    }
     if (
       response.status === 502 ||
       response.status === 503 ||
@@ -61,11 +67,42 @@ export const LIGHTER_RETRY_DEFAULTS: ResolvedRetryPolicy = {
   },
 }
 
+const LIGHTER_RATE_LIMIT_HOLD_MS = 60_000
+const LIGHTER_RATE_LIMIT_HOLD_MAX_MS = 300_000
+
+const isLighterRateLimit = (status: number): boolean =>
+  status === 429 || status === 405
+
+const retryAfterMs = (header: string | null, nowMs: number): number => {
+  if (header === null) {
+    return LIGHTER_RATE_LIMIT_HOLD_MS
+  }
+  const seconds = Number(header)
+  if (Number.isFinite(seconds) && seconds >= 0) {
+    return Math.min(seconds * 1000, LIGHTER_RATE_LIMIT_HOLD_MAX_MS)
+  }
+  const dateMs = Date.parse(header)
+  return Number.isFinite(dateMs)
+    ? Math.min(Math.max(0, dateMs - nowMs), LIGHTER_RATE_LIMIT_HOLD_MAX_MS)
+    : LIGHTER_RATE_LIMIT_HOLD_MS
+}
+
+/**
+ * Mutable rate-limit deadline shared by the request clients for one provider
+ * instance. A client creates an isolated hold when the caller omits this.
+ *
+ * @internal
+ */
+export interface LighterRateLimitHold {
+  untilMs: number
+}
+
 /** @internal */
 export interface LighterApiClientOptions {
   signal?: AbortSignal
   policy?: ResolvedRetryPolicy
   fetchImpl?: typeof fetch
+  rateLimitHold?: LighterRateLimitHold
 }
 
 /**
@@ -82,9 +119,10 @@ export interface LighterApiClientOptions {
  * `Authorization` header. This matches Lighter's OpenAPI spec and lets the
  * same call work browser-direct and from server-side proxies.
  *
- * Lighter signals rate limiting via 429 OR 405 (documented behaviour) with a
- * documented 60s firewall cooldown. The default {@link ResolvedRetryPolicy}
- * waits long enough to avoid hammering through the cooldown.
+ * 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
+ * seconds when the response has no valid header.
  * @public
  */
 export class LighterApiClient {
@@ -92,14 +130,57 @@ export class LighterApiClient {
   private readonly signal: AbortSignal | undefined
   private readonly policy: ResolvedRetryPolicy
   private readonly fetchImpl: typeof fetch | undefined
+  private readonly rateLimitHold: LighterRateLimitHold
+  private readonly fetchWithHold: typeof fetch
 
   constructor(baseUrl: string, options?: LighterApiClientOptions) {
     this.baseUrl = baseUrl.replace(/\/$/, '')
     this.signal = options?.signal
     this.policy = options?.policy ?? LIGHTER_RETRY_DEFAULTS
     this.fetchImpl = options?.fetchImpl
+    this.rateLimitHold = options?.rateLimitHold ?? { untilMs: 0 }
+    this.fetchWithHold = async (input, init) => {
+      this.assertRequestAllowed()
+      const response = await (this.fetchImpl ?? fetch)(input, init)
+      if (isLighterRateLimit(response.status)) {
+        const responseNowMs = Date.now()
+        this.rateLimitHold.untilMs = Math.max(
+          this.rateLimitHold.untilMs,
+          responseNowMs +
+            retryAfterMs(response.headers.get('Retry-After'), responseNowMs)
+        )
+      }
+      return response
+    }
+  }
+
+  /**
+   * Send a single request through this client's rate-limit hold.
+   *
+   * @internal
+   */
+  request(input: RequestInfo | URL, init?: RequestInit): Promise<Response> {
+    return this.fetchWithHold(input, init)
+  }
+
+  private rateLimitError(): PerpsError {
+    return new PerpsError(
+      PerpsErrorCode.RateLimitExceeded,
+      `Lighter API requests are held until ${new Date(this.rateLimitHold.untilMs).toISOString()}`
+    )
   }
 
+  private assertRequestAllowed(): void {
+    if (Date.now() < this.rateLimitHold.untilMs) {
+      throw this.rateLimitError()
+    }
+  }
+
+  private assertNotRateLimited(response: Response): void {
+    if (isLighterRateLimit(response.status)) {
+      throw this.rateLimitError()
+    }
+  }
   private buildUrl(path: string, params?: ApiParams): string {
     const url = `${this.baseUrl}${path}`
     if (!params || Object.keys(params).length === 0) {
@@ -131,6 +212,12 @@ export class LighterApiClient {
       ...params,
       auth: authToken,
     })
+    if (isLighterTokenRevoked(data)) {
+      throw new LighterTokenRevokedError(
+        PerpsErrorCode.ThirdPartyError,
+        `Lighter reports a revoked auth token for ${path}`
+      )
+    }
     if (isLighterAuthRejection(status, data)) {
       throw new LighterAuthRejectedError(
         PerpsErrorCode.ThirdPartyError,
@@ -150,12 +237,18 @@ export class LighterApiClient {
     path: string,
     params?: ApiParams
   ): Promise<{ status: number; data: T }> {
+    this.assertRequestAllowed()
     const url = this.buildUrl(path, params)
     const response = await fetchWithRetry(
       url,
       {},
-      { policy: this.policy, fetchImpl: this.fetchImpl, signal: this.signal }
+      {
+        policy: this.policy,
+        fetchImpl: this.fetchWithHold,
+        signal: this.signal,
+      }
     )
+    this.assertNotRateLimited(response)
     const data = (await response.json().catch(() => undefined)) as T
     return { status: response.status, data }
   }
@@ -174,13 +267,13 @@ export class LighterApiClient {
     for (const [k, v] of Object.entries(params)) {
       body.set(k, String(v))
     }
-    const fetchImpl = this.fetchImpl ?? fetch
-    const response = await fetchImpl(`${this.baseUrl}${path}`, {
+    const response = await this.fetchWithHold(`${this.baseUrl}${path}`, {
       method: 'POST',
       headers: { 'content-type': 'application/x-www-form-urlencoded' },
       body: body.toString(),
       signal: this.signal,
     })
+    this.assertNotRateLimited(response)
     const data = (await response.json().catch(() => undefined)) as T
     return { status: response.status, data }
   }