@sip-protocol/react 0.1.0

package/src/hooks/use-sip.ts

@@ -0,0 +1,188 @@
+import { useState, useCallback, useContext } from 'react'
+import { SIP, type SIPConfig } from '@sip-protocol/sdk'
+import { useSIPContext } from '../providers/sip-provider'
+
+/**
+ * Return type for useSIP hook
+ */
+export interface UseSIPReturn {
+  /** SIP client instance (null if not initialized or no provider) */
+  client: SIP | null
+  /** Whether the client is ready to use */
+  isReady: boolean
+  /** Error during initialization (if any) */
+  error: Error | null
+  /** Manually initialize the SIP client (only for standalone usage) */
+  initialize: (config: SIPConfig) => Promise<void>
+}
+
+/**
+ * useSIP - Main hook for accessing SIP client
+ *
+ * Provides access to the SIP client instance from SIPProvider, along with
+ * initialization state and error handling. Can also be used standalone without
+ * a provider by calling `initialize()`.
+ *
+ * **Usage with SIPProvider (recommended):**
+ * ```tsx
+ * import { SIPProvider, useSIP } from '@sip-protocol/react'
+ *
+ * function App() {
+ *   return (
+ *     <SIPProvider config={{ network: 'testnet' }}>
+ *       <MyComponent />
+ *     </SIPProvider>
+ *   )
+ * }
+ *
+ * function MyComponent() {
+ *   const { client, isReady } = useSIP()
+ *
+ *   if (!isReady || !client) {
+ *     return <div>Loading...</div>
+ *   }
+ *
+ *   // Use client.createIntent(), client.getQuotes(), etc.
+ * }
+ * ```
+ *
+ * **Standalone usage (without provider):**
+ * ```tsx
+ * function MyComponent() {
+ *   const { client, isReady, initialize, error } = useSIP()
+ *
+ *   useEffect(() => {
+ *     initialize({ network: 'testnet' }).catch(console.error)
+ *   }, [])
+ *
+ *   if (error) {
+ *     return <div>Error: {error.message}</div>
+ *   }
+ *
+ *   if (!isReady || !client) {
+ *     return <div>Initializing...</div>
+ *   }
+ *
+ *   return <div>Ready!</div>
+ * }
+ * ```
+ *
+ * @returns Object with client, isReady, error, and initialize function
+ *
+ * @example Basic usage with provider
+ * ```tsx
+ * import { useSIP } from '@sip-protocol/react'
+ *
+ * function MyComponent() {
+ *   const { client, isReady } = useSIP()
+ *
+ *   if (!isReady || !client) {
+ *     return <div>Loading...</div>
+ *   }
+ *
+ *   // Use client methods
+ *   const handleCreateIntent = async () => {
+ *     const intent = await client.createIntent({ ... })
+ *   }
+ * }
+ * ```
+ *
+ * @example With error handling
+ * ```tsx
+ * function MyComponent() {
+ *   const { client, isReady, error } = useSIP()
+ *
+ *   if (error) {
+ *     return <div>Failed to initialize: {error.message}</div>
+ *   }
+ *
+ *   if (!isReady || !client) {
+ *     return <div>Initializing SIP client...</div>
+ *   }
+ *
+ *   return <div>Ready to use SIP!</div>
+ * }
+ * ```
+ *
+ * @example Standalone initialization
+ * ```tsx
+ * function MyComponent() {
+ *   const { client, isReady, initialize } = useSIP()
+ *
+ *   const handleInit = async () => {
+ *     try {
+ *       await initialize({
+ *         network: 'mainnet',
+ *         mode: 'production',
+ *         intentsAdapter: { jwtToken: 'xxx' }
+ *       })
+ *     } catch (err) {
+ *       console.error('Init failed:', err)
+ *     }
+ *   }
+ *
+ *   return (
+ *     <button onClick={handleInit} disabled={isReady}>
+ *       {isReady ? 'Initialized' : 'Initialize SIP'}
+ *     </button>
+ *   )
+ * }
+ * ```
+ */
+export function useSIP(): UseSIPReturn {
+  // State for standalone usage (without provider)
+  const [standaloneClient, setStandaloneClient] = useState<SIP | null>(null)
+  const [standaloneReady, setStandaloneReady] = useState(false)
+  const [standaloneError, setStandaloneError] = useState<Error | null>(null)
+
+  // Try to get context from SIPProvider
+  let providerContext
+  try {
+    providerContext = useSIPContext()
+  } catch {
+    // Not inside SIPProvider, use standalone mode
+    providerContext = null
+  }
+
+  const standaloneInitialize = useCallback(async (config: SIPConfig) => {
+    // Prevent re-initialization if already initialized
+    if (standaloneClient && standaloneReady) {
+      console.warn('SIP client already initialized. Call will be ignored.')
+      return
+    }
+
+    try {
+      setStandaloneError(null)
+      setStandaloneReady(false)
+
+      const newClient = new SIP(config)
+      setStandaloneClient(newClient)
+      setStandaloneReady(true)
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error(String(err))
+      setStandaloneError(error)
+      setStandaloneReady(false)
+      throw error
+    }
+  }, [standaloneClient, standaloneReady])
+
+  // If we have a provider context, use it
+  if (providerContext) {
+    return {
+      client: providerContext.client,
+      isReady: true, // Provider always provides ready client
+      error: null, // Provider throws on error, doesn't expose it
+      initialize: async () => {
+        console.warn('initialize() called but SIPProvider is already providing a client. This call will be ignored.')
+      },
+    }
+  }
+
+  // Otherwise, return standalone state
+  return {
+    client: standaloneClient,
+    isReady: standaloneReady,
+    error: standaloneError,
+    initialize: standaloneInitialize,
+  }
+}

