toss-expo-sdk 0.1.2 → 1.0.1

package/src/storage/secureStorage.ts

@@ -98,3 +98,141 @@ export async function clearAllSecureIntents(): Promise<void> {
     throw new StorageError('Failed to clear all intents', { cause: error });
   }
 }
+
+/**
+ * GAP #1: Cleanup expired intents from local storage
+ * Per TOSS Paper Section 8: Local state is append-only until settlement confirmation
+ */
+export async function cleanupExpiredIntents(): Promise<number> {
+  try {
+    const intents = await getAllSecureIntents();
+    const now = Math.floor(Date.now() / 1000);
+    let cleanedCount = 0;
+
+    for (const intent of intents) {
+      if (intent.expiry < now) {
+        await removeSecureIntent(intent.id);
+        cleanedCount++;
+      }
+    }
+
+    return cleanedCount;
+  } catch (error) {
+    throw new StorageError('Failed to cleanup expired intents', {
+      cause: error,
+    });
+  }
+}
+
+/**
+ * GAP #2: Store and retrieve reconciliation state
+ * Per TOSS Paper Section 9: Track which intents have been synced/failed/conflicted
+ */
+const RECONCILIATION_STATE_KEY = 'toss_reconciliation_state_';
+
+export interface ReconciliationStateData {
+  userId: string;
+  lastSyncTime: number;
+  lastSyncSlot: number;
+  processedIntents: string[]; // Intent IDs successfully settled
+  failedIntents: string[]; // Intent IDs that failed/were rejected
+  conflictingIntents: string[]; // Intent IDs with detected conflicts
+}
+
+export async function saveReconciliationState(
+  userId: string,
+  state: Partial<ReconciliationStateData>
+): Promise<void> {
+  try {
+    const key = `${RECONCILIATION_STATE_KEY}${userId}`;
+    const existing = await SecureStore.getItemAsync(key);
+    const currentState: ReconciliationStateData = existing
+      ? JSON.parse(existing)
+      : {
+          userId,
+          lastSyncTime: 0,
+          lastSyncSlot: 0,
+          processedIntents: [],
+          failedIntents: [],
+          conflictingIntents: [],
+        };
+
+    const merged: ReconciliationStateData = {
+      ...currentState,
+      ...state,
+      userId, // Always preserve userId
+    };
+
+    await SecureStore.setItemAsync(key, JSON.stringify(merged));
+  } catch (error) {
+    throw new StorageError('Failed to save reconciliation state', {
+      cause: error,
+      userId,
+    });
+  }
+}
+
+export async function getReconciliationState(
+  userId: string
+): Promise<ReconciliationStateData> {
+  try {
+    const key = `${RECONCILIATION_STATE_KEY}${userId}`;
+    const value = await SecureStore.getItemAsync(key);
+
+    if (value) {
+      return JSON.parse(value);
+    }
+
+    return {
+      userId,
+      lastSyncTime: 0,
+      lastSyncSlot: 0,
+      processedIntents: [],
+      failedIntents: [],
+      conflictingIntents: [],
+    };
+  } catch (error) {
+    throw new StorageError('Failed to retrieve reconciliation state', {
+      cause: error,
+      userId,
+    });
+  }
+}
+
+export async function updateReconciliationState(
+  userId: string,
+  intentId: string,
+  status: 'processed' | 'failed' | 'conflicted'
+): Promise<void> {
+  try {
+    const current = await getReconciliationState(userId);
+
+    // Remove from all lists first
+    current.processedIntents = current.processedIntents.filter(
+      (id) => id !== intentId
+    );
+    current.failedIntents = current.failedIntents.filter(
+      (id) => id !== intentId
+    );
+    current.conflictingIntents = current.conflictingIntents.filter(
+      (id) => id !== intentId
+    );
+
+    // Add to appropriate list
+    if (status === 'processed') {
+      current.processedIntents.push(intentId);
+    } else if (status === 'failed') {
+      current.failedIntents.push(intentId);
+    } else if (status === 'conflicted') {
+      current.conflictingIntents.push(intentId);
+    }
+
+    await saveReconciliationState(userId, current);
+  } catch (error) {
+    throw new StorageError('Failed to update reconciliation state', {
+      cause: error,
+      userId,
+      intentId,
+    });
+  }
+}

package/src/sync.ts

@@ -4,6 +4,8 @@
  * Implements Section 9 of the TOSS Technical Paper:
  * Upon regaining connectivity, devices initiate reconciliation with onchain state.
  * All offline artifacts are verified onchain and settled with deterministic outcomes.
+ *
+ * GAP #2 FIX: Track synchronization state persistently
  */
 
 import { Connection, PublicKey } from '@solana/web3.js';
@@ -14,6 +16,7 @@ import {
   type SettlementResult,
   type ReconciliationState,
 } from './reconciliation';
+import { updateReconciliationState } from './storage/secureStorage';
 import { NetworkError } from './errors';
 
 export interface SyncResult {
@@ -40,12 +43,16 @@ export interface SyncResult {
  * 2. Settle all pending intents
  * 3. Update local state with results
  *
+ * GAP #2 FIX: Persist reconciliation state for future queries
+ *
  * @param connection Connection to Solana RPC
+ * @param userId User ID for state tracking (required for persistence)
  * @param feePayer Optional fee payer keypair public key
  * @returns Detailed sync results including conflicts and settlements
  */
 export async function syncToChain(
   connection: Connection,
+  userId?: string,
   feePayer?: PublicKey
 ): Promise<SyncResult> {
   const syncTimestamp = Math.floor(Date.now() / 1000);
@@ -71,6 +78,39 @@ export async function syncToChain(
     // Step 4: Get final reconciliation state
     const reconciliationState = await getReconciliationState(connection);
 
+    // GAP #2 FIX: Persist reconciliation state to storage
+    if (userId) {
+      try {
+        // Update individual intent statuses
+        for (const settlement of successfulSettlements) {
+          await updateReconciliationState(
+            userId,
+            settlement.intentId,
+            'processed'
+          );
+        }
+        for (const settlement of failedSettlements) {
+          await updateReconciliationState(
+            userId,
+            settlement.intentId,
+            'failed'
+          );
+        }
+        for (const conflict of detectedConflicts) {
+          await updateReconciliationState(
+            userId,
+            conflict.intentId,
+            'conflicted'
+          );
+        }
+      } catch (storageError) {
+        console.warn(
+          'Failed to update reconciliation state storage:',
+          storageError
+        );
+      }
+    }
+
     const isComplete =
       failedSettlements.length === 0 && detectedConflicts.length === 0;
 

package/src/types/nonceAccount.ts

@@ -0,0 +1,75 @@
+/**
+ * Represents a durable nonce account for offline transaction support
+ * Enables secure offline transaction creation with replay protection
+ */
+export interface NonceAccountInfo {
+  // Account Identity
+  address: string; // Public key of the nonce account
+  owner: string; // Public key of owner/authority
+  authorizedSigner: string; // Public key authorized to use this nonce
+
+  // Nonce State
+  currentNonce: number; // Current nonce value
+  lastUsedNonce: number; // Last consumed nonce
+  blockhash: string; // Associated blockhash
+
+  // Security
+  isBiometricProtected: boolean; // Requires biometric to use
+  createdAt: number; // Unix timestamp
+  lastModified: number; // Unix timestamp
+
+  // Storage
+  isStoredSecurely: boolean; // In secure enclave
+  encryptedData?: string; // Optional encrypted backup
+  minRentLamports?: number; // Minimum rent exemption amount
+  status?: 'active' | 'expired' | 'revoked'; // Account lifecycle status
+}
+
+/**
+ * Options for creating a durable nonce account
+ */
+export interface CreateNonceAccountOptions {
+  // Biometric & Security
+  requireBiometric?: boolean; // Default: true (mandatory)
+  securityLevel?: 'standard' | 'high' | 'maximum'; // Default: 'standard'
+
+  // Nonce Config
+  minNonceCount?: number; // Minimum nonces to maintain (default: 1)
+  maxNonceCount?: number; // Maximum nonces to cache (default: 100)
+
+  // Storage
+  persistToSecureStorage?: boolean; // Default: true
+  allowCloudBackup?: boolean; // Default: false
+
+  // Lifecycle
+  autoRenew?: boolean; // Auto-renew when close to expiry (default: true)
+  expiryDays?: number; // Account expiry in days (default: 365)
+}
+
+/**
+ * Nonce account cache entry for efficient offline usage
+ */
+export interface NonceAccountCacheEntry {
+  accountInfo: NonceAccountInfo;
+  nonces: number[];
+  expiresAt: number;
+}
+
+/**
+ * Represents a transaction prepared for offline use with nonce account
+ */
+export interface OfflineTransaction {
+  id: string;
+  nonceAccount: string;
+  nonce: number;
+  transaction: string; // Base64 or serialized transaction
+  signature?: string;
+  status: 'prepared' | 'signed' | 'submitted' | 'confirmed' | 'failed';
+  createdAt: number;
+  expiresAt: number;
+  metadata?: {
+    description?: string;
+    tags?: string[];
+    [key: string]: any;
+  };
+}

package/src/types/tossUser.ts

@@ -2,6 +2,7 @@ import { PublicKey } from '@solana/web3.js';
 
 /**
  * Represents a TOSS wallet user in the ecosystem
+ * Enhanced with secure nonce account support for offline transactions
  */
 export type TossUser = {
   // Core Identity
@@ -9,13 +10,22 @@ export type TossUser = {
   username: string; // @handle format (e.g., '@alice')
   displayName?: string; // Optional display name
 
-  // TOSS Wallet
+  // TOSS Wallet (Primary wallet)
   wallet: {
     publicKey: PublicKey; // Main wallet address
     isVerified: boolean; // KYC/verification status
     createdAt: string; // ISO timestamp
   };
 
+  // Nonce Account (For offline transactions with replay protection)
+  nonceAccount?: {
+    address: PublicKey; // Public key of the nonce account
+    authorizedSigner: PublicKey; // Public key authorized to use this nonce
+    isBiometricProtected: boolean; // Requires biometric authentication
+    expiresAt?: number; // Unix timestamp of expiry
+    status: 'active' | 'expired' | 'revoked'; // Account status
+  };
+
   // Device & Session
   device: {
     id: string; // Unique device ID
@@ -24,16 +34,26 @@ export type TossUser = {
     client: 'mobile' | 'web' | 'desktop';
   };
 
+  // Security & Biometrics
+  security: {
+    biometricEnabled: boolean; // Biometric authentication enabled
+    biometricSalt?: string; // Salt for biometric derivation
+    nonceAccountRequiresBiometric: boolean; // Nonce operations require biometric
+    lastBiometricVerification?: number; // Unix timestamp
+  };
+
   // Status
   status: 'active' | 'inactive' | 'restricted';
   lastSeen: string; // ISO timestamp
 
-  // TOSS-specific
+  // TOSS-specific Features
   tossFeatures: {
     canSend: boolean;
     canReceive: boolean;
     isPrivateTxEnabled: boolean;
     maxTransactionAmount: number; // In lamports
+    offlineTransactionsEnabled?: boolean; // Can create offline transactions
+    nonceAccountEnabled?: boolean; // Has durable nonce account
   };
 
   // Timestamps
@@ -62,12 +82,23 @@ export const exampleTossUser: TossUser = {
     isVerified: true,
     createdAt: '2023-01-01T00:00:00Z',
   },
+  nonceAccount: {
+    address: new PublicKey('22222222222222222222222222222222'),
+    authorizedSigner: new PublicKey('33333333333333333333333333333333'),
+    isBiometricProtected: true,
+    status: 'active',
+  },
   device: {
     id: 'dev_xyz789',
     name: 'Alice iPhone',
     lastActive: new Date().toISOString(),
     client: 'mobile',
   },
+  security: {
+    biometricEnabled: true,
+    nonceAccountRequiresBiometric: true,
+    lastBiometricVerification: Math.floor(Date.now() / 1000),
+  },
   status: 'active',
   lastSeen: new Date().toISOString(),
   tossFeatures: {
@@ -75,6 +106,8 @@ export const exampleTossUser: TossUser = {
     canReceive: true,
     isPrivateTxEnabled: true,
     maxTransactionAmount: 1000000000, // 1 SOL in lamports
+    offlineTransactionsEnabled: true,
+    nonceAccountEnabled: true,
   },
   createdAt: '2023-01-01T00:00:00Z',
   updatedAt: new Date().toISOString(),