@lifi/perps-sdk-provider-ondo 20.1.0 → 20.2.1

package/src/accountConfig.ts

@@ -94,6 +94,7 @@ function projectOndoDescriptor(
     case ActionType.META_ACCEPT_TERMS:
     case ActionType.META_ONBOARD:
     case ActionType.META_CREATE_REFERRAL_CODE:
+    case ActionType.ADD_WITHDRAWAL_ADDRESS:
     case ActionType.SYNC_FEE_ATTRIBUTION:
       throw new PerpsError(
         PerpsErrorCode.SDKError,

package/src/auth/OndoApiKeyStore.ts

@@ -1,5 +1,6 @@
 import { readValidatedRecord, type StorageAdapter } from '@lifi/perps-sdk'
 import type { Address } from 'viem'
+import { ONDO_API_KEY_SCOPES } from '../constants.js'
 import type { OndoApiKey } from '../types/auth.js'
 
 // Keys are namespaced by environment host as well as address: a production
@@ -29,6 +30,10 @@ export const isOndoApiKey = (value: unknown): value is OndoApiKey => {
   )
 }
 
+/** @internal */
+export const hasOndoApiKeyScopes = (apiKey: OndoApiKey): boolean =>
+  ONDO_API_KEY_SCOPES.every((scope) => apiKey.scopes.includes(scope))
+
 /**
  * Persists the Ondo trading API key per wallet address and environment via a
  * `StorageAdapter`, mirroring {@link OndoTokenStore}. The record holds the

package/src/auth/signActions.ts

@@ -8,12 +8,13 @@ import type {
   SiweActionStep,
 } from '@lifi/perps-types'
 import { ActionType, PerpsErrorCode, SigningMethod } from '@lifi/perps-types'
-import type { Address } from 'viem'
+import { type Address, getAddress } from 'viem'
 import {
   ONDO_API_KEY_NAME,
   ONDO_API_KEY_SCOPES,
   ONDO_PRIVACY_VERSION,
   ONDO_TERMS_VERSION,
+  ONDO_WITHDRAWAL_ADDRESS_LABEL,
 } from '../constants.js'
 import type { OndoApiKey } from '../types/auth.js'
 import type { OndoApiKeyInfo, OndoCreatedApiKey } from '../types/wire.js'
@@ -26,9 +27,16 @@ import {
   buildOndoProvisionPayload,
   listOndoDepositAddress,
 } from '../utils/depositAddress.js'
-import { completeSiweLogin } from './completeSiweLogin.js'
+import {
+  completeSiweLogin,
+  type OndoSiweChallenge,
+} from './completeSiweLogin.js'
 import { hmacSignRequest } from './hmac.js'
-import { isOndoApiKey, type OndoApiKeyStore } from './OndoApiKeyStore.js'
+import {
+  hasOndoApiKeyScopes,
+  isOndoApiKey,
+  type OndoApiKeyStore,
+} from './OndoApiKeyStore.js'
 import type { OndoTokenStore } from './OndoTokenStore.js'
 
 /** @internal */
@@ -45,6 +53,18 @@ const isSiweStep = (step: ActionStep): step is SiweActionStep => 'siwe' in step
 const isSessionStep = (step: ActionStep): step is SessionActionStep =>
   'session' in step
 
+const requireUserWallet = (ctx: SignActionsContext | undefined) => {
+  const userWallet = ctx?.userWallet
+  if (userWallet === undefined) {
+    throw new PerpsError(
+      PerpsErrorCode.SDKError,
+      'Ondo SIWE login requires the user wallet. Pass `userWallet` when ' +
+        'creating the perps client.'
+    )
+  }
+  return userWallet
+}
+
 const hasRequest = (
   step: ActionStep
 ): step is Extract<ActionStep, { request: unknown }> => 'request' in step
@@ -64,7 +84,7 @@ function toStoredApiKey(created: OndoCreatedApiKey): OndoApiKey {
     createdAt: created.createdAt,
     scopes: created.scopes,
   }
-  if (!isOndoApiKey(record)) {
+  if (!isOndoApiKey(record) || !hasOndoApiKeyScopes(record)) {
     throw new OndoApiError(
       `Ondo POST /v1/api_keys returned an unusable key record: ${JSON.stringify({ ...created, secretKey: '[REDACTED]' }).slice(0, 200)}`
     )
@@ -72,17 +92,45 @@ function toStoredApiKey(created: OndoCreatedApiKey): OndoApiKey {
   return record
 }
 
+const pendingApiKeys = new WeakMap<
+  OndoApiKeyStore,
+  Map<string, Promise<OndoApiKey>>
+>()
+
 /**
- * Fetch the stored trading API key. When no valid key exists, list the venue
- * registry and reclaim the oldest LI.FI-owned slot if the account is at
- * capacity. The replacement secret is stored immediately after creation.
+ * Fetch the stored trading API key, or create one. Concurrent calls for one
+ * address share one creation, so the venue never holds a duplicate key.
  */
-async function ensureApiKey(
+function ensureApiKey(
+  deps: OndoSignActionsDeps,
+  address: Address
+): Promise<OndoApiKey> {
+  const pending = pendingApiKeys.get(deps.apiKeyStore) ?? new Map()
+  pendingApiKeys.set(deps.apiKeyStore, pending)
+  const pendingKey = address.toLowerCase()
+  const inFlight = pending.get(pendingKey)
+  if (inFlight !== undefined) {
+    return inFlight
+  }
+  const request = resolveApiKey(deps, address).finally(() => {
+    pending.delete(pendingKey)
+  })
+  pending.set(pendingKey, request)
+  return request
+}
+
+/**
+ * Return the stored key when it holds every required scope. Otherwise list
+ * the venue registry, revoke the stored key when the venue still lists it,
+ * and reclaim the oldest LI.FI-owned slot if the account is at capacity. The
+ * replacement secret is stored immediately after creation.
+ */
+async function resolveApiKey(
   deps: OndoSignActionsDeps,
   address: Address
 ): Promise<OndoApiKey> {
   const existing = await deps.apiKeyStore.get(address)
-  if (existing !== null) {
+  if (existing !== null && hasOndoApiKeyScopes(existing)) {
     return existing
   }
   const token = await deps.tokenStore.get(address)
@@ -91,10 +139,22 @@ async function ensureApiKey(
       `No valid Ondo session token stored for ${address}. Run the SIWE login first.`
     )
   }
-  const configuredKeys =
+  const listedKeys =
     (await deps.client.get<OndoApiKeyInfo[] | null>('/v1/api_keys', {
       authToken: token.token,
     })) ?? []
+  const superseded =
+    existing === null
+      ? undefined
+      : listedKeys.find((key) => key.keyId === existing.keyId)
+  if (superseded !== undefined) {
+    await deps.client.send(
+      'DELETE',
+      `/v1/api_keys/${encodeURIComponent(superseded.keyId)}`,
+      { authToken: token.token }
+    )
+  }
+  const configuredKeys = listedKeys.filter((key) => key !== superseded)
   if (configuredKeys.length >= ONDO_API_KEY_LIMIT) {
     let staleKey: OndoApiKeyInfo | undefined
     let staleKeyCreatedAtMs = Number.POSITIVE_INFINITY
@@ -139,6 +199,45 @@ async function ensureApiKey(
   return apiKey
 }
 
+/**
+ * Add the login address to the Ondo address book, the only withdrawal
+ * destination the SDK offers. Ondo requires a wallet signature over its own
+ * challenge for each new entry.
+ */
+async function addWithdrawalAddress(
+  deps: OndoSignActionsDeps,
+  address: Address,
+  ctx: SignActionsContext | undefined
+): Promise<void> {
+  const token = await deps.tokenStore.get(address)
+  if (token === null) {
+    throw new OndoSessionExpiredError(
+      `No valid Ondo session token stored for ${address}. Run the SIWE login first.`
+    )
+  }
+  const userWallet = requireUserWallet(ctx)
+  const withdrawalAddress = getAddress(address)
+  const challenge = await deps.client.post<OndoSiweChallenge>(
+    '/v1/auth/erc-4361/address_book/get_challenge',
+    { walletAddress: withdrawalAddress, chainId: '1', withdrawalAddress },
+    { authToken: token.token }
+  )
+  const signature = await userWallet.signMessage({
+    account: userWallet.account,
+    message: challenge.message,
+  })
+  await deps.client.post(
+    '/v1/auth/erc-4361/address_book/complete_challenge',
+    {
+      id: challenge.id,
+      signature,
+      withdrawalAddress,
+      addressLabel: ONDO_WITHDRAWAL_ADDRESS_LABEL,
+    },
+    { authToken: token.token }
+  )
+}
+
 /**
  * Execute a backend-authored session request directly against the venue with
  * the stored session JWT. The pre-serialized wire body is parsed back to an
@@ -191,14 +290,7 @@ export async function ondoSignActions(
 ): Promise<SignedActionStep[]> {
   switch (method) {
     case SigningMethod.SIWE: {
-      const userWallet = ctx?.userWallet
-      if (userWallet === undefined) {
-        throw new PerpsError(
-          PerpsErrorCode.SDKError,
-          'Ondo SIWE login requires the user wallet. Pass `userWallet` when ' +
-            'creating the perps client.'
-        )
-      }
+      const userWallet = requireUserWallet(ctx)
       for (const step of steps) {
         if (!isSiweStep(step)) {
           throw new PerpsError(
@@ -303,6 +395,9 @@ export async function ondoSignActions(
           case ActionType.REGISTER_API_KEY:
             await ensureApiKey(deps, address)
             break
+          case ActionType.ADD_WITHDRAWAL_ADDRESS:
+            await addWithdrawalAddress(deps, address, ctx)
+            break
           default:
             throw new PerpsError(
               PerpsErrorCode.SDKError,

package/src/constants.ts

@@ -45,11 +45,12 @@ export const ONDO_BASE_FEE_TIER = {
 export const ONDO_API_KEY_NAME = 'lifi-perps'
 
 /**
- * Scopes requested when minting the trading API key.
+ * Scopes requested when creating the trading API key. `POST /v1/withdraw`
+ * needs `transfer`; the SDK replaces a stored key without every scope.
  *
  * @public
  */
-export const ONDO_API_KEY_SCOPES = ['trade']
+export const ONDO_API_KEY_SCOPES = ['trade', 'transfer']
 
 /**
  * Terms-of-Service version accepted at first login. Venue-owned; current value.
@@ -64,3 +65,10 @@ export const ONDO_TERMS_VERSION = 1
  * @public
  */
 export const ONDO_PRIVACY_VERSION = 1
+
+/**
+ * Label Ondo shows on the address book entry the SDK adds for withdrawals.
+ *
+ * @public
+ */
+export const ONDO_WITHDRAWAL_ADDRESS_LABEL = 'LI.FI'

package/src/types/wire.ts

@@ -308,8 +308,14 @@ export interface OndoWalletDeposit {
   logIndex?: string
 }
 
-/** @public */
+/**
+ * The REST spec lists the lowercase values. The live API sends the
+ * `WITHDRAWAL_`-prefixed values.
+ * @public
+ */
 export type OndoWithdrawalStatus =
+  | 'WITHDRAWAL_PENDING'
+  | 'WITHDRAWAL_SUCCESS'
   | 'complete'
   | 'failure'
   | 'pending'
@@ -337,6 +343,22 @@ export interface OndoWalletWithdrawal {
   from?: OndoAccountWalletKey
 }
 
+/** Mirrors Ondo's `AddressBookEntry` (one `GET /v1/wallet/address_book` row). @public */
+export interface OndoAddressBookEntry {
+  withdrawalAddress: string
+  label: string
+  lastUpdated: string
+}
+
+/**
+ * Mirrors Ondo's `AddressBookResult`. The venue sends `null` for an empty
+ * address book.
+ * @public
+ */
+export interface OndoAddressBookResult {
+  addressBook: OndoAddressBookEntry[] | null
+}
+
 /**
  * One side of an Ondo value movement: an account id plus which of that
  * account's two wallets held the value.

package/src/utils/apiClient.ts

@@ -8,7 +8,7 @@ import {
 import { PerpsErrorCode } from '@lifi/perps-types'
 import type { OndoGenericResponse } from '../types/auth.js'
 import type { OndoPageInfo } from '../types/wire.js'
-import { ondoErrorCodeFromBody } from './ondoErrorCode.js'
+import { ondoErrorFromBody } from './ondoErrorCode.js'
 
 /** @internal */
 export type ApiParams = Record<string, string | number | boolean>
@@ -246,12 +246,12 @@ export class OndoApiClient {
       )
     }
     if (isGenericResponse(data) && !data.success) {
-      const bodyCode = ondoErrorCodeFromBody(data.error_code)
-      if (bodyCode !== undefined) {
+      const bodyError = ondoErrorFromBody(data.error_code)
+      if (bodyError !== undefined) {
         throw new OndoApiError(
-          `Ondo API error for ${path}: ${data.error_code} — ${data.error ?? 'no error message'}`,
+          `Ondo API error for ${path}: ${data.error_code} — ${bodyError.message ?? data.error ?? 'no error message'}`,
           data.error_code,
-          bodyCode
+          bodyError.code
         )
       }
     }

package/src/utils/mapActivity.ts

@@ -137,6 +137,8 @@ export const mapDepositActivity = (
 }
 
 const SETTLING_WITHDRAWAL_STATUSES = new Set<string>([
+  'WITHDRAWAL_PENDING',
+  'WITHDRAWAL_SUCCESS',
   'complete',
   'pending',
   'unknown',

package/src/utils/ondoErrorCode.ts

@@ -1,16 +1,70 @@
 import { PerpsErrorCode } from '@lifi/perps-types'
 
+/**
+ * The classification of an Ondo envelope `error_code`. `message` replaces the
+ * venue's own text when that text does not tell the caller what to do.
+ */
+export interface OndoBodyError {
+  code: PerpsErrorCode
+  message?: string
+}
+
 /** Ondo envelope `error_code` values that name a rejection a `PerpsErrorCode` describes. */
-const ONDO_BODY_ERROR_CODES: ReadonlyMap<string, PerpsErrorCode> = new Map([
-  ['insufficient_margin', PerpsErrorCode.InsufficientMargin],
-  ['clientOrderID_collision', PerpsErrorCode.NonceAlreadyUsed],
+const ONDO_BODY_ERRORS: ReadonlyMap<string, OndoBodyError> = new Map([
+  ['insufficient_margin', { code: PerpsErrorCode.InsufficientMargin }],
+  ['clientOrderID_collision', { code: PerpsErrorCode.NonceAlreadyUsed }],
+  [
+    'bad_label',
+    {
+      code: PerpsErrorCode.ValidationError,
+      message: 'Ondo rejected the withdrawal address label.',
+    },
+  ],
+  [
+    'empty_label',
+    {
+      code: PerpsErrorCode.ValidationError,
+      message: 'Ondo requires a withdrawal address label.',
+    },
+  ],
+  [
+    'bad_withdrawal_address',
+    {
+      code: PerpsErrorCode.ValidationError,
+      message: 'Ondo rejected the withdrawal address as not valid.',
+    },
+  ],
+  [
+    'internal_withdrawal_address',
+    {
+      code: PerpsErrorCode.ValidationError,
+      message:
+        'Ondo does not accept an Ondo deposit address as a withdrawal address.',
+    },
+  ],
+  [
+    'challenge_not_found',
+    {
+      code: PerpsErrorCode.NonceExpired,
+      message:
+        'The Ondo address book challenge is unknown or expired. Request a new challenge.',
+    },
+  ],
+  [
+    'withdrawal_address_not_found',
+    {
+      code: PerpsErrorCode.SetupRequired,
+      message:
+        'The withdrawal destination is not in the Ondo address book. Add the withdrawal address first.',
+    },
+  ],
 ])
 
 /**
- * Maps an Ondo envelope `error_code` to the `PerpsErrorCode` it names. Returns
- * `undefined` for every other code so the status-driven layer decides.
+ * Classifies an Ondo envelope `error_code`. Returns `undefined` for every other
+ * code so the status-driven layer decides.
  */
-export const ondoErrorCodeFromBody = (
+export const ondoErrorFromBody = (
   errorCode: string | undefined
-): PerpsErrorCode | undefined =>
-  errorCode === undefined ? undefined : ONDO_BODY_ERROR_CODES.get(errorCode)
+): OndoBodyError | undefined =>
+  errorCode === undefined ? undefined : ONDO_BODY_ERRORS.get(errorCode)