package/src/hooks/use-stealth-address.ts

@@ -0,0 +1,184 @@
+import { useState, useEffect, useCallback } from 'react'
+import {
+  generateStealthMetaAddress,
+  generateStealthAddress,
+  generateEd25519StealthMetaAddress,
+  generateEd25519StealthAddress,
+  encodeStealthMetaAddress,
+  isEd25519Chain,
+} from '@sip-protocol/sdk'
+import type { ChainId } from '@sip-protocol/types'
+
+/**
+ * useStealthAddress - Generate and manage stealth addresses
+ *
+ * @remarks
+ * This hook handles stealth address generation for privacy-preserving transactions.
+ * It automatically generates a meta-address on mount and allows regeneration of
+ * one-time stealth addresses from that meta-address.
+ *
+ * Features:
+ * - Auto-generates meta-address for the specified chain
+ * - Generates one-time stealth addresses
+ * - Supports both secp256k1 (EVM) and ed25519 (Solana/NEAR) chains
+ * - Copy-to-clipboard functionality
+ * - Loading state management
+ *
+ * @param chain - Target blockchain (determines curve type and address format)
+ *
+ * @example
+ * ```tsx
+ * import { useStealthAddress } from '@sip-protocol/react'
+ *
+ * function ReceivePayment() {
+ *   const {
+ *     metaAddress,
+ *     stealthAddress,
+ *     isGenerating,
+ *     regenerate,
+ *     copyToClipboard,
+ *   } = useStealthAddress('ethereum')
+ *
+ *   return (
+ *     <div>
+ *       <p>Share this: {metaAddress}</p>
+ *       <p>One-time address: {stealthAddress}</p>
+ *       <button onClick={regenerate}>Generate New</button>
+ *       <button onClick={copyToClipboard}>Copy</button>
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
+export function useStealthAddress(chain: ChainId): {
+  metaAddress: string | null
+  stealthAddress: string | null
+  isGenerating: boolean
+  regenerate: () => void
+  copyToClipboard: () => Promise<void>
+} {
+  const [metaAddress, setMetaAddress] = useState<string | null>(null)
+  const [stealthAddress, setStealthAddress] = useState<string | null>(null)
+  const [isGenerating, setIsGenerating] = useState<boolean>(false)
+
+  // Generate meta-address on mount
+  useEffect(() => {
+    let cancelled = false
+
+    setIsGenerating(true)
+
+    // Use setTimeout to make it async and allow state to flush
+    const timer = setTimeout(() => {
+      if (cancelled) return
+
+      try {
+        // Use ed25519 for Solana/NEAR/Aptos/Sui, secp256k1 for others
+        const isEd25519 = isEd25519Chain(chain)
+
+        const metaAddressData = isEd25519
+          ? generateEd25519StealthMetaAddress(chain)
+          : generateStealthMetaAddress(chain)
+
+        const encoded = encodeStealthMetaAddress(metaAddressData.metaAddress)
+        if (cancelled) return
+        setMetaAddress(encoded)
+
+        // Generate initial stealth address from meta-address
+        const stealthData = isEd25519
+          ? generateEd25519StealthAddress(metaAddressData.metaAddress)
+          : generateStealthAddress(metaAddressData.metaAddress)
+
+        if (cancelled) return
+        setStealthAddress(stealthData.stealthAddress.address)
+      } catch (error) {
+        console.error('Failed to generate stealth addresses:', error)
+        if (cancelled) return
+        setMetaAddress(null)
+        setStealthAddress(null)
+      } finally {
+        if (!cancelled) {
+          setIsGenerating(false)
+        }
+      }
+    }, 0)
+
+    return () => {
+      cancelled = true
+      clearTimeout(timer)
+    }
+  }, [chain])
+
+  // Regenerate stealth address from existing meta-address
+  const regenerate = useCallback(() => {
+    if (!metaAddress) {
+      return
+    }
+
+    setIsGenerating(true)
+
+    // Use setTimeout to make it async
+    setTimeout(() => {
+      try {
+        // Parse the meta-address back to object
+        const parts = metaAddress.split(':')
+        if (parts.length < 4) {
+          throw new Error('Invalid meta-address format')
+        }
+
+        const [, chainId, spendingKey, viewingKey] = parts
+        const metaAddressObj = {
+          chain: chainId as ChainId,
+          spendingKey: (spendingKey.startsWith('0x') ? spendingKey : `0x${spendingKey}`) as `0x${string}`,
+          viewingKey: (viewingKey.startsWith('0x') ? viewingKey : `0x${viewingKey}`) as `0x${string}`,
+        }
+
+        // Generate new stealth address
+        const isEd25519 = isEd25519Chain(chain)
+        const stealthData = isEd25519
+          ? generateEd25519StealthAddress(metaAddressObj)
+          : generateStealthAddress(metaAddressObj)
+
+        setStealthAddress(stealthData.stealthAddress.address)
+      } catch (error) {
+        console.error('Failed to regenerate stealth address:', error)
+      } finally {
+        setIsGenerating(false)
+      }
+    }, 0)
+  }, [metaAddress, chain])
+
+  // Copy stealth address to clipboard
+  const copyToClipboard = useCallback(async () => {
+    if (!stealthAddress) {
+      return
+    }
+
+    try {
+      await navigator.clipboard.writeText(stealthAddress)
+    } catch (error) {
+      console.error('Failed to copy to clipboard:', error)
+      // Fallback for older browsers
+      const textArea = document.createElement('textarea')
+      textArea.value = stealthAddress
+      textArea.style.position = 'fixed'
+      textArea.style.left = '-999999px'
+      document.body.appendChild(textArea)
+      textArea.select()
+      try {
+        document.execCommand('copy')
+      } catch (err) {
+        console.error('Fallback copy failed:', err)
+      } finally {
+        document.body.removeChild(textArea)
+      }
+    }
+  }, [stealthAddress])
+
+  return {
+    metaAddress,
+    stealthAddress,
+    isGenerating,
+    regenerate,
+    copyToClipboard,
+  }
+}

package/src/hooks/use-viewing-key.ts

@@ -0,0 +1,190 @@
+import { useState, useCallback } from 'react'
+import type { ViewingKey, EncryptedTransaction } from '@sip-protocol/types'
+import {
+  generateViewingKey as sdkGenerateViewingKey,
+  decryptWithViewing,
+} from '@sip-protocol/sdk'
+
+/**
+ * Auditor share entry
+ */
+interface AuditorShare {
+  auditorId: string
+  viewingKeyHash: string
+  sharedAt: number
+}
+
+/**
+ * useViewingKey - Generate and manage viewing keys for compliance
+ *
+ * @remarks
+ * Hook for managing viewing keys that enable selective disclosure of transaction
+ * details to auditors or regulators while maintaining on-chain privacy.
+ *
+ * Features:
+ * - Generate cryptographically random viewing keys
+ * - Decrypt encrypted transaction data
+ * - Share viewing keys with auditors (tracked in state)
+ * - Hierarchical key derivation via path parameter
+ *
+ * @example Basic usage
+ * ```tsx
+ * import { useViewingKey } from '@sip-protocol/react'
+ *
+ * function CompliancePanel() {
+ *   const { viewingKey, generate, decrypt, share } = useViewingKey()
+ *
+ *   const handleGenerateKey = () => {
+ *     const key = generate('m/0/audit')
+ *     console.log('Generated viewing key:', key.hash)
+ *   }
+ *
+ *   const handleDecrypt = async (encrypted: EncryptedTransaction) => {
+ *     try {
+ *       const data = await decrypt(encrypted)
+ *       console.log('Decrypted amount:', data.amount)
+ *     } catch (e) {
+ *       console.error('Decryption failed - wrong key')
+ *     }
+ *   }
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={handleGenerateKey}>Generate Key</button>
+ *       {viewingKey && <p>Key hash: {viewingKey.hash}</p>}
+ *     </div>
+ *   )
+ * }
+ * ```
+ *
+ * @example Sharing with auditors
+ * ```tsx
+ * function AuditManager() {
+ *   const { viewingKey, generate, share, sharedWith } = useViewingKey()
+ *
+ *   useEffect(() => {
+ *     generate('m/0/compliance')
+ *   }, [])
+ *
+ *   const handleShareWithAuditor = async () => {
+ *     await share('auditor-123')
+ *     console.log('Shared with:', sharedWith)
+ *   }
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={handleShareWithAuditor}>Share with Auditor</button>
+ *       <ul>
+ *         {sharedWith.map(audit => (
+ *           <li key={audit.auditorId}>{audit.auditorId}</li>
+ *         ))}
+ *       </ul>
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
+export function useViewingKey() {
+  const [viewingKey, setViewingKey] = useState<ViewingKey | null>(null)
+  const [sharedWith, setSharedWith] = useState<AuditorShare[]>([])
+
+  /**
+   * Generate a new viewing key
+   *
+   * @param path - Hierarchical derivation path (BIP32-style, defaults to 'm/0')
+   * @returns Generated viewing key
+   *
+   * @example
+   * ```tsx
+   * const key = generate('m/0/audit')
+   * console.log(key.hash) // "0xabc123..."
+   * ```
+   */
+  const generate = useCallback((path?: string): ViewingKey => {
+    const key = sdkGenerateViewingKey(path)
+    setViewingKey(key)
+    setSharedWith([]) // Reset shares when generating new key
+    return key
+  }, [])
+
+  /**
+   * Decrypt encrypted transaction data with the current viewing key
+   *
+   * @param encrypted - Encrypted transaction data
+   * @returns Promise resolving to decrypted transaction details
+   * @throws {Error} If no viewing key is set or decryption fails
+   *
+   * @example
+   * ```tsx
+   * const data = await decrypt(encryptedTransaction)
+   * console.log(`Sender: ${data.sender}`)
+   * console.log(`Amount: ${data.amount}`)
+   * ```
+   */
+  const decrypt = useCallback(
+    async (encrypted: EncryptedTransaction) => {
+      if (!viewingKey) {
+        throw new Error('No viewing key available. Call generate() first.')
+      }
+
+      return decryptWithViewing(encrypted, viewingKey)
+    },
+    [viewingKey],
+  )
+
+  /**
+   * Share viewing key with an auditor (tracked in state)
+   *
+   * @param auditorId - Unique identifier for the auditor
+   * @returns Promise that resolves when sharing is complete
+   * @throws {Error} If no viewing key is set
+   *
+   * @remarks
+   * This function tracks which auditors have been given access to the viewing key.
+   * In a production system, you would:
+   * - Encrypt the viewing key with the auditor's public key
+   * - Store the encrypted key in a database or smart contract
+   * - Send the encrypted key to the auditor via secure channel
+   *
+   * @example
+   * ```tsx
+   * await share('auditor-alice')
+   * await share('auditor-bob')
+   * console.log(sharedWith) // [{ auditorId: 'auditor-alice', ... }, ...]
+   * ```
+   */
+  const share = useCallback(
+    async (auditorId: string): Promise<void> => {
+      if (!viewingKey) {
+        throw new Error('No viewing key available. Call generate() first.')
+      }
+
+      const shareEntry: AuditorShare = {
+        auditorId,
+        viewingKeyHash: viewingKey.hash,
+        sharedAt: Date.now(),
+      }
+
+      setSharedWith(prev => [...prev, shareEntry])
+
+      // In a real implementation:
+      // 1. Encrypt viewing key with auditor's public key
+      // 2. Store encrypted key on-chain or in secure database
+      // 3. Notify auditor via secure channel
+    },
+    [viewingKey],
+  )
+
+  return {
+    /** Current viewing key (null if not generated) */
+    viewingKey,
+    /** List of auditors who have been given access */
+    sharedWith,
+    /** Generate a new viewing key */
+    generate,
+    /** Decrypt encrypted transaction data */
+    decrypt,
+    /** Share viewing key with an auditor */
+    share,
+  }
+}

