@lifi/perps-sdk-provider-ondo 0.0.0 → 1.0.0

package/src/auth/OndoApiKeyStore.ts

@@ -0,0 +1,64 @@
+import { readValidatedRecord, type StorageAdapter } from '@lifi/perps-sdk'
+import type { Address } from 'viem'
+import type { OndoApiKey } from '../types/auth.js'
+
+// Keys are namespaced by environment host as well as address: a production
+// API key is meaningless against the sandbox, and both stores may share one
+// localStorage.
+
+const STORAGE_PREFIX = 'lifi-perps-ondo-apikey'
+
+const isOndoApiKey = (value: unknown): value is OndoApiKey => {
+  if (typeof value !== 'object' || value === null) {
+    return false
+  }
+  const { keyId, apiSecret, name, createdAt, scopes } = value as Record<
+    string,
+    unknown
+  >
+  return (
+    typeof keyId === 'string' &&
+    keyId.length > 0 &&
+    typeof apiSecret === 'string' &&
+    apiSecret.length > 0 &&
+    typeof name === 'string' &&
+    typeof createdAt === 'string' &&
+    Array.isArray(scopes) &&
+    scopes.every((scope) => typeof scope === 'string')
+  )
+}
+
+/**
+ * Persists the Ondo trading API key per wallet address and environment via a
+ * `StorageAdapter`, mirroring {@link OndoTokenStore}. The record holds the
+ * `apiSecret` returned only at creation; a poisoned record reads back as absent
+ * (and is evicted), so callers can treat `null` uniformly as "mint a key".
+ *
+ * @public
+ */
+export class OndoApiKeyStore {
+  private readonly storage: StorageAdapter
+  private readonly host: string
+
+  constructor(storage: StorageAdapter, baseUrl: string) {
+    this.storage = storage
+    this.host = new URL(baseUrl).host
+  }
+
+  private storageKey(address: Address): string {
+    return `${STORAGE_PREFIX}:${this.host}:${address.toLowerCase()}`
+  }
+
+  async get(address: Address): Promise<OndoApiKey | null> {
+    const key = this.storageKey(address)
+    return (await readValidatedRecord(this.storage, key, isOndoApiKey)) ?? null
+  }
+
+  async set(address: Address, apiKey: OndoApiKey): Promise<void> {
+    await this.storage.set(this.storageKey(address), JSON.stringify(apiKey))
+  }
+
+  async remove(address: Address): Promise<void> {
+    await this.storage.remove(this.storageKey(address))
+  }
+}

package/src/auth/hmac.ts

@@ -0,0 +1,45 @@
+/** @internal */
+export interface OndoHmacRequest {
+  /** Milliseconds since epoch; Ondo enforces a 30-second signing window. */
+  timestampMs: number
+  method: string
+  /** Venue-relative path including any query string. */
+  pathWithQuery: string
+  /** Pre-serialized body, signed verbatim; empty for bodyless requests. */
+  body?: string
+}
+
+const encoder = new TextEncoder()
+
+const toHex = (buffer: ArrayBuffer): string =>
+  Array.from(new Uint8Array(buffer))
+    .map((byte) => byte.toString(16).padStart(2, '0'))
+    .join('')
+
+/**
+ * Compute Ondo's per-request HMAC-SHA256 signature, hex-encoded. The signed
+ * message concatenates timestamp, upper-cased method, path-with-query, and the
+ * verbatim body with no separators.
+ *
+ * @param apiSecret - the API key's secret, used as the HMAC key.
+ * @internal
+ */
+export async function hmacSignRequest(
+  apiSecret: string,
+  request: OndoHmacRequest
+): Promise<string> {
+  const message = `${request.timestampMs}${request.method.toUpperCase()}${request.pathWithQuery}${request.body ?? ''}`
+  const key = await crypto.subtle.importKey(
+    'raw',
+    encoder.encode(apiSecret),
+    { name: 'HMAC', hash: 'SHA-256' },
+    false,
+    ['sign']
+  )
+  const signature = await crypto.subtle.sign(
+    'HMAC',
+    key,
+    encoder.encode(message)
+  )
+  return toHex(signature)
+}

package/src/auth/index.ts

@@ -4,9 +4,10 @@ export {
   completeSiweLogin,
   type OndoSiweChallenge,
 } from './completeSiweLogin.js'
+export { hmacSignRequest, type OndoHmacRequest } from './hmac.js'
+export { OndoApiKeyStore } from './OndoApiKeyStore.js'
 export { OndoTokenStore } from './OndoTokenStore.js'
 export {
-  executeOndoRestCallActions,
   type OndoSignActionsDeps,
   ondoSignActions,
 } from './signActions.js'

package/src/auth/signActions.ts

@@ -1,43 +1,90 @@
 import { PerpsError, type SignActionsContext } from '@lifi/perps-sdk'
 import type {
-  ActionResult,
   ActionStep,
-  RestCallSignedActionStep,
+  HmacSignedActionStep,
+  SessionActionStep,
   SignedActionStep,
   SiweActionStep,
 } from '@lifi/perps-types'
