toss-expo-sdk 0.1.0

package/src/client/TossClient.ts

@@ -0,0 +1,435 @@
+import { Connection, Keypair, PublicKey } from '@solana/web3.js';
+import type { SolanaIntent, IntentStatus } from '../intent';
+import { createIntent } from '../intent';
+import {
+  secureStoreIntent,
+  getSecureIntent,
+  getAllSecureIntents,
+} from '../storage/secureStorage';
+import { processIntentsForSync } from '../intentManager';
+import { TossError, NetworkError, StorageError, ERROR_CODES } from '../errors';
+import { createNonceAccount, getNonce } from '../utils/nonceUtils';
+import { useWallet } from '../contexts/WalletContext';
+import { syncToChain, checkSyncStatus, type SyncResult } from '../sync';
+import { detectConflicts, getReconciliationState } from '../reconciliation';
+
+export type TossConfig = {
+  projectId: string;
+  mode?: 'devnet' | 'testnet' | 'mainnet-beta';
+  privateTransactions?: boolean;
+  provider?: any; // AnchorProvider or similar
+  sync?: {
+    syncBackupDb?: boolean;
+    dbUrl?: string;
+  };
+  rpcUrl?: string;
+  maxRetries?: number;
+  retryDelay?: number;
+  feePayer?: Keypair; // Optional fee payer
+};
+
+const DEFAULT_RETRY_OPTIONS = {
+  maxRetries: 3,
+  retryDelay: 1000, // 1 second
+};
+
+export class TossClient {
+  private connection: Connection;
+  private config: Required<Omit<TossConfig, 'rpcUrl' | 'feePayer'>> & {
+    rpcUrl: string;
+    feePayer?: Keypair;
+  };
+  private nonceAccount?: Keypair;
+  private nonceAuth?: PublicKey;
+  private walletContext: ReturnType<typeof useWallet>;
+
+  static createClient(config: TossConfig): TossClient {
+    return new TossClient(config);
+  }
+
+  private constructor(config: TossConfig) {
+    this.config = {
+      projectId: config.projectId,
+      mode: config.mode || 'devnet',
+      privateTransactions: config.privateTransactions || false,
+      provider: config.provider,
+      sync: config.sync || { syncBackupDb: false },
+      rpcUrl: config.rpcUrl || this.getDefaultRpcUrl(config.mode || 'devnet'),
+      maxRetries: config.maxRetries ?? DEFAULT_RETRY_OPTIONS.maxRetries,
+      retryDelay: config.retryDelay ?? DEFAULT_RETRY_OPTIONS.retryDelay,
+      feePayer: config.feePayer,
+    } as const;
+    this.connection = new Connection(this.config.rpcUrl, 'confirmed');
+    this.walletContext = useWallet();
+
+    if (!this.walletContext) {
+      throw new Error('TossClient must be used within a WalletProvider');
+    }
+  }
+
+  private getDefaultRpcUrl(network: string): string {
+    const urls = {
+      'devnet': 'https://api.devnet.solana.com',
+      'testnet': 'https://api.testnet.solana.com',
+      'mainnet-beta': 'https://api.mainnet-beta.solana.com',
+    };
+    return urls[network as keyof typeof urls] || urls.devnet;
+  }
+
+  private async withRetry<T>(
+    fn: () => Promise<T>,
+    context: string
+  ): Promise<T> {
+    let lastError: Error | null = null;
+    const { maxRetries, retryDelay } = this.config;
+
+    for (let attempt = 1; attempt <= maxRetries; attempt++) {
+      try {
+        return await fn();
+      } catch (error) {
+        lastError = error as Error;
+
+        // Don't retry on validation errors
+        if (error instanceof TossError) {
+          throw error;
+        }
+
+        // Exponential backoff
+        if (attempt < maxRetries) {
+          const delay = retryDelay * Math.pow(2, attempt - 1);
+          await new Promise((resolve) => setTimeout(resolve, delay));
+        }
+      }
+    }
+
+    throw new NetworkError(
+      `Failed after ${maxRetries} attempts: ${lastError?.message}`,
+      { context, cause: lastError }
+    );
+  }
+
+  /**
+   * Initialize a nonce account for durable transactions
+   * @param amount SOL amount to fund the nonce account with (default: 1 SOL)
+   * @returns Object containing nonce account and authority public keys
+   */
+  async initializeNonceAccount(
+    amount = 1
+  ): Promise<{ nonceAccount: string; nonceAuth: string }> {
+    if (!this.config.feePayer) {
+      throw new Error(
+        'Fee payer keypair is required for nonce account creation'
+      );
+    }
+
+    const { nonceAccount, nonceAuth } = await createNonceAccount(
+      this.connection,
+      this.config.feePayer,
+      undefined,
+      amount * 1e9 // Convert SOL to lamports
+    );
+
+    this.nonceAccount = nonceAccount;
+    this.nonceAuth = nonceAuth;
+
+    return {
+      nonceAccount: nonceAccount.publicKey.toBase58(),
+      nonceAuth: nonceAuth.toBase58(),
+    };
+  }
+
+  /**
+   * Get the current nonce value from the nonce account
+   * @returns The current nonce value as a base58 string
+   */
+  async getCurrentNonce(): Promise<string> {
+    if (!this.nonceAccount) {
+      throw new Error(
+        'Nonce account not initialized. Call initializeNonceAccount() first.'
+      );
+    }
+    return getNonce(this.connection, this.nonceAccount.publicKey);
+  }
+
+  async createIntent(
+    sender: Keypair | 'current',
+    recipient: PublicKey | string,
+    amount: number,
+    feePayer?: PublicKey | string,
+    options: {
+      expiresIn?: number;
+      nonce?: number;
+      useDurableNonce?: boolean;
+      memo?: string;
+    } = {}
+  ): Promise<SolanaIntent> {
+    return this.withRetry(async () => {
+      try {
+        if (!this.connection) {
+          throw new TossError(
+            'Connection not initialized',
+            ERROR_CODES.NETWORK_ERROR
+          );
+        }
+
+        // Handle 'current' sender to use the wallet context
+        const senderKeypair =
+          sender === 'current' ? this.walletContext.keypair : sender;
+
+        if (!senderKeypair) {
+          throw new TossError(
+            'No sender keypair provided and no wallet is connected',
+            ERROR_CODES.SIGNATURE_VERIFICATION_FAILED
+          );
+        }
+
+        // Convert string addresses to PublicKey if needed
+        const recipientPubkey =
+          typeof recipient === 'string' ? new PublicKey(recipient) : recipient;
+
+        const feePayerPubkey = feePayer
+          ? typeof feePayer === 'string'
+            ? new PublicKey(feePayer)
+            : feePayer
+          : senderKeypair.publicKey;
+
+        // Set up nonce account and auth if using durable nonce
+        if (options.useDurableNonce && this.nonceAccount && this.nonceAuth) {
+          // nonce account and auth are passed via options to createIntent
+        }
+
+        // Get the latest blockhash (no need to store it as it's handled internally)
+        await this.connection.getLatestBlockhash();
+
+        const intent = await createIntent(
+          senderKeypair,
+          recipientPubkey,
+          amount,
+          this.connection,
+          {
+            ...options,
+            feePayer: feePayerPubkey,
+            nonceAccount: options.useDurableNonce
+              ? this.nonceAccount
+              : undefined,
+            nonceAuth: options.useDurableNonce ? this.nonceAuth : undefined,
+          }
+        );
+
+        await secureStoreIntent(intent);
+        return intent;
+      } catch (error) {
+        if (error instanceof TossError) throw error;
+        throw new TossError(
+          'Failed to create intent',
+          ERROR_CODES.TRANSACTION_FAILED,
+          { cause: error }
+        );
+      }
+    }, 'createIntent');
+  }
+
+  async getIntents(): Promise<SolanaIntent[]> {
+    return this.withRetry(async () => {
+      try {
+        return await getAllSecureIntents();
+      } catch (error) {
+        if (error instanceof TossError) throw error;
+        throw new StorageError('Failed to retrieve intents', { cause: error });
+      }
+    }, 'getIntents');
+  }
+
+  async updateIntentStatus(
+    intentId: string,
+    status: IntentStatus,
+    error?: string
+  ): Promise<SolanaIntent | null> {
+    return this.withRetry(async () => {
+      try {
+        const intent = await getSecureIntent(intentId);
+        if (!intent) return null;
+
+        // Ensure updatedAt is a number (timestamp)
+        const updatedAt = Date.now();
+
+        const updatedIntent: SolanaIntent = {
+          ...intent,
+          status,
+          updatedAt,
+          ...(error ? { error } : {}),
+        };
+
+        await secureStoreIntent(updatedIntent);
+        return updatedIntent;
+      } catch (error) {
+        if (error instanceof TossError) throw error;
+        throw new StorageError('Failed to update intent status', {
+          cause: error,
+          intentId,
+          status,
+        });
+      }
+    }, 'updateIntentStatus');
+  }
+
+  async sync(): Promise<SolanaIntent[]> {
+    return this.withRetry(async () => {
+      try {
+        const intents = await getAllSecureIntents();
+
+        if (!this.config.sync?.syncBackupDb || !this.config.sync.dbUrl) {
+          return intents;
+        }
+
+        // Process intents for sync and update their statuses
+        const processedIntents = await processIntentsForSync(
+          intents,
+          this.connection
+        );
+
+        // Save updated intents
+        await Promise.all(
+          processedIntents.map((intent) => secureStoreIntent(intent))
+        );
+
+        return processedIntents;
+      } catch (error) {
+        if (error instanceof TossError) throw error;
+        throw new NetworkError('Failed to sync intents', { cause: error });
+      }
+    }, 'sync');
+  }
+
+  /**
+   * Full synchronisation with Solana blockchain (TOSS Section 9)
+   *
+   * Performs complete reconciliation:
+   * - Detects conflicts with onchain state
+   * - Settles all pending intents
+   * - Updates local state deterministically
+   *
+   * @returns Complete sync results including settlements, conflicts, and final state
+   */
+  async fullSync(): Promise<SyncResult> {
+    return this.withRetry(async () => {
+      try {
+        return await syncToChain(
+          this.connection,
+          this.config.feePayer?.publicKey
+        );
+      } catch (error) {
+        if (error instanceof TossError) throw error;
+        throw new NetworkError('Full sync failed', { cause: error });
+      }
+    }, 'fullSync');
+  }
+
+  /**
+   * Check synchronisation status without settling
+   *
+   * Lightweight operation to query current reconciliation state
+   * without committing any settlements to the blockchain.
+   */
+  async checkSyncStatus() {
+    return this.withRetry(async () => {
+      return await checkSyncStatus(this.connection);
+    }, 'checkSyncStatus');
+  }
+
+  /**
+   * Detect conflicts between local intents and onchain state
+   *
+   * Useful for monitoring and alerting users to potential issues
+   * before attempting settlement.
+   */
+  async detectIntentConflicts() {
+    return this.withRetry(async () => {
+      return await detectConflicts(this.connection);
+    }, 'detectIntentConflicts');
+  }
+
+  /**
+   * Get current reconciliation state
+   *
+   * Returns summary of processed, failed, and conflicting intents
+   * for UI updates or logging.
+   */
+  async getReconciliationStatus() {
+    return this.withRetry(async () => {
+      return await getReconciliationState(this.connection);
+    }, 'getReconciliationStatus');
+  }
+
+  /**
+   * Create an intent from the current user's wallet
+   */
+  async createUserIntent(
+    recipient: PublicKey | string,
+    amount: number,
+    options: {
+      memo?: string;
+      useDurableNonce?: boolean;
+    } = {}
+  ): Promise<SolanaIntent> {
+    if (!this.walletContext.user) {
+      throw new TossError(
+        'No user is currently signed in',
+        ERROR_CODES.SIGNATURE_VERIFICATION_FAILED
+      );
+    }
+
+    // Ensure wallet is unlocked
+    if (!this.walletContext.isUnlocked) {
+      const unlocked = await this.walletContext.unlockWallet();
+      if (!unlocked) {
+        throw new TossError(
+          'Wallet is locked',
+          ERROR_CODES.SIGNATURE_VERIFICATION_FAILED
+        );
+      }
+    }
+
+    const recipientPubkey =
+      typeof recipient === 'string' ? new PublicKey(recipient) : recipient;
+
+    return this.createIntent(
+      'current', // This will use the wallet context's keypair
+      recipientPubkey,
+      amount,
+      this.walletContext.user.wallet.publicKey,
+      {
+        ...options,
+        memo: options.memo || `TOSS transfer to ${recipientPubkey.toBase58()}`,
+      }
+    );
+  }
+
+  /**
+   * Get the current user's wallet address
+   */
+  getCurrentUserAddress(): string | null {
+    return this.walletContext.user?.wallet.publicKey.toString() || null;
+  }
+
+  /**
+   * Check if the wallet is currently unlocked
+   */
+  isWalletUnlocked(): boolean {
+    return this.walletContext.isUnlocked;
+  }
+
+  /**
+   * Lock the wallet
+   */
+  async lockWallet(): Promise<void> {
+    await this.walletContext.lockWallet();
+  }
+
+  /**
+   * Sign out the current user
+   */
+  async signOut(): Promise<void> {
+    await this.walletContext.signOut();
+  }
+}