package/src/index.ts

@@ -0,0 +1,10 @@
+// Provider
+export { SIPProvider, type SIPProviderProps } from './providers/sip-provider'
+
+// Hooks
+export {
+  useSIP,
+  useStealthAddress,
+  usePrivateSwap,
+  useViewingKey,
+} from './hooks'

package/src/providers/sip-provider.tsx

@@ -0,0 +1,50 @@
+import React, { createContext, useContext, useMemo, type ReactNode } from 'react'
+import { SIP, type SIPConfig } from '@sip-protocol/sdk'
+
+interface SIPContextValue {
+  client: SIP
+  config: SIPConfig
+}
+
+const SIPContext = createContext<SIPContextValue | undefined>(undefined)
+
+export interface SIPProviderProps {
+  config: SIPConfig
+  children: ReactNode
+}
+
+/**
+ * SIPProvider wraps your app and provides SIP client instance via context
+ *
+ * @example
+ * ```tsx
+ * import { SIPProvider } from '@sip-protocol/react'
+ *
+ * function App() {
+ *   return (
+ *     <SIPProvider config={{ nearIntents: { apiUrl: '...' } }}>
+ *       <YourApp />
+ *     </SIPProvider>
+ *   )
+ * }
+ * ```
+ */
+export function SIPProvider({ config, children }: SIPProviderProps) {
+  const client = useMemo(() => new SIP(config), [config])
+
+  const value = useMemo(() => ({ client, config }), [client, config])
+
+  return <SIPContext.Provider value={value}>{children}</SIPContext.Provider>
+}
+
+/**
+ * useSIPContext - Internal hook to access SIP context
+ * @internal
+ */
+export function useSIPContext(): SIPContextValue {
+  const context = useContext(SIPContext)
+  if (!context) {
+    throw new Error('useSIPContext must be used within SIPProvider')
+  }
+  return context
+}