toss-expo-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2025 Joshua Idele (Zypp Protocol)
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,292 @@
+# TOSS Expo SDK
+
+**TOSS (The Offline Solana Stack)** is a robust, production-ready SDK for building offline-capable Solana applications with secure local transport and delayed on-chain settlement.
+
+[![npm version](https://img.shields.io/npm/v/toss-expo-sdk)](https://www.npmjs.com/package/toss-expo-sdk)
+[![License](https://img.shields.io/badge/License-Proprietary-blue.svg)](LICENSE)
+
+## 🚀 Features
+
+### Core Capabilities
+
+- **Offline-First Architecture**: Create and process transactions without immediate network access
+- **Secure Wallet Integration**: Built-in wallet management with support for multiple keypairs
+- **Durable Transactions**: Nonce-based transaction handling for reliability
+- **TypeScript Support**: Full TypeScript definitions for better developer experience
+
+### Security
+
+- End-to-end encryption for all transactions
+- Secure key management with hardware wallet support
+- Non-custodial by design - users maintain control of their keys
+
+### Developer Experience
+
+- Simple, intuitive API for common operations
+- Comprehensive error handling with detailed error codes
+- Built-in retry mechanisms with exponential backoff
+- React hooks for easy integration with React Native components
+
+## 📦 Installation
+
+```bash
+# Using npm
+npm install toss-expo-sdk @solana/web3.js
+
+# Using yarn
+yarn add toss-expo-sdk @solana/web3.js
+```
+
+## 🏁 Quick Start
+
+### Initialize the Client
+
+```typescript
+import { TossClient } from 'toss-expo-sdk';
+
+const client = new TossClient({
+  projectId: 'your-project-id',
+  mode: 'devnet', // or 'testnet' | 'mainnet-beta'
+  privateTransactions: true,
+  maxRetries: 3,
+  retryDelay: 1000,
+});
+```
+
+### Create and Send an Intent
+
+```typescript
+// Create a transfer intent
+const intent = await client.createIntent(
+  senderKeypair, // or 'current' to use connected wallet
+  recipientAddress,
+  amountInLamports,
+  {
+    memo: 'Payment for services',
+    useDurableNonce: true,
+  }
+);
+
+// Later, when online
+const syncedIntents = await client.sync();
+```
+
+### Using with React Native
+
+```typescript
+import { WalletProvider, useWallet } from 'toss-expo-sdk';
+
+function App() {
+  return (
+    <WalletProvider>
+      <PaymentScreen />
+    </WalletProvider>
+  );
+}
+
+function PaymentScreen() {
+  const {
+    isConnected,
+    connect,
+    disconnect,
+    signMessage,
+    sendTransaction
+  } = useWallet();
+
+  // ... rest of your component
+}
+```
+
+## Core Idea: Intent, Not Transaction
+
+TOSS uses an **intent-based model**.
+
+An **intent** is:
+
+- a signed declaration of what a user wants to do
+- transferable offline
+- verifiable locally
+- settled later on-chain
+
+This separation allows applications to function **without connectivity** while preserving Solana’s security guarantees.
+
+---
+
+## 🔒 Security
+
+### Best Practices
+
+1. Always verify transaction details before signing
+2. Use the latest version of the SDK
+3. Never expose private keys in client-side code
+4. Implement proper error handling
+
+### Error Handling
+
+The SDK provides detailed error codes for handling various scenarios. All errors extend from the base `TossError` class and include a `code` property for programmatic handling.
+
+#### Error Codes Reference
+
+| Error Code                      | Description                        | When It Occurs                                                   |
+| ------------------------------- | ---------------------------------- | ---------------------------------------------------------------- |
+| `INVALID_INTENT`                | The intent is malformed or invalid | When validating an intent fails due to invalid structure or data |
+| `NETWORK_ERROR`                 | Network-related operation failed   | When a network request fails or times out                        |
+| `STORAGE_ERROR`                 | Local storage operation failed     | When reading/writing to secure storage fails                     |
+| `SIGNATURE_VERIFICATION_FAILED` | Signature verification failed      | When a signature doesn't match the expected value                |
+| `INTENT_EXPIRED`                | The intent has expired             | When processing an intent that's past its expiration time        |
+| `INSUFFICIENT_FUNDS`            | Not enough funds for the operation | When an account has insufficient balance                         |
+| `TRANSACTION_FAILED`            | Transaction processing failed      | When a transaction is rejected by the network                    |
+
+#### Error Handling Example
+
+```typescript
+import { ERROR_CODES } from 'toss-expo-sdk';
+
+try {
+  await client.createIntent(...);
+} catch (error) {
+  if (error.code === ERROR_CODES.INSUFFICIENT_FUNDS) {
+    // Handle insufficient funds
+    console.error('Insufficient funds for this transaction');
+  } else if (error.code === ERROR_CODES.INTENT_EXPIRED) {
+    // Handle expired intent
+    console.error('This transaction intent has expired');
+  } else if (error.code === ERROR_CODES.NETWORK_ERROR) {
+    // Handle network issues
+    console.error('Network error occurred. Please check your connection.');
+  } else {
+    // Handle other errors
+    console.error('An error occurred:', error.message);
+  }
+}
+```
+
+#### Error Object Structure
+
+All errors have the following structure:
+
+```typescript
+{
+  name: string;        // Error class name (e.g., 'NetworkError')
+  message: string;     // Human-readable error message
+  code: string;        // Error code (from ERROR_CODES)
+  details?: any;       // Additional error details (if any)
+  cause?: Error;       // Original error that caused this one (if any)
+}
+```
+
+## 🔄 Synchronisation and Settlement
+
+TOSS implements deterministic synchronisation (Section 9 of the technical paper) when devices reconnect to the network.
+
+### Full Synchronisation Flow
+
+```typescript
+import { syncToChain } from 'toss-expo-sdk';
+import { Connection } from '@solana/web3.js';
+
+const connection = new Connection('https://api.devnet.solana.com');
+
+// When your device reconnects to internet
+const syncResult = await syncToChain(connection);
+
+// Handle settlements
+console.log(`Successfully settled: ${syncResult.successfulSettlements.length}`);
+console.log(`Failed settlements: ${syncResult.failedSettlements.length}`);
+console.log(`Detected conflicts: ${syncResult.detectedConflicts.length}`);
+
+// Check individual failures
+for (const failed of syncResult.failedSettlements) {
+  console.error(`Intent ${failed.intentId} failed: ${failed.error}`);
+}
+
+// Handle conflicts
+for (const conflict of syncResult.detectedConflicts) {
+  console.warn(`Conflict in ${conflict.intentId}: ${conflict.conflict}`);
+}
+```
+
+### Conflict Detection and Resolution
+
+When multiple devices are offline and create conflicting intents, TOSS automatically resolves them deterministically:
+
+```typescript
+import { MultiDeviceConflictResolver } from 'toss-expo-sdk';
+
+// If multiple devices created the same intent
+const conflicts = MultiDeviceConflictResolver.detectConflicts([
+  intentFromDeviceA,
+  intentFromDeviceB,
+]);
+
+// Deterministically resolve using:
+// 1. Lowest nonce (replay protection)
+// 2. Earliest timestamp (fairness)
+// 3. Lexicographic signature (tiebreak)
+const resolution = MultiDeviceConflictResolver.resolveConflicts(conflicts[0]);
+
+console.log(`Winner: ${resolution.winner.id}`);
+console.log(`Losers: ${resolution.losers.map((i) => i.id)}`);
+```
+
+### Device Discovery and Peer Exchange
+
+Devices can discover and exchange intents with nearby peers:
+
+```typescript
+import { deviceDiscovery, intentExchange } from 'toss-expo-sdk';
+import { startTossScan } from 'toss-expo-sdk';
+
+// Scan for nearby TOSS devices
+startTossScan(
+  (user, device) => {
+    // Register discovered peer
+    deviceDiscovery.registerPeer({
+      id: device.id,
+      user,
+      lastSeen: Date.now(),
+      transport: 'ble',
+    });
+
+    // Create intent exchange request
+    const request = intentExchange.createRequest(
+      myIntent,
+      'my-device-id',
+      undefined,
+      5 * 60 // 5 minute expiry
+    );
+
+    console.log(`Exchange request created: ${request.requestId}`);
+  },
+  (intent, device) => {
+    console.log(`Received intent from ${device.id}`);
+  }
+);
+```
+
+## 🌐 Network Support
+
+| Network | Status  | RPC Endpoint                        |
+| ------- | ------- | ----------------------------------- |
+| Devnet  | ✅ Live | https://api.devnet.solana.com       |
+| Testnet | ✅ Live | https://api.testnet.solana.com      |
+| Mainnet | ✅ Live | https://api.mainnet-beta.solana.com |
+
+## 📚 Architecture and Design
+
+For complete implementation details including:
+
+- Full API reference
+- Architecture diagrams
+- Performance considerations
+- Future improvements
+
+See [IMPLEMENTATION.md](./IMPLEMENTATION.md)
+
+## 🌐 Network Support
+
+| Network | Status  | RPC Endpoint                   |
+| ------- | ------- | ------------------------------ |
+| Devnet  | ✅ Live | https://api.devnet.solana.com  |
+| Testnet | ✅ Live | https://api.testnet.solana.com |
+| Mainnet | ✅ Live | https://api.mainnet.solana.com |

package/lib/module/ble.js

@@ -0,0 +1,103 @@
+"use strict";
+
+// src/ble.ts
+import { BleManager } from 'react-native-ble-plx';
+import { PermissionsAndroid, Platform } from 'react-native';
+const SERVICE_UUID = '0000ff00-0000-1000-8000-00805f9b34fb';
+const USER_CHARACTERISTIC = '0000ff01-0000-1000-8000-00805f9b34fb';
+const INTENT_CHARACTERISTIC = '0000ff02-0000-1000-8000-00805f9b34fb';
+const manager = new BleManager();
+export async function requestBLEPermissions() {
+  if (Platform.OS === 'android') {
+    await PermissionsAndroid.requestMultiple([PermissionsAndroid.PERMISSIONS.BLUETOOTH_SCAN, PermissionsAndroid.PERMISSIONS.BLUETOOTH_CONNECT, PermissionsAndroid.PERMISSIONS.ACCESS_FINE_LOCATION]);
+  }
+}
+
+// Connect to a BLE device
+async function connect(device) {
+  const connectedDevice = await manager.connectToDevice(device.id);
+  await connectedDevice.discoverAllServicesAndCharacteristics();
+  return connectedDevice;
+}
+
+// Scan for BLE devices advertising TOSS service
+export function startTossScan(onUserFound, onIntentFound) {
+  manager.startDeviceScan([SERVICE_UUID], null, async (error, device) => {
+    if (error) {
+      console.warn('BLE scan error', error.message);
+      return;
+    }
+    if (device) {
+      try {
+        const connectedDevice = await connect(device);
+        const services = await connectedDevice.discoverAllServicesAndCharacteristics();
+
+        // Check for user data
+        const userData = await services.readCharacteristicForService(device.id, SERVICE_UUID, USER_CHARACTERISTIC);
+        if (userData?.value) {
+          const user = JSON.parse(userData.value);
+          onUserFound(user, device);
+        }
+
+        // Check for intent data
+        const intentData = await services.readCharacteristicForService(device.id, SERVICE_UUID, INTENT_CHARACTERISTIC);
+        if (intentData?.value) {
+          const intent = JSON.parse(intentData.value);
+          onIntentFound(intent, device);
+        }
+      } catch (err) {
+        console.warn('Error reading device data:', err);
+      }
+    }
+  });
+}
+import { State } from 'react-native-ble-plx';
+
+// Advertise user data via BLE
+export async function advertiseUser(user) {
+  try {
+    // On Android, we need to use a different approach since react-native-ble-plx
+    // doesn't support BLE advertising directly on the client side
+    if (Platform.OS === 'android') {
+      console.warn('BLE advertising is not directly supported on Android. Consider using react-native-ble-advertise for this functionality.');
+      return;
+    }
+
+    // For iOS, we can use the state change to know when advertising starts
+    const subscription = manager.onStateChange(state => {
+      if (state === State.PoweredOn) {
+        console.log(`Advertising user ${user.userId} via BLE`);
+        subscription.remove();
+      }
+    }, true);
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    console.error('Error in BLE advertising:', errorMessage);
+    throw new Error(`Failed to advertise user: ${errorMessage}`);
+  }
+}
+export async function stopAdvertising() {
+  try {
+    // On iOS, we can stop scanning which will effectively stop advertising
+    manager.stopDeviceScan();
+    console.log('Stopped BLE advertising');
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    console.error('Error stopping BLE advertising:', errorMessage);
+  }
+}
+
+// Send intent to a specific device
+export async function sendIntentToDevice(deviceId, intent) {
+  const jsonIntent = JSON.stringify(intent);
+  const device = await manager.connectToDevice(deviceId);
+  await device.discoverAllServicesAndCharacteristics();
+  await device.writeCharacteristicWithResponseForService(device.id, SERVICE_UUID, INTENT_CHARACTERISTIC, Buffer.from(jsonIntent).toString('base64'));
+  await device.cancelConnection();
+}
+
+// Stop scan
+export function stopScan() {
+  manager.stopDeviceScan();
+}
+//# sourceMappingURL=ble.js.map

package/lib/module/ble.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["BleManager","PermissionsAndroid","Platform","SERVICE_UUID","USER_CHARACTERISTIC","INTENT_CHARACTERISTIC","manager","requestBLEPermissions","OS","requestMultiple","PERMISSIONS","BLUETOOTH_SCAN","BLUETOOTH_CONNECT","ACCESS_FINE_LOCATION","connect","device","connectedDevice","connectToDevice","id","discoverAllServicesAndCharacteristics","startTossScan","onUserFound","onIntentFound","startDeviceScan","error","console","warn","message","services","userData","readCharacteristicForService","value","user","JSON","parse","intentData","intent","err","State","advertiseUser","subscription","onStateChange","state","PoweredOn","log","userId","remove","errorMessage","Error","String","stopAdvertising","stopDeviceScan","sendIntentToDevice","deviceId","jsonIntent","stringify","writeCharacteristicWithResponseForService","Buffer","from","toString","cancelConnection","stopScan"],"sourceRoot":"../../src","sources":["ble.ts"],"mappings":"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","ignoreList":[]}