package/src/client/index.ts

@@ -0,0 +1,2 @@
+export * from './TossClient';
+export type { TossConfig } from './TossClient';

package/src/contexts/WalletContext.tsx

@@ -0,0 +1,127 @@
+import { createContext, useContext, useState, useEffect } from 'react';
+import type { ReactNode } from 'react';
+import { Keypair } from '@solana/web3.js';
+import { AuthService } from '../services/authService';
+import type { TossUser } from '../types/tossUser';
+
+type WalletContextType = {
+  isInitialized: boolean;
+  isUnlocked: boolean;
+  user: TossUser | null;
+  keypair: Keypair | null;
+  unlockWallet: () => Promise<boolean>;
+  lockWallet: () => Promise<void>;
+  signIn: (walletAddress: string, isTemporary?: boolean) => Promise<void>;
+  signOut: () => Promise<void>;
+};
+
+const WalletContext = createContext<WalletContextType | undefined>(undefined);
+
+export const WalletProvider: React.FC<{ children: ReactNode }> = ({
+  children,
+}) => {
+  const [isInitialized, setIsInitialized] = useState(false);
+  const [isUnlocked, setIsUnlocked] = useState(false);
+  const [user, setUser] = useState<TossUser | null>(null);
+  const [keypair, setKeypair] = useState<Keypair | null>(null);
+
+  useEffect(() => {
+    const checkAuth = async () => {
+      try {
+        const session = await AuthService.getSession();
+        if (session) {
+          // In a real app, you'd fetch the user from your backend
+          const { user } = await AuthService.signInWithWallet(
+            session.walletAddress
+          );
+          setUser(user);
+          setIsUnlocked(await AuthService.isWalletUnlocked());
+        }
+      } catch (error) {
+        console.error('Auth check failed:', error);
+      } finally {
+        setIsInitialized(true);
+      }
+    };
+
+    checkAuth();
+  }, []);
+
+  const unlockWallet = async (): Promise<boolean> => {
+    try {
+      // Biometric authentication REQUIRED - throws if not authorized
+      const unlockedKeypair = await AuthService.unlockWalletWithBiometrics();
+      if (unlockedKeypair) {
+        // Keypair held ONLY in React state memory (NOT persisted to disk)
+        setKeypair(unlockedKeypair);
+        setIsUnlocked(true);
+        return true;
+      }
+      return false;
+    } catch (error) {
+      console.error('Biometric authentication failed:', error);
+      setIsUnlocked(false);
+      setKeypair(null);
+      return false;
+    }
+  };
+
+  const lockWallet = async (): Promise<void> => {
+    // Clear keypair from memory (from React state)
+    // Encrypted keypair remains stored securely (requires biometric to re-unlock)
+    setKeypair(null);
+    setIsUnlocked(false);
+  };
+
+  const signIn = async (
+    walletAddress: string,
+    isTemporary: boolean = false
+  ): Promise<void> => {
+    const { user } = await AuthService.signInWithWallet(
+      walletAddress,
+      isTemporary
+    );
+    setUser(user);
+    setIsUnlocked(true);
+  };
+
+  const signOut = async (): Promise<void> => {
+    // Clear session from storage
+    await AuthService.signOut();
+
+    // Clear all memory (state)
+    setUser(null);
+    setKeypair(null); // Remove from RAM
+    setIsUnlocked(false);
+
+    // NOTE: Encrypted keypair remains in SecureStore
+    // It can only be accessed again with biometric authentication
+  };
+
+  return (
+    <WalletContext.Provider
+      value={{
+        isInitialized,
+        isUnlocked,
+        user,
+        keypair,
+        unlockWallet,
+        lockWallet,
+        signIn,
+        signOut,
+      }}
+    >
+      {children}
+    </WalletContext.Provider>
+  );
+};
+
+export const useWallet = (): WalletContextType => {
+  const context = useContext(WalletContext);
+  if (context === undefined) {
+    throw new Error('useWallet must be used within a WalletProvider');
+  }
+  return context;
+};
+
+export default WalletContext;