@lifi/perps-sdk 1.6.0 → 2.1.0

package/src/types/api.ts

@@ -14,7 +14,11 @@ import type {
 } from '@lifi/perps-types'
 import type { Account, Address, WalletClient } from 'viem'
 import type { RetryConfig } from '../transport/retryPolicy.js'
-import type { ProviderConfigs, RequestInterceptor } from './config.js'
+import type {
+  ProviderConfigs,
+  RequestInterceptor,
+  SwitchChainHook,
+} from './config.js'
 import type { PerpsProviderPlugin } from './provider.js'
 
 /**
@@ -85,6 +89,12 @@ export interface PerpsClientOptions {
    * a keyed `ProviderConfigs` map.
    */
   providers?: PerpsProviderPlugin[] | ProviderConfigs
+  /**
+   * Hook invoked before a USER-signed EIP-712 action is signed, to switch the
+   * user's wallet to the action's target chain. Also settable at runtime via
+   * `setSwitchChain`.
+   */
+  switchChain?: SwitchChainHook
 }
 
 /**
@@ -145,6 +155,22 @@ export interface WithdrawParams {
   withdrawal: WithdrawalParams
 }
 
+/**
+ * Parameters for {@link PerpsClient.sendAsset}. The send-asset fields are held
+ * flat (not nested) to avoid colliding with `@lifi/perps-types`'
+ * `SendAssetParams`, which types the underlying action payload.
+ *
+ * @public
+ */
+export interface SendAssetActionParams {
+  provider: string
+  address: Address
+  collateral: string
+  sourceDex: string
+  destinationDex: string
+  amount: string
+}
+
 /**
  * Parameters for canceling orders.
  *
@@ -153,7 +179,11 @@ export interface WithdrawParams {
 export interface CancelOrdersParams {
   provider: string
   address: Address
+  /** Venue order ids. Venues whose ids are scoped per market (e.g. Lighter's
+   * `order_index`) also accept the composite `"<market_id>:<order_id>"`. */
   ids: string[]
