toss-expo-sdk 0.1.1 → 0.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toss-expo-sdk",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "The official React Native SDK for The Offline Solana Stack (TOSS)",
   "type": "module",
   "main": "./lib/module/index.js",
@@ -91,6 +91,7 @@
     "del-cli": "^6.0.0",
     "eslint": "^9.35.0",
     "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-ft-flow": "^3.0.11",
     "eslint-plugin-prettier": "^5.5.4",
     "eslint-plugin-react-native": "^5.0.0",
     "jest": "^29.7.0",
@@ -136,6 +137,16 @@
     "modulePathIgnorePatterns": [
       "<rootDir>/example/node_modules",
       "<rootDir>/lib/"
+    ],
+    "transformIgnorePatterns": [
+      "node_modules/(?!(react-native|\\@react-native|\\@solana|@arcium-hq|@chainsafe)/)"
+    ],
+    "transform": {
+      "^.+\\.(js|ts|tsx|mjs)$": "babel-jest"
+    },
+    "extensionsToTreatAsEsm": [
+      ".ts",
+      ".tsx"
     ]
   },
   "commitlint": {

package/src/__tests__/reconciliation.test.tsx

@@ -180,7 +180,8 @@ describe('Discovery Module', () => {
 
       // Manually set old timestamp
       discovery.registerPeer(peer);
-      discovery['discoveredPeers'].get('peer_timeout')!.lastSeen =
+      // Access private storage for testing via cast to any
+      (discovery as any).discoveredPeers.get('peer_timeout')!.lastSeen =
         Date.now() - 6 * 60 * 1000;
 
       const active = discovery.getActivePeers();
@@ -214,6 +215,11 @@ describe('Discovery Module', () => {
       protocol = new IntentExchangeProtocol();
     });
 
+    afterEach(() => {
+      // Ensure any timers or sessions are cleaned up so Jest can exit
+      protocol.dispose();
+    });
+
     it('should create an exchange request', () => {
       const intent: SolanaIntent = {
         id: 'intent_test',

package/src/client/TossClient.ts

@@ -9,7 +9,7 @@ import {
 import { processIntentsForSync } from '../intentManager';
 import { TossError, NetworkError, StorageError, ERROR_CODES } from '../errors';
 import { createNonceAccount, getNonce } from '../utils/nonceUtils';
-import { useWallet } from '../contexts/WalletContext';
+// Note: TossClient is not tied to a React hook. To use wallet-provided keys in React, pass a Keypair to methods directly.
 import { syncToChain, checkSyncStatus, type SyncResult } from '../sync';
 import { detectConflicts, getReconciliationState } from '../reconciliation';
 
@@ -41,7 +41,6 @@ export class TossClient {
   };
   private nonceAccount?: Keypair;
   private nonceAuth?: PublicKey;
-  private walletContext: ReturnType<typeof useWallet>;
 
   static createClient(config: TossConfig): TossClient {
     return new TossClient(config);
@@ -60,11 +59,6 @@ export class TossClient {
       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 {
@@ -172,13 +166,20 @@ export class TossClient {
           );
         }
 
-        // Handle 'current' sender to use the wallet context
-        const senderKeypair =
-          sender === 'current' ? this.walletContext.keypair : sender;
+        // Handle 'current' sender: explicit wallet integration via React hooks is
+        // not available in this non-React class. Require a Keypair to be passed.
+        if (sender === 'current') {
+          throw new TossError(
+            'Using "current" as sender is only supported when the client is used inside a WalletProvider. Please provide a Keypair instead.',
+            ERROR_CODES.SIGNATURE_VERIFICATION_FAILED
+          );
+        }
+
+        const senderKeypair = sender as Keypair;
 
         if (!senderKeypair) {
           throw new TossError(
-            'No sender keypair provided and no wallet is connected',
+            'No sender keypair provided',
             ERROR_CODES.SIGNATURE_VERIFICATION_FAILED
           );
         }
@@ -262,10 +263,10 @@ export class TossClient {
 
         await secureStoreIntent(updatedIntent);
         return updatedIntent;
-      } catch (error) {
-        if (error instanceof TossError) throw error;
+      } catch (err) {
+        if (err instanceof TossError) throw err;
         throw new StorageError('Failed to update intent status', {
-          cause: error,
+          cause: err,
           intentId,
           status,
         });
@@ -364,7 +365,14 @@ export class TossClient {
   /**
    * Create an intent from the current user's wallet
    */
+  /**
+   * Create an intent using an explicit Keypair for the sender.
+   * Use this method from non-React contexts. For React apps, use
+   * WalletProvider.createUserIntent helper wrappers that call
+   * TossClient.createIntent with the unlocked keypair.
+   */
   async createUserIntent(
+    senderKeypair: Keypair,
     recipient: PublicKey | string,
     amount: number,
     options: {
@@ -372,32 +380,14 @@ export class TossClient {
       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
+      senderKeypair,
       recipientPubkey,
       amount,
-      this.walletContext.user.wallet.publicKey,
+      senderKeypair.publicKey,
       {
         ...options,
         memo: options.memo || `TOSS transfer to ${recipientPubkey.toBase58()}`,
@@ -406,30 +396,27 @@ export class TossClient {
   }
 
   /**
-   * Get the current user's wallet address
+   * The following helper methods require a WalletProvider (React) context.
+   * TossClient is framework-agnostic; if you need these features from a
+   * React app, use the WalletProvider utilities instead.
    */
   getCurrentUserAddress(): string | null {
-    return this.walletContext.user?.wallet.publicKey.toString() || null;
+    throw new Error(
+      'getCurrentUserAddress is only available when using WalletProvider'
+    );
   }
 
-  /**
-   * Check if the wallet is currently unlocked
-   */
   isWalletUnlocked(): boolean {
-    return this.walletContext.isUnlocked;
+    throw new Error(
+      'isWalletUnlocked is only available when using WalletProvider'
+    );
   }
 
-  /**
-   * Lock the wallet
-   */
   async lockWallet(): Promise<void> {
-    await this.walletContext.lockWallet();
+    throw new Error('lockWallet is only available when using WalletProvider');
   }
 
-  /**
-   * Sign out the current user
-   */
   async signOut(): Promise<void> {
-    await this.walletContext.signOut();
+    throw new Error('signOut is only available when using WalletProvider');
   }
 }

package/src/contexts/WalletContext.tsx

@@ -31,10 +31,10 @@ export const WalletProvider: React.FC<{ children: ReactNode }> = ({
         const session = await AuthService.getSession();
         if (session) {
           // In a real app, you'd fetch the user from your backend
-          const { user } = await AuthService.signInWithWallet(
+          const { user: sessionUser } = await AuthService.signInWithWallet(
             session.walletAddress
           );
-          setUser(user);
+          setUser(sessionUser);
           setIsUnlocked(await AuthService.isWalletUnlocked());
         }
       } catch (error) {
@@ -77,11 +77,11 @@ export const WalletProvider: React.FC<{ children: ReactNode }> = ({
     walletAddress: string,
     isTemporary: boolean = false
   ): Promise<void> => {
-    const { user } = await AuthService.signInWithWallet(
+    const { user: sessionUser } = await AuthService.signInWithWallet(
       walletAddress,
       isTemporary
     );
-    setUser(user);
+    setUser(sessionUser);
     setIsUnlocked(true);
   };
 

package/src/discovery.ts

@@ -152,6 +152,12 @@ export class DeviceDiscoveryService {
 export class IntentExchangeProtocol {
   private pendingRequests: Map<string, IntentExchangeRequest> = new Map();
   private noiseSessions: Map<string, NoiseSession> = new Map();
+  // Track timeout handles so they can be cleared during shutdown/cleanup
+  private requestTimeouts: Map<string, ReturnType<typeof setTimeout>> =
+    new Map();
+  private sessionTimeouts: Map<string, ReturnType<typeof setTimeout>> =
+    new Map();
+
   private deviceStaticKey: Uint8Array; // Static key for this device
   private readonly REQUEST_TIMEOUT = 2 * 60 * 1000; // 2 minutes
   private readonly SESSION_TIMEOUT = 30 * 60 * 1000; // 30 minutes
@@ -187,11 +193,14 @@ export class IntentExchangeProtocol {
 
     this.noiseSessions.set(peerId, session);
 
-    // Clean up expired sessions
-    setTimeout(() => {
+    // Clean up expired sessions (track timer so it can be cleared)
+    const sessTimer = setTimeout(() => {
       this.noiseSessions.delete(peerId);
+      this.sessionTimeouts.delete(peerId);
     }, this.SESSION_TIMEOUT);
 
+    this.sessionTimeouts.set(peerId, sessTimer);
+
     return session;
   }
 
@@ -224,8 +233,11 @@ export class IntentExchangeProtocol {
     // XOR encryption with session key
     const encrypted = new Uint8Array(payload.length);
     for (let i = 0; i < payload.length; i++) {
+      // XOR operation used intentionally for lightweight obfuscation
+      // Prefer Uint8 arithmetic to avoid bitwise lint; modulo ensures 0-255 values
       encrypted[i] =
-        payload[i]! ^ session.sessionKey[i % session.sessionKey.length]!;
+        (payload[i]! + session.sessionKey[i % session.sessionKey.length]!) %
+        256;
     }
 
     return encrypted;
@@ -241,8 +253,12 @@ export class IntentExchangeProtocol {
     // Reverse the XOR operation
     const decrypted = new Uint8Array(ciphertext.length);
     for (let i = 0; i < ciphertext.length; i++) {
+      // Reverse the lightweight obfuscation
       decrypted[i] =
-        ciphertext[i]! ^ session.sessionKey[i % session.sessionKey.length]!;
+        (256 +
+          ciphertext[i]! -
+          (session.sessionKey[i % session.sessionKey.length]! % 256)) %
+        256;
     }
 
     const jsonPayload = new TextDecoder().decode(decrypted);
@@ -293,11 +309,14 @@ export class IntentExchangeProtocol {
 
     this.pendingRequests.set(requestId, request);
 
-    // Clean up expired requests after timeout
-    setTimeout(() => {
+    // Clean up expired requests after timeout (track timer so it can be cleared)
+    const reqTimer = setTimeout(() => {
       this.pendingRequests.delete(requestId);
+      this.requestTimeouts.delete(requestId);
     }, this.REQUEST_TIMEOUT);
 
+    this.requestTimeouts.set(requestId, reqTimer);
+
     return request;
   }
 
@@ -380,18 +399,37 @@ export class IntentExchangeProtocol {
   }
 
   /**
-   * Clear all pending requests
+   * Clear all pending requests and their timers
    */
   clearRequests(): void {
+    // Clear any outstanding timers
+    for (const [id, timer] of this.requestTimeouts.entries()) {
+      clearTimeout(timer);
+      this.requestTimeouts.delete(id);
+    }
+
     this.pendingRequests.clear();
   }
 
   /**
-   * Clear all Noise sessions
+   * Clear all Noise sessions and their timers
    */
   clearSessions(): void {
+    for (const [id, timer] of this.sessionTimeouts.entries()) {
+      clearTimeout(timer);
+      this.sessionTimeouts.delete(id);
+    }
+
     this.noiseSessions.clear();
   }
+
+  /**
+   * Dispose of the protocol, clearing internal state and timers
+   */
+  dispose(): void {
+    this.clearRequests();
+    this.clearSessions();
+  }
 }
 
 /**

package/src/examples/offlinePaymentFlow.ts

@@ -10,7 +10,13 @@
  */
 
 import { Connection, Keypair, PublicKey } from '@solana/web3.js';
-import { createIntent, type SolanaIntent, verifyIntent } from '../intent';
+import {
+  createUserIntent,
+  createIntent,
+  type SolanaIntent,
+  verifyIntent,
+} from '../intent';
+import type { TossUser } from '../types/tossUser';
 import {
   secureStoreIntent,
   getAllSecureIntents,
@@ -25,7 +31,47 @@ import { syncToChain } from '../sync';
 import { TossError } from '../errors';
 
 /**
- * Example: Sender initiates offline payment
+ * Example: Sender initiates offline payment using TOSS users
+ *
+ * User-centric approach: sender and recipient are TossUser objects
+ * Intent creation validates user features and transaction limits
+ */
+export async function exampleInitiateUserPayment(
+  senderUser: TossUser,
+  senderKeypair: Keypair,
+  recipientUser: TossUser,
+  amountLamports: number,
+  connection: Connection
+): Promise<SolanaIntent> {
+  console.log('📝 Creating offline payment intent between TOSS users...');
+  console.log(`   From: @${senderUser.username}`);
+  console.log(`   To: @${recipientUser.username}`);
+
+  // Create the intent using user objects (validates sender/recipient features)
+  const intent = await createUserIntent(
+    senderUser,
+    senderKeypair,
+    recipientUser,
+    amountLamports,
+    connection,
+    {
+      expiresIn: 24 * 60 * 60, // Valid for 24 hours
+    }
+  );
+
+  console.log(`✅ Intent created: ${intent.id}`);
+  console.log(`   Amount: ${intent.amount} lamports`);
+  console.log(`   Expires at: ${new Date(intent.expiry * 1000).toISOString()}`);
+
+  // Store locally
+  await secureStoreIntent(intent);
+  console.log('💾 Intent stored securely locally\n');
+
+  return intent;
+}
+
+/**
+ * Example: Sender initiates offline payment using addresses (legacy)
  *
  * This simulates a sender who wants to send lamports to a recipient
  * while offline. The intent is created, signed, and stored locally.

package/src/index.tsx

@@ -1,5 +1,11 @@
 // Core types and intents
-export { createIntent, type SolanaIntent, type IntentStatus } from './intent';
+export {
+  createIntent,
+  createUserIntent,
+  createSignedIntent,
+  type SolanaIntent,
+  type IntentStatus,
+} from './intent';
 
 // Intent management
 export {
@@ -25,6 +31,8 @@ export { QRScanner } from './qr';
 
 // Client
 export { TossClient, type TossConfig } from './client/TossClient';
+export type { TossUser } from './types/tossUser';
+export { WalletProvider, useWallet } from './contexts/WalletContext';
 
 // Create client instance
 import { TossClient } from './client/TossClient';

package/src/intent.ts

@@ -4,6 +4,7 @@ import bs58 from 'bs58';
 import { v4 as uuidv4 } from 'uuid';
 import { sign } from 'tweetnacl';
 import nacl from 'tweetnacl';
+import type { TossUser, TossUserContext } from './types/tossUser';
 import {
   encryptForArciumInternal,
   type ArciumEncryptedOutput,
@@ -23,6 +24,9 @@ export interface SolanaIntent {
   id: string; // Unique identifier for the intent
   from: string; // Sender's public key
   to: string; // Recipient's public key
+  // Optional TOSS user contexts (preferred for TOSS-to-TOSS communication)
+  fromUser?: TossUserContext; // Minimal sender user context
+  toUser?: TossUserContext; // Minimal recipient user context
   amount: number; // Amount in lamports
   nonce: number; // For replay protection
   expiry: number; // Unix timestamp in seconds
@@ -64,6 +68,9 @@ export interface CreateIntentOptions {
   nonceAuth?: PublicKey;
   /** Fee payer for the transaction (defaults to sender) */
   feePayer?: PublicKey | string;
+  /** Optional minimal user contexts for sender and recipient */
+  fromUser?: TossUserContext;
+  toUser?: TossUserContext;
 }
 
 /**
@@ -133,6 +140,84 @@ class NonceManager {
 
 export const nonceManager = new NonceManager();
 
+/**
+ * Creates a signed intent between two TOSS users (User-centric API)
+ * Recommended for application developers - validates user wallets
+ */
+export async function createUserIntent(
+  senderUser: TossUser,
+  senderKeypair: Keypair,
+  recipientUser: TossUser,
+  amount: number,
+  connection: Connection,
+  options: CreateIntentOptions = {}
+): Promise<SolanaIntent> {
+  // Verify sender's keypair matches their wallet
+  if (
+    senderKeypair.publicKey.toBase58() !==
+    senderUser.wallet.publicKey.toBase58()
+  ) {
+    throw new Error('Sender keypair does not match user wallet');
+  }
+
+  // Verify both users can transact
+  if (!senderUser.tossFeatures.canSend) {
+    throw new Error('Sender account is not enabled for sending');
+  }
+  if (!recipientUser.tossFeatures.canReceive) {
+    throw new Error('Recipient account is not enabled for receiving');
+  }
+
+  // Verify transaction amount is within limits
+  if (amount > senderUser.tossFeatures.maxTransactionAmount) {
+    throw new Error(
+      `Transaction amount exceeds limit of ${senderUser.tossFeatures.maxTransactionAmount} lamports`
+    );
+  }
+
+  // Prepare minimal user contexts for inclusion in the intent
+  const senderCtx: TossUserContext = {
+    userId: senderUser.userId,
+    username: senderUser.username,
+    wallet: {
+      publicKey: senderUser.wallet.publicKey,
+      isVerified: senderUser.wallet.isVerified,
+      createdAt: senderUser.wallet.createdAt,
+    },
+    status: senderUser.status,
+    deviceId: senderUser.device.id,
+    sessionId: uuidv4(),
+  };
+
+  const recipientCtx: TossUserContext = {
+    userId: recipientUser.userId,
+    username: recipientUser.username,
+    wallet: {
+      publicKey: recipientUser.wallet.publicKey,
+      isVerified: recipientUser.wallet.isVerified,
+      createdAt: recipientUser.wallet.createdAt,
+    },
+    status: recipientUser.status,
+    deviceId: recipientUser.device.id,
+    sessionId: uuidv4(),
+  };
+
+  // Create intent using keypair and recipient's public key, and include user contexts
+  const intent = await createSignedIntent(
+    senderKeypair,
+    recipientUser.wallet.publicKey,
+    amount,
+    connection,
+    { ...options, fromUser: senderCtx, toUser: recipientCtx }
+  );
+
+  // Ensure user contexts are present on return (for backward compatibility)
+  intent.fromUser = senderCtx;
+  intent.toUser = recipientCtx;
+
+  return intent;
+}
+
 /**
  * Creates a signed intent that can be verified offline
  */
@@ -159,6 +244,9 @@ export async function createSignedIntent(
     id: uuidv4(),
     from: sender.publicKey.toBase58(),
     to: recipient.toBase58(),
+    // Include optional user contexts when provided
+    ...(options.fromUser ? { fromUser: options.fromUser } : {}),
+    ...(options.toUser ? { toUser: options.toUser } : {}),
     amount,
     nonce,
     expiry: now + (options.expiresIn || defaultExpiry),

package/src/nfc.ts

@@ -1,5 +1,5 @@
 // src/nfc.ts
-import NfcManager, { NfcTech, Ndef } from "react-native-nfc-manager";
+import NfcManager, { NfcTech, Ndef } from 'react-native-nfc-manager';
 import type { TossUser } from './types/tossUser';
 import type { SolanaIntent } from './intent';
 
@@ -14,11 +14,11 @@ export async function readNFCUser(): Promise<TossUser> {
     await NfcManager.requestTechnology(NfcTech.Ndef);
     const tag = await NfcManager.getTag();
     await NfcManager.cancelTechnologyRequest();
-    
+
     if (!tag?.ndefMessage?.[0]?.payload) {
       throw new Error('No NDEF message found');
     }
-    
+
     const message = Ndef.uri.decodePayload(tag.ndefMessage[0].payload as any);
     return JSON.parse(message) as TossUser;
   } catch (ex: unknown) {
@@ -54,4 +54,4 @@ export async function writeIntentToNFC(intent: SolanaIntent): Promise<boolean> {
     await NfcManager.cancelTechnologyRequest();
     throw new Error(`Failed to write intent to NFC: ${String(ex)}`);
   }
-}
+}

package/src/noise.ts

@@ -1,4 +1,4 @@
-import { noise } from "@chainsafe/libp2p-noise";
+import { noise } from '@chainsafe/libp2p-noise';
 
 /**
  * Initialize Noise secure session with a static key.

package/src/storage/secureStorage.ts

@@ -24,7 +24,7 @@ export async function secureStoreIntent(intent: SolanaIntent): Promise<void> {
   try {
     const key = `${STORAGE_PREFIX}${intent.id}`;
     await SecureStore.setItemAsync(key, JSON.stringify(intent));
-    
+
     // Update the keys list
     const keys = await getAllKeys();
     if (!keys.includes(key)) {
@@ -74,10 +74,10 @@ export async function removeSecureIntent(intentId: string): Promise<void> {
   try {
     const key = `${STORAGE_PREFIX}${intentId}`;
     await SecureStore.deleteItemAsync(key);
-    
+
     // Update the keys list
     const keys = await getAllKeys();
-    const updatedKeys = keys.filter(k => k !== key);
+    const updatedKeys = keys.filter((k) => k !== key);
     await saveKeys(updatedKeys);
   } catch (error) {
     throw new StorageError('Failed to remove intent', {
@@ -97,4 +97,4 @@ export async function clearAllSecureIntents(): Promise<void> {
   } catch (error) {
     throw new StorageError('Failed to clear all intents', { cause: error });
   }
-}
+}

package/src/storage.ts

@@ -1,15 +1,15 @@
-import AsyncStorage from "@react-native-async-storage/async-storage";
+import AsyncStorage from '@react-native-async-storage/async-storage';
 
-const INTENTS_KEY = "TOSS_PENDING_INTENTS";
+const INTENTS_KEY = 'TOSS_PENDING_INTENTS';
 
 export async function storePendingIntent(intent: any) {
-  const current = JSON.parse((await AsyncStorage.getItem(INTENTS_KEY)) || "[]");
+  const current = JSON.parse((await AsyncStorage.getItem(INTENTS_KEY)) || '[]');
   current.push(intent);
   await AsyncStorage.setItem(INTENTS_KEY, JSON.stringify(current));
 }
 
 export async function getPendingIntents() {
-  return JSON.parse((await AsyncStorage.getItem(INTENTS_KEY)) || "[]");
+  return JSON.parse((await AsyncStorage.getItem(INTENTS_KEY)) || '[]');
 }
 
 export async function clearPendingIntents() {