-import { PerpsErrorCode, SigningMethod } from '@lifi/perps-types'
+import { ActionType, PerpsErrorCode, SigningMethod } from '@lifi/perps-types'
 import type { Address } from 'viem'
+import {
+  ONDO_API_KEY_NAME,
+  ONDO_API_KEY_SCOPES,
+  ONDO_PRIVACY_VERSION,
+  ONDO_TERMS_VERSION,
+} from '../constants.js'
+import type { OndoApiKey } from '../types/auth.js'
 import {
   type OndoApiClient,
-  type OndoHttpMethod,
   OndoSessionExpiredError,
 } from '../utils/apiClient.js'
 import { completeSiweLogin } from './completeSiweLogin.js'
+import { hmacSignRequest } from './hmac.js'
+import type { OndoApiKeyStore } from './OndoApiKeyStore.js'
 import type { OndoTokenStore } from './OndoTokenStore.js'
 
 /** @internal */
 export interface OndoSignActionsDeps {
   client: OndoApiClient
   tokenStore: OndoTokenStore
+  apiKeyStore: OndoApiKeyStore
 }
 
 const isSiweStep = (step: ActionStep): step is SiweActionStep => 'siwe' in step
 
+const isSessionStep = (step: ActionStep): step is SessionActionStep =>
+  'session' in step
+
 const hasRequest = (
   step: ActionStep
 ): step is Extract<ActionStep, { request: unknown }> => 'request' in step
 
+/**
+ * Fetch the stored trading API key, minting one on first use. Minting is
+ * JWT-authorized (`POST /v1/api_keys`); the returned record — including the
+ * `apiSecret` the venue reveals only once — is stored immediately. An absent
+ * session throws {@link OndoSessionExpiredError} so callers re-run SIWE login.
+ */
+async function ensureApiKey(
+  deps: OndoSignActionsDeps,
+  address: Address
+): Promise<OndoApiKey> {
+  const existing = await deps.apiKeyStore.get(address)
+  if (existing !== null) {
+    return existing
+  }
+  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 apiKey = await deps.client.post<OndoApiKey>(
+    '/v1/api_keys',
+    { name: ONDO_API_KEY_NAME, scopes: ONDO_API_KEY_SCOPES },
+    { authToken: token.token }
+  )
+  await deps.apiKeyStore.set(address, apiKey)
+  return apiKey
+}
+
 /**
  * Ondo's `signActions` arms.
  *
- * `SIWE` signs the backend-built ERC-4361 challenge with the user's wallet
- * and completes the login directly against Ondo — the returned session JWT is
+ * `SIWE` signs the backend-built ERC-4361 challenge with the user's wallet and
+ * completes the login directly against Ondo — the returned session JWT is
  * persisted in the token store and never transits the LI.FI backend.
  *
- * `AUTH_TOKEN` attaches the stored session JWT as an `Authorization: Bearer`
- * header on each REST-call step; an absent or expired token throws
- * {@link OndoSessionExpiredError} so callers re-run the SIWE login.
+ * `SESSION` executes client-only setup steps directly against the venue with
+ * the stored session token, keyed on the step's action — the marker steps
+ * carry no request material by design. Returns no signed steps, so
+ * `executeAction` is skipped.
+ *
+ * `HMAC` computes a per-request HMAC-SHA256 signature over each request step
+ * from the client-held API key (minting one on first use), attaching the
+ * `hmac` material. The signed step rides the normal `executeAction` path; the
+ * API secret itself never leaves the client.
  *
  * @public
  */
@@ -77,84 +124,86 @@ export async function ondoSignActions(
       return signed
     }
 
-    case SigningMethod.AUTH_TOKEN: {
-      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.`
-        )
-      }
-      return steps.map((step): RestCallSignedActionStep => {
-        if (!hasRequest(step)) {
+    case SigningMethod.HMAC: {
+      const apiKey = await ensureApiKey(deps, address)
+      return Promise.all(
+        steps.map(async (step): Promise<HmacSignedActionStep> => {
+          if (!hasRequest(step)) {
+            throw new PerpsError(
+              PerpsErrorCode.SDKError,
+              `Ondo received a step without a request ('${step.action}') under the hmac signing method.`
+            )
+          }
+          // Stamped immediately before executeAction; Ondo enforces a 30s window.
+          const timestampMs = Date.now()
+          const signature = await hmacSignRequest(apiKey.apiSecret, {
+            timestampMs,
+            method: step.request.method,
+            pathWithQuery: step.request.path,
+            body: step.request.body,
+          })
+          return {
+            action: step.action,
+            request: step.request,
+            hmac: {
+              keyId: apiKey.keyId,
+              timestampMs,
+              signature,
+            },
+          }
+        })
+      )
+    }
+
+    case SigningMethod.SESSION: {
+      for (const step of steps) {
+        if (!isSessionStep(step)) {
           throw new PerpsError(
             PerpsErrorCode.SDKError,
-            `Ondo received a non-REST step ('${step.action}') under the AUTH_TOKEN signing method.`
+            `Ondo received a non-session step ('${step.action}') under the session signing method.`
           )
         }
-        return {
-          action: step.action,
-          request: step.request,
-          headers: { Authorization: `Bearer ${token.token}` },
+        switch (step.action) {
+          case ActionType.ACCEPT_PROVIDER_TERMS: {
+            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.`
+              )
+            }
+            await deps.client.post(
+              '/v1/agreement',
+              {
+                termsVersion: ONDO_TERMS_VERSION,
+                privacyVersion: ONDO_PRIVACY_VERSION,
+              },
+              { authToken: token.token }
+            )
+            if (token.newAccount) {
+              await deps.tokenStore.set(address, {
+                ...token,
+                newAccount: false,
+              })
+            }
+            break
+          }
+          case ActionType.REGISTER_API_KEY:
+            await ensureApiKey(deps, address)
+            break
+          default:
+            throw new PerpsError(
+              PerpsErrorCode.SDKError,
+              `Ondo has no session-step executor for action '${step.action}'.`
+            )
         }