+  /** Market context for per-market order ids; the order's `market.id`. */
+  assetId?: string
 }
 
 /**
@@ -205,9 +235,7 @@ export interface ProviderSetup {
 }
 
 /**
- * Parameters for {@link PerpsClient.executeProviderSetup}.
- *
- * @public
+ * Parameters for the internal `PerpsClient.executeProviderSetup` batch submit.
  */
 export interface ExecuteProviderSetupParams {
   /** Provider to satisfy setup for */
@@ -221,9 +249,7 @@ export interface ExecuteProviderSetupParams {
 }
 
 /**
- * Result from {@link PerpsClient.executeProviderSetup}.
- *
- * @public
+ * Result from the internal `PerpsClient.executeProviderSetup` batch submit.
  */
 export interface ExecuteProviderSetupResult {
   results: ExecuteActionResponse

package/src/types/config.ts

@@ -9,6 +9,20 @@ import type { RetryConfig } from '../transport/retryPolicy.js'
  */
 export type PerpsClientSigner = WalletClient<any, any, Account>
 
+/**
+ * Consumer-supplied hook invoked at the SDK's signing choke point to switch the
+ * user's wallet to a USER-signed EIP-712 action's target chain. Modelled on
+ * `@lifi/sdk`'s switch-chain contract: a json-rpc wallet switches in place and
+ * resolves to the re-fetched client; a local/private-key signer resolves to a
+ * chain-bound client (or signs offline). Resolve to `undefined` to signal the
+ * switch could not be performed.
+ *
+ * @public
+ */
+export type SwitchChainHook = (
+  chainId: number
+) => Promise<PerpsClientSigner | undefined>
+
 /**
  * Per-provider config — restricts which `markets` the WS client subscribes
  * to. Indexed by provider key.

package/src/types/provider.ts

@@ -63,6 +63,17 @@ export interface SignActionsContext {
    * forwards the descriptor's `signers` as data; it does not branch on them.
    */
   signers?: PerpsSigner[]
+  /**
+   * Switch `userWallet` to `chainId` and resolve the client to broadcast with.
+   * Bound by core to the consumer's `switchChain` hook and the resolved
+   * `userWallet`: a no-op returning the same client when already on `chainId`,
+   * else it switches and re-verifies, rejecting with `PerpsErrorCode.SDKError`
+   * when the switch cannot be completed. Present only when a `switchChain` hook
+   * is configured; a plugin whose legs broadcast on-chain (Lighter's `EVM_TX`)
+   * calls it per leg, and falls back to a fail-loud wrong-chain guard when it is
+   * absent (local/private-key signer, or no hook).
+   */
+  switchToChain?: (chainId: number) => Promise<PerpsClientSigner>
 }
 
 /**

package/src/utils/accountSummary.ts

@@ -15,6 +15,9 @@ const sumValueUsd = (balances: AccountResponse['balances']): number =>
  * - `'free'` — free collateral only; locked margin and unrealized PnL are
  *   both carried by the positions. Available margin is the free collateral
  *   as-is; unrealized PnL is not counted toward it.
+ * - `'net'` — free collateral with unrealized PnL already marked in; only
+ *   the locked margin is carried by the positions (e.g. a venue-reported
+ *   available balance).
  * - `'gross'` — locked margin included, unrealized PnL carried by the
  *   positions (e.g. spot holdings backing a unified account). The venue
  *   counts unrealized PnL toward buying power, so it is added to available
@@ -25,7 +28,7 @@ const sumValueUsd = (balances: AccountResponse['balances']): number =>
  *
  * @public
  */
-export type CollateralSemantics = 'free' | 'gross' | 'equity'
+export type CollateralSemantics = 'free' | 'net' | 'gross' | 'equity'
 
 /**
  * Roll an {@link AccountResponse} and its open positions up into an
@@ -51,9 +54,13 @@ export function summarizeAccount(
   const balances = sumValueUsd(account.balances)
 
   const grossCollateral =
-    semantics === 'free' ? collateral + marginUsed : collateral
+    semantics === 'free' || semantics === 'net'
+      ? collateral + marginUsed
+      : collateral
   const equity =
-    semantics === 'equity' ? grossCollateral : grossCollateral + unrealizedPnl
+    semantics === 'equity' || semantics === 'net'
+      ? grossCollateral
+      : grossCollateral + unrealizedPnl
 
   // Buying power is equity net of locked margin, so unrealized PnL counts
   // toward it. The `'free'` rows exclude uPnL from available margin, holding

package/src/utils/switchChain.ts

@@ -0,0 +1,73 @@
+import type {
+  ActionStep,
+  Eip712ActionStep,
+  ProviderAction,
+} from '@lifi/perps-types'
+import { PerpsErrorCode, PerpsSigner, SigningMethod } from '@lifi/perps-types'
+import { getChainId } from 'viem/actions'
+import { PerpsError } from '../errors/PerpsError.js'
+import type { PerpsClientSigner, SwitchChainHook } from '../types/config.js'
+
+/**
+ * The chain a batch of `actions` must be signed on, or `undefined` when no
+ * wallet chain switch applies. Only USER-signed EIP-712 batches carry a target
+ * (agent-signed batches sign with a chain-bound keypair; other schemes are not
+ * EIP-712). Reads the first numeric `typedData.domain.chainId`; a batch whose
+ * steps omit `chainId` yields `undefined`.
+ */
+export function userEip712TargetChainId(
+  descriptor: ProviderAction,
+  actions: ActionStep[]
+): number | undefined {
+  if (
+    descriptor.signingMethod !== SigningMethod.EIP712 ||
+    !descriptor.signers.includes(PerpsSigner.USER)
+  ) {
+    return undefined
+  }
+  for (const step of actions) {
+    const chainId = (step as Eip712ActionStep).typedData?.domain?.chainId
+    if (typeof chainId === 'number') {
+      return chainId
+    }
+  }
+  return undefined
+}
+
+/**
+ * Ensure `wallet` is on `targetChainId` before signing, returning the wallet to
+ * sign with. Without a `switchChain` hook the wallet is returned unchanged (no
+ * throw, no RPC) — a local/private-key signer signs EIP-712 offline regardless
+ * of its transport chain. With a hook: probe the current chain via viem
+ * `getChainId`, return the wallet untouched when already on target, else invoke
+ * the hook and re-verify. Throws `PerpsErrorCode.SDKError` when the hook yields
+ * no client or a client still on the wrong chain.
+ */
+export async function switchSigningChain(
+  wallet: PerpsClientSigner,
+  targetChainId: number,
+  switchChain?: SwitchChainHook
+): Promise<PerpsClientSigner> {
+  if (!switchChain) {
+    return wallet
+  }
+  const currentChainId = await getChainId(wallet)
+  if (currentChainId === targetChainId) {
+    return wallet
+  }
+  const switched = await switchChain(targetChainId)
+  if (!switched) {
+    throw new PerpsError(
+      PerpsErrorCode.SDKError,
+      `Wallet chain switch to ${targetChainId} was not completed.`
+    )
+  }
+  const switchedChainId = await getChainId(switched)
+  if (switchedChainId !== targetChainId) {
+    throw new PerpsError(
+      PerpsErrorCode.SDKError,
+      `Wallet is on chain ${switchedChainId} but chain ${targetChainId} is required to sign.`
+    )
+  }
+  return switched
+}

package/src/version.ts

@@ -1,2 +1,2 @@
 export const name = '@lifi/perps-sdk'
-export const version = '1.6.0'
+export const version = '2.1.0'