@sip-protocol/react-native 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,442 @@
+export { Asset, ChainId, HexString, PrivacyLevel } from '@sip-protocol/types';
+
+/**
+ * useStealthAddress - Mobile-optimized stealth address hook
+ *
+ * React Native version with secure storage and native clipboard support.
+ *
+ * @example
+ * ```tsx
+ * import { useStealthAddress } from '@sip-protocol/react-native'
+ *
+ * function ReceiveScreen() {
+ *   const {
+ *     metaAddress,
+ *     stealthAddress,
+ *     isGenerating,
+ *     regenerate,
+ *     copyToClipboard,
+ *     saveToKeychain,
+ *   } = useStealthAddress('solana')
+ *
+ *   return (
+ *     <View>
+ *       <Text>Share: {metaAddress}</Text>
+ *       <TouchableOpacity onPress={copyToClipboard}>
+ *         <Text>Copy</Text>
+ *       </TouchableOpacity>
+ *       <TouchableOpacity onPress={saveToKeychain}>
+ *         <Text>Save Securely</Text>
+ *       </TouchableOpacity>
+ *     </View>
+ *   )
+ * }
+ * ```
+ */
+/**
+ * Supported chain IDs (matches @sip-protocol/types ChainId)
+ */
+type SupportedChainId = 'ethereum' | 'solana' | 'near' | 'bitcoin' | 'polygon' | 'arbitrum' | 'optimism' | 'base' | 'bsc' | 'avalanche' | 'cosmos' | 'aptos' | 'sui' | 'polkadot' | 'tezos';
+/**
+ * Options for useStealthAddress hook
+ */
+interface UseStealthAddressOptions {
+    /** Auto-save to secure storage on generation */
+    autoSave?: boolean;
+    /** Require biometrics to access stored keys */
+    requireBiometrics?: boolean;
+    /** Wallet identifier for storage (default: 'default') */
+    walletId?: string;
+}
+/**
+ * Return type for useStealthAddress hook
+ */
+interface UseStealthAddressReturn {
+    /** Encoded meta-address for sharing */
+    metaAddress: string | null;
+    /** One-time stealth address */
+    stealthAddress: string | null;
+    /** Spending private key (for claiming) */
+    spendingPrivateKey: string | null;
+    /** Viewing private key (for scanning) */
+    viewingPrivateKey: string | null;
+    /** Whether generation is in progress */
+    isGenerating: boolean;
+    /** Error if any occurred */
+    error: Error | null;
+    /** Generate a new stealth address */
+    regenerate: () => void;
+    /** Copy stealth address to clipboard */
+    copyToClipboard: () => Promise<boolean>;
+    /** Save keys to secure storage */
+    saveToKeychain: () => Promise<boolean>;
+    /** Load keys from secure storage */
+    loadFromKeychain: () => Promise<boolean>;
+    /** Clear error state */
+    clearError: () => void;
+}
+/**
+ * Mobile-optimized stealth address hook
+ *
+ * @param chain - Target blockchain
+ * @param options - Hook options
+ */
+declare function useStealthAddress(chain: SupportedChainId, options?: UseStealthAddressOptions): UseStealthAddressReturn;
+
+/**
+ * useStealthTransfer - Mobile-optimized private transfer hook
+ *
+ * Handles shielded SPL token transfers on Solana from mobile devices.
+ *
+ * @example
+ * ```tsx
+ * import { useStealthTransfer } from '@sip-protocol/react-native'
+ *
+ * function SendScreen() {
+ *   const { transfer, status, error, isLoading } = useStealthTransfer({
+ *     connection,
+ *     wallet: walletAdapter,
+ *   })
+ *
+ *   const handleSend = async () => {
+ *     const result = await transfer({
+ *       recipientMetaAddress: 'sip:solana:...',
+ *       amount: 1000000n, // 1 USDC
+ *       mint: USDC_MINT,
+ *     })
+ *     if (result.success) {
+ *       Alert.alert('Success', 'Payment sent privately!')
+ *     }
+ *   }
+ *
+ *   return (
+ *     <TouchableOpacity onPress={handleSend} disabled={isLoading}>
+ *       <Text>{isLoading ? 'Sending...' : 'Send Private Payment'}</Text>
+ *     </TouchableOpacity>
+ *   )
+ * }
+ * ```
+ */
+/**
+ * Wallet adapter interface for mobile wallets
+ */
+interface MobileWalletAdapter {
+    publicKey: {
+        toBase58(): string;
+    } | null;
+    signTransaction: <T>(transaction: T) => Promise<T>;
+    signAllTransactions?: <T>(transactions: T[]) => Promise<T[]>;
+}
+/**
+ * Transfer status enum
+ */
+type TransferStatus = 'idle' | 'preparing' | 'signing' | 'sending' | 'confirming' | 'success' | 'error';
+/**
+ * Parameters for stealth transfer
+ */
+interface TransferParams {
+    /** Recipient's stealth meta-address */
+    recipientMetaAddress: string;
+    /** Amount in smallest units */
+    amount: bigint;
+    /** SPL token mint address */
+    mint: string;
+}
+/**
+ * Result of stealth transfer
+ */
+interface TransferResult {
+    success: boolean;
+    signature?: string;
+    stealthAddress?: string;
+    error?: Error;
+}
+/**
+ * Connection interface (subset of @solana/web3.js Connection)
+ */
+interface SolanaConnection$1 {
+    confirmTransaction(signature: string, commitment?: string): Promise<{
+        value: {
+            err: unknown;
+        };
+    }>;
+}
+/**
+ * Parameters for useStealthTransfer hook
+ */
+interface UseStealthTransferParams {
+    /** Solana connection */
+    connection: SolanaConnection$1;
+    /** Wallet adapter */
+    wallet: MobileWalletAdapter;
+}
+/**
+ * Return type for useStealthTransfer hook
+ */
+interface UseStealthTransferReturn {
+    /** Execute a private transfer */
+    transfer: (params: TransferParams) => Promise<TransferResult>;
+    /** Current transfer status */
+    status: TransferStatus;
+    /** Error if any occurred */
+    error: Error | null;
+    /** Whether a transfer is in progress */
+    isLoading: boolean;
+    /** Reset the hook state */
+    reset: () => void;
+}
+/**
+ * Mobile-optimized stealth transfer hook
+ *
+ * @param params - Hook parameters
+ */
+declare function useStealthTransfer(params: UseStealthTransferParams): UseStealthTransferReturn;
+/**
+ * Get associated token address helper
+ *
+ * Dynamically imports from @solana/spl-token
+ *
+ * @param mint - Token mint address string
+ * @param owner - Owner address string
+ * @returns Associated token address
+ */
+declare function getAssociatedTokenAddress(mint: string, owner: string): Promise<string>;
+
+/**
+ * useScanPayments - Mobile-optimized payment scanning hook
+ *
+ * Scans for incoming stealth payments using viewing key.
+ *
+ * @example
+ * ```tsx
+ * import { useScanPayments } from '@sip-protocol/react-native'
+ *
+ * function InboxScreen() {
+ *   const { payments, isScanning, scan, claim } = useScanPayments({
+ *     connection,
+ *     provider: heliusProvider,
+ *   })
+ *
+ *   useEffect(() => {
+ *     // Load keys from keychain and scan
+ *     loadKeysAndScan()
+ *   }, [])
+ *
+ *   return (
+ *     <FlatList
+ *       data={payments}
+ *       renderItem={({ item }) => (
+ *         <PaymentCard
+ *           payment={item}
+ *           onClaim={() => claim(item.signature)}
+ *         />
+ *       )}
+ *     />
+ *   )
+ * }
+ * ```
+ */
+/**
+ * Solana connection interface (subset of @solana/web3.js Connection)
+ */
+interface SolanaConnection {
+    getAccountInfo(publicKey: unknown): Promise<unknown>;
+    getSignaturesForAddress(address: unknown, options?: unknown): Promise<unknown[]>;
+    getTransaction(signature: string, options?: unknown): Promise<unknown>;
+}
+/**
+ * Scanned payment info
+ */
+interface ScannedPayment {
+    /** Transaction signature */
+    signature: string;
+    /** Stealth address that received the payment */
+    stealthAddress: string;
+    /** Ephemeral public key */
+    ephemeralPublicKey: string;
+    /** Token mint address */
+    mint: string;
+    /** Amount in smallest units */
+    amount: bigint;
+    /** Block timestamp */
+    timestamp: number;
+    /** Whether this payment has been claimed */
+    claimed: boolean;
+}
+/**
+ * Scan status
+ */
+type ScanStatus = 'idle' | 'scanning' | 'claiming' | 'error';
+/**
+ * Hook parameters
+ */
+interface UseScanPaymentsParams {
+    /** Solana connection */
+    connection: SolanaConnection;
+    /** RPC provider (Helius recommended) */
+    provider?: unknown;
+}
+/**
+ * Hook return type
+ */
+interface UseScanPaymentsReturn {
+    /** Scanned payments */
+    payments: ScannedPayment[];
+    /** Current status */
+    status: ScanStatus;
+    /** Error if any */
+    error: Error | null;
+    /** Whether scanning is in progress */
+    isScanning: boolean;
+    /** Scan for payments */
+    scan: (viewingPrivateKey: string, spendingPublicKey: string) => Promise<void>;
+    /** Claim a specific payment */
+    claim: (signature: string, spendingPrivateKey: string, destinationAddress: string) => Promise<string | null>;
+    /** Claim all unclaimed payments */
+    claimAll: (spendingPrivateKey: string, destinationAddress: string) => Promise<string[]>;
+    /** Clear payments */
+    clear: () => void;
+}
+/**
+ * Mobile payment scanning hook
+ */
+declare function useScanPayments(params: UseScanPaymentsParams): UseScanPaymentsReturn;
+
+/**
+ * Secure Key Storage for React Native
+ *
+ * Provides secure storage for private keys using native platform capabilities:
+ * - iOS: Keychain with biometric protection
+ * - Android: Keystore with biometric protection
+ *
+ * Falls back to in-memory storage if react-native-keychain is not available.
+ *
+ * @example
+ * ```typescript
+ * import { SecureStorage } from '@sip-protocol/react-native'
+ *
+ * // Store viewing key
+ * await SecureStorage.setViewingKey('my-wallet', viewingPrivateKey)
+ *
+ * // Retrieve with biometric prompt
+ * const key = await SecureStorage.getViewingKey('my-wallet')
+ *
+ * // Clear on logout
+ * await SecureStorage.clearAll()
+ * ```
+ */
+/**
+ * Storage options for secure key storage
+ */
+interface SecureStorageOptions {
+    /** Key identifier/service name */
+    service?: string;
+    /** Require biometric authentication to access */
+    requireBiometrics?: boolean;
+    /** iOS: Accessibility level */
+    accessible?: 'whenUnlocked' | 'afterFirstUnlock' | 'always';
+    /** Storage backend to use */
+    backend?: 'keychain' | 'memory';
+}
+/**
+ * Key prefixes for different key types
+ */
+declare const KEY_PREFIXES: {
+    readonly spending: "sip:spending:";
+    readonly viewing: "sip:viewing:";
+    readonly ephemeral: "sip:ephemeral:";
+    readonly meta: "sip:meta:";
+};
+type KeyType = keyof typeof KEY_PREFIXES;
+/**
+ * Store a key securely
+ *
+ * @param type - Type of key (spending, viewing, ephemeral, meta)
+ * @param identifier - Unique identifier (e.g., wallet address)
+ * @param value - Key value (hex string)
+ * @param options - Storage options
+ */
+declare function setKey(type: KeyType, identifier: string, value: string, options?: SecureStorageOptions): Promise<boolean>;
+/**
+ * Retrieve a key from secure storage
+ *
+ * @param type - Type of key (spending, viewing, ephemeral, meta)
+ * @param identifier - Unique identifier (e.g., wallet address)
+ * @param options - Storage options
+ * @returns Key value or null if not found
+ */
+declare function getKey(type: KeyType, identifier: string, options?: SecureStorageOptions): Promise<string | null>;
+/**
+ * Delete a key from secure storage
+ *
+ * @param type - Type of key (spending, viewing, ephemeral, meta)
+ * @param identifier - Unique identifier (e.g., wallet address)
+ * @param options - Storage options
+ */
+declare function deleteKey(type: KeyType, identifier: string, options?: SecureStorageOptions): Promise<boolean>;
+/**
+ * Clear all stored keys
+ *
+ * @param options - Storage options
+ */
+declare function clearAll(options?: SecureStorageOptions): Promise<boolean>;
+/**
+ * Check if biometrics are available on this device
+ *
+ * @returns Biometrics support info
+ */
+declare function getSupportedBiometrics(): Promise<{
+    available: boolean;
+    biometryType: 'FaceID' | 'TouchID' | 'Fingerprint' | 'None';
+}>;
+/**
+ * Check if secure storage is available
+ */
+declare function isAvailable(): boolean;
+/**
+ * SecureStorage API
+ *
+ * Unified API for secure key storage on mobile devices.
+ */
+declare const SecureStorage: {
+    readonly setKey: typeof setKey;
+    readonly getKey: typeof getKey;
+    readonly deleteKey: typeof deleteKey;
+    readonly clearAll: typeof clearAll;
+    readonly setViewingKey: (identifier: string, key: string, options?: SecureStorageOptions) => Promise<boolean>;
+    readonly getViewingKey: (identifier: string, options?: SecureStorageOptions) => Promise<string | null>;
+    readonly deleteViewingKey: (identifier: string, options?: SecureStorageOptions) => Promise<boolean>;
+    readonly setSpendingKey: (identifier: string, key: string, options?: SecureStorageOptions) => Promise<boolean>;
+    readonly getSpendingKey: (identifier: string, options?: SecureStorageOptions) => Promise<string | null>;
+    readonly deleteSpendingKey: (identifier: string, options?: SecureStorageOptions) => Promise<boolean>;
+    readonly setMetaAddress: (identifier: string, meta: string, options?: SecureStorageOptions) => Promise<boolean>;
+    readonly getMetaAddress: (identifier: string, options?: SecureStorageOptions) => Promise<string | null>;
+    readonly deleteMetaAddress: (identifier: string, options?: SecureStorageOptions) => Promise<boolean>;
+    readonly getSupportedBiometrics: typeof getSupportedBiometrics;
+    readonly isAvailable: typeof isAvailable;
+};
+
+/**
+ * Clipboard Utilities for React Native
+ *
+ * Provides cross-platform clipboard access with fallback support.
+ */
+/**
+ * Copy text to clipboard
+ *
+ * @param text - Text to copy
+ * @returns true if successful
+ */
+declare function copyToClipboard(text: string): Promise<boolean>;
+/**
+ * Read text from clipboard
+ *
+ * @returns Clipboard contents or empty string
+ */
+declare function readFromClipboard(): Promise<string>;
+/**
+ * Check if clipboard is available
+ */
+declare function isClipboardAvailable(): boolean;
+
+export { type KeyType, type MobileWalletAdapter, type ScanStatus, type ScannedPayment, SecureStorage, type SecureStorageOptions, type TransferParams, type TransferResult, type TransferStatus, type UseScanPaymentsParams, type UseScanPaymentsReturn, type UseStealthAddressOptions, type UseStealthAddressReturn, type UseStealthTransferParams, type UseStealthTransferReturn, copyToClipboard, getAssociatedTokenAddress, isClipboardAvailable, readFromClipboard, useScanPayments, useStealthAddress, useStealthTransfer };