@aspect-wallet/sdk 0.1.0

package/README.md

@@ -0,0 +1,708 @@
+# @aspect-wallet/sdk
+
+TypeScript SDK for building on the **Aspect Wallet** ERC-4337 Account Abstraction system. Create smart wallets, send gasless transactions, authenticate with social logins, and manage session keys -- all from your frontend.
+
+## Features
+
+| Feature | Description |
+|---------|-------------|
+| **Smart Wallets** | Deterministic CREATE2 addresses, lazy deployment on first transaction |
+| **Gasless Transactions** | VerifyingPaymaster sponsors gas -- users pay nothing |
+| **Social Login** | Google, Apple, Facebook, Email OTP -- bridged to on-chain signers via Turnkey |
+| **Passkeys** | WebAuthn/P256 biometric signing with RIP-7212 precompile support |
+| **Session Keys** | Scoped ephemeral keys with allowlist, spend limits, time bounds |
+| **Multi-Factor Auth** | On-chain enforced: device+guardian, K-of-N multi-sig, timelock |
+| **Account Recovery** | Social recovery via guardians with timelock, two-step key rotation |
+| **Emergency Freeze** | Instantly revoke all session keys and freeze account on compromise |
+| **Audit Trail** | Full operation history, real-time events, webhook notifications |
+| **Multi-Chain** | Arbitrum, Base, Polygon, Ethereum -- same address across chains |
+
+## Installation
+
+```bash
+npm install @aspect-wallet/sdk viem
+```
+
+## Quick Start
+
+```typescript
+import { FcxWalletClient, EoaSigner } from '@aspect-wallet/sdk';
+import { privateKeyToAccount } from 'viem/accounts';
+
+const client = new FcxWalletClient({
+  chain: 'arbitrum-sepolia',
+  paymasterUrl: 'https://paymaster.yourapp.com',
+  bundlerUrl: 'https://bundler.yourapp.com/rpc',
+});
+
+// Get deterministic wallet address (no deployment needed yet)
+const walletAddress = await client.getWalletAddress();
+
+// Execute a transaction (deploys wallet on first tx if needed)
+const result = await client.execute({
+  target: '0xContractAddress...',
+  value: 0n,
+  data: '0x...',
+  sponsored: true, // Paymaster pays gas
+});
+
+console.log('TX:', result.transactionHash);
+console.log('Gas paid by user:', 0); // Gasless!
+```
+
+---
+
+## Wallet Lifecycle
+
+### Counterfactual Address
+
+Users get a wallet address **instantly** -- no on-chain transaction needed. Assets can be sent to this address before the contract exists.
+
+```typescript
+import { computeWalletAddress, WalletFactory } from '@aspect-wallet/sdk';
+
+// Option A: Pure computation (no RPC call)
+const address = computeWalletAddress({
+  factory: '0x1DFCc3c2ae138Da4BdF00DBF62CFf6f922D353EA',
+  owner: signerAddress,
+  salt: 0n,
+});
+
+// Option B: Query factory contract
+const factory = new WalletFactory(publicClient, factoryAddress);
+const address = await factory.getAddress(signerAddress, 0n);
+const isDeployed = await factory.isDeployed(address);
+```
+
+### Lazy Deployment
+
+The wallet deploys automatically on the first UserOp. The SDK handles `initCode` transparently:
+
+```typescript
+// First transaction: SDK includes initCode, factory deploys via CREATE2
+const result = await client.execute({
+  target: recipientAddress,
+  value: parseEther('0.01'),
+  data: '0x',
+});
+// Wallet now exists on-chain at the same address
+```
+
+---
+
+## UserOperation Builder
+
+### High-Level (Recommended)
+
+```typescript
+// Single call
+const result = await client.execute({
+  target: tokenContract,
+  value: 0n,
+  data: encodeFunctionData({ abi: erc20Abi, functionName: 'transfer', args: [to, amount] }),
+});
+
+// Batch call (atomic: all succeed or all revert)
+const result = await client.executeBatch([
+  { target: tokenA, value: 0n, data: approveData },
+  { target: dex, value: 0n, data: swapData },
+]);
+```
+
+### Low-Level (Advanced)
+
+```typescript
+import { UserOpBuilder, getUserOpHash } from '@aspect-wallet/sdk';
+
+const builder = new UserOpBuilder({ publicClient, entryPoint, factory });
+
+// Step 1: Build
+const userOp = await builder
+  .setSender(walletAddress)
+  .setCallData({ target, value, data })
+  .setNonce({ key: 0n })
+  .build();
+
+// Step 2: Estimate gas (applies 130% safety margin)
+const estimated = await builder.estimateGas(userOp);
+
+// Step 3: Get sponsorship
+const sponsored = await paymasterClient.approve(estimated);
+
+// Step 4: Compute hash
+const hash = getUserOpHash(sponsored, entryPointAddress, chainId);
+
+// Step 5: Sign
+const signature = await signer.sign(hash);
+sponsored.signature = signature;
+
+// Step 6: Submit
+const opHash = await bundlerClient.sendUserOperation(sponsored);
+
+// Step 7: Wait for receipt
+const receipt = await bundlerClient.waitForReceipt(opHash, { timeout: 60_000 });
+```
+
+### Hash Computation
+
+The SDK's `getUserOpHash()` matches `EntryPoint.getUserOpHash()` exactly (verified on-chain):
+
+```typescript
+import { getUserOpHash } from '@aspect-wallet/sdk';
+
+const hash = getUserOpHash(userOp, entryPointAddress, chainId);
+// Includes chainId + entryPoint address for anti-replay
+// Variable-length fields (initCode, callData, paymasterAndData) individually hashed
+```
+
+---
+
+## Gas Sponsorship (Paymaster)
+
+Users transact with **zero ETH**. The VerifyingPaymaster contract pays gas, authorized by your backend signing service.
+
+```typescript
+import { PaymasterClient } from '@aspect-wallet/sdk';
+
+const paymaster = new PaymasterClient({
+  url: 'https://paymaster.yourapp.com',
+});
+
+// Request sponsorship approval
+const approval = await paymaster.approve(userOp);
+// approval.paymasterAndData = 97 bytes: address(20) + validUntil(6) + validAfter(6) + signature(65)
+
+// Insert into UserOp
+userOp.paymasterAndData = approval.paymasterAndData;
+
+// Check remaining budget
+const budget = await paymaster.getBudget();
+// budget.daily.remaining = 3800000000000000000n (3.8 ETH)
+```
+
+### Transparent Sponsorship
+
+```typescript
+const result = await client.execute({
+  target: contractAddress,
+  value: 0n,
+  data: callData,
+  sponsored: true, // SDK handles paymaster flow automatically
+});
+```
+
+---
+
+## Authentication & Social Login
+
+### Email OTP
+
+```typescript
+import { AuthClient } from '@aspect-wallet/sdk';
+
+const auth = new AuthClient({ url: 'https://auth.yourapp.com' });
+
+// Send OTP
+await auth.sendEmailOtp('user@example.com');
+
+// Verify OTP → get session + wallet
+const session = await auth.verifyEmailOtp({
+  email: 'user@example.com',
+  code: '847291',
+});
+// session.wallet.address = '0x...' (deterministic, instant)
+// session.signer.address = '0x...' (Turnkey-generated secp256k1 key)
+// session.jwt = 'eyJ...' (for subsequent API calls)
+```
+
+### OAuth (Google / Apple / Facebook)
+
+```typescript
+import { OAuthClient } from '@aspect-wallet/sdk';
+
+const oauth = new OAuthClient({ url: 'https://auth.yourapp.com' });
+
+// Google
+const session = await oauth.loginWithGoogle();
+
+// Apple
+const session = await oauth.loginWithApple();
+
+// Facebook
+const session = await oauth.loginWithFacebook();
+
+// All return the same SessionInfo structure
+// First login: creates Turnkey sub-org + generates signing key
+// Returning login: loads existing key
+```
+
+### Passkey Authentication
+
+```typescript
+import { PasskeyAuthClient } from '@aspect-wallet/sdk';
+
+const passkey = new PasskeyAuthClient({ url: 'https://auth.yourapp.com' });
+
+// Register passkey (after initial login)
+await passkey.register({ displayName: 'My MacBook' });
+
+// Login with passkey (biometric prompt)
+const session = await passkey.authenticate();
+```
+
+---
+
+## Signing
+
+### Signer Interface
+
+All signers implement `ISigner`:
+
+```typescript
+interface ISigner {
+  type: 'eoa' | 'passkey' | 'turnkey' | 'session-key' | 'multi-sig';
+  address: string;
+  sign(userOpHash: Hex): Promise<Hex>;
+}
+```
+
+### EOA Signer (Testing / Backend)
+
+```typescript
+import { EoaSigner } from '@aspect-wallet/sdk';
+
+const signer = new EoaSigner({ privateKey: '0x...' });
+const signature = await signer.sign(userOpHash);
+// 65-byte ECDSA signature with EIP-191 prefix
+```
+
+### Passkey Signer (Browser)
+
+```typescript
+import { PasskeySigner } from '@aspect-wallet/sdk';
+
+const signer = new PasskeySigner({ credentialId: '...' });
+const signature = await signer.sign(userOpHash);
+// WebAuthn assertion: authenticatorData + clientDataJSON + r + s
+// P256 verified on-chain via RIP-7212 precompile (3,450 gas)
+```
+
+### Modular Signature Format
+
+For modular accounts (ERC-6900), signatures include a module ID prefix:
+
+```typescript
+import { encodeModuleSignature } from '@aspect-wallet/sdk';
+
+const modularSig = encodeModuleSignature(0, ecdsaSignature);
+// moduleId(4 bytes) + signature = routes to correct on-chain validator
+// 0 = SingleSigner, 1 = SessionKey, 2 = DeviceGuardian, 3 = MultiSig, 4 = WebAuthn
+```
+
+---
+
+## Session Keys
+
+Temporary scoped keys that let dApps execute transactions **without user interaction** per action, while strictly limiting what the key can do.
+
+### Create Session Key
+
+```typescript
+import { SessionKeyManager, SessionKeyTemplates } from '@aspect-wallet/sdk';
+
+const manager = new SessionKeyManager(client);
+
+// Custom permissions
+const session = await manager.create({
+  permissions: {
+    allowlist: [
+      { target: gameContract, selector: '0x12345678' }, // playMove()
+      { target: gameContract, selector: '0xabcdef01' }, // claimReward()
+    ],
+    spendLimit: { perTx: 0n, cumulative: 0n },
+    timeRange: {
+      validAfter: Math.floor(Date.now() / 1000),
+      validUntil: Math.floor(Date.now() / 1000) + 4 * 3600, // 4 hours
+    },
+    requiredPaymaster: paymasterAddress,
+  },
+});
+
+// Or use pre-built templates
+const gaming = SessionKeyTemplates.gaming({
+  gameContract: '0x...',
+  duration: 4 * 3600,
+  paymaster: '0x...',
+});
+
+const defi = SessionKeyTemplates.defi({
+  dexRouter: '0x...',
+  lendingPool: '0x...',
+  spendLimit: parseEther('1'),
+  duration: 3600,
+});
+```
+
+### Execute with Session Key
+
+```typescript
+// No user interaction needed -- session key signs automatically
+const result = await manager.execute(session.moduleId, {
+  target: gameContract,
+  value: 0n,
+  data: playMoveData,
+});
+
+// On-chain hooks enforce:
+// - AllowlistModule: target + selector in whitelist
+// - NativeTokenLimitModule: value within limits
+// - TimeRangeModule: within valid time window
+// - PaymasterGuardModule: using required paymaster
+```
+
+### Revoke
+
+```typescript
+await manager.revoke(session.moduleId); // Immediate on-chain revocation
+```
+
+---
+
+## Multi-Factor Authentication
+
+On-chain enforced MFA -- the blockchain rejects transactions that don't meet the multi-factor requirements.
+
+### 4-Tier Step-Up Auth
+
+```typescript
+import { TierSelector } from '@aspect-wallet/sdk';
+
+// SDK auto-selects tier based on value + target
+const result = await client.execute({
+  target: tokenContract,
+  value: parseEther('5'), // High value → Tier 3 (device + guardian)
+  data: transferData,
+});
+
+// Force specific tier
+const result = await client.execute({
+  target: tokenContract,
+  value: parseEther('0.01'),
+  data: transferData,
+  authTier: 3, // Force device + guardian
+});
+```
+
+| Tier | When | Signers | Latency |
+|------|------|---------|---------|
+| 1 | Low-value, scoped actions | Session key (auto-sign) | Instant |
+| 2 | Normal transactions | Owner key | 1 biometric prompt |
+| 3 | High-value transfers | Owner + Guardian | 2 approvals |
+| 4 | Account management | 2-of-3 multi-sig + 24h timelock | Hours/days |
+
+### Guardian Management
+
+```typescript
+import { GuardianManager } from '@aspect-wallet/sdk';
+
+const guardians = new GuardianManager(client);
+
+await guardians.add({ guardian: '0x...', label: 'Mom' });
+await guardians.add({ guardian: '0x...', label: 'Backend Co-Signer' });
+await guardians.setThreshold(2); // 2-of-3 required for recovery
+
+const list = await guardians.list(walletAddress);
+```
+
+### Multi-Sig Operations
+
+```typescript
+import { MultiSigManager } from '@aspect-wallet/sdk';
+
+const multisig = new MultiSigManager(client);
+
+// Propose (owner 1)
+const proposal = await multisig.propose({
+  target: tokenContract,
+  value: 0n,
+  data: transferData,
+});
+
+// Approve (owner 2)
+await multisig.approve(proposal.id);
+// If threshold met → UserOp submitted automatically
+```
+
+---
+
+## Account Recovery
+
+### Social Recovery (Guardian-Based)
+
+```typescript
+import { SocialRecovery } from '@aspect-wallet/sdk';
+
+const recovery = new SocialRecovery(client);
+
+// Guardian A initiates
+await recovery.initiate({
+  account: userWallet,
+  newOwner: newKeyAddress,
+});
+
+// Guardian B approves
+await recovery.approve({ account: userWallet });
+
+// After timelock (e.g., 3 days) → execute
+await recovery.execute({ account: userWallet });
+
+// Owner can cancel during timelock
+await recovery.cancel();
+
+// Check status
+const status = await recovery.getStatus(walletAddress);
+// { pending: true, approvals: 2, threshold: 2, executeAfter: ..., canExecute: false }
+```
+
+### Key Rotation (Two-Step)
+
+```typescript
+import { KeyRotation } from '@aspect-wallet/sdk';
+
+const rotation = new KeyRotation(client);
+
+// Step 1: Current owner initiates
+await rotation.initiate({ newOwner: newSignerAddress });
+
+// Step 2: New owner accepts
+await rotation.accept();
+// Old key immediately loses access. Account address unchanged.
+```
+
+### Multi-Device
+
+```typescript
+import { DeviceManager } from '@aspect-wallet/sdk';
+
+const devices = new DeviceManager(client);
+
+await devices.add({ name: 'iPhone 15', type: 'passkey', moduleId: 2 });
+await devices.remove(moduleId); // Remove lost device
+
+const list = await devices.list(walletAddress);
+// [{ moduleId: 0, name: 'MacBook', type: 'turnkey', active: true }, ...]
+```
+
+---
+
+## Security & Emergency
+
+### Emergency Freeze
+
+```typescript
+import { FreezeManager } from '@aspect-wallet/sdk';
+
+const freeze = new FreezeManager(client);
+
+// Freeze account (revokes all session keys, suspends paymaster)
+await freeze.freeze({ reason: 'suspicious_activity' });
+
+// Unfreeze (requires MFA)
+await freeze.unfreeze();
+```
+
+### Bulk Session Key Revocation
+
+```typescript
+import { RevokeManager } from '@aspect-wallet/sdk';
+
+const revoke = new RevokeManager(client);
+await revoke.revokeAll(); // Revoke ALL session keys at once
+```
+
+### Watchtower Alerts
+
+```typescript
+import { WatchtowerClient } from '@aspect-wallet/sdk';
+
+const watchtower = new WatchtowerClient(client);
+
+await watchtower.subscribe({
+  account: walletAddress,
+  alerts: ['recovery_initiated', 'owner_changed', 'large_transfer'],
+  channels: {
+    email: 'user@example.com',
+    webhook: 'https://myapp.com/webhooks/security',
+  },
+});
+```
+
+---
+
+## Audit & Logging
+
+```typescript
+import { AuditClient } from '@aspect-wallet/sdk';
+
+const audit = new AuditClient(client);
+
+// Operation history
+const history = await audit.getHistory(walletAddress, {
+  limit: 50,
+  types: ['execute', 'deploy', 'module_install'],
+});
+
+// Each operation includes:
+// - userOpHash, transactionHash
+// - target, value, selector
+// - signer address + type (turnkey/passkey/session-key/multi-sig)
+// - sponsored (boolean), paymaster address
+// - gasCost, success, blockNumber, timestamp
+```
+
+---
+
+## Chain Configuration
+
+```typescript
+import { ChainRegistry } from '@aspect-wallet/sdk';
+
+const chains = new ChainRegistry();
+
+// Get chain config
+const config = chains.get('arbitrum-sepolia');
+// { chainId: 421614, entryPoint: '0x5FF1...', factory: '0x1DFC...', paymaster: '0x13e6...', ... }
+
+// Switch chains
+client.switchChain('base');
+
+// Same address across chains (CREATE2 determinism)
+const arbAddr = computeWalletAddress({ factory: arbFactory, owner, salt: 0n });
+const baseAddr = computeWalletAddress({ factory: baseFactory, owner, salt: 0n });
+// arbAddr === baseAddr (if factories deployed at same address)
+```
+
+---
+
+## Bundler Client
+
+```typescript
+import { BundlerClient } from '@aspect-wallet/sdk';
+
+const bundler = new BundlerClient({ url: 'https://bundler.yourapp.com/rpc' });
+
+// Submit UserOp
+const hash = await bundler.sendUserOperation(signedUserOp, entryPointAddress);
+
+// Wait for receipt (exponential backoff)
+const receipt = await bundler.waitForReceipt(hash, {
+  timeout: 60_000,
+  pollingInterval: 2_000,
+});
+
+// Gas estimation
+const gas = await bundler.estimateUserOperationGas(userOp, entryPointAddress);
+// { preVerificationGas, verificationGasLimit, callGasLimit }
+
+// Check supported entry points
+const entryPoints = await bundler.supportedEntryPoints();
+```
+
+---
+
+## Error Handling
+
+All errors are typed via `FcxError`:
+
+```typescript
+import { FcxError } from '@aspect-wallet/sdk';
+
+try {
+  await client.execute({ ... });
+} catch (e) {
+  if (e instanceof FcxError) {
+    switch (e.code) {
+      case 'USEROP_SIGNATURE_INVALID':  // -32507
+      case 'USEROP_SIMULATION_FAILED':  // -32500
+      case 'SPONSOR_BUDGET_EXHAUSTED':  // Budget exceeded
+      case 'SESSION_KEY_EXPIRED':       // Session key time range expired
+      case 'SESSION_KEY_NOT_ALLOWED':   // Target/selector not in allowlist
+      case 'MFA_THRESHOLD_NOT_MET':     // Not enough signatures
+      case 'AUTH_SESSION_EXPIRED':      // JWT expired
+        // Handle specific error
+        break;
+    }
+    console.error(e.code, e.message, e.details);
+  }
+}
+```
+
+---
+
+## Deployed Contracts
+
+### Arbitrum Sepolia (Testnet)
+
+| Contract | Address |
+|----------|---------|
+| EntryPoint v0.6 | `0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789` |
+| SimpleAccountFactory | `0x1DFCc3c2ae138Da4BdF00DBF62CFf6f922D353EA` |
+| SimpleAccount (impl) | `0xe6FEe0AF343A9c59a03070Ef4239519bD6C243F2` |
+| VerifyingPaymaster | `0x13e6e887168d5ca78a47fac4EF71Ec5d0C6a9d2B` |
+
+---
+
+## Architecture
+
+```
+Your Frontend App
+       │
+       ▼
+@aspect-wallet/sdk (this package)
+       │
+       ├── Bundler RPC ──────── eth_sendUserOperation ──► EntryPoint (on-chain)
+       │                                                       │
+       ├── Paymaster Service ── POST /api/paymaster/sign       ├── Smart Account (proxy)
+       │                                                       ├── Factory (CREATE2)
+       ├── Auth Server ──────── POST /auth/email/verify        ├── Paymaster (verifying)
+       │                        POST /auth/oauth/google        └── Validation Modules
+       │                                                            ├── SingleSigner
+       └── Turnkey Enclave ─── Key generation + signing             ├── WebAuthn (P256)
+           (AWS Nitro)          via cross-origin iframe              ├── MultiSig (K-of-N)
+                                                                    ├── SessionKey + hooks
+                                                                    └── SocialRecovery
+```
+
+---
+
+## TypeScript Types
+
+All types are exported and available for your application:
+
+```typescript
+import type {
+  UserOperation,
+  ExecutionResult,
+  SessionInfo,
+  WalletState,
+  SessionKeyPermissions,
+  PaymasterApproval,
+  RecoveryStatus,
+  AuditOperation,
+} from '@aspect-wallet/sdk';
+
+// Or import types separately
+import type { UserOperation } from '@aspect-wallet/sdk/types';
+```
+
+---
+
+## Requirements
+
+- Node.js >= 18
+- `viem` >= 2.0.0 (peer dependency)
+- EVM chain with ERC-4337 EntryPoint v0.6 deployed
+
+## License
+
+MIT