@lumiapassport/core 1.14.2 → 1.14.3

package/README.md

@@ -7,164 +7,164 @@ Framework-agnostic core SDK for Lumia Passport smart accounts.
 - ✅ **Zero React dependencies** - Works in Node.js, browser, and edge functions
 - ✅ **TypeScript-first** - Full type safety
 - ✅ **Modular** - Import only what you need
-- ✅ **Storage abstraction** - Works with localStorage, Redis, memory, or custom storage
+- ✅ **Storage abstraction** - Works with file storage, memory, or custom storage
 - ✅ **Account Abstraction** - Full ERC-4337 support
 - ✅ **MPC/TSS** - Secure key management
 - ✅ **Server-side wallets** - Backend wallet management with API keys
+- ✅ **Zero configuration** - Works out of the box with Lumia Beam testnet
 
 ## Installation
 
 ```bash
-npm install @lumiapassport/core viem
+npm install @lumiapassport/core viem dkls23-wasm
 # or
-pnpm add @lumiapassport/core viem
+pnpm add @lumiapassport/core viem dkls23-wasm
 # or
-yarn add @lumiapassport/core viem
+yarn add @lumiapassport/core viem dkls23-wasm
 ```
 
-## Usage
+## Quick Start
 
-### Backend (Node.js)
+The SDK works out of the box with Lumia Beam testnet. No additional configuration required:
 
 ```typescript
-import { createLumiaPassportCore, MemoryStorage } from '@lumiapassport/core';
-
-const core = createLumiaPassportCore({
-  tssUrl: process.env.LUMIA_TSS_URL,
-  bundlerUrl: process.env.LUMIA_BUNDLER_URL,
-  chainId: 2030232745,
-  tokenStorage: new MemoryStorage(),
-  keyshareStorage: new MemoryStorage(),
-});
+import { createServerWalletManager, MemoryKeyshareStorage } from '@lumiapassport/core';
 
-// Create server wallet
-const account = await core.account.createAccountSession({
-  mpcUserId: 'server-wallet-001',
-  usePaymaster: true,
+// Create manager with just API key
+const manager = createServerWalletManager({
+  apiKey: process.env.LUMIA_PASSPORT_API_KEY!, // Get from dashboard.lumiapassport.com
+  storage: new MemoryKeyshareStorage(),
 });
 
-// Send transaction
-const hash = await core.account.sendUserOperation(
-  account,
-  '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
-  '1000000000000000000' // 1 ETH in wei
-);
+// Create a wallet
+const wallet = await manager.createWallet('my-wallet');
+console.log('Smart Account address:', wallet.smartAccountAddress);
 ```
 
-### Frontend (Browser)
+## Usage
+
+### Server-Side Wallets (Recommended)
+
+Create and manage backend wallets with a simple high-level API:
 
 ```typescript
-import { createLumiaPassportCore, LocalStorageAdapter } from '@lumiapassport/core';
+import { createServerWalletManager, MemoryKeyshareStorage } from '@lumiapassport/core';
 
-const core = createLumiaPassportCore({
-  tssUrl: import.meta.env.VITE_LUMIA_TSS_URL,
-  bundlerUrl: import.meta.env.VITE_LUMIA_BUNDLER_URL,
-  tokenStorage: new LocalStorageAdapter(),
-  keyshareStorage: new LocalStorageAdapter(),
+// Create manager
+const manager = createServerWalletManager({
+  apiKey: process.env.LUMIA_PASSPORT_API_KEY!, // Get from dashboard.lumiapassport.com
+  storage: new MemoryKeyshareStorage(), // Use FileKeyshareStorage or custom storage in production
 });
 
-// Send UserOperation
-const userOpHash = await core.bundler.sendUserOperation(params);
-console.log('Transaction hash:', userOpHash);
-```
+// Create a wallet (handles all TSS protocol complexity)
+const wallet = await manager.createWallet('treasury_main');
+console.log('Owner address (EOA):', wallet.ownerAddress);
+console.log('Smart Account address:', wallet.smartAccountAddress);
 
-### Backend: Verify and Submit UserOperation
+// Send a transaction (Account Abstraction with ERC-4337)
+const userOpHash = await wallet.sendUserOperation(
+  '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb', // recipient
+  '1000000000000000000', // 1 ETH in wei
+  '0x', // optional contract call data
+  'standard' // fee type: 'economy' | 'standard' | 'fast'
+);
+console.log('UserOp hash:', userOpHash);
 
-```typescript
-import { sendUserOperationRaw, getUserOperationReceipt } from '@lumiapassport/core';
-import { recoverAddress } from 'viem';
+// Wait for transaction confirmation
+const receipt = await manager.waitForUserOperationReceipt(userOpHash);
+console.log('Transaction hash:', receipt.transactionHash);
 
-// Receive from frontend (prepared with prepareUserOperation)
-const { userOp, userOpHash, ownerAddress } = await request.json();
+// Sign a message
+const signature = await wallet.signDigest(messageHash);
 
-// Verify signature
-const recoveredAddress = await recoverAddress({
-  hash: userOpHash,
-  signature: userOp.signature,
+// List all wallets
+const wallets = await manager.listWallets();
+wallets.forEach(w => {
+  console.log(`${w.userId}: ${w.smartAccountAddress}`);
 });
+```
 
-if (recoveredAddress.toLowerCase() !== ownerAddress.toLowerCase()) {
-  throw new Error('Invalid signature');
-}
+### Storage Options
 
-// Submit to bundler - returns userOpHash
-const submittedUserOpHash = await sendUserOperationRaw(userOp);
-console.log('UserOperation submitted:', submittedUserOpHash);
-
-// Poll for receipt to get transaction hash and status
-const waitForReceipt = async (userOpHash: string, maxAttempts = 60, delayMs = 1000) => {
-  for (let i = 0; i < maxAttempts; i++) {
-    const receipt = await getUserOperationReceipt(userOpHash as `0x${string}`);
-    if (receipt) {
-      return {
-        success: receipt.success,
-        transactionHash: receipt.receipt?.transactionHash,
-        blockNumber: receipt.receipt?.blockNumber,
-        gasUsed: receipt.actualGasUsed,
-      };
-    }
-    await new Promise(resolve => setTimeout(resolve, delayMs));
-  }
-  throw new Error('Transaction timeout');
-};
+#### MemoryKeyshareStorage (Development only)
+
+Simple in-memory storage. **Keyshares are lost on restart!**
 
-const result = await waitForReceipt(submittedUserOpHash);
-console.log('Transaction confirmed:', result.transactionHash);
-console.log('Status:', result.success ? 'Success' : 'Failed');
+```typescript
+import { MemoryKeyshareStorage } from '@lumiapassport/core';
+
+const storage = new MemoryKeyshareStorage();
 ```
 
-### JWT Verification
+#### FileKeyshareStorage (Production-ready)
+
+Encrypted file-based storage using AES-256-CBC. Available in Node.js only:
 
 ```typescript
-import { createLumiaPassportCore } from '@lumiapassport/core';
+import { FileKeyshareStorage } from '@lumiapassport/core/clients/node';
+
+const storage = new FileKeyshareStorage({
+  storageDir: './data/keyshares',
+  encryptionPassword: process.env.LUMIA_PASSPORT_KEYSHARE_ENCRYPTION_PASSWORD!,
+});
+
+// Initialize storage directory
+await storage.init();
 
-const core = createLumiaPassportCore({ tssUrl: process.env.LUMIA_TSS_URL });
+const manager = createServerWalletManager({
+  apiKey: process.env.LUMIA_PASSPORT_API_KEY!,
+  storage,
+});
+```
+
+#### Custom Storage
 
-// Verify token
-const verification = await core.auth.verifyToken(token);
+Implement the `KeyshareStorage` interface for custom backends (AWS KMS, Vault, etc.):
 
-if (verification.valid) {
-  console.log('User ID:', verification.userId);
+```typescript
+interface KeyshareStorage {
+  set(userId: string, keyshare: string): Promise<void> | void;
+  get(userId: string): Promise<string | null> | string | null;
+  has(userId: string): Promise<boolean> | boolean;
+  list(): Promise<string[]> | string[];
 }
 ```
 
-### Server-Side Wallets
+### Keyshare Backup and Restore
 
-Create and manage backend wallets with a simple high-level API:
+Backup keyshares to Lumia ShareVault for recovery:
 
 ```typescript
-import {
-  createServerWalletManager,
-  MemoryKeyshareStorage,
-} from '@lumiapassport/core';
+// Check if wallet exists on TSS service
+const exists = await manager.walletExists('my-wallet');
 
-// Create manager
-const manager = createServerWalletManager({
-  apiKey: process.env.LUMIA_PASSPORT_API_KEY!, // Get from dashboard
-  storage: new MemoryKeyshareStorage(), // Use AWS KMS, Vault, etc. in production
-});
+// Check if we have keyshare locally
+const hasKeyshare = await manager.hasKeyshare('my-wallet');
 
-// Create a wallet (handles all TSS protocol complexity)
-const wallet = await manager.createWallet('treasury_main');
-console.log('Owner address (EOA):', wallet.ownerAddress);
-console.log('Smart Account address:', wallet.smartAccountAddress);
+if (!hasKeyshare) {
+  // Check if backup exists in vault
+  const { hasBackup } = await manager.checkBackupExists('my-wallet');
 
-// Send a transaction (Account Abstraction with ERC-4337)
-const userOpHash = await wallet.sendUserOperation(
-  '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb', // recipient
-  '1000000000000000000', // 1 ETH in wei
-  '0x', // optional contract call data
-  'standard' // fee type: 'economy' | 'standard' | 'fast'
-);
-console.log('Transaction hash:', userOpHash);
+  if (hasBackup) {
+    // Restore from vault
+    await manager.restoreFromVault('my-wallet', process.env.BACKUP_PASSWORD!);
+    console.log('Keyshare restored from vault');
+  }
+}
 
-// Sign a message
-const signature = await wallet.signDigest(messageHash);
+// Backup keyshare to vault
+await manager.backupToVault('my-wallet', process.env.BACKUP_PASSWORD!);
+```
 
-// List all wallets
-const wallets = await manager.listWallets();
-wallets.forEach(w => {
-  console.log(`${w.userId}: ${w.smartAccountAddress}`);
+### Using Paymaster (Sponsored Transactions)
+
+Configure paymaster for gasless transactions:
+
+```typescript
+const manager = createServerWalletManager({
+  apiKey: process.env.LUMIA_PASSPORT_API_KEY!,
+  storage,
+  paymasterAddress: '0x...' as `0x${string}`, // Your paymaster contract
 });
 ```
 
@@ -381,6 +381,22 @@ const logs = await client.getLogs({
   fromBlock: 1000000n,
   toBlock: 'latest',
 });
+
+// Get transaction receipt (returns null if pending)
+const receipt = await client.getTransactionReceipt({
+  hash: '0x...transactionHash',
+});
+
+// Wait for transaction to be mined
+const receipt = await client.waitForTransactionReceipt({
+  hash: '0x...transactionHash',
+  confirmations: 1,      // optional, default: 1
+  pollingInterval: 4000, // optional, default: 4000ms
+  timeout: 60000,        // optional, default: 60000ms
+  onReplaced: (response) => {
+    console.log('Transaction replaced:', response.reason);
+  },
+});
 ```
 
 **Features:**
@@ -388,6 +404,7 @@ const logs = await client.getLogs({
 - **RPC Fallback** - Automatic failover to backup RPCs
 - **Multicall Batching** - Batch reads for better performance
 - **Log Pagination** - Automatic chunking for large block ranges
+- **Transaction Receipts** - Get receipt or wait with polling/timeout
 
 ## API
 

package/dist/internal/error-tracking.cjs

@@ -45,7 +45,7 @@ function initSdkErrorTracking() {
       // Don't track performance for SDK (only errors)
       tracesSampleRate: 0,
       // Release version from package.json
-      release: `@lumiapassport/core@${"1.14.2"}`,
+      release: `@lumiapassport/core@${"1.14.3"}`,
       environment: "production",
       // Filter to only track SDK errors
       beforeSend(event) {

package/dist/internal/error-tracking.js

@@ -23,7 +23,7 @@ function initSdkErrorTracking() {
       // Don't track performance for SDK (only errors)
       tracesSampleRate: 0,
       // Release version from package.json
-      release: `@lumiapassport/core@${"1.14.2"}`,
+      release: `@lumiapassport/core@${"1.14.3"}`,
       environment: "production",
       // Filter to only track SDK errors
       beforeSend(event) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumiapassport/core",
-  "version": "1.14.2",
+  "version": "1.14.3",
   "description": "Framework-agnostic core SDK for Lumia Passport smart accounts",
   "type": "module",
   "main": "./dist/index.cjs",