-      })
+      }
+      return []
     }
 
     default:
       throw new PerpsError(
         PerpsErrorCode.SDKError,
-        `Ondo does not sign via '${method}'. Supported methods: siwe, authToken.`
+        `Ondo does not sign via '${method}'. Supported methods: siwe, hmac, session.`
       )
   }
 }
-
-/**
- * Execute credential-bearing REST-call steps directly against Ondo,
- * sequentially — later steps in a batch may depend on earlier ones (e.g.
- * leverage update before order placement), so after the first failure the
- * remainder is skipped rather than executed out of order.
- *
- * @public
- */
-export async function executeOndoRestCallActions(
-  client: OndoApiClient,
-  steps: RestCallSignedActionStep[]
-): Promise<ActionResult[]> {
-  const results: ActionResult[] = []
-  let failed = false
-  for (const step of steps) {
-    if (failed) {
-      results.push({
-        action: step.action,
-        success: false,
-        error: 'Skipped: a preceding step in the batch failed.',
-      })
-      continue
-    }
-    try {
-      const result = await client.send<unknown>(
-        step.request.method as OndoHttpMethod,
-        step.request.path,
-        { body: step.request.body, headers: step.headers }
-      )
-      const orderId =
-        typeof result === 'object' &&
-        result !== null &&
-        typeof (result as { orderId?: unknown }).orderId === 'string'
-          ? (result as { orderId: string }).orderId
-          : undefined
-      results.push({
-        action: step.action,
-        success: true,
-        ...(orderId === undefined ? {} : { orderId }),
-      })
-    } catch (err) {
-      failed = true
-      results.push({
-        action: step.action,
-        success: false,
-        error: err instanceof Error ? err.message : String(err),
-      })
-    }
-  }
-  return results
-}

package/src/constants.ts

@@ -36,3 +36,31 @@ export const ONDO_BASE_FEE_TIER = {
   maker: '0.0002',
   taker: '0.0005',
 }
+
+/**
+ * Name applied to the trading API key the SDK mints on first trading use.
+ *
+ * @public
+ */
+export const ONDO_API_KEY_NAME = 'lifi-perps'
+
+/**
+ * Scopes requested when minting the trading API key.
+ *
+ * @public
+ */
+export const ONDO_API_KEY_SCOPES = ['trade']
+
+/**
+ * Terms-of-Service version accepted at first login. Venue-owned; current value.
+ *
+ * @public
+ */
+export const ONDO_TERMS_VERSION = 1
+
+/**
+ * Privacy-policy version accepted at first login. Venue-owned; current value.
+ *
+ * @public
+ */
+export const ONDO_PRIVACY_VERSION = 1

package/src/types/auth.ts

@@ -30,3 +30,20 @@ export interface OndoAuthToken {
   /** True when this login created the Ondo account. */
   newAccount: boolean
 }
+
+/**
+ * An Ondo trading API key, as returned by `POST /v1/api_keys` and persisted
+ * client-side. `apiSecret` is the HMAC key returned only at creation, so the
+ * whole record is stored immediately and never re-fetched.
+ *
+ * @public
+ */
+export interface OndoApiKey {
+  keyId: string
+  /** HMAC secret; returned only at creation and kept strictly userland. */
+  apiSecret: string
+  name: string
+  /** ISO-8601 creation timestamp, as returned by the venue. */
+  createdAt: string
+  scopes: string[]
+}

package/src/utils/apiClient.ts

@@ -146,10 +146,8 @@ export class OndoApiClient {
   }
 
   /**
-   * Arbitrary-method request with caller-prebuilt headers — the execution
-   * surface for credential-bearing `RestCallSignedActionStep`s, whose
-   * `Authorization` header is attached by `signActions` from the token store.
-   * Only GET is ever retried; writes are not idempotent.
+   * Arbitrary-method request with caller-prebuilt headers. Only GET is ever
+   * retried; writes are not idempotent.
    */
   async send<T>(
     method: OndoHttpMethod,