@lifi/perps-sdk-provider-lighter 1.6.0 → 1.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lifi/perps-sdk-provider-lighter",
-  "version": "1.6.0",
+  "version": "1.8.0",
   "description": "Lighter provider plugin for @lifi/perps-sdk",
   "homepage": "https://github.com/lifinance/perps-sdk",
   "bugs": {
@@ -46,10 +46,10 @@
   "dependencies": {
     "big.js": "^7.0.1",
     "viem": "^2.48.8",
-    "@lifi/perps-types": "^1.10.0"
+    "@lifi/perps-types": "^1.12.0"
   },
   "peerDependencies": {
-    "@lifi/perps-sdk": "^1.5.6"
+    "@lifi/perps-sdk": "^1.6.0"
   },
   "publishConfig": {
     "access": "public"

package/src/LighterProvider.ts

@@ -81,6 +81,7 @@ import {
   LighterApiClient,
   LighterAuthRejectedError,
 } from './utils/apiClient.js'
+import { isAssetMarginEnabled } from './utils/assetCollateral.js'
 import {
   classifyAndMapOrders,
   estimateLiquidationPrice,
@@ -697,12 +698,25 @@ export const lighterProvider = (
         valueUsd: a.symbol === 'USDC' ? a.balance : '0',
       }))
 
+      const assetCollateral = account.assets.flatMap((a) =>
+        a.margin_mode === undefined
+          ? []
+          : [
+              {
+                assetId: String(a.asset_id),
+                enabled: isAssetMarginEnabled(a.margin_mode),
+              },
+            ]
+      )
+
       const config: LighterAccountConfig = {
         provider: LIGHTER_PROVIDER_KEY,
         accountIndex: account.index,
         apiKeyIndex: DEFAULT_API_KEY_INDEX,
         apiKeyRegistered,
         accountType: account.account_type,
+        accountTradingMode: account.account_trading_mode,
+        assetCollateral,
         // Satisfied when a non-expired read-only token is stored locally
         // (`readOnlyTokenManager.get` filters out expired ones).
         readOnlyTokenApproved: storedReadOnlyToken !== undefined,
@@ -1202,6 +1216,7 @@ export const lighterProvider = (
         {
           signer: signerRef,
           keyStore: keyStoreRef,
+          apiClient: apiClient(),
           resolveAccountIndex: async (addr) => {
             const apiKey = await keyStoreRef.get(addr)
             if (apiKey !== null) {

package/src/accountConfig.ts

@@ -27,6 +27,17 @@ 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
+
+const ACCOUNT_MODE_INT_TO_WIRE: Readonly<Record<number, string>> = {
+  [LIGHTER_ACCOUNT_MODE_SIMPLE]: 'simpleTradingAccount',
+  [LIGHTER_ACCOUNT_MODE_UNIFIED]: 'unifiedTradingAccount',
+}
+
 /**
  * Project a single Lighter descriptor against the typed
  * `LighterAccountConfig` into an `AccountConfigSetting`.
@@ -37,8 +48,9 @@ const ACCOUNT_TYPE_INT_TO_WIRE: Readonly<Record<number, string>> = {
  * |---------------------------|--------------------------------------------------
  * | REGISTER_API_KEY          | []                  (no parameters)
  * | APPROVE_READ_ONLY_TOKEN   | []                  (no parameters)
- * | ACCOUNT_MODE              | [{ name: 'mode', value: null }]  (Lighter has no
- * |                           |  abstraction-mode equivalent; read-only here)
+ * | SET_REFERRAL              | []                  (no parameters)
+ * | APPROVE_INTEGRATOR        | []                  (no parameters)
+ * | ACCOUNT_MODE              | [{ name: 'mode', value: config.accountTradingMode }]
  * | ACCOUNT_TYPE              | [{ name: 'tier', value: config.accountType }]
  *
  * The switch is exhaustive over `ActionType` so enum additions force a
@@ -70,13 +82,25 @@ function projectLighterDescriptor(
         satisfied: config.readOnlyTokenApproved,
       }
 
-    // Lighter exposes no abstraction-mode equivalent; if a backend descriptor
-    // surfaces ACCOUNT_MODE on Lighter it always projects `null` and callers
-    // fall back to the descriptor's `default` ParamOption.
+    // Backend-gated setup steps: `checkSetup` → `createAction` decides
+    // satisfaction (the backend emits no actions once satisfied), so the
+    // projection carries no local state.
+    case ActionType.SET_REFERRAL:
+    case ActionType.APPROVE_INTEGRATOR:
+      return { type: descriptor.type, values: [] }
+
+    // `mode` decodes the raw `account_trading_mode` integer to the descriptor's
+    // wire strings (`unifiedTradingAccount` / `simpleTradingAccount`).
+    // Unrecognised integers project to `null`.
     case ActionType.ACCOUNT_MODE:
       return {
         type: descriptor.type,
-        values: [{ name: 'mode', value: null }],
+        values: [
+          {
+            name: 'mode',
+            value: ACCOUNT_MODE_INT_TO_WIRE[config.accountTradingMode] ?? null,
+          },
+        ],
       }
 
     // `tier` is the wire string `/changeAccountTier` accepts; we decode the
@@ -97,8 +121,6 @@ function projectLighterDescriptor(
 
     case ActionType.APPROVE_AGENT:
     case ActionType.APPROVE_BUILDER_FEE:
-    case ActionType.APPROVE_INTEGRATOR:
-    case ActionType.SET_REFERRAL:
     case ActionType.SEND_ASSET:
     case ActionType.WITHDRAWAL:
     case ActionType.TRANSFER:
@@ -109,6 +131,7 @@ function projectLighterDescriptor(
     case ActionType.MODIFY_ORDER:
     case ActionType.UPDATE_LEVERAGE:
     case ActionType.UPDATE_POSITION_MARGIN:
+    case ActionType.UPDATE_ASSET_COLLATERAL:
     case ActionType.DEPOSIT:
     case ActionType.META_VOTE:
     case ActionType.META_ACCEPT_TERMS:

package/src/constants.ts

@@ -83,8 +83,18 @@ const LIGHTER_INVALID_AUTH_CODE = 20013
  */
 const LIGHTER_SUCCESS_CODES = new Set([0, 200])
 
+/**
+ * Lighter body `code` meaning "operation succeeded" on the non-`/sendTx`
+ * mutation endpoints (`/changeAccountTier`, `/referral/use`). Any other code is
+ * a business-rule rejection surfaced verbatim to the caller.
+ *
+ * @internal
+ */
+const LIGHTER_MUTATION_SUCCESS_CODE = 200
+
 export {
   LIGHTER_CODE_ACCOUNT_NOT_FOUND,
   LIGHTER_INVALID_AUTH_CODE,
+  LIGHTER_MUTATION_SUCCESS_CODE,
   LIGHTER_SUCCESS_CODES,
 }

package/src/signers/LighterSigner.ts

@@ -1,5 +1,6 @@
 import { ActionType } from '@lifi/perps-types'
 import { DEFAULT_LIGHTER_REST_URL } from '../constants.js'
+import { assetMarginModeInt } from '../utils/assetCollateral.js'
 import {
   type LighterWasmExports,
   type LoadLighterWasmOptions,
@@ -425,6 +426,23 @@ export class LighterSigner {
           ctx.apiKeyIndex,
           ctx.accountIndex
         )
+      case ActionType.ACCOUNT_MODE:
+        return wasm.SignUpdateAccountConfig(
+          numberField(p, 'account_trading_mode'),
+          SKIP_NONCE_DISABLED,
+          nonce,
+          ctx.apiKeyIndex,
+          ctx.accountIndex
+        )
+      case ActionType.UPDATE_ASSET_COLLATERAL:
+        return wasm.SignUpdateAccountAssetConfig(
+          numberField(p, 'asset_index'),
+          assetMarginModeInt(booleanField(p, 'enabled')),
+          SKIP_NONCE_DISABLED,
+          nonce,
+          ctx.apiKeyIndex,
+          ctx.accountIndex
+        )
       default:
         throw new Error(
           `Lighter WASM signer does not support action: ${action}`
@@ -481,6 +499,16 @@ function optionalNumberField(
   return numberField(p, key)
 }
 
+function booleanField(p: Record<string, unknown>, key: string): boolean {
+  const v = p[key]
+  if (typeof v === 'boolean') {
+    return v
+  }
+  throw new Error(
+    `Lighter sign params missing boolean field '${key}' (got ${typeof v})`
+  )
+}
+
 function stringField(p: Record<string, unknown>, key: string): string {
   const v = p[key]
   if (typeof v === 'string' && v !== '') {

package/src/signers/signActions.ts

@@ -11,20 +11,29 @@ import { ActionType, PerpsErrorCode, SigningMethod } from '@lifi/perps-types'
 import type { Address } from 'viem'
 import { parseAbi } from 'viem'
 import { waitForTransactionReceipt } from 'viem/actions'
-import { DEFAULT_API_KEY_INDEX } from '../constants.js'
+import {
+  DEFAULT_API_KEY_INDEX,
+  LIGHTER_MUTATION_SUCCESS_CODE,
+} from '../constants.js'
+import type { ApiParams, LighterApiClient } from '../utils/apiClient.js'
 import type { LighterApiKey, LighterKeyStore } from './LighterKeyStore.js'
 import type { LighterSigner } from './LighterSigner.js'
 
 /**
  * Per-batch dependencies the Lighter `signActions` implementation needs:
  * a WASM signer (`LighterSigner`), the API-key store keyed on L1 address,
- * and a reference to the host SDK client for descriptor/account fetches
- * within the REGISTER_API_KEY hybrid flow.
+ * a REST client for the token-authenticated venue mutations that execute
+ * client-side, and a reference to the host SDK client for descriptor/account
+ * fetches within the REGISTER_API_KEY hybrid flow.
  * @internal
  */
 export interface LighterSignActionsDeps {
   signer: LighterSigner
   keyStore: LighterKeyStore
+  /** REST client bound to the user's Lighter base URL, used for the direct
+   * `changeAccountTier` / `referral/use` POSTs so their auth token never
+   * transits the LI.FI backend. */
+  apiClient: LighterApiClient
   /**
    * Resolve the user's Lighter `accountIndex` for an L1 address. Required
    * by REGISTER_API_KEY so the ChangePubKey blob carries the right
@@ -34,15 +43,32 @@ export interface LighterSignActionsDeps {
   resolveAccountIndex(address: Address): Promise<number>
 }
 
+/**
+ * `wasmSignParams.kind` values for the Lighter mutations that authenticate with
+ * a short-lived auth token instead of a wasm-signed transaction. Both execute
+ * client-side (SDK → Lighter REST) so the token never reaches the backend.
+ * @internal
+ */
+const TOKEN_AUTH_MUTATION_KINDS = new Set(['changeAccountTier', 'referralUse'])
+
+/**
+ * Lifetime of the per-call auth token minted for a token-authenticated venue
+ * mutation. Minutes, not the read endpoints' hours: it authenticates one POST
+ * that completes immediately, so it never lingers usable.
+ */
+const TOKEN_AUTH_MUTATION_DEADLINE_SECONDS = 5 * 60
+
 /**
  * Sign a `WASM_BLOB` batch (Lighter). Ensures the user's API keypair is
  * registered first — generating one and running the REGISTER_API_KEY
  * hybrid flow via the L1 signer if not — then feeds each subsequent step
  * through the WASM signer.
  *
- * `ACCOUNT_TYPE` (Lighter `/changeAccountTier`) is a WASM_BLOB envelope
- * authenticated with an auth token rather than a wasm tx signature —
- * created via `LighterSigner.createAuthToken` and parked in `signedTx.txInfo`.
+ * The token-authenticated mutations (`ACCOUNT_TYPE` → `/changeAccountTier`,
+ * `SET_REFERRAL` → `/referral/use`) are NOT wasm-signed: they execute
+ * client-side here via a direct Lighter POST authenticated with a short-lived
+ * auth token, so the token never transits the LI.FI backend. They produce no
+ * backend-bound step and are omitted from the returned array.
  * @internal
  */
 export async function signWasmBlobActions(
@@ -55,8 +81,10 @@ export async function signWasmBlobActions(
   for (const step of steps) {
     if (step.action === ActionType.REGISTER_API_KEY) {
       signed.push(await signRegisterApiKey(deps, address, step, ctx))
-    } else if (step.action === ActionType.ACCOUNT_TYPE) {
-      signed.push(await signAccountTierChange(deps, address, step))
+    } else if (
+      TOKEN_AUTH_MUTATION_KINDS.has(step.wasmSignParams.kind as string)
+    ) {
+      await executeTokenAuthMutation(deps, address, step)
     } else {
       signed.push(await signStandardWasmAction(deps, address, step))
     }
@@ -169,44 +197,94 @@ async function signRegisterApiKey(
 }
 
 /**
- * Sign an `ACCOUNT_TYPE` step (Lighter `changeAccountTier`).
- *
- * Lighter's `/api/v1/changeAccountTier` is an HTTP-only mutation —
- * Lighter does NOT consume a wasm-signed transaction here; it
- * authenticates the request with the same auth token its read endpoints
- * use, and enforces anti-replay business rules server-side. The backend
- * declares the step as a `WasmBlobActionStep` with
- * `wasmSignParams.kind = 'changeAccountTier'` and expects the SDK to create
- * an auth token in lieu of a transaction signature; the executor reads
- * `signedTx.txInfo` as the `auth` form parameter.
+ * Execute a token-authenticated Lighter mutation (`ACCOUNT_TYPE` →
+ * `/changeAccountTier`, `SET_REFERRAL` → `/referral/use`) client-side.
  *
- * The 1h deadline mirrors the previous behaviour — Lighter caps tokens at
- * 8h hard, and the backend's executor runs `verifyPendingAction` then a
- * single POST, which completes well inside an hour.
+ * Neither endpoint consumes a wasm-signed transaction — both authenticate with
+ * a Lighter auth token and enforce their business rules (open positions,
+ * pending orders, 24h tier cooldown) server-side. We mint a fresh short-lived
+ * token per call (never the stored read-only token, never persisted) and POST
+ * the mirror of the backend's form body directly to Lighter, so no auth token
+ * ever transits the LI.FI backend. A non-success verdict surfaces Lighter's
+ * `code`/`message` verbatim as an {@link PerpsErrorCode.ExchangeRejected}.
  */
-async function signAccountTierChange(
+async function executeTokenAuthMutation(
   deps: LighterSignActionsDeps,
   address: Address,
   step: WasmBlobActionStep
-): Promise<WasmBlobSignedActionStep> {
+): Promise<void> {
   const apiKey = await requireApiKey(deps, address)
-  const deadline = Math.floor(Date.now() / 1000) + 60 * 60
+  const deadline =
+    Math.floor(Date.now() / 1000) + TOKEN_AUTH_MUTATION_DEADLINE_SECONDS
   const authToken = await deps.signer.createAuthToken(deadline, {
     apiKeyPrivateKey: apiKey.apiKeyPrivateKey,
     apiKeyIndex: apiKey.apiKeyIndex,
     accountIndex: apiKey.accountIndex,
   })
-  return {
-    action: step.action,
-    wasmSignParams: step.wasmSignParams,
-    signedTx: {
-      // `/changeAccountTier` reads only `txInfo` (the auth token); `txType`
-      // and `txHash` are placeholders to satisfy the envelope shape.
-      txType: 0,
-      txInfo: authToken,
-      txHash: '',
-    },
+
+  const { path, params } = buildTokenAuthMutationRequest(step, authToken)
+  const { status, data } = await deps.apiClient.postForm<{
+    code?: number
+    message?: string
+  }>(path, params)
+
+  const code = data?.code
+  if (status < 200 || status >= 300 || code !== LIGHTER_MUTATION_SUCCESS_CODE) {
+    const suffix = data?.message ? `: ${data.message}` : ''
+    throw new PerpsError(
+      PerpsErrorCode.ExchangeRejected,
+      `Lighter ${step.action} rejected (code ${code ?? status})${suffix}`
+    )
+  }
+}
+
+/**
+ * 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`.
+ */
+function buildTokenAuthMutationRequest(
+  step: WasmBlobActionStep,
+  authToken: string
+): { path: string; params: ApiParams } {
+  const kind = step.wasmSignParams.kind
+  if (kind === 'changeAccountTier') {
+    const { account_index, new_tier } = step.wasmSignParams as {
+      account_index?: number
+      new_tier?: string
+    }
+    if (account_index == null || new_tier == null) {
+      throw new PerpsError(
+        PerpsErrorCode.SDKError,
+        'Lighter ACCOUNT_TYPE wasmSignParams missing account_index or new_tier'
+      )
+    }
+    return {
+      path: '/api/v1/changeAccountTier',
+      params: { auth: authToken, account_index, new_tier },
+    }
+  }
+  if (kind === 'referralUse') {
+    const { l1_address, referral_code, x } = step.wasmSignParams as {
+      l1_address?: string
+      referral_code?: string
+      x?: string
+    }
+    if (l1_address == null || referral_code == null || x == null) {
+      throw new PerpsError(
+        PerpsErrorCode.SDKError,
+        'Lighter SET_REFERRAL wasmSignParams missing l1_address, referral_code, or x'
+      )
+    }
+    return {
+      path: '/api/v1/referral/use',
+      params: { auth: authToken, l1_address, referral_code, x },
+    }
   }
+  throw new PerpsError(
+    PerpsErrorCode.SDKError,
+    `Lighter token-auth mutation: unknown wasmSignParams.kind '${String(kind)}'`
+  )
 }
 
 async function requireApiKey(
@@ -266,16 +344,6 @@ export async function signEvmTxActions(
       )
     }
 
-    if (walletSigner.chain?.id !== params.chainId) {
-      throw new PerpsError(
-        PerpsErrorCode.SDKError,
-        `EVM_TX leg '${step.action}' targets chain ${params.chainId}, but the ` +
-          `connected wallet is on chain ${walletSigner.chain?.id ?? 'unknown'}. ` +
-          `Switch the wallet to chain ${params.chainId} before signing — the ` +
-          "SDK broadcasts on the wallet's active chain and does not switch it."
-      )
-    }
-
     const txHash = await walletSigner.writeContract({
       address: params.to,
       abi: parseAbi(params.abi),

package/src/signers/wasmLoader.ts

@@ -166,6 +166,18 @@ export interface LighterWasmExports {
    * fee requires a non-nil integrator index.
    */
   SignApproveIntegrator: (...args: unknown[]) => SignResult
+  /**
+   * 5 args: accountTradingMode (0 = Classic/Simple, 1 = Unified), skipNonce,
+   * then the trailing three. `accountTradingMode` is validated to {0, 1} by
+   * lighter-go before signing.
+   */
+  SignUpdateAccountConfig: (...args: unknown[]) => SignResult
+  /**
+   * 6 args: assetIndex, assetMarginMode (0 = MarginDisabled, 1 = MarginEnabled),
+   * skipNonce, then the trailing three. Keyed per spot asset, not per market —
+   * signs `L2UpdateAccountAssetConfigTx` (tx type 42).
+   */
+  SignUpdateAccountAssetConfig: (...args: unknown[]) => SignResult
 }
 
 /** @internal */
@@ -191,6 +203,8 @@ const WASM_FUNCTION_NAMES = [
   'SignModifyOrder',
   'SignUpdateMargin',
   'SignApproveIntegrator',
+  'SignUpdateAccountConfig',
+  'SignUpdateAccountAssetConfig',
 ] as const
 
 type GoClass = new () => {

package/src/types/account.ts

@@ -29,6 +29,12 @@ export type LtAccountAsset = {
   asset_id: number
   balance: string
   locked_balance: string
+  /**
+   * Cross-margin collateral flag: 0 = MarginDisabled, 1 = MarginEnabled.
+   * Lighter surfaces it via `additional_properties`, so it may be absent —
+   * chiefly outside Unified Trading Account mode.
+   */
+  margin_mode?: number
 }
 
 /**

package/src/utils/apiClient.ts

@@ -160,6 +160,31 @@ export class LighterApiClient {
     return { status: response.status, data }
   }
 
+  /**
+   * 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.
+   */
+  async postForm<T>(
+    path: string,
+    params: ApiParams
+  ): Promise<{ status: number; data: T }> {
+    const body = new URLSearchParams()
+    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}`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/x-www-form-urlencoded' },
+      body: body.toString(),
+      signal: this.signal,
+    })
+    const data = (await response.json().catch(() => undefined)) as T
+    return { status: response.status, data }
+  }
+
   private async getChecked<T>(path: string, params?: ApiParams): Promise<T> {
     const { status, data } = await this.getWithStatus<unknown>(path, params)
     this.assertOk(path, status, data)

package/src/utils/assetCollateral.ts

@@ -0,0 +1,16 @@
+// Lighter's `AssetMarginMode` wire ints (lighter-go
+// `types/txtypes/update_account_asset_config.go`), used for both the write
+// direction (signing `L2UpdateAccountAssetConfigTx`, tx type 42) and decoding
+// an account asset's `margin_mode` on the read side.
+const ASSET_MARGIN_DISABLED = 0
+const ASSET_MARGIN_ENABLED = 1
+
+/** Map the user-facing `enabled` flag to Lighter's `AssetMarginMode` wire int. */
+export function assetMarginModeInt(enabled: boolean): number {
+  return enabled ? ASSET_MARGIN_ENABLED : ASSET_MARGIN_DISABLED
+}
+
+/** Decode Lighter's `margin_mode` int on an account asset back to `enabled`. */
+export function isAssetMarginEnabled(marginMode: number): boolean {
+  return marginMode === ASSET_MARGIN_ENABLED
+}