@lumiapassport/ui-kit 1.1.0 → 1.2.0

package/README.md

@@ -0,0 +1,434 @@
+# @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 } 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
+const txHash = await sendUserOperationRaw(userOp);
+return { success: true, txHash };
+```
+
+## 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)

package/dist/index.cjs

@@ -2807,6 +2807,7 @@ __export(index_exports, {
   UserOpStatus: () => UserOpStatus,
   getUserProfile: () => getUserProfile,
   lumiaBeam: () => lumiaBeam,
+  prepareUserOperation: () => prepareUserOperation,
   queryClient: () => queryClient,
   sendUserOperation: () => sendUserOperation,
   updateUserProfile: () => updateUserProfile,
@@ -5294,6 +5295,208 @@ async function sendUserOperation(session, callTarget, amountWei, innerData = "0x
   }
   return hash;
 }
+async function prepareUserOperation(session, callTarget, amountWei, innerData = "0x", feeType = "standard", entryPointVersion = "v0.7") {
+  const entryPointAddress = entryPointVersion === "v0.6" ? ENTRYPOINT_V06 : ENTRYPOINT_V07;
+  const amountWeiBigInt = BigInt(amountWei);
+  const isMinimalTest = callTarget === "0x0000000000000000000000000000000000000000" && amountWei === "0" && innerData === "0x";
+  let callData;
+  if (isMinimalTest) {
+    callData = "0x";
+  } else {
+    callData = (0, import_viem3.encodeFunctionData)({ abi: executeAbi, functionName: "execute", args: [callTarget, amountWeiBigInt, innerData] });
+  }
+  let isDeployed = false;
+  let deploymentMethod = "unknown";
+  try {
+    const code = await publicClient.getCode({ address: session.smartAccountAddress });
+    if (code && code !== "0x" && code.length > 2) {
+      isDeployed = true;
+      deploymentMethod = "getCode";
+    }
+  } catch {
+  }
+  const nonce = await fetchEntryPointNonce(session.smartAccountAddress, entryPointAddress);
+  const nonceValue = BigInt(nonce);
+  if (!isDeployed && nonceValue !== 0n) throw new Error(`Undeployed account has non-zero nonce: ${nonce}. This will cause CodeHashChanged error.`);
+  const shouldIncludeFactory = !isDeployed;
+  let userOp;
+  if (shouldIncludeFactory) {
+    const compatCreateAbi = [{ type: "function", name: "createAccount", stateMutability: "payable", inputs: [{ name: "owner", type: "address" }, { name: "salt", type: "bytes32" }], outputs: [{ name: "", type: "address" }] }];
+    const saltZero = "0x0000000000000000000000000000000000000000000000000000000000000000";
+    const factoryData = (0, import_viem3.encodeFunctionData)({ abi: compatCreateAbi, functionName: "createAccount", args: [session.ownerAddress, saltZero] });
+    userOp = await (0, import_bundler.createUserOperationWithDynamicFees)(
+      session.smartAccountAddress,
+      nonce,
+      callData,
+      true,
+      session.factoryAddress,
+      factoryData,
+      feeType
+    );
+  } else {
+    userOp = await (0, import_bundler.createUserOperationWithDynamicFees)(
+      session.smartAccountAddress,
+      nonce,
+      callData,
+      false,
+      void 0,
+      void 0,
+      feeType
+    );
+  }
+  const ensureGenerousDefaults = () => {
+    const toHex2 = (v) => `0x${v.toString(16)}`;
+    const minCallGas = 0x493e0n;
+    const minVerificationGas = 0x989680n;
+    const minPreVerificationGas = 0x30d40n;
+    if (BigInt(userOp.callGasLimit || "0x0") < minCallGas) userOp.callGasLimit = toHex2(minCallGas);
+    if (BigInt(userOp.verificationGasLimit || "0x0") < minVerificationGas) userOp.verificationGasLimit = toHex2(minVerificationGas);
+    if (BigInt(userOp.preVerificationGas || "0x0") < minPreVerificationGas) userOp.preVerificationGas = toHex2(minPreVerificationGas);
+  };
+  const enforceCaps = (usePaymaster) => {
+    try {
+      const envCaps = typeof import_meta !== "undefined" && import_meta.env || {};
+      const maxBundlerVerifGas = envCaps.VITE_MAX_VERIFICATION_GAS ? BigInt(envCaps.VITE_MAX_VERIFICATION_GAS) : MAX_BUNDLER_VERIFICATION_GAS;
+      const maxCallGas = envCaps.VITE_MAX_CALL_GAS_LIMIT ? BigInt(envCaps.VITE_MAX_CALL_GAS_LIMIT) : 0x7a120n;
+      const toHex2 = (v) => `0x${v.toString(16)}`;
+      const maxAccountVerifGas = usePaymaster ? maxBundlerVerifGas - PAYMASTER_VERIFICATION_GAS : maxBundlerVerifGas;
+      const verGas = BigInt(userOp.verificationGasLimit || "0x0");
+      if (verGas > maxAccountVerifGas) userOp.verificationGasLimit = toHex2(maxAccountVerifGas);
+      const callGas = BigInt(userOp.callGasLimit || "0x0");
+      if (callGas > maxCallGas) userOp.callGasLimit = toHex2(maxCallGas);
+    } catch {
+    }
+  };
+  let estimated = false;
+  try {
+    const gasEst = await (0, import_bundler.estimateUserOperationGas)({ ...userOp, signature: `0x${"00".repeat(65)}` });
+    userOp.callGasLimit = gasEst.callGasLimit;
+    userOp.verificationGasLimit = gasEst.verificationGasLimit;
+    userOp.preVerificationGas = gasEst.preVerificationGas;
+    ensureGenerousDefaults();
+    enforceCaps(session.usePaymaster);
+    estimated = true;
+  } catch {
+    ensureGenerousDefaults();
+    enforceCaps(session.usePaymaster);
+  }
+  try {
+    const toHex2 = (v) => `0x${v.toString(16)}`;
+    const isContractCall = !!userOp.callData && userOp.callData !== "0x";
+    if (isContractCall) {
+      const currentVer = BigInt(userOp.verificationGasLimit || "0x0");
+      const call = BigInt(userOp.callGasLimit || "0x0");
+      const postOp = 150000n;
+      const safety10k = 10000n;
+      let buffer = call + postOp + safety10k;
+      buffer += buffer / 63n;
+      const newVer = currentVer + buffer;
+      userOp.verificationGasLimit = toHex2(newVer);
+      enforceCaps(session.usePaymaster);
+    }
+  } catch {
+  }
+  if (session.usePaymaster && LUMIA_PAYMASTER_ADDRESS) {
+    userOp.paymaster = LUMIA_PAYMASTER_ADDRESS;
+    userOp.paymasterData = "0x";
+    userOp.paymasterVerificationGasLimit = PAYMASTER_VERIFICATION_GAS_LIMIT;
+    userOp.paymasterPostOpGasLimit = PAYMASTER_POSTOP_GAS_LIMIT;
+  }
+  userOp.nonce = nonce;
+  let opHash;
+  if (entryPointVersion === "v0.6") {
+    const userOpV06 = convertUserOpV07ToV06(userOp);
+    opHash = await publicClient.readContract({
+      address: entryPointAddress,
+      abi: [{ type: "function", name: "getUserOpHash", inputs: [{ name: "userOp", type: "tuple", components: [{ name: "sender", type: "address" }, { name: "nonce", type: "uint256" }, { name: "initCode", type: "bytes" }, { name: "callData", type: "bytes" }, { name: "callGasLimit", type: "uint256" }, { name: "verificationGasLimit", type: "uint256" }, { name: "preVerificationGas", type: "uint256" }, { name: "maxFeePerGas", type: "uint256" }, { name: "maxPriorityFeePerGas", type: "uint256" }, { name: "paymasterAndData", type: "bytes" }, { name: "signature", type: "bytes" }] }], outputs: [{ name: "", type: "bytes32" }] }],
+      functionName: "getUserOpHash",
+      args: [{
+        sender: userOpV06.sender,
+        nonce: BigInt(userOpV06.nonce),
+        initCode: userOpV06.initCode,
+        callData: userOpV06.callData,
+        callGasLimit: BigInt(userOpV06.callGasLimit),
+        verificationGasLimit: BigInt(userOpV06.verificationGasLimit),
+        preVerificationGas: BigInt(userOpV06.preVerificationGas),
+        maxFeePerGas: BigInt(userOpV06.maxFeePerGas),
+        maxPriorityFeePerGas: BigInt(userOpV06.maxPriorityFeePerGas),
+        paymasterAndData: userOpV06.paymasterAndData,
+        signature: "0x"
+      }]
+    });
+  } else {
+    const hasFactoryData = !!(userOp.factory && userOp.factoryData);
+    const initCode = hasFactoryData ? (() => {
+      const factoryAddr = userOp.factory.startsWith("0x") ? userOp.factory.slice(2) : userOp.factory;
+      const factoryDataClean = userOp.factoryData.startsWith("0x") ? userOp.factoryData.slice(2) : userOp.factoryData;
+      return `0x${factoryAddr}${factoryDataClean}`;
+    })() : "0x";
+    const accountGasLimits = pack2x128(BigInt(userOp.verificationGasLimit), BigInt(userOp.callGasLimit));
+    const gasFees = pack2x128(BigInt(userOp.maxPriorityFeePerGas), BigInt(userOp.maxFeePerGas));
+    let paymasterAndData = "0x";
+    if (userOp.paymaster && userOp.paymaster !== "0x0000000000000000000000000000000000000000") {
+      const verificationGasLimit = userOp.paymasterVerificationGasLimit || "0x186a0";
+      const postOpGasLimit = userOp.paymasterPostOpGasLimit || "0x186a0";
+      const paymasterDataField = userOp.paymasterData || "0x";
+      const packedPaymasterGasLimits = pack2x128(BigInt(verificationGasLimit), BigInt(postOpGasLimit));
+      const paymasterAddr = userOp.paymaster.startsWith("0x") ? userOp.paymaster.slice(2) : userOp.paymaster;
+      const paymasterDataClean = paymasterDataField === "0x" ? "" : paymasterDataField.startsWith("0x") ? paymasterDataField.slice(2) : paymasterDataField;
+      paymasterAndData = `0x${paymasterAddr}${packedPaymasterGasLimits.slice(2)}${paymasterDataClean}`;
+    }
+    const packedForHash = {
+      sender: session.smartAccountAddress,
+      nonce: BigInt(nonce),
+      initCode,
+      callData,
+      accountGasLimits,
+      preVerificationGas: BigInt(userOp.preVerificationGas),
+      gasFees,
+      paymasterAndData,
+      signature: "0x"
+    };
+    opHash = await publicClient.readContract({
+      address: entryPointAddress,
+      abi: import_account_abstraction2.entryPoint07Abi,
+      functionName: "getUserOpHash",
+      args: [packedForHash]
+    });
+  }
+  let signature;
+  if (session.mpcUserId) {
+    const mpcSig = await signDigestWithMpc(session.mpcUserId, opHash, {
+      sender: userOp.sender,
+      nonce: userOp.nonce,
+      callData: userOp.callData,
+      callGasLimit: userOp.callGasLimit,
+      verificationGasLimit: userOp.verificationGasLimit,
+      preVerificationGas: userOp.preVerificationGas,
+      maxFeePerGas: userOp.maxFeePerGas,
+      maxPriorityFeePerGas: userOp.maxPriorityFeePerGas,
+      paymaster: userOp.paymaster,
+      factory: userOp.factory,
+      factoryData: userOp.factoryData
+    });
+    if (!mpcSig) throw new Error("MPC signing failed");
+    signature = mpcSig;
+  } else if (session.ownerPrivateKey) {
+    const account = (0, import_accounts.privateKeyToAccount)(session.ownerPrivateKey);
+    const rawSig = await account.sign({ hash: opHash });
+    signature = normalizeSignature(rawSig);
+  } else {
+    throw new Error("No signing method available");
+  }
+  userOp.signature = signature;
+  if (typeof userOp.sender !== "string") {
+    userOp.sender = session.smartAccountAddress;
+  }
+  console.log("[Account] \u2705 Prepared signed UserOp (not sent):", JSON.stringify(userOp, (key, value) => typeof value === "bigint" ? `0x${value.toString(16)}` : value, 2));
+  console.log("[Account] \u{1F511} UserOp Hash:", opHash);
+  if (entryPointVersion === "v0.6") {
+    const userOpV06 = convertUserOpV07ToV06(userOp);
+    return { userOp: userOpV06, userOpHash: opHash };
+  }
+  return { userOp, userOpHash: opHash };
+}
 async function getEntryPointDeposit(address, entryPointVersion = "v0.7") {
   const entryPointAddress = entryPointVersion === "v0.6" ? ENTRYPOINT_V06 : ENTRYPOINT_V07;
   const depositAbi = [{ type: "function", name: "balanceOf", stateMutability: "view", inputs: [{ name: "account", type: "address" }], outputs: [{ name: "", type: "uint256" }] }];
@@ -9524,6 +9727,7 @@ function useSmartAccountTransactions() {
   UserOpStatus,
   getUserProfile,
   lumiaBeam,
+  prepareUserOperation,
   queryClient,
   sendUserOperation,
   updateUserProfile,