toss-expo-sdk 0.1.0

package/src/examples/offlinePaymentFlow.ts

@@ -0,0 +1,331 @@
+/**
+ * Complete Offline Payment Flow Example
+ *
+ * Demonstrates the full TOSS lifecycle per Section 12 of the Technical Paper:
+ * 1. Sender constructs and signs payment intent
+ * 2. Intent is exchanged offline via BLE/NFC/QR
+ * 3. Both devices store pending intent
+ * 4. When connectivity is restored, devices reconcile
+ * 5. Intent is submitted onchain with deterministic outcome
+ */
+
+import { Connection, Keypair, PublicKey } from '@solana/web3.js';
+import { createIntent, type SolanaIntent, verifyIntent } from '../intent';
+import {
+  secureStoreIntent,
+  getAllSecureIntents,
+} from '../storage/secureStorage';
+import {
+  deviceDiscovery,
+  intentExchange,
+  MultiDeviceConflictResolver,
+  type PeerDevice,
+} from '../discovery';
+import { syncToChain } from '../sync';
+import { TossError } from '../errors';
+
+/**
+ * Example: Sender initiates offline payment
+ *
+ * This simulates a sender who wants to send lamports to a recipient
+ * while offline. The intent is created, signed, and stored locally.
+ */
+export async function exampleInitiateOfflinePayment(
+  senderKeypair: Keypair,
+  recipientAddress: string,
+  amountLamports: number,
+  connection: Connection
+): Promise<SolanaIntent> {
+  console.log('📝 Creating offline payment intent...');
+
+  // Create the intent (this is done offline, no network needed)
+  const intent = await createIntent(
+    senderKeypair,
+    new PublicKey(recipientAddress),
+    amountLamports,
+    connection,
+    {
+      expiresIn: 24 * 60 * 60, // Valid for 24 hours
+    }
+  );
+
+  console.log(`✅ Intent created: ${intent.id}`);
+  console.log(`   From: ${intent.from}`);
+  console.log(`   To: ${intent.to}`);
+  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: Intent exchange via proximity (BLE/NFC)
+ *
+ * One device has an intent it wants to share with a nearby peer.
+ * This demonstrates the intent exchange protocol.
+ */
+export async function exampleExchangeIntentWithPeer(
+  intent: SolanaIntent,
+  localDeviceId: string,
+  peerDeviceId: string,
+  peerDevice: PeerDevice
+): Promise<void> {
+  console.log('📡 Initiating intent exchange with peer...');
+  console.log(`   Local Device: ${localDeviceId}`);
+  console.log(`   Peer Device: ${peerDeviceId}`);
+
+  // Register the peer
+  deviceDiscovery.registerPeer(peerDevice);
+  console.log(`✅ Peer registered: ${peerDevice.id}`);
+
+  // Create an exchange request
+  const exchangeRequest = intentExchange.createRequest(
+    intent,
+    localDeviceId,
+    undefined,
+    5 * 60 // 5 minute expiry
+  );
+
+  console.log(`📨 Exchange request created: ${exchangeRequest.requestId}`);
+  console.log(`   Intent ID: ${intent.id}`);
+  console.log(`   Amount: ${intent.amount} lamports`);
+
+  // In a real scenario, this request would be transmitted via BLE/NFC/QR
+  // For this example, we'll simulate the peer receiving and accepting it
+
+  // Simulate peer accepting the request
+  const response = intentExchange.createResponse(
+    exchangeRequest.requestId,
+    peerDeviceId,
+    'accepted',
+    undefined,
+    [intent.id]
+  );
+
+  console.log(`\n✅ Peer accepted exchange`);
+  console.log(`   Status: ${response.status}`);
+  console.log(
+    `   Acknowledged intents: ${response.acknowledgedIntentIds?.join(', ')}\n`
+  );
+
+  // In a real app, the peer would now have the intent in their local storage
+}
+
+/**
+ * Example: Multiple devices create conflicting intents
+ *
+ * Demonstrates TOSS's deterministic conflict resolution when
+ * multiple offline devices create intents for the same action.
+ */
+export async function exampleMultiDeviceConflict(
+  connection: Connection
+): Promise<void> {
+  console.log('🔄 Simulating multi-device conflict scenario...\n');
+
+  // Create keypair for "Device A"
+  const senderKeypair = Keypair.generate();
+  const recipient = new PublicKey('11111111111111111111111111111111');
+  const amount = 1000000; // 0.001 SOL
+
+  // Both devices create identical intents (same sender, recipient, amount)
+  // but at slightly different times
+  const intentA = await createIntent(
+    senderKeypair,
+    recipient,
+    amount,
+    connection,
+    { expiresIn: 3600 }
+  );
+
+  // Simulate Device B creating same intent 1 second later
+  await new Promise((resolve) => setTimeout(resolve, 1000));
+
+  const intentB = await createIntent(
+    senderKeypair, // Same sender!
+    recipient,
+    amount,
+    connection,
+    { expiresIn: 3600 }
+  );
+
+  console.log('❌ Conflict Detected!');
+  console.log(
+    `   Device A created intent: ${intentA.id} at ${intentA.createdAt}`
+  );
+  console.log(
+    `   Device B created intent: ${intentB.id} at ${intentB.createdAt}`
+  );
+  console.log(`   Both intents: Same sender, same recipient, same amount\n`);
+
+  // Use the conflict resolver
+  const conflictingIntents = [intentA, intentB];
+  const resolution =
+    MultiDeviceConflictResolver.resolveConflicts(conflictingIntents);
+
+  console.log('⚖️ Deterministic Resolution Applied:');
+  console.log(`   Winner: ${resolution.winner.id}`);
+  console.log(`   Winner nonce: ${resolution.winner.nonce}`);
+  console.log(
+    `   Winner timestamp: ${new Date(resolution.winner.createdAt * 1000).toISOString()}`
+  );
+
+  console.log(
+    `\n   Losers: ${resolution.losers.map((i: SolanaIntent) => i.id).join(', ')}`
+  );
+  console.log(`   (These intents will be marked failed during settlement)\n`);
+}
+
+/**
+ * Example: Full offline-to-settlement flow
+ *
+ * Shows the complete journey of an intent from creation to onchain settlement.
+ */
+export async function exampleCompleteOfflineFlow(
+  senderKeypair: Keypair,
+  recipientAddress: string,
+  amountLamports: number,
+  connection: Connection
+): Promise<void> {
+  console.log('='.repeat(60));
+  console.log('🚀 TOSS Complete Offline Payment Flow');
+  console.log('='.repeat(60) + '\n');
+
+  try {
+    // Step 1: Create intent offline
+    console.log('STEP 1: Offline Intent Creation');
+    console.log('-'.repeat(60));
+    const intent = await exampleInitiateOfflinePayment(
+      senderKeypair,
+      recipientAddress,
+      amountLamports,
+      connection
+    );
+
+    // Step 2: Simulate peer device discovery and exchange
+    console.log('STEP 2: Peer Discovery & Intent Exchange');
+    console.log('-'.repeat(60));
+    const peerDevice: PeerDevice = {
+      id: 'device_peer_001',
+      lastSeen: Date.now(),
+      transport: 'ble',
+      signalStrength: -45, // dBm
+      trustScore: 75,
+    };
+
+    await exampleExchangeIntentWithPeer(
+      intent,
+      'device_local_001',
+      'device_peer_001',
+      peerDevice
+    );
+
+    // Step 3: Device reconnects and initiates synchronisation
+    console.log('STEP 3: Synchronisation with Solana');
+    console.log('-'.repeat(60));
+    console.log('📱 Device reconnected to network...');
+    console.log('🔄 Initiating sync with Solana blockchain...\n');
+
+    // Check sync status
+    const syncResult = await syncToChain(connection);
+
+    console.log('📊 Sync Results:');
+    console.log(
+      `   Successful settlements: ${syncResult.successfulSettlements.length}`
+    );
+    console.log(
+      `   Failed settlements: ${syncResult.failedSettlements.length}`
+    );
+    console.log(
+      `   Detected conflicts: ${syncResult.detectedConflicts.length}`
+    );
+    console.log(`   Overall complete: ${syncResult.isComplete}\n`);
+
+    if (syncResult.successfulSettlements.length > 0) {
+      console.log('✅ Successful Settlements:');
+      for (const settlement of syncResult.successfulSettlements) {
+        console.log(`   Intent ${settlement.intentId}`);
+        console.log(`   Signature: ${settlement.signature}`);
+        console.log(
+          `   Timestamp: ${new Date(settlement.timestamp * 1000).toISOString()}`
+        );
+      }
+      console.log();
+    }
+
+    if (syncResult.failedSettlements.length > 0) {
+      console.log('❌ Failed Settlements:');
+      for (const settlement of syncResult.failedSettlements) {
+        console.log(`   Intent ${settlement.intentId}`);
+        console.log(`   Reason: ${settlement.error}`);
+      }
+      console.log();
+    }
+
+    if (syncResult.detectedConflicts.length > 0) {
+      console.log('⚠️ Detected Conflicts:');
+      for (const conflict of syncResult.detectedConflicts) {
+        console.log(`   Intent ${conflict.intentId}: ${conflict.conflict}`);
+      }
+      console.log();
+    }
+
+    // Step 4: Verify final state
+    console.log('STEP 4: Final State Verification');
+    console.log('-'.repeat(60));
+    const allIntents = await getAllSecureIntents();
+    const settledIntents = allIntents.filter(
+      (i: SolanaIntent) => i.status === 'settled'
+    );
+    const failedIntents = allIntents.filter(
+      (i: SolanaIntent) => i.status === 'failed'
+    );
+
+    console.log(`📦 Intent Storage:
+   Total intents: ${allIntents.length}
+   Settled: ${settledIntents.length}
+   Failed: ${failedIntents.length}\n`);
+
+    console.log('✨ Flow complete!\n');
+    console.log('='.repeat(60));
+  } catch (error) {
+    console.error('❌ Error during offline flow:', error);
+    if (error instanceof TossError) {
+      console.error(`   Error code: ${(error as TossError).code}`);
+    }
+  }
+}
+
+/**
+ * Example: Verify intent before exchange
+ *
+ * Good practice: receivers should verify intent signatures
+ * before accepting and storing them.
+ */
+export async function exampleVerifyIntentBeforeAcceptance(
+  intent: SolanaIntent,
+  connection: Connection
+): Promise<boolean> {
+  console.log('🔐 Verifying intent signature...');
+
+  try {
+    const isValid = await verifyIntent(intent, connection);
+
+    if (isValid) {
+      console.log('✅ Intent signature is valid');
+      console.log(`   From: ${intent.from}`);
+      console.log(`   To: ${intent.to}`);
+      console.log(`   Amount: ${intent.amount} lamports`);
+      return true;
+    } else {
+      console.log('❌ Intent signature is invalid');
+      return false;
+    }
+  } catch (error) {
+    console.error('❌ Verification failed:', error);
+    return false;
+  }
+}

package/src/index.tsx

@@ -0,0 +1,61 @@
+// Core types and intents
+export { createIntent, type SolanaIntent, type IntentStatus } from './intent';
+
+// Intent management
+export {
+  verifyIntentSignature,
+  isIntentExpired,
+  updateIntentStatus,
+  validateIntent,
+  processIntentsForSync,
+  filterExpiredIntents,
+} from './intentManager';
+
+// Storage
+export {
+  storePendingIntent,
+  getPendingIntents,
+  clearPendingIntents,
+} from './storage';
+
+// Transport methods
+export { startTossScan, requestBLEPermissions } from './ble';
+export { initNFC, readNFCUser, writeUserToNFC, writeIntentToNFC } from './nfc';
+export { QRScanner } from './qr';
+
+// Client
+export { TossClient, type TossConfig } from './client/TossClient';
+
+// Create client instance
+import { TossClient } from './client/TossClient';
+export const createClient = TossClient.createClient;
+
+// Sync and settlement
+export { syncToChain, checkSyncStatus, type SyncResult } from './sync';
+
+// Reconciliation and conflict detection
+export {
+  reconcilePendingIntents,
+  settleIntent,
+  validateIntentOnchain,
+  buildTransactionFromIntent,
+  submitTransactionToChain,
+  detectConflicts,
+  getReconciliationState,
+  type SettlementResult,
+  type ReconciliationState,
+} from './reconciliation';
+
+// Device discovery and intent exchange
+export {
+  DeviceDiscoveryService,
+  IntentExchangeProtocol,
+  IntentRoutingService,
+  MultiDeviceConflictResolver,
+  deviceDiscovery,
+  intentExchange,
+  intentRouting,
+  type PeerDevice,
+  type IntentExchangeRequest,
+  type IntentExchangeResponse,
+} from './discovery';

package/src/intent.ts

@@ -0,0 +1,328 @@
+import { PublicKey, Keypair, Connection } from '@solana/web3.js';
+import type { AccountInfo } from '@solana/web3.js';
+import bs58 from 'bs58';
+import { v4 as uuidv4 } from 'uuid';
+import { sign } from 'tweetnacl';
+import nacl from 'tweetnacl';
+import {
+  encryptForArciumInternal,
+  type ArciumEncryptedOutput,
+} from './internal/arciumHelper';
+// Nonce management now handled internally
+
+/**
+ * Status of an intent in its lifecycle
+ */
+export type IntentStatus = 'pending' | 'settled' | 'failed' | 'expired';
+
+/**
+ * Core type for an offline intent following TOSS specification
+ */
+export interface SolanaIntent {
+  // Core fields
+  id: string; // Unique identifier for the intent
+  from: string; // Sender's public key
+  to: string; // Recipient's public key
+  amount: number; // Amount in lamports
+  nonce: number; // For replay protection
+  expiry: number; // Unix timestamp in seconds
+  signature: string; // Signature of the intent
+  status: IntentStatus;
+  createdAt: number;
+  updatedAt: number;
+  error?: string;
+
+  // Transaction metadata
+  blockhash?: string; // Optional: For transaction construction
+  feePayer?: string; // Optional: Public key of fee payer
+  signatures?: string[]; // Optional: Transaction signatures
+  serialized?: string; // Optional: Serialized transaction
+  nonceAccount?: string; // Optional: Public key of the nonce account
+  nonceAuth?: string; // Optional: Public key authorized to use the nonce
+
+  // Privacy features
+  encrypted?: ArciumEncryptedOutput; // Optional encrypted payload
+}
+
+/**
+ * Options for creating a new intent
+ */
+export interface CreateIntentOptions {
+  /** Whether to encrypt the transaction details using Arcium */
+  privateTransaction?: boolean;
+  /** Program ID for Arcium encryption */
+  mxeProgramId?: PublicKey;
+  /** Provider for blockchain access */
+  provider?: any; // AnchorProvider or similar
+  /** Expiry time in seconds from now (default: 1 hour) */
+  expiresIn?: number;
+  /** Custom nonce (auto-generated if not provided) */
+  nonce?: number;
+  /** Keypair for the nonce account (for durable transactions) */
+  nonceAccount?: Keypair;
+  /** Public key authorized to use the nonce account */
+  nonceAuth?: PublicKey;
+  /** Fee payer for the transaction (defaults to sender) */
+  feePayer?: PublicKey | string;
+}
+
+/**
+ * Manages nonce values for transaction replay protection
+ */
+class NonceManager {
+  private nonceStore: Map<string, { nonce: number; lastUsed: number }> =
+    new Map();
+  private readonly NONCE_EXPIRY = 5 * 60 * 1000; // 5 minutes
+
+  async getNextNonce(
+    publicKey: PublicKey,
+    connection: Connection
+  ): Promise<number> {
+    const key = publicKey.toBase58();
+    const now = Date.now();
+
+    // Clean up old nonces
+    this.cleanupNonces();
+
+    try {
+      // Get nonce from chain
+      const accountInfo = await connection.getAccountInfo(publicKey);
+      const chainNonce = accountInfo
+        ? this.extractNonceFromAccountInfo(accountInfo)
+        : 0;
+
+      // Get or initialize stored nonce
+      const stored = this.nonceStore.get(key) || {
+        nonce: chainNonce,
+        lastUsed: now,
+      };
+      const nextNonce = Math.max(stored.nonce + 1, chainNonce + 1);
+
+      // Update store
+      this.nonceStore.set(key, { nonce: nextNonce, lastUsed: now });
+      return nextNonce;
+    } catch (error) {
+      console.warn(
+        'Failed to get nonce from chain, using in-memory nonce',
+        error
+      );
+      const stored = this.nonceStore.get(key) || { nonce: 0, lastUsed: now };
+      const nextNonce = stored.nonce + 1;
+      this.nonceStore.set(key, { nonce: nextNonce, lastUsed: now });
+      return nextNonce;
+    }
+  }
+
+  private extractNonceFromAccountInfo(
+    accountInfo: AccountInfo<Buffer>
+  ): number {
+    // For SystemProgram accounts, nonce is typically stored in the first 8 bytes
+    const data = accountInfo.data;
+    return data?.length >= 8 ? data.readUInt32LE(0) : 0;
+  }
+
+  private cleanupNonces() {
+    const now = Date.now();
+    for (const [key, value] of this.nonceStore.entries()) {
+      if (now - value.lastUsed > this.NONCE_EXPIRY) {
+        this.nonceStore.delete(key);
+      }
+    }
+  }
+}
+
+export const nonceManager = new NonceManager();
+
+/**
+ * Creates a signed intent that can be verified offline
+ */
+export async function createSignedIntent(
+  sender: Keypair,
+  recipient: PublicKey,
+  amount: number,
+  connection: Connection,
+  options: CreateIntentOptions = {}
+): Promise<SolanaIntent> {
+  const now = Math.floor(Date.now() / 1000);
+  const defaultExpiry = 24 * 60 * 60; // 24 hours default
+
+  // Get latest blockhash and nonce
+  const [{ blockhash }, nonce] = await Promise.all([
+    connection.getLatestBlockhash(),
+    options.nonce !== undefined
+      ? Promise.resolve(options.nonce)
+      : nonceManager.getNextNonce(sender.publicKey, connection),
+  ]);
+
+  // Create base intent
+  const baseIntent: Omit<SolanaIntent, 'signature'> = {
+    id: uuidv4(),
+    from: sender.publicKey.toBase58(),
+    to: recipient.toBase58(),
+    amount,
+    nonce,
+    expiry: now + (options.expiresIn || defaultExpiry),
+    blockhash,
+    feePayer: options.nonceAuth?.toBase58() || sender.publicKey.toBase58(),
+    status: 'pending',
+    createdAt: now,
+    updatedAt: now,
+    ...(options.nonceAccount && options.nonceAuth
+      ? {
+          nonceAccount: options.nonceAccount.publicKey.toBase58(),
+          nonceAuth: options.nonceAuth.toBase58(),
+        }
+      : {}),
+  };
+
+  // Sign the intent
+  const signature = sign(
+    Buffer.from(JSON.stringify(baseIntent)),
+    sender.secretKey
+  );
+
+  return {
+    ...baseIntent,
+    signature: bs58.encode(signature),
+  };
+}
+
+/**
+ * Verifies the signature, nonce, and expiry of an intent
+ */
+export async function verifyIntent(
+  intent: SolanaIntent,
+  connection?: Connection
+): Promise<boolean> {
+  try {
+    // Basic validation
+    if (!intent.signature || !intent.from || !intent.to) {
+      return false;
+    }
+
+    // Check if intent is expired
+    if (isIntentExpired(intent)) {
+      return false;
+    }
+
+    // Verify signature
+    const signature = bs58.decode(intent.signature);
+    const message = Buffer.from(
+      JSON.stringify({ ...intent, signature: undefined })
+    );
+    const publicKey = new PublicKey(intent.from).toBytes();
+
+    try {
+      // Use nacl.sign.detached.verify for detached signature verification
+      // Requires: message, detached signature, public key
+      const publicKeyUint8 = new Uint8Array(publicKey);
+      const signatureUint8 = new Uint8Array(signature);
+
+      const verified = nacl.sign.detached.verify(
+        Buffer.from(message),
+        signatureUint8,
+        publicKeyUint8
+      );
+
+      if (!verified) {
+        return false;
+      }
+    } catch (error) {
+      console.error('Signature verification failed:', error);
+      return false;
+    }
+
+    // Verify nonce if connection is provided
+    if (connection) {
+      try {
+        const accountInfo = await connection.getAccountInfo(
+          new PublicKey(intent.from)
+        );
+        if (accountInfo) {
+          const currentNonce =
+            accountInfo.data?.length >= 8
+              ? accountInfo.data.readUInt32LE(0)
+              : 0;
+          if (intent.nonce <= currentNonce) {
+            return false; // Nonce too low or reused
+          }
+        }
+      } catch (error) {
+        console.warn('Failed to verify nonce:', error);
+        // Continue without nonce verification if we can't check the chain
+      }
+    }
+
+    return true;
+  } catch (error) {
+    console.error('Intent verification failed:', error);
+    return false;
+  }
+}
+
+/**
+ * Creates an offline Solana intent following TOSS specification.
+ * If privateTransaction is true, encrypts internal data with Arcium.
+ */
+export async function createIntent(
+  sender: Keypair,
+  recipient: PublicKey,
+  amount: number,
+  connection: Connection,
+  options: CreateIntentOptions = {}
+): Promise<SolanaIntent> {
+  // First create and sign the intent
+  const intent = await createSignedIntent(
+    sender,
+    recipient,
+    amount,
+    connection,
+    options
+  );
+
+  // If private transaction, encrypt the intent data
+  if (options.privateTransaction) {
+    if (!options.mxeProgramId) {
+      throw new Error('MXE Program ID is required for private transactions');
+    }
+    if (!options.provider) {
+      throw new Error('Provider is required for private transactions');
+    }
+
+    const plaintextValues: bigint[] = [
+      BigInt(amount),
+      // Include additional fields for privacy as needed
+    ];
+
+    intent.encrypted = await encryptForArciumInternal(
+      options.mxeProgramId,
+      plaintextValues,
+      options.provider
+    );
+  }
+
+  return intent;
+}
+
+/**
+ * Checks if an intent has expired
+ */
+export function isIntentExpired(intent: SolanaIntent): boolean {
+  return intent.expiry <= Math.floor(Date.now() / 1000);
+}
+
+/**
+ * Updates the status of an intent
+ */
+export function updateIntentStatus(
+  intent: SolanaIntent,
+  status: IntentStatus,
+  error?: string
+): SolanaIntent {
+  return {
+    ...intent,
+    status,
+    error,
+    updatedAt: Math.floor(Date.now() / 1000),
+  };
+}