@lumiapassport/ui-kit 1.1.0 → 1.3.0

package/README.md

@@ -0,0 +1,456 @@
+# @lumiapassport/ui-kit
+
+React UI components and hooks for Lumia Passport - a secure, user-friendly authentication and Account Abstraction wallet solution with MPC (Multi-Party Computation) key management.
+
+## Features
+
+- 🔐 **Secure Authentication** - Multiple auth methods: Email, Passkey, Telegram, Wallet connect
+- 🔑 **MPC Key Management** - Distributed key generation with iframe isolation
+- 💼 **Account Abstraction** - ERC-4337 compliant smart contract wallets
+- 🎨 **Pre-built UI Components** - Ready-to-use React components with customizable themes
+- ⚡ **Easy Integration** - Just wrap your app with `LumiaPassportProvider`
+
+## Installation
+
+```bash
+npm install @lumiapassport/ui-kit @lumiapassport/core
+# or
+pnpm add @lumiapassport/ui-kit @lumiapassport/core
+# or
+yarn add @lumiapassport/ui-kit @lumiapassport/core
+```
+
+### Peer Dependencies
+
+The following packages are required as peer dependencies:
+
+```bash
+npm install react react-dom viem wagmi @tanstack/react-query
+```
+
+## Quick Start
+
+### 1. Wrap your app with `LumiaPassportProvider`
+
+```tsx
+import { LumiaPassportProvider } from '@lumiapassport/ui-kit';
+import '@lumiapassport/ui-kit/dist/styles.css';
+
+function App() {
+  return (
+    <LumiaPassportProvider
+      config={{
+        projectId: 'your-project-id', // Get from Lumia Passport Dashboard
+        services: {
+          tssUrl: 'https://api.lumiapassport.com/tss',
+          bundlerUrl: 'https://api.lumiapassport.com/rundler',
+          shareVaultUrl: 'https://api.lumiapassport.com/vault',
+        }
+      }}
+    >
+      <YourApp />
+    </LumiaPassportProvider>
+  );
+}
+```
+
+### 2. Add the Connect Button
+
+```tsx
+import { ConnectWalletButton } from '@lumiapassport/ui-kit';
+
+function YourApp() {
+  return (
+    <div>
+      <h1>My App</h1>
+      <ConnectWalletButton />
+    </div>
+  );
+}
+```
+
+That's it! The `ConnectWalletButton` provides a complete authentication UI with wallet management.
+
+## Configuration Options
+
+### Basic Configuration
+
+```tsx
+<LumiaPassportProvider
+  config={{
+    projectId: 'your-project-id', // Required
+
+    // Optional: Service URLs (defaults to production)
+    services: {
+      tssUrl: 'https://api.lumiapassport.com/tss',
+      bundlerUrl: 'https://api.lumiapassport.com/rundler',
+      shareVaultUrl: 'https://api.lumiapassport.com/vault',
+      iframeUrl: 'https://auth.lumiapassport.com',
+    },
+
+    // Optional: Custom RPC and network
+    rpcUrl: 'https://beam-rpc.lumia.org',
+    explorerUrl: 'https://beam-explorer.lumia.org',
+
+    // Optional: Custom smart contract addresses
+    aaFactoryAddress: '0x...',
+    paymasterAddress: '0x...',
+  }}
+>
+```
+
+### Advanced Configuration
+
+```tsx
+<LumiaPassportProvider
+  config={{
+    projectId: 'your-project-id',
+
+    // Authentication providers
+    authProviders: {
+      email: true,      // Email OTP
+      passkey: true,    // Passkey/WebAuthn
+      telegram: true,   // Telegram Mini App
+      wallet: true,     // External wallet connection
+    },
+
+    // UI customization
+    theme: {
+      mode: 'dark',           // 'light' | 'dark' | 'auto'
+      primaryColor: '#6366f1', // Custom brand color
+    },
+
+    // Features
+    features: {
+      backup: true,           // Enable key backup/recovery
+      mpcSecurity: true,      // Enable MPC iframe isolation
+    },
+  }}
+>
+```
+
+## Using Hooks
+
+### useAuth - Authentication State
+
+```tsx
+import { useAuth } from '@lumiapassport/ui-kit';
+
+function MyComponent() {
+  const {
+    user,           // Current user info
+    isAuthenticated, // Auth status
+    login,          // Login function
+    logout,         // Logout function
+    loading,        // Loading state
+  } = useAuth();
+
+  if (loading) return <div>Loading...</div>;
+
+  if (!isAuthenticated) {
+    return <button onClick={() => login()}>Sign In</button>;
+  }
+
+  return (
+    <div>
+      <p>Welcome, {user.userId}</p>
+      <button onClick={() => logout()}>Sign Out</button>
+    </div>
+  );
+}
+```
+
+### useWallet - Wallet Operations
+
+```tsx
+import { useWallet } from '@lumiapassport/ui-kit';
+
+function SendTransaction() {
+  const { address, sendTransaction, balance } = useWallet();
+
+  const handleSend = async () => {
+    const hash = await sendTransaction({
+      to: '0x...',
+      value: '0.1', // ETH amount
+    });
+    console.log('Transaction hash:', hash);
+  };
+
+  return (
+    <div>
+      <p>Address: {address}</p>
+      <p>Balance: {balance} ETH</p>
+      <button onClick={handleSend}>Send Transaction</button>
+    </div>
+  );
+}
+```
+
+### useSendTransaction - Send Transactions
+
+```tsx
+import { useSendTransaction } from '@lumiapassport/ui-kit';
+
+function TransactionExample() {
+  const { sendTransaction, isPending } = useSendTransaction();
+
+  const handleSend = async () => {
+    try {
+      const userOpHash = await sendTransaction({
+        to: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
+        value: '1000000000000000000', // 1 ETH in wei
+        data: '0x', // Optional contract call data
+      });
+      console.log('UserOp hash:', userOpHash);
+    } catch (error) {
+      console.error('Transaction failed:', error);
+    }
+  };
+
+  return (
+    <div>
+      <button onClick={handleSend} disabled={isPending}>
+        {isPending ? 'Sending...' : 'Send Transaction'}
+      </button>
+    </div>
+  );
+}
+```
+
+### prepareUserOperation - Prepare for Backend Submission
+
+```tsx
+import { prepareUserOperation, useLumiaSession } from '@lumiapassport/ui-kit';
+
+function BackendSubmissionExample() {
+  const { session } = useLumiaSession();
+
+  const handlePrepare = async () => {
+    if (!session) return;
+
+    // Prepare and sign UserOp without sending to bundler
+    const { userOp, userOpHash } = await prepareUserOperation(
+      session,
+      '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb', // to
+      '1000000000000000000', // 1 ETH in wei
+      '0x', // data
+      'standard', // fee type: 'economy' | 'standard' | 'fast'
+      'v0.7' // EntryPoint version
+    );
+
+    // Send to backend for validation and submission
+    await fetch('/api/submit-transaction', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        userOp,
+        userOpHash,
+        ownerAddress: session.ownerAddress // for signature verification
+      }),
+    });
+  };
+
+  return (
+    <button onClick={handlePrepare}>
+      Prepare & Send to Backend
+    </button>
+  );
+}
+```
+
+**Backend example (using @lumiapassport/core):**
+
+```typescript
+import { sendUserOperationRaw, getUserOperationReceipt } from '@lumiapassport/core';
+import { recoverAddress } from 'viem';
+
+// Receive from frontend
+const { userOp, userOpHash, ownerAddress } = await request.json();
+
+// Verify signature
+const recoveredAddress = await recoverAddress({
+  hash: userOpHash,
+  signature: userOp.signature,
+});
+
+if (recoveredAddress.toLowerCase() !== ownerAddress.toLowerCase()) {
+  throw new Error('Invalid signature');
+}
+
+// Submit to bundler - returns userOpHash
+const submittedUserOpHash = await sendUserOperationRaw(userOp);
+
+// 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,
+      };
+    }
+    await new Promise(resolve => setTimeout(resolve, delayMs));
+  }
+  throw new Error('Transaction timeout');
+};
+
+const result = await waitForReceipt(submittedUserOpHash);
+return {
+  success: result.success,
+  transactionHash: result.transactionHash,
+  blockNumber: result.blockNumber
+};
+```
+
+## Components
+
+### ConnectWalletButton
+
+Pre-built button with authentication modal.
+
+```tsx
+<ConnectWalletButton
+  className="custom-class"
+  onConnect={(user) => console.log('Connected:', user)}
+  onDisconnect={() => console.log('Disconnected')}
+/>
+```
+
+### Custom Authentication Flow
+
+```tsx
+import { AuthModal, useAuthModal } from '@lumiapassport/ui-kit';
+
+function CustomAuth() {
+  const { openAuth } = useAuthModal();
+
+  return (
+    <div>
+      <button onClick={() => openAuth()}>
+        Custom Sign In
+      </button>
+      <AuthModal />
+    </div>
+  );
+}
+```
+
+## Authentication Methods
+
+### Email OTP
+
+Users receive a one-time code via email.
+
+```tsx
+// Configured by default, no additional setup needed
+```
+
+### Passkey (WebAuthn)
+
+Secure biometric authentication with device passkeys.
+
+```tsx
+// Configured by default
+// Users can register passkey after initial login
+```
+
+### Telegram Mini App
+
+Authentication via Telegram for mini apps.
+
+```tsx
+// Requires Telegram bot configuration
+// Set in config:
+config={{
+  telegram: {
+    botName: 'your_bot_name',
+  }
+}}
+```
+
+### External Wallet
+
+Connect existing wallets (MetaMask, WalletConnect, etc.).
+
+```tsx
+// Configured by default
+// Uses RainbowKit for wallet connections
+```
+
+## Styling
+
+### Using Built-in Themes
+
+```tsx
+import '@lumiapassport/ui-kit/dist/styles.css';
+
+<LumiaPassportProvider
+  config={{
+    projectId: 'your-project-id',
+    theme: {
+      mode: 'dark', // or 'light', 'auto'
+    }
+  }}
+>
+```
+
+### Custom Styling
+
+Override CSS variables for custom branding:
+
+```css
+.lumia-scope {
+  --lumia-primary: #6366f1;
+  --lumia-background: #0f172a;
+  --lumia-surface: #1e293b;
+  --lumia-text-primary: #f8fafc;
+  --lumia-text-secondary: #cbd5e1;
+}
+```
+
+## TypeScript Support
+
+Full TypeScript support with exported types:
+
+```tsx
+import type {
+  LumiaPassportConfig,
+  User,
+  AuthProvider,
+  WalletInfo,
+} from '@lumiapassport/ui-kit';
+```
+
+## Examples
+
+Check out the `/examples` directory for complete working examples:
+
+- **React + Vite** - Modern React setup with Vite
+- **Next.js** - Next.js App Router integration
+- **React + TypeScript** - Full TypeScript example
+
+## Security
+
+- 🔒 **MPC Key Management** - Keys are split between client and server using threshold cryptography
+- 🏝️ **Iframe Isolation** - Sensitive operations run in isolated iframe context
+- 🔐 **No Private Key Exposure** - Private keys never exist in complete form on client
+- ✅ **Non-custodial** - Users maintain full control of their accounts
+
+## Need Help?
+
+- 📖 [Documentation](https://docs.lumiapassport.com)
+- 💬 [Discord Community](https://discord.gg/lumia)
+- 🐛 [Report Issues](https://github.com/lumiachain/lumia-passport-sdk/issues)
+- 📧 [Email Support](mailto:support@lumia.org)
+
+## License
+
+MIT License - see LICENSE file for details.
+
+## Links
+
+- [Website](https://lumiapassport.com)
+- [GitHub](https://github.com/lumiachain/lumia-passport-sdk)
+- [NPM Package](https://www.npmjs.com/package/@lumiapassport/ui-kit)