toss-expo-sdk 0.1.0

package/src/storage/secureStorage.ts

@@ -0,0 +1,100 @@
+import * as SecureStore from 'expo-secure-store';
+import { StorageError } from '../errors';
+import type { SolanaIntent } from '../intent';
+
+const STORAGE_PREFIX = 'toss_intent_';
+
+// Helper function to get all keys
+async function getAllKeys(): Promise<string[]> {
+  // expo-secure-store doesn't have a direct way to get all keys,
+  // so we'll need to track them manually
+  const keys = await SecureStore.getItemAsync(`${STORAGE_PREFIX}_keys`);
+  return keys ? JSON.parse(keys) : [];
+}
+
+// Helper function to save all keys
+async function saveKeys(keys: string[]): Promise<void> {
+  await SecureStore.setItemAsync(
+    `${STORAGE_PREFIX}_keys`,
+    JSON.stringify(keys)
+  );
+}
+
+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)) {
+      keys.push(key);
+      await saveKeys(keys);
+    }
+  } catch (error) {
+    throw new StorageError('Failed to store intent securely', {
+      cause: error,
+      intentId: intent.id,
+    });
+  }
+}
+
+export async function getSecureIntent(
+  intentId: string
+): Promise<SolanaIntent | null> {
+  try {
+    const value = await SecureStore.getItemAsync(
+      `${STORAGE_PREFIX}${intentId}`
+    );
+    return value ? JSON.parse(value) : null;
+  } catch (error) {
+    throw new StorageError('Failed to retrieve intent', {
+      cause: error,
+      intentId,
+    });
+  }
+}
+
+export async function getAllSecureIntents(): Promise<SolanaIntent[]> {
+  try {
+    const keys = await getAllKeys();
+    const intents = await Promise.all(
+      keys.map(async (key: string) => {
+        const value = await SecureStore.getItemAsync(key);
+        return value ? JSON.parse(value) : null;
+      })
+    );
+    return intents.filter(Boolean);
+  } catch (error) {
+    throw new StorageError('Failed to retrieve all intents', { cause: error });
+  }
+}
+
+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);
+    await saveKeys(updatedKeys);
+  } catch (error) {
+    throw new StorageError('Failed to remove intent', {
+      cause: error,
+      intentId,
+    });
+  }
+}
+
+export async function clearAllSecureIntents(): Promise<void> {
+  try {
+    const keys = await getAllKeys();
+    await Promise.all(
+      keys.map((key: string) => SecureStore.deleteItemAsync(key))
+    );
+    await saveKeys([]);
+  } catch (error) {
+    throw new StorageError('Failed to clear all intents', { cause: error });
+  }
+}

package/src/storage.ts

@@ -0,0 +1,17 @@
+import AsyncStorage from "@react-native-async-storage/async-storage";
+
+const INTENTS_KEY = "TOSS_PENDING_INTENTS";
+
+export async function storePendingIntent(intent: any) {
+  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)) || "[]");
+}
+
+export async function clearPendingIntents() {
+  await AsyncStorage.removeItem(INTENTS_KEY);
+}

package/src/sync.ts

@@ -0,0 +1,101 @@
+/**
+ * Synchronisation with Solana Blockchain
+ *
+ * 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.
+ */
+
+import { Connection, PublicKey } from '@solana/web3.js';
+import {
+  reconcilePendingIntents,
+  detectConflicts,
+  getReconciliationState,
+  type SettlementResult,
+  type ReconciliationState,
+} from './reconciliation';
+import { NetworkError } from './errors';
+
+export interface SyncResult {
+  // Intents that were successfully settled onchain
+  successfulSettlements: SettlementResult[];
+  // Intents that were rejected or failed
+  failedSettlements: SettlementResult[];
+  // Conflicts detected during reconciliation
+  detectedConflicts: { intentId: string; conflict: string }[];
+  // Overall reconciliation state
+  reconciliationState: ReconciliationState;
+  // Timestamp of sync
+  syncTimestamp: number;
+  // Whether sync was successful (all intents processed)
+  isComplete: boolean;
+}
+
+/**
+ * Full sync and reconciliation with the Solana blockchain
+ *
+ * This is the primary function for TOSS settlement. When a device regains
+ * connectivity, it calls this to:
+ * 1. Detect any conflicts with onchain state
+ * 2. Settle all pending intents
+ * 3. Update local state with results
+ *
+ * @param connection Connection to Solana RPC
+ * @param feePayer Optional fee payer keypair public key
+ * @returns Detailed sync results including conflicts and settlements
+ */
+export async function syncToChain(
+  connection: Connection,
+  feePayer?: PublicKey
+): Promise<SyncResult> {
+  const syncTimestamp = Math.floor(Date.now() / 1000);
+
+  try {
+    // Step 1: Detect any conflicts with onchain state
+    const detectedConflicts = await detectConflicts(connection);
+
+    // Step 2: Reconcile and settle all pending intents
+    const allSettlementResults = await reconcilePendingIntents(
+      connection,
+      feePayer
+    );
+
+    // Step 3: Separate successful and failed settlements
+    const successfulSettlements = allSettlementResults.filter(
+      (r) => r.status === 'success'
+    );
+    const failedSettlements = allSettlementResults.filter(
+      (r) => r.status !== 'success'
+    );
+
+    // Step 4: Get final reconciliation state
+    const reconciliationState = await getReconciliationState(connection);
+
+    const isComplete =
+      failedSettlements.length === 0 && detectedConflicts.length === 0;
+
+    return {
+      successfulSettlements,
+      failedSettlements,
+      detectedConflicts,
+      reconciliationState,
+      syncTimestamp,
+      isComplete,
+    };
+  } catch (error) {
+    throw new NetworkError(
+      `Sync to chain failed: ${error instanceof Error ? error.message : String(error)}`,
+      { cause: error }
+    );
+  }
+}
+
+/**
+ * Lightweight sync to check status without settling
+ * Useful for monitoring or UI updates without committing to settlements
+ */
+export async function checkSyncStatus(
+  connection: Connection
+): Promise<ReconciliationState> {
+  return getReconciliationState(connection);
+}

package/src/types/tossUser.ts

@@ -0,0 +1,81 @@
+import { PublicKey } from '@solana/web3.js';
+
+/**
+ * Represents a TOSS wallet user in the ecosystem
+ */
+export type TossUser = {
+  // Core Identity
+  userId: string; // TOSS internal ID (e.g., 'toss_123')
+  username: string; // @handle format (e.g., '@alice')
+  displayName?: string; // Optional display name
+
+  // TOSS Wallet
+  wallet: {
+    publicKey: PublicKey; // Main wallet address
+    isVerified: boolean; // KYC/verification status
+    createdAt: string; // ISO timestamp
+  };
+
+  // Device & Session
+  device: {
+    id: string; // Unique device ID
+    name?: string; // User-defined device name
+    lastActive: string; // ISO timestamp
+    client: 'mobile' | 'web' | 'desktop';
+  };
+
+  // Status
+  status: 'active' | 'inactive' | 'restricted';
+  lastSeen: string; // ISO timestamp
+
+  // TOSS-specific
+  tossFeatures: {
+    canSend: boolean;
+    canReceive: boolean;
+    isPrivateTxEnabled: boolean;
+    maxTransactionAmount: number; // In lamports
+  };
+
+  // Timestamps
+  createdAt: string;
+  updatedAt: string;
+};
+
+/**
+ * Minimal user info for transaction context
+ */
+export type TossUserContext = Pick<
+  TossUser,
+  'userId' | 'username' | 'wallet' | 'status'
+> & {
+  deviceId: string;
+  sessionId: string;
+};
+
+// Example usage
+export const exampleTossUser: TossUser = {
+  userId: 'toss_abc123',
+  username: '@alice',
+  displayName: 'Alice',
+  wallet: {
+    publicKey: new PublicKey('11111111111111111111111111111111'), // Example key
+    isVerified: true,
+    createdAt: '2023-01-01T00:00:00Z',
+  },
+  device: {
+    id: 'dev_xyz789',
+    name: 'Alice iPhone',
+    lastActive: new Date().toISOString(),
+    client: 'mobile',
+  },
+  status: 'active',
+  lastSeen: new Date().toISOString(),
+  tossFeatures: {
+    canSend: true,
+    canReceive: true,
+    isPrivateTxEnabled: true,
+    maxTransactionAmount: 1000000000, // 1 SOL in lamports
+  },
+  createdAt: '2023-01-01T00:00:00Z',
+  updatedAt: new Date().toISOString(),
+};

package/src/utils/nonceUtils.ts

@@ -0,0 +1,56 @@
+import {
+  SystemProgram,
+  PublicKey,
+  Transaction,
+  Connection,
+  Keypair,
+  LAMPORTS_PER_SOL,
+} from '@solana/web3.js';
+
+export async function createNonceAccount(
+  connection: Connection,
+  feePayer: Keypair,
+  nonceAccount: Keypair = Keypair.generate(),
+  amount = 1 * LAMPORTS_PER_SOL // 1 SOL should be enough for many transactions
+): Promise<{ nonceAccount: Keypair; nonceAuth: PublicKey }> {
+  const nonceAuth = feePayer.publicKey;
+  const tx = new Transaction().add(
+    SystemProgram.createAccount({
+      fromPubkey: feePayer.publicKey,
+      newAccountPubkey: nonceAccount.publicKey,
+      lamports: amount,
+      space: 80, // Size of nonce account
+      programId: SystemProgram.programId,
+    }),
+    SystemProgram.nonceInitialize({
+      noncePubkey: nonceAccount.publicKey,
+      authorizedPubkey: nonceAuth,
+    })
+  );
+
+  tx.recentBlockhash = (await connection.getLatestBlockhash()).blockhash;
+  tx.feePayer = feePayer.publicKey;
+  tx.sign(feePayer, nonceAccount);
+
+  await connection.sendRawTransaction(tx.serialize());
+  return { nonceAccount, nonceAuth };
+}
+
+export async function getNonce(
+  connection: Connection,
+  nonceAccount: PublicKey
+): Promise<string> {
+  const accountInfo = await connection.getAccountInfo(nonceAccount);
+  if (!accountInfo) throw new Error('Nonce account not found');
+  return accountInfo.data.slice(32, 64).toString('hex');
+}
+
+export function createNonceAdvanceInstruction(
+  noncePubkey: PublicKey,
+  authorizedPubkey: PublicKey
+) {
+  return SystemProgram.nonceAdvance({
+    noncePubkey,
+    authorizedPubkey,
+  });
+}