# Authentication URL: /docs/authentication Deep dive into Bitcoin-based authentication flows *** title: Authentication description: Deep dive into Bitcoin-based authentication flows -------------------------------------------------------------- # Authentication Learn how Bitcoin-based authentication works in BigBlocks. ## Overview BigBlocks implements `bitcoin-auth`, using public-private key pairs as a primary authentication mechanism. This enables compatibility with Identity related blocks, which use [Bitcoin Attestation Protocol](https://github.com/b-open-io/bap) under the hood to establish a self-sovereign identity. ## Key Principles ### 1. Client-Side Key Generation * Private keys are generated on the client, never shared with the backend * Componenets never directly expose keys with two exceptions: * local backup componenets: downloads encrypted/unencrypted backup files, * cloud backup componenets uploads encrypted backups to the cloud * Keys never leave the user's device unencrypted * Leverages cryptographic standards like: * Type42 key derivation for identity * BRC77 message signing for authentication ### 2. Password Encryption * Users set a password to encrypt their private keys * Password is used for local encryption only * Lost passwords cannot be recovered (by design) * `bitcoin-backup` encryption functions for storing encrypted backups ### 3. OAuth Backup Storage * Encrypted backups stored via OAuth providers (Google, GitHub, X) * OAuth is used for storage only, not authentication * Multiple backup locations for redundancy ### 4. BSM/BRC77 Authentication * Bitcoin Signed Messages (BSM) or BRC77 can be used to authenticate API requests * `bitcoin-auth` abstracts the underlying auth token generation * Time-bound signatures prevent replay attacks * body-bound signatures ensure the message is not tampered with * Bigblocks provides compatibility with JWT based authentication flows ## Authentication Components ### AuthFlowOrchestrator Complete authentication flow management: ```tsx import { AuthFlowOrchestrator } from 'bigblocks'; function AuthPage() { return ( { console.log('Authenticated:', user); }} onError={(error) => { console.error('Auth failed:', error); }} /> ); } ``` ### LoginForm Standalone login component: ```tsx import { LoginForm } from 'bigblocks'; function LoginPage() { return ( router.push('/dashboard')} showBackupImport={true} showOAuthRestore={true} /> ); } ``` ### SignupFlow Multi-step signup process: ```tsx import { SignupFlow } from 'bigblocks'; function SignupPage() { return ( { console.log('Signup complete:', user); }} /> ); } ``` ## Authentication Flow ### 1. New User Signup ```mermaid graph TD A[User Clicks Signup] --> B[Generate HD Keys] B --> C[User Sets Password] C --> D[Encrypt Private Keys] D --> E[Create BAP Identity] E --> F[OAuth Backup Storage] F --> G[Authentication Complete] ``` ### 2. Existing User Login ```mermaid graph TD A[User Enters Password] --> B[Decrypt Local Storage] B --> C{Keys Found?} C -->|Yes| D[Authenticate with BSM] C -->|No| E[Import from Backup] E --> F[OAuth Provider Selection] F --> G[Download Encrypted Backup] G --> H[Decrypt with Password] H --> D ``` ### 3. OAuth Restore Flow ```tsx import { OAuthRestoreFlow } from 'bigblocks'; function RestorePage() { return ( { console.log('Backup restored:', backup); }} /> ); } ``` ## API Authentication ### Setting Up API Routes ```typescript // api/protected/route.ts import { verifyBSM } from 'bigblocks/auth'; export async function POST(request: Request) { try { const { address, signature, message } = await request.json(); // Verify the BSM signature const isValid = await verifyBSM({ address, signature, message, maxAge: 600 // 10 minutes }); if (!isValid) { return new Response('Unauthorized', { status: 401 }); } // Process authenticated request return new Response('Success'); } catch (error) { return new Response('Invalid signature', { status: 401 }); } } ``` ### Client-Side API Calls ```typescript import { useAuth, signMessage } from 'bigblocks'; function MyComponent() { const { address, privateKey } = useAuth(); const callAPI = async () => { const message = `Authenticate ${Date.now()}`; const signature = await signMessage(message, privateKey); const response = await fetch('/api/protected', { method: 'POST', headers: { 'Content-Type': 'application/json', }, body: JSON.stringify({ address, signature, message, }), }); }; } ``` ## Security Considerations ### Password Requirements * Minimum 8 characters recommended * Password strength indicator included * No password recovery possible (feature, not bug) ### Backup Security * Backups are AES-256 encrypted * Encryption happens client-side * OAuth providers cannot decrypt backups * Multiple backup locations recommended ### Key Storage * Keys stored in browser's localStorage * Always encrypted at rest * Session storage for temporary decryption * Auto-lock after inactivity ## Best Practices 1. **Always use HTTPS** in production 2. **Implement rate limiting** on authentication endpoints 3. **Use time-bound signatures** for API calls 4. **Educate users** about password importance 5. **Provide backup download** options 6. **Test restore flows** thoroughly ## Troubleshooting ### Common Issues **"Invalid signature" errors** * Check system clock synchronization * Verify message format matches * Ensure private key is correct **"Backup not found" errors** * User may have wrong OAuth account * Check all linked providers * Verify backup was created **"Decryption failed" errors** * Wrong password entered * Backup may be corrupted * Try alternative backup sources ## Next Steps * Implement [Profile Management](/docs/components/profiles) * Add [Social Features](/docs/components/social) * Set up [Wallet Integration](/docs/components/wallet) # Components Overview URL: /docs/components Full reference for all BigBlocks components *** title: Components Overview description: Full reference for all BigBlocks components -------------------------------------------------------- # Components Overview BigBlocks provides 96+ production-ready components organized into logical categories. ## Component Categories ### Authentication Components Core components for Bitcoin-based authentication flows. ```tsx import { AuthButton } from 'bigblocks'; // Simple authentication button // With custom text Sign In with Bitcoin // With callback console.log('Authenticated:', user)} /> ``` **Key Components:** * `AuthFlowOrchestrator` - Complete authentication flow * `LoginForm` - Standalone login interface * `SignupFlow` - Multi-step signup process * `OAuthProviders` - OAuth provider selection * `BackupImport` - Import encrypted backups * `PasswordInput` - Secure password field ### Profile & Identity Manage Bitcoin Attestation Protocol (BAP) profiles. ```tsx import { ProfileCard } from 'bigblocks'; console.log('Edit profile')} onViewDetails={() => console.log('View details')} /> ``` **Key Components:** * `ProfileCard` - Display user profiles * `ProfileEditor` - Edit profile information * `ProfileSwitcher` - Switch between identities * `ProfileManager` - Complete profile system * `IdentityGeneration` - Create new identities ### Wallet Components Bitcoin wallet functionality and transaction management. **Key Components:** * `WalletConnect` - Connect wallets * `WalletOverview` - Display balance and history * `SendBSVButton` - Send Bitcoin transactions * `DonateButton` - Accept donations * `TokenBalance` - Display token balances * `TransactionHistory` - Show transaction list ### Social Components Build social features with on-chain interactions. **Key Components:** * `PostCard` - Display social posts * `PostButton` - Create new posts * `LikeButton` - Like content on-chain * `FollowButton` - Follow users * `SocialFeed` - Content feed display * `FriendsDialog` - Manage connections ### Market Components Ordinals marketplace and trading functionality. **Key Components:** * `MarketTable` - Display marketplace listings * `CreateListingButton` - List items for sale * `BuyListingButton` - Purchase items * `CompactMarketTable` - Minimal market view ### MetaLens Commenting System Universal commenting for any context type. **Key Components:** * `MetaLensProvider` - Commenting system provider * `MetaLensComments` - Full commenting interface * `MetaLensBadge` - Comment count badges * `MetaLensEmbed` - Embedded comments * `MetaLensReactions` - Like/reaction system * `MetaLensThread` - Threaded discussions ### UI Primitives Basic building blocks for your application. ```tsx import { LoadingButton, StepIndicator, WarningCard, ErrorDisplay } from 'bigblocks'; // Loading button states Save Saving... // Multi-step indicator // Warning messages This action cannot be undone. // Error handling ``` **Key Components:** * `Modal` - Accessible modal dialogs * `LoadingButton` - Button with loading states * `ErrorDisplay` - Error message display * `SuccessLayout` - Success confirmations * `StepIndicator` - Multi-step indicators * `TerminalCodeBlock` - Code display ### Advanced BAP Components Advanced Bitcoin Attestation Protocol features. **Key Components:** * `KeyManager` - HD key management * `BapEncryption` - Encrypt/decrypt data * `FileSignature` - Sign files * `KeyRotation` - Rotate keys * `Type42KeyDerivation` - Advanced derivation * `ShamirSecretSharing` - Split keys ## Component Requirements ### Provider Requirements Most components require these providers: ```tsx {/* Your components */} ``` ### Authentication Requirements Components are marked with requirement badges: * **No Auth Required** - Works without authentication * **Auth Required** - Requires signed-in user * **Funding Required** - Needs BSV balance * **Droplit Required** - Uses gasless transactions ## Using Components ### Import Components ```tsx import { AuthButton, ProfileCard, WalletOverview } from 'bigblocks'; ``` ### Add Individual Components ```bash npx bigblocks add AuthButton ProfileCard ``` ### Component Props All components are fully typed with TypeScript. Use your IDE's IntelliSense for prop discovery or refer to individual component documentation. ## Next Steps * Browse the [Component Browser](/components) for live demos * Check [Component Examples](/docs/examples) for usage patterns * Read about [Theme Customization](/docs/themes) # Documentation URL: /docs BigBlocks documentation overview *** title: Documentation description: BigBlocks documentation overview --------------------------------------------- # Documentation Welcome to the BigBlocks documentation. Choose a section below to get started: ## Getting Started * [What is BigBlocks?](/docs/introduction/what-is-bigblocks) - Overview and key features * [Quick Start](/docs/introduction/quickstart) - Get up and running fast ## Core Documentation * [Authentication](/docs/authentication) - Bitcoin auth system * [Components](/docs/components) - 96+ production-ready components * [MCP Server](/docs/mcp-server) - AI assistant integration * [MetaLens](/docs/metalens) - Universal commenting system ## External Resources * [LLMs.txt](/llms.txt) - AI-readable documentation format # MetaLens Commenting System URL: /docs/metalens Universal commenting system for any context *** title: MetaLens Commenting System description: Universal commenting system for any context -------------------------------------------------------- # MetaLens Commenting System MetaLens is a universal commenting system that enables comments on any context type - URLs, transactions, geohashes, ISBNs, and more. ## Overview MetaLens provides a complete commenting solution with: * Zero-cost transactions via Droplit integration * Full B:// and MAP protocol support * Real-time updates * Moderation capabilities * Multiple context types ## Supported Context Types * `url` - Web pages and resources * `tx` - Bitcoin transactions * `upc` - Product barcodes * `geohash` - Geographic locations * `ipfs` - IPFS content hashes * `isbn` - Books and publications * `doi` - Digital object identifiers ## Basic Usage ### Simple Comments Section ```tsx import { MetaLensProvider, MetaLensComments } from 'bigblocks'; function MyPage() { return ( ); } ``` ### Comment Count Badge Display comment counts inline with content: ```tsx ``` ### Reactions Add likes and reactions to any content: ```tsx ``` ## Advanced Features ### Threaded Discussions Enable nested comment threads: ```tsx ``` ### Embedded Comments Lightweight comment widget: ```tsx ``` ### Custom Styling MetaLens components support custom styling: ```tsx ``` ## Configuration ### Provider Options ```tsx {children} ``` ### Comment Options ```tsx console.log('New comment:', comment)} onError={(error) => console.error('Comment error:', error)} /> ``` ## Integration Examples ### E-commerce Product Comments ```tsx function ProductPage({ productUPC }) { return (

Product Name

); } ``` ### Transaction Explorer Comments ```tsx function TransactionDetails({ txid }) { return (

Transaction {txid}

); } ``` ### Location-Based Comments ```tsx function LocationComments({ latitude, longitude }) { const geohash = encodeGeohash(latitude, longitude); return ( ); } ``` ## Zero-Cost Transactions MetaLens uses Droplit integration for gasless operations: 1. Comments are created without requiring BSV balance 2. Droplit handles transaction fees 3. Comments are still recorded on-chain 4. Full ownership and immutability preserved ## Data Structure MetaLens comments follow the MAP protocol: ```json { "app": "metalens", "type": "comment", "context": "url", "contextValue": "https://example.com", "content": "This is a comment", "timestamp": 1704067200, "author": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa" } ``` ## Best Practices 1. **Choose appropriate context types** - Use the most specific context for your use case 2. **Enable moderation** - For public-facing applications 3. **Implement rate limiting** - Prevent spam 4. **Cache comment counts** - For performance 5. **Handle errors gracefully** - Network issues may occur ## API Integration ### Backend Setup ```typescript // api/metalens/comments/route.ts import { getMetaLensComments } from 'bigblocks/metalens'; export async function GET(request: Request) { const { searchParams } = new URL(request.url); const context = searchParams.get('context'); const value = searchParams.get('value'); const comments = await getMetaLensComments({ context, value, limit: 50, offset: 0, }); return Response.json(comments); } ``` ### Creating Comments ```typescript import { createMetaLensComment } from 'bigblocks/metalens'; export async function POST(request: Request) { const { context, value, content, author } = await request.json(); const comment = await createMetaLensComment({ context, value, content, author, droplit: true, // Use gasless transaction }); return Response.json(comment); } ``` ## Next Steps * Explore [Component Examples](/docs/examples) for more patterns * Learn about [Droplit Integration](/docs/droplit) * Read the [MAP Protocol Guide](/docs/protocols) # Storage Adapter URL: /docs/components/storage-adapter Pluggable storage interface for BigBlocks authentication and data persistence *** title: Storage Adapter description: Pluggable storage interface for BigBlocks authentication and data persistence category: utilities ------------------- import { StorageAdapterDemo } from '@/components/docs/demos/StorageAdapterDemo'; # Storage Adapter A pluggable storage interface that provides a consistent API for data persistence across different environments. BigBlocks uses storage adapters for authentication data, session management, and backup persistence. ## Installation ```bash npx bigblocks add storage-adapter ``` ## Import ```typescript import { createMemoryStorage, createLocalStorage } from 'bigblocks'; ``` ## Interface All storage adapters implement the `StorageAdapter` interface: ```typescript interface StorageAdapter { get: (key: string) => Promise; set: (key: string, value: string) => Promise; delete: (key: string) => Promise; clear?: () => Promise; } ``` ## Built-in Adapters ### Memory Storage For testing and development without persistence: ```typescript import { createMemoryStorage } from 'bigblocks'; const storage = createMemoryStorage(); // Usage with auth const authManager = createAuthManager({ apiUrl: '/api', storage: storage }); ``` ### Local Storage For browser-based persistence: ```typescript import { createLocalStorage } from 'bigblocks'; const storage = createLocalStorage(); // With namespace const namespacedStorage = createLocalStorage('myapp'); ``` ### Session Storage For temporary session-based storage: ```typescript import { createSessionStorage } from 'bigblocks'; const storage = createSessionStorage(); ``` ## Custom Storage Adapters ### Server-Side Storage For Node.js environments: ```typescript import { StorageAdapter } from 'bigblocks'; class ServerStorageAdapter implements StorageAdapter { private storage = new Map(); async get(key: string): Promise { // Implement database/file system retrieval return this.storage.get(key) || null; } async set(key: string, value: string): Promise { // Implement database/file system storage this.storage.set(key, value); } async delete(key: string): Promise { // Implement database/file system removal this.storage.delete(key); } async clear(): Promise { // Clear all stored data this.storage.clear(); } } const auth = createAuthManager({ apiUrl: '/api', storage: new ServerStorageAdapter() }); ``` ### Redis Storage For distributed applications: ```typescript import Redis from 'ioredis'; import { StorageAdapter } from 'bigblocks'; class RedisStorageAdapter implements StorageAdapter { private redis: Redis; private namespace: string; constructor(redisUrl: string, namespace = 'bigblocks:') { this.redis = new Redis(redisUrl); this.namespace = namespace; } async get(key: string): Promise { return this.redis.get(this.namespace + key); } async set(key: string, value: string): Promise { await this.redis.set(this.namespace + key, value); } async delete(key: string): Promise { await this.redis.del(this.namespace + key); } async clear(): Promise { const keys = await this.redis.keys(this.namespace + '*'); if (keys.length > 0) { await this.redis.del(...keys); } } } const auth = createBigBlocksAuth({ storage: new RedisStorageAdapter(process.env.REDIS_URL!) }); ``` ### Encrypted Storage For enhanced security: ```typescript import { StorageAdapter } from 'bigblocks'; import CryptoJS from 'crypto-js'; class EncryptedStorageAdapter implements StorageAdapter { private storage: StorageAdapter; private encryptionKey: string; constructor(storage: StorageAdapter, encryptionKey: string) { this.storage = storage; this.encryptionKey = encryptionKey; } async get(key: string): Promise { const encrypted = await this.storage.get(key); if (!encrypted) return null; try { const bytes = CryptoJS.AES.decrypt(encrypted, this.encryptionKey); return bytes.toString(CryptoJS.enc.Utf8); } catch { return null; // Invalid or corrupted data } } async set(key: string, value: string): Promise { const encrypted = CryptoJS.AES.encrypt(value, this.encryptionKey).toString(); await this.storage.set(key, encrypted); } async delete(key: string): Promise { await this.storage.delete(key); } async clear(): Promise { await this.storage.clear(); } } // Usage const baseStorage = createLocalStorage(); const encryptedStorage = new EncryptedStorageAdapter(baseStorage, 'secret-key'); const auth = createAuthManager({ apiUrl: '/api', storage: encryptedStorage }); ``` ## Usage with Components ### AuthManager ```typescript import { createAuthManager, createMemoryStorage } from 'bigblocks'; const authManager = createAuthManager({ apiUrl: '/api', storage: createMemoryStorage(), // For testing storageNamespace: 'auth:' }); ``` ### BitcoinAuthProvider ```typescript import { BitcoinAuthProvider, createLocalStorage } from 'bigblocks'; function App() { return ( {/* Your app */} ); } ``` ### createBigBlocksAuth ```typescript import { createBigBlocksAuth, createSessionStorage } from 'bigblocks'; const auth = createBigBlocksAuth({ apiUrl: '/api', storage: createSessionStorage(), storageNamespace: 'bigblocks:auth:' }); ``` ## Configuration Options ### Storage Namespacing Use namespaces to avoid key conflicts: ```typescript const auth = createAuthManager({ apiUrl: '/api', storage: createLocalStorage(), storageNamespace: 'myapp:auth:' // Prefix for all keys }); ``` ### Multiple Storage Instances Use different storage for different purposes: ```typescript const sessionStorage = createSessionStorage(); const localStorage = createLocalStorage(); // Session data const auth = createAuthManager({ apiUrl: '/api', storage: sessionStorage }); // Persistent user preferences const preferences = { storage: localStorage, get: (key: string) => localStorage.get(`prefs:${key}`), set: (key: string, value: string) => localStorage.set(`prefs:${key}`, value) }; ``` ## Testing ### Mock Storage For unit tests: ```typescript import { StorageAdapter } from 'bigblocks'; class MockStorageAdapter implements StorageAdapter { private data: Record = {}; async get(key: string): Promise { return this.data[key] || null; } async set(key: string, value: string): Promise { this.data[key] = value; } async delete(key: string): Promise { delete this.data[key]; } async clear(): Promise { this.data = {}; } // Test helpers getData() { return { ...this.data }; } setData(data: Record) { this.data = { ...data }; } } // In tests const mockStorage = new MockStorageAdapter(); const auth = createAuthManager({ apiUrl: '/api', storage: mockStorage }); // Verify storage calls expect(mockStorage.getData()).toEqual({ 'auth:session': 'encrypted-session-data' }); ``` ## Error Handling ### Graceful Degradation ```typescript class FallbackStorageAdapter implements StorageAdapter { private primary: StorageAdapter; private fallback: StorageAdapter; constructor(primary: StorageAdapter, fallback: StorageAdapter) { this.primary = primary; this.fallback = fallback; } async get(key: string): Promise { try { return await this.primary.get(key); } catch { return await this.fallback.get(key); } } async set(key: string, value: string): Promise { try { await this.primary.set(key, value); } catch { await this.fallback.set(key, value); } } async delete(key: string): Promise { await Promise.all([ this.primary.delete(key).catch(() => {}), this.fallback.delete(key).catch(() => {}) ]); } async clear(): Promise { await Promise.all([ this.primary.clear().catch(() => {}), this.fallback.clear().catch(() => {}) ]); } } // Usage const storage = new FallbackStorageAdapter( createLocalStorage(), createMemoryStorage() ); ``` ### Storage Quota Management ```typescript class QuotaAwareStorage implements StorageAdapter { private storage: StorageAdapter; private maxSize: number; constructor(storage: StorageAdapter, maxSize = 5 * 1024 * 1024) { // 5MB this.storage = storage; this.maxSize = maxSize; } async setItem(key: string, value: string): Promise { if (value.length > this.maxSize) { throw new Error('Value exceeds storage quota'); } try { await this.storage.set(key, value); } catch (error) { if (error.name === 'QuotaExceededError') { // Clear old data and retry await this.cleanupOldData(); await this.storage.set(key, value); } else { throw error; } } } private async cleanupOldData(): Promise { // Implement cleanup strategy console.warn('Storage quota exceeded, cleaning up old data'); } async get(key: string): Promise { return this.storage.get(key); } async delete(key: string): Promise { return this.storage.delete(key); } async clear(): Promise { return this.storage.clear(); } } ``` ## Best Practices 1. **Choose the Right Adapter**: Use memory storage for testing, local storage for browsers, custom adapters for servers 2. **Handle Async Operations**: Many storage operations are async, always await them 3. **Use Namespaces**: Prevent key conflicts with proper namespacing 4. **Error Handling**: Implement fallback strategies for storage failures 5. **Security**: Use encrypted storage for sensitive data 6. **Testing**: Mock storage for unit tests to avoid side effects ## Common Patterns ### Configuration Factory ```typescript function createStorageConfig(env: 'development' | 'test' | 'production') { switch (env) { case 'test': return createMemoryStorage(); case 'development': return createLocalStorage('dev'); case 'production': return new EncryptedStorageAdapter( createLocalStorage(), process.env.ENCRYPTION_KEY! ); } } const storage = createStorageConfig(process.env.NODE_ENV); ``` ### Multi-Layer Storage ```typescript class CachedStorageAdapter implements StorageAdapter { private cache: StorageAdapter; private persistent: StorageAdapter; constructor(cache: StorageAdapter, persistent: StorageAdapter) { this.cache = cache; this.persistent = persistent; } async get(key: string): Promise { // Try cache first let value = await this.cache.get(key); if (value === null) { // Fallback to persistent storage value = await this.persistent.get(key); if (value !== null) { // Cache for next time await this.cache.set(key, value); } } return value; } async set(key: string, value: string): Promise { await Promise.all([ this.cache.set(key, value), this.persistent.set(key, value) ]); } async delete(key: string): Promise { await Promise.all([ this.cache.delete(key), this.persistent.delete(key) ]); } async clear(): Promise { await Promise.all([ this.cache.clear(), this.persistent.clear() ]); } } ``` ## Related Components * [createMemoryStorage](/docs/components/create-memory-storage) - Memory-based storage utility * [createLocalStorage](/docs/components/create-local-storage) - Browser localStorage wrapper * [AuthManager](/docs/components/auth-manager) - Uses storage for session persistence * [BitcoinAuthProvider](/docs/components/bitcoin-auth-provider) - Provider with storage configuration ## API Reference This component provides a consistent storage interface for all BigBlocks components and utilities. The interface supports both synchronous and asynchronous operations to accommodate different storage backends. ### Core Interface ```typescript interface StorageAdapter { get: (key: string) => Promise; set: (key: string, value: string) => Promise; delete: (key: string) => Promise; clear?: () => Promise; } ``` ### Built-in Utilities * `createMemoryStorage()` - In-memory storage for testing * `createLocalStorage(namespace?)` - Browser localStorage wrapper * `createSessionStorage(namespace?)` - Browser sessionStorage wrapper # Quick Start URL: /docs/introduction/quickstart Get up and running with BigBlocks in minutes *** title: Quick Start description: Get up and running with BigBlocks in minutes --------------------------------------------------------- Get up and running with BigBlocks in minutes.

Interactive Quick Start

Try our interactive tutorial with live examples and step-by-step guidance

## Installation ### Using npm/yarn/bun ```bash # npm npm install bigblocks@latest # yarn yarn add bigblocks@latest # bun bun add bigblocks@latest ``` ### Using init-prism For a complete project setup with BigBlocks pre-configured: ```bash npm install -g init-prism@latest init-prism create my-app --bigblocks ``` ## Basic Setup ### 1. Add Required Providers Wrap your application with the necessary providers: ```tsx import { BitcoinAuthProvider, BitcoinQueryProvider, BitcoinThemeProvider } from 'bigblocks'; function App() { return ( {/* Your app content */} ); } ``` ### 2. Add Your First Component Import and use any BigBlocks component: ```tsx import { AuthButton, ProfileCard } from 'bigblocks'; function MyComponent() { return (

); } ``` ### 3. Framework-Specific Setup #### Next.js (App Router) ```typescript // app/api/auth/[...nextauth]/route.ts import { createNextJSBigBlocks } from 'bigblocks/nextjs'; const { auth, handlers } = createNextJSBigBlocks({ // Your config }); export { handlers.GET, handlers.POST }; ``` #### Express ```typescript import { createExpressBigBlocks } from 'bigblocks/express'; const bigblocks = createExpressBigBlocks({ // Your config }); app.use('/auth', bigblocks.router); ``` #### Astro ```typescript import { createAstroBigBlocks } from 'bigblocks/astro'; const bigblocks = createAstroBigBlocks({ // Your config }); ``` ## Core Concepts ### Bitcoin as Identity In BigBlocks, Bitcoin private keys ARE the user's identity: * No traditional usernames or passwords * Client-side key generation only * BSM (Bitcoin Signed Messages) for authentication * Encrypted backup storage via OAuth providers ### Required Providers Most BigBlocks components require these context providers: 1. **BitcoinAuthProvider** - Manages authentication state 2. **BitcoinQueryProvider** - Handles data fetching 3. **BitcoinThemeProvider** - Provides theme context ### Component Categories BigBlocks components are organized into categories: * **Authentication** - Login, signup, OAuth flows * **Profiles** - Identity and profile management * **Wallet** - Bitcoin transactions and balances * **Social** - Posts, likes, follows * **Market** - Trading and marketplace * **MetaLens** - Universal commenting system * **UI Primitives** - Basic building blocks ## Next Steps * Explore the [Component Browser](/components) to see all available components * Learn about [Bitcoin Authentication](/docs/authentication) * Try the [Theme Builder](/themes) to customize your app * Check out [Common Patterns](/docs/guides) for best practices # What is BigBlocks? URL: /docs/introduction/what-is-bigblocks Complete guide to Bitcoin authentication components *** title: What is BigBlocks? description: Complete guide to Bitcoin authentication components ---------------------------------------------------------------- # What is BigBlocks? Welcome to BigBlocks - your complete guide to building Bitcoin applications with 96+ production-ready components. ## Overview BigBlocks is a comprehensive Bitcoin UI component library for React applications with framework-agnostic adapters. It provides everything you need to build Bitcoin-powered applications where private keys ARE the identity. ### Key Features * **Bitcoin-based Authentication** - No usernames or passwords required * **96+ Production Components** - Complete UI library from auth flows to social features * **Radix Themes Integration** - Full theme customization with dark/light mode support * **MetaLens Commenting System** (v0.0.17) - Universal commenting for any context * **Framework Adapters** - Native support for Next.js, Express, and Astro * **Zero-cost Transactions** - Droplit integration for gasless operations ## Quick Links * [Getting Started](/docs/getting-started) - Installation and setup * [Authentication](/docs/authentication) - Bitcoin auth flows * [Components](/docs/components) - Full component reference * [MetaLens](/docs/metalens) - Commenting system guide * [API Reference](/docs/api) - Backend integration * [Guides](/docs/guides) - Common patterns and recipes # MCP Server URL: /docs/mcp-server Bitcoin development toolkit for AI assistants via Model Context Protocol *** title: MCP Server description: Bitcoin development toolkit for AI assistants via Model Context Protocol ------------------------------------------------------------------------------------- # BigBlocks MCP Server The BigBlocks MCP (Model Context Protocol) Server provides Bitcoin development capabilities directly to AI assistants like Claude, enabling seamless Bitcoin application development. ## What is MCP? Model Context Protocol (MCP) is an open standard that allows AI assistants to securely connect to external systems and tools. The BigBlocks MCP Server exposes Bitcoin functionality as a set of tools that AI assistants can use to help you build Bitcoin applications. ## Features * **Component Generation** - Access to 90+ BigBlocks component prompts * **Bitcoin Operations** - Wallet creation, transaction signing, broadcasting * **BSV Blockchain** - Full Bitcoin SV blockchain integration * **Code Examples** - Production-ready code snippets and templates * **Best Practices** - Bitcoin development patterns and security guidelines ## Quick Start ### Installation ```bash # Install globally npm install -g bigblocks-mcp # Or run directly npx bigblocks-mcp ``` ### Connect to Claude 1. **Install the MCP Server**: ```bash npm install -g bigblocks-mcp ``` 2. **Add to Claude Desktop**: Open Claude Desktop settings and add: ```json { "mcpServers": { "bigblocks": { "command": "npx", "args": ["bigblocks-mcp"] } } } ``` 3. **Restart Claude Desktop** and you'll see BigBlocks tools available ## Available Tools ### Component Tools * `get_component_prompt` - Get prompts for specific BigBlocks components * `search_components` - Search components by category or functionality * `list_categories` - List all available component categories ### Bitcoin Tools * `create_wallet` - Generate new Bitcoin wallets * `sign_transaction` - Sign Bitcoin transactions * `broadcast_transaction` - Broadcast transactions to BSV network * `get_balance` - Check wallet balances * `get_utxos` - Retrieve unspent transaction outputs ### Development Tools * `generate_template` - Create project templates with BigBlocks * `validate_setup` - Check development environment * `get_examples` - Access code examples and patterns ## Example Usage Once connected, you can ask Claude: > "Create a Bitcoin payment button component using BigBlocks" Claude will use the MCP server to: 1. Fetch the appropriate component prompt 2. Generate the code with proper Bitcoin integration 3. Provide setup and usage instructions 4. Include security best practices ## Configuration The MCP server supports various configuration options: ```json { "mcpServers": { "bigblocks": { "command": "npx", "args": ["bigblocks-mcp"], "env": { "BIGBLOCKS_API_URL": "https://api.bigblocks.dev", "BSV_NETWORK": "mainnet" } } } } ``` ## Supported AI Assistants * **Claude Desktop** - Full support * **VS Code with MCP** - Full support * **Cursor** - Full support * **Other MCP-compatible tools** - Basic support ## Security The MCP server follows security best practices: * No private keys are stored or transmitted * All Bitcoin operations use proper signing workflows * API calls are authenticated and rate-limited * Local development mode available for testing ## Getting Help * [MCP Server Documentation](/mcp-server) * [Component Reference](/docs/components) * [GitHub Issues](https://github.com/b-open-io/bigblocks/issues) * [Discord Community](https://discord.gg/bigblocks) ## Next Steps 1. [Install the MCP Server](/mcp-server) 2. [Explore Components](/docs/components) 3. [Read the Getting Started Guide](/docs/introduction/quickstart) 4. [Join the Community](https://discord.gg/bigblocks) # AuthButton URL: /docs/components/authentication/auth-button Bitcoin authentication button component for sign-in and sign-up flows *** title: AuthButton description: Bitcoin authentication button component for sign-in and sign-up flows categories: \['auth', 'ui', 'onboarding'] providers: \['BitcoinAuthProvider'] ----------------------------------- import { AuthButtonDemo } from '@/components/docs/demos/AuthButtonDemo' import { ComponentBadges } from '@/components/docs/ComponentBadges' Authentication button that integrates with Bitcoin authentication flows and providers. AuthButton extends the [Radix Button primitive](https://www.radix-ui.com/themes/docs/components/button) with Bitcoin-specific authentication modes and seamless integration with [BitcoinAuthProvider](/docs/components/bitcoin-auth-provider). ## Installation ```bash npx bigblocks add auth-button ``` ## Import ```tsx import { AuthButton } from 'bigblocks'; ``` ## API Reference This component extends the [Button primitive](https://www.radix-ui.com/themes/docs/components/button) and inherits all its props. | Prop | Type | Default | Description | | -------------- | --------------------------------------------------------------------- | -------------------------------------- | ------------------------------------------------------------ | | mode | `'signin' \| 'signup' \| 'signout'` | `'signin'` | Authentication mode - determines flow behavior | | size | `Responsive<"1" \| "2" \| "3" \| "4">` | `"3"` | Button size | | variant | `"classic" \| "solid" \| "soft" \| "surface" \| "outline" \| "ghost"` | `"solid"` | Button variant style | | color | Radix color | - | Color theme | | className | `string` | - | Additional CSS classes | | style | `React.CSSProperties` | - | Inline styles | | children | `React.ReactNode` | - | Button content | | confirmSignOut | `boolean` | `false` | Whether to show confirmation dialog on sign out | | confirmMessage | `string` | `"Are you sure you want to sign out?"` | Custom confirmation message for sign out | | redirectTo | `string` | - | URL to redirect after sign out | | onSignOut | `() => void` | - | Callback fired after successful sign out | | showClearInfo | `boolean` | `false` | Whether to show detailed info about what happens on sign out | ## Basic Usage ```tsx import { AuthButton } from 'bigblocks'; export default function SignInPage() { return ( Sign In with Bitcoin ); } ``` ## Authentication Modes AuthButton automatically handles different authentication flows based on the `mode` prop: ```tsx // Sign-in mode - triggers existing user authentication Sign In // Sign-up mode - triggers new user registration flow Create Account // Sign-out mode - shows sign out button when authenticated Sign Out ``` ## Sign Out Customization AuthButton provides several options for customizing the sign out experience: ```tsx // Basic sign out with confirmation Sign Out // Custom confirmation message Log Out // Show detailed info and redirect after sign out console.log('User signed out')} > Sign Out Securely ``` ## Integration with Auth Provider AuthButton automatically integrates with [BitcoinAuthProvider](/docs/components/bitcoin-auth-provider) context: ```tsx import { AuthButton, BitcoinAuthProvider } from 'bigblocks'; export default function App() { return (

Connect Wallet

); } ``` For styling options (size, variant, color, etc.), see the [Radix Button documentation](https://www.radix-ui.com/themes/docs/components/button). ## Related Components * [BitcoinAuthProvider](/docs/components/bitcoin-auth-provider) - Authentication context provider * [LoginForm](/docs/components/login-form) - Complete authentication form * [AuthCard](/docs/components/auth-card) - Card layout for auth flows # AuthCard URL: /docs/components/authentication/auth-card Flexible card component designed for authentication forms and flows *** title: AuthCard description: Flexible card component designed for authentication forms and flows category: layouts ----------------- import { AuthCardDemo } from '@/components/docs/demos/AuthCardDemo'; A flexible card component designed specifically for authentication forms and flows. It provides a consistent structure with optional header, content area, and footer sections, making it ideal for login forms, signup flows, and other authentication-related UI. ## Installation ```bash npx bigblocks add auth-card ``` ## Import ```typescript import { AuthCard } from 'bigblocks'; ``` ## Props | Prop | Type | Required | Default | Description | | --------- | --------------------------------------- | -------- | ----------- | ----------------------- | | children | `ReactNode` | Yes | - | Card content | | title | `string` | No | - | Optional card title | | subtitle | `string` | No | - | Optional card subtitle | | footer | `ReactNode` | No | - | Optional footer content | | variant | `'default' \| 'outlined' \| 'elevated'` | No | `'default'` | Card style variant | | className | `string` | No | - | Additional CSS classes | ## Basic Usage ```tsx import { AuthCard } from 'bigblocks'; export default function Example() { return ( ); } ``` ## Advanced Usage ### With Footer ```tsx import { AuthCard } from 'bigblocks'; import { Text, Link } from '@radix-ui/themes'; export default function LoginCard() { return ( Don't have an account? Sign up } variant="elevated" > console.log('Logged in:', user)} /> ); } ``` ### Different Variants ```tsx import { AuthCard } from 'bigblocks'; export default function VariantExamples() { return (

{/* Default variant */}

Standard surface card with subtle background

{/* Outlined variant */}

Classic card with border

{/* Elevated variant */}

Surface card with shadow for emphasis

); } ``` ### Multi-Step Form ```tsx import { AuthCard } from 'bigblocks'; import { useState } from 'react'; export default function MultiStepAuth() { const [currentStep, setCurrentStep] = useState(1); const totalSteps = 3; return ( {currentStep === 1 && setCurrentStep(2)} />} {currentStep === 2 && setCurrentStep(3)} />} {currentStep === 3 && console.log('Done!')} />} ); } ``` ## Common Patterns ### Login Form ```tsx import { AuthCard, LoginForm } from 'bigblocks'; import { Link } from '@radix-ui/themes'; export function LoginPage() { return ( Forgot password? } > ); } ``` ### Error State ```tsx import { AuthCard, ErrorDisplay } from 'bigblocks'; export function AuthWithError({ error }) { return ( ); } ``` ### Loading State ```tsx import { AuthCard } from 'bigblocks'; import { Spinner } from '@radix-ui/themes'; export function LoadingAuth() { return (

); } ``` ### Custom Styling ```tsx import { AuthCard } from 'bigblocks'; export function StyledAuthCard() { return (

This card has custom background styling

); } ``` ## Styling AuthCard uses Radix Themes design tokens for consistent styling: * **Spacing**: Uses `--space-6` for consistent padding * **Colors**: Automatically adapts to the current theme * **Typography**: Uses Radix heading and text components * **Shadows**: `--shadow-6` for elevated variant ### Variant Styles * **default**: Standard surface card with subtle background * **outlined**: Classic card with border styling * **elevated**: Surface card with shadow for emphasis and depth ## Accessibility * Uses semantic HTML structure with proper heading hierarchy * Maintains keyboard navigation support * Compatible with screen readers * Proper ARIA attributes when needed ## Best Practices 1. **Title Hierarchy**: Use title for main heading, subtitle for supporting text 2. **Footer Content**: Ideal for secondary actions, links, or disclaimers 3. **Variant Selection**: * Use `default` for most authentication forms * Use `outlined` for secondary forms or nested cards * Use `elevated` for primary actions or important forms 4. **Responsive Design**: Card adapts to container width automatically 5. **Content Spacing**: Use consistent spacing within card content ## Troubleshooting ### Card Not Centered * Wrap AuthCard in a CenteredLayout component for page-level centering * Check parent container width and centering styles ### Styling Not Applied * Ensure Radix Themes CSS is imported * Check that BitcoinThemeProvider is wrapping your app * Verify custom classes don't conflict with Radix styles ### Content Overflow * AuthCard handles responsive sizing automatically * For very long content, consider pagination or scrollable areas * Test on various screen sizes ## Related Components * [AuthLayout](/docs/components/auth-layout) - Full-page authentication layout * [CenteredLayout](/docs/components/centered-layout) - Center content on page * [LoginForm](/docs/components/login-form) - Complete login form * [SignupFlow](/docs/components/signup-flow) - Multi-step signup process * [ErrorDisplay](/docs/components/error-display) - Error message display ## API Reference ### Variant Types * `'default'` - Standard surface styling * `'outlined'` - Border-based styling * `'elevated'` - Shadow-enhanced styling ### Layout Structure The AuthCard component creates the following structure: * Card container with variant styling * Optional header with title/subtitle * Main content area (children) * Optional footer section ## Integration Works seamlessly with other BigBlocks components: * Contains forms like `LoginForm`, `SignupFlow` * Pairs with `AuthLayout` for full-page layouts * Compatible with all authentication components * Integrates with theme system automatically # AuthFlowOrchestrator URL: /docs/components/authentication/auth-flow-orchestrator Unified authentication flow manager for intelligent routing through sign in, sign up, or wallet restoration *** title: AuthFlowOrchestrator description: Unified authentication flow manager for intelligent routing through sign in, sign up, or wallet restoration category: authentication ------------------------ A comprehensive authentication flow manager that intelligently routes users through sign in, sign up, OAuth restoration, device linking, or file import flows. This component provides a unified entry point for all authentication scenarios with automatic flow detection and seamless transitions. ## Installation ```bash npx bigblocks add auth-flow-orchestrator ``` ## Import ```typescript import { AuthFlowOrchestrator } from 'bigblocks'; ``` ## Props | Prop | Type | Required | Default | Description | | -------------------- | ----------------------------------------------- | -------- | ------------ | ----------------------------------- | | flowType | `AuthFlowType` | No | `'unified'` | Initial flow type | | initialStep | `AuthStep` | No | `'initial'` | Starting step in the flow | | enableOAuth | `boolean` | No | `true` | Enable OAuth provider options | | enableDeviceLink | `boolean` | No | `true` | Enable device linking flow | | enableFileImport | `boolean` | No | `true` | Enable file import for backups | | enableLocalBackup | `boolean` | No | `true` | Enable local backup storage | | enableProfileSync | `boolean` | No | `false` | Enable profile synchronization | | maxDiscoveryAttempts | `number` | No | `3` | Max attempts for profile discovery | | oauthProviders | `OAuthProvider[]` | No | - | Custom OAuth provider configuration | | onSuccess | `(user: {id: string, address: string}) => void` | No | - | Success callback | | onError | `(error: string) => void` | No | - | Error callback | | onFlowChange | `(flow: AuthFlowType) => void` | No | - | Flow change callback | | onStepChange | `(step: AuthStep) => void` | No | - | Step change callback | | title | `string` | No | - | Custom title | | subtitle | `string` | No | - | Custom subtitle | | showHeader | `boolean` | No | `true` | Show header section | | showFooter | `boolean` | No | `true` | Show footer section | | className | `string` | No | - | Additional CSS classes | | layout | `'centered' \| 'full' \| 'custom'` | No | `'centered'` | Layout style | | customLayout | `React.ComponentType` | No | - | Custom layout component | | autoDetectFlow | `boolean` | No | `true` | Auto-detect best flow | | persistFlow | `boolean` | No | `true` | Persist flow state | | debug | `boolean` | No | `false` | Enable debug mode | ## Flow Types ```typescript type AuthFlowType = | 'unified' // Auto-detect best flow | 'signin' // Direct sign in | 'signup' // New account creation | 'oauth-restore' // Restore via OAuth | 'device-link' // Link new device | 'import' // Import backup file | 'custom'; // Custom flow ``` ## Auth Steps ```typescript type AuthStep = | 'initial' // Starting point | 'signin' // Sign in form | 'signup' // Sign up form | 'password' // Password entry | 'confirm-password' // Password confirmation | 'backup-display' // Show backup | 'backup-download' // Download backup | 'oauth-link' // Link OAuth provider | 'oauth-restore' // Restore from OAuth | 'import-backup' // Import backup file | 'success'; // Success state ``` ## Basic Usage ```tsx import { AuthFlowOrchestrator, BitcoinAuthProvider } from 'bigblocks'; import { useRouter } from 'next/navigation'; export default function AuthPage() { const router = useRouter(); return ( { console.log('Auth successful:', user); router.push('/dashboard'); }} onError={(error) => { console.error('Auth failed:', error); }} /> ); } ``` ## Advanced Usage ### Specific Flow Type ```tsx import { AuthFlowOrchestrator } from 'bigblocks'; export default function SignUpOnly() { return ( { console.log('New user created:', user); }} /> ); } ``` ### Custom OAuth Providers ```tsx import { AuthFlowOrchestrator } from 'bigblocks'; import { FaGoogle, FaGithub } from 'react-icons/fa'; export default function CustomOAuth() { const customProviders = [ { id: 'google', name: 'Google', icon: }, { id: 'github', name: 'GitHub', icon: } ]; return ( { console.log('OAuth auth successful'); }} /> ); } ``` ### Track Flow Progress ```tsx import { AuthFlowOrchestrator } from 'bigblocks'; import { useState } from 'react'; export default function TrackedAuth() { const [currentFlow, setCurrentFlow] = useState('unified'); const [currentStep, setCurrentStep] = useState('initial'); return (

Current Flow: {currentFlow}

Current Step: {currentStep}

{ analytics.track('auth_completed', { flow: currentFlow, userId: user.id }); }} />

); } ``` ### Custom Layout ```tsx import { AuthFlowOrchestrator } from 'bigblocks'; const CustomAuthLayout = ({ children }) => (

{children}

); export default function CustomLayoutAuth() { return ( { console.log('Auth completed'); }} /> ); } ``` ### Debug Mode ```tsx import { AuthFlowOrchestrator } from 'bigblocks'; export default function DebugAuth() { return ( { console.log('Debug auth successful:', user); }} onError={(error) => { console.error('Debug auth error:', error); }} /> ); } ``` ## Common Patterns ### With Loading State ```tsx import { AuthFlowOrchestrator } from 'bigblocks'; import { useEffect, useState } from 'react'; export function SmartAuth() { const [hasExistingBackup, setHasExistingBackup] = useState(false); const [loading, setLoading] = useState(true); useEffect(() => { // Check for existing backup const backup = localStorage.getItem('encryptedBackup'); setHasExistingBackup(!!backup); setLoading(false); }, []); if (loading) { return

; } return ( { console.log('Auth successful'); }} /> ); } ``` ### In Modal ```tsx import { AuthFlowOrchestrator } from 'bigblocks'; import { Modal } from '@radix-ui/themes'; export function AuthModal({ isOpen, onClose }) { return ( { console.log('Modal auth successful'); onClose(); }} /> ); } ``` ### Profile Sync Enabled ```tsx import { AuthFlowOrchestrator } from 'bigblocks'; export function ProfileSyncAuth() { return ( { console.log('Auth with profile sync completed'); }} /> ); } ``` ## Flow Behavior ### Unified Flow (Default) * Detects if user has existing backup * Routes to appropriate flow automatically * Seamless transitions between states ### Sign In Flow 1. Password entry 2. Backup decryption 3. Identity verification 4. Success ### Sign Up Flow 1. Identity generation 2. Password creation 3. Backup creation 4. Download/save backup 5. Optional OAuth linking 6. Success ### OAuth Restore Flow 1. Select OAuth provider 2. Authenticate with provider 3. Retrieve encrypted backup 4. Decrypt with password 5. Success ### Device Link Flow 1. Generate device link code 2. Scan QR or enter code 3. Authorize on primary device 4. Sync backup to new device 5. Success ## Troubleshooting ### Flow Not Auto-Detecting * Check that `autoDetectFlow` is enabled * Verify local storage is accessible * Ensure BitcoinAuthProvider is properly configured ### OAuth Not Working * Verify OAuth providers are configured in your backend * Check that `enableOAuth` is true * Ensure callback URLs are properly set ### Custom Layout Issues * Layout component must accept `children` prop * Ensure proper CSS/styling is applied * Check that `layout` prop is set to `'custom'` ## Related Components * [LoginForm](/docs/components/login-form) - Standalone login form * [SignupFlow](/docs/components/signup-flow) - Signup flow component * [OAuthRestoreFlow](/docs/components/oauth-restore-flow) - OAuth restoration * [BackupImport](/docs/components/backup-import) - File import component * [DeviceLinkQR](/docs/components/device-link-qr) - Device linking QR ## API Reference ### Success Callback The `onSuccess` callback receives a user object: ```typescript { id: string; // User's BAP ID address: string; // Bitcoin address } ``` ### Error Handling Errors are passed as strings to the `onError` callback. Common error types: * `'USER_EXISTS'` - Account already exists * `'INVALID_PASSWORD'` - Incorrect password * `'INVALID_BACKUP'` - Corrupted backup file * `'OAUTH_FAILED'` - OAuth authentication failed * `'DEVICE_LINK_FAILED'` - Device linking failed ### Flow State The component manages internal state including: * Current flow type * Current step * Form data * Error states * Loading states ## Notes for Improvement **Implementation Note**: The prompt described props like `mode`, `allowModeSwitch`, `showOAuthProviders`, and `customSteps` which don't exist in the actual implementation. The actual component uses `flowType`, `enableOAuth`, and other boolean flags for configuration. The component is more feature-rich than the prompt suggested, with support for device linking, profile sync, and debug mode. # AuthLayout URL: /docs/components/authentication/auth-layout Full-page layout component for authentication screens with progress tracking *** title: AuthLayout description: Full-page layout component for authentication screens with progress tracking category: layouts ----------------- A full-page layout component designed specifically for authentication screens. It provides a consistent structure with optional header, progress indicator, and centered content area, making it perfect for login pages, signup flows, and password reset screens. ## Installation ```bash npx bigblocks add auth-layout ``` ## Import ```typescript import { AuthLayout } from 'bigblocks'; ``` ## Props | Prop | Type | Required | Default | Description | | ------------ | ----------- | -------- | ------- | ----------------------- | | children | `ReactNode` | Yes | - | Main content to display | | title | `string` | No | - | Optional page title | | subtitle | `string` | No | - | Optional page subtitle | | showProgress | `boolean` | No | `false` | Show progress indicator | | progressStep | `number` | No | `1` | Current step number | | totalSteps | `number` | No | `3` | Total number of steps | | className | `string` | No | - | Additional CSS classes | ## Basic Usage ```tsx import { AuthLayout, LoginForm } from 'bigblocks'; export default function LoginPage() { return ( console.log('Logged in:', user)} /> ); } ``` ## Advanced Usage ### Multi-Step Registration ```tsx import { AuthLayout } from 'bigblocks'; import { useState } from 'react'; export default function SignupPage() { const [currentStep, setCurrentStep] = useState(1); const totalSteps = 4; return ( {currentStep === 1 && setCurrentStep(2)} />} {currentStep === 2 && setCurrentStep(3)} />} {currentStep === 3 && setCurrentStep(4)} />} {currentStep === 4 && console.log('Done!')} />} ); } ``` ### With Custom Styling ```tsx import { AuthLayout } from 'bigblocks'; export default function StyledAuthPage() { return ( ); } ``` ### Password Reset Flow ```tsx import { AuthLayout } from 'bigblocks'; export default function PasswordResetPage() { return ( ); } ``` ## Common Patterns ### Dynamic Progress Tracking ```tsx import { AuthLayout } from 'bigblocks'; import { useState } from 'react'; export function OnboardingFlow() { const [step, setStep] = useState(1); const steps = [ { title: "Account Info", component: AccountInfo }, { title: "Security Setup", component: SecuritySetup }, { title: "Backup Creation", component: BackupCreation }, { title: "Verification", component: Verification } ]; const CurrentStepComponent = steps[step - 1].component; return ( setStep(step + 1)} onBack={() => setStep(step - 1)} /> ); } ``` ### With Error Handling ```tsx import { AuthLayout, ErrorDisplay } from 'bigblocks'; import { useState } from 'react'; export function AuthWithErrors() { const [error, setError] = useState(null); return ( {error && } setError(err.message)} onSuccess={(user) => { setError(null); console.log('Success!'); }} /> ); } ``` ### Conditional Content ```tsx import { AuthLayout } from 'bigblocks'; export function ConditionalAuthPage({ isNewUser }) { return ( {isNewUser ? : } ); } ``` ## Layout Structure The AuthLayout component creates a full-height page with the following structure: ``` ┌─────────────────────────────────┐ │ Header Section │ │ Title & Subtitle Text │ ├─────────────────────────────────┤ │ │ │ Progress Bar (if enabled) │ │ [===========------] 60% │ │ │ │ ┌─────────────────────────┐ │ │ │ │ │ │ │ Centered Content │ │ │ │ (440px max width) │ │ │ │ │ │ │ └─────────────────────────┘ │ │ │ └─────────────────────────────────┘ ``` ## Features ### Full Height Layout * Automatically fills viewport height * Ensures content is always centered * No scrolling for standard auth forms ### Progress Tracking * Visual progress bar for multi-step flows * Percentage display for accessibility * Smooth animations between steps ### Responsive Design * Adapts to all screen sizes * Maintains readability on mobile * Consistent padding and spacing ### Theme Integration * Follows active theme colors * Supports dark/light modes * Consistent with BigBlocks design system ## Styling AuthLayout uses Radix Themes design tokens: * **Background**: `var(--color-background)` * **Text Color**: `var(--gray-12)` for titles * **Spacing**: `var(--space-4)` padding * **Container**: 440px maximum width for content * **Progress Bar**: Theme accent color ## Best Practices 1. **Title Usage**: Keep titles concise and action-oriented (e.g., "Sign In", "Create Account") 2. **Progress Steps**: Use progress tracking for flows with 3 or more steps 3. **Content Width**: Content is limited to 440px for optimal readability 4. **Spacing**: The layout maintains consistent padding across all screen sizes 5. **Subtitle**: Use subtitles to provide helpful context or instructions ## Accessibility * Uses semantic HTML structure with proper heading hierarchy * Progress indicator includes percentage text for screen readers * Maintains focus management during step transitions * Fully keyboard navigable * Supports reduced motion preferences ## Troubleshooting ### Content Not Centering * Ensure parent container doesn't have conflicting styles * Check that the layout is at the root of your page component * Verify no global CSS is overriding flexbox properties ### Progress Bar Not Showing * Confirm `showProgress` prop is set to `true` * Verify `progressStep` and `totalSteps` are valid numbers * Check that `progressStep` is between 1 and `totalSteps` ### Layout Height Issues * AuthLayout uses `min-h-screen` - ensure no parent has `height` constraints * Check for conflicting global styles on `html` or `body` elements ## Related Components * [AuthCard](/docs/components/auth-card) - Card-based container for auth forms * [CenteredLayout](/docs/components/centered-layout) - Generic centered layout wrapper * [LoginForm](/docs/components/login-form) - Common child component for sign-in * [SignupFlow](/docs/components/signup-flow) - Multi-step registration component * [LoadingLayout](/docs/components/loading-layout) - Loading state layout * [ErrorLayout](/docs/components/error-layout) - Error state layout * [SuccessLayout](/docs/components/success-layout) - Success state layout ## API Reference ### Progress Calculation The progress bar percentage is calculated as: ```typescript percentage = (progressStep / totalSteps) * 100 ``` ### Layout Sizing * **Content Max Width**: 440px * **Vertical Spacing**: Flexible, centers content * **Horizontal Padding**: Responsive (16px mobile, 24px desktop) # AuthManager URL: /docs/components/authentication/auth-manager Core authentication manager class for Bitcoin-based authentication and session management *** title: AuthManager description: Core authentication manager class for Bitcoin-based authentication and session management categories: \[authentication, core, session-management] ------------------------------------------------------- import { ComponentBadges } from '@/components/docs/ComponentBadges'; import { AuthManagerDemo } from '@/components/docs/demos/AuthManagerDemo'; Core authentication manager class that handles Bitcoin-based authentication, session management, backup operations, and user state. It provides a comprehensive API for managing Bitcoin identity authentication with support for multiple backup formats and OAuth integration. ## Demo ## API Reference This component extends [BitcoinAuthConfig](/docs/components/bitcoin-auth-provider) for configuration and uses [StorageAdapter](/docs/components/storage-adapter) for persistent storage. ## Overview The `AuthManager` is the core engine behind BigBlocks authentication. It manages the complete authentication lifecycle, from account creation and sign-in to backup management and session handling. It supports multiple backup formats (BAP Master, BAP Member, OneSat) and provides OAuth integration for cloud backup storage. ## Key Features * **Multi-format Backup Support**: BAP Master, BAP Member, OneSat, WIF formats * **Encrypted Storage**: AES-256 encryption for local backup storage * **OAuth Integration**: Link Google, GitHub, and custom providers for cloud backups * **Session Management**: Secure session creation and management * **Event System**: Subscribe to authentication state changes * **Wallet Integration**: Check for and integrate with browser wallet extensions * **Type-safe API**: Full TypeScript support with comprehensive type definitions ## Configuration ```typescript interface BitcoinAuthConfig { apiUrl?: string; // API base URL (default: '/api') oauthProviders?: OAuthProvider[]; // OAuth providers to enable customOAuthProviders?: CustomOAuthProvider[]; // Custom OAuth configurations backupTypes?: BackupTypeConfig; // Allowed backup formats storage?: StorageAdapter; // Storage implementation storageNamespace?: string; // Storage key namespace theme?: ThemeConfig; // UI theme configuration redirects?: RedirectConfig; // OAuth redirect URLs onSuccess?: (user: AuthUser) => void; // Success callback onError?: (error: AuthError) => void; // Error callback } ``` ## Basic Usage ### Creating an AuthManager ```typescript import { AuthManager, createAuthManager } from 'bigblocks'; // Using factory function (recommended) const authManager = createAuthManager({ apiUrl: 'https://api.bigblocks.io', oauthProviders: ['google', 'github'], storage: customStorageAdapter, // Optional custom storage }); // Direct instantiation const authManager = new AuthManager({ apiUrl: '/api', backupTypes: { enabled: ['bap-master', 'bap-member'] } }); ``` ### Authentication Flow ```typescript // Sign up new user async function handleSignUp(password: string) { try { await authManager.signUp(password); console.log('Account created successfully'); } catch (error) { console.error('Sign up failed:', error); } } // Sign in existing user async function handleSignIn(password: string) { try { await authManager.signIn(password); console.log('Signed in successfully'); } catch (error) { console.error('Sign in failed:', error); } } // Sign out current user async function handleSignOut() { await authManager.signOut(); console.log('Signed out'); } ``` ## Core Methods ### Authentication Methods ```typescript class AuthManager { // Create new account with password async signUp(password: string): Promise<{ success: boolean; error?: AuthError }> // Sign in with existing backup async signIn(password: string): Promise<{ success: boolean; error?: AuthError }> // Sign out current user async signOut(): Promise // Validate password against stored backup async validatePassword(password: string): Promise } ``` ### Backup Management ```typescript class AuthManager { // Generate backup for current user generateBackup(): BapMasterBackup // Import backup from file async importBackup(file: File): Promise // Get current backup status getBackupStatus(): BackupStatus } ``` ### OAuth Integration ```typescript class AuthManager { // Link OAuth provider for cloud backup async linkOAuth(provider: OAuthProvider): Promise // Handle OAuth callback after authorization async handleOAuthCallback(provider: OAuthProvider, success: boolean): Promise // Get linked OAuth providers getLinkedProviders(): OAuthProvider[] } ``` ### State Management ```typescript class AuthManager { // Get current authentication state getState(): AuthState // Subscribe to state changes subscribe(listener: (event: AuthEvent) => void): () => void // Get action functions for UI integration getActions(): AuthActions } ``` ## State Management ### Authentication State ```typescript interface AuthState { user: AuthUser | null; // Current authenticated user isAuthenticated: boolean; // Authentication status isLoading: boolean; // Loading state error: AuthError | null; // Current error currentStep: AuthStep; // Current flow step mode: 'signin' | 'signup'; // Current mode hasLocalBackup: boolean; // Local backup exists backupStatus: BackupStatus; // Detailed backup status isImportedBackup: boolean; // Backup was imported hasWalletCapabilities: boolean; // Wallet extension available linkedProviders: OAuthProvider[]; // Linked OAuth providers pendingOAuthProvider: OAuthProvider | null; // Pending OAuth link } ``` ### Event System ```typescript type AuthEvent = | { type: 'AUTH_STARTED' } | { type: 'AUTH_SUCCESS'; user: AuthUser } | { type: 'AUTH_FAILED'; error: AuthError } | { type: 'OAUTH_STARTED'; provider: OAuthProvider } | { type: 'OAUTH_LINKED'; provider: OAuthProvider } | { type: 'BACKUP_IMPORTED'; backupType: string } | { type: 'BACKUP_EXPORTED' } | { type: 'SESSION_EXPIRED' }; ``` ## Advanced Usage ### State Subscription with React ```tsx import { createAuthManager } from 'bigblocks'; import { useEffect, useState } from 'react'; export function AuthStateManager() { const [authManager] = useState(() => createAuthManager({ apiUrl: '/api', onSuccess: (user) => console.log('Auth success:', user), onError: (error) => console.error('Auth error:', error) })); const [authState, setAuthState] = useState(authManager.getState()); useEffect(() => { const unsubscribe = authManager.subscribe((event) => { console.log('Auth event:', event); setAuthState(authManager.getState()); // Handle specific events switch (event.type) { case 'AUTH_SUCCESS': // Redirect to dashboard window.location.href = '/dashboard'; break; case 'AUTH_FAILED': // Show error message alert(event.error.message); break; case 'OAUTH_LINKED': // Show success message console.log(`${event.provider} linked successfully`); break; } }); return unsubscribe; }, [authManager]); return (

Authentication Status

Authenticated: {authState.isAuthenticated ? 'Yes' : 'No'}

User: {authState.user?.paymail || 'None'}

Current Step: {authState.currentStep}

Has Local Backup: {authState.hasLocalBackup ? 'Yes' : 'No'}

Linked Providers: {authState.linkedProviders.join(', ') || 'None'}

{authState.error && (

Error: {authState.error.message}

)}

); } ``` ### Backup Import with Validation ```tsx import { createAuthManager } from 'bigblocks'; export function BackupImporter() { const authManager = createAuthManager({ apiUrl: '/api' }); const [importing, setImporting] = useState(false); const handleFileSelect = async (event: React.ChangeEvent) => { const file = event.target.files?.[0]; if (!file) return; setImporting(true); try { await authManager.importBackup(file); console.log('Backup imported successfully'); // Check backup status const state = authManager.getState(); if (state.hasLocalBackup) { console.log('Local backup is now available'); } } catch (error) { console.error('Import failed:', error); if (error.code === 'INVALID_BACKUP_FORMAT') { alert('Invalid backup file format'); } else if (error.code === 'UNSUPPORTED_BACKUP_TYPE') { alert('This backup type is not supported'); } } finally { setImporting(false); } }; return (

{importing &&

Importing backup...

}

); } ``` ### OAuth Integration ```tsx import { createAuthManager } from 'bigblocks'; export function OAuthLinker() { const authManager = createAuthManager({ apiUrl: '/api', oauthProviders: ['google', 'github'], redirects: { success: '/dashboard', error: '/auth/error' } }); const handleLinkProvider = async (provider: 'google' | 'github') => { try { await authManager.linkOAuth(provider); // User will be redirected to OAuth provider } catch (error) { console.error('OAuth linking failed:', error); } }; const handleOAuthCallback = async (provider: 'google' | 'github', success: boolean) => { await authManager.handleOAuthCallback(provider, success); const state = authManager.getState(); if (state.linkedProviders.includes(provider)) { console.log(`${provider} linked successfully`); } }; return (

); } ``` ### Custom Storage Adapter ```typescript import { StorageAdapter } from 'bigblocks'; // Custom storage adapter for server-side rendering const serverStorageAdapter: StorageAdapter = { async get(key: string): Promise { // Implement server-side storage retrieval return await db.get(`auth:${key}`); }, async set(key: string, value: string): Promise { // Implement server-side storage await db.set(`auth:${key}`, value); }, async remove(key: string): Promise { // Implement server-side storage removal await db.delete(`auth:${key}`); } }; const authManager = createAuthManager({ apiUrl: '/api', storage: serverStorageAdapter }); ``` ## Error Handling The AuthManager provides detailed error information: ```typescript interface AuthError { code: 'BACKUP_NOT_FOUND' | 'INVALID_PASSWORD' | 'NETWORK_ERROR' | 'INVALID_BACKUP_FORMAT' | 'UNSUPPORTED_BACKUP_TYPE' | 'OAUTH_ERROR' | 'SESSION_EXPIRED' | 'UNKNOWN_ERROR'; message: string; details?: Record; } // Handle specific error types try { await authManager.signIn(password); } catch (error: AuthError) { switch (error.code) { case 'BACKUP_NOT_FOUND': // Show sign-up flow break; case 'INVALID_PASSWORD': // Show password reset option break; case 'NETWORK_ERROR': // Show retry option break; default: // Show generic error break; } } ``` ## Supported Backup Formats * **BAP Master**: Complete identity with private keys and attestations * **BAP Member**: Member-only backup with limited capabilities * **OneSat**: Simple backup format with basic identity * **WIF**: Wallet Import Format for single private key ## Security Features * **AES-256 Encryption**: All local backups are encrypted with user password * **Secure Session Management**: Sessions are managed securely with proper cleanup * **OAuth Security**: Secure OAuth flow with state verification * **Storage Security**: Sensitive data is never stored in plain text ## Installation ```bash npm install bigblocks ``` ## Related Components * [BitcoinAuthProvider](/docs/components/bitcoin-auth-provider) - Authentication context provider * [useBitcoinAuth](/docs/components/use-bitcoin-auth) - Authentication hook * [AuthButton](/docs/components/auth-button) - Authentication UI components * [BackupDownload](/docs/components/backup-download) - Backup management * [BackupImport](/docs/components/backup-import) - Backup import functionality # createAuthManager URL: /docs/components/authentication/create-auth-manager Factory function for creating pre-configured AuthManager instances *** title: createAuthManager description: Factory function for creating pre-configured AuthManager instances category: route-helpers ----------------------- A factory function that creates and configures AuthManager instances for Bitcoin authentication. Provides a comprehensive API for managing authentication state, sessions, and wallet operations. ## Installation ```bash npx bigblocks add create-auth-manager ``` ## Import ```typescript import { createAuthManager } from 'bigblocks'; ``` ## Basic Usage ```tsx import { createAuthManager } from 'bigblocks'; // Create auth manager instance const authManager = createAuthManager({ apiUrl: '/api' }); // Use in your application async function handleSignIn(password: string) { try { await authManager.signIn(password); console.log('Signed in successfully'); } catch (error) { console.error('Sign in failed:', error); } } ``` ## Configuration ```typescript interface BitcoinAuthConfig { apiUrl: string; // API endpoint URL debug?: boolean; // Enable debug logging backupTypes?: string[]; // Supported backup types } ``` ## API Methods The AuthManager instance provides these methods: ### Authentication ```typescript // Sign in with password await authManager.signIn(password: string); // Sign up with new account await authManager.signUp(password: string); // Sign out await authManager.signOut(); // Validate password const isValid = await authManager.validatePassword(password: string); ``` ### State Management ```typescript // Get current state const state = authManager.getState(); // Returns: { isAuthenticated, isLoading, user, error } // Subscribe to state changes const unsubscribe = authManager.subscribe((event) => { console.log('Auth event:', event.type, event.data); }); // Cleanup unsubscribe(); ``` ### Backup Operations ```typescript // Generate backup const backup = authManager.generateBackup(); // Import backup from file await authManager.importBackup(file: File); ``` ### OAuth Integration ```typescript // Link OAuth provider await authManager.linkOAuth('google'); // Handle OAuth callback await authManager.handleOAuthCallback('google', true); ``` ### Wallet Features ```typescript // Get wallet extension (if user has wallet capabilities) const walletExt = await authManager.getWalletExtension(); ``` ### Actions Helper ```typescript // Get all actions as a convenient object const actions = authManager.getActions(); // Includes: signIn, signUp, signOut, importBackup, linkOAuth, etc. ``` ## Advanced Usage ### With React Hook ```tsx import { createAuthManager } from 'bigblocks'; import { useState, useEffect, useCallback } from 'react'; function useAuthManager(config) { const [authManager] = useState(() => createAuthManager(config)); const [state, setState] = useState(authManager.getState()); useEffect(() => { const unsubscribe = authManager.subscribe((event) => { setState(authManager.getState()); }); return unsubscribe; }, [authManager]); const signIn = useCallback(async (password) => { await authManager.signIn(password); }, [authManager]); const signOut = useCallback(async () => { await authManager.signOut(); }, [authManager]); return { ...state, signIn, signOut, authManager }; } // Usage function LoginComponent() { const { isAuthenticated, user, signIn, signOut } = useAuthManager({ apiUrl: '/api' }); if (isAuthenticated) { return (

Welcome, {user.name}!

); } return ( ); } ``` ### With Error Handling ```tsx import { createAuthManager } from 'bigblocks'; const authManager = createAuthManager({ apiUrl: '/api', debug: true }); // Subscribe to all events authManager.subscribe((event) => { switch (event.type) { case 'AUTH_ERROR': console.error('Auth error:', event.data.error); showErrorNotification(event.data.error.message); break; case 'STATE_CHANGE': console.log('State changed:', event.data); break; case 'SESSION_CREATED': console.log('Session created for:', event.data.user.name); trackLogin(event.data.user); break; case 'SESSION_DESTROYED': console.log('Session destroyed'); trackLogout(); break; } }); ``` ### With Backup Management ```tsx import { createAuthManager } from 'bigblocks'; const authManager = createAuthManager({ apiUrl: '/api', backupTypes: ['BapMasterBackup', 'OneSatBackup', 'WifBackup'] }); // Export backup function exportBackup() { const backup = authManager.generateBackup(); const blob = new Blob([JSON.stringify(backup)], { type: 'application/json' }); const url = URL.createObjectURL(blob); const a = document.createElement('a'); a.href = url; a.download = 'bitcoin-wallet-backup.json'; a.click(); } // Import backup async function importBackup(file) { try { await authManager.importBackup(file); console.log('Backup imported successfully'); } catch (error) { console.error('Import failed:', error); } } ``` ### With OAuth Flow ```tsx import { createAuthManager } from 'bigblocks'; const authManager = createAuthManager({ apiUrl: '/api' }); // OAuth link button function OAuthLinkButton({ provider }) { const handleLink = async () => { try { await authManager.linkOAuth(provider); // This will redirect to OAuth provider } catch (error) { console.error('OAuth link failed:', error); } }; return ( ); } // OAuth callback handler async function handleOAuthReturn() { const params = new URLSearchParams(window.location.search); const provider = params.get('provider'); const success = params.get('success') === 'true'; if (provider) { await authManager.handleOAuthCallback(provider, success); } } ``` ## Event Types The AuthManager emits these events: ```typescript type AuthEvent = | { type: 'STATE_CHANGE'; data: AuthState } | { type: 'AUTH_ERROR'; data: { error: Error } } | { type: 'SESSION_CREATED'; data: { user: AuthUser } } | { type: 'SESSION_DESTROYED'; data: null } | { type: 'BACKUP_IMPORTED'; data: { type: string } } | { type: 'OAUTH_LINKED'; data: { provider: string } }; ``` ## State Structure ```typescript interface AuthState { isAuthenticated: boolean; isLoading: boolean; user: AuthUser | null; error: Error | null; } interface AuthUser { bapId: string; name?: string; address?: string; hasWalletCapabilities?: boolean; createdAt?: Date; // ... other user properties } ``` ## Common Patterns ### Protected Routes ```tsx function ProtectedRoute({ children }) { const authManager = createAuthManager({ apiUrl: '/api' }); const [state, setState] = useState(authManager.getState()); useEffect(() => { const unsubscribe = authManager.subscribe(() => { setState(authManager.getState()); }); return unsubscribe; }, []); if (!state.isAuthenticated) { return ; } return children; } ``` ### Session Persistence ```tsx function PersistentAuth() { const authManager = createAuthManager({ apiUrl: '/api' }); useEffect(() => { // Check for existing session on mount const checkSession = async () => { const encryptedBackup = localStorage.getItem('encryptedBackup'); if (encryptedBackup) { // Session exists, validate it const state = authManager.getState(); if (!state.isAuthenticated) { // Re-authenticate if needed console.log('Session expired, please sign in again'); } } }; checkSession(); }, []); } ``` ### Multi-Provider Support ```tsx function MultiProviderAuth() { const authManager = createAuthManager({ apiUrl: '/api', backupTypes: ['BapMasterBackup', 'OneSatBackup', 'WifBackup'] }); const handleImport = async (file) => { try { await authManager.importBackup(file); // Check which type was imported const state = authManager.getState(); console.log('Imported user:', state.user); } catch (error) { if (error.message.includes('password')) { // Prompt for password const password = prompt('Enter backup password:'); // Retry import with password } } }; } ``` ## Error Handling ```typescript authManager.subscribe((event) => { if (event.type === 'AUTH_ERROR') { const error = event.data.error; switch (error.code) { case 'INVALID_PASSWORD': showError('Invalid password'); break; case 'NETWORK_ERROR': showError('Network connection failed'); break; case 'SESSION_EXPIRED': showError('Session expired, please sign in again'); break; case 'BACKUP_CORRUPTED': showError('Backup file is corrupted'); break; default: showError('Authentication failed'); } } }); ``` ## Best Practices 1. **Single Instance**: Create one AuthManager instance per app 2. **Error Handling**: Always handle authentication errors 3. **State Subscription**: Subscribe to state changes for reactive UI 4. **Cleanup**: Unsubscribe from events when components unmount 5. **Security**: Never log sensitive data like passwords or private keys ## Troubleshooting ### State Not Updating ```typescript // Ensure you're subscribing to changes const unsubscribe = authManager.subscribe((event) => { // Update your UI state here updateUIState(authManager.getState()); }); // Don't forget to cleanup return () => unsubscribe(); ``` ### Import Failing ```typescript // Check supported backup types console.log('Supported types:', authManager.options?.backupTypes); // Validate file before import if (!file.type.match(/json|text/)) { throw new Error('Invalid file type'); } ``` ## Related Components * [BitcoinAuthProvider](/docs/components/bitcoin-auth-provider) - React provider wrapper * [createBigBlocksAuth](/docs/components/create-bigblocks-auth) - Lower-level auth core * [LoginForm](/docs/components/login-form) - Pre-built login UI * [SignupFlow](/docs/components/signup-flow) - Complete signup flow ## API Reference ### AuthManager Class The AuthManager provides a complete authentication system with: * Password-based authentication * Backup import/export * OAuth provider linking * Session management * Event-driven state updates * Wallet integration support All methods are async and return promises for easy integration with modern JavaScript applications. # createBigBlocksAuth URL: /docs/components/authentication/create-bigblocks-auth Framework-agnostic authentication core for Bitcoin-based authentication *** title: createBigBlocksAuth description: Framework-agnostic authentication core for Bitcoin-based authentication category: route-helpers ----------------------- A framework-agnostic authentication core that provides Bitcoin-based authentication primitives for any JavaScript framework. Creates a low-level auth instance with a universal handler pattern for maximum flexibility. ## Installation ```bash npx bigblocks add create-bigblocks-auth ``` ## Import ```typescript import { createBigBlocksAuth } from 'bigblocks'; ``` ## Basic Usage ```tsx import { createBigBlocksAuth } from 'bigblocks'; // Create authentication instance const auth = createBigBlocksAuth({ verifySignatures: true, timeWindow: 600000, // 10 minutes basePath: '/api/auth' }); // Use the universal handler const response = await auth.handler(request); ``` ## Configuration ```typescript interface BigBlocksAuthOptions { verifySignatures?: boolean; // Verify Bitcoin signatures (default: true) timeWindow?: number; // Signature validity window in ms (default: 600000) bodyEncoding?: 'hex' | 'base64' | 'utf8'; // Request body encoding (default: 'utf8') basePath?: string; // Base API path (default: '/api/auth') storage?: StorageAdapter; // Storage adapter storageNamespace?: string; // Storage key prefix backupTypes?: string[]; // Supported backup types } ``` ## Core API The auth instance provides: ### Universal Handler ```typescript // Handle any authentication request const response = await auth.handler(request); ``` ### API Methods ```typescript // Verify authentication const result = await auth.api.verifyAuth({ address: 'bitcoin-address', idKey: 'bap-id-key', authToken: 'signed-message', requestPath: '/api/protected', body: 'request-body' }); // Get session from headers const session = await auth.api.getSession(headers); // Generate backup const backup = auth.api.generateBackup(); // Encrypt backup const encrypted = await auth.api.encryptBackup(backup, password); // Decrypt backup const decrypted = await auth.api.decryptBackup(encrypted, password); ``` ## Framework Integrations ### Next.js App Router ```typescript // app/api/auth/[...auth]/route.ts import { createBigBlocksAuth } from 'bigblocks'; const auth = createBigBlocksAuth({ basePath: '/api/auth' }); export async function GET(request: Request) { return auth.handler(request); } export async function POST(request: Request) { return auth.handler(request); } ``` ### Express.js ```typescript import express from 'express'; import { createBigBlocksAuth } from 'bigblocks'; const app = express(); const auth = createBigBlocksAuth(); // Convert Express request to standard Request app.use('/api/auth/*', async (req, res) => { const url = `http://localhost${req.originalUrl}`; const request = new Request(url, { method: req.method, headers: req.headers, body: req.method !== 'GET' ? JSON.stringify(req.body) : undefined }); const response = await auth.handler(request); const body = await response.text(); res.status(response.status).send(body); }); ``` ### Fastify ```typescript import fastify from 'fastify'; import { createBigBlocksAuth } from 'bigblocks'; const app = fastify(); const auth = createBigBlocksAuth(); app.all('/api/auth/*', async (request, reply) => { const standardRequest = new Request(request.url, { method: request.method, headers: request.headers, body: request.body ? JSON.stringify(request.body) : undefined }); const response = await auth.handler(standardRequest); const body = await response.text(); reply.code(response.status).send(body); }); ``` ### Hono ```typescript import { Hono } from 'hono'; import { createBigBlocksAuth } from 'bigblocks'; const app = new Hono(); const auth = createBigBlocksAuth(); app.all('/api/auth/*', async (c) => { const response = await auth.handler(c.req.raw); return response; }); ``` ## Advanced Usage ### Custom Storage Adapter ```typescript import { createBigBlocksAuth } from 'bigblocks'; class RedisStorageAdapter { async get(key: string): Promise { return redis.get(key); } async set(key: string, value: string): Promise { await redis.set(key, value); } async delete(key: string): Promise { await redis.del(key); } } const auth = createBigBlocksAuth({ storage: new RedisStorageAdapter(), storageNamespace: 'bigblocks:auth:' }); ``` ### Custom Verification ```typescript const auth = createBigBlocksAuth({ verifySignatures: true, timeWindow: 300000, // 5 minutes for stricter security bodyEncoding: 'base64' // For binary data }); // Manual verification async function verifyRequest(req: Request) { const authHeader = req.headers.get('X-Auth-Token'); if (!authHeader) { return { success: false, error: 'Missing auth token' }; } const [address, idKey, signature] = authHeader.split(':'); return auth.api.verifyAuth({ address, idKey, authToken: signature, requestPath: new URL(req.url).pathname, body: await req.text() }); } ``` ### Session Management ```typescript const auth = createBigBlocksAuth(); // Middleware to attach session async function sessionMiddleware(req: Request): Promise { const session = await auth.api.getSession(req.headers); if (session) { // Attach session to request (req as any).session = session; } return req; } // Protected route handler async function protectedHandler(req: Request) { const session = (req as any).session; if (!session) { return new Response('Unauthorized', { status: 401 }); } return new Response(JSON.stringify({ message: 'Protected data', user: session.user })); } ``` ### Backup Operations ```typescript const auth = createBigBlocksAuth({ backupTypes: ['BapMasterBackup', 'OneSatBackup', 'WifBackup'] }); // Generate and encrypt backup async function exportBackup(password: string) { const backup = auth.api.generateBackup(); const encrypted = await auth.api.encryptBackup(backup, password); // Save to file const blob = new Blob([encrypted], { type: 'text/plain' }); const url = URL.createObjectURL(blob); const a = document.createElement('a'); a.href = url; a.download = 'wallet-backup.txt'; a.click(); } // Import and decrypt backup async function importBackup(file: File, password: string) { const encrypted = await file.text(); const backup = await auth.api.decryptBackup(encrypted, password); // Process backup console.log('Imported backup:', backup); return backup; } ``` ## Authentication Flow ### Client-Side ```typescript // Sign authentication request async function authenticatedFetch(url: string, options?: RequestInit) { const { address, idKey, privateKey } = getWalletInfo(); // Create message to sign const timestamp = Date.now(); const body = options?.body || ''; const message = `${url}:${body}:${timestamp}`; // Sign with Bitcoin private key const signature = await signMessage(message, privateKey); // Create auth token const authToken = `${address}:${idKey}:${signature}:${timestamp}`; return fetch(url, { ...options, headers: { ...options?.headers, 'X-Auth-Token': authToken } }); } ``` ### Server-Side Verification ```typescript const auth = createBigBlocksAuth(); async function handleProtectedRoute(request: Request) { // Auth handler automatically verifies the signature const authResponse = await auth.handler(request); if (!authResponse.ok) { return authResponse; // Return error response } // Get verified session const session = await auth.api.getSession(request.headers); // Process authenticated request return new Response(JSON.stringify({ message: 'Success', user: session?.user })); } ``` ## Route Patterns The universal handler supports these routes: * `POST /signin` - Sign in with Bitcoin signature * `POST /signout` - Sign out and clear session * `GET /session` - Get current session * `POST /verify` - Verify authentication token * `POST /backup/generate` - Generate wallet backup * `POST /backup/encrypt` - Encrypt backup * `POST /backup/decrypt` - Decrypt backup ## Error Handling ```typescript const auth = createBigBlocksAuth(); async function handleAuthError(request: Request) { try { const response = await auth.handler(request); return response; } catch (error) { console.error('Auth error:', error); if (error.message.includes('signature')) { return new Response('Invalid signature', { status: 401 }); } if (error.message.includes('expired')) { return new Response('Token expired', { status: 401 }); } return new Response('Authentication failed', { status: 500 }); } } ``` ## Best Practices 1. **Security**: Always use HTTPS in production 2. **Time Window**: Set appropriate signature expiry time 3. **Storage**: Use persistent storage for production 4. **Error Handling**: Provide clear error messages 5. **Logging**: Log authentication events for security ## Types ```typescript interface BigBlocksAuthPayload { address: string; // Bitcoin address idKey: string; // BAP identity key authToken: string; // Signed message requestPath: string; // API path body: string; // Request body timestamp?: string; // Optional timestamp } interface BigBlocksAuthResult { success: boolean; user?: AuthUser; error?: string; } interface BigBlocksSession { user: AuthUser; sessionId: string; expiresAt: Date; } ``` ## Troubleshooting ### Signature Verification Failed ```typescript // Check time synchronization const auth = createBigBlocksAuth({ timeWindow: 1200000 // 20 minutes for testing }); // Log verification details auth.api.verifyAuth(payload).catch(error => { console.error('Verification failed:', error); console.log('Payload:', payload); }); ``` ### Session Not Persisting ```typescript // Ensure storage is configured const auth = createBigBlocksAuth({ storage: new PersistentStorageAdapter(), storageNamespace: 'myapp:auth:' }); ``` ## Related Components * [createAuthManager](/docs/components/create-auth-manager) - Higher-level auth manager * [BitcoinAuthProvider](/docs/components/bitcoin-auth-provider) - React provider * [AuthButton](/docs/components/auth-button) - Pre-built auth UI * Framework adapters for Next.js, Express, Astro ## Notes for Improvement **Simplified Implementation**: The actual component is a universal handler pattern following the Better Auth approach. It's more focused on: * Universal request/response handling * Bitcoin signature verification * Session management via headers * Backup encryption/decryption utilities The prompt described a more complex client-side focused API, while the actual implementation is server-oriented with a clean handler pattern for easy framework integration. # IdentityGeneration URL: /docs/components/authentication/identity-generation Component for generating new Bitcoin identities or importing existing ones *** title: IdentityGeneration description: Component for generating new Bitcoin identities or importing existing ones category: backup-recovery ------------------------- import { IdentityGenerationDemo } from '@/components/docs/demos/IdentityGenerationDemo'; A streamlined component that provides options to generate a new Bitcoin identity or import an existing backup. It offers a simple interface with two primary actions, perfect for onboarding flows. ## Installation ```bash npx bigblocks add identity-generation ``` ## Import ```typescript import { IdentityGeneration } from 'bigblocks'; ``` ## Props | Prop | Type | Required | Default | Description | | ---------- | ---------------------- | -------- | ------- | --------------------------------------- | | onGenerate | `() => void` | Yes | - | Handler when generate button is clicked | | onImport | `(file: File) => void` | Yes | - | Handler when import file is selected | | loading | `boolean` | No | `false` | Show loading state | | error | `string` | No | - | Error message to display | | className | `string` | No | - | Additional CSS classes | ## Basic Usage ```tsx import { IdentityGeneration } from 'bigblocks'; import { useRouter } from 'next/navigation'; export default function OnboardingPage() { const router = useRouter(); const handleGenerate = () => { // Navigate to identity creation flow router.push('/create-identity'); }; const handleImport = (file: File) => { // Process the imported file console.log('Importing backup file:', file.name); // Navigate to import flow router.push('/import-backup'); }; return ( ); } ``` ## Advanced Usage ### With Loading State ```tsx import { IdentityGeneration } from 'bigblocks'; import { useState } from 'react'; export default function LoadingExample() { const [loading, setLoading] = useState(false); const handleGenerate = async () => { setLoading(true); try { // Simulate async operation await new Promise(resolve => setTimeout(resolve, 2000)); // Navigate or process } finally { setLoading(false); } }; return ( console.log(file)} loading={loading} /> ); } ``` ### With Error Handling ```tsx import { IdentityGeneration } from 'bigblocks'; import { useState } from 'react'; export default function ErrorHandlingExample() { const [error, setError] = useState(); const handleImport = (file: File) => { setError(undefined); // Validate file if (!file.name.match(/\.(txt|json|enc)$/)) { setError('Invalid file type. Please select a backup file.'); return; } if (file.size > 10 * 1024 * 1024) { setError('File too large. Maximum size is 10MB.'); return; } // Process file processBackupFile(file); }; return ( console.log('Generate clicked')} onImport={handleImport} error={error} /> ); } ``` ### Custom Styling ```tsx import { IdentityGeneration } from 'bigblocks'; export default function StyledExample() { return (

Get Started

console.log('Generate')} onImport={(file) => console.log('Import', file)} className="max-w-md mx-auto" />

); } ``` ## Common Patterns ### In Onboarding Flow ```tsx import { IdentityGeneration } from 'bigblocks'; import { useState } from 'react'; export function OnboardingFlow() { const [step, setStep] = useState<'choice' | 'generate' | 'import'>('choice'); return (

{step === 'choice' && (

Welcome to BigBlocks

setStep('generate')} onImport={(file) => { // Store file for processing sessionStorage.setItem('importFile', file.name); setStep('import'); }} />

)} {step === 'generate' && (

Generate New Identity

{/* Identity creation component */}

)} {step === 'import' && (

Import Backup

{/* Backup import component */}

)}

); } ``` ### With File Processing ```tsx import { IdentityGeneration } from 'bigblocks'; export function ProcessingExample() { const processFile = async (file: File) => { const content = await file.text(); // Detect format if (content.startsWith('U2FsdGVkX1')) { console.log('Processing encrypted backup'); // Handle encrypted backup } else if (content.startsWith('{')) { console.log('Processing JSON backup'); // Handle JSON backup } else { console.log('Processing WIF backup'); // Handle WIF format } }; return ( { console.log('Creating new identity'); }} onImport={processFile} /> ); } ``` ### With Navigation ```tsx import { IdentityGeneration } from 'bigblocks'; import { useRouter } from 'next/navigation'; export function NavigationExample() { const router = useRouter(); return ( { router.push('/auth/create-identity'); }} onImport={(file) => { // Store file reference const fileUrl = URL.createObjectURL(file); sessionStorage.setItem('importFileUrl', fileUrl); router.push('/auth/import-backup'); }} /> ); } ``` ### In Modal Dialog ```tsx import { IdentityGeneration } from 'bigblocks'; import { useState } from 'react'; export function ModalExample() { const [showModal, setShowModal] = useState(true); return ( <> {showModal && (

Get Started

{ setShowModal(false); // Start generation flow }} onImport={(file) => { setShowModal(false); // Start import flow }} />

)} ); } ``` ## File Handling The component uses a hidden file input that accepts common backup formats: ```tsx // Internal file input configuration { const file = e.target.files?.[0]; if (file) onImport(file); }} /> ``` ## Styling The component uses Radix Themes Button components and can be customized with the className prop: ```css /* Default button arrangement */ .identity-generation { display: flex; flex-direction: column; gap: 1rem; } /* Custom styling example */ .custom-identity-generation { max-width: 400px; margin: 0 auto; } ``` ## Best Practices 1. **Clear Actions**: The two buttons clearly indicate the available options 2. **Error Feedback**: Always provide error messages for invalid files 3. **Loading States**: Show loading state during async operations 4. **File Validation**: Validate file type and size before processing 5. **Navigation**: Handle navigation after user selection ## Accessibility * Both buttons are keyboard accessible * Clear visual feedback for hover and focus states * Error messages are announced to screen readers * File input is properly labeled ## Troubleshooting ### Import Not Working * Check that onImport handler is defined * Verify file types are accepted * Ensure file input isn't blocked by browser ### Generate Not Triggering * Verify onGenerate handler is provided * Check for JavaScript errors in console * Ensure component isn't disabled via loading state ### Styling Issues * Check className is applied correctly * Verify Radix Themes is properly configured * Inspect for CSS conflicts ## Related Components * [BackupImport](/docs/components/backup-import) - Detailed backup import * [MnemonicDisplay](/docs/components/mnemonic-display) - Display recovery phrases * [BackupDownload](/docs/components/backup-download) - Download backups * [SignupFlow](/docs/components/signup-flow) - Complete signup process ## API Reference This component provides a simple interface for choosing between generating a new Bitcoin identity or importing an existing backup. ### Handler Types ```typescript type GenerateHandler = () => void; type ImportHandler = (file: File) => void; ``` ### File Object The File object passed to onImport contains: ```typescript interface File { name: string; size: number; type: string; lastModified: number; text(): Promise; arrayBuffer(): Promise; } ``` ## Notes for Improvement **Simplified Implementation**: The actual component is much simpler than the prompt described. It lacks: * Built-in identity generation logic (just triggers a callback) * Multiple generation modes (mnemonic vs random) * Direct identity/backup object handling * showImport prop to hide import option * generateMode prop for different generation methods The actual implementation is a basic choice component with two buttons that delegate all logic to the parent component via callbacks. # LoginForm URL: /docs/components/authentication/login-form Complete Bitcoin wallet login form with multiple authentication modes *** title: LoginForm description: Complete Bitcoin wallet login form with multiple authentication modes category: authentication ------------------------ import { LoginFormDemo } from '@/components/docs/demos/LoginFormDemo' Complete authentication form supporting Bitcoin wallet sign-in, sign-up, and restoration flows. LoginForm combines multiple [Radix Themes components](https://www.radix-ui.com/themes/docs/components) with Bitcoin-specific authentication logic, providing a complete user experience for wallet-based authentication including keypair generation, backup management, and session handling. ## Installation ```bash npx bigblocks add login-form ``` ## Import ```tsx import { LoginForm } from 'bigblocks'; ``` ## API Reference This component uses [Radix Themes components](https://www.radix-ui.com/themes/docs/components) for UI elements. | Prop | Type | Default | Description | | -------------------- | ----------------------------------- | ---------- | ---------------------------------------- | | mode | `'signin' \| 'signup' \| 'restore'` | `'signin'` | Authentication flow mode | | onSuccess | `(user: AuthUser) => void` | - | Callback when authentication succeeds | | onError | `(error: AuthError) => void` | - | Callback when authentication fails | | enableProfileSync | `boolean` | `false` | Enable automatic profile synchronization | | maxDiscoveryAttempts | `number` | `3` | Max attempts for profile discovery | | className | `string` | - | Additional CSS classes | | style | `React.CSSProperties` | - | Inline styles | | cardProps | `object` | - | Props for card container styling | | buttonProps | `object` | - | Props for button styling | ## Basic Usage ```tsx import { LoginForm, BitcoinAuthProvider } from 'bigblocks'; export default function LoginPage() { return ( { console.log('Login successful:', user); router.push('/dashboard'); }} onError={(error) => { console.error('Login failed:', error); }} /> ); } ``` ## Authentication Modes LoginForm supports three distinct authentication flows: ```tsx // Sign-in mode - authenticate existing users router.push('/dashboard')} /> // Sign-up mode - create new Bitcoin identity router.push('/onboarding')} /> // Restore mode - recover from backup file router.push('/dashboard')} /> ``` ## Profile Synchronization Enable automatic profile discovery and synchronization: ```tsx { console.log('User profiles synced:', user.profiles); }} /> ``` ## Custom Styling Customize the form appearance using cardProps and buttonProps: ```tsx ``` ## Authentication Flow LoginForm automatically handles the complete authentication process: 1. **Sign-in**: Password entry → Backup decryption → Session creation 2. **Sign-up**: Password creation → Backup generation → Download → Account creation 3. **Restore**: File import → Password entry → Backup decryption → Session restoration For styling customization, see the [Radix Themes documentation](https://www.radix-ui.com/themes/docs/components). ## Related Components * [AuthButton](/docs/components/auth-button) - Simple authentication button * [BitcoinAuthProvider](/docs/components/bitcoin-auth-provider) - Authentication context provider * [BackupDownload](/docs/components/backup-download) - Backup file management # OAuthProviders URL: /docs/components/authentication/oauth-providers OAuth provider selection component for linking cloud backup storage *** title: OAuthProviders description: OAuth provider selection component for linking cloud backup storage category: wallet-integrations ----------------------------- import { OAuthProvidersDemo } from '@/components/docs/demos/OAuthProvidersDemo'; A component for displaying and managing OAuth provider connections for cloud backup storage. Supports multiple providers with official brand colors and flexible configuration. ## Installation ```bash npx bigblocks add oauth-providers ``` ## Import ```typescript import { OAuthProviders } from 'bigblocks'; ``` ## Props | Prop | Type | Required | Default | Description | | --------------- | -------------------------------- | -------- | ----------------- | ----------------------------- | | providers | `OAuthProvider[]` | No | Default providers | Custom provider configuration | | action | `'signin' \| 'signup' \| 'link'` | No | `'link'` | Action context | | callbackUrl | `string` | No | - | OAuth callback URL | | linkedProviders | `string[]` | No | `[]` | Already linked provider IDs | | onProviderClick | `(provider: string) => void` | No | - | Provider click handler | | disabled | `boolean` | No | `false` | Disable all providers | | loading | `boolean` | No | `false` | Loading state | | className | `string` | No | - | Additional CSS classes | | size | `'1' \| '2' \| '3'` | No | `'2'` | Button size | ## Types ```typescript interface OAuthProvider { id: string; name: string; icon: React.ReactNode; enabled?: boolean; } ``` ## Basic Usage ```tsx import { OAuthProviders } from 'bigblocks'; export default function BackupSettings() { const handleProviderClick = (provider: string) => { console.log('Selected provider:', provider); // Initiate OAuth flow window.location.href = `/api/auth/link?provider=${provider}`; }; return ( ); } ``` ## Advanced Usage ### With Custom Providers ```tsx import { OAuthProviders } from 'bigblocks'; const customProviders = [ { id: 'google', name: 'Google', icon: , enabled: true, }, { id: 'github', name: 'GitHub', icon: , enabled: true, }, { id: 'microsoft', name: 'Microsoft', icon: , enabled: false, // Disabled }, ]; export default function CustomProviders() { return ( { console.log('Clicked:', provider); }} /> ); } ``` ### With Linked Status ```tsx import { OAuthProviders } from 'bigblocks'; import { useConnectedAccounts } from '@/hooks/useConnectedAccounts'; export default function LinkedProviders() { const { data: accounts } = useConnectedAccounts(); const linkedProviders = accounts?.map(a => a.provider) || []; return ( { if (linkedProviders.includes(provider)) { // Already linked - maybe unlink? console.log('Already linked:', provider); } else { // Link new provider window.location.href = `/api/auth/link?provider=${provider}`; } }} /> ); } ``` ### Different Actions ```tsx import { OAuthProviders } from 'bigblocks'; export default function ActionExamples() { return (

{/* Sign in with OAuth */} { window.location.href = `/api/auth/signin?provider=${provider}`; }} /> {/* Sign up with OAuth */} { window.location.href = `/api/auth/signup?provider=${provider}`; }} /> {/* Link for backup */} { window.location.href = `/api/auth/link?provider=${provider}`; }} />

); } ``` ### With Loading State ```tsx import { OAuthProviders } from 'bigblocks'; import { useState } from 'react'; export default function LoadingExample() { const [isLoading, setIsLoading] = useState(false); const handleProviderClick = async (provider: string) => { setIsLoading(true); try { await linkProvider(provider); } finally { setIsLoading(false); } }; return ( ); } ``` ### Custom Sizing ```tsx import { OAuthProviders } from 'bigblocks'; export default function SizingExample() { return (

); } ``` ## Brand Colors The component exports official brand colors for OAuth providers: ```tsx import { OAUTH_BRAND_COLORS } from 'bigblocks'; // Access brand colors const googleBlue = OAUTH_BRAND_COLORS.google.blue; // #4285F4 const githubDark = OAUTH_BRAND_COLORS.github; // #24292e const twitterBlue = OAUTH_BRAND_COLORS.twitter; // #1DA1F2 const handcashGreen = OAUTH_BRAND_COLORS.handcash; // #38CB7C const discordPurple = OAUTH_BRAND_COLORS.discord; // #5865F2 const facebookBlue = OAUTH_BRAND_COLORS.facebook; // #1877F2 const microsoftBlue = OAUTH_BRAND_COLORS.microsoft; // #00BCF2 ``` ## Common Patterns ### In Settings Page ```tsx import { OAuthProviders } from 'bigblocks'; export function SecuritySettings() { const { data: user } = useAuth(); const linkedProviders = user?.connectedAccounts || []; return (

Cloud Backup Providers

Link providers to backup your wallet

{ if (linkedProviders.includes(provider)) { if (confirm(`Unlink ${provider}?`)) { unlinkProvider(provider); } } else { linkProvider(provider); } }} />

{linkedProviders.length === 0 && (

No providers linked yet

)} {linkedProviders.length > 0 && (

Linked: {linkedProviders.join(', ')}

)}

); } ``` ### In Signup Flow ```tsx import { OAuthProviders } from 'bigblocks'; export function SignupStep() { const [step, setStep] = useState('create'); return (

{step === 'create' && (

Create Your Account

setStep('backup')} />

)} {step === 'backup' && (

Backup Your Wallet

Link a cloud provider for automatic backups

{ // Store provider choice sessionStorage.setItem('backupProvider', provider); // Redirect to OAuth window.location.href = `/api/auth/link?provider=${provider}`; }} />

)}

); } ``` ### With Custom Styling ```tsx import { OAuthProviders } from 'bigblocks'; export function StyledProviders() { return (

{ console.log('Selected:', provider); }} />

); } ``` ## Provider Setup Each provider requires OAuth app configuration: ### Google 1. Visit [Google Cloud Console](https://console.cloud.google.com) 2. Create OAuth 2.0 credentials 3. Add redirect URI: `https://yourdomain.com/api/auth/callback/google` 4. Enable Google Drive API for backup storage ### GitHub 1. Visit [GitHub Developer Settings](https://github.com/settings/developers) 2. Create OAuth App 3. Add redirect URI: `https://yourdomain.com/api/auth/callback/github` 4. Request `gist` scope for backup storage ### Twitter 1. Visit [Twitter Developer Portal](https://developer.twitter.com) 2. Create OAuth 2.0 app 3. Add redirect URI: `https://yourdomain.com/api/auth/callback/twitter` ### HandCash 1. Visit [HandCash Developer Portal](https://developer.handcash.io) 2. Create app 3. Add redirect URI: `https://yourdomain.com/api/auth/callback/handcash` ## Styling The component uses Radix Themes buttons and can be customized: ```css /* Custom provider button styles */ .oauth-providers { display: flex; gap: 1rem; flex-wrap: wrap; } .oauth-provider-button { min-width: 120px; } .oauth-provider-button[data-linked="true"] { opacity: 0.7; position: relative; } .oauth-provider-button[data-linked="true"]::after { content: "✓"; position: absolute; top: 0; right: 0; background: green; color: white; border-radius: 50%; width: 20px; height: 20px; display: flex; align-items: center; justify-content: center; } ``` ## Best Practices 1. **Clear Action Context**: Use appropriate `action` prop for context 2. **Loading States**: Show loading feedback during OAuth flows 3. **Error Handling**: Handle OAuth failures gracefully 4. **Security**: Always validate OAuth responses server-side 5. **Accessibility**: Ensure keyboard navigation works ## Troubleshooting ### Providers Not Showing * Check that providers array is properly configured * Ensure `enabled` is true for each provider * Verify component is wrapped in theme provider ### Click Handler Not Working * Ensure `onProviderClick` is properly defined * Check for event propagation issues * Verify buttons aren't disabled ### OAuth Flow Issues * Verify redirect URIs match exactly * Check OAuth app permissions/scopes * Ensure callback handlers are implemented ## Related Components * [SignupFlow](/docs/components/signup-flow) - Uses during registration * [LoginForm](/docs/components/login-form) - OAuth sign-in option * [CloudBackupManager](/docs/components/cloud-backup-manager) - Manages backups * [OAuthRestoreFlow](/docs/components/oauth-restore-flow) - Restore from OAuth ## API Reference ### Default Providers The component includes these providers by default: * Google (id: 'google') * GitHub (id: 'github') * Twitter (id: 'twitter') * HandCash (id: 'handcash') Each can be customized or filtered using the `providers` prop. ## Notes for Improvement **Enhanced Implementation**: The actual component is more sophisticated than the prompt suggested: * Supports custom provider configurations * Includes brand color constants * Has size variants for different contexts * More flexible action contexts (signin/signup/link) * Better TypeScript support with proper interfaces # SignOutButton URL: /docs/components/authentication/sign-out-button Secure sign-out button with confirmation dialog and session cleanup *** title: SignOutButton description: Secure sign-out button with confirmation dialog and session cleanup category: authentication ------------------------ A secure sign-out button component that handles session cleanup while preserving encrypted backups. It features optional confirmation dialogs, loading states, and customizable appearance to fit various UI contexts. ## Installation ```bash npx bigblocks add sign-out-button ``` ## Import ```typescript import { SignOutButton } from 'bigblocks'; ``` ## Props | Prop | Type | Required | Default | Description | | -------------- | -------------------------------------------------- | -------- | -------------------------------------- | ------------------------------ | | redirectTo | `string` | No | `'/'` | URL to redirect after sign out | | confirmSignOut | `boolean` | No | `false` | Show confirmation dialog | | confirmMessage | `string` | No | `'Are you sure you want to sign out?'` | Custom confirmation message | | variant | `'solid' \| 'soft' \| 'outline' \| 'ghost'` | No | `'soft'` | Button style variant | | color | `'gray' \| 'red' \| 'orange' \| 'blue' \| 'green'` | No | `'gray'` | Button color | | size | `'1' \| '2' \| '3' \| '4'` | No | `'3'` | Button size (Radix scale) | | showIcon | `boolean` | No | `true` | Show exit icon | | children | `React.ReactNode` | No | `'Sign Out'` | Custom button text | | className | `string` | No | - | Additional CSS classes | | onSignOut | `() => void` | No | - | Callback after sign out | | showClearInfo | `boolean` | No | `false` | Show what will be cleared | ## Basic Usage ```tsx import { SignOutButton } from 'bigblocks'; export default function Header() { return ( ); } ``` ## Advanced Usage ### With Confirmation Dialog ```tsx import { SignOutButton } from 'bigblocks'; export default function SecuritySettings() { return ( ); } ``` ### Custom Sign Out Handler ```tsx import { SignOutButton } from 'bigblocks'; export default function ProfileMenu() { const handleSignOut = async () => { // Clean up app-specific data await clearLocalCache(); // Track analytics analytics.track('user_signed_out', { location: 'profile_menu', timestamp: Date.now() }); // Show toast notification toast.success('Signed out successfully'); }; return ( ); } ``` ### With Clear Info Display ```tsx import { SignOutButton } from 'bigblocks'; export default function DetailedSignOut() { return ( ); } ``` ### In Dropdown Menu ```tsx import { SignOutButton } from 'bigblocks'; import { DropdownMenu } from '@radix-ui/themes'; export function UserMenu() { return ( Profile Settings ); } ``` ## Common Patterns ### Header Integration ```tsx import { SignOutButton } from 'bigblocks'; import { useAuth } from '@/hooks/useAuth'; export function AppHeader() { const { isAuthenticated } = useAuth(); return (

My App

{isAuthenticated && ( )}

); } ``` ### Mobile Responsive ```tsx import { SignOutButton } from 'bigblocks'; export function ResponsiveSignOut() { return ( Sign Out ); } ``` ### Settings Page ```tsx import { SignOutButton } from 'bigblocks'; export function AccountSettings() { return (

Account

Sign Out

Sign out of your account. Your encrypted backup will be preserved.

); } ``` ## Data Management ### What Gets Cleared When signing out, the following data is cleared: 1. **Session Storage** * Decrypted backup data * Temporary authentication tokens * Active session information 2. **Authentication State** * User context * Authentication status * Active profile 3. **Server Session** * NextAuth session cookies * Server-side session data 4. **Cache** * React Query cache * API response cache ### What Gets Preserved The following data remains after sign out: 1. **Encrypted Backup** * Stored in localStorage * Password-protected * Ready for next sign in 2. **OAuth Links** * Connected provider information * OAuth backup references 3. **User Preferences** * Theme settings * UI preferences * Language settings ## Confirmation Dialog When `confirmSignOut` is enabled, the component shows a modal with: * Custom confirmation message * Clear information (if enabled) * Cancel button * Confirm button Example dialog content: ``` Are you sure you want to sign out? This will clear: • Current session • Temporary data Your encrypted backup will remain safe. [Cancel] [Sign Out] ``` ## Styling The button uses Radix Themes styling system: ```tsx // Different variants // Filled background // Subtle background // Border only // Minimal styling // Different colors // Default // Danger/warning // Caution // Info // Success // Different sizes // Extra small // Small // Medium (default) // Large ``` ## Best Practices 1. **Confirmation for Important Flows**: Enable confirmation when signing out would interrupt important work 2. **Color Coding**: Use red color for emphasis in security contexts 3. **Placement**: Common locations include headers, profile menus, and settings pages 4. **Clear Information**: Show what will be cleared in sensitive applications 5. **Loading States**: The button shows a spinner during the sign-out process ## Accessibility * **Auto-hide**: Only renders when user is authenticated * **Keyboard Navigation**: Fully keyboard accessible * **Screen Readers**: Proper ARIA labels and announcements * **Focus Management**: Proper focus handling in confirmation dialog ## Security Considerations 1. **Client-Side Cleanup**: Ensures all sensitive session data is cleared 2. **Server Coordination**: Properly invalidates server sessions 3. **Backup Protection**: Never touches encrypted backup data 4. **No Data Loss**: Preserves all persistent user data ## Troubleshooting ### Button Not Showing * Verify user is authenticated * Check that component is inside `BitcoinAuthProvider` * Ensure proper React Query setup ### Sign Out Not Working * Check console for errors * Verify API endpoints are accessible * Ensure proper session configuration ### Redirect Not Working * For Next.js apps, ensure router is properly configured * Check that redirect URL is valid * Verify no middleware is blocking navigation ## Related Components * [LoginForm](/docs/components/login-form) - Sign in form * [AuthButton](/docs/components/auth-button) - Generic auth button * [ProfileDropdownMenu](/docs/components/profile-dropdown-menu) - Profile menu with sign out * [AuthFlowOrchestrator](/docs/components/auth-flow-orchestrator) - Complete auth flows ## API Reference ### Internal Behavior The component internally: 1. Checks authentication status 2. Clears session storage 3. Calls sign out API 4. Clears authentication context 5. Redirects (if specified) 6. Calls onSignOut callback ### Session Cleanup The sign-out process: ```typescript 1. Clear sessionStorage 2. Clear authentication state 3. Invalidate server session 4. Clear React Query cache 5. Preserve encrypted backup 6. Redirect to specified URL ``` # SignupFlow URL: /docs/components/authentication/signup-flow Multi-step signup process for creating new Bitcoin wallets *** title: SignupFlow description: Multi-step signup process for creating new Bitcoin wallets category: authentication ------------------------ A comprehensive multi-step signup component for creating new Bitcoin wallets with built-in identity generation, password setup, and backup management. It provides a complete onboarding experience with proper error handling and state management. ## Installation ```bash npx bigblocks add signup-flow ``` ## Import ```typescript import { SignupFlow } from 'bigblocks'; ``` ## Props | Prop | Type | Required | Default | Description | | --------- | ---------------------------- | -------- | ------- | ----------------------------- | | onSuccess | `(user: AuthUser) => void` | No | - | Callback when signup succeeds | | onError | `(error: AuthError) => void` | No | - | Callback for error handling | | className | `string` | No | - | Additional CSS classes | ## Basic Usage ```tsx import { SignupFlow, BitcoinAuthProvider } from 'bigblocks'; import { useRouter } from 'next/navigation'; export default function SignupPage() { const router = useRouter(); const handleSuccess = (user) => { console.log('Signup successful:', user); router.push('/dashboard'); }; const handleError = (error) => { console.error('Signup failed:', error); }; return ( ); } ``` ## Advanced Usage ### With Custom Error Handling ```tsx import { SignupFlow } from 'bigblocks'; import { toast } from 'sonner'; export default function SignupWithErrorHandling() { return ( { toast.success('Account created successfully!'); router.push('/onboarding'); }} onError={(error) => { // Handle specific error types switch (error.code) { case 'USER_EXISTS': toast.error('An account already exists. Please sign in.'); router.push('/signin'); break; case 'NETWORK_ERROR': toast.error('Network error. Please check your connection.'); break; case 'INVALID_PASSWORD': toast.error('Password does not meet requirements.'); break; default: toast.error(error.message || 'Signup failed. Please try again.'); } }} /> ); } ``` ### With Analytics Tracking ```tsx import { SignupFlow } from 'bigblocks'; import { analytics } from '@/lib/analytics'; export default function TrackedSignup() { const startTime = Date.now(); return ( { const duration = Date.now() - startTime; analytics.track('signup_completed', { userId: user.id, duration: duration, profileCount: user.profiles.length, hasMultipleProfiles: user.profiles.length > 1 }); // Set user for future analytics analytics.identify(user.id, { address: user.address, createdAt: new Date().toISOString() }); router.push('/welcome'); }} onError={(error) => { analytics.track('signup_failed', { error: error.code, duration: Date.now() - startTime }); }} /> ); } ``` ### With Custom Styling ```tsx import { SignupFlow } from 'bigblocks'; export default function StyledSignup() { return (

{ router.push('/dashboard'); }} />

); } ``` ### In Modal ```tsx import { SignupFlow } from 'bigblocks'; import { Modal } from '@radix-ui/themes'; export function SignupModal({ isOpen, onClose }) { return ( Create Your Bitcoin Wallet { console.log('Signup completed:', user); onClose(); router.push('/dashboard'); }} onError={(error) => { if (error.code !== 'USER_CANCELLED') { toast.error('Signup failed'); } }} /> ); } ``` ## Signup Flow Steps The SignupFlow component guides users through these steps: ### 1. Welcome Step * Introduction to Bitcoin wallet creation * Terms of service acceptance (if configured) * Clear value proposition ### 2. Identity Generation * Automatic Bitcoin keypair generation * Visual feedback during generation * Secure client-side process ### 3. Password Setup * Password creation for encryption * Password strength indicator * Confirmation field * Requirements display ### 4. Backup Creation * Encrypted backup generation * Download prompt * Security instructions * Verification checkbox ### 5. Success Confirmation * Account creation confirmation * Next steps guidance * Navigation to dashboard ## Common Patterns ### Full Page Signup ```tsx import { SignupFlow } from 'bigblocks'; export function SignupPage() { return (

Create Account

{ router.push('/onboarding'); }} />

); } ``` ### With Navigation Options ```tsx import { SignupFlow } from 'bigblocks'; import Link from 'next/link'; export function SignupWithNav() { return (

{ router.push('/dashboard'); }} />

Already have an account?{' '} Sign in

); } ``` ### With Loading Overlay ```tsx import { SignupFlow } from 'bigblocks'; import { useState } from 'react'; export function SignupWithLoading() { const [isProcessing, setIsProcessing] = useState(false); return ( <> {isProcessing && (

Setting up your account...

)} { setIsProcessing(true); try { // Additional setup await setupUserProfile(user); await createDefaultSettings(user.id); router.push('/welcome'); } finally { setIsProcessing(false); } }} /> ); } ``` ## Security Features 1. **Client-Side Key Generation**: All cryptographic operations happen in the browser 2. **Password Encryption**: Private keys are encrypted before any storage 3. **No Password Transmission**: Passwords never leave the client 4. **Secure Backup Format**: Industry-standard encryption for backups 5. **Session Management**: Secure session creation after signup ## Error Types ```typescript interface AuthError { code: | 'USER_EXISTS' // Account already exists | 'NETWORK_ERROR' // Network connectivity issues | 'INVALID_PASSWORD' // Password requirements not met | 'GENERATION_FAILED' // Key generation failed | 'BACKUP_FAILED' // Backup creation failed | 'SESSION_FAILED' // Session creation failed | 'USER_CANCELLED'; // User cancelled the flow message: string; } ``` ## Styling The SignupFlow uses Radix Themes and respects the BitcoinThemeProvider: ```css /* Component structure */ .signup-flow-container { /* Inherits theme styles */ } .signup-step { /* Individual step styling */ } .signup-navigation { /* Step navigation buttons */ } ``` ## State Management The component internally manages: * Current step tracking * Form data across steps * Loading states * Error states * Validation state * Backup generation status ## Best Practices 1. **Error Handling**: Always implement onError to handle failures gracefully 2. **Success Routing**: Navigate users appropriately after signup 3. **Loading States**: Show feedback during async operations 4. **Backup Emphasis**: Ensure users understand backup importance 5. **Mobile Optimization**: Test on mobile devices for touch interactions ## Troubleshooting ### Component Not Rendering * Ensure wrapped in `BitcoinAuthProvider` * Check that React Query is properly configured * Verify API endpoints are accessible ### Key Generation Failing * Check browser crypto API support * Ensure sufficient entropy available * Verify no browser extensions blocking crypto ### Backup Download Issues * Check browser download permissions * Ensure popup blockers aren't interfering * Verify file download API compatibility ## Related Components * [LoginForm](/docs/components/login-form) - Sign in existing users * [AuthFlowOrchestrator](/docs/components/auth-flow-orchestrator) - Unified auth flows * [BackupDownload](/docs/components/backup-download) - Backup management * [IdentityGeneration](/docs/components/identity-generation) - Key generation * [OAuthProviders](/docs/components/oauth-providers) - OAuth integration ## API Reference ### AuthUser Type ```typescript interface AuthUser { id: string; // User's BAP ID address: string; // Bitcoin address idKey: string; // Identity key profiles: ProfileInfo[]; // User profiles activeProfileId: string; // Current profile } ``` ### Internal Flow 1. Generate Bitcoin keypair 2. Create password 3. Encrypt private key 4. Generate backup file 5. Store encrypted backup 6. Create server session 7. Return authenticated user ## Notes for Improvement **Implementation Differences**: The actual component is simpler than the prompt described: * No `onCancel` callback * No `showBackupStep` or `showOAuthStep` props to control flow * No configurable steps * OAuth linking is not part of the current implementation * The flow is more streamlined with fewer customization options # BackupDownload URL: /docs/components/backup/backup-download Component for downloading encrypted wallet backups with security features *** title: BackupDownload description: Component for downloading encrypted wallet backups with security features categories: \['backup-recovery', 'security', 'wallet'] providers: \['BitcoinAuthProvider'] ----------------------------------- import { BackupDownloadDemo } from '@/components/docs/demos/BackupDownloadDemo' import { ComponentBadges } from '@/components/docs/ComponentBadges' BackupDownload combines the [Radix Button primitive](https://www.radix-ui.com/themes/docs/components/button) with Bitcoin backup generation, providing secure encrypted wallet backup downloads with user guidance and safety instructions. ## Installation ```bash npx bigblocks add backup-download ``` ## Import ```typescript import { BackupDownload } from 'bigblocks'; ``` This component extends the [Button primitive](https://www.radix-ui.com/themes/docs/components/button) and inherits all its props. ## Props | Prop | Type | Required | Default | Description | | --------------- | ----------------- | -------- | ------- | -------------------------------------------------- | | backup | `BapMasterBackup` | Yes | - | The backup data to download | | password | `string` | No | - | Password for encryption (if not already encrypted) | | onDownloaded | `() => void` | No | - | Callback when download is complete | | requireDownload | `boolean` | No | `false` | Whether download is required before proceeding | | className | `string` | No | - | Additional CSS classes | ## Basic Usage ```tsx import { BackupDownload } from 'bigblocks'; export default function BackupExample() { const backup = { // BapMasterBackup data idKey: 'L1...', derivationScheme: 'master', profiles: [], bitcoin: {} }; return ( { console.log('Backup downloaded successfully'); }} /> ); } ``` ## Advanced Usage ### Required Download ```tsx import { BackupDownload } from 'bigblocks'; import { useState } from 'react'; export default function RequiredBackupFlow() { const [downloadComplete, setDownloadComplete] = useState(false); const backup = generateBackup(); // Your backup generation logic return (

Step 2: Download Your Backup

You must download your backup before continuing.

{ setDownloadComplete(true); }} />

); } ``` ### With Custom Styling ```tsx import { BackupDownload } from 'bigblocks'; export default function StyledBackupDownload() { const backup = getUserBackup(); return ( { toast.success('Backup saved successfully!'); }} /> ); } ``` ### In Registration Flow ```tsx import { BackupDownload } from 'bigblocks'; import { useAuth } from '@/hooks/useAuth'; export default function RegistrationBackupStep() { const { backup, password } = useAuth(); const [downloaded, setDownloaded] = useState(false); return (

Save Your Backup

This backup file is the only way to recover your account. Download and store it safely.

{ setDownloaded(true); analytics.track('backup_downloaded'); }} /> {downloaded && (

✓ Backup downloaded successfully

)}

); } ``` ## Common Patterns ### Backup Settings Page ```tsx import { BackupDownload } from 'bigblocks'; import { useWallet } from '@/hooks/useWallet'; export function BackupSettings() { const { backup } = useWallet(); const [password, setPassword] = useState(''); const [showBackup, setShowBackup] = useState(false); const handlePasswordSubmit = (e) => { e.preventDefault(); // Validate password setShowBackup(true); }; return (

Download Backup

{!showBackup ? ( ) : ( { console.log('New backup downloaded'); setShowBackup(false); setPassword(''); }} /> )}

); } ``` ### With Progress Tracking ```tsx import { BackupDownload } from 'bigblocks'; export function BackupWithProgress() { const [step, setStep] = useState(1); const backup = generateBackup(); return (

{step === 1 && (

Create Password

setStep(2)} />

)} {step === 2 && (

Download Backup

setStep(3)} />

)} {step === 3 && (

Backup Complete!

Your wallet is now safely backed up.

)}

); } ``` ### Error Handling ```tsx import { BackupDownload } from 'bigblocks'; export function BackupWithErrorHandling() { const backup = getUserBackup(); const [error, setError] = useState(null); if (!backup) { return

No backup available

; } return (

{error && (

{error}

)} { try { // Additional validation or tracking validateBackupDownload(); console.log('Backup downloaded successfully'); } catch (err) { setError('Failed to validate backup download'); } }} />

); } ``` ## File Format The downloaded backup file is encrypted and contains: ```typescript // Encrypted backup format (after decryption) interface BapMasterBackup { idKey: string; // Master private key derivationScheme: string; // Key derivation scheme profiles: ProfileInfo[]; // User profiles bitcoin: { // Bitcoin-specific data mnemonic?: string; // Optional seed phrase network?: string; // Bitcoin network }; } ``` The file is saved with a timestamp-based filename: * Format: `bitcoin-backup-{timestamp}.txt` * Content: Base64 encoded encrypted data ## Security Considerations 1. **Encryption**: Backups are encrypted using AES-256-GCM 2. **Password**: Never stored, only used for encryption 3. **Client-side**: All encryption happens in the browser 4. **No Network**: Download doesn't require network requests 5. **User Responsibility**: Users must safely store their backups ## Styling The component uses Radix Themes and can be styled with: ```css /* Custom styling example */ .backup-download-container { background: var(--orange-2); border: 1px solid var(--orange-6); border-radius: var(--radius-3); padding: var(--space-4); } ``` ## Best Practices 1. **Password Strength**: Encourage strong passwords for encryption 2. **Multiple Copies**: Advise users to make multiple backup copies 3. **Offline Storage**: Recommend offline storage (USB, paper) 4. **Test Recovery**: Suggest testing backup restoration 5. **Regular Updates**: Remind users to update backups after profile changes ## Troubleshooting ### Download Not Working * Check that backup data is valid BapMasterBackup format * Ensure browser allows file downloads * Verify password is provided if encryption is needed ### File Not Encrypted * Confirm password prop is provided * Check that backup isn't already encrypted * Verify encryption library is loaded ### Callback Not Firing * Ensure onDownloaded prop is a valid function * Check browser console for errors * Verify download completes successfully ## Related Components * [BackupImport](/docs/components/backup-import) - Import backup files * [FileImport](/docs/components/file-import) - General file import * [MemberExport](/docs/components/member-export) - Export member backups * [QRCodeRenderer](/docs/components/qr-code-renderer) - QR code backups ## API Reference ### BapMasterBackup Type The backup data structure expected by the component: ```typescript interface BapMasterBackup { idKey: string; derivationScheme: string; profiles: Array<{ idKey: string; name?: string; // ... other profile data }>; bitcoin: { mnemonic?: string; network?: string; }; } ``` ### File Generation The component handles: 1. Encryption of backup data (if password provided) 2. Base64 encoding 3. File blob creation 4. Download trigger 5. Cleanup ## Notes for Improvement **Major Discrepancy**: The prompt describes a much more feature-rich component than what's actually implemented. The actual component is simpler with: * No variant prop (button vs card) * No size options * No preview functionality * No progress tracking * No error callback * No custom filename support * No instruction display options * No backend integration The actual implementation focuses solely on downloading an encrypted backup file with minimal UI. # BackupImport URL: /docs/components/backup/backup-import Component for importing Bitcoin wallet backups from various formats *** title: BackupImport description: Component for importing Bitcoin wallet backups from various formats categories: \['backup-recovery', 'onboarding', 'security'] providers: \[] -------------- import { BackupImportDemo } from '@/components/docs/demos/BackupImportDemo' import { ComponentBadges } from '@/components/docs/ComponentBadges' BackupImport combines native HTML file input with Bitcoin backup processing, providing a streamlined interface for importing encrypted wallet backups with validation, profile synchronization, and secure file handling. ## Installation ```bash npx bigblocks add backup-import ``` ## Import ```typescript import { BackupImport } from 'bigblocks'; ``` This component extends native HTML file input functionality with Bitcoin-specific backup processing. ## Props | Prop | Type | Required | Default | Description | | -------------------- | --------------------------------------- | -------- | ------- | ---------------------------------- | | onImport | `(file: File) => Promise \| void` | Yes | - | Handler for file import | | disabled | `boolean` | No | `false` | Disable the import button | | className | `string` | No | - | Additional CSS classes | | showLabel | `boolean` | No | `true` | Show the label text | | enableProfileSync | `boolean` | No | `false` | Enable profile synchronization | | maxDiscoveryAttempts | `number` | No | `3` | Max attempts for profile discovery | | onImportSuccess | `() => void` | No | - | Callback when import succeeds | ## Basic Usage ```tsx import { BackupImport } from 'bigblocks'; export default function RestorePage() { const handleImport = async (file: File) => { try { // Process the backup file const content = await file.text(); // Your backup processing logic await processBackup(content); console.log('Backup imported successfully'); } catch (error) { console.error('Import failed:', error); throw error; // Re-throw to show error in UI } }; return ( { console.log('Import completed!'); }} /> ); } ``` ## Advanced Usage ### With Authentication Manager ```tsx import { BackupImport } from 'bigblocks'; import { useAuthManager } from '@/hooks/useAuthManager'; export default function AuthBackupImport() { const authManager = useAuthManager(); return ( { await authManager.importBackup(file); }} onImportSuccess={() => { router.push('/dashboard'); }} /> ); } ``` ### With Profile Sync ```tsx import { BackupImport } from 'bigblocks'; export default function ProfileSyncImport() { return ( { toast.success('Backup imported with profile sync'); }} /> ); } ``` ### Disabled State ```tsx import { BackupImport } from 'bigblocks'; import { useState } from 'react'; export default function ConditionalImport() { const [isProcessing, setIsProcessing] = useState(false); return ( { setIsProcessing(true); try { await processBackupFile(file); } finally { setIsProcessing(false); } }} disabled={isProcessing} showLabel={!isProcessing} /> ); } ``` ### Custom Styling ```tsx import { BackupImport } from 'bigblocks'; export default function StyledImport() { return ( ); } ``` ## Common Patterns ### In Restore Flow ```tsx import { BackupImport } from 'bigblocks'; import { useState } from 'react'; export function RestoreFlow() { const [step, setStep] = useState<'import' | 'password' | 'complete'>('import'); const [backupFile, setBackupFile] = useState(null); return (

{step === 'import' && (

Import Your Backup

{ setBackupFile(file); setStep('password'); }} />

)} {step === 'password' && backupFile && (

Enter Password

{ await decryptAndImport(backupFile, password); setStep('complete'); }} />

)} {step === 'complete' && (

Import Complete!

)}

); } ``` ### With Error Handling ```tsx import { BackupImport } from 'bigblocks'; import { useState } from 'react'; export function ImportWithErrors() { const [error, setError] = useState(null); return (

{error && (

{error}

)} { setError(null); try { // Validate file if (!file.name.match(/\.(txt|json|enc)$/)) { throw new Error('Invalid file type. Please select a backup file.'); } if (file.size > 10 * 1024 * 1024) { throw new Error('File too large. Maximum size is 10MB.'); } await processBackup(file); } catch (err) { setError(err.message); throw err; // Re-throw for component error handling } }} onImportSuccess={() => { setError(null); toast.success('Backup imported successfully'); }} />

); } ``` ### Multiple Import Options ```tsx import { BackupImport } from 'bigblocks'; export function ImportOptions() { return (

Import from File

{ console.log('File import complete'); }} />

Import from Cloud

); } ``` ## File Handling The component accepts various backup file formats: ```typescript async function handleImport(file: File) { const content = await file.text(); // Detect format if (content.startsWith('U2FsdGVkX1')) { // Encrypted backup const password = await promptForPassword(); const decrypted = decrypt(content, password); await restoreFromBackup(decrypted); } else if (content.startsWith('{')) { // JSON backup const backup = JSON.parse(content); await restoreFromBackup(backup); } else if (content.match(/^[KL5][1-9A-HJ-NP-Za-km-z]{50,51}$/)) { // WIF format await restoreFromWIF(content); } else { throw new Error('Unknown backup format'); } } ``` ## Styling The component uses Radix Themes and can be customized: ```css /* Default structure */ .backup-import-container { /* Button styling from Radix */ } .backup-import-input { /* Hidden file input */ display: none; } ``` ## Best Practices 1. **Validation**: Always validate file format and size before processing 2. **Error Handling**: Provide clear error messages for common issues 3. **Progress Feedback**: Show loading state during import 4. **Success Confirmation**: Always confirm successful import 5. **Security**: Never log or expose sensitive backup data ## Security Considerations 1. **Client-Side Processing**: Handle backup data only in the browser 2. **File Validation**: Check file size and format before processing 3. **Password Protection**: Prompt for passwords for encrypted backups 4. **Memory Cleanup**: Clear sensitive data from memory after use 5. **Error Messages**: Don't expose sensitive information in errors ## Troubleshooting ### Import Button Not Working * Check that onImport handler is properly defined * Ensure component isn't disabled * Verify file input isn't blocked by browser ### File Not Processing * Check file format is supported * Verify file isn't corrupted * Ensure async operations are properly handled ### Success Callback Not Firing * Make sure onImport doesn't throw errors * Verify onImportSuccess prop is passed * Check that import process completes successfully ## Related Components * [BackupDownload](/docs/components/backup-download) - Download backups * [FileImport](/docs/components/file-import) - Generic file import * [IdentityGeneration](/docs/components/identity-generation) - Create new identity * [LoginForm](/docs/components/login-form) - Sign in with existing backup ## API Reference ### File Processing The onImport handler receives a File object: ```typescript interface File { name: string; size: number; type: string; lastModified: number; text(): Promise; arrayBuffer(): Promise; } ``` ### Error Handling Errors thrown in onImport will be caught and displayed by the component. Return or throw errors to show them to users. ## Notes for Improvement **Major Simplification**: The actual component is much simpler than the prompt described. It lacks: * Multiple format support options * Built-in validation * Progress tracking * Format detection * The extensive backend API integration described * Drag and drop functionality * Conflict resolution * Preview capabilities The actual implementation is a basic file input button that delegates all processing to the onImport handler. # CloudBackupManager URL: /docs/components/backup/cloud-backup-manager Component for managing encrypted cloud backups stored with OAuth providers *** title: CloudBackupManager description: Component for managing encrypted cloud backups stored with OAuth providers category: backup-recovery ------------------------- import { CloudBackupManagerDemo } from '@/components/docs/demos/CloudBackupManagerDemo'; A streamlined component for managing cloud-stored wallet backups via OAuth providers. It provides status checking, update capabilities, and automatic synchronization of encrypted backups. ## Installation ```bash npx bigblocks add cloud-backup-manager ``` ## Import ```typescript import { CloudBackupManager } from 'bigblocks'; ``` ## Props | Prop | Type | Required | Default | Description | | ----------------- | ------------------------------------- | -------- | ------- | ------------------------------- | | checkBackupStatus | `() => Promise` | No | - | Function to check backup status | | updateCloudBackup | `() => Promise` | No | - | Function to update cloud backup | | onStatusChange | `(status: CloudBackupStatus) => void` | No | - | Callback when status changes | | className | `string` | No | - | Additional CSS classes | ## Types ```typescript interface CloudBackupStatus { hasCloudBackup: boolean; isOutdated?: boolean; lastUpdated?: number; provider?: string; } ``` ## Basic Usage ```tsx import { CloudBackupManager } from 'bigblocks'; export default function BackupSettings() { const checkStatus = async () => { // Check backup status from your backend const response = await fetch('/api/backup/status'); return response.json(); }; const updateBackup = async () => { // Update cloud backup await fetch('/api/backup/sync', { method: 'POST' }); }; return ( { console.log('Backup status:', status); }} /> ); } ``` ## Advanced Usage ### With Authentication Context ```tsx import { CloudBackupManager } from 'bigblocks'; import { useAuth } from '@/hooks/useAuth'; export default function AuthenticatedBackup() { const { user, backup } = useAuth(); const checkBackupStatus = async () => { if (!user) throw new Error('Not authenticated'); const response = await fetch('/api/backup/status', { headers: { 'X-Auth-Token': user.authToken, }, }); return response.json(); }; const updateCloudBackup = async () => { if (!backup) throw new Error('No backup available'); await fetch('/api/backup/sync', { method: 'POST', headers: { 'X-Auth-Token': user.authToken, 'Content-Type': 'application/json', }, body: JSON.stringify({ backup }), }); }; return ( { if (status.isOutdated) { console.log('Backup is outdated, consider updating'); } }} /> ); } ``` ### With Custom Status Handling ```tsx import { CloudBackupManager } from 'bigblocks'; import { useState, useEffect } from 'react'; export default function CustomStatusHandling() { const [lastSync, setLastSync] = useState(null); const [provider, setProvider] = useState(null); const handleStatusChange = (status: CloudBackupStatus) => { if (status.lastUpdated) { setLastSync(new Date(status.lastUpdated)); } if (status.provider) { setProvider(status.provider); } }; return (

{lastSync && (

Last synced: {lastSync.toLocaleString()}

)} {provider && (

Backed up with: {provider}

)}

); } ``` ### Auto-sync Implementation ```tsx import { CloudBackupManager } from 'bigblocks'; import { useEffect, useRef } from 'react'; export default function AutoSyncBackup() { const intervalRef = useRef(null); const checkBackupStatus = async () => { const response = await fetch('/api/backup/status'); const status = await response.json(); // Auto-update if backup is outdated by more than 24 hours if (status.lastUpdated) { const hoursSinceUpdate = (Date.now() - status.lastUpdated) / (1000 * 60 * 60); if (hoursSinceUpdate > 24) { status.isOutdated = true; } } return status; }; useEffect(() => { // Check status every 5 minutes intervalRef.current = setInterval(() => { checkBackupStatus(); }, 5 * 60 * 1000); return () => { if (intervalRef.current) { clearInterval(intervalRef.current); } }; }, []); return ( { if (status.isOutdated) { // Trigger notification showNotification('Your backup is outdated'); } }} /> ); } ``` ### With Error Handling ```tsx import { CloudBackupManager } from 'bigblocks'; import { useState } from 'react'; export default function ErrorHandlingExample() { const [error, setError] = useState(null); const checkBackupStatus = async () => { try { setError(null); const response = await fetch('/api/backup/status'); if (!response.ok) { throw new Error('Failed to check backup status'); } return response.json(); } catch (err) { setError(err.message); throw err; } }; const updateCloudBackup = async () => { try { setError(null); const response = await fetch('/api/backup/sync', { method: 'POST', }); if (!response.ok) { throw new Error('Failed to update backup'); } } catch (err) { setError(err.message); throw err; } }; return (

{error && (

{error}

)}

); } ``` ## Common Patterns ### In Settings Page ```tsx import { CloudBackupManager } from 'bigblocks'; export function BackupSettingsSection() { return (

Backup Management

Keep your wallet backup synchronized with your cloud provider

Backup Tips

• Keep your backup password secure
• Update your backup after profile changes
• Backups are end-to-end encrypted

); } ``` ### With Multiple Providers ```tsx import { CloudBackupManager } from 'bigblocks'; import { useState } from 'react'; export function MultiProviderBackup() { const [activeProvider, setActiveProvider] = useState(null); const checkBackupStatus = async () => { // Check status across multiple providers const providers = ['google', 'github', 'dropbox']; for (const provider of providers) { const response = await fetch(`/api/backup/status?provider=${provider}`); const status = await response.json(); if (status.hasCloudBackup) { setActiveProvider(provider); return status; } } return { hasCloudBackup: false }; }; return (

{activeProvider && (

Active provider: {activeProvider}

)}

); } ``` ### In Dashboard Widget ```tsx import { CloudBackupManager } from 'bigblocks'; export function DashboardBackupWidget() { return (

Cloud Backup

Auto-sync enabled

{ // Update dashboard metrics updateDashboardMetrics({ backupStatus: status.hasCloudBackup ? 'active' : 'none', lastSync: status.lastUpdated, }); }} />

); } ``` ## API Reference This component provides cloud backup management functionality with configurable status checking and update capabilities. ## API Integration ### Status Check Endpoint ```typescript // GET /api/backup/status interface BackupStatusResponse { hasCloudBackup: boolean; isOutdated?: boolean; lastUpdated?: number; provider?: string; size?: number; profileCount?: number; } ``` ### Sync Endpoint ```typescript // POST /api/backup/sync interface BackupSyncRequest { backup?: string; // Optional encrypted backup data forceUpdate?: boolean; } interface BackupSyncResponse { success: boolean; provider: string; timestamp: number; backupId: string; } ``` ## Features * **Status Monitoring**: Real-time backup status checking * **Automatic Updates**: Detect and update outdated backups * **Provider Display**: Show which OAuth provider stores the backup * **Last Update Time**: Display when backup was last synchronized * **Status Callbacks**: React to backup status changes * **Error Handling**: Graceful error handling with user feedback ## Styling The component uses Radix Themes and can be customized: ```css /* Custom styling */ .cloud-backup-manager { padding: 1rem; border: 1px solid var(--gray-5); border-radius: var(--radius-3); } .backup-status { display: flex; align-items: center; gap: 0.5rem; } .update-button { margin-top: 0.5rem; } ``` ## Best Practices 1. **Regular Checks**: Implement periodic status checks 2. **Error Handling**: Always handle API errors gracefully 3. **User Feedback**: Show clear status messages 4. **Auto-sync**: Consider implementing automatic synchronization 5. **Security**: Ensure all backups are encrypted before cloud storage ## Security Considerations 1. **Encryption**: All backups are encrypted client-side 2. **OAuth Only**: Uses OAuth providers as storage, not authentication 3. **No Credentials**: Never store provider credentials 4. **Token Handling**: Secure handling of auth tokens 5. **HTTPS Only**: Always use secure connections ## Troubleshooting ### Status Not Updating * Verify checkBackupStatus returns correct format * Check network connectivity * Ensure proper authentication headers ### Update Failing * Verify updateCloudBackup is properly implemented * Check OAuth provider permissions * Ensure backup data is properly formatted ### Provider Not Showing * Confirm provider field is returned from status check * Verify OAuth connection is active * Check provider permissions ## Related Components * [BackupDownload](/docs/components/backup-download) - Download local backups * [BackupImport](/docs/components/backup-import) - Import backup files * [OAuthProviders](/docs/components/oauth-providers) - OAuth provider management * [IdentityGeneration](/docs/components/identity-generation) - Create new identities ## Notes for Improvement **Simplified Implementation**: The actual component is more focused than the prompt suggested: * No multi-provider UI management (handled by callbacks) * No built-in auto-sync configuration * No direct provider linking/unlinking * Delegates all API operations to parent component * Focus on status display and update triggering The actual implementation provides a clean interface for backup status management while leaving the complex provider and sync logic to the implementing application. # MnemonicDisplay URL: /docs/components/backup/mnemonic-display Component for displaying, verifying, or importing mnemonic seed phrases *** title: MnemonicDisplay description: Component for displaying, verifying, or importing mnemonic seed phrases category: backup-recovery ------------------------- import { MnemonicDisplayDemo } from '@/components/docs/demos/MnemonicDisplayDemo'; A versatile component for handling mnemonic seed phrases with three modes: viewing, verifying, and importing. It provides a secure interface for displaying recovery phrases with optional verification and import capabilities. ## Installation ```bash npx bigblocks add mnemonic-display ``` ## Import ```typescript import { MnemonicDisplay, MnemonicMode } from 'bigblocks'; ``` ## Props | Prop | Type | Required | Default | Description | | -------------------- | ---------------------------------- | -------- | -------- | -------------------------------------------------- | | mnemonic | `string` | No | - | Mnemonic phrase to display (for view/verify modes) | | mode | `MnemonicMode` | No | `'view'` | Display mode: 'view', 'verify', or 'import' | | onResult | `(result: MnemonicResult) => void` | No | - | Callback with operation result | | onContinue | `() => void` | No | - | Handler for continue action | | onBack | `() => void` | No | - | Handler for back action | | showCopyButton | `boolean` | No | `true` | Show copy to clipboard button | | requireVerification | `boolean` | No | `false` | Require verification in view mode | | wordCount | `12 \| 24` | No | `12` | Expected word count for import | | autoCompleteLastWord | `boolean` | No | `false` | Auto-complete the last word | | className | `string` | No | - | Additional CSS classes | ## Modes ### View Mode Display a mnemonic phrase securely with optional copy functionality: ```tsx import { MnemonicDisplay, MnemonicMode } from 'bigblocks'; export default function ViewMnemonic() { const mnemonic = "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about"; return ( { console.log('User acknowledged'); }} showCopyButton={true} /> ); } ``` ### Verify Mode Test user's backup by requiring them to confirm specific words: ```tsx import { MnemonicDisplay, MnemonicMode } from 'bigblocks'; export default function VerifyMnemonic() { const mnemonic = "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about"; return ( { if (result.verified) { console.log('Verification successful'); } else { console.log('Verification failed'); } }} /> ); } ``` ### Import Mode Allow users to enter their own mnemonic phrase: ```tsx import { MnemonicDisplay, MnemonicMode } from 'bigblocks'; export default function ImportMnemonic() { return ( { if (result.importedMnemonic) { console.log('Imported:', result.importedMnemonic); } }} /> ); } ``` ## Result Types ```typescript type MnemonicResult = { verified?: boolean; // For verify mode importedMnemonic?: string; // For import mode words?: string[]; // Word array for processing }; ``` ## Advanced Usage ### Complete Backup Flow ```tsx import { MnemonicDisplay, MnemonicMode } from 'bigblocks'; import { useState } from 'react'; export function BackupFlow() { const [step, setStep] = useState<'view' | 'verify' | 'complete'>('view'); const mnemonic = "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about"; return (

{step === 'view' && (

Your Recovery Phrase

setStep('verify')} showCopyButton={true} />

)} {step === 'verify' && (

Verify Your Backup

{ if (result.verified) { setStep('complete'); } else { alert('Please try again'); } }} onBack={() => setStep('view')} />

)} {step === 'complete' && (

Backup Complete!

Your recovery phrase has been verified.

)}

); } ``` ### Import with Validation ```tsx import { MnemonicDisplay, MnemonicMode } from 'bigblocks'; import { validateMnemonic } from '@bsv/sdk'; export function ImportWithValidation() { const handleImport = async (result: MnemonicResult) => { if (!result.importedMnemonic) return; try { // Validate mnemonic const isValid = validateMnemonic(result.importedMnemonic); if (!isValid) { throw new Error('Invalid mnemonic phrase'); } // Process valid mnemonic await processImport(result.importedMnemonic); } catch (error) { console.error('Import failed:', error); } }; return ( window.history.back()} /> ); } ``` ### View with Custom Styling ```tsx import { MnemonicDisplay, MnemonicMode } from 'bigblocks'; export function StyledMnemonicView() { return (

Recovery Phrase

{ console.log('Proceeding to next step'); }} />

⚠️ Never share these words with anyone

); } ``` ### Conditional Copy Button ```tsx import { MnemonicDisplay, MnemonicMode } from 'bigblocks'; import { useState } from 'react'; export function ConditionalCopy() { const [allowCopy, setAllowCopy] = useState(false); return (

setAllowCopy(e.target.checked)} className="mr-2" /> I understand the security risks of copying console.log('Continue')} />

); } ``` ## Common Patterns ### In SignupFlow ```tsx import { MnemonicDisplay, MnemonicMode } from 'bigblocks'; export function SignupMnemonicStep({ mnemonic, onComplete }) { const [verified, setVerified] = useState(false); return (

{!verified ? ( setVerified(true)} /> ) : ( { if (result.verified) { onComplete(); } }} /> )}

); } ``` ### Recovery Flow ```tsx import { MnemonicDisplay, MnemonicMode } from 'bigblocks'; export function RecoveryFlow() { const [mnemonic, setMnemonic] = useState(null); return (

Recover Your Wallet

{ if (result.importedMnemonic) { setMnemonic(result.importedMnemonic); // Proceed with recovery recoverWallet(result.importedMnemonic); } }} />

); } ``` ## Features by Mode ### View Mode Features * Grid display of numbered words * Optional copy to clipboard * Security warnings * Verification requirement option * Continue button ### Verify Mode Features * Random word verification * Input validation * Error feedback * Back navigation * Success/failure callbacks ### Import Mode Features * Word count selection (12 or 24) * Auto-completion for last word * BIP39 word list validation * Paste support * Progress tracking ## Styling The component uses Radix Themes and supports custom styling: ```css /* Word grid styling */ .mnemonic-grid { display: grid; grid-template-columns: repeat(3, 1fr); gap: 0.5rem; } /* Word item styling */ .mnemonic-word { padding: 0.5rem; background: var(--gray-2); border-radius: var(--radius-2); font-family: monospace; } ``` ## Best Practices 1. **Security First**: Always show security warnings in view mode 2. **Verification**: Require verification for new wallet creation 3. **Copy Protection**: Consider disabling copy for sensitive contexts 4. **Clear Instructions**: Provide mode-specific guidance 5. **Error Handling**: Validate mnemonics before processing ## Accessibility * Keyboard navigation for all interactive elements * Screen reader announcements for verification * Clear focus indicators * Semantic HTML structure ## Troubleshooting ### Verification Failing * Ensure correct mnemonic is passed * Check for extra spaces or formatting * Verify word indices are correct ### Import Not Working * Validate BIP39 word list compatibility * Check word count matches expected * Ensure proper whitespace handling ### Copy Not Working * Check browser clipboard permissions * Verify showCopyButton prop * Test in different browsers ## Related Components * [IdentityGeneration](/docs/components/identity-generation) - Generate new identities * [BackupDownload](/docs/components/backup-download) - Download encrypted backups * [SignupFlow](/docs/components/signup-flow) - Complete signup with mnemonic * [BackupImport](/docs/components/backup-import) - Import from various formats ## API Reference This component provides secure mnemonic phrase handling with three distinct modes for viewing, verifying, and importing seed phrases. ### MnemonicMode Enum ```typescript enum MnemonicMode { View = "view", Verify = "verify", Import = "import" } ``` ### MnemonicResult Type ```typescript type MnemonicResult = { verified?: boolean; // Verification success (verify mode) importedMnemonic?: string; // Imported phrase (import mode) words?: string[]; // Word array for processing }; ``` ## Notes for Improvement **Mode-Based Implementation**: The actual component is more sophisticated than the prompt suggested, with three distinct modes: * View mode for displaying phrases * Verify mode for testing user knowledge * Import mode for entering phrases The prompt described mainly view mode features, while the actual implementation provides a complete mnemonic handling solution with verification and import capabilities. # ArtifactDisplay URL: /docs/components/developer/artifact-display Universal content renderer for blockchain artifacts (ordinals, inscriptions, files) *** title: ArtifactDisplay description: Universal content renderer for blockchain artifacts (ordinals, inscriptions, files) categories: \[blockchain, content, display, media] -------------------------------------------------- import { ComponentBadges } from '@/components/docs/ComponentBadges'; import { ArtifactDisplayDemo } from '@/components/docs/demos/ArtifactDisplayDemo'; A universal content renderer for blockchain artifacts including ordinals, inscriptions, and files. This component supports a wide variety of content types including images, videos, audio, HTML, text, JSON, SVG, PDF, and 3D models. It uses the bitcoin-image library for blockchain URL processing. ## Demo ## API Reference This component is a custom implementation that handles various content types and media formats. For specific media types, consider using: * Native HTML elements (`img`, `video`, `audio`) * [SVG elements](https://developer.mozilla.org/en-US/docs/Web/SVG) for vector graphics * [Canvas API](https://developer.mozilla.org/en-US/docs/Web/API/Canvas_API) for interactive content ## Installation ```bash npx bigblocks add artifact-display ``` ## Import ```typescript import { ArtifactDisplay, ArtifactType } from 'bigblocks'; ``` ## Props | Prop | Type | Required | Default | Description | | ------------ | ---------------------------------- | -------- | ------- | ------------------------------------------------------- | | artifact | `ArtifactData` | Yes | - | The artifact data object containing source and metadata | | size | `number` | No | - | Display size in pixels | | maxWidth | `number` | No | - | Maximum width constraint | | showControls | `boolean` | No | `false` | Whether to show controls/footer | | allowZoom | `boolean` | No | `false` | Whether to allow zooming on the artifact | | showMetadata | `boolean` | No | `false` | Whether to show artifact metadata | | loading | `boolean` | No | `false` | Loading state indicator | | error | `string` | No | - | Error message to display | | className | `string` | No | - | Custom CSS classes | | onClick | `(artifact: ArtifactData) => void` | No | - | Click handler for the artifact | | onDownload | `(artifact: ArtifactData) => void` | No | - | Download handler | | onShare | `(artifact: ArtifactData) => void` | No | - | Share handler | | fallback | `React.ReactNode` | No | - | Custom fallback component for unsupported types | ## ArtifactData Interface ```typescript interface ArtifactData { /** The URL or blockchain reference to the artifact */ src: string; /** Content type (MIME type) */ contentType?: string; /** Artifact type (auto-detected if not provided) */ type?: ArtifactType; /** Size in bytes */ size?: number; /** Display name */ name?: string; /** Description */ description?: string; /** Transaction ID (for blockchain artifacts) */ txid?: string; /** Output index */ vout?: number; /** Inscription number */ number?: string | number; /** Additional metadata */ metadata?: Record; } ``` ## Artifact Types ```typescript enum ArtifactType { Image = "image", Video = "video", Audio = "audio", HTML = "html", Text = "text", JSON = "json", SVG = "svg", PDF = "pdf", Model = "model", Unknown = "unknown" } ``` ## Basic Usage ```tsx import { ArtifactDisplay } from 'bigblocks'; export default function Example() { const artifact = { src: "https://ordfs.network/abc123_0", contentType: "image/png", name: "My NFT", txid: "abc123", vout: 0 }; return ( ); } ``` ## Advanced Usage ### With Event Handlers ```tsx import { ArtifactDisplay, ArtifactData } from 'bigblocks'; export default function InteractiveArtifact() { const handleClick = (artifact: ArtifactData) => { console.log('Artifact clicked:', artifact.name); }; const handleDownload = (artifact: ArtifactData) => { // Custom download logic console.log('Downloading:', artifact.src); }; const handleShare = (artifact: ArtifactData) => { // Share functionality navigator.share({ title: artifact.name, url: artifact.src }); }; const artifact = { src: "ordfs://abc123_0", contentType: "video/mp4", name: "Bitcoin Documentary", description: "A short documentary about Bitcoin", size: 5242880, // 5MB txid: "abc123", vout: 0, metadata: { duration: "2:30", creator: "Satoshi" } }; return ( ); } ``` ### With Custom Fallback ```tsx import { ArtifactDisplay } from 'bigblocks'; export default function ArtifactWithFallback() { const artifact = { src: "blockchain://unknown-format", type: ArtifactType.Unknown, name: "Unknown Artifact" }; const customFallback = (

This artifact type is not supported

Download Raw File

); return ( ); } ``` ## Common Patterns ### Gallery Display ```tsx import { ArtifactDisplay } from 'bigblocks'; export function ArtifactGallery({ artifacts }) { return (

{artifacts.map((artifact) => ( openLightbox(art)} /> ))}

); } ``` ### Loading States ```tsx import { ArtifactDisplay } from 'bigblocks'; import { useState, useEffect } from 'react'; export function AsyncArtifact({ txid }) { const [artifact, setArtifact] = useState(null); const [loading, setLoading] = useState(true); const [error, setError] = useState(null); useEffect(() => { fetchArtifact(txid) .then(setArtifact) .catch(err => setError(err.message)) .finally(() => setLoading(false)); }, [txid]); return ( ); } ``` ## Troubleshooting ### Artifact Not Displaying * Ensure the `src` URL is accessible * Check that the `contentType` is correctly set or can be auto-detected * Verify blockchain URLs are properly formatted (e.g., `ordfs://txid_vout`) ### Performance Issues * Use the `size` prop to constrain large images/videos * Implement lazy loading for galleries with many artifacts * Consider thumbnails for initial display ### CORS Errors * Blockchain URLs may require proxy configuration * Ensure your bitcoin-image library is properly configured * Check browser console for specific CORS error messages ## Related Components * [BitcoinImage](/docs/components/bitcoin-image) - Optimized image display for blockchain sources * [FileImport](/docs/components/file-import) - Import files to create artifacts * [QRCodeRenderer](/docs/components/qr-code-renderer) - Display artifact URLs as QR codes ## API Reference ### ArtifactType Enum The component exports an `ArtifactType` enum for type-safe artifact type specification. ### Type Detection If `type` is not provided in the artifact data, the component will attempt to auto-detect based on: 1. The `contentType` MIME type 2. File extension in the `src` URL 3. Blockchain metadata ## Notes for Improvement **Discrepancy Alert**: The original prompt for this component incorrectly described it as displaying Bitcoin transactions, blocks, and scripts. The actual implementation is a media/content renderer for blockchain artifacts. If transaction/block/script display functionality is needed, consider creating separate components like `TransactionDisplay`, `BlockDisplay`, and `ScriptDisplay`. # DataPushButton URL: /docs/components/developer/data-push-button Push structured data to the Bitcoin blockchain using predefined protocol templates *** title: DataPushButton description: Push structured data to the Bitcoin blockchain using predefined protocol templates category: droplit ----------------- A powerful component for pushing structured data to the Bitcoin blockchain using predefined protocol templates. Unlike traditional OP\_RETURN data storage, this component uses the droplit protocol for zero-cost data transactions while maintaining blockchain permanence. [View Component Preview →](/component-preview/data-push-button) ## Installation ```bash npx bigblocks add data-push-button ``` ## Import ```typescript import { DataPushButton } from 'bigblocks'; ``` ## Props | Prop | Type | Required | Default | Description | | -------------------- | ---------------------------------------------------------------------- | -------- | -------------- | -------------------------------------------- | | onSuccess | `(result: { txid: string; data: string[]; template: string }) => void` | No | - | Callback when data is successfully pushed | | onError | `(error: Error) => void` | No | - | Error callback | | data | `string[]` | No | - | Custom data array to push (disables form UI) | | template | `DataTemplate` | No | First template | Pre-selected protocol template | | buttonText | `string` | No | `'Push Data'` | Custom button text | | variant | `'solid' \| 'soft' \| 'outline' \| 'ghost'` | No | `'solid'` | Button variant style | | size | `'1' \| '2' \| '3' \| '4'` | No | `'2'` | Button size | | showTemplateSelector | `boolean` | No | `true` | Show protocol template selector | | showPreview | `boolean` | No | `true` | Show data preview before pushing | | className | `string` | No | - | Additional CSS classes | | color | `'blue' \| 'green' \| 'orange' \| 'red' \| 'purple' \| 'gray'` | No | `'orange'` | Button color theme | | requireAuth | `boolean` | No | `false` | Require authentication | | disabled | `boolean` | No | `false` | Disable the button | ## Basic Usage ```tsx import { DataPushButton } from 'bigblocks'; function MyComponent() { return ( { console.log('Data pushed:', result.txid); console.log('Template used:', result.template); console.log('Data array:', result.data); }} onError={(error) => { console.error('Push failed:', error); }} /> ); } ``` ## Advanced Usage ### With Custom Template Selection ```tsx { alert(`Posted! TX ID: ${result.txid}`); }} /> ``` ### Button-Only Mode with Custom Data ```tsx { console.log('Market listing created:', result.txid); }} /> ``` ## Common Patterns ### Social Media Integration ```tsx function SocialPostForm() { const [content, setContent] = useState(''); return (

setContent(e.target.value)}
        placeholder="What's on your mind?"
      />
      <DataPushButton
        data={['B_SOCIAL', 'POST', content, new Date().toISOString()]}
        showTemplateSelector={false}
        buttonText="Post"
        disabled={!content}
        onSuccess={(result) => {
          setContent(''); // Clear form
          console.log('Posted with ID:', result.txid);
        }}
      />
    </div>
  );
}
```

### Marketplace Listing

```tsx
function CreateListing({ ordinalId, price }) {
  return (
    <DataPushButton
      data={[
        'B_MARKET', 
        'LIST', 
        ordinalId, 
        price.toString(), 
        'BSV', 
        'Digital Art NFT'
      ]}
      buttonText={`List for ${price} satoshis`}
      color="green"
      size="4"
      requireAuth={true}
      onSuccess={(result) => {
        router.push(`/market/listing/${result.txid}`);
      }}
      onError={(error) => {
        if (error.message.includes('Authentication')) {
          router.push('/signin');
        }
      }}
    />
  );
}
```

### Identity Attestation

```tsx
function IdentityClaim({ claimType, claimValue }) {
  const { address, signMessage } = useBitcoinAuth();
  
  const handleAttest = async () => {
    const signature = await signMessage(`${claimType}:${claimValue}`);
    
    return (
      <DataPushButton
        data={['B_ID', 'ATTEST', claimType, claimValue, signature]}
        buttonText="Attest Identity"
        color="purple"
        variant="outline"
        requireAuth={true}
        onSuccess={(result) => {
          console.log('Identity attested:', result.txid);
        }}
      />
    );
  };
}
```

## Protocol Templates

The component includes several built-in protocol templates:

### Social Post

```typescript
{
  protocol: 'B_SOCIAL',
  example: ['B_SOCIAL', 'POST', 'content', 'timestamp']
}
```

### Social Like

```typescript
{
  protocol: 'B_SOCIAL',
  example: ['B_SOCIAL', 'LIKE', 'post-txid', 'emoji-reaction']
}
```

### Market Listing

```typescript
{
  protocol: 'B_MARKET',
  example: ['B_MARKET', 'LIST', 'item-id', 'price', 'currency', 'description']
}
```

### Identity Claim

```typescript
{
  protocol: 'B_ID',
  example: ['B_ID', 'ATTEST', 'claim-type', 'claim-value', 'signature']
}
```

## Custom Template Definition

```tsx
const customTemplate: DataTemplate = {
  id: 'my-app-action',
  name: 'My App Action',
  description: 'Custom action for my application',
  protocol: 'MY_APP',
  category: 'protocol',
  example: ['MY_APP', 'ACTION', 'data1', 'data2', 'data3']
};

<DataPushButton
  template={customTemplate}
  onSuccess={(result) => {
    console.log('Custom action recorded:', result);
  }}
/>
```

## Authentication Requirements

When `requireAuth` is true, the component requires:

```tsx
import { BitcoinAuthProvider, BitcoinQueryProvider } from 'bigblocks';

function App() {
  return (
    <BitcoinQueryProvider>
      <BitcoinAuthProvider config={{ apiUrl: '/api' }}>
        <DataPushButton requireAuth={true} />
      </BitcoinAuthProvider>
    </BitcoinQueryProvider>
  );
}
```

## API Integration

### Data Push Response

```typescript
interface DataPushResult {
  txid: string;        // Transaction ID (simulated for droplit)
  data: string[];      // Data array that was pushed
  template: string;    // Template ID used
}
```

### Error Handling

```typescript
interface DataPushError {
  message: string;
  code?: 'AUTH_REQUIRED' | 'INVALID_DATA' | 'NETWORK_ERROR';
}
```

## Styling

The component uses Radix Themes and can be customized:

```tsx
<DataPushButton
  className="my-custom-class"
  color="blue"
  variant="soft"
  size="3"
/>
```

### CSS Variables

```css
.my-custom-class {
  --button-height: 48px;
  --button-padding: 24px;
  --button-radius: 8px;
}
```

## Troubleshooting

### Authentication Required Error

**Solution**: Wrap the component in `BitcoinAuthProvider` and ensure the user is signed in.

### Template Not Found

**Solution**: Use one of the built-in templates or provide a complete custom template object.

### Data Format Error

**Solution**: Ensure the data array matches the expected protocol format (array of strings).

### Network Issues

**Solution**: The droplit protocol simulates blockchain operations without actual network calls, so network errors are rare.

## Best Practices

1. **Use Templates**: Leverage built-in templates for standard protocols
2. **Validate Data**: Ensure data arrays match protocol specifications
3. **Handle Errors**: Always provide error handlers for user feedback
4. **Show Preview**: Enable preview for user confirmation
5. **Authentication**: Require auth for sensitive operations

## Related Components

* [TapButton](/docs/components/tap-button) - Simple data push without templates
* [PostButton](/docs/components/post-button) - Specialized social posting
* [CreateListingButton](/docs/components/create-listing-button) - Marketplace listings
* [LikeButton](/docs/components/like-button) - Social interactions

## API Reference

### DataTemplate Interface

```typescript
interface DataTemplate {
  id: string;
  name: string;
  description: string;
  protocol: string;
  category: 'social' | 'market' | 'identity' | 'protocol';
  example: string[];
}
```

### Component Methods

The component handles all data pushing internally. For programmatic access:

```typescript
// Use the data prop for direct control
const pushData = (dataArray: string[]) => {
  return <DataPushButton data={dataArray} />;
};
```

# Storage Adapter
URL: /docs/components/developer/storage-adapter

Pluggable storage interface for BigBlocks authentication and data persistence

***

title: Storage Adapter
description: Pluggable storage interface for BigBlocks authentication and data persistence
category: utilities
-------------------

import { StorageAdapterDemo } from '@/components/docs/demos/StorageAdapterDemo';

A pluggable storage interface that provides a consistent API for data persistence across different environments. BigBlocks uses storage adapters for authentication data, session management, and backup persistence.

## Installation

```bash
npx bigblocks add storage-adapter
```

## Import

```typescript
import { createMemoryStorage, createLocalStorage } from 'bigblocks';
```

## Interface

All storage adapters implement the `StorageAdapter` interface:

```typescript
interface StorageAdapter {
  get: (key: string) => Promise<string | null>;
  set: (key: string, value: string) => Promise<void>;
  delete: (key: string) => Promise<void>;
  clear?: () => Promise<void>;
}
```

## Built-in Adapters

### Memory Storage

For testing and development without persistence:

```typescript
import { createMemoryStorage } from 'bigblocks';

const storage = createMemoryStorage();

// Usage with auth
const authManager = createAuthManager({
  apiUrl: '/api',
  storage: storage
});
```

### Local Storage

For browser-based persistence:

```typescript
import { createLocalStorage } from 'bigblocks';

const storage = createLocalStorage();

// With namespace
const namespacedStorage = createLocalStorage('myapp');
```

### Session Storage

For temporary session-based storage:

```typescript
import { createSessionStorage } from 'bigblocks';

const storage = createSessionStorage();
```

## Custom Storage Adapters

### Server-Side Storage

For Node.js environments:

```typescript
import { StorageAdapter } from 'bigblocks';

class ServerStorageAdapter implements StorageAdapter {
  private storage = new Map<string, string>();
  
  async get(key: string): Promise<string | null> {
    // Implement database/file system retrieval
    return this.storage.get(key) || null;
  }
  
  async set(key: string, value: string): Promise<void> {
    // Implement database/file system storage
    this.storage.set(key, value);
  }
  
  async delete(key: string): Promise<void> {
    // Implement database/file system removal
    this.storage.delete(key);
  }
  
  async clear(): Promise<void> {
    // Clear all stored data
    this.storage.clear();
  }
}

const auth = createAuthManager({
  apiUrl: '/api',
  storage: new ServerStorageAdapter()
});
```

### Redis Storage

For distributed applications:

```typescript
import Redis from 'ioredis';
import { StorageAdapter } from 'bigblocks';

class RedisStorageAdapter implements StorageAdapter {
  private redis: Redis;
  private namespace: string;
  
  constructor(redisUrl: string, namespace = 'bigblocks:') {
    this.redis = new Redis(redisUrl);
    this.namespace = namespace;
  }
  
  async get(key: string): Promise<string | null> {
    return this.redis.get(this.namespace + key);
  }
  
  async set(key: string, value: string): Promise<void> {
    await this.redis.set(this.namespace + key, value);
  }
  
  async delete(key: string): Promise<void> {
    await this.redis.del(this.namespace + key);
  }
  
  async clear(): Promise<void> {
    const keys = await this.redis.keys(this.namespace + '*');
    if (keys.length > 0) {
      await this.redis.del(...keys);
    }
  }
}

const auth = createBigBlocksAuth({
  storage: new RedisStorageAdapter(process.env.REDIS_URL!)
});
```

### Encrypted Storage

For enhanced security:

```typescript
import { StorageAdapter } from 'bigblocks';
import CryptoJS from 'crypto-js';

class EncryptedStorageAdapter implements StorageAdapter {
  private storage: StorageAdapter;
  private encryptionKey: string;
  
  constructor(storage: StorageAdapter, encryptionKey: string) {
    this.storage = storage;
    this.encryptionKey = encryptionKey;
  }
  
  async get(key: string): Promise<string | null> {
    const encrypted = await this.storage.get(key);
    if (!encrypted) return null;
    
    try {
      const bytes = CryptoJS.AES.decrypt(encrypted, this.encryptionKey);
      return bytes.toString(CryptoJS.enc.Utf8);
    } catch {
      return null; // Invalid or corrupted data
    }
  }
  
  async set(key: string, value: string): Promise<void> {
    const encrypted = CryptoJS.AES.encrypt(value, this.encryptionKey).toString();
    await this.storage.set(key, encrypted);
  }
  
  async delete(key: string): Promise<void> {
    await this.storage.delete(key);
  }
  
  async clear(): Promise<void> {
    await this.storage.clear();
  }
}

// Usage
const baseStorage = createLocalStorage();
const encryptedStorage = new EncryptedStorageAdapter(baseStorage, 'secret-key');

const auth = createAuthManager({
  apiUrl: '/api',
  storage: encryptedStorage
});
```

## Usage with Components

### AuthManager

```typescript
import { createAuthManager, createMemoryStorage } from 'bigblocks';

const authManager = createAuthManager({
  apiUrl: '/api',
  storage: createMemoryStorage(), // For testing
  storageNamespace: 'auth:'
});
```

### BitcoinAuthProvider

```typescript
import { BitcoinAuthProvider, createLocalStorage } from 'bigblocks';

function App() {
  return (
    <BitcoinAuthProvider
      appId="my-app"
      apiUrl="/api"
      storage={createLocalStorage('my-app')}
    >
      {/* Your app */}
    </BitcoinAuthProvider>
  );
}
```

### createBigBlocksAuth

```typescript
import { createBigBlocksAuth, createSessionStorage } from 'bigblocks';

const auth = createBigBlocksAuth({
  apiUrl: '/api',
  storage: createSessionStorage(),
  storageNamespace: 'bigblocks:auth:'
});
```

## Configuration Options

### Storage Namespacing

Use namespaces to avoid key conflicts:

```typescript
const auth = createAuthManager({
  apiUrl: '/api',
  storage: createLocalStorage(),
  storageNamespace: 'myapp:auth:' // Prefix for all keys
});
```

### Multiple Storage Instances

Use different storage for different purposes:

```typescript
const sessionStorage = createSessionStorage();
const localStorage = createLocalStorage();

// Session data
const auth = createAuthManager({
  apiUrl: '/api',
  storage: sessionStorage
});

// Persistent user preferences
const preferences = {
  storage: localStorage,
  get: (key: string) => localStorage.get(`prefs:${key}`),
  set: (key: string, value: string) => localStorage.set(`prefs:${key}`, value)
};
```

## Testing

### Mock Storage

For unit tests:

```typescript
import { StorageAdapter } from 'bigblocks';

class MockStorageAdapter implements StorageAdapter {
  private data: Record<string, string> = {};
  
  async get(key: string): Promise<string | null> {
    return this.data[key] || null;
  }
  
  async set(key: string, value: string): Promise<void> {
    this.data[key] = value;
  }
  
  async delete(key: string): Promise<void> {
    delete this.data[key];
  }
  
  async clear(): Promise<void> {
    this.data = {};
  }
  
  // Test helpers
  getData() {
    return { ...this.data };
  }
  
  setData(data: Record<string, string>) {
    this.data = { ...data };
  }
}

// In tests
const mockStorage = new MockStorageAdapter();
const auth = createAuthManager({
  apiUrl: '/api',
  storage: mockStorage
});

// Verify storage calls
expect(mockStorage.getData()).toEqual({
  'auth:session': 'encrypted-session-data'
});
```

## Error Handling

### Graceful Degradation

```typescript
class FallbackStorageAdapter implements StorageAdapter {
  private primary: StorageAdapter;
  private fallback: StorageAdapter;
  
  constructor(primary: StorageAdapter, fallback: StorageAdapter) {
    this.primary = primary;
    this.fallback = fallback;
  }
  
  async get(key: string): Promise<string | null> {
    try {
      return await this.primary.get(key);
    } catch {
      return await this.fallback.get(key);
    }
  }
  
  async set(key: string, value: string): Promise<void> {
    try {
      await this.primary.set(key, value);
    } catch {
      await this.fallback.set(key, value);
    }
  }
  
  async delete(key: string): Promise<void> {
    await Promise.all([
      this.primary.delete(key).catch(() => {}),
      this.fallback.delete(key).catch(() => {})
    ]);
  }
  
  async clear(): Promise<void> {
    await Promise.all([
      this.primary.clear().catch(() => {}),
      this.fallback.clear().catch(() => {})
    ]);
  }
}

// Usage
const storage = new FallbackStorageAdapter(
  createLocalStorage(),
  createMemoryStorage()
);
```

### Storage Quota Management

```typescript
class QuotaAwareStorage implements StorageAdapter {
  private storage: StorageAdapter;
  private maxSize: number;
  
  constructor(storage: StorageAdapter, maxSize = 5 * 1024 * 1024) { // 5MB
    this.storage = storage;
    this.maxSize = maxSize;
  }
  
  async setItem(key: string, value: string): Promise<void> {
    if (value.length > this.maxSize) {
      throw new Error('Value exceeds storage quota');
    }
    
    try {
      await this.storage.set(key, value);
    } catch (error) {
      if (error.name === 'QuotaExceededError') {
        // Clear old data and retry
        await this.cleanupOldData();
        await this.storage.set(key, value);
      } else {
        throw error;
      }
    }
  }
  
  private async cleanupOldData(): Promise<void> {
    // Implement cleanup strategy
    console.warn('Storage quota exceeded, cleaning up old data');
  }
  
  async get(key: string): Promise<string | null> {
    return this.storage.get(key);
  }
  
  async delete(key: string): Promise<void> {
    return this.storage.delete(key);
  }
  
  async clear(): Promise<void> {
    return this.storage.clear();
  }
}
```

## Best Practices

1. **Choose the Right Adapter**: Use memory storage for testing, local storage for browsers, custom adapters for servers
2. **Handle Async Operations**: Many storage operations are async, always await them
3. **Use Namespaces**: Prevent key conflicts with proper namespacing
4. **Error Handling**: Implement fallback strategies for storage failures
5. **Security**: Use encrypted storage for sensitive data
6. **Testing**: Mock storage for unit tests to avoid side effects

## Common Patterns

### Configuration Factory

```typescript
function createStorageConfig(env: 'development' | 'test' | 'production') {
  switch (env) {
    case 'test':
      return createMemoryStorage();
    
    case 'development':
      return createLocalStorage('dev');
    
    case 'production':
      return new EncryptedStorageAdapter(
        createLocalStorage(),
        process.env.ENCRYPTION_KEY!
      );
  }
}

const storage = createStorageConfig(process.env.NODE_ENV);
```

### Multi-Layer Storage

```typescript
class CachedStorageAdapter implements StorageAdapter {
  private cache: StorageAdapter;
  private persistent: StorageAdapter;
  
  constructor(cache: StorageAdapter, persistent: StorageAdapter) {
    this.cache = cache;
    this.persistent = persistent;
  }
  
  async get(key: string): Promise<string | null> {
    // Try cache first
    let value = await this.cache.get(key);
    if (value === null) {
      // Fallback to persistent storage
      value = await this.persistent.get(key);
      if (value !== null) {
        // Cache for next time
        await this.cache.set(key, value);
      }
    }
    return value;
  }
  
  async set(key: string, value: string): Promise<void> {
    await Promise.all([
      this.cache.set(key, value),
      this.persistent.set(key, value)
    ]);
  }
  
  async delete(key: string): Promise<void> {
    await Promise.all([
      this.cache.delete(key),
      this.persistent.delete(key)
    ]);
  }
  
  async clear(): Promise<void> {
    await Promise.all([
      this.cache.clear(),
      this.persistent.clear()
    ]);
  }
}
```

## Related Components

* [createMemoryStorage](/docs/components/create-memory-storage) - Memory-based storage utility
* [createLocalStorage](/docs/components/create-local-storage) - Browser localStorage wrapper
* [AuthManager](/docs/components/auth-manager) - Uses storage for session persistence
* [BitcoinAuthProvider](/docs/components/bitcoin-auth-provider) - Provider with storage configuration

## API Reference

This component provides a consistent storage interface for all BigBlocks components and utilities. The interface supports both synchronous and asynchronous operations to accommodate different storage backends.

### Core Interface

### Built-in Utilities

* `createMemoryStorage()` - In-memory storage for testing
* `createLocalStorage(namespace?)` - Browser localStorage wrapper
* `createSessionStorage(namespace?)` - Browser sessionStorage wrapper

# TapButton
URL: /docs/components/developer/tap-button

A Droplit-specific button component for data transactions without BSV fees, demonstrating multi-tenant wallet interactions

***

title: TapButton
description: A Droplit-specific button component for data transactions without BSV fees, demonstrating multi-tenant wallet interactions
category: other
---------------

A specialized button component designed for Droplit multi-tenant wallet platform, enabling data transactions without BSV costs. Perfect for applications requiring frequent micro-interactions, loyalty programs, or engagement tracking without blockchain fees.

[View Component Preview →](/component-preview/tap-button)

## Installation

```bash
npx bigblocks add tap-button
```

## Import

```typescript
import { TapButton } from 'bigblocks';
```

## Props

| Prop         | Type                                                           | Required | Default         | Description                       |
| ------------ | -------------------------------------------------------------- | -------- | --------------- | --------------------------------- |
| onSuccess    | `(result: TapResult) => void`                                  | No       | -               | Success callback with tap details |
| onError      | `(error: Error) => void`                                       | No       | -               | Error callback                    |
| buttonText   | `string`                                                       | No       | `'Tap Droplit'` | Button label text                 |
| variant      | `'solid' \| 'soft' \| 'outline' \| 'ghost'`                    | No       | `'solid'`       | Button style variant              |
| size         | `'1' \| '2' \| '3' \| '4'`                                     | No       | `'2'`           | Button size                       |
| disabled     | `boolean`                                                      | No       | `false`         | Disable button                    |
| className    | `string`                                                       | No       | -               | Additional CSS classes            |
| showTapCount | `boolean`                                                      | No       | `true`          | Display tap counter               |
| color        | `'blue' \| 'green' \| 'orange' \| 'red' \| 'purple' \| 'gray'` | No       | `'blue'`        | Button color theme                |

### TapResult Interface

```typescript
interface TapResult {
  message: string;      // Success message with tap count
  timestamp: string;    // ISO timestamp of the tap
  tapCount: number;     // Total number of taps in session
}
```

## Basic Usage

```tsx
import { TapButton } from 'bigblocks';

export default function BasicExample() {
  const handleTapSuccess = (result) => {
    console.log('Tap successful:', result);
    // result: { message: "Droplit access granted! Tap #1", timestamp: "2024-01-20T...", tapCount: 1 }
  };

return (
    <TapButton onSuccess={handleTapSuccess} />
  );
}
```

## Advanced Usage

### Complete Integration Example

```tsx
import { TapButton } from 'bigblocks';
import { useState } from 'react';

export default function DroplitIntegration() {
  const [totalTaps, setTotalTaps] = useState(0);
  const [lastTapTime, setLastTapTime] = useState<string | null>(null);
  const [error, setError] = useState<string | null>(null);
  const [rewards, setRewards] = useState(0);

const handleTapError = (error: Error) => {
    console.error('Tap failed:', error);
    setError(error.message);
  };

return (
    <div className="droplit-integration">
      <h2>Droplit Engagement</h2>
      
      <TapButton
        onSuccess={handleTapSuccess}
        onError={handleTapError}
        buttonText="Earn Points"
        color="green"
        size="3"
      />
      
      <div className="stats">
        <p>Total Taps: {totalTaps}</p>
        <p>Reward Points: {rewards}</p>
        {lastTapTime && (
          <p>Last Tap: {new Date(lastTapTime).toLocaleTimeString()}</p>
        )}
      </div>
      
      {error && (
        <div className="error-message">
          Error: {error}
        </div>
      )}
    </div>
  );
}
```

### Multi-Tenant Application

```tsx
import { TapButton } from 'bigblocks';
import { useTenant } from '@/hooks/useTenant';

export default function TenantSpecificTap() {
  const { tenant, tenantConfig } = useTenant();
  const [interactions, setInteractions] = useState<TapResult[]>([]);

return (
    <div className="tenant-tap">
      <h3>{tenant.name} Engagement</h3>
      
      <TapButton
        onSuccess={handleTenantTap}
        buttonText={tenantConfig.buttonText || 'Tap to Engage'}
        color={tenantConfig.brandColor || 'blue'}
        showTapCount={tenantConfig.showCounter !== false}
      />
      
      {tenantConfig.showHistory && (
        <div className="interaction-history">
          {interactions.map((tap, i) => (
            <div key={i}>
              Tap #{tap.tapCount} at {new Date(tap.timestamp).toLocaleTimeString()}
            </div>
          ))}
        </div>
      )}
    </div>
  );
}
```

## Common Patterns

### Gamification System

```tsx
import { TapButton } from 'bigblocks';
import { useState, useEffect } from 'react';

export default function GamificationExample() {
  const [level, setLevel] = useState(1);
  const [experience, setExperience] = useState(0);
  const [achievements, setAchievements] = useState<string[]>([]);
  const [streak, setStreak] = useState(0);
  const [lastTapDate, setLastTapDate] = useState<string | null>(null);

const calculateLevel = (totalTaps: number) => Math.floor(Math.sqrt(totalTaps / 10)) + 1;
  const calculateXP = (tapCount: number) => tapCount * 10;

return (
    <div className="gamification-system">
      <div className="player-stats">
        <h3>Level {level}</h3>
        <div className="xp-bar">
          <div 
            className="xp-fill" 
            style={{ width: `${(experience % 100)}%` }}
          />
        </div>
        <p>{experience} XP | {streak} day streak</p>
      </div>
      
      <TapButton
        onSuccess={handleGameTap}
        buttonText="Tap for XP"
        color="purple"
        size="3"
      />
      
      {achievements.length > 0 && (
        <div className="achievements">
          <h4>Achievements ({achievements.length})</h4>
          {achievements.map(a => (
            <span key={a} className="achievement-badge">🏆 {a}</span>
          ))}
        </div>
      )}
    </div>
  );
}
```

### Loyalty Program Integration

```tsx
import { TapButton } from 'bigblocks';
import { useLoyaltyProgram } from '@/hooks/useLoyaltyProgram';

export default function LoyaltyTapButton() {
  const { 
    points, 
    tier, 
    addPoints, 
    checkTierUpgrade 
  } = useLoyaltyProgram();

const POINTS_PER_TAP = 5;
  const BONUS_MULTIPLIER = {
    bronze: 1,
    silver: 1.5,
    gold: 2,
    platinum: 3
  };

return (
    <div className="loyalty-tap">
      <div className="loyalty-status">
        <h4>{tier.toUpperCase()} Member</h4>
        <p>{points.toLocaleString()} points</p>
      </div>
      
      <TapButton
        onSuccess={handleLoyaltyTap}
        buttonText={`Tap for ${POINTS_PER_TAP * BONUS_MULTIPLIER[tier]} pts`}
        color={tier === 'platinum' ? 'purple' : tier === 'gold' ? 'orange' : 'blue'}
        size="3"
      />
      
      <p className="bonus-info">
        {tier} tier: {BONUS_MULTIPLIER[tier]}x points per tap
      </p>
    </div>
  );
}
```

### A/B Testing Variant

```tsx
import { TapButton } from 'bigblocks';
import { useABTest } from '@/hooks/useABTest';

export default function ABTestTapButton() {
  const { variant, trackConversion } = useABTest('tap-button-experiment');
  const [conversions, setConversions] = useState(0);

// Different configurations for A/B test
  const variants = {
    control: {
      text: 'Tap Droplit',
      color: 'blue' as const,
      size: '2' as const
    },
    variantA: {
      text: 'Earn Rewards Now',
      color: 'green' as const,
      size: '3' as const
    },
    variantB: {
      text: '💧 Tap for Points',
      color: 'orange' as const,
      size: '3' as const
    }
  };

const config = variants[variant] || variants.control;

return (
    <div className="ab-test-container">
      <p>Test Variant: {variant}</p>
      
      <TapButton
        onSuccess={handleABTap}
        buttonText={config.text}
        color={config.color}
        size={config.size}
        variant="solid"
      />
      
      <p>Conversions: {conversions}</p>
    </div>
  );
}
```

### Rate-Limited Tapping

```tsx
import { TapButton } from 'bigblocks';
import { useState, useEffect } from 'react';

export default function RateLimitedTap() {
  const [remainingTaps, setRemainingTaps] = useState(10);
  const [resetTime, setResetTime] = useState<Date | null>(null);
  const [isRateLimited, setIsRateLimited] = useState(false);

const TAP_LIMIT = 10;
  const RESET_INTERVAL = 60 * 60 * 1000; // 1 hour

useEffect(() => {
    // Check stored rate limit data
    const stored = localStorage.getItem('tapRateLimit');
    if (stored) {
      const { count, resetAt } = JSON.parse(stored);
      const now = new Date();
      const reset = new Date(resetAt);
      
      if (now < reset) {
        setRemainingTaps(TAP_LIMIT - count);
        setResetTime(reset);
        setIsRateLimited(count >= TAP_LIMIT);
      } else {
        // Reset period has passed
        localStorage.removeItem('tapRateLimit');
        setRemainingTaps(TAP_LIMIT);
      }
    }
  }, []);

return (
    <div className="rate-limited-tap">
      <h3>Limited Engagement</h3>
      
      <TapButton
        onSuccess={handleRateLimitedTap}
        buttonText={isRateLimited ? 'Rate Limited' : `Tap (${remainingTaps} left)`}
        disabled={isRateLimited}
        color={isRateLimited ? 'red' : 'blue'}
      />
      
      {isRateLimited && resetTime && (
        <p className="rate-limit-message">
          Reset in: {formatTimeRemaining()}
        </p>
      )}
      
      <div className="tap-meter">
        <div 
          className="tap-meter-fill"
          style={{ width: `${(remainingTaps / TAP_LIMIT) * 100}%` }}
        />
      </div>
    </div>
  );
}
```

## Authentication Requirements

While TapButton is designed for Droplit's feeless interactions, it can be integrated with Bitcoin authentication for hybrid experiences:

```tsx
import { 
  BitcoinAuthProvider, 
  BitcoinQueryProvider,
  TapButton,
  useBitcoinAuth
} from 'bigblocks';

function AuthenticatedTap() {
  const { isAuthenticated, address } = useBitcoinAuth();
  const [hybridMode, setHybridMode] = useState(false);

return (
    <div>
      <TapButton
        onSuccess={handleAuthenticatedTap}
        buttonText={isAuthenticated ? 'Authenticated Tap' : 'Anonymous Tap'}
        color={isAuthenticated ? 'green' : 'gray'}
      />
      
      {hybridMode && (
        <p>✨ BSV features now available!</p>
      )}
    </div>
  );
}

function App() {
  return (
    <BitcoinQueryProvider>
      <BitcoinAuthProvider config={{ apiUrl: '/api' }}>
        <AuthenticatedTap />
      </BitcoinAuthProvider>
    </BitcoinQueryProvider>
  );
}
```

## API Integration

TapButton works with Droplit's multi-tenant architecture:

### Droplit Tap Endpoints

```typescript
// Record tap interaction
POST /api/droplit/tap
{
  tenantId: string;
  userId?: string;
  tapCount: number;
  timestamp: string;
  metadata?: Record<string, any>;
}

Response:
{
  success: boolean;
  interaction: {
    id: string;
    tenantId: string;
    tapCount: number;
    rewards?: number;
    achievements?: string[];
  }
}

// Get tap statistics
GET /api/droplit/stats/:userId

Response:
{
  totalTaps: number;
  dailyTaps: number;
  streak: number;
  rewards: number;
  level: number;
  achievements: string[];
}
```

### Implementation Example

```typescript
// Backend API handler
app.post('/api/droplit/tap', async (req, res) => {
  const { tenantId, userId, tapCount, timestamp } = req.body;
  
  // Multi-tenant data isolation
  const tenant = await getTenant(tenantId);
  const storage = tenant.getStorage();
  
  // Record interaction without blockchain
  const interaction = await storage.recordInteraction({
    userId,
    type: 'tap',
    count: tapCount,
    timestamp,
    cost: 0 // No BSV cost
  });
  
  // Calculate rewards based on tenant config
  const rewards = tenant.config.rewardPerTap * tapCount;
  if (rewards > 0) {
    await storage.addRewards(userId, rewards);
  }
  
  // Check achievements
  const achievements = await checkAchievements(userId, tapCount);
  
  res.json({
    success: true,
    interaction: {
      id: interaction.id,
      tenantId,
      tapCount,
      rewards,
      achievements
    }
  });
});
```

## Features

* **Feeless Interactions**: Data transactions without BSV costs
* **Multi-Tenant Support**: Works with Droplit's tenant isolation
* **Engagement Tracking**: Built-in tap counting and analytics
* **Visual Feedback**: Loading states and success indicators
* **Customizable Appearance**: Multiple colors, sizes, and variants
* **Session Persistence**: Tap count maintained during session
* **Achievement System**: Easy integration with gamification
* **Rate Limiting**: Built-in support for interaction limits

## Error Handling

### Common Error Scenarios

```tsx
import { TapButton } from 'bigblocks';

export default function ErrorHandlingExample() {
  const [errorLog, setErrorLog] = useState<string[]>([]);

return (
    <div>
      <TapButton
        onError={handleTapError}
        onSuccess={(result) => console.log('Success:', result)}
      />
      
      {errorLog.length > 0 && (
        <div className="error-log">
          <h4>Error Log</h4>
          {errorLog.map((error, i) => (
            <div key={i} className="error-entry">{error}</div>
          ))}
        </div>
      )}
    </div>
  );
}
```

## Styling

TapButton uses Radix Themes styling system:

```tsx
// Color variants
<TapButton color="blue" />    // Default
<TapButton color="green" />   // Success/rewards
<TapButton color="orange" />  // Warning/special
<TapButton color="red" />     // Error/limit
<TapButton color="purple" />  // Premium/special
<TapButton color="gray" />    // Disabled/inactive

// Size variants
<TapButton size="1" />  // Extra small
<TapButton size="2" />  // Default
<TapButton size="3" />  // Large
<TapButton size="4" />  // Extra large

// Style variants
<TapButton variant="solid" />   // Default filled
<TapButton variant="soft" />    // Subtle background
<TapButton variant="outline" /> // Border only
<TapButton variant="ghost" />   // Minimal style

// Custom styling
<TapButton
  className="custom-tap-button"
  style={{ minWidth: '200px' }}
/>
```

## Performance Optimization

### Debounced Tapping

```tsx
import { TapButton } from 'bigblocks';
import { useCallback } from 'react';
import { debounce } from 'lodash';

export default function DebouncedTap() {
  const processTap = useCallback(
    debounce((result: TapResult) => {
      // Process tap after debounce period
      console.log('Processing tap:', result);
      analyticsTrack('tap', result);
    }, 500),
    []
  );

return (
    <TapButton
      onSuccess={(result) => {
        // Immediate UI feedback
        console.log('Tap registered');
        // Debounced processing
        processTap(result);
      }}
    />
  );
}
```

## Best Practices

1. **Use for High-Frequency Interactions**: Ideal for engagement tracking without blockchain costs
2. **Implement Rate Limiting**: Prevent abuse with client and server-side limits
3. **Add Visual Feedback**: Show users their progress with counters and achievements
4. **Consider Hybrid Models**: Combine with BSV transactions for premium features
5. **Track Analytics**: Monitor engagement patterns for optimization
6. **Handle Offline State**: Store taps locally and sync when online

## Troubleshooting

### Tap count not persisting

* Tap count is session-based by default
* Implement localStorage or API persistence for cross-session tracking

### Button not responding

* Check if component is disabled
* Verify onSuccess callback is defined
* Ensure no JavaScript errors in console

### Custom styling not applying

* TapButton uses Radix Themes
* Ensure styles don't conflict with Radix classes
* Use className prop for additional styles

### Rate limiting issues

* Clear localStorage for testing
* Verify server-side rate limit configuration
* Check timezone differences for reset times

## Related Components

* [DataPushButton](/docs/components/data-push-button) - Send data to Droplit
* [QuickDonateButton](/docs/components/quick-donate-button) - BSV-based donations
* [LoadingButton](/docs/components/loading-button) - Generic loading button
* [AuthButton](/docs/components/auth-button) - Bitcoin authentication

## API Reference

### TapButton Props

```typescript
interface TapButtonProps {
  onSuccess?: (result: TapResult) => void;
  onError?: (error: Error) => void;
  buttonText?: string;
  variant?: 'solid' | 'soft' | 'outline' | 'ghost';
  size?: '1' | '2' | '3' | '4';
  disabled?: boolean;
  className?: string;
  showTapCount?: boolean;
  color?: 'blue' | 'green' | 'orange' | 'red' | 'purple' | 'gray';
}

interface TapResult {
  message: string;
  timestamp: string;
  tapCount: number;
}
```

### Usage with Custom Hooks

```typescript
// Custom hook for tap management
function useTapManager() {
  const [taps, setTaps] = useState<TapResult[]>([]);
  const [stats, setStats] = useState({ total: 0, today: 0, streak: 0 });
  
  const recordTap = useCallback((result: TapResult) => {
    setTaps(prev => [...prev, result]);
    updateStats(result);
  }, []);
  
  return { taps, stats, recordTap };
}

// Usage
function TapManager() {
  const { taps, stats, recordTap } = useTapManager();
  
  return (
    <>
      <TapButton onSuccess={recordTap} />
      <div>Total: {stats.total} | Today: {stats.today}</div>
    </>
  );
}
```

# useBitcoinAuth
URL: /docs/components/hooks/use-bitcoin-auth

Core authentication hook for Bitcoin-based identity management

***

title: useBitcoinAuth
description: Core authentication hook for Bitcoin-based identity management
---------------------------------------------------------------------------

The primary hook for accessing Bitcoin authentication state, user data, and auth operations in BigBlocks applications. Provides comprehensive authentication management with Bitcoin-based identity where Bitcoin keypairs ARE the identity - no traditional usernames, emails, or passwords.

## Usage

```tsx
import { useBitcoinAuth } from 'bigblocks';

## Return Value

```typescript
interface UseBitcoinAuthReturn {
  // Authentication State
  user: AuthUser | null;                 // Current authenticated user
  isAuthenticated: boolean;              // Authentication status
  isLoading: boolean;                    // Loading state
  error: AuthError | null;               // Error state
  
  // Wallet Capabilities
  hasWalletCapabilities: boolean;        // Can make transactions
  balance: number | null;                // BSV balance
  address: string | null;                // Bitcoin address
  
  // Auth Operations
  signIn: (method?: AuthMethod) => Promise<void>;
  signOut: () => Promise<void>;
  refresh: () => Promise<void>;
  
  // Profile Management
  updateProfile: (data: ProfileUpdate) => Promise<void>;
  createProfile: (data: NewProfile) => Promise<void>;
  switchProfile: (bapId: string) => Promise<void>;
  
  // Backup Operations
  downloadBackup: () => Promise<void>;
  importBackup: (backup: string) => Promise<void>;
  linkOAuthProvider: (provider: OAuthProvider) => Promise<void>;
}

interface AuthUser {
  bapId: string;                         // BAP identity ID
  name: string;                          // Display name
  email?: string;                        // Email address
  avatar?: string;                       // Profile image URL
  publicKey: string;                     // Bitcoin public key
  address: string;                       // Bitcoin address
  createdAt: string;                     // Account creation date
  lastSeen: string;                      // Last activity
  verified: boolean;                     // Verification status
  reputation?: number;                   // Reputation score
  profiles: BapProfile[];                // Available profiles
}
```

## Authentication Methods

### Basic Bitcoin Authentication

The default authentication method uses Bitcoin signatures for cryptographic proof of identity:

```tsx
function BasicAuth() {
  const { signIn, signOut, isAuthenticated, user } = useBitcoinAuth();
  
  const handleSignIn = async () => {
    try {
      await signIn('credentials'); // Default Bitcoin signature auth
      toast.success('Signed in successfully!');
    } catch (error) {
      toast.error('Sign in failed: ' + error.message);
    }
  };
  
  return (
    <div className="auth-section">
      {isAuthenticated ? (
        <div className="user-info">
          <h3>Welcome {user.name}!</h3>
          <p>Address: {user.address}</p>
          <button onClick={signOut}>Sign Out</button>
        </div>
      ) : (
        <button onClick={handleSignIn}>
          Sign In with Bitcoin
        </button>
      )}
    </div>
  );
}
```

### OAuth Restoration

OAuth providers (Google, GitHub) serve as "anchors" to store encrypted backups, enabling cross-device access:

```tsx
function OAuthRestore() {
  const { signIn, isLoading, error } = useBitcoinAuth();
  
  const handleOAuthRestore = async (provider) => {
    try {
      await signIn('oauth', { provider });
      // Will trigger OAuth flow and restore from cloud backup
    } catch (error) {
      console.error('OAuth restore failed:', error);
    }
  };
  
  return (
    <div className="oauth-restore">
      <h3>Restore from Cloud Backup</h3>
      
      <button 
        onClick={() => handleOAuthRestore('google')}
        disabled={isLoading}
      >
        {isLoading ? 'Restoring...' : 'Restore from Google'}
      </button>
      
      <button 
        onClick={() => handleOAuthRestore('github')}
        disabled={isLoading}
      >
        {isLoading ? 'Restoring...' : 'Restore from GitHub'}
      </button>
      
      {error && (
        <ErrorDisplay error={error.message} />
      )}
    </div>
  );
}
```

## Profile Management

### Multiple Profiles

Users can create and switch between multiple profiles within the same identity:

```tsx
function ProfileSwitcher() {
  const {
    user,
    switchProfile,
    createProfile,
    updateProfile
  } = useBitcoinAuth();
  
  const [isCreating, setIsCreating] = useState(false);
  const [newProfileName, setNewProfileName] = useState('');
  
  const handleCreateProfile = async () => {
    if (!newProfileName.trim()) return;
    
    setIsCreating(true);
    try {
      await createProfile({
        name: newProfileName,
        bio: '',
        avatar: ''
      });
      setNewProfileName('');
      toast.success('Profile created successfully!');
    } catch (error) {
      toast.error('Failed to create profile');
    } finally {
      setIsCreating(false);
    }
  };
  
  return (
    <div className="profile-manager">
      <h3>Current Profile: {user.name}</h3>
      
      <div className="profile-list">
        {user.profiles.map(profile => (
          <div key={profile.bapId} className="profile-item">
            <BitcoinAvatar 
              src={profile.avatar}
              name={profile.name}
              size="small"
            />
            <span>{profile.name}</span>
            <button onClick={() => switchProfile(profile.bapId)}>
              Switch
            </button>
          </div>
        ))}
      </div>
      
      <div className="create-profile">
        <input 
          type="text"
          placeholder="New profile name"
          value={newProfileName}
          onChange={(e) => setNewProfileName(e.target.value)}
        />
        <button 
          onClick={handleCreateProfile}
          disabled={isCreating || !newProfileName.trim()}
        >
          {isCreating ? 'Creating...' : 'Create Profile'}
        </button>
      </div>
    </div>
  );
}
```

## Wallet Integration

### Balance and Transaction Capabilities

The hook provides wallet functionality when the user has imported a wallet-enabled backup:

```tsx
function WalletBalance() {
  const { hasWalletCapabilities, balance, address, refresh } = useBitcoinAuth();
  const [refreshing, setRefreshing] = useState(false);
  
  const handleRefresh = async () => {
    setRefreshing(true);
    try {
      await refresh();
    } finally {
      setRefreshing(false);
    }
  };
  
  if (!hasWalletCapabilities) {
    return (
      <div className="wallet-unavailable">
        <p>Wallet features not available</p>
        <p>Sign in with a wallet-enabled backup</p>
      </div>
    );
  }
  
  return (
    <div className="wallet-info">
      <div className="balance-section">
        <h4>Wallet Balance</h4>
        <SimpleTokenBalance 
          symbol="BSV"
          balance={balance || 0}
          showSymbol={true}
        />
        <button 
          onClick={handleRefresh}
          disabled={refreshing}
          className="refresh-button"
        >
          {refreshing ? '🔄' : '↻'} Refresh
        </button>
      </div>
      
      <div className="address-section">
        <h4>Bitcoin Address</h4>
        <div className="address-display">
          <code>{address}</code>
          <button onClick={() => navigator.clipboard.writeText(address)}>
            Copy
          </button>
        </div>
      </div>
    </div>
  );
}
```

## Backup Management

### Download and Cloud Backup

Secure backup management with local download and OAuth provider linking:

```tsx
function BackupManager() {
  const { downloadBackup, linkOAuthProvider } = useBitcoinAuth();
  const [downloading, setDownloading] = useState(false);
  const [linking, setLinking] = useState(false);
  
  const handleDownloadBackup = async () => {
    setDownloading(true);
    try {
      await downloadBackup();
      toast.success('Backup downloaded successfully!');
    } catch (error) {
      toast.error('Backup download failed');
    } finally {
      setDownloading(false);
    }
  };
  
  const handleLinkProvider = async (provider) => {
    setLinking(true);
    try {
      await linkOAuthProvider(provider);
      toast.success(`${provider} linked successfully!`);
    } catch (error) {
      toast.error(`Failed to link ${provider}`);
    } finally {
      setLinking(false);
    }
  };
  
  return (
    <div className="backup-manager">
      <h3>Backup & Security</h3>
      
      <div className="backup-section">
        <h4>Local Backup</h4>
        <p>Download an encrypted backup file</p>
        <LoadingButton 
          onClick={handleDownloadBackup}
          loading={downloading}
        >
          Download Backup
        </LoadingButton>
      </div>
      
      <div className="cloud-backup-section">
        <h4>Cloud Backup</h4>
        <p>Link OAuth providers for cloud backup access</p>
        
        <div className="provider-buttons">
          <LoadingButton 
            onClick={() => handleLinkProvider('google')}
            loading={linking}
            variant="outline"
          >
            Link Google
          </LoadingButton>
          
          <LoadingButton 
            onClick={() => handleLinkProvider('github')}
            loading={linking}
            variant="outline"
          >
            Link GitHub
          </LoadingButton>
        </div>
      </div>
    </div>
  );
}
```

## Error Handling

### Authentication Error Recovery

Comprehensive error handling with recovery actions:

```tsx
function AuthErrorHandler() {
  const { error, signIn, refresh } = useBitcoinAuth();
  
  const getErrorMessage = (error) => {
    switch (error?.code) {
      case 'INVALID_SIGNATURE':
        return 'Invalid Bitcoin signature. Please try again.';
      case 'EXPIRED_SESSION':
        return 'Your session has expired. Please sign in again.';
      case 'NETWORK_ERROR':
        return 'Network error. Please check your connection.';
      case 'BACKUP_CORRUPTED':
        return 'Backup file appears to be corrupted.';
      default:
        return error?.message || 'An unexpected error occurred.';
    }
  };
  
  const getRecoveryAction = (error) => {
    switch (error?.code) {
      case 'EXPIRED_SESSION':
        return () => signIn();
      case 'NETWORK_ERROR':
        return () => refresh();
      default:
        return null;
    }
  };
  
  if (!error) return null;
  
  const recoveryAction = getRecoveryAction(error);
  
  return (
    <div className="auth-error">
      <ErrorDisplay error={getErrorMessage(error)} />
      
      {recoveryAction && (
        <LoadingButton onClick={recoveryAction}>
          Try Again
        </LoadingButton>
      )}
    </div>
  );
}
```

## Signature Generation

### Bitcoin Message Signing

The hook handles Bitcoin signature generation internally for authentication:

```tsx
function SignatureExample() {
  const { user, signIn } = useBitcoinAuth();
  
  // The hook internally handles:
  // 1. Generate challenge message with timestamp
  // 2. Sign with private key using Bitcoin Signed Message (BSM)
  // 3. Verify signature on server
  // 4. Create session with JWT token
  
  // Example of what happens internally:
  // const message = `Sign in to BigBlocks\nTimestamp: ${Date.now()}`;
  // const signature = await bitcoinSign(message, privateKey);
  // const response = await api.authenticate({ message, signature, publicKey });
  
  return (
    <div>
      <p>Authentication uses Bitcoin signatures internally</p>
      <p>No passwords or usernames needed!</p>
      <button onClick={() => signIn()}>
        Sign In (Generates Bitcoin Signature)
      </button>
    </div>
  );
}
```

## Session Management

### Automatic Session Handling

The hook manages session tokens and automatic refresh:

```tsx
function SessionInfo() {
  const { user, refresh, isAuthenticated } = useBitcoinAuth();
  const [sessionInfo, setSessionInfo] = useState(null);
  
  useEffect(() => {
    if (isAuthenticated) {
      // Session is automatically managed by the hook
      // JWT tokens are refreshed before expiry
      // Session data is stored in secure HTTP-only cookies
      
      const checkSession = async () => {
        try {
          const response = await fetch('/api/auth/session');
          const data = await response.json();
          setSessionInfo(data);
        } catch (error) {
          console.error('Session check failed:', error);
        }
      };
      
      checkSession();
    }
  }, [isAuthenticated]);
  
  return (
    <div className="session-info">
      <h3>Session Management</h3>
      {sessionInfo && (
        <div>
          <p>Session ID: {sessionInfo.id}</p>
          <p>Expires: {new Date(sessionInfo.expires).toLocaleString()}</p>
          <p>Auto-refresh: Enabled</p>
        </div>
      )}
      <button onClick={refresh}>
        Manual Refresh
      </button>
    </div>
  );
}
```

## Best Practices

1. **Check Authentication State**: Always check `isAuthenticated` before accessing user data
2. **Handle Loading States**: Show loading indicators during auth operations
3. **Error Boundaries**: Wrap components using this hook in error boundaries
4. **Wallet Capabilities**: Check `hasWalletCapabilities` before wallet operations
5. **Profile Switching**: Update UI state when users switch profiles
6. **Session Persistence**: The hook handles session persistence automatically
7. **Secure Storage**: Private keys are always encrypted before storage

## Technical Details

* **React Query Integration**: Uses React Query for caching and real-time updates
* **Local Storage**: Manages encrypted local storage for session persistence
* **WebSocket Support**: Real-time updates for balance and profile changes
* **Signature Validation**: All operations validated with Bitcoin signatures
* **Session Management**: Automatic session refresh and token management
* **Time-bound Tokens**: 10-minute validity window prevents replay attacks

## Security Considerations

* Private keys never exposed through the hook interface
* All operations require valid Bitcoin signatures
* Session tokens have limited lifetime with automatic refresh
* Backup operations are always encrypted
* OAuth linking requires existing authentication
* Signatures include timestamps to prevent replay attacks

## Requirements

* Must be used within `BitcoinAuthProvider` context
* Requires `BitcoinQueryProvider` for caching
* Network connection required for authentication operations
* Local storage available for session persistence
* Modern browser with Web Crypto API support

## Example: Complete Authentication Flow

```tsx
function CompleteAuthExample() {
  const {
    user,
    isAuthenticated,
    isLoading,
    error,
    signIn,
    signOut,
    downloadBackup,
    hasWalletCapabilities,
    balance,
    address
  } = useBitcoinAuth();
  
  if (isLoading) {
    return <LoadingSpinner />;
  }
  
  if (error) {
    return <AuthErrorHandler error={error} />;
  }
  
  if (!isAuthenticated) {
    return (
      <AuthLayout>
        <LoginForm onSuccess={() => console.log('Signed in!')} />
      </AuthLayout>
    );
  }
  
  return (
    <div className="authenticated-app">
      <header>
        <h1>Welcome, {user.name}!</h1>
        <ProfileDropdownMenu />
      </header>
      
      <main>
        <section className="identity-info">
          <h2>Bitcoin Identity</h2>
          <p>BAP ID: {user.bapId}</p>
          <p>Public Key: {user.publicKey}</p>
          <p>Address: {address}</p>
        </section>
        
        {hasWalletCapabilities && (
          <section className="wallet-info">
            <h2>Wallet</h2>
            <p>Balance: {balance} BSV</p>
            <SendBSVButton />
          </section>
        )}
        
        <section className="actions">
          <button onClick={downloadBackup}>
            Download Backup
          </button>
          <button onClick={signOut}>
            Sign Out
          </button>
        </section>
      </main>
    </div>
  );
}
```

## Related Components

* [AuthButton](/docs/components/auth-button) - Pre-built authentication button
* [LoginForm](/docs/components/login-form) - Complete login form component
* [ProfileEditor](/docs/components/profile-editor) - Profile management UI
* [BackupDownload](/docs/components/backup-download) - Backup management component
* [BitcoinAuthProvider](/docs/components/bitcoin-auth-provider) - Required provider component

# useSocial
URL: /docs/components/hooks/use-social

Comprehensive hook combining all social operations (posts, likes, follows, friends) into a single interface

***

title: useSocial
description: Comprehensive hook combining all social operations (posts, likes, follows, friends) into a single interface
category: social
----------------

A powerful hook that combines all social operations into a single, unified interface. It provides methods for creating posts, managing likes, following users, and handling friend relationships on the Bitcoin blockchain.

[View Hook Demo →](/component-preview/use-social)

## Installation

```bash
npx bigblocks add use-social
```

## Import

```typescript
import { useSocial } from 'bigblocks';
```

## Return Value

The hook returns an object with the following properties:

### Post Operations

| Method            | Type                                                   | Description                     |
| ----------------- | ------------------------------------------------------ | ------------------------------- |
| `createPost`      | `(data: PostMutationData) => void`                     | Create a new post               |
| `createPostAsync` | `(data: PostMutationData) => Promise<BroadcastResult>` | Async version returning promise |

### Follow Operations

| Method              | Type                                                     | Description     |
| ------------------- | -------------------------------------------------------- | --------------- |
| `followUser`        | `(data: FollowMutationData) => void`                     | Follow a user   |
| `followUserAsync`   | `(data: FollowMutationData) => Promise<BroadcastResult>` | Async version   |
| `unfollowUser`      | `(data: FollowMutationData) => void`                     | Unfollow a user |
| `unfollowUserAsync` | `(data: FollowMutationData) => Promise<BroadcastResult>` | Async version   |

### Like Operations

| Method            | Type                                                   | Description   |
| ----------------- | ------------------------------------------------------ | ------------- |
| `likePost`        | `(data: LikeMutationData) => void`                     | Like a post   |
| `likePostAsync`   | `(data: LikeMutationData) => Promise<BroadcastResult>` | Async version |
| `unlikePost`      | `(data: LikeMutationData) => void`                     | Unlike a post |
| `unlikePostAsync` | `(data: LikeMutationData) => Promise<BroadcastResult>` | Async version |

### Friend Operations

| Method                 | Type                      | Description              |
| ---------------------- | ------------------------- | ------------------------ |
| `acceptFriendRequest`  | `(idKey: string) => void` | Accept a friend request  |
| `declineFriendRequest` | `(idKey: string) => void` | Decline a friend request |

### State Management

| Property    | Type                  | Description                |
| ----------- | --------------------- | -------------------------- |
| `isLoading` | `boolean`             | Any operation is loading   |
| `isError`   | `boolean`             | Any operation has error    |
| `isSuccess` | `boolean`             | Last operation succeeded   |
| `hasError`  | `boolean`             | Boolean error check        |
| `error`     | `SocialError \| null` | Error object if any        |
| `reset`     | `() => void`          | Reset all operation states |

### Data

| Property         | Type            | Description                      |
| ---------------- | --------------- | -------------------------------- |
| `friends`        | `Friend[]`      | Array of friend objects          |
| `friendRequests` | `BapIdentity[]` | Array of pending friend requests |

## Type Definitions

### PostMutationData

```typescript
interface PostMutationData {
  content: string;
  contentType?: 'text/plain' | 'text/markdown';
  app?: string;
}
```

### FollowMutationData

```typescript
interface FollowMutationData {
  idKey: string; // BAP identity key
}
```

### LikeMutationData

```typescript
interface LikeMutationData {
  txid: string;
  emoji?: string; // Default: '👍'
}
```

### BroadcastResult

```typescript
interface BroadcastResult {
  success: boolean;
  txid?: string;
  rawTx?: string;
  error?: string;
  fee?: number;
}
```

### SocialError

```typescript
interface SocialError {
  code: SocialErrorCode;
  message: string;
  details?: Error | Record<string, unknown>;
}

## Basic Usage

```tsx
import { useSocial } from 'bigblocks';

function SocialDashboard() {
  const {
    createPost,
    likePost,
    followUser,
    friends,
    isLoading,
    error
  } = useSocial();

const handlePost = () => {
    createPost({
      content: "Hello Bitcoin world!",
      contentType: 'text/plain'
    });
  };

return (
    <div>
      <button 
        onClick={handlePost} 
        disabled={isLoading}
      >
        Create Post
      </button>
      
      {error && <div>Error: {error.message}</div>}
      
      <div>Friends: {friends.length}</div>
    </div>
  );
}
```

## Advanced Usage

### Complete Social Implementation

```tsx
import { useSocial } from 'bigblocks';

function SocialHub() {
  const {
    createPostAsync,
    likePost,
    unlikePost,
    followUserAsync,
    unfollowUserAsync,
    acceptFriendRequest,
    declineFriendRequest,
    friends,
    friendRequests,
    isLoading,
    error,
    reset
  } = useSocial();

const [postContent, setPostContent] = useState('');
  const [followingStatus, setFollowingStatus] = useState<Map<string, boolean>>(new Map());

// Handle post creation with async/await
  const handleCreatePost = async () => {
    try {
      const result = await createPostAsync({
        content: postContent,
        contentType: 'text/markdown',
        app: 'my-social-app'
      });
      
      if (result.success) {
        console.log('Post created:', result.txid);
        setPostContent('');
        // Show success notification
      }
    } catch (err) {
      console.error('Failed to create post:', err);
    }
  };

// Toggle follow/unfollow
  const toggleFollow = async (idKey: string) => {
    const isFollowing = followingStatus.get(idKey);
    
    try {
      if (isFollowing) {
        await unfollowUserAsync({ idKey });
        setFollowingStatus(prev => new Map(prev).set(idKey, false));
      } else {
        await followUserAsync({ idKey });
        setFollowingStatus(prev => new Map(prev).set(idKey, true));
      }
    } catch (err) {
      console.error('Follow operation failed:', err);
    }
  };

// Handle friend requests
  const handleFriendRequest = (requestId: string, accept: boolean) => {
    if (accept) {
      acceptFriendRequest(requestId);
    } else {
      declineFriendRequest(requestId);
    }
  };

// Auto-clear errors after 5 seconds
  useEffect(() => {
    if (error) {
      const timer = setTimeout(reset, 5000);
      return () => clearTimeout(timer);
    }
  }, [error, reset]);

return (
    <div className="space-y-4">
      {/* Post Creation */}
      <div>
        <textarea
          value={postContent}
          onChange={(e) => setPostContent(e.target.value)}
          placeholder="What's on your mind?"
          maxLength={217}
          disabled={isLoading}
        />
        <button
          onClick={handleCreatePost}
          disabled={isLoading || !postContent.trim()}
        >
          {isLoading ? 'Posting...' : 'Post'}
        </button>
      </div>

{/* Friend Requests */}
      {friendRequests.length > 0 && (
        <div>
          <h3>Friend Requests ({friendRequests.length})</h3>
          {friendRequests.map(request => (
            <div key={request.idKey}>
              <span>{request.alternateName || request.idKey}</span>
              <button
                onClick={() => handleFriendRequest(request.idKey, true)}
                disabled={isLoading}
              >
                Accept
              </button>
              <button
                onClick={() => handleFriendRequest(request.idKey, false)}
                disabled={isLoading}
              >
                Decline
              </button>
            </div>
          ))}
        </div>
      )}

{/* Friends List */}
      <div>
        <h3>Friends ({friends.length})</h3>
        {friends.map(friend => (
          <div key={friend.idKey}>
            {friend.alternateName || friend.idKey}
          </div>
        ))}
      </div>

{/* Error Display */}
      {error && (
        <div className="error-banner">
          {error.code}: {error.message}
          <button onClick={reset}>Dismiss</button>
        </div>
      )}
    </div>
  );
}
```

## Common Patterns

### Social Feed with Actions

```tsx
function SocialFeed({ posts }) {
  const { likePost, unlikePost, followUser } = useSocial();
  const [likedPosts, setLikedPosts] = useState<Set<string>>(new Set());

return (
    <div>
      {posts.map(post => (
        <article key={post.txid}>
          <header>
            <span>{post.author.name}</span>
            <button
              onClick={() => followUser({ idKey: post.author.idKey })}
            >
              Follow
            </button>
          </header>
          
          <p>{post.content}</p>
          
          <footer>
            <button
              onClick={() => handleLike(post.txid)}
              className={likedPosts.has(post.txid) ? 'liked' : ''}
            >
              {likedPosts.has(post.txid) ? '❤️' : '🤍'} Like
            </button>
          </footer>
        </article>
      ))}
    </div>
  );
}
```

### Error Handling with Retry

```tsx
function RobustSocialActions() {
  const { createPostAsync, error, reset } = useSocial();
  const [retryCount, setRetryCount] = useState(0);
  const maxRetries = 3;

return (
    <div>
      {error && (
        <div>
          Error: {error.message}
          {retryCount > 0 && ` (Retry ${retryCount}/${maxRetries})`}
        </div>
      )}
      {/* Your UI here */}
    </div>
  );
}
```

### Optimistic UI Updates

```tsx
function OptimisticSocialFeed() {
  const { likePostAsync } = useSocial();
  const [optimisticLikes, setOptimisticLikes] = useState<Map<string, boolean>>(new Map());

return (
    <div>
      {/* Show likes including optimistic updates */}
    </div>
  );
}
```

## Authentication Requirements

The `useSocial` hook requires proper authentication context:

```tsx
import { 
  BitcoinAuthProvider, 
  BitcoinQueryProvider,
  BitcoinThemeProvider 
} from 'bigblocks';

function App() {
  return (
    <BitcoinQueryProvider>
      <BitcoinAuthProvider config={{ apiUrl: '/api' }}>
        <BitcoinThemeProvider>
          <YourComponent />
        </BitcoinThemeProvider>
      </BitcoinAuthProvider>
    </BitcoinQueryProvider>
  );
}
```

## API Integration

### Required Endpoints

The hook expects the following API endpoints:

* `POST /api/social/post` - Create posts
* `POST /api/social/like` - Like posts
* `POST /api/social/unlike` - Unlike posts
* `POST /api/social/follow` - Follow users
* `POST /api/social/unfollow` - Unfollow users
* `POST /api/social/friend/accept` - Accept friend requests
* `POST /api/social/friend/decline` - Decline friend requests
* `GET /api/social/friends` - Get friends list

### Bitcoin Transaction Flow

1. User initiates social action
2. Hook creates and signs Bitcoin transaction
3. Transaction broadcasted to BSV network
4. API returns transaction ID
5. UI updates with result

## Troubleshooting

### INSUFFICIENT\_FUNDS Error

The user's wallet doesn't have enough BSV for the transaction fee:

```tsx
if (error?.code === 'INSUFFICIENT_FUNDS') {
  return <div>Please add funds to perform social actions</div>;
}
```

### RATE\_LIMITED Error

Too many requests in a short time:

```tsx
if (error?.code === 'RATE_LIMITED') {
  return <div>Please wait before performing more actions</div>;
}
```

### CONTENT\_TOO\_LONG Error

Posts are limited to 217 characters on-chain:

```tsx
const MAX_POST_LENGTH = 217;

if (postContent.length > MAX_POST_LENGTH) {
  return <div>Post is too long ({postContent.length}/{MAX_POST_LENGTH})</div>;
}
```

### Network Errors

Handle network connectivity issues:

```tsx
if (error?.code === 'NETWORK_ERROR') {
  return (
    <div>
      Network error. Check your connection.
      <button onClick={reset}>Retry</button>
    </div>
  );
}
```

## Best Practices

1. **Error Boundaries**: Wrap social components in error boundaries
2. **Loading States**: Always show loading indicators during operations
3. **Optimistic Updates**: Update UI immediately for better UX
4. **Batch Operations**: Use async methods for multiple operations
5. **Content Validation**: Validate content length and format before posting
6. **Rate Limiting**: Implement client-side rate limiting
7. **State Persistence**: Consider persisting social state across sessions

## Related Components

* [PostButton](/docs/components/post-button) - Simple post creation button
* [LikeButton](/docs/components/like-button) - Like/unlike button
* [FollowButton](/docs/components/follow-button) - Follow/unfollow button
* [SocialFeed](/docs/components/social-feed) - Complete social feed
* [FriendsDialog](/docs/components/friends-dialog) - Friend management UI

## API Reference

### Hook Configuration

While `useSocial` doesn't accept direct configuration, it uses the `BitcoinAuthProvider` config:

```tsx
<BitcoinAuthProvider config={{
  apiUrl: '/api',
  network: 'mainnet', // or 'testnet'
  broadcaster: 'https://api.whatsonchain.com/v1/bsv/main/tx/raw'
}}>
```

### Social Protocol Standards

The hook implements standard Bitcoin social protocols:

* **B Protocol**: For content storage
* **MAP Protocol**: For metadata
* **BAP Protocol**: For identity
* **AIP Protocol**: For authentication signatures

# BSV21MintButton
URL: /docs/components/inscriptions/bsv21-mint-button

Deploy BSV-21 NFT tokens with icon validation and on-chain deployment

***

title: BSV21MintButton
description: Deploy BSV-21 NFT tokens with icon validation and on-chain deployment
categories: \[inscriptions, nft, blockchain, tokens]
providers: \[BitcoinAuthProvider]
---------------------------------

import { ComponentBadges } from '@/components/docs/ComponentBadges';
import { BSV21MintButtonDemo } from '@/components/docs/demos/BSV21MintButtonDemo';

Deploy BSV-21 NFT tokens with icon inscriptions. BSV-21 is the NFT standard that requires an icon image, supporting square images up to 400x400px and 100KB in size.

## Demo

## API Reference

This component extends the [Button](https://www.radix-ui.com/primitives/docs/components/button) and [Dialog](https://www.radix-ui.com/primitives/docs/components/dialog) primitives from Radix and uses [DropZone](/docs/components/dropzone) for icon file upload.

## Installation

```bash
npx bigblocks add bsv21-mint-button
```

## Import

```typescript
import { BSV21MintButton } from 'bigblocks';
```

## Props

| Prop            | Type                                        | Required | Default                     | Description                          |
| --------------- | ------------------------------------------- | -------- | --------------------------- | ------------------------------------ |
| token           | `Partial<BSV21Token>`                       | No       | -                           | Pre-filled token data                |
| buttonText      | `string`                                    | No       | `"Deploy BSV-21 Token"`     | Button text                          |
| dialogTitle     | `string`                                    | No       | `"Deploy BSV-21 NFT Token"` | Dialog title                         |
| variant         | `'solid' \| 'soft' \| 'outline' \| 'ghost'` | No       | `'solid'`                   | Button variant                       |
| size            | `'1' \| '2' \| '3' \| '4'`                  | No       | `'2'`                       | Button size                          |
| color           | `'blue' \| 'green' \| 'red' \| 'gray'`      | No       | `'blue'`                    | Button color                         |
| className       | `string`                                    | No       | -                           | Custom CSS classes                   |
| disabled        | `boolean`                                   | No       | `false`                     | Whether button is disabled           |
| showFeeEstimate | `boolean`                                   | No       | `false`                     | Show transaction fee estimate        |
| onSuccess       | `(txid: string, token: BSV21Token) => void` | No       | -                           | Success callback with transaction ID |
| onError         | `(error: Error) => void`                    | No       | -                           | Error callback                       |

## Types

### BSV21Token

```typescript
interface BSV21Token {
  /** Token symbol/ticker */
  symbol: string;
  /** Icon image file */
  icon: File | null;
  /** Maximum supply */
  maxSupply: string;
  /** Number of decimal places */
  decimals?: number;
}
```

## Basic Usage

```tsx
import { BSV21MintButton } from 'bigblocks';

export default function TokenCreator() {
  const handleSuccess = (txid: string, token: BSV21Token) => {
    console.log('Token deployed!', { txid, token });
    // Redirect or show success message
  };

const handleError = (error: Error) => {
    console.error('Deployment failed:', error);
    // Show error message to user
  };

return (
    <div className="p-6">
      <h2>Create Your NFT Token</h2>
      <BSV21MintButton
        onSuccess={handleSuccess}
        onError={handleError}
        showFeeEstimate={true}
      />
    </div>
  );
}
```

## Advanced Usage

### Pre-filled Token Data

```tsx
import { BSV21MintButton } from 'bigblocks';

export default function GameTokens() {
  const gameTokenDefaults = {
    symbol: 'HERO',
    maxSupply: '1000',
    decimals: 0
  };

return (
    <BSV21MintButton
      token={gameTokenDefaults}
      buttonText="Create Game Token"
      dialogTitle="Deploy Game Hero Token"
      color="green"
      onSuccess={(txid, token) => {
        // Save to game database
        saveGameToken({ txid, ...token });
        
        // Navigate to token management
        router.push(`/game/tokens/${txid}`);
      }}
    />
  );
}
```

### Collection Integration

```tsx
import { BSV21MintButton } from 'bigblocks';
import { useState } from 'react';

export default function CollectionManager() {
  const [deployedTokens, setDeployedTokens] = useState([]);

return (
    <div className="space-y-6">
      <div className="grid grid-cols-1 md:grid-cols-2 gap-4">
        <BSV21MintButton
          token={{ symbol: 'ART', decimals: 0 }}
          buttonText="Deploy Art Token"
          onSuccess={handleTokenDeployment}
        />
        
        <BSV21MintButton
          token={{ symbol: 'MUSIC', decimals: 0 }}
          buttonText="Deploy Music Token"
          onSuccess={handleTokenDeployment}
        />
      </div>
      
      {deployedTokens.length > 0 && (
        <div>
          <h3>Deployed Tokens</h3>
          <ul>
            {deployedTokens.map(token => (
              <li key={token.txid}>
                {token.symbol} - Supply: {token.maxSupply}
              </li>
            ))}
          </ul>
        </div>
      )}
    </div>
  );
}
```

## Icon Requirements

### Image Validation

* **Format**: PNG, JPEG, GIF, or WebP
* **Size**: Maximum 100KB file size
* **Dimensions**: Must be square (same width and height)
* **Maximum Resolution**: 400x400 pixels

### Best Practices

```tsx
// Example icon preparation
const prepareIcon = async (file: File): Promise<boolean> => {
  // Check file type
  const validTypes = ['image/png', 'image/jpeg', 'image/gif', 'image/webp'];
  if (!validTypes.includes(file.type)) {
    throw new Error('Invalid image type');
  }
  
  // Check file size
  if (file.size > 100 * 1024) {
    throw new Error('Image too large (max 100KB)');
  }
  
  // Check dimensions
  return new Promise((resolve, reject) => {
    const img = new Image();
    img.onload = () => {
      if (img.width !== img.height) {
        reject(new Error('Image must be square'));
      } else if (img.width > 400) {
        reject(new Error('Image too large (max 400x400)'));
      } else {
        resolve(true);
      }
    };
    img.src = URL.createObjectURL(file);
  });
};
```

## BSV-21 Standard

BSV-21 tokens are NFTs on Bitcoin SV that include:

* Unique symbol/ticker
* Icon inscription on-chain
* Fixed or unlimited supply
* Decimal places for fractional ownership
* Ordinal-based ownership tracking

### Token Economics

```typescript
// Example token configurations
const limitedEdition = {
  symbol: 'RARE',
  maxSupply: '100',    // Limited to 100 tokens
  decimals: 0          // Whole tokens only
};

const fractionalArt = {
  symbol: 'ARTPIECE',
  maxSupply: '1',      // Single piece
  decimals: 8          // Allows fractional ownership
};

const gameItems = {
  symbol: 'SWORD',
  maxSupply: '10000',  // Game economy
  decimals: 0          // Discrete items
};
```

## Error Handling

Common error scenarios:

* Wallet not connected
* Insufficient UTXOs
* Invalid icon format/size
* Network connectivity issues
* Transaction broadcast failures

```tsx
const handleError = (error: Error) => {
  switch (error.message) {
    case 'Wallet not connected':
      // Prompt user to connect wallet
      setShowConnectDialog(true);
      break;
    case 'No UTXOs available':
      // Suggest funding wallet
      setShowFundingDialog(true);
      break;
    default:
      // Generic error handling
      toast.error(`Deployment failed: ${error.message}`);
  }
};
```

## Integration Examples

### Marketplace Integration

```tsx
import { BSV21MintButton } from 'bigblocks';

export default function MarketplaceCreator() {
  return (
    <BSV21MintButton
      onSuccess={(txid, token) => {
        // Auto-list on marketplace
        createMarketplaceListing({
          tokenTxid: txid,
          symbol: token.symbol,
          price: 1000, // sats
          description: `BSV-21 token: ${token.symbol}`
        });
      }}
    />
  );
}
```

### Social Media Integration

```tsx
const handleTokenCreation = (txid: string, token: BSV21Token) => {
  // Share on social media
  const message = `🎨 Just created ${token.symbol} NFT token on Bitcoin SV! Supply: ${token.maxSupply}`;
  
  // Post to social feed
  socialPost({
    message,
    attachments: [{ type: 'token', txid }]
  });
};
```

## Related Components

* [CollectionMintButton](/docs/components/collection-mint-button) - Deploy NFT collections
* [BSV20MintButton](/docs/components/bsv20-mint-button) - Deploy fungible tokens
* [InscriptionButton](/docs/components/inscription-button) - General inscription creation

## Best Practices

### Token Symbol Guidelines

* Use uppercase letters (automatically converted)
* Keep symbols short and memorable (1-10 characters)
* Avoid using existing popular symbols
* Consider namespace conflicts

### Icon Design

* Use high contrast for visibility at small sizes
* Avoid complex details that don't scale down well
* Consider using SVG format for crisp scaling
* Test icon visibility on different backgrounds

### Supply Economics

```tsx
// Consider your token's use case
const collectible = { maxSupply: '1' };        // Unique item
const limitedSeries = { maxSupply: '100' };    // Limited edition
const gameAsset = { maxSupply: '10000' };      // Game economy
const fractional = { maxSupply: '1', decimals: 8 }; // Shared ownership
```

# CollectionMintButton
URL: /docs/components/inscriptions/collection-mint-button

Create NFT collections with metadata, traits, rarities, and royalty configurations

***

title: CollectionMintButton
description: Create NFT collections with metadata, traits, rarities, and royalty configurations
categories: \[inscriptions, nft, collections, blockchain]
providers: \[BitcoinAuthProvider]
---------------------------------

import { ComponentBadges } from '@/components/docs/ComponentBadges';
import { CollectionMintButtonDemo } from '@/components/docs/demos/CollectionMintButtonDemo';

Create comprehensive NFT collections with metadata, traits, rarities, and royalty configurations. Collections are parent inscriptions that define the structure and attributes for collection items.

## Demo

## API Reference

## Installation

```bash
npx bigblocks add collection-mint-button
```

## Import

```typescript
import { CollectionMintButton } from 'bigblocks';
```

## Props

| Prop        | Type                                                 | Required | Default                   | Description                          |
| ----------- | ---------------------------------------------------- | -------- | ------------------------- | ------------------------------------ |
| collection  | `Partial<CollectionData>`                            | No       | -                         | Pre-filled collection data           |
| buttonText  | `string`                                             | No       | `"Create Collection"`     | Button text                          |
| dialogTitle | `string`                                             | No       | `"Create NFT Collection"` | Dialog title                         |
| variant     | `'solid' \| 'soft' \| 'outline' \| 'ghost'`          | No       | `'solid'`                 | Button variant                       |
| size        | `'1' \| '2' \| '3' \| '4'`                           | No       | `'2'`                     | Button size                          |
| color       | `'blue' \| 'green' \| 'red' \| 'gray'`               | No       | `'blue'`                  | Button color                         |
| className   | `string`                                             | No       | -                         | Custom CSS classes                   |
| disabled    | `boolean`                                            | No       | `false`                   | Whether button is disabled           |
| onSuccess   | `(txid: string, collection: CollectionData) => void` | No       | -                         | Success callback with transaction ID |
| onError     | `(error: Error) => void`                             | No       | -                         | Error callback                       |

## Types

### CollectionData

```typescript
interface CollectionData {
  // Basic info
  name: string;
  description: string;
  quantity?: number;
  // Cover image
  coverImage: File | null;
  // Rarities
  rarities: CollectionRarity[];
  // Traits
  traits: CollectionTraits;
  // Royalties
  royalties: CollectionRoyalty[];
}
```

### CollectionRarity

```typescript
interface CollectionRarity {
  label: string;
  percentage: string; // Decimal format: "0.5000" = 50%
  items?: string; // Number of items with this rarity
}
```

### CollectionRoyalty

```typescript
interface CollectionRoyalty {
  type: RoytaltyType;
  destination: string;
  percentage: string; // Decimal format: "0.0100" = 1%
}
```

## Basic Usage

```tsx
import { CollectionMintButton } from 'bigblocks';

export default function CollectionCreator() {
  const handleSuccess = (txid: string, collection: CollectionData) => {
    console.log('Collection created!', { txid, collection });
    // Redirect to collection management
    router.push(`/collections/${txid}`);
  };

const handleError = (error: Error) => {
    console.error('Collection creation failed:', error);
    // Show error message to user
  };

return (
    <div className="p-6">
      <h2>Create Your NFT Collection</h2>
      <CollectionMintButton
        onSuccess={handleSuccess}
        onError={handleError}
      />
    </div>
  );
}
```

## Advanced Usage

### Pre-configured Collection

```tsx
import { CollectionMintButton } from 'bigblocks';

export default function GameCollections() {
  const gameCollectionDefaults = {
    name: 'Hero Cards',
    description: 'Collectible hero cards for the fantasy game',
    quantity: 10000,
    rarities: [
      { label: 'Common', percentage: '0.6000' },
      { label: 'Rare', percentage: '0.3000' },
      { label: 'Epic', percentage: '0.0900' },
      { label: 'Legendary', percentage: '0.0100' }
    ],
    traits: {
      'Class': {
        values: {
          'Warrior': { rarity: '0.2500' },
          'Mage': { rarity: '0.2500' },
          'Archer': { rarity: '0.2500' },
          'Assassin': { rarity: '0.2500' }
        }
      },
      'Element': {
        values: {
          'Fire': { rarity: '0.2000' },
          'Water': { rarity: '0.2000' },
          'Earth': { rarity: '0.2000' },
          'Air': { rarity: '0.2000' },
          'Light': { rarity: '0.1000' },
          'Dark': { rarity: '0.1000' }
        }
      }
    }
  };

return (
    <CollectionMintButton
      collection={gameCollectionDefaults}
      buttonText="Create Game Collection"
      dialogTitle="Deploy Hero Card Collection"
      color="green"
      onSuccess={(txid, collection) => {
        // Save to game database
        saveGameCollection({ txid, ...collection });
        
        // Set up minting pipeline
        initializeCollectionMinting(txid);
      }}
    />
  );
}
```

### Marketplace Integration

```tsx
import { CollectionMintButton } from 'bigblocks';
import { useState } from 'react';

export default function MarketplaceCollections() {
  const [collections, setCollections] = useState([]);

return (
    <div className="space-y-6">
      <CollectionMintButton
        onSuccess={handleCollectionCreation}
        buttonText="Launch New Collection"
      />
      
      {collections.length > 0 && (
        <div>
          <h3>Your Collections</h3>
          <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
            {collections.map(collection => (
              <div key={collection.txid} className="border rounded-lg p-4">
                <h4 className="font-semibold">{collection.name}</h4>
                <p className="text-sm text-gray-600">{collection.description}</p>
                <div className="mt-2 flex justify-between">
                  <span className="text-xs">Items: {collection.quantity}</span>
                  <span className="text-xs">Traits: {Object.keys(collection.traits).length}</span>
                </div>
              </div>
            ))}
          </div>
        </div>
      )}
    </div>
  );
}
```

## Collection Creation Steps

The component guides users through a 5-step process:

### 1. Basic Information

* Collection name and description
* Quantity (optional for unlimited)
* Cover image upload (square, max 1MB, max 2048x2048px)

### 2. Rarity Configuration

* Define rarity tiers with labels and percentages
* Percentage or item count modes
* Automatic percentage validation (must sum to 100%)

### 3. Trait Definition

* Create trait categories (e.g., "Background", "Eyes", "Accessories")
* Define trait values with individual rarity percentages
* Support for multiple traits per category

### 4. Royalty Setup

* Configure creator royalties (max 7% per 1sat standard)
* Support for multiple royalty recipients
* Automatic validation of royalty totals

### 5. Review & Deploy

* Complete collection preview
* Estimated deployment cost
* Final validation before blockchain deployment

## Cover Image Requirements

### Image Validation

* **Format**: PNG, JPEG, GIF, or WebP
* **Size**: Maximum 1MB file size
* **Dimensions**: Must be square (same width and height)
* **Maximum Resolution**: 2048x2048 pixels

### Best Practices

```tsx
// Example image preparation
const prepareCollectionImage = async (file: File): Promise<boolean> => {
  // Validate format
  const validTypes = ['image/png', 'image/jpeg', 'image/gif', 'image/webp'];
  if (!validTypes.includes(file.type)) {
    throw new Error('Invalid image format');
  }
  
  // Check size limit
  if (file.size > 1024 * 1024) {
    throw new Error('Image too large (max 1MB)');
  }
  
  // Validate dimensions
  return new Promise((resolve, reject) => {
    const img = new Image();
    img.onload = () => {
      if (img.width !== img.height) {
        reject(new Error('Image must be square'));
      } else if (img.width > 2048) {
        reject(new Error('Image too large (max 2048x2048)'));
      } else {
        resolve(true);
      }
    };
    img.src = URL.createObjectURL(file);
  });
};
```

## Trait System

### Trait Categories

```typescript
// Example trait structure
const artCollectionTraits = {
  'Background': {
    values: {
      'Solid Blue': { rarity: '0.3000' },    // 30%
      'Gradient': { rarity: '0.2000' },      // 20%
      'Abstract': { rarity: '0.1500' },      // 15%
      'Cosmic': { rarity: '0.0500' }         // 5%
    }
  },
  'Style': {
    values: {
      'Minimalist': { rarity: '0.4000' },    // 40%
      'Detailed': { rarity: '0.3000' },      // 30%
      'Experimental': { rarity: '0.2000' },  // 20%
      'Surreal': { rarity: '0.1000' }        // 10%
    }
  }
};
```

### Rarity Calculation

```typescript
// Calculate overall item rarity
const calculateItemRarity = (traits: Record<string, string>) => {
  let totalRarity = 1;
  
  Object.entries(traits).forEach(([category, value]) => {
    const traitRarity = parseFloat(
      collectionTraits[category]?.values[value]?.rarity || '1'
    );
    totalRarity *= traitRarity;
  });
  
  return totalRarity;
};
```

## Royalty Management

### Royalty Configuration

```typescript
// Example royalty setup
const royaltyConfig = [
  {
    type: RoytaltyType.PAYMAIL,
    destination: 'artist@handcash.io',
    percentage: '0.0500' // 5%
  },
  {
    type: RoytaltyType.ADDRESS,
    destination: '1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa',
    percentage: '0.0200' // 2%
  }
];
```

### Royalty Validation

* Maximum 7% total royalties per 1sat standard
* Minimum 0.01% per recipient
* Automatic percentage validation
* Support for paymail and Bitcoin addresses

## Error Handling

Common error scenarios:

* Invalid image format/size
* Rarity percentages don't sum to 100%
* Royalty percentages exceed 7%
* Trait configuration errors
* Wallet connectivity issues

```tsx
const handleError = (error: Error) => {
  switch (error.message) {
    case 'Royalties exceed maximum 7%':
      setErrorMessage('Total royalties cannot exceed 7%. Please adjust your royalty configuration.');
      break;
    case 'Rarities must sum to 100%':
      setErrorMessage('Rarity percentages must total 100%. Please check your rarity configuration.');
      break;
    default:
      setErrorMessage(`Collection creation failed: ${error.message}`);
  }
};
```

## Integration Examples

### Social Media Integration

```tsx
const handleCollectionCreation = (txid: string, collection: CollectionData) => {
  // Share collection launch
  const message = `🎨 Just launched "${collection.name}" NFT collection on Bitcoin SV! ${collection.quantity} items with ${Object.keys(collection.traits).length} trait categories.`;
  
  socialPost({
    message,
    attachments: [{ type: 'collection', txid }],
    hashtags: ['#NFT', '#BSV', '#Collection']
  });
};
```

### Analytics Integration

```tsx
const trackCollectionMetrics = (collection: CollectionData) => {
  analytics.track('Collection Created', {
    name: collection.name,
    quantity: collection.quantity,
    traitCount: Object.keys(collection.traits).length,
    rarityTiers: collection.rarities.length,
    royaltyRecipients: collection.royalties.length
  });
};
```

## Related Components

* [BSV21MintButton](/docs/components/bsv21-mint-button) - Deploy individual NFT tokens
* [RarityEditor](/docs/components/rarity-editor) - Configure collection rarities
* [TraitEditor](/docs/components/trait-editor) - Define trait categories and values
* [RoyaltyEditor](/docs/components/royalty-editor) - Set up creator royalties

## Best Practices

### Collection Planning

```tsx
// Plan your collection structure
const planCollection = {
  // Clear theme and concept
  name: 'Pixel Warriors',
  description: '8-bit style warrior characters for the metaverse',
  
  // Reasonable quantity
  quantity: 5000, // Not too large for initial launch
  
  // Balanced rarities
  rarities: [
    { label: 'Common', percentage: '0.5000' },     // 50%
    { label: 'Uncommon', percentage: '0.3000' },   // 30%
    { label: 'Rare', percentage: '0.1500' },       // 15%
    { label: 'Epic', percentage: '0.0450' },       // 4.5%
    { label: 'Legendary', percentage: '0.0050' }    // 0.5%
  ]
};
```

### Trait Design

* Keep trait categories meaningful and distinct
* Balance common vs rare traits
* Consider trait interaction and combination possibilities
* Plan for future trait additions

### Royalty Strategy

```tsx
// Sustainable royalty structure
const sustainableRoyalties = [
  {
    type: RoytaltyType.PAYMAIL,
    destination: 'creator@domain.com',
    percentage: '0.0300' // 3% - reasonable for creator
  },
  {
    type: RoytaltyType.ADDRESS,
    destination: 'platform-address',
    percentage: '0.0150' // 1.5% - platform fee
  }
  // Total: 4.5% - leaves room for secondary market growth
];
```

# SyncAssetsComponent
URL: /docs/components/inscriptions/sync-assets-component

Complete file sync management for blockchain integration with ordfs.network API

***

title: SyncAssetsComponent
description: Complete file sync management for blockchain integration with ordfs.network API
categories: \[developer-tools, blockchain, file-management, sync]
-----------------------------------------------------------------

import { ComponentBadges } from '@/components/docs/ComponentBadges';
import { SyncAssetsComponentDemo } from '@/components/docs/demos/SyncAssetsComponentDemo';

Complete file sync management for blockchain integration with multi-file drop zone, validation, hash calculation, and ordfs.network API integration for checking existing files on-chain.

## Demo

## API Reference

This component uses [DropZone](/docs/components/dropzone) for file upload handling and extends the [Table](https://www.radix-ui.com/primitives/docs/components/table) and [Progress](https://www.radix-ui.com/primitives/docs/components/progress) primitives from Radix.

## Installation

```bash
npx bigblocks add sync-assets-component
```

## Import

```typescript
import { SyncAssetsComponent, FileSyncStatus } from 'bigblocks';
```

## Props

| Prop              | Type                                                             | Required | Default           | Description                            |
| ----------------- | ---------------------------------------------------------------- | -------- | ----------------- | -------------------------------------- |
| onSyncComplete    | `(results: { success: SyncFile[]; failed: SyncFile[] }) => void` | No       | -                 | Callback when sync operation completes |
| onError           | `(error: string) => void`                                        | No       | -                 | Callback when an error occurs          |
| maxFileSize       | `number`                                                         | No       | `10485760`        | Maximum file size in bytes (10MB)      |
| maxFiles          | `number`                                                         | No       | `50`              | Maximum number of files allowed        |
| acceptedTypes     | `string[]`                                                       | No       | Common file types | Array of accepted file extensions      |
| estimatedFeePerKB | `number`                                                         | No       | `500`             | Estimated fee per KB in satoshis       |
| className         | `string`                                                         | No       | -                 | Custom CSS classes                     |

## Types

### FileSyncStatus

```typescript
enum FileSyncStatus {
  Pending = 'pending',
  Checking = 'checking',
  OnChain = 'on-chain',
  NeedsSync = 'needs-sync',
  Syncing = 'syncing',
  Synced = 'synced',
  Failed = 'failed'
}
```

### SyncFile

```typescript
interface SyncFile {
  id: string;
  file: File;
  hash?: string;
  status: FileSyncStatus;
  size: number;
  txid?: string;
  error?: string;
  progress?: number;
  estimatedFee?: number;
}
```

### SyncSummary

```typescript
interface SyncSummary {
  totalFiles: number;
  needsSyncCount: number;
  totalSize: number; // in bytes
  estimatedTotalFee: number; // in satoshis
}
```

## Basic Usage

```tsx
import { SyncAssetsComponent } from 'bigblocks';

export default function FileSyncPage() {
  const handleSyncComplete = (results) => {
    console.log('Sync completed:', results);
    console.log('Successful syncs:', results.success.length);
    console.log('Failed syncs:', results.failed.length);
  };

const handleError = (error) => {
    console.error('Sync error:', error);
  };

return (
    <div className="max-w-4xl mx-auto p-6">
      <h1>File Sync Manager</h1>
      <SyncAssetsComponent
        onSyncComplete={handleSyncComplete}
        onError={handleError}
      />
    </div>
  );
}
```

## Advanced Usage

### Custom Configuration

```tsx
import { SyncAssetsComponent } from 'bigblocks';

export default function CustomSyncManager() {
  return (
    <SyncAssetsComponent
      maxFileSize={50 * 1024 * 1024} // 50MB
      maxFiles={100}
      acceptedTypes={['.jpg', '.png', '.pdf', '.json']}
      estimatedFeePerKB={1000} // Higher fee rate
      onSyncComplete={(results) => {
        // Handle completion
        if (results.failed.length > 0) {
          console.warn('Some files failed to sync:', results.failed);
        }
        
        // Update UI or navigate
        router.push('/files/success');
      }}
      onError={(error) => {
        // Handle errors
        toast.error(`Sync error: ${error}`);
      }}
    />
  );
}
```

### Integration with File Management

```tsx
import { SyncAssetsComponent, FileSyncStatus } from 'bigblocks';
import { useState } from 'react';

export default function FileManager() {
  const [syncedFiles, setSyncedFiles] = useState([]);
  const [syncHistory, setSyncHistory] = useState([]);

const handleSyncComplete = (results) => {
    // Update local state
    setSyncedFiles(prev => [...prev, ...results.success]);
    
    // Log to history
    setSyncHistory(prev => [...prev, {
      timestamp: new Date(),
      successCount: results.success.length,
      failureCount: results.failed.length,
      totalSize: results.success.reduce((sum, file) => sum + file.size, 0)
    }]);

// Notify other components
    window.dispatchEvent(new CustomEvent('filesSync', {
      detail: results
    }));
  };

return (
    <div className="space-y-6">
      <SyncAssetsComponent
        onSyncComplete={handleSyncComplete}
        maxFileSize={25 * 1024 * 1024} // 25MB
      />
      
      {syncedFiles.length > 0 && (
        <div>
          <h3>Recently Synced Files</h3>
          <ul>
            {syncedFiles.map(file => (
              <li key={file.id}>
                {file.file.name} - 
                <a href={`https://ordfs.network/${file.txid}`} target="_blank">
                  View on Blockchain
                </a>
              </li>
            ))}
          </ul>
        </div>
      )}
    </div>
  );
}
```

## Features

### Multi-File Drop Zone

* Drag and drop multiple files
* File validation (size, type, duplicates)
* Real-time feedback on validation errors
* Support for common file types

### Hash Calculation

* Uses Web Crypto API SHA-256
* Client-side hash calculation
* Efficient handling of large files
* Progress indication during hashing

### Blockchain Integration

* ordfs.network API integration
* Check existing files on-chain
* Avoid duplicate uploads
* Transaction ID tracking

### Fee Estimation

* Configurable fee rates
* Per-file fee calculation
* Total sync cost estimation
* Real-time fee updates

### Progress Tracking

* Individual file progress
* Overall sync progress
* Status indicators with icons
* Error handling and retry

## File Status Flow

```mermaid
graph TD
    A[Pending] --> B[Checking]
    B --> C{File Exists?}
    C -->|Yes| D[OnChain]
    C -->|No| E[NeedsSync]
    E --> F[Syncing]
    F --> G{Success?}
    G -->|Yes| H[Synced]
    G -->|No| I[Failed]
    B --> I
```

## API Integration

The component integrates with ordfs.network API:

```typescript
// Check if file exists on blockchain
const response = await fetch(`https://ordfs.network/api/files/${hash}`, {
  method: 'GET',
  headers: { Accept: 'application/json' }
});
```

## Error Handling

Common error scenarios:

* File too large
* Unsupported file type
* Duplicate files
* Network connectivity issues
* API rate limiting
* Insufficient funds for sync

## Performance Considerations

* Efficient hash calculation using Web Workers (where available)
* Configurable batch sizes for large file sets
* Progressive UI updates during sync operations
* Memory-efficient file handling

## Related Components

* [DropZone](/docs/components/dropzone) - File upload handling
* [LoadingButton](/docs/components/loading-button) - Action buttons with loading states
* [ErrorDisplay](/docs/components/error-display) - Error message display

## Best Practices

### File Organization

```tsx
// Organize files by type before syncing
const imageFiles = files.filter(f => f.type.startsWith('image/'));
const documentFiles = files.filter(f => f.type === 'application/pdf');
```

### Error Recovery

```tsx
const handleError = (error) => {
  // Log error for debugging
  console.error('Sync error:', error);
  
  // Show user-friendly message
  setErrorMessage('Failed to sync files. Please check your connection and try again.');
  
  // Optionally retry failed operations
  setTimeout(() => retrySyncOperation(), 5000);
};
```

### Cost Management

```tsx
// Monitor total sync costs
const handleSyncComplete = (results) => {
  const totalCost = results.success.reduce((sum, file) => sum + (file.estimatedFee || 0), 0);
  
  if (totalCost > maxBudget) {
    console.warn('Sync cost exceeded budget:', totalCost);
  }
};
```

# BuyListingButton
URL: /docs/components/market/buy-listing-button

Purchase marketplace items with Bitcoin SV transactions, supporting various asset types and secure payment processing.

***

title: BuyListingButton
description: Purchase marketplace items with Bitcoin SV transactions, supporting various asset types and secure payment processing.
categories: \['marketplace', 'payments', 'actions']
providers: \['BitcoinAuthProvider', 'BitcoinQueryProvider']
-----------------------------------------------------------

import { BuyListingButtonDemo } from '@/components/docs/demos/BuyListingButtonDemo'
import { ComponentBadges } from '@/components/docs/ComponentBadges'

Purchase button for marketplace items with Bitcoin SV transaction processing and built-in confirmation dialog.

BuyListingButton combines the [Radix Button primitive](https://www.radix-ui.com/themes/docs/components/button) and [Dialog primitive](https://www.radix-ui.com/themes/docs/components/dialog) with Bitcoin marketplace logic, providing secure payment processing, balance validation, and confirmation workflows for BSV20, BSV21, and Ordinals purchases.

## Installation

```bash
npx bigblocks add buy-listing-button
```

## Import

```tsx
import { BuyListingButton } from 'bigblocks';
```

## API Reference

This component extends the [Button primitive](https://www.radix-ui.com/themes/docs/components/button) and [Dialog primitive](https://www.radix-ui.com/themes/docs/components/dialog) and inherits their props.

| Prop        | Type                                        | Default              | Description                                         |
| ----------- | ------------------------------------------- | -------------------- | --------------------------------------------------- |
| listing\*   | `MarketListing`                             | -                    | Marketplace listing to purchase                     |
| onSuccess   | `(txid: string) => void`                    | -                    | Callback with transaction ID on successful purchase |
| onError     | `(error: Error) => void`                    | -                    | Callback when purchase fails                        |
| buttonText  | `string`                                    | `'Buy Now'`          | Custom button text                                  |
| dialogTitle | `string`                                    | `'Confirm Purchase'` | Purchase confirmation dialog title                  |
| showDetails | `boolean`                                   | `true`               | Show item details in confirmation dialog            |
| disabled    | `boolean`                                   | `false`              | Disable the button                                  |
| loading     | `boolean`                                   | `false`              | Show loading state                                  |
| variant     | `"solid" \| "soft" \| "outline" \| "ghost"` | `"solid"`            | Button variant style                                |
| size        | `"1" \| "2" \| "3" \| "4"`                  | `"2"`                | Button size                                         |
| className   | `string`                                    | -                    | Additional CSS classes                              |

\* Required props

## Basic Usage

```tsx
import { BuyListingButton } from 'bigblocks';

export default function MarketplaceListing() {
  const listing = {
    id: 'listing-123',
    assetType: 'BSV20',
    symbol: 'SATS',
    priceSats: 5000000,
    payAddress: '1Seller...',
    tokenAmount: 1000,
    decimals: 8
  };

return (
    <BuyListingButton
      listing={listing}
      onSuccess={(txid) => {
        console.log('Purchase successful!', txid);
        router.push('/my-purchases');
      }}
      onError={(error) => {
        console.error('Purchase failed:', error.message);
      }}
    />
  );
}
```

## Purchase Confirmation

BuyListingButton automatically handles the complete purchase flow:

```tsx
<BuyListingButton
  listing={listing}
  dialogTitle="Purchase NFT"
  showDetails={true}
  onSuccess={(txid) => {
    toast.success(`Purchase completed! TX: ${txid}`);
    updateInventory();
  }}
  onError={(error) => {
    if (error.message === 'INSUFFICIENT_FUNDS') {
      toast.error('Not enough BSV in wallet');
    } else {
      toast.error(`Purchase failed: ${error.message}`);
    }
  }}
/>
```

## Asset Support

Supports various Bitcoin asset types with automatic validation:

```tsx
// BSV20 Token
<BuyListingButton
  listing={{
    assetType: 'BSV20',
    symbol: 'SATS',
    tokenAmount: 1000,
    priceSats: 100000,
    // ... other props
  }}
/>

// Ordinals NFT
<BuyListingButton
  listing={{
    assetType: 'Ordinals', 
    tokenId: 'abc123...',
    priceSats: 5000000,
    // ... other props
  }}
/>
```

## Quick Buy Variant

For minimal UI with streamlined purchase flow:

```tsx
import { QuickBuyButton } from 'bigblocks';

<QuickBuyButton
  listing={listing}
  onSuccess={(txid) => console.log('Quick purchase:', txid)}
/>
```

## Marketplace Listing Structure

```tsx
interface MarketListing {
  id: string;
  assetType: 'BSV20' | 'BSV21' | 'Ordinals';
  symbol?: string;
  tokenId?: string;
  tokenAmount?: number;
  decimals?: number;
  priceSats: number;
  payAddress: string;
}
```

For styling options (variant, size, etc.), see the [Radix Button documentation](https://www.radix-ui.com/themes/docs/components/button).

## Related Components

* [MarketTable](/docs/components/market-table) - Display multiple listings
* [CreateListingButton](/docs/components/create-listing-button) - Create new listings
* [QuickBuyButton](/docs/components/quick-buy-button) - Streamlined purchase flow

# CompactMarketTable
URL: /docs/components/market/compact-market-table

A space-efficient table component for displaying marketplace listings in constrained layouts with optimized mobile responsiveness

***

title: CompactMarketTable
description: A space-efficient table component for displaying marketplace listings in constrained layouts with optimized mobile responsiveness
category: market
----------------

A space-efficient table component designed for displaying marketplace listings in constrained layouts like sidebars, mobile views, and dashboard widgets. Provides an optimized view of market data with configurable columns and actions.

[View Component Preview →](/component-preview/compact-market-table)

## Installation

```bash
npx bigblocks add compact-market-table
```

## Import

```typescript
import { CompactMarketTable } from 'bigblocks';
```

## Props

| Prop         | Type                               | Required | Default  | Description                              |
| ------------ | ---------------------------------- | -------- | -------- | ---------------------------------------- |
| listings     | `MarketListing[]`                  | Yes      | -        | Array of marketplace listings to display |
| maxItems     | `number`                           | No       | `10`     | Maximum number of items to display       |
| onItemClick  | `(listing: MarketListing) => void` | No       | -        | Click handler for listing items          |
| showPrice    | `boolean`                          | No       | `true`   | Display price column                     |
| showSeller   | `boolean`                          | No       | `false`  | Display seller column                    |
| showActions  | `boolean`                          | No       | `true`   | Show action buttons (Buy, View)          |
| condensed    | `boolean`                          | No       | `false`  | Enable extra compact mode                |
| showCategory | `boolean`                          | No       | `false`  | Display category column                  |
| showStatus   | `boolean`                          | No       | `false`  | Display listing status                   |
| sortBy       | `'price' \| 'date' \| 'name'`      | No       | `'date'` | Default sort order                       |
| className    | `string`                           | No       | -        | Additional CSS classes                   |

### MarketListing Interface

```typescript
interface MarketListing {
  id: string;
  title: string;
  description?: string;
  price: number;              // Price in satoshis
  priceBSV?: string;          // Formatted BSV price
  priceUSD?: number;          // USD equivalent
  seller: {
    address: string;
    name?: string;
    avatar?: string;
    verified?: boolean;
  };
  category?: string;
  status: 'active' | 'sold' | 'pending' | 'expired';
  createdAt: number;          // Timestamp
  updatedAt?: number;
  images?: string[];
  tags?: string[];
  views?: number;
  likes?: number;
}
```

## Basic Usage

```tsx
import { CompactMarketTable } from 'bigblocks';

export default function SidebarListings() {
  const recentListings = [
    {
      id: '1',
      title: 'Bitcoin Art NFT',
      price: 1000000, // 0.01 BSV
      priceBSV: '0.01',
      seller: {
        address: '1BitcoinArtist...',
        name: 'CryptoArtist'
      },
      category: 'Digital Art',
      status: 'active',
      createdAt: Date.now()
    },
    // ... more listings
  ];

return (
    <CompactMarketTable
      listings={recentListings}
      maxItems={5}
      onItemClick={(listing) => {
        console.log('Selected listing:', listing.id);
        window.location.href = `/listing/${listing.id}`;
      }}
    />
  );
}
```

## Advanced Usage

### Full-Featured Market Widget

```tsx
import { CompactMarketTable } from 'bigblocks';
import { useState, useEffect } from 'react';

export default function MarketWidget() {
  const [listings, setListings] = useState<MarketListing[]>([]);
  const [loading, setLoading] = useState(true);
  const [filter, setFilter] = useState<'all' | 'art' | 'collectibles' | 'services'>('all');

useEffect(() => {
    fetchListings();
  }, [filter]);

const handleListingClick = (listing: MarketListing) => {
    // Track analytics
    fetch('/api/analytics/listing-view', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ listingId: listing.id })
    });

// Navigate to listing details
    window.location.href = `/marketplace/listing/${listing.id}`;
  };

const handleQuickBuy = async (listing: MarketListing) => {
    if (listing.price > 10000000) { // > 0.1 BSV
      if (!confirm(`Buy "${listing.title}" for ${listing.priceBSV} BSV?`)) {
        return;
      }
    }

try {
      const response = await fetch('/api/market/quick-buy', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ listingId: listing.id })
      });

if (response.ok) {
        alert('Purchase successful!');
        fetchListings(); // Refresh listings
      }
    } catch (error) {
      console.error('Purchase failed:', error);
      alert('Purchase failed. Please try again.');
    }
  };

if (loading) {
    return <div className="loading-spinner">Loading marketplace...</div>;
  }

return (
    <div className="market-widget">
      <div className="widget-header">
        <h3>Marketplace</h3>
        <select 
          value={filter} 
          onChange={(e) => setFilter(e.target.value as any)}
          className="filter-select"
        >
          <option value="all">All Categories</option>
          <option value="art">Digital Art</option>
          <option value="collectibles">Collectibles</option>
          <option value="services">Services</option>
        </select>
      </div>

<div className="widget-footer">
        <a href="/marketplace" className="view-all-link">
          View All Listings →
        </a>
      </div>
    </div>
  );
}
```

### Mobile-Optimized Display

```tsx
import { CompactMarketTable } from 'bigblocks';
import { useMediaQuery } from 'bigblocks/hooks';

export default function MobileMarketplace() {
  const isMobile = useMediaQuery('(max-width: 768px)');
  const [selectedListing, setSelectedListing] = useState<MarketListing | null>(null);

return (
    <div className="mobile-marketplace">
      <CompactMarketTable
        listings={featuredListings}
        maxItems={20}
        showPrice={true}
        showSeller={!isMobile} // Hide seller on mobile for space
        showActions={!isMobile} // Use click handler on mobile
        condensed={isMobile}
        onItemClick={handleItemClick}
        className="mobile-optimized"
      />

{/* Mobile Detail Modal */}
      {selectedListing && isMobile && (
        <div className="listing-modal">
          <div className="modal-content">
            <h3>{selectedListing.title}</h3>
            <p className="price">{selectedListing.priceBSV} BSV</p>
            <p className="seller">by {selectedListing.seller.name || 'Anonymous'}</p>
            <div className="modal-actions">
              <button onClick={() => buyListing(selectedListing)}>
                Buy Now
              </button>
              <button onClick={() => setSelectedListing(null)}>
                Close
              </button>
            </div>
          </div>
        </div>
      )}
    </div>
  );
}
```

## Common Patterns

### Dashboard Recent Activity

```tsx
import { CompactMarketTable } from 'bigblocks';

export default function DashboardActivity() {
  const { recentListings, popularListings, yourListings } = useMarketData();

return (
    <div className="dashboard-activity">
      <div className="activity-section">
        <h4>🆕 Recent Listings</h4>
        <CompactMarketTable
          listings={recentListings}
          maxItems={5}
          showPrice={true}
          showActions={false}
          condensed={true}
          onItemClick={(listing) => navigateToListing(listing.id)}
        />
      </div>

<div className="activity-section">
        <h4>🔥 Popular Items</h4>
        <CompactMarketTable
          listings={popularListings}
          maxItems={5}
          showPrice={true}
          showStatus={true}
          condensed={true}
          sortBy="price"
        />
      </div>

<div className="activity-section">
        <h4>📦 Your Listings</h4>
        <CompactMarketTable
          listings={yourListings}
          maxItems={5}
          showPrice={true}
          showStatus={true}
          showActions={false}
          onItemClick={(listing) => editListing(listing.id)}
        />
      </div>
    </div>
  );
}
```

### Category-Filtered Sidebar

```tsx
import { CompactMarketTable } from 'bigblocks';
import { useState } from 'react';

interface CategorySidebarProps {
  categories: string[];
  onCategoryChange?: (category: string) => void;
}

export default function CategorySidebar({ categories, onCategoryChange }: CategorySidebarProps) {
  const [selectedCategory, setSelectedCategory] = useState('all');
  const [categoryListings, setCategoryListings] = useState<MarketListing[]>([]);

const handleCategorySelect = async (category: string) => {
    setSelectedCategory(category);
    onCategoryChange?.(category);

// Fetch listings for category
    try {
      const response = await fetch(`/api/market/category/${category}`);
      const data = await response.json();
      setCategoryListings(data.listings);
    } catch (error) {
      console.error('Failed to fetch category listings:', error);
    }
  };

return (
    <div className="category-sidebar">
      <div className="category-tabs">
        <button 
          className={selectedCategory === 'all' ? 'active' : ''}
          onClick={() => handleCategorySelect('all')}
        >
          All
        </button>
        {categories.map((category) => (
          <button
            key={category}
            className={selectedCategory === category ? 'active' : ''}
            onClick={() => handleCategorySelect(category)}
          >
            {category}
          </button>
        ))}
      </div>

<CompactMarketTable
        listings={categoryListings}
        maxItems={10}
        showPrice={true}
        showSeller={false}
        condensed={true}
        onItemClick={(listing) => {
          console.log('Selected from category:', selectedCategory, listing);
          window.location.href = `/marketplace/${selectedCategory}/${listing.id}`;
        }}
        className="category-listings"
      />
    </div>
  );
}
```

### Live Auction Feed

```tsx
import { CompactMarketTable } from 'bigblocks';
import { useEffect, useState } from 'react';

export default function LiveAuctionFeed() {
  const [auctions, setAuctions] = useState<MarketListing[]>([]);
  const [ws, setWs] = useState<WebSocket | null>(null);

useEffect(() => {
    // Connect to auction WebSocket
    const websocket = new WebSocket('wss://api.example.com/auctions/live');
    
    websocket.onmessage = (event) => {
      const update = JSON.parse(event.data);
      
      if (update.type === 'new_bid') {
        setAuctions(prev => 
          prev.map(auction => 
            auction.id === update.listingId
              ? { ...auction, price: update.newPrice, priceBSV: update.newPriceBSV }
              : auction
          )
        );
      } else if (update.type === 'new_listing') {
        setAuctions(prev => [update.listing, ...prev].slice(0, 20));
      }
    };

setWs(websocket);

return () => {
      websocket.close();
    };
  }, []);

const handleAuctionClick = (listing: MarketListing) => {
    // Open auction detail in modal for quick bidding
    openAuctionModal(listing);
  };

return (
    <div className="live-auction-feed">
      <div className="feed-header">
        <h3>🔴 Live Auctions</h3>
        <span className="live-indicator">● LIVE</span>
      </div>

### Watchlist Widget

```tsx
import { CompactMarketTable } from 'bigblocks';
import { useWatchlist } from 'bigblocks/hooks';

export default function WatchlistWidget() {
  const { watchlist, addToWatchlist, removeFromWatchlist } = useWatchlist();
  const [priceAlerts, setPriceAlerts] = useState<Record<string, number>>({});

// Register price alert
      fetch('/api/market/price-alerts', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          listingId: listing.id,
          targetPrice: targetSatoshis
        })
      });
    }
  };

const watchlistWithAlerts = watchlist.map(listing => ({
    ...listing,
    priceAlert: priceAlerts[listing.id],
    priceChange: calculatePriceChange(listing)
  }));

return (
    <div className="watchlist-widget">
      <div className="widget-header">
        <h3>👁️ Watchlist ({watchlist.length})</h3>
        <button onClick={() => window.location.href = '/market/watchlist'}>
          Manage
        </button>
      </div>

{watchlist.length === 0 ? (
        <p className="empty-state">No items in watchlist</p>
      ) : (
        <CompactMarketTable
          listings={watchlistWithAlerts}
          maxItems={10}
          showPrice={true}
          showStatus={true}
          showActions={true}
          onItemClick={(listing) => {
            console.log('Watchlist item clicked:', listing);
            window.location.href = `/listing/${listing.id}`;
          }}
          className="watchlist-table"
        />
      )}

<div className="watchlist-actions">
        <button onClick={() => window.location.href = '/marketplace'}>
          Browse Marketplace
        </button>
      </div>
    </div>
  );
}
```

## Authentication Requirements

The CompactMarketTable can work without authentication for public listings, but some features require auth:

```tsx
import { 
  BitcoinAuthProvider, 
  BitcoinQueryProvider, 
  CompactMarketTable 
} from 'bigblocks';

function App() {
  return (
    <BitcoinQueryProvider>
      <BitcoinAuthProvider config={{ apiUrl: '/api' }}>
        {/* Authenticated features: Buy buttons, watchlist, etc. */}
        <CompactMarketTable 
          listings={listings}
          showActions={true} // Buy buttons require auth
        />
      </BitcoinAuthProvider>
    </BitcoinQueryProvider>
  );
}
```

## Features

* **Space-Efficient Design**: Optimized for sidebars and constrained layouts
* **Configurable Columns**: Show/hide price, seller, category, status as needed
* **Mobile Responsive**: Automatically adapts to smaller screens
* **Action Buttons**: Quick buy and view actions (configurable)
* **Sorting Options**: Sort by price, date, or name
* **Condensed Mode**: Extra compact display for tight spaces
* **Click Handling**: Customizable item click behavior
* **Real-time Updates**: Can integrate with WebSocket for live data
* **Performance**: Virtualized rendering for large lists

## Styling

The component includes responsive styling optimized for different contexts:

```css
/* Default compact table styles */
.compact-market-table {
  width: 100%;
  font-size: 0.875rem;
}

.compact-market-table th {
  padding: 0.5rem;
  font-weight: 600;
  text-align: left;
  border-bottom: 1px solid var(--border-color);
}

.compact-market-table td {
  padding: 0.5rem;
  border-bottom: 1px solid var(--border-color-light);
}

/* Condensed mode */
.compact-market-table.condensed th,
.compact-market-table.condensed td {
  padding: 0.25rem 0.5rem;
  font-size: 0.813rem;
}

/* Mobile responsive */
@media (max-width: 768px) {
  .compact-market-table .seller-column,
  .compact-market-table .category-column {
    display: none;
  }
  
  .compact-market-table .title-column {
    max-width: 150px;
    overflow: hidden;
    text-overflow: ellipsis;
    white-space: nowrap;
  }
}

/* Hover effects */
.compact-market-table tbody tr:hover {
  background-color: var(--hover-bg);
  cursor: pointer;
}

/* Status indicators */
.status-active { color: var(--color-success); }
.status-sold { color: var(--color-muted); }
.status-pending { color: var(--color-warning); }
.status-expired { color: var(--color-error); }
```

## Performance Optimization

### Virtual Scrolling for Large Lists

```tsx
import { CompactMarketTable } from 'bigblocks';
import { useVirtualizer } from '@tanstack/react-virtual';

export default function VirtualizedMarketTable({ listings }: { listings: MarketListing[] }) {
  const parentRef = useRef<HTMLDivElement>(null);

const virtualizer = useVirtualizer({
    count: listings.length,
    getScrollElement: () => parentRef.current,
    estimateSize: () => 40, // Estimated row height
    overscan: 5,
  });

const virtualItems = virtualizer.getVirtualItems();
  const virtualListings = virtualItems.map(item => listings[item.index]);

return (
    <div ref={parentRef} className="virtual-container" style={{ height: '400px', overflow: 'auto' }}>
      <div style={{ height: `${virtualizer.getTotalSize()}px`, position: 'relative' }}>
        <CompactMarketTable
          listings={virtualListings}
          maxItems={virtualItems.length}
          showPrice={true}
          condensed={true}
        />
      </div>
    </div>
  );
}
```

## Troubleshooting

### Common Issues

**Table not rendering**

* Verify listings array is properly formatted
* Check that required props (listings) are provided
* Ensure MarketListing objects have required fields (id, title, price, seller, status)

**Click handlers not working**

* Verify onItemClick prop is passed correctly
* Check for event propagation issues
* Ensure table rows aren't disabled

**Columns not showing/hiding**

* Check boolean props (showPrice, showSeller, etc.)
* Verify responsive styles aren't hiding columns
* Test in different viewport sizes

**Performance issues with large lists**

* Use maxItems to limit displayed rows
* Implement virtual scrolling for lists > 100 items
* Consider pagination or lazy loading

## Related Components

* [MarketTable](/docs/components/market-table) - Full-featured market table
* [QuickBuyButton](/docs/components/quick-buy-button) - Inline purchase actions
* [CreateListingButton](/docs/components/create-listing-button) - Create new listings
* [BuyListingButton](/docs/components/buy-listing-button) - Detailed purchase flow

## API Reference

### CompactMarketTable Component

```typescript
interface CompactMarketTableProps {
  listings: MarketListing[];
  maxItems?: number;
  onItemClick?: (listing: MarketListing) => void;
  showPrice?: boolean;
  showSeller?: boolean;
  showActions?: boolean;
  condensed?: boolean;
  showCategory?: boolean;
  showStatus?: boolean;
  sortBy?: 'price' | 'date' | 'name';
  className?: string;
}
```

### Usage with React Query

```typescript
import { useQuery } from '@tanstack/react-query';
import { CompactMarketTable } from 'bigblocks';

function MarketTableWithQuery() {
  const { data: listings, isLoading } = useQuery({
    queryKey: ['market-listings', 'featured'],
    queryFn: () => fetch('/api/market/featured').then(res => res.json()),
    refetchInterval: 30000, // Refresh every 30 seconds
  });

if (isLoading) return <div>Loading listings...</div>;

return (
    <CompactMarketTable 
      listings={listings || []}
      maxItems={10}
      showPrice={true}
      showActions={true}
    />
  );
}
```

# CreateListingButton
URL: /docs/components/market/create-listing-button

Create marketplace listings on the Bitcoin blockchain with customizable forms, image uploads, and rich metadata

***

title: CreateListingButton
description: Create marketplace listings on the Bitcoin blockchain with customizable forms, image uploads, and rich metadata
category: market
----------------

A comprehensive component for creating marketplace listings on the Bitcoin blockchain, featuring customizable forms, multi-image uploads, category selection, and on-chain metadata storage for permanent, decentralized marketplace functionality.

[View Component Preview →](/component-preview/create-listing-button)

## Installation

```bash
npx bigblocks add create-listing-button
```

## Import

```typescript
import { CreateListingButton } from 'bigblocks';
```

## Props

| Prop             | Type                             | Required | Default            | Description                                   |
| ---------------- | -------------------------------- | -------- | ------------------ | --------------------------------------------- |
| onCreateListing  | `(listing: Listing) => void`     | No       | -                  | Callback when listing is created successfully |
| onError          | `(error: MarketError) => void`   | No       | -                  | Error callback                                |
| categories       | `string[]`                       | No       | Default categories | Available categories for selection            |
| maxImages        | `number`                         | No       | `5`                | Maximum number of images allowed              |
| requiresApproval | `boolean`                        | No       | `false`            | Whether listings require admin approval       |
| feeAmount        | `number`                         | No       | `0.001`            | Listing fee in BSV                            |
| variant          | `'button' \| 'card' \| 'inline'` | No       | `'button'`         | Display variant                               |
| size             | `'sm' \| 'md' \| 'lg'`           | No       | `'md'`             | Component size                                |
| className        | `string`                         | No       | -                  | Additional CSS classes                        |

### Listing Interface

```typescript
interface Listing {
  id: string;
  txid: string;                    // Blockchain transaction ID
  title: string;
  description: string;
  price: number;                   // Price in satoshis
  currency: 'BSV' | 'USD';
  category: string;
  images: string[];                // Array of image URLs
  seller: {
    address: string;
    name?: string;
    idKey: string;               // BAP identity key
  };
  assetType: 'BSV20' | 'BSV21' | 'BSV721' | 'DIGITAL' | 'PHYSICAL';
  metadata?: {
    condition?: 'new' | 'used' | 'refurbished';
    location?: string;
    shipping?: boolean;
    tags?: string[];
  };
  paymentAddress: string;         // Address to receive payment
  ordAddress: string;             // Ordinals address for NFTs
  timestamp: number;
  status: 'active' | 'sold' | 'cancelled';
}

interface MarketError {
  code: 
    | 'INSUFFICIENT_FUNDS'
    | 'INVALID_LISTING_DATA'
    | 'IMAGE_TOO_LARGE'
    | 'UNSUPPORTED_ASSET_TYPE'
    | 'CATEGORY_NOT_FOUND'
    | 'RATE_LIMITED';
  message: string;
  details?: {
    required?: number;
    available?: number;
    maxSize?: number;
    supportedTypes?: string[];
  };
}
```

## Basic Usage

```tsx
import { CreateListingButton } from 'bigblocks';

export default function Marketplace() {
  const handleListingCreated = (listing: Listing) => {
    console.log('Created listing:', listing);
    console.log('Transaction ID:', listing.txid);
    
    // Navigate to listing detail page
    window.location.href = `/marketplace/listing/${listing.id}`;
  };

return (
    <CreateListingButton
      onCreateListing={handleListingCreated}
      onError={handleError}
    />
  );
}
```

## Advanced Usage

### Complete Marketplace Integration

```tsx
import { CreateListingButton } from 'bigblocks';
import { useState, useEffect } from 'react';

export default function AdvancedMarketplace() {
  const [categories, setCategories] = useState<string[]>([]);
  const [userListings, setUserListings] = useState<Listing[]>([]);
  const [listingFee, setListingFee] = useState(0.001);

useEffect(() => {
    // Fetch available categories
    fetchCategories();
    // Get current listing fee
    fetchListingFee();
  }, []);

// Show success notification
    const notification = new Notification('Listing Created!', {
      body: `Your listing "${listing.title}" is now live on the marketplace.`,
      icon: '/icon-192x192.png'
    });

// Navigate to listing
    setTimeout(() => {
      window.location.href = `/marketplace/listing/${listing.id}`;
    }, 2000);
  };

return (
    <div className="advanced-marketplace">
      <div className="marketplace-header">
        <h1>Create New Listing</h1>
        <p className="fee-info">
          Listing fee: {listingFee} BSV
        </p>
      </div>

<CreateListingButton
        categories={categories}
        maxImages={10}
        feeAmount={listingFee}
        variant="card"
        size="lg"
        onCreateListing={handleListingCreated}
        onError={(error) => {
          if (error.code === 'RATE_LIMITED') {
            alert('You can only create 10 listings per hour. Please try again later.');
          } else if (error.code === 'IMAGE_TOO_LARGE') {
            alert(`Image too large. Maximum size: ${error.details?.maxSize} MB`);
          } else {
            alert(`Error: ${error.message}`);
          }
        }}
        className="marketplace-create-button"
      />

{userListings.length > 0 && (
        <div className="user-listings mt-8">
          <h2>Your Recent Listings</h2>
          <div className="listings-grid">
            {userListings.slice(0, 6).map((listing) => (
              <div key={listing.id} className="listing-card">
                <img src={listing.images[0]} alt={listing.title} />
                <h3>{listing.title}</h3>
                <p className="price">{listing.price / 100000000} BSV</p>
                <span className="status">{listing.status}</span>
              </div>
            ))}
          </div>
        </div>
      )}
    </div>
  );
}
```

### NFT Marketplace Creation

```tsx
import { CreateListingButton } from 'bigblocks';

interface NFTMetadata {
  name: string;
  description: string;
  image: string;
  attributes: Array<{
    trait_type: string;
    value: string | number;
  }>;
  rarity?: string;
  collection?: string;
}

export default function NFTMarketplace() {
  const handleNFTListing = async (listing: Listing) => {
    console.log('NFT listing created:', listing);
    
    // For NFT listings, the ordAddress is particularly important
    console.log('Ordinals address:', listing.ordAddress);
    console.log('Asset type:', listing.assetType); // BSV721
    
    // Store NFT metadata on-chain
    await storeNFTMetadata(listing.id, listing.metadata as NFTMetadata);
  };

return (
    <div className="nft-marketplace">
      <h1>List Your NFT</h1>
      
      <CreateListingButton
        variant="card"
        categories={['Art', 'Collectibles', 'Gaming', 'Music', 'Photography']}
        maxImages={10}
        feeAmount={0.01} // Higher fee for NFT listings
        onCreateListing={handleNFTListing}
        className="nft-create-listing"
      />
      
      <div className="listing-tips">
        <h3>Tips for NFT Listings</h3>
        <ul>
          <li>Use high-quality images (at least 1000x1000px)</li>
          <li>Include detailed metadata and attributes</li>
          <li>Specify rarity and collection information</li>
          <li>Set competitive prices based on market trends</li>
        </ul>
      </div>
    </div>
  );
}
```

## Common Patterns

### Multi-Step Listing Creation

```tsx
import { CreateListingButton } from 'bigblocks';
import { useState } from 'react';

export default function MultiStepListing() {
  const [step, setStep] = useState<'prepare' | 'create' | 'complete'>('prepare');
  const [preparedData, setPreparedData] = useState<any>(null);
  const [createdListing, setCreatedListing] = useState<Listing | null>(null);

const handlePrepare = () => {
    // Prepare listing data
    const data = {
      title: document.getElementById('title')?.value,
      description: document.getElementById('description')?.value,
      price: parseFloat(document.getElementById('price')?.value) * 100000000,
      category: document.getElementById('category')?.value,
    };
    
    setPreparedData(data);
    setStep('create');
  };

const handleListingCreated = (listing: Listing) => {
    setCreatedListing(listing);
    setStep('complete');
  };

return (
    <div className="multi-step-listing">
      {step === 'prepare' && (
        <div className="step-prepare">
          <h2>Prepare Your Listing</h2>
          <form>
            <input id="title" placeholder="Title" required />
            <textarea id="description" placeholder="Description" required />
            <input id="price" type="number" placeholder="Price in BSV" required />
            <select id="category" required>
              <option value="">Select Category</option>
              <option value="Electronics">Electronics</option>
              <option value="Art">Art</option>
              <option value="Collectibles">Collectibles</option>
            </select>
          </form>
          <button onClick={handlePrepare}>Next: Add Images</button>
        </div>
      )}

{step === 'create' && (
        <div className="step-create">
          <h2>Complete Your Listing</h2>
          <div className="prepared-info">
            <h3>{preparedData.title}</h3>
            <p>{preparedData.description}</p>
            <p className="price">{preparedData.price / 100000000} BSV</p>
          </div>
          
          <CreateListingButton
            variant="inline"
            onCreateListing={handleListingCreated}
            className="complete-listing-button"
          />
        </div>
      )}

{step === 'complete' && createdListing && (
        <div className="step-complete">
          <h2>✅ Listing Created Successfully!</h2>
          <div className="listing-summary">
            <h3>{createdListing.title}</h3>
            <p>Transaction ID: {createdListing.txid}</p>
            <p>Listing ID: {createdListing.id}</p>
            <p>Status: {createdListing.status}</p>
          </div>
          
          <div className="next-actions">
            <button onClick={() => window.location.href = `/marketplace/listing/${createdListing.id}`}>
              View Listing
            </button>
            <button onClick={() => window.location.href = '/marketplace/dashboard'}>
              Go to Dashboard
            </button>
            <button onClick={() => setStep('prepare')}>
              Create Another
            </button>
          </div>
        </div>
      )}
    </div>
  );
}
```

### Bulk Listing Upload

```tsx
import { CreateListingButton } from 'bigblocks';
import { useState } from 'react';

interface BulkListingData {
  title: string;
  description: string;
  price: number;
  category: string;
  images: File[];
}

export default function BulkListingUpload() {
  const [bulkData, setBulkData] = useState<BulkListingData[]>([]);
  const [currentIndex, setCurrentIndex] = useState(0);
  const [created, setCreated] = useState<Listing[]>([]);

const handleCSVUpload = (event: React.ChangeEvent<HTMLInputElement>) => {
    const file = event.target.files?.[0];
    if (!file) return;

// Parse CSV and populate bulkData
    const reader = new FileReader();
    reader.onload = (e) => {
      const csv = e.target?.result as string;
      const parsed = parseCSV(csv);
      setBulkData(parsed);
    };
    reader.readAsText(file);
  };

const currentListing = bulkData[currentIndex];

return (
    <div className="bulk-listing-upload">
      <h2>Bulk Listing Upload</h2>
      
      {bulkData.length === 0 ? (
        <div className="upload-section">
          <input 
            type="file" 
            accept=".csv"
            onChange={handleCSVUpload}
          />
          <p>Upload a CSV file with your listings</p>
        </div>
      ) : (
        <div className="bulk-creation">
          <div className="progress">
            Creating listing {currentIndex + 1} of {bulkData.length}
          </div>
          
          <div className="current-listing">
            <h3>{currentListing.title}</h3>
            <p>{currentListing.description}</p>
            <p>{currentListing.price} BSV</p>
          </div>
          
          <CreateListingButton
            variant="inline"
            onCreateListing={handleListingCreated}
            onError={(error) => {
              console.error(`Failed to create listing ${currentIndex + 1}:`, error);
              // Skip to next
              if (currentIndex < bulkData.length - 1) {
                setCurrentIndex(currentIndex + 1);
              }
            }}
          />
          
          <div className="created-count">
            ✅ {created.length} listings created successfully
          </div>
        </div>
      )}
    </div>
  );
}
```

### Service Marketplace

```tsx
import { CreateListingButton } from 'bigblocks';

interface ServiceListing extends Listing {
  metadata: {
    serviceType: 'consultation' | 'development' | 'design' | 'writing' | 'other';
    deliveryTime: string;
    revisions: number;
    requirements?: string[];
  };
}

export default function ServiceMarketplace() {
  const handleServiceListing = (listing: Listing) => {
    const serviceListing = listing as ServiceListing;
    
    console.log('Service listing created:', {
      title: serviceListing.title,
      type: serviceListing.metadata.serviceType,
      delivery: serviceListing.metadata.deliveryTime,
      price: `${serviceListing.price / 100000000} BSV`
    });
  };

return (
    <div className="service-marketplace">
      <h1>Offer Your Services</h1>
      
      <CreateListingButton
        categories={[
          'Consultation',
          'Development', 
          'Design',
          'Writing',
          'Marketing',
          'Other Services'
        ]}
        variant="card"
        size="lg"
        onCreateListing={handleServiceListing}
        className="service-listing-button"
      />
      
      <div className="service-examples">
        <h3>Popular Services</h3>
        <ul>
          <li>🖥️ Smart Contract Development</li>
          <li>🎨 NFT Art Creation</li>
          <li>✍️ Technical Writing</li>
          <li>📊 Blockchain Consulting</li>
          <li>🔍 Security Audits</li>
        </ul>
      </div>
    </div>
  );
}
```

### Physical Goods with Shipping

```tsx
import { CreateListingButton } from 'bigblocks';

export default function PhysicalGoodsMarketplace() {
  const shippingRegions = ['Local', 'National', 'International'];
  
  const handlePhysicalListing = async (listing: Listing) => {
    if (listing.assetType !== 'PHYSICAL') return;
    
    // Calculate shipping costs
    const shippingCosts = await calculateShipping({
      weight: listing.metadata?.weight,
      dimensions: listing.metadata?.dimensions,
      destination: listing.metadata?.location
    });
    
    console.log('Physical item listed:', {
      title: listing.title,
      shipping: listing.metadata?.shipping,
      location: listing.metadata?.location,
      estimatedShipping: shippingCosts
    });
  };

return (
    <div className="physical-goods-marketplace">
      <h1>Sell Physical Items</h1>
      
      <CreateListingButton
        categories={[
          'Electronics',
          'Books',
          'Collectibles',
          'Art',
          'Jewelry',
          'Home & Garden',
          'Sports & Outdoors'
        ]}
        variant="card"
        maxImages={10}
        onCreateListing={handlePhysicalListing}
      />
      
      <div className="shipping-info">
        <h3>Shipping Information</h3>
        <p>When listing physical items, please include:</p>
        <ul>
          <li>Item weight and dimensions</li>
          <li>Shipping regions you support</li>
          <li>Estimated delivery times</li>
          <li>Return policy</li>
        </ul>
      </div>
    </div>
  );
}
```

## Authentication Requirements

The CreateListingButton requires Bitcoin authentication for creating listings:

```tsx
import { 
  BitcoinAuthProvider, 
  BitcoinQueryProvider, 
  CreateListingButton 
} from 'bigblocks';

function App() {
  return (
    <BitcoinQueryProvider>
      <BitcoinAuthProvider config={{ 
        apiUrl: '/api',
        walletMode: 'integrated' // Required for payment
      }}>
        <CreateListingButton 
          onCreateListing={(listing) => {
            console.log('Created listing:', listing);
          }}
        />
      </BitcoinAuthProvider>
    </BitcoinQueryProvider>
  );
}
```

## API Integration

The CreateListingButton integrates with several backend endpoints:

### Core Listing Endpoints

```typescript
// Create new listing
POST /api/market/listings
{
  title: string;
  description: string;
  price: number; // satoshis
  currency: 'BSV' | 'USD';
  category: string;
  images: string[];
  metadata?: object;
  assetType: string;
}

// Upload images
POST /api/market/images/upload
FormData with multiple image files

// Get categories
GET /api/market/categories

// Estimate listing fee
POST /api/market/listings/estimate-fee
{
  assetType: string;
  imageCount: number;
  hasMetadata: boolean;
}
```

### Real-time Updates

```typescript
// Server-Sent Events for marketplace
GET /api/market/stream

Events:
- listing_created: { listing: Listing }
- listing_sold: { listingId: string, buyer: string }
- listing_cancelled: { listingId: string }
- price_updated: { listingId: string, newPrice: number }
```

## Features

* **On-chain Storage**: Permanent blockchain marketplace listings
* **Multi-Image Upload**: Support for multiple images with automatic thumbnails
* **Category System**: Organized hierarchical category structure
* **Flexible Pricing**: Support for BSV or USD pricing
* **Rich Metadata**: Detailed item information and attributes
* **Preview Mode**: Review listing before blockchain submission
* **Fee Estimation**: Calculate listing fees before creation
* **Draft Saving**: Save listings as drafts before publishing
* **Asset Types**: Support for digital goods, NFTs, and physical items

## Error Handling

### Comprehensive Error Management

```tsx
import { CreateListingButton } from 'bigblocks';

export default function RobustListingCreation() {
  const handleError = (error: MarketError) => {
    switch (error.code) {
      case 'INSUFFICIENT_FUNDS':
        console.log(`Need ${error.details?.required} satoshis for listing fee`);
        // Prompt user to add funds
        showFundingModal(error.details?.required);
        break;
        
      case 'IMAGE_TOO_LARGE':
        alert(`Image exceeds maximum size of ${error.details?.maxSize} MB`);
        break;
        
      case 'RATE_LIMITED':
        alert('You have reached the hourly listing limit. Please try again later.');
        break;
        
      case 'UNSUPPORTED_ASSET_TYPE':
        console.error('Asset type not supported:', error.details?.supportedTypes);
        break;
        
      default:
        alert(`Error creating listing: ${error.message}`);
    }
  };

return (
    <CreateListingButton 
      onError={handleError}
      onCreateListing={(listing) => {
        console.log('Success:', listing);
      }}
    />
  );
}
```

## Styling

The component includes multiple display variants:

```css
/* Button variant */
.create-listing-button {
  display: inline-flex;
  align-items: center;
  gap: 0.5rem;
  padding: 0.75rem 1.5rem;
  background: var(--primary-color);
  color: white;
  border-radius: 0.5rem;
  font-weight: 600;
  transition: all 0.2s;
}

/* Card variant */
.create-listing-card {
  border: 1px solid var(--border-color);
  border-radius: 0.75rem;
  padding: 2rem;
  background: var(--card-background);
  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
}

/* Inline variant */
.create-listing-inline {
  width: 100%;
  padding: 1rem;
  border: 2px dashed var(--border-color);
  border-radius: 0.5rem;
  text-align: center;
  cursor: pointer;
  transition: border-color 0.2s;
}

.create-listing-inline:hover {
  border-color: var(--primary-color);
}

/* Modal form */
.listing-form-modal {
  max-width: 600px;
  max-height: 90vh;
  overflow-y: auto;
}

/* Image upload area */
.image-upload-zone {
  border: 2px dashed var(--border-color);
  border-radius: 0.5rem;
  padding: 2rem;
  text-align: center;
  cursor: pointer;
}

.image-preview-grid {
  display: grid;
  grid-template-columns: repeat(auto-fill, minmax(100px, 1fr));
  gap: 1rem;
  margin-top: 1rem;
}
```

## Performance Optimization

### Image Optimization

```tsx
import { CreateListingButton } from 'bigblocks';

export default function OptimizedImageUpload() {
  const processImages = async (images: File[]) => {
    // Resize and compress images before upload
    const optimized = await Promise.all(
      images.map(async (file) => {
        if (file.size > 1024 * 1024) { // > 1MB
          return compressImage(file, {
            maxWidth: 1920,
            maxHeight: 1080,
            quality: 0.8
          });
        }
        return file;
      })
    );
    
    return optimized;
  };

return (
    <CreateListingButton 
      maxImages={20} // Allow more images since they're optimized
      onCreateListing={(listing) => {
        console.log('Optimized listing created:', listing);
      }}
    />
  );
}
```

## Troubleshooting

### Common Issues

**Form validation errors**

* Ensure all required fields are filled
* Check price is a valid number > 0
* Verify at least one image is uploaded
* Confirm category is selected

**Image upload failures**

* Check file size (max 10MB per image)
* Verify supported formats (JPG, PNG, GIF, WebP)
* Ensure stable internet connection
* Try reducing image dimensions

**Insufficient funds error**

* Check wallet balance for listing fee
* Fee includes base fee + image storage
* Typical fee: 0.001-0.01 BSV

**Rate limiting**

* Maximum 10 listings per hour
* Wait for cooldown period
* Consider bulk upload for multiple items

## Related Components

* [CompactMarketTable](/docs/components/compact-market-table) - Display marketplace listings
* [MarketTable](/docs/components/market-table) - Full marketplace table
* [BuyListingButton](/docs/components/buy-listing-button) - Purchase listings
* [QuickBuyButton](/docs/components/quick-buy-button) - Quick purchase interface

## API Reference

### CreateListingButton Component

```typescript
interface CreateListingButtonProps {
  onCreateListing?: (listing: Listing) => void;
  onError?: (error: MarketError) => void;
  categories?: string[];
  maxImages?: number;
  requiresApproval?: boolean;
  feeAmount?: number;
  variant?: 'button' | 'card' | 'inline';
  size?: 'sm' | 'md' | 'lg';
  className?: string;
}
```

### Usage with React Query

```typescript
import { useMutation } from '@tanstack/react-query';
import { CreateListingButton } from 'bigblocks';

return (
    <CreateListingButton 
      onCreateListing={(listing) => {
        console.log('Component listing:', listing);
        // Additional processing if needed
      }}
    />
  );
}
```

# MarketTable
URL: /docs/components/market/market-table

A full-featured table component for displaying marketplace listings with sorting, filtering, and action capabilities.

***

title: MarketTable
description: A full-featured table component for displaying marketplace listings with sorting, filtering, and action capabilities.
----------------------------------------------------------------------------------------------------------------------------------

A full-featured table component for displaying marketplace listings with sorting, filtering, and action capabilities. Perfect for building Bitcoin SV marketplaces with comprehensive listing management.

[View MarketTable examples →](/component-preview/market-table)

## Installation

```bash
npm install bigblocks
```

## Usage

```tsx
import { MarketTable } from 'bigblocks';

export default function MarketplacePage() {
  const listings = [
    {
      id: '1',
      title: 'Bitcoin T-Shirt',
      price: { bsv: '0.01', satoshis: 1000000 },
      seller: { name: 'CryptoStore', rating: 4.8 },
      category: 'clothing',
      status: 'active'
    }
  ];

return (
    <MarketTable
      listings={listings}
      onListingClick={(listing) => router.push(`/listing/${listing.id}`)}
      onBuySuccess={(txid, listing) => {
        console.log('Purchase successful:', txid);
      }}
    />
  );
}
```

## Props

| Prop             | Type                                             | Default | Description                      |
| ---------------- | ------------------------------------------------ | ------- | -------------------------------- |
| `listings`       | `MarketListing[]`                                | `[]`    | Array of marketplace listings    |
| `loading`        | `boolean`                                        | `false` | Show loading state               |
| `error`          | `string`                                         | -       | Error message to display         |
| `onListingClick` | `(listing: MarketListing) => void`               | -       | Callback when listing is clicked |
| `onBuySuccess`   | `(txid: string, listing: MarketListing) => void` | -       | Success callback for purchases   |
| `onBuyError`     | `(error: Error, listing: MarketListing) => void` | -       | Error callback for purchases     |
| `showAssetType`  | `boolean`                                        | `true`  | Show asset type column           |
| `showSeller`     | `boolean`                                        | `true`  | Show seller information          |
| `maxItems`       | `number`                                         | -       | Maximum items to display         |
| `className`      | `string`                                         | -       | Additional CSS classes           |

### MarketListing Interface

```typescript
interface MarketListing {
  id: string;
  title: string;
  description?: string;
  price: {
    satoshis: number;
    bsv: string;
    usd?: number;
  };
  seller: {
    name: string;
    address?: string;
    rating?: number;
    verified?: boolean;
  };
  category: string;
  condition?: 'new' | 'used' | 'refurbished';
  images?: Array<{
    url: string;
    thumbnailUrl?: string;
  }>;
  status: 'active' | 'sold' | 'reserved' | 'expired';
  created: number;
  expires?: number;
}
```

## Features

* **Responsive Design**: Mobile-optimized table layout
* **Interactive Actions**: Buy buttons with transaction handling
* **Seller Information**: Ratings, verification status, and profiles
* **Asset Categories**: Flexible categorization system
* **Real-time Updates**: Live listing status and price changes
* **Error Handling**: Comprehensive error states and recovery
* **Loading States**: Skeleton loading for better UX

## Examples

### Basic Market Table

```tsx
<MarketTable
  listings={listings}
  onListingClick={(listing) => {
    console.log('Viewing listing:', listing.title);
  }}
/>
```

### With Purchase Handling

```tsx
<MarketTable
  listings={listings}
  onBuySuccess={(txid, listing) => {
    toast.success(`Purchased ${listing.title}! TX: ${txid}`);
    refreshListings();
  }}
  onBuyError={(error, listing) => {
    toast.error(`Failed to buy ${listing.title}: ${error.message}`);
  }}
/>
```

### Loading State

```tsx
<MarketTable
  listings={[]}
  loading={true}
  onListingClick={handleListingClick}
/>
```

### Error State

```tsx
<MarketTable
  listings={[]}
  error="Failed to load marketplace listings"
  onListingClick={handleListingClick}
/>
```

### Compact Version

```tsx
import { CompactMarketTable } from 'bigblocks';

<CompactMarketTable
  listings={featuredListings}
  maxItems={5}
  className="featured-items"
/>
```

### Filtered Listings

```tsx
function FilteredMarketplace() {
  const [category, setCategory] = useState('all');
  const [priceRange, setPriceRange] = useState({ min: 0, max: 1000000 });
  const [filteredListings, setFilteredListings] = useState([]);

const applyFilters = useCallback(() => {
    let filtered = allListings;
    
    if (category !== 'all') {
      filtered = filtered.filter(listing => listing.category === category);
    }
    
    filtered = filtered.filter(listing => 
      listing.price.satoshis >= priceRange.min && 
      listing.price.satoshis <= priceRange.max
    );
    
    setFilteredListings(filtered);
  }, [category, priceRange, allListings]);

return (
    <div className="filtered-marketplace">
      <div className="filters">
        <select value={category} onChange={(e) => setCategory(e.target.value)}>
          <option value="all">All Categories</option>
          <option value="digital">Digital Assets</option>
          <option value="physical">Physical Items</option>
          <option value="services">Services</option>
        </select>
        
        <div className="price-range">
          <input
            type="number"
            placeholder="Min Price (sats)"
            value={priceRange.min}
            onChange={(e) => setPriceRange(prev => ({ 
              ...prev, 
              min: parseInt(e.target.value) || 0 
            }))}
          />
          <input
            type="number"
            placeholder="Max Price (sats)"
            value={priceRange.max}
            onChange={(e) => setPriceRange(prev => ({ 
              ...prev, 
              max: parseInt(e.target.value) || 1000000 
            }))}
          />
        </div>
      </div>
      
      <MarketTable
        listings={filteredListings}
        onListingClick={handleListingClick}
        onBuySuccess={handlePurchaseSuccess}
      />
    </div>
  );
}
```

### Marketplace Dashboard

```tsx
function MarketplaceDashboard() {
  const [listings, setListings] = useState([]);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState(null);
  const [stats, setStats] = useState(null);

useEffect(() => {
    fetchMarketData()
      .then(data => {
        setListings(data.listings);
        setStats(data.stats);
      })
      .catch(setError)
      .finally(() => setLoading(false));
  }, []);

return (
    <div className="marketplace-dashboard">
      <div className="dashboard-header">
        <h1>Marketplace</h1>
        {stats && (
          <div className="stats">
            <div className="stat">
              <span className="value">{stats.totalListings}</span>
              <span className="label">Active Listings</span>
            </div>
            <div className="stat">
              <span className="value">{stats.totalVolume}</span>
              <span className="label">Volume (BSV)</span>
            </div>
          </div>
        )}
      </div>
      
      <MarketTable
        listings={listings}
        loading={loading}
        error={error}
        onListingClick={(listing) => {
          router.push(`/marketplace/listing/${listing.id}`);
        }}
        onBuySuccess={(txid, listing) => {
          toast.success('Purchase completed successfully!');
          // Update local state
          setListings(prev => 
            prev.map(l => 
              l.id === listing.id 
                ? { ...l, status: 'sold' } 
                : l
            )
          );
        }}
        className="main-market-table"
      />
    </div>
  );
}
```

### Seller's Store View

```tsx
function SellerStore({ sellerId }) {
  const [sellerListings, setSellerListings] = useState([]);
  const [sellerInfo, setSellerInfo] = useState(null);

useEffect(() => {
    fetchSellerData(sellerId).then(data => {
      setSellerListings(data.listings);
      setSellerInfo(data.seller);
    });
  }, [sellerId]);

return (
    <div className="seller-store">
      {sellerInfo && (
        <div className="seller-header">
          <img src={sellerInfo.avatar} alt={sellerInfo.name} />
          <div className="seller-details">
            <h2>{sellerInfo.name}</h2>
            <div className="rating">
              ⭐ {sellerInfo.rating} ({sellerInfo.totalSales} sales)
            </div>
            {sellerInfo.verified && (
              <span className="verified-badge">✓ Verified</span>
            )}
          </div>
        </div>
      )}
      
      <MarketTable
        listings={sellerListings}
        showSeller={false} // Hide seller column since all items are from same seller
        onListingClick={(listing) => {
          router.push(`/listing/${listing.id}`);
        }}
        onBuySuccess={(txid, listing) => {
          console.log('Purchased from seller:', txid);
        }}
      />
    </div>
  );
}
```

### Real-time Market Updates

```tsx
function LiveMarketTable() {
  const [listings, setListings] = useState([]);

useEffect(() => {
    // WebSocket for real-time updates
    const ws = new WebSocket('/api/market/stream');
    
    ws.onmessage = (event) => {
      const data = JSON.parse(event.data);
      
      switch (data.type) {
        case 'listing_created':
          setListings(prev => [data.listing, ...prev]);
          break;
          
        case 'listing_updated':
          setListings(prev => 
            prev.map(listing => 
              listing.id === data.listingId 
                ? { ...listing, ...data.updates }
                : listing
            )
          );
          break;
          
        case 'listing_sold':
          setListings(prev => 
            prev.map(listing => 
              listing.id === data.listingId 
                ? { ...listing, status: 'sold' }
                : listing
            )
          );
          break;
      }
    };

return () => ws.close();
  }, []);

return (
    <MarketTable
      listings={listings}
      onListingClick={handleListingClick}
      onBuySuccess={handlePurchaseSuccess}
    />
  );
}
```

## Required Context

The component requires the following providers:

```tsx
import { 
  BitcoinAuthProvider, 
  BitcoinQueryProvider 
} from 'bigblocks';

function App() {
  return (
    <BitcoinAuthProvider>
      <BitcoinQueryProvider>
        <MarketTable
          listings={listings}
          onBuySuccess={handlePurchaseSuccess}
        />
      </BitcoinQueryProvider>
    </BitcoinAuthProvider>
  );
}
```

## API Integration

### Required Backend Endpoints

The component expects these API endpoints:

#### 1. Get Market Listings

```typescript
GET /api/market/listings?category=<category>&sort=<sort>&limit=20

Response:
{
  listings: MarketListing[];
  pagination: {
    total: number;
    hasMore: boolean;
  };
  filters: {
    categories: string[];
    priceRanges: Array<{ min: number; max: number; count: number }>;
  };
}
```

#### 2. Purchase Listing

```typescript
POST /api/market/listings/{id}/purchase

Request:
{
  quantity: number;
  shippingAddress?: string;
  paymentMethod: 'bsv';
}

Response:
{
  success: boolean;
  txid: string;
  orderId: string;
  totalCost: number;
}
```

#### 3. Get Listing Details

```typescript
GET /api/market/listings/{id}

Response:
{
  listing: MarketListing;
  seller: SellerProfile;
  related: MarketListing[];
}
```

### Authentication Headers

For authenticated market operations:

```typescript
headers: {
  'X-Auth-Token': '<BSM signature>',
  'Content-Type': 'application/json'
}
```

## Market Categories

### Supported Categories

| Category       | Description              | Examples                        |
| -------------- | ------------------------ | ------------------------------- |
| `digital`      | Digital assets and files | NFTs, eBooks, Software          |
| `physical`     | Physical items           | Electronics, Clothing, Books    |
| `services`     | Service offerings        | Consulting, Design, Development |
| `collectibles` | Rare and unique items    | Art, Cards, Memorabilia         |
| `tickets`      | Event tickets            | Concerts, Sports, Theater       |

## Purchase Flow

### Transaction Process

1. **Item Selection**: User clicks buy button
2. **Payment Calculation**: Total cost including fees
3. **Transaction Creation**: Bitcoin transaction built
4. **User Confirmation**: Confirm purchase details
5. **Transaction Signing**: Sign with user's private key
6. **Broadcast**: Submit to BSV network
7. **Confirmation**: Monitor transaction status

### Error Handling

```tsx
<MarketTable
  listings={listings}
  onBuyError={(error, listing) => {
    switch (error.message) {
      case 'INSUFFICIENT_FUNDS':
        toast.error('Insufficient BSV balance');
        break;
      case 'LISTING_UNAVAILABLE':
        toast.error('Item no longer available');
        break;
      case 'SELLER_OFFLINE':
        toast.error('Seller is currently offline');
        break;
      default:
        toast.error(`Purchase failed: ${error.message}`);
    }
  }}
/>
```

## Performance Considerations

* **Lazy Loading**: Load images on demand
* **Pagination**: Handle large datasets efficiently
* **Caching**: Cache listing data for better performance
* **Debounced Search**: Prevent excessive API calls
* **Virtual Scrolling**: For very large lists

## Styling Customization

```tsx
// Custom marketplace theme
<MarketTable
  listings={listings}
  className="
    bg-white dark:bg-gray-900 
    border border-gray-200 dark:border-gray-700
    rounded-lg shadow-lg
  "
  onListingClick={handleClick}
/>

// Compact mobile view
<MarketTable
  listings={listings}
  className="md:hidden compact-mobile-table"
  maxItems={10}
/>
```

## Related Components

* [CompactMarketTable](/docs/components/compact-market-table) - Space-efficient display
* [BuyListingButton](/docs/components/buy-listing-button) - Individual purchase buttons
* [CreateListingButton](/docs/components/create-listing-button) - Create new listings
* [QuickBuyButton](/docs/components/quick-buy-button) - Simplified purchase flow

# QuickBuyButton
URL: /docs/components/market/quick-buy-button

A one-click purchase button for marketplace listings with built-in transaction handling and confirmation flows

***

title: QuickBuyButton
description: A one-click purchase button for marketplace listings with built-in transaction handling and confirmation flows
category: market
----------------

A streamlined one-click purchase button designed for marketplace listings, providing instant buying capabilities with built-in transaction handling, optional confirmation dialogs, and comprehensive error management for a frictionless purchase experience.

[View Component Preview →](/component-preview/quick-buy-button)

## Installation

```bash
npx bigblocks add quick-buy-button
```

## Import

```typescript
import { QuickBuyButton } from 'bigblocks';
```

## Props

| Prop            | Type                                 | Required | Default     | Description                               |
| --------------- | ------------------------------------ | -------- | ----------- | ----------------------------------------- |
| listingId       | `string`                             | Yes      | -           | Marketplace listing ID to purchase        |
| price           | `number`                             | Yes      | -           | Price in satoshis                         |
| onSuccess       | `(transaction: Transaction) => void` | No       | -           | Success callback with transaction details |
| onError         | `(error: MarketError) => void`       | No       | -           | Error callback                            |
| confirmPurchase | `boolean`                            | No       | `true`      | Show confirmation dialog before purchase  |
| variant         | `'default' \| 'outline' \| 'ghost'`  | No       | `'default'` | Button style variant                      |
| size            | `'sm' \| 'md' \| 'lg'`               | No       | `'md'`      | Button size                               |
| disabled        | `boolean`                            | No       | `false`     | Disable the button                        |
| loading         | `boolean`                            | No       | `false`     | Show loading state                        |
| className       | `string`                             | No       | -           | Additional CSS classes                    |

### Transaction Interface

```typescript
interface Transaction {
  txid: string;                    // Blockchain transaction ID
  listingId: string;               // Purchased listing ID
  price: number;                   // Amount paid in satoshis
  seller: {
    address: string;
    idKey?: string;              // BAP identity key
  };
  buyer: {
    address: string;
    idKey?: string;
  };
  timestamp: number;
  status: 'pending' | 'confirmed' | 'failed';
  confirmations?: number;
  blockHeight?: number;
}

interface MarketError {
  code: 
    | 'INSUFFICIENT_FUNDS'
    | 'LISTING_NOT_FOUND'
    | 'LISTING_SOLD'
    | 'PAYMENT_FAILED'
    | 'NETWORK_ERROR'
    | 'AUTH_REQUIRED';
  message: string;
  details?: {
    required?: number;
    available?: number;
    listingStatus?: string;
  };
}
```

## Basic Usage

```tsx
import { QuickBuyButton } from 'bigblocks';

export default function ListingCard({ listing }) {
  const handlePurchaseSuccess = (transaction: Transaction) => {
    console.log('Purchase successful!');
    console.log('Transaction ID:', transaction.txid);
    console.log('Listing purchased:', transaction.listingId);
    
    // Navigate to success page
    window.location.href = `/purchases/${transaction.txid}`;
  };

return (
    <div className="listing-card">
      <h3>{listing.title}</h3>
      <p className="price">{listing.price} sats</p>
      
      <QuickBuyButton
        listingId={listing.id}
        price={listing.price}
        onSuccess={handlePurchaseSuccess}
        onError={handlePurchaseError}
      />
    </div>
  );
}
```

## Advanced Usage

### Complete Marketplace Integration

```tsx
import { QuickBuyButton } from 'bigblocks';
import { useState, useEffect } from 'react';

interface MarketplaceListing {
  id: string;
  title: string;
  description: string;
  price: number;
  images: string[];
  seller: {
    name: string;
    address: string;
    rating: number;
  };
  status: 'active' | 'sold' | 'pending';
}

export default function AdvancedMarketplace() {
  const [listings, setListings] = useState<MarketplaceListing[]>([]);
  const [purchases, setPurchases] = useState<Transaction[]>([]);
  const [processingId, setProcessingId] = useState<string | null>(null);

const handlePurchase = async (listingId: string) => {
    setProcessingId(listingId);
  };

return (
    <div className="advanced-marketplace">
      <h1>Marketplace</h1>
      
      <div className="listings-grid">
        {listings.map((listing) => (
          <div key={listing.id} className="listing-item">
            <img src={listing.images[0]} alt={listing.title} />
            <h3>{listing.title}</h3>
            <p className="seller">by {listing.seller.name}</p>
            <p className="price">{listing.price.toLocaleString()} sats</p>
            
            {listing.status === 'active' ? (
              <QuickBuyButton
                listingId={listing.id}
                price={listing.price}
                onSuccess={handlePurchaseSuccess}
                onError={handlePurchaseError}
                loading={processingId === listing.id}
                disabled={processingId !== null && processingId !== listing.id}
                variant="default"
                size="md"
              />
            ) : (
              <span className="sold-badge">SOLD</span>
            )}
          </div>
        ))}
      </div>
      
      {purchases.length > 0 && (
        <div className="recent-purchases">
          <h2>Your Recent Purchases</h2>
          <ul>
            {purchases.slice(0, 5).map((purchase) => (
              <li key={purchase.txid}>
                <a href={`/purchases/${purchase.txid}`}>
                  {purchase.txid.slice(0, 8)}...
                </a>
                <span className="purchase-price">
                  {purchase.price.toLocaleString()} sats
                </span>
              </li>
            ))}
          </ul>
        </div>
      )}
    </div>
  );
}
```

### Skip Confirmation for Small Purchases

```tsx
import { QuickBuyButton } from 'bigblocks';

export default function MicropaymentMarketplace() {
  const MICROPAYMENT_THRESHOLD = 10000; // 10k satoshis
  
  const handleQuickPurchase = (listing: any) => {
    const skipConfirmation = listing.price < MICROPAYMENT_THRESHOLD;
    
    return (
      <QuickBuyButton
        listingId={listing.id}
        price={listing.price}
        confirmPurchase={!skipConfirmation}
        onSuccess={(tx) => {
          if (skipConfirmation) {
            console.log('Micropayment processed instantly:', tx);
          } else {
            console.log('Purchase confirmed:', tx);
          }
        }}
        size="sm"
        variant="outline"
      />
    );
  };

return (
    <div className="micropayment-marketplace">
      <h2>Digital Downloads</h2>
      <p className="info">
        Purchases under {MICROPAYMENT_THRESHOLD.toLocaleString()} sats are instant!
      </p>
      
      <div className="downloads-grid">
        {digitalGoods.map((item) => (
          <div key={item.id} className="download-item">
            <h4>{item.title}</h4>
            <p className="price">{item.price} sats</p>
            {handleQuickPurchase(item)}
          </div>
        ))}
      </div>
    </div>
  );
}
```

## Common Patterns

### NFT Marketplace Quick Buy

```tsx
import { QuickBuyButton } from 'bigblocks';

interface NFTListing {
  id: string;
  tokenId: string;
  collection: string;
  name: string;
  price: number;
  rarity: 'common' | 'rare' | 'epic' | 'legendary';
  owner: string;
}

export default function NFTMarketplace() {
  const [nfts, setNfts] = useState<NFTListing[]>([]);

const getRarityColor = (rarity: string) => {
    const colors = {
      common: 'gray',
      rare: 'blue',
      epic: 'purple',
      legendary: 'orange'
    };
    return colors[rarity] || 'gray';
  };

return (
    <div className="nft-marketplace">
      <h1>NFT Marketplace</h1>
      
      <div className="nft-grid">
        {nfts.map((nft) => (
          <div key={nft.id} className="nft-card">
            <div className={`rarity-badge ${nft.rarity}`}>
              {nft.rarity.toUpperCase()}
            </div>
            
            <img src={`/api/nft/image/${nft.tokenId}`} alt={nft.name} />
            
            <div className="nft-details">
              <h3>{nft.name}</h3>
              <p className="collection">{nft.collection}</p>
              <p className="price">{nft.price.toLocaleString()} sats</p>
              
              <QuickBuyButton
                listingId={nft.id}
                price={nft.price}
                onSuccess={handleNFTPurchase}
                onError={(error) => {
                  if (error.code === 'LISTING_SOLD') {
                    alert('This NFT has already been sold!');
                    refreshNFTs();
                  }
                }}
                variant="default"
                className={`rarity-${nft.rarity}`}
              />
            </div>
          </div>
        ))}
      </div>
    </div>
  );
}
```

### Auction Quick Buy-It-Now

```tsx
import { QuickBuyButton } from 'bigblocks';
import { useState, useEffect } from 'react';

interface AuctionListing {
  id: string;
  title: string;
  currentBid: number;
  buyItNowPrice: number;
  endTime: number;
  bidCount: number;
}

export default function AuctionMarketplace() {
  const [auctions, setAuctions] = useState<AuctionListing[]>([]);

const handleBuyItNow = (transaction: Transaction) => {
    console.log('Buy It Now executed:', transaction);
    
    // Remove from active auctions
    setAuctions(prev => prev.filter(a => a.id !== transaction.listingId));
    
    // Show success message
    alert('You won the auction with Buy It Now!');
  };

return (
    <div className="auction-marketplace">
      <h1>Live Auctions</h1>
      
      <div className="auctions-grid">
        {auctions.map((auction) => (
          <div key={auction.id} className="auction-card">
            <h3>{auction.title}</h3>
            
            <div className="auction-stats">
              <div className="current-bid">
                <span className="label">Current Bid</span>
                <span className="value">{auction.currentBid.toLocaleString()} sats</span>
                <span className="bid-count">({auction.bidCount} bids)</span>
              </div>
              
              <div className="time-remaining">
                <span className="label">Time Left</span>
                <span className="value">{getTimeRemaining(auction.endTime)}</span>
              </div>
            </div>
            
            <div className="buy-it-now">
              <p className="or-divider">— OR —</p>
              <p className="bin-label">Buy It Now</p>
              
              <QuickBuyButton
                listingId={auction.id}
                price={auction.buyItNowPrice}
                onSuccess={handleBuyItNow}
                confirmPurchase={true}
                variant="default"
                size="lg"
                className="buy-it-now-button"
              />
            </div>
          </div>
        ))}
      </div>
    </div>
  );
}
```

### Service Marketplace Quick Purchase

```tsx
import { QuickBuyButton } from 'bigblocks';

interface ServiceListing {
  id: string;
  title: string;
  description: string;
  price: number;
  deliveryTime: string;
  provider: {
    name: string;
    rating: number;
    completedJobs: number;
  };
}

export default function ServiceMarketplace() {
  const [services, setServices] = useState<ServiceListing[]>([]);

return (
    <div className="service-marketplace">
      <h1>Hire Bitcoin Developers</h1>
      
      <div className="services-grid">
        {services.map((service) => (
          <div key={service.id} className="service-card">
            <div className="provider-info">
              <span className="provider-name">{service.provider.name}</span>
              <span className="rating">
                ⭐ {service.provider.rating} ({service.provider.completedJobs} jobs)
              </span>
            </div>
            
            <h3>{service.title}</h3>
            <p>{service.description}</p>
            
            <div className="service-details">
              <span className="delivery">🚚 {service.deliveryTime}</span>
              <span className="price">{service.price.toLocaleString()} sats</span>
            </div>
            
            <QuickBuyButton
              listingId={service.id}
              price={service.price}
              onSuccess={handleServicePurchase}
              variant="outline"
              size="md"
              className="hire-button"
            />
          </div>
        ))}
      </div>
    </div>
  );
}
```

### Subscription Quick Purchase

```tsx
import { QuickBuyButton } from 'bigblocks';

interface SubscriptionPlan {
  id: string;
  name: string;
  price: number;
  period: 'monthly' | 'yearly';
  features: string[];
  popular?: boolean;
}

export default function SubscriptionPlans() {
  const plans: SubscriptionPlan[] = [
    {
      id: 'basic',
      name: 'Basic',
      price: 50000,
      period: 'monthly',
      features: ['Feature A', 'Feature B']
    },
    {
      id: 'pro',
      name: 'Pro',
      price: 100000,
      period: 'monthly',
      features: ['Everything in Basic', 'Feature C', 'Feature D'],
      popular: true
    },
    {
      id: 'enterprise',
      name: 'Enterprise',
      price: 250000,
      period: 'monthly',
      features: ['Everything in Pro', 'Feature E', 'Priority Support']
    }
  ];

return (
    <div className="subscription-plans">
      <h1>Choose Your Plan</h1>
      
      <div className="plans-grid">
        {plans.map((plan) => (
          <div key={plan.id} className={`plan-card ${plan.popular ? 'popular' : ''}`}>
            {plan.popular && <span className="popular-badge">Most Popular</span>}
            
            <h2>{plan.name}</h2>
            <p className="price">
              {plan.price.toLocaleString()} sats
              <span className="period">/{plan.period}</span>
            </p>
            
            <ul className="features">
              {plan.features.map((feature, index) => (
                <li key={index}>✓ {feature}</li>
              ))}
            </ul>
            
            <QuickBuyButton
              listingId={plan.id}
              price={plan.price}
              onSuccess={handleSubscriptionPurchase}
              confirmPurchase={true}
              variant={plan.popular ? 'default' : 'outline'}
              size="lg"
              className="subscribe-button"
            />
          </div>
        ))}
      </div>
    </div>
  );
}
```

## Authentication Requirements

The QuickBuyButton requires Bitcoin authentication for transaction processing:

```tsx
import { 
  BitcoinAuthProvider, 
  BitcoinQueryProvider, 
  QuickBuyButton 
} from 'bigblocks';

function App() {
  return (
    <BitcoinQueryProvider>
      <BitcoinAuthProvider config={{ 
        apiUrl: '/api',
        walletMode: 'integrated' // Required for payments
      }}>
        <QuickBuyButton 
          listingId="listing123"
          price={10000}
          onSuccess={(tx) => console.log('Purchased!', tx)}
        />
      </BitcoinAuthProvider>
    </BitcoinQueryProvider>
  );
}
```

## API Integration

The QuickBuyButton integrates with marketplace purchase endpoints:

### Purchase Endpoints

```typescript
// Execute quick purchase
POST /api/market/quick-buy
{
  listingId: string;
  price: number;
}

Response:
{
  success: boolean;
  transaction: {
    txid: string;
    listingId: string;
    price: number;
    seller: { address: string; idKey: string; };
    buyer: { address: string; idKey: string; };
    timestamp: number;
    status: string;
  };
}

// Verify listing availability
GET /api/market/listings/{listingId}/availability

Response:
{
  available: boolean;
  price: number;
  seller: string;
  status: 'active' | 'sold' | 'pending';
}
```

## Features

* **One-Click Purchase**: Instant buying with minimal friction
* **Confirmation Dialog**: Optional purchase confirmation for safety
* **Transaction Handling**: Complete blockchain transaction management
* **Error Recovery**: Comprehensive error handling and user feedback
* **Loading States**: Visual feedback during transaction processing
* **Style Variants**: Multiple button styles for different contexts
* **Size Options**: Flexible sizing for various layouts
* **Status Updates**: Real-time transaction status tracking

## Error Handling

### Comprehensive Error Management

```tsx
import { QuickBuyButton } from 'bigblocks';

export default function RobustQuickBuy() {
  const handleError = (error: MarketError) => {
    switch (error.code) {
      case 'INSUFFICIENT_FUNDS':
        const needed = error.details?.required || 0;
        const have = error.details?.available || 0;
        alert(`Insufficient funds. Need ${needed} sats but only have ${have}.`);
        // Show funding options
        showFundingModal(needed - have);
        break;
        
      case 'LISTING_SOLD':
        alert('This item has already been sold.');
        // Refresh the listing
        window.location.reload();
        break;
        
      case 'AUTH_REQUIRED':
        alert('Please sign in to make purchases.');
        window.location.href = '/signin';
        break;
        
      case 'NETWORK_ERROR':
        alert('Network error. Please check your connection and try again.');
        break;
        
      default:
        alert(`Purchase failed: ${error.message}`);
    }
  };

return (
    <QuickBuyButton 
      listingId="abc123"
      price={50000}
      onError={handleError}
      onSuccess={(tx) => {
        console.log('Success!', tx);
      }}
    />
  );
}
```

## Styling

The component includes three style variants:

```css
/* Default variant */
.quick-buy-button.default {
  background: var(--primary-color);
  color: white;
  border: none;
}

.quick-buy-button.default:hover {
  background: var(--primary-hover);
}

/* Outline variant */
.quick-buy-button.outline {
  background: transparent;
  color: var(--primary-color);
  border: 1px solid var(--primary-color);
}

.quick-buy-button.outline:hover {
  background: var(--primary-light);
}

/* Ghost variant */
.quick-buy-button.ghost {
  background: transparent;
  color: var(--text-color);
  border: none;
}

.quick-buy-button.ghost:hover {
  background: var(--hover-bg);
}

/* Size variations */
.quick-buy-button.sm {
  padding: 0.25rem 0.75rem;
  font-size: 0.875rem;
}

.quick-buy-button.md {
  padding: 0.5rem 1rem;
  font-size: 1rem;
}

.quick-buy-button.lg {
  padding: 0.75rem 1.5rem;
  font-size: 1.125rem;
}

/* Loading state */
.quick-buy-button.loading {
  opacity: 0.7;
  cursor: not-allowed;
}

.quick-buy-button .spinner {
  animation: spin 1s linear infinite;
}
```

## Performance Optimization

### Optimistic UI Updates

```tsx
import { QuickBuyButton } from 'bigblocks';
import { useOptimistic } from 'react';

export default function OptimisticPurchase({ listing }) {
  const [optimisticStatus, setOptimisticStatus] = useOptimistic(
    listing.status,
    (state, newStatus) => newStatus
  );

return (
    <div className={`listing ${optimisticStatus}`}>
      <h3>{listing.title}</h3>
      
      {optimisticStatus === 'active' ? (
        <QuickBuyButton
          listingId={listing.id}
          price={listing.price}
          onSuccess={handlePurchase}
        />
      ) : (
        <span className="sold-badge">SOLD</span>
      )}
    </div>
  );
}
```

## Troubleshooting

### Common Issues

**Button not responding**

* Verify Bitcoin authentication is set up
* Check that user has sufficient balance
* Ensure listing ID and price are valid
* Confirm wallet is unlocked

**Confirmation dialog not showing**

* Check `confirmPurchase` prop is true (default)
* Verify no JavaScript errors in console
* Ensure modal container is present

**Transaction failures**

* Check wallet balance for funds + fees
* Verify listing is still available
* Ensure network connectivity
* Check for rate limiting

**Loading state stuck**

* Verify API endpoints are responding
* Check for network timeouts
* Ensure error callbacks are implemented

## Related Components

* [BuyListingButton](/docs/components/buy-listing-button) - Full purchase flow with details
* [CreateListingButton](/docs/components/create-listing-button) - Create marketplace listings
* [CompactMarketTable](/docs/components/compact-market-table) - Display listings
* [MarketTable](/docs/components/market-table) - Full marketplace table

## API Reference

### QuickBuyButton Component

```typescript
interface QuickBuyButtonProps {
  listingId: string;
  price: number;
  onSuccess?: (transaction: Transaction) => void;
  onError?: (error: MarketError) => void;
  confirmPurchase?: boolean;
  variant?: 'default' | 'outline' | 'ghost';
  size?: 'sm' | 'md' | 'lg';
  disabled?: boolean;
  loading?: boolean;
  className?: string;
}
```

### Usage with React Query

```typescript
import { useMutation } from '@tanstack/react-query';
import { QuickBuyButton } from 'bigblocks';

return (
    <QuickBuyButton 
      listingId={listing.id}
      price={listing.price}
      loading={purchaseMutation.isLoading}
      onSuccess={(tx) => {
        console.log('Component success:', tx);
      }}
    />
  );
}
```

# QuickListButton
URL: /docs/components/market/quick-list-button

A streamlined button component for quickly creating marketplace listings with minimal configuration and instant publishing

***

title: QuickListButton
description: A streamlined button component for quickly creating marketplace listings with minimal configuration and instant publishing
category: market
----------------

A streamlined one-click button component for instantly creating marketplace listings with minimal configuration, perfect for adding "Sell This" functionality to any item, product card, or inventory management interface.

[View Component Preview →](/component-preview/quick-list-button)

## Installation

```bash
npx bigblocks add quick-list-button
```

## Import

```typescript
import { QuickListButton } from 'bigblocks';
```

## Props

| Prop        | Type                                | Required | Default     | Description                           |
| ----------- | ----------------------------------- | -------- | ----------- | ------------------------------------- |
| name        | `string`                            | Yes      | -           | Item name for the listing             |
| price       | `number`                            | Yes      | -           | Price in satoshis                     |
| description | `string`                            | No       | -           | Optional item description             |
| image       | `string`                            | No       | -           | Item image URL                        |
| category    | `string`                            | No       | `'General'` | Marketplace category                  |
| onSuccess   | `(listing: MarketListing) => void`  | No       | -           | Success callback with created listing |
| onError     | `(error: Error) => void`            | No       | -           | Error callback                        |
| variant     | `'default' \| 'outline' \| 'ghost'` | No       | `'default'` | Button style variant                  |
| size        | `'sm' \| 'md' \| 'lg'`              | No       | `'md'`      | Button size                           |
| autoPublish | `boolean`                           | No       | `true`      | Automatically publish listing         |
| currency    | `'BSV' \| 'USD'`                    | No       | `'BSV'`     | Price currency                        |
| className   | `string`                            | No       | -           | Additional CSS classes                |

### MarketListing Interface

```typescript
interface MarketListing {
  id: string;
  name: string;
  description?: string;
  price: number;
  currency: 'BSV' | 'USD';
  category: string;
  image?: string;
  seller: {
    address: string;
    idKey: string;
    name?: string;
  };
  txid: string;
  timestamp: number;
  status: 'active' | 'pending' | 'sold';
  views: number;
  ordAddress?: string;           // For NFT listings
}
```

## Basic Usage

```tsx
import { QuickListButton } from 'bigblocks';

export default function ProductCard({ product }) {
  const handleListingSuccess = (listing: MarketListing) => {
    console.log('Product listed successfully!');
    console.log('Listing ID:', listing.id);
    console.log('Transaction:', listing.txid);
    
    // Navigate to listing page
    window.location.href = `/marketplace/listing/${listing.id}`;
  };

return (
    <div className="product-card">
      <img src={product.image} alt={product.name} />
      <h3>{product.name}</h3>
      <p>${product.price}</p>
      
      <QuickListButton
        name={product.name}
        price={product.price * 100000000} // Convert to satoshis
        image={product.image}
        onSuccess={handleListingSuccess}
      />
    </div>
  );
}
```

## Advanced Usage

### Complete Inventory Management

```tsx
import { QuickListButton } from 'bigblocks';
import { useState } from 'react';

interface InventoryItem {
  id: string;
  name: string;
  description: string;
  quantity: number;
  price: number;
  image: string;
  category: string;
}

export default function InventoryManagement() {
  const [inventory, setInventory] = useState<InventoryItem[]>([]);
  const [listedItems, setListedItems] = useState<Set<string>>(new Set());
  const [listings, setListings] = useState<MarketListing[]>([]);

const handleListingError = (item: InventoryItem, error: Error) => {
    console.error(`Failed to list ${item.name}:`, error);
    alert(`Failed to list item: ${error.message}`);
  };

return (
    <div className="inventory-management">
      <h1>Inventory Management</h1>
      
      <div className="inventory-grid">
        {inventory.map((item) => (
          <div key={item.id} className="inventory-item">
            <img src={item.image} alt={item.name} />
            <h3>{item.name}</h3>
            <p className="description">{item.description}</p>
            <p className="quantity">Stock: {item.quantity}</p>
            <p className="price">${item.price}</p>
            
            <div className="actions">
              {listedItems.has(item.id) ? (
                <span className="listed-badge">✓ Listed</span>
              ) : (
                <QuickListButton
                  name={item.name}
                  price={item.price * 100000000}
                  description={item.description}
                  image={item.image}
                  category={item.category}
                  onSuccess={(listing) => handleQuickList(item, listing)}
                  onError={(error) => handleListingError(item, error)}
                  variant="outline"
                  size="sm"
                />
              )}
            </div>
          </div>
        ))}
      </div>
      
      {listings.length > 0 && (
        <div className="active-listings">
          <h2>Active Listings ({listings.length})</h2>
          <ul>
            {listings.map((listing) => (
              <li key={listing.id}>
                <a href={`/marketplace/listing/${listing.id}`}>
                  {listing.name} - {listing.price / 100000000} BSV
                </a>
              </li>
            ))}
          </ul>
        </div>
      )}
    </div>
  );
}
```

### Multi-Currency Quick Listing

```tsx
import { QuickListButton } from 'bigblocks';
import { useState } from 'react';

export default function MultiCurrencyListing() {
  const [currency, setCurrency] = useState<'BSV' | 'USD'>('BSV');
  const [exchangeRate, setExchangeRate] = useState(45); // USD per BSV

return (
    <div className="multi-currency-listing">
      <div className="currency-selector">
        <label>
          List prices in:
          <select value={currency} onChange={(e) => setCurrency(e.target.value as any)}>
            <option value="BSV">BSV</option>
            <option value="USD">USD</option>
          </select>
        </label>
      </div>
      
      <div className="products">
        {products.map((product) => (
          <div key={product.id} className="product">
            <h3>{product.name}</h3>
            <p>
              {currency === 'BSV' 
                ? `${product.priceBSV} BSV`
                : `$${product.priceUSD}`
              }
            </p>
            
            <QuickListButton
              name={product.name}
              price={currency === 'BSV' ? product.priceBSV * 100000000 : product.priceUSD}
              currency={currency}
              onSuccess={(listing) => {
                console.log(`Listed in ${currency}:`, listing);
              }}
            />
          </div>
        ))}
      </div>
    </div>
  );
}
```

## Common Patterns

### Digital Asset Quick Listing

```tsx
import { QuickListButton } from 'bigblocks';

interface DigitalAsset {
  id: string;
  name: string;
  type: 'ebook' | 'music' | 'video' | 'software' | 'template';
  fileSize: string;
  preview: string;
  price: number;
}

export default function DigitalAssetStore() {
  const [assets, setAssets] = useState<DigitalAsset[]>([]);

const getAssetIcon = (type: string) => {
    const icons = {
      ebook: '📚',
      music: '🎵',
      video: '🎬',
      software: '💻',
      template: '📄'
    };
    return icons[type] || '📁';
  };

return (
    <div className="digital-asset-store">
      <h1>Digital Assets</h1>
      
      <div className="assets-grid">
        {assets.map((asset) => (
          <div key={asset.id} className="asset-card">
            <div className="asset-icon">{getAssetIcon(asset.type)}</div>
            <h3>{asset.name}</h3>
            <p className="file-size">{asset.fileSize}</p>
            <p className="price">{asset.price / 100000000} BSV</p>
            
            <a href={asset.preview} target="_blank" className="preview-link">
              Preview
            </a>
            
            <QuickListButton
              name={asset.name}
              price={asset.price}
              description={`Digital ${asset.type} - ${asset.fileSize}`}
              category="Digital Goods"
              onSuccess={(listing) => handleAssetListed(asset, listing)}
              variant="default"
              size="sm"
            />
          </div>
        ))}
      </div>
    </div>
  );
}
```

### NFT Collection Quick List

```tsx
import { QuickListButton } from 'bigblocks';

interface NFT {
  tokenId: string;
  name: string;
  collection: string;
  rarity: string;
  image: string;
  attributes: Record<string, any>;
}

export default function NFTCollection() {
  const [nfts, setNfts] = useState<NFT[]>([]);
  const [floorPrice, setFloorPrice] = useState(100000); // satoshis

const calculateNFTPrice = (nft: NFT) => {
    const rarityMultipliers = {
      common: 1,
      uncommon: 2,
      rare: 5,
      epic: 10,
      legendary: 25
    };
    
    return floorPrice * (rarityMultipliers[nft.rarity] || 1);
  };

return (
    <div className="nft-collection">
      <h1>My NFT Collection</h1>
      
      <div className="collection-stats">
        <p>Floor Price: {floorPrice / 100000000} BSV</p>
        <p>Total NFTs: {nfts.length}</p>
      </div>
      
      <div className="nft-grid">
        {nfts.map((nft) => (
          <div key={nft.tokenId} className="nft-item">
            <img src={nft.image} alt={nft.name} />
            <h3>{nft.name}</h3>
            <p className="collection">{nft.collection}</p>
            <p className={`rarity rarity-${nft.rarity}`}>{nft.rarity}</p>
            
            <QuickListButton
              name={nft.name}
              price={calculateNFTPrice(nft)}
              description={`${nft.collection} - ${nft.rarity}`}
              image={nft.image}
              category="NFTs"
              onSuccess={(listing) => handleNFTListing(nft, listing)}
              variant="outline"
            />
          </div>
        ))}
      </div>
    </div>
  );
}
```

### Bulk Quick Listing

```tsx
import { QuickListButton } from 'bigblocks';
import { useState } from 'react';

export default function BulkQuickListing() {
  const [selectedItems, setSelectedItems] = useState<Set<string>>(new Set());
  const [bulkPrice, setBulkPrice] = useState(10000); // satoshis
  const [isListing, setIsListing] = useState(false);

return (
    <div className="bulk-quick-listing">
      <div className="bulk-controls">
        <h2>Bulk Quick List</h2>
        <input 
          type="number"
          value={bulkPrice / 100000000}
          onChange={(e) => setBulkPrice(parseFloat(e.target.value) * 100000000)}
          placeholder="Bulk price in BSV"
        />
        <button 
          onClick={handleBulkList}
          disabled={selectedItems.size === 0 || isListing}
        >
          List {selectedItems.size} items
        </button>
      </div>
      
      <div className="inventory-selection">
        {inventory.map((item) => (
          <div key={item.id} className="selectable-item">
            <input 
              type="checkbox"
              checked={selectedItems.has(item.id)}
              onChange={(e) => {
                if (e.target.checked) {
                  setSelectedItems(new Set([...selectedItems, item.id]));
                } else {
                  const newSet = new Set(selectedItems);
                  newSet.delete(item.id);
                  setSelectedItems(newSet);
                }
              }}
            />
            
            <span>{item.name}</span>
            
            <QuickListButton
              name={item.name}
              price={bulkPrice}
              image={item.image}
              onSuccess={(listing) => {
                console.log(`Individual quick list: ${listing.name}`);
              }}
              size="sm"
              variant="ghost"
            />
          </div>
        ))}
      </div>
    </div>
  );
}
```

### Social Commerce Integration

```tsx
import { QuickListButton } from 'bigblocks';

export default function SocialCommerce() {
  const [userPosts, setUserPosts] = useState([]);

return (
    <div className="social-commerce">
      <h1>My Posts</h1>
      
      {userPosts.map((post) => (
        <div key={post.id} className="social-post">
          <img src={post.image} alt={post.title} />
          <h3>{post.title}</h3>
          <p>{post.description}</p>
          
          <div className="post-actions">
            <button className="like">👍 {post.likes}</button>
            <button className="share">🔄 Share</button>
            
            {!post.hasListing && (
              <QuickListButton
                name={post.title}
                price={50000} // Default price
                description={post.description}
                image={post.image}
                onSuccess={(listing) => handleSocialListing(post, listing)}
                variant="outline"
                size="sm"
              />
            )}
            
            {post.hasListing && (
              <a href={`/marketplace/listing/${post.listingId}`} className="view-listing">
                View Listing
              </a>
            )}
          </div>
        </div>
      ))}
    </div>
  );
}
```

## Authentication Requirements

The QuickListButton requires Bitcoin authentication for creating listings:

```tsx
import { 
  BitcoinAuthProvider, 
  BitcoinQueryProvider, 
  QuickListButton 
} from 'bigblocks';

function App() {
  return (
    <BitcoinQueryProvider>
      <BitcoinAuthProvider config={{ 
        apiUrl: '/api',
        walletMode: 'integrated' // Required for listing fees
      }}>
        <QuickListButton 
          name="My Item"
          price={10000}
          onSuccess={(listing) => {
            console.log('Listed:', listing);
          }}
        />
      </BitcoinAuthProvider>
    </BitcoinQueryProvider>
  );
}
```

## API Integration

The QuickListButton uses streamlined endpoints for quick listing creation:

### Quick List Endpoints

```typescript
// Create quick listing
POST /api/market/quick-list
{
  name: string;
  price: number;
  description?: string;
  image?: string;
  category?: string;
  currency: 'BSV' | 'USD';
  autoPublish: boolean;
}

Response:
{
  success: boolean;
  listing: MarketListing;
  fee: number; // Listing fee in satoshis
}

// Check listing availability
GET /api/market/quick-list/check?name={name}

Response:
{
  available: boolean;
  suggestions?: string[]; // Alternative names if taken
}
```

## Features

* **One-Click Listing**: Instant marketplace listing creation
* **Minimal Configuration**: Only name and price required
* **Auto-Publishing**: Listings go live immediately by default
* **Multi-Currency**: Support for BSV and USD pricing
* **Image Support**: Optional image URL for visual listings
* **Category Assignment**: Automatic or manual categorization
* **Success Callbacks**: Handle post-listing actions
* **Error Management**: Graceful error handling
* **Style Variants**: Multiple button styles for UI flexibility

## Error Handling

### Common Error Scenarios

```tsx
import { QuickListButton } from 'bigblocks';

export default function ErrorHandlingExample() {
  const handleListingError = (error: Error) => {
    if (error.message.includes('insufficient funds')) {
      alert('Not enough BSV for listing fee. Please add funds.');
    } else if (error.message.includes('duplicate')) {
      alert('An item with this name already exists.');
    } else if (error.message.includes('rate limit')) {
      alert('Too many listings. Please wait before creating more.');
    } else {
      alert(`Listing failed: ${error.message}`);
    }
  };

return (
    <QuickListButton 
      name="Test Item"
      price={10000}
      onError={handleListingError}
      onSuccess={(listing) => {
        console.log('Success!', listing);
      }}
    />
  );
}
```

## Styling

The component includes three style variants:

```css
/* Default variant */
.quick-list-button.default {
  background: var(--primary-color);
  color: white;
  padding: 0.5rem 1rem;
  border-radius: 0.375rem;
}

/* Outline variant */
.quick-list-button.outline {
  background: transparent;
  border: 1px solid var(--primary-color);
  color: var(--primary-color);
}

/* Ghost variant */
.quick-list-button.ghost {
  background: transparent;
  color: var(--text-color);
  padding: 0.25rem 0.5rem;
}

/* Size variations */
.quick-list-button.sm {
  font-size: 0.875rem;
  padding: 0.25rem 0.75rem;
}

.quick-list-button.lg {
  font-size: 1.125rem;
  padding: 0.75rem 1.5rem;
}

/* Loading state */
.quick-list-button:disabled {
  opacity: 0.6;
  cursor: not-allowed;
}
```

## Performance Optimization

### Debounced Listing Creation

```tsx
import { QuickListButton } from 'bigblocks';
import { useCallback, useRef } from 'react';

export default function DebouncedQuickList() {
  const pendingListings = useRef(new Map());

return (
    <QuickListButton 
      name={item.name}
      price={item.price}
      onSuccess={(listing) => {
        debouncedList(item);
        console.log('Listed:', listing);
      }}
    />
  );
}
```

## Troubleshooting

### Common Issues

**Button not responding**

* Verify Bitcoin authentication is configured
* Check user has sufficient balance for listing fee
* Ensure required props (name, price) are provided

**Listing creation fails**

* Check for duplicate item names
* Verify price is valid (> 0)
* Ensure image URL is accessible
* Check rate limiting hasn't been exceeded

**Auto-publish not working**

* Confirm autoPublish prop is true (default)
* Check user has listing permissions
* Verify marketplace API is accessible

**Success callback not firing**

* Ensure onSuccess prop is properly defined
* Check for JavaScript errors in console
* Verify listing was actually created

## Related Components

* [CreateListingButton](/docs/components/create-listing-button) - Full listing creation interface
* [QuickBuyButton](/docs/components/quick-buy-button) - One-click purchase button
* [CompactMarketTable](/docs/components/compact-market-table) - Display marketplace listings
* [MarketTable](/docs/components/market-table) - Full marketplace table

## API Reference

### QuickListButton Component

```typescript
interface QuickListButtonProps {
  name: string;
  price: number;
  description?: string;
  image?: string;
  category?: string;
  onSuccess?: (listing: MarketListing) => void;
  onError?: (error: Error) => void;
  variant?: 'default' | 'outline' | 'ghost';
  size?: 'sm' | 'md' | 'lg';
  autoPublish?: boolean;
  currency?: 'BSV' | 'USD';
  className?: string;
}
```

### Usage with React Query

```typescript
import { useMutation } from '@tanstack/react-query';
import { QuickListButton } from 'bigblocks';

return (
    <QuickListButton 
      name={item.name}
      price={item.price}
      onSuccess={(listing) => {
        console.log('Component callback:', listing);
      }}
    />
  );
}
```

# ProfileDropdownMenu
URL: /docs/components/profiles/profile-dropdown-menu

Comprehensive dropdown menu for user profiles with authentication states, wallet features, profile switching, and settings

***

title: ProfileDropdownMenu
description: Comprehensive dropdown menu for user profiles with authentication states, wallet features, profile switching, and settings
category: profiles
------------------

A comprehensive dropdown menu component for user profiles that handles authentication states, wallet features, profile switching, theme selection, and settings access.

## Installation

```bash
npx bigblocks add profile-dropdown-menu
```

## Import

```typescript
import { ProfileDropdownMenu } from 'bigblocks';
```

## Props

| Prop               | Type                                     | Required | Default    | Description                        |
| ------------------ | ---------------------------------------- | -------- | ---------- | ---------------------------------- |
| showWalletBalance  | `boolean`                                | No       | `true`     | Show wallet balance when available |
| walletBalance      | `BSVBalance`                             | No       | -          | Wallet balance data                |
| exchangeRate       | `number`                                 | No       | `50`       | BSV to USD exchange rate           |
| currency           | `'BSV' \| 'USD'`                         | No       | `'USD'`    | Display currency                   |
| useMenuIcon        | `boolean`                                | No       | `false`    | Use menu icon instead of avatar    |
| trigger            | `React.ReactNode`                        | No       | -          | Custom trigger element             |
| showThemeSwitch    | `boolean`                                | No       | `true`     | Show theme switcher in menu        |
| onViewProfile      | `() => void`                             | No       | -          | View profile callback              |
| onSettings         | `() => void`                             | No       | -          | Settings callback                  |
| onWalletUnlocked   | `() => void`                             | No       | -          | Wallet unlock callback             |
| onCreateAccount    | `() => void`                             | No       | -          | Create account callback            |
| onSignIn           | `() => void`                             | No       | -          | Sign in callback                   |
| additionalItems    | `React.ReactNode`                        | No       | -          | Extra menu items                   |
| align              | `'start' \| 'center' \| 'end'`           | No       | `'end'`    | Menu alignment                     |
| side               | `'top' \| 'right' \| 'bottom' \| 'left'` | No       | `'bottom'` | Menu side                          |
| signOutRedirectTo  | `string`                                 | No       | `'/'`      | Sign out redirect URL              |
| showProfileDetails | `boolean`                                | No       | `true`     | Show profile info in menu          |

## Basic Usage

```tsx
import { ProfileDropdownMenu } from 'bigblocks';

export default function Header() {
  return (
    <nav className="flex justify-between items-center p-4">
      <div className="text-xl font-bold">
        My App
      </div>
      
      <ProfileDropdownMenu
        showWalletBalance={true}
        showThemeSwitch={true}
        onViewProfile={() => router.push('/profile')}
        onSettings={() => router.push('/settings')}
      />
    </nav>
  );
}
```

## Advanced Usage

### Complete Header Integration

```tsx
import { ProfileDropdownMenu } from 'bigblocks';
import { useState, useEffect } from 'react';

export default function AppHeader() {
  const [walletBalance, setWalletBalance] = useState(null);
  const [exchangeRate, setExchangeRate] = useState(50);

useEffect(() => {
    // Load wallet balance
    const loadBalance = async () => {
      try {
        const balance = await fetchWalletBalance();
        setWalletBalance(balance);
      } catch (error) {
        console.error('Failed to load balance:', error);
      }
    };

// Load exchange rate
    const loadExchangeRate = async () => {
      try {
        const rate = await fetchBSVUSDRate();
        setExchangeRate(rate);
      } catch (error) {
        console.error('Failed to load exchange rate:', error);
      }
    };

loadBalance();
    loadExchangeRate();
  }, []);

const handleWalletUnlocked = () => {
    // Refresh balance when wallet is unlocked
    loadBalance();
    toast.success('Wallet unlocked successfully!');
  };

const handleCreateAccount = () => {
    router.push('/signup');
  };

const handleSignIn = () => {
    router.push('/signin');
  };

return (
    <header className="bg-white shadow-sm border-b">
      <div className="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8">
        <div className="flex justify-between items-center h-16">
          <div className="flex items-center">
            <h1 className="text-xl font-semibold">Bitcoin App</h1>
          </div>

<ProfileDropdownMenu
            showWalletBalance={true}
            walletBalance={walletBalance}
            exchangeRate={exchangeRate}
            currency="USD"
            showThemeSwitch={true}
            onViewProfile={() => router.push('/profile')}
            onSettings={() => router.push('/settings')}
            onWalletUnlocked={handleWalletUnlocked}
            onCreateAccount={handleCreateAccount}
            onSignIn={handleSignIn}
            signOutRedirectTo="/home"
          />
        </div>
      </div>
    </header>
  );
}
```

### Custom Trigger Element

```tsx
import { ProfileDropdownMenu } from 'bigblocks';
import { Button } from '@radix-ui/themes';

export default function CustomTriggerMenu() {
  return (
    <ProfileDropdownMenu
      trigger={
        <Button variant="soft" size="2">
          <PersonIcon />
          Account
        </Button>
      }
      onViewProfile={() => router.push('/profile')}
      onSettings={() => router.push('/settings')}
    />
  );
}
```

### Mobile Navigation Menu

```tsx
import { ProfileDropdownMenu } from 'bigblocks';

export default function MobileHeader() {
  return (
    <header className="md:hidden bg-white shadow-sm">
      <div className="flex justify-between items-center p-4">
        <h1 className="text-lg font-semibold">App</h1>
        
        <ProfileDropdownMenu
          useMenuIcon={true}
          additionalItems={
            <>
              <DropdownMenu.Item onClick={() => router.push('/about')}>
                <InfoCircledIcon className="mr-2 h-4 w-4" />
                About
              </DropdownMenu.Item>
              <DropdownMenu.Item onClick={() => router.push('/help')}>
                <QuestionMarkCircledIcon className="mr-2 h-4 w-4" />
                Help
              </DropdownMenu.Item>
              <DropdownMenu.Item onClick={() => router.push('/contact')}>
                <ChatBubbleIcon className="mr-2 h-4 w-4" />
                Contact
              </DropdownMenu.Item>
            </>
          }
        />
      </div>
    </header>
  );
}
```

### Dashboard Layout

```tsx
import { ProfileDropdownMenu } from 'bigblocks';

export default function Dashboard() {
  const [currency, setCurrency] = useState('USD');

return (
    <div className="min-h-screen bg-gray-50">
      <nav className="bg-white shadow">
        <div className="max-w-7xl mx-auto px-4">
          <div className="flex justify-between h-16">
            <div className="flex items-center space-x-8">
              <h1 className="text-xl font-bold">Dashboard</h1>
              
              <div className="hidden md:flex space-x-4">
                <a href="/dashboard" className="text-gray-900">Overview</a>
                <a href="/transactions" className="text-gray-500">Transactions</a>
                <a href="/ordinals" className="text-gray-500">Ordinals</a>
              </div>
            </div>

<div className="flex items-center space-x-4">
              <select
                value={currency}
                onChange={(e) => setCurrency(e.target.value)}
                className="text-sm border rounded px-2 py-1"
              >
                <option value="USD">USD</option>
                <option value="BSV">BSV</option>
              </select>

<ProfileDropdownMenu
                currency={currency}
                showWalletBalance={true}
                onViewProfile={() => router.push('/profile')}
                onSettings={() => router.push('/settings')}
              />
            </div>
          </div>
        </div>
      </nav>

<main className="max-w-7xl mx-auto py-6 px-4">
        {/* Dashboard content */}
      </main>
    </div>
  );
}
```

### Admin Interface

```tsx
import { ProfileDropdownMenu } from 'bigblocks';

export default function AdminHeader({ user }) {
  const isAdmin = user?.role === 'admin';

return (
    <header className="bg-gray-900 text-white">
      <div className="max-w-7xl mx-auto px-4">
        <div className="flex justify-between items-center h-16">
          <div className="flex items-center space-x-4">
            <h1 className="text-xl font-bold">Admin Panel</h1>
            {isAdmin && (
              <span className="bg-red-600 text-xs px-2 py-1 rounded">
                ADMIN
              </span>
            )}
          </div>

<ProfileDropdownMenu
            showWalletBalance={false} // Hide wallet for admin
            additionalItems={
              isAdmin ? (
                <>
                  <DropdownMenu.Separator />
                  <DropdownMenu.Item onClick={() => router.push('/admin/users')}>
                    <PersonIcon className="mr-2 h-4 w-4" />
                    Manage Users
                  </DropdownMenu.Item>
                  <DropdownMenu.Item onClick={() => router.push('/admin/settings')}>
                    <GearIcon className="mr-2 h-4 w-4" />
                    System Settings
                  </DropdownMenu.Item>
                  <DropdownMenu.Item onClick={() => router.push('/admin/logs')}>
                    <FileTextIcon className="mr-2 h-4 w-4" />
                    System Logs
                  </DropdownMenu.Item>
                </>
              ) : null
            }
            onSettings={() => router.push('/admin/settings')}
            signOutRedirectTo="/admin/login"
          />
        </div>
      </div>
    </header>
  );
}
```

### E-commerce Integration

```tsx
import { ProfileDropdownMenu } from 'bigblocks';

export default function StoreHeader({ cartItems }) {
  return (
    <header className="bg-white shadow-sm">
      <div className="max-w-7xl mx-auto px-4">
        <div className="flex justify-between items-center h-16">
          <div className="flex items-center space-x-8">
            <h1 className="text-xl font-bold">Bitcoin Store</h1>
            <nav className="hidden md:flex space-x-6">
              <a href="/products">Products</a>
              <a href="/categories">Categories</a>
              <a href="/deals">Deals</a>
            </nav>
          </div>

<div className="flex items-center space-x-4">
            <button className="relative p-2">
              <ShoppingCartIcon className="h-6 w-6" />
              {cartItems.length > 0 && (
                <span className="absolute -top-1 -right-1 bg-red-500 text-white text-xs rounded-full h-5 w-5 flex items-center justify-center">
                  {cartItems.length}
                </span>
              )}
            </button>

<ProfileDropdownMenu
              showWalletBalance={true}
              additionalItems={
                <>
                  <DropdownMenu.Item onClick={() => router.push('/orders')}>
                    <BoxIcon className="mr-2 h-4 w-4" />
                    My Orders
                  </DropdownMenu.Item>
                  <DropdownMenu.Item onClick={() => router.push('/wishlist')}>
                    <HeartIcon className="mr-2 h-4 w-4" />
                    Wishlist
                  </DropdownMenu.Item>
                </>
              }
              onViewProfile={() => router.push('/account')}
              onSettings={() => router.push('/account/settings')}
            />
          </div>
        </div>
      </div>
    </header>
  );
}
```

## Authentication States

The component automatically handles different authentication states:

### 1. Authenticated User

* Shows avatar with initials or profile image
* Displays wallet balance (if enabled)
* Profile details and switcher
* Theme selection
* Settings and sign out options

### 2. Has Local Backup

* Shows "Unlock" button
* Password dialog to decrypt backup
* Seamless sign-in flow after unlock

### 3. New User

* Shows "Sign Up" button
* Create account option
* Sign in option

## Menu Sections

### Wallet Overview

```typescript
interface BSVBalance {
  confirmed: number;    // Confirmed satoshis
  unconfirmed: number;  // Unconfirmed satoshis
  total: number;        // Total satoshis
}
```

### Profile Information

* Avatar display with fallback initials
* Profile name and alternate name
* Bitcoin address preview
* Publication status indicator

### Address Copying

Quick copy buttons for:

* **Payment Address**: Default receiving address
* **Ordinals Address**: NFT/inscription address
* **Identity Address**: BAP identity address

### Profile Switcher

* List of all user profiles
* Active profile indicator
* Switch profile functionality
* Create new profile option

### Theme Selection

Built-in theme options:

* **Light/Dark modes**
* **Bitcoin themes**: Orange, Purple, Blue, Mint, Ruby, Cyan, Gold, Bronze

## Wallet States

### Locked Wallet

```tsx
// Shows lock icon in menu
<ProfileDropdownMenu
  onWalletUnlocked={() => {
    // Called when user successfully unlocks wallet
    refreshWalletData();
    toast.success('Wallet unlocked!');
  }}
/>
```

### Unlocked Wallet

```tsx
// Shows balance and "Active" badge
<ProfileDropdownMenu
  showWalletBalance={true}
  walletBalance={{
    confirmed: 100000000, // 1 BSV in satoshis
    unconfirmed: 0,
    total: 100000000
  }}
  exchangeRate={50} // $50 per BSV
  currency="USD"
/>
```

## Common Patterns

### Responsive Header

```tsx
import { ProfileDropdownMenu } from 'bigblocks';

export default function ResponsiveHeader() {
  const [isMobile, setIsMobile] = useState(false);

useEffect(() => {
    const checkMobile = () => {
      setIsMobile(window.innerWidth < 768);
    };
    
    checkMobile();
    window.addEventListener('resize', checkMobile);
    return () => window.removeEventListener('resize', checkMobile);
  }, []);

return (
    <header className="bg-white shadow">
      <div className="max-w-7xl mx-auto px-4">
        <div className="flex justify-between items-center h-16">
          <h1 className="text-xl font-bold">My App</h1>
          
          <ProfileDropdownMenu
            useMenuIcon={isMobile}
            showWalletBalance={!isMobile} // Hide balance on mobile
            additionalItems={
              isMobile ? (
                <>
                  <DropdownMenu.Item onClick={() => router.push('/about')}>
                    About
                  </DropdownMenu.Item>
                  <DropdownMenu.Item onClick={() => router.push('/contact')}>
                    Contact
                  </DropdownMenu.Item>
                </>
              ) : null
            }
          />
        </div>
      </div>
    </header>
  );
}
```

### Multi-language Support

```tsx
import { ProfileDropdownMenu } from 'bigblocks';

export default function InternationalHeader() {
  const { t, locale } = useTranslation();

return (
    <ProfileDropdownMenu
      additionalItems={
        <>
          <DropdownMenu.Sub>
            <DropdownMenu.SubTrigger>
              <GlobeIcon className="mr-2 h-4 w-4" />
              {t('language')}
            </DropdownMenu.SubTrigger>
            <DropdownMenu.SubContent>
              <DropdownMenu.Item onClick={() => setLocale('en')}>
                English
              </DropdownMenu.Item>
              <DropdownMenu.Item onClick={() => setLocale('es')}>
                Español
              </DropdownMenu.Item>
              <DropdownMenu.Item onClick={() => setLocale('fr')}>
                Français
              </DropdownMenu.Item>
            </DropdownMenu.SubContent>
          </DropdownMenu.Sub>
        </>
      }
    />
  );
}
```

### Notification Integration

```tsx
import { ProfileDropdownMenu } from 'bigblocks';

export default function NotificationHeader({ notifications }) {
  const unreadCount = notifications.filter(n => !n.read).length;

return (
    <div className="flex items-center space-x-4">
      <button className="relative p-2">
        <BellIcon className="h-6 w-6" />
        {unreadCount > 0 && (
          <span className="absolute -top-1 -right-1 bg-red-500 text-white text-xs rounded-full h-5 w-5 flex items-center justify-center">
            {unreadCount}
          </span>
        )}
      </button>

<ProfileDropdownMenu
        additionalItems={
          <>
            <DropdownMenu.Item onClick={() => router.push('/notifications')}>
              <BellIcon className="mr-2 h-4 w-4" />
              Notifications
              {unreadCount > 0 && (
                <span className="ml-auto bg-red-500 text-white text-xs rounded-full px-2 py-1">
                  {unreadCount}
                </span>
              )}
            </DropdownMenu.Item>
          </>
        }
      />
    </div>
  );
}
```

## Customization Options

### Menu Position

```tsx
<ProfileDropdownMenu
  align="start"    // left, center, right
  side="bottom"    // top, right, bottom, left
/>
```

### Custom Styling

```tsx
<ProfileDropdownMenu
  trigger={
    <Button 
      variant="ghost" 
      className="rounded-full"
      size="1"
    >
      <Avatar 
        src={user?.image} 
        fallback={user?.name?.[0] || '?'}
        size="1"
      />
    </Button>
  }
/>
```

## Features

* **Authentication State Management**: Automatically adapts to user auth status
* **Wallet Integration**: Display balance, lock/unlock functionality
* **Profile Management**: Switch between profiles, view/edit profile
* **Theme Selection**: Built-in Bitcoin-inspired themes
* **Address Utilities**: Quick copy for different address types
* **Responsive Design**: Mobile-friendly with menu icon option
* **Extensible**: Add custom menu items easily
* **Accessibility**: Full keyboard navigation and screen reader support

## Security Considerations

* Password fields are properly secured
* Sensitive data cleared on sign out
* Session security maintained
* No private keys exposed in UI

## Best Practices

1. **Consistent Placement**: Usually top-right corner of header
2. **Mobile Optimization**: Use menu icon on smaller screens
3. **Clear Visual States**: Distinguish between auth states clearly
4. **Quick Access**: Most common actions easily reachable
5. **Extension Points**: Use additionalItems for app-specific features

## Accessibility

* Full keyboard navigation support
* Screen reader compatible
* Focus management in dialogs
* High contrast mode support
* Clear visual state indicators

## Troubleshooting

### Menu Not Opening

* Check that component is properly wrapped in providers
* Verify no conflicting z-index styles
* Ensure proper event handling setup

### Balance Not Showing

* Verify `showWalletBalance` is true
* Check wallet balance data format
* Ensure wallet is unlocked if required

### Theme Switch Not Working

* Verify theme provider is properly configured
* Check that `showThemeSwitch` is true
* Ensure theme persistence is set up

## Related Components

* [ProfileViewer](/docs/components/profile-viewer) - Display full profile details
* [ProfileSwitcher](/docs/components/profile-switcher) - Dedicated profile switching
* [WalletOverview](/docs/components/wallet-overview) - Detailed wallet information
* [ThemeSelector](/docs/components/theme-selector) - Standalone theme selection

## API Integration

Works with authentication and profile APIs:

```typescript
// Get current user
GET /api/auth/session

// Switch profile
POST /api/profiles/switch

// Sign out
POST /api/auth/signout

// Get wallet balance
GET /api/wallet/balance
```

## Notes for Improvement

**Enhanced Implementation**: The actual component provides more sophisticated features than the basic prompt described:

* Advanced authentication state handling with multiple backup types
* Comprehensive wallet integration with BSV balance display
* Better theme system with 8+ Bitcoin-inspired color schemes
* More robust profile switching with validation
* Enhanced accessibility and keyboard navigation
* Better mobile responsiveness with adaptive layouts

# ProfileEditor
URL: /docs/components/profiles/profile-editor

Edit BAP profile information with validation, image preview, and save/cancel actions

***

title: ProfileEditor
description: Edit BAP profile information with validation, image preview, and save/cancel actions
category: profiles
------------------

A component for editing BAP (Bitcoin Attestation Protocol) profile information, including name, description, image URL, and other profile fields with validation and preview functionality.

## Installation

```bash
npx bigblocks add profile-editor
```

## Import

```typescript
import { ProfileEditor } from 'bigblocks';
```

## Props

| Prop                 | Type                                               | Required | Default     | Description                             |
| -------------------- | -------------------------------------------------- | -------- | ----------- | --------------------------------------- |
| profile              | `ProfileInfo`                                      | Yes      | -           | Current profile data to edit            |
| onSave               | `(updates: Partial<ProfileInfo>) => Promise<void>` | Yes      | -           | Save handler for profile updates        |
| onCancel             | `() => void`                                       | No       | -           | Cancel button click handler             |
| allowImageUpload     | `boolean`                                          | No       | `true`      | Enable image URL input field            |
| maxNameLength        | `number`                                           | No       | `50`        | Maximum character limit for name        |
| maxDescriptionLength | `number`                                           | No       | `160`       | Maximum character limit for description |
| className            | `string`                                           | No       | -           | Additional CSS classes                  |
| variant              | `'surface' \| 'classic' \| 'ghost'`                | No       | `'surface'` | Visual style variant                    |
| size                 | `'1' \| '2' \| '3' \| '4'`                         | No       | `'3'`       | Component size                          |

## Basic Usage

```tsx
import { ProfileEditor } from 'bigblocks';

export default function EditProfile() {
  const [profile, setProfile] = useState({
    id: 'bap-123',
    address: '1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa',
    isPublished: false,
    name: 'Bitcoin Builder',
    description: 'Building the future of money',
    image: 'https://api.dicebear.com/7.x/avataaars/svg?seed=builder'
  });

const handleCancel = () => {
    console.log('Edit cancelled');
    // Navigate back or close modal
  };

return (
    <ProfileEditor
      profile={profile}
      onSave={handleSave}
      onCancel={handleCancel}
    />
  );
}
```

## Advanced Usage

### Complete Profile Editing

```tsx
import { ProfileEditor } from 'bigblocks';

export default function CompleteProfileEditor() {
  const [profile, setProfile] = useState({
    id: 'bap-456',
    address: '1BvBMSEYstWetqTFn5Au4m4GFg7xJaNVN2',
    isPublished: true,
    '@context': 'https://schema.org',
    '@type': 'Person',
    name: 'Satoshi Nakamoto',
    alternateName: '@satoshi',
    description: 'Creator of Bitcoin and digital currency pioneer.',
    image: 'https://api.dicebear.com/7.x/avataaars/svg?seed=satoshi',
    banner: 'https://images.unsplash.com/photo-1640340434855-6084b1f4901c',
    url: 'https://bitcoin.org',
    email: 'satoshi@gmx.com',
    paymail: 'satoshi@relayx.io',
    givenName: 'Satoshi',
    familyName: 'Nakamoto',
    location: 'Worldwide'
  });

const handleSave = async (updates) => {
    try {
      // Validate updates
      if (updates.name && updates.name.length < 3) {
        throw new Error('Name must be at least 3 characters');
      }

// Save to blockchain if profile is published
      if (profile.isPublished) {
        await publishProfileUpdate(profile.id, updates);
      } else {
        await saveProfileDraft(profile.id, updates);
      }

setProfile(prev => ({ ...prev, ...updates }));
      toast.success('Profile updated successfully!');
    } catch (error) {
      toast.error(`Failed to save: ${error.message}`);
    }
  };

return (
    <ProfileEditor
      profile={profile}
      onSave={handleSave}
      onCancel={() => router.back()}
      maxNameLength={50}
      maxDescriptionLength={280}
      variant="surface"
      size="4"
    />
  );
}
```

### With Loading State

```tsx
import { ProfileEditor } from 'bigblocks';
import { useState } from 'react';

export default function ProfileEditorWithLoading() {
  const [profile, setProfile] = useState(null);
  const [saving, setSaving] = useState(false);
  const [loading, setLoading] = useState(true);

useEffect(() => {
    const loadProfile = async () => {
      try {
        const profileData = await fetchProfile();
        setProfile(profileData);
      } catch (error) {
        console.error('Failed to load profile:', error);
      } finally {
        setLoading(false);
      }
    };

loadProfile();
  }, []);

if (loading) {
    return <div>Loading profile...</div>;
  }

if (!profile) {
    return <div>Profile not found</div>;
  }

return (
    <div>
      {saving && (
        <div className="mb-4 p-3 bg-blue-100 text-blue-700 rounded">
          Saving profile...
        </div>
      )}
      
      <ProfileEditor
        profile={profile}
        onSave={handleSave}
        onCancel={() => router.back()}
      />
    </div>
  );
}
```

### In Modal Dialog

```tsx
import { ProfileEditor, Modal } from 'bigblocks';

export default function ProfileEditModal({ isOpen, onClose, profile }) {
  const [hasChanges, setHasChanges] = useState(false);

const handleCancel = () => {
    if (hasChanges) {
      const confirmed = confirm('You have unsaved changes. Are you sure you want to cancel?');
      if (!confirmed) return;
    }
    
    setHasChanges(false);
    onClose();
  };

return (
    <Modal isOpen={isOpen} onClose={handleCancel}>
      <div className="p-6">
        <h2 className="text-xl font-semibold mb-4">Edit Profile</h2>
        
        <ProfileEditor
          profile={profile}
          onSave={handleSave}
          onCancel={handleCancel}
          onChange={() => setHasChanges(true)}
        />
      </div>
    </Modal>
  );
}
```

### Different Variants and Sizes

```tsx
import { ProfileEditor } from 'bigblocks';

export default function ProfileEditorVariants({ profile }) {
  const handleSave = async (updates) => {
    await updateProfile(profile.id, updates);
  };

return (
    <div className="space-y-8">
      {/* Surface variant (default) */}
      <div>
        <h3>Surface Variant</h3>
        <ProfileEditor
          profile={profile}
          onSave={handleSave}
          variant="surface"
          size="3"
        />
      </div>

{/* Classic variant */}
      <div>
        <h3>Classic Variant</h3>
        <ProfileEditor
          profile={profile}
          onSave={handleSave}
          variant="classic"
          size="3"
        />
      </div>

{/* Ghost variant */}
      <div>
        <h3>Ghost Variant</h3>
        <ProfileEditor
          profile={profile}
          onSave={handleSave}
          variant="ghost"
          size="3"
        />
      </div>
    </div>
  );
}
```

### Custom Validation

```tsx
import { ProfileEditor } from 'bigblocks';

export default function ValidatedProfileEditor({ profile }) {
  const [errors, setErrors] = useState({});

const validateProfile = (updates) => {
    const newErrors = {};

if (updates.name !== undefined) {
      if (!updates.name || updates.name.trim().length < 3) {
        newErrors.name = 'Name must be at least 3 characters';
      }
      if (updates.name && updates.name.length > 50) {
        newErrors.name = 'Name must be less than 50 characters';
      }
    }

if (updates.description !== undefined && updates.description) {
      if (updates.description.length > 280) {
        newErrors.description = 'Description must be less than 280 characters';
      }
    }

if (updates.email !== undefined && updates.email) {
      const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
      if (!emailRegex.test(updates.email)) {
        newErrors.email = 'Please enter a valid email address';
      }
    }

if (updates.url !== undefined && updates.url) {
      try {
        new URL(updates.url);
      } catch {
        newErrors.url = 'Please enter a valid URL';
      }
    }

return newErrors;
  };

const handleSave = async (updates) => {
    const validationErrors = validateProfile(updates);
    
    if (Object.keys(validationErrors).length > 0) {
      setErrors(validationErrors);
      return;
    }

setErrors({});

try {
      await updateProfile(profile.id, updates);
      toast.success('Profile saved successfully!');
    } catch (error) {
      toast.error('Failed to save profile');
    }
  };

return (
    <div>
      {Object.keys(errors).length > 0 && (
        <div className="mb-4 p-3 bg-red-100 text-red-700 rounded">
          <ul>
            {Object.values(errors).map((error, index) => (
              <li key={index}>• {error}</li>
            ))}
          </ul>
        </div>
      )}
      
      <ProfileEditor
        profile={profile}
        onSave={handleSave}
        maxNameLength={50}
        maxDescriptionLength={280}
      />
    </div>
  );
}
```

### Auto-save Implementation

```tsx
import { ProfileEditor } from 'bigblocks';
import { useDebounce } from 'use-debounce';

export default function AutoSaveProfileEditor({ profile }) {
  const [pendingUpdates, setPendingUpdates] = useState({});
  const [debouncedUpdates] = useDebounce(pendingUpdates, 2000);
  const [lastSaved, setLastSaved] = useState(null);

// Auto-save when debounced updates change
  useEffect(() => {
    if (Object.keys(debouncedUpdates).length > 0) {
      autoSave(debouncedUpdates);
    }
  }, [debouncedUpdates]);

const handleChange = (updates) => {
    setPendingUpdates(prev => ({ ...prev, ...updates }));
  };

return (
    <div>
      <div className="mb-4 flex justify-between items-center">
        <div className="text-sm text-gray-500">
          {lastSaved ? (
            `Last saved: ${lastSaved.toLocaleTimeString()}`
          ) : (
            'No changes saved yet'
          )}
        </div>
        
        {Object.keys(pendingUpdates).length > 0 && (
          <div className="text-sm text-orange-600">
            Unsaved changes...
          </div>
        )}
      </div>

<ProfileEditor
        profile={profile}
        onSave={handleManualSave}
        onChange={handleChange}
      />
    </div>
  );
}
```

## Common Patterns

### Profile Setup Flow

```tsx
import { ProfileEditor } from 'bigblocks';

export default function ProfileSetupFlow() {
  const [step, setStep] = useState(1);
  const [profile, setProfile] = useState({
    id: 'new-profile',
    address: '',
    isPublished: false,
    name: '',
    description: '',
    image: ''
  });

const handleSave = async (updates) => {
    const updatedProfile = { ...profile, ...updates };
    
    // Validate required fields for next step
    if (step === 1 && (!updatedProfile.name || updatedProfile.name.length < 3)) {
      toast.error('Please enter a valid name to continue');
      return;
    }

setProfile(updatedProfile);

if (step < 3) {
      setStep(step + 1);
    } else {
      // Final save
      await createProfile(updatedProfile);
      router.push('/profile');
    }
  };

const getStepTitle = () => {
    switch (step) {
      case 1: return 'Basic Information';
      case 2: return 'Profile Image';
      case 3: return 'Description';
      default: return 'Profile Setup';
    }
  };

return (
    <div className="max-w-2xl mx-auto">
      <div className="mb-6">
        <h1 className="text-2xl font-bold">Set Up Your Profile</h1>
        <p className="text-gray-600">Step {step} of 3: {getStepTitle()}</p>
      </div>

<ProfileEditor
        profile={profile}
        onSave={handleSave}
        onCancel={() => step > 1 ? setStep(step - 1) : router.back()}
        maxNameLength={50}
        maxDescriptionLength={160}
      />
    </div>
  );
}
```

### Organization Profile Editor

```tsx
import { ProfileEditor } from 'bigblocks';

export default function OrganizationEditor({ orgProfile }) {
  const handleSave = async (updates) => {
    // Add organization-specific validation
    if (updates['@type'] && updates['@type'] !== 'Organization') {
      toast.error('This editor is for organizations only');
      return;
    }

try {
      await updateOrganizationProfile(orgProfile.id, updates);
      toast.success('Organization profile updated!');
    } catch (error) {
      toast.error('Failed to update organization');
    }
  };

return (
    <div>
      <h2 className="text-xl font-semibold mb-4">Edit Organization</h2>
      
      <ProfileEditor
        profile={orgProfile}
        onSave={handleSave}
        maxNameLength={100} // Longer names for organizations
        maxDescriptionLength={500} // Longer descriptions
        allowImageUpload={true}
      />
    </div>
  );
}
```

### Bulk Profile Updates

```tsx
import { ProfileEditor } from 'bigblocks';

export default function BulkProfileEditor({ profiles }) {
  const [selectedProfile, setSelectedProfile] = useState(profiles[0]);
  const [allUpdates, setAllUpdates] = useState({});

const handleSave = async (updates) => {
    // Save updates for current profile
    setAllUpdates(prev => ({
      ...prev,
      [selectedProfile.id]: { ...prev[selectedProfile.id], ...updates }
    }));

toast.success('Changes saved for ' + selectedProfile.name);
  };

return (
    <div className="grid grid-cols-1 lg:grid-cols-4 gap-6">
      {/* Profile selector */}
      <div className="lg:col-span-1">
        <h3 className="font-semibold mb-3">Select Profile</h3>
        <div className="space-y-2">
          {profiles.map(profile => (
            <button
              key={profile.id}
              onClick={() => setSelectedProfile(profile)}
              className={`w-full text-left p-3 rounded ${
                selectedProfile.id === profile.id
                  ? 'bg-blue-100 text-blue-700'
                  : 'bg-gray-50 hover:bg-gray-100'
              }`}
            >
              {profile.name}
              {allUpdates[profile.id] && (
                <span className="text-orange-600 text-sm ml-2">•</span>
              )}
            </button>
          ))}
        </div>

{Object.keys(allUpdates).length > 0 && (
          <button
            onClick={applyAllUpdates}
            className="w-full mt-4 px-4 py-2 bg-green-600 text-white rounded hover:bg-green-700"
          >
            Apply All Changes ({Object.keys(allUpdates).length})
          </button>
        )}
      </div>

{/* Profile editor */}
      <div className="lg:col-span-3">
        <ProfileEditor
          key={selectedProfile.id} // Force re-render when profile changes
          profile={selectedProfile}
          onSave={handleSave}
        />
      </div>
    </div>
  );
}
```

## Form Fields

The ProfileEditor includes these editable fields:

### Basic Fields

* **Name**: User's display name (required)
* **Description**: Bio or profile description
* **Image URL**: Avatar image URL

### Extended Fields (if supported by profile schema)

* **Alternate Name**: Username or handle
* **Email**: Contact email address
* **Website URL**: Personal or company website
* **Paymail**: Bitcoin paymail address
* **Location**: Geographic location

## Validation Rules

### Name Field

* **Required**: Must not be empty
* **Minimum Length**: 3 characters (configurable)
* **Maximum Length**: 50 characters (configurable)
* **Character Set**: Alphanumeric and common punctuation

### Description Field

* **Optional**: Can be empty
* **Maximum Length**: 160 characters (configurable)
* **Line Breaks**: Preserved in saved data

### Image URL Field

* **Optional**: Can be empty
* **Format**: Must be valid URL if provided
* **Preview**: Shows image preview when valid URL entered

### Email Field

* **Optional**: Can be empty
* **Format**: Must be valid email format if provided
* **Validation**: Real-time email format checking

## Character Counters

* Live character count display
* Warning when approaching limit
* Error state when limit exceeded
* Visual indicator (color changes)

## Image Preview

* Real-time preview of avatar image
* Fallback to default avatar if URL invalid
* Loading state while image loads
* Error handling for broken images

## Features

* **Real-time Validation**: Immediate feedback on field requirements
* **Character Limits**: Configurable limits with live counters
* **Image Preview**: Live preview of avatar images
* **Save/Cancel Actions**: Clear action buttons with loading states
* **Error Handling**: Graceful handling of save failures
* **Responsive Design**: Works on desktop and mobile
* **Accessibility**: Screen reader support and keyboard navigation

## Accessibility

* Form labels and descriptions
* Keyboard navigation support
* Screen reader announcements
* High contrast support
* Focus indicators on interactive elements
* Error messages properly associated with fields

## Best Practices

1. **Validate Early**: Provide immediate feedback on field validation
2. **Save Often**: Consider auto-save for better user experience
3. **Handle Errors**: Gracefully handle network and validation errors
4. **Image Optimization**: Encourage users to use optimized images
5. **Privacy Guidance**: Inform users about data visibility

## Troubleshooting

### Save Not Working

* Check that `onSave` handler is provided and returns a Promise
* Verify network connectivity for API calls
* Check browser console for error messages

### Image Preview Not Showing

* Verify image URL is accessible and valid
* Check for CORS issues with external images
* Ensure image format is supported (JPEG, PNG, GIF, WebP)

### Validation Errors

* Check that validation rules match component props
* Verify maximum length settings are reasonable
* Ensure required fields are properly marked

## Related Components

* [ProfileViewer](/docs/components/profile-viewer) - Display profiles
* [ProfileManager](/docs/components/profile-manager) - Manage multiple profiles
* [ProfilePublisher](/docs/components/profile-publisher) - Publish to blockchain

## API Integration

The component integrates with profile management APIs:

```typescript
// Update profile
PUT /api/bap/profiles/{id}

// Create profile
POST /api/bap/profiles

// Validate profile data
POST /api/bap/profiles/validate
```

## Notes for Improvement

**Enhanced Implementation**: The actual component provides more sophisticated features than the basic prompt described:

* Uses complete ProfileInfo type with all schema.org fields
* Proper TypeScript integration with strict typing
* Better character validation and limits
* Multiple visual variants and sizes
* Improved error handling and user feedback
* Real-time image preview with fallback handling

# ProfileManager
URL: /docs/components/profiles/profile-manager

Complete profile management interface for viewing, editing, publishing, and switching between BAP profiles

***

title: ProfileManager
description: Complete profile management interface for viewing, editing, publishing, and switching between BAP profiles
category: profiles
------------------

A comprehensive profile management interface that provides a tabbed interface for viewing, editing, publishing, and switching between multiple BAP (Bitcoin Attestation Protocol) profiles.

## Installation

```bash
npx bigblocks add profile-manager
```

## Import

```typescript
import { ProfileManager } from 'bigblocks';
```

## Props

| Prop                 | Type                                               | Required | Default | Description                    |
| -------------------- | -------------------------------------------------- | -------- | ------- | ------------------------------ |
| user                 | `AuthUser`                                         | No       | -       | Current user with profiles     |
| onProfileUpdate      | `(profile: ProfileInfo) => void`                   | No       | -       | Profile update handler         |
| onProfilePublish     | `(profileId: string) => Promise<{ txid: string }>` | No       | -       | Publish profile to blockchain  |
| onProfileCreate      | `() => Promise<ProfileInfo>`                       | No       | -       | Create new profile handler     |
| onProfileSwitch      | `(profileId: string) => void`                      | No       | -       | Switch active profile handler  |
| showPublisher        | `boolean`                                          | No       | `true`  | Show publish tab               |
| maxProfiles          | `number`                                           | No       | `5`     | Maximum number of profiles     |
| className            | `string`                                           | No       | -       | Additional CSS classes         |
| enableProfileSync    | `boolean`                                          | No       | `false` | Enable profile synchronization |
| maxDiscoveryAttempts | `number`                                           | No       | `3`     | Max profile discovery attempts |

## Basic Usage

```tsx
import { ProfileManager } from 'bigblocks';
import { useAuth } from 'bigblocks';

export default function ProfileSettings() {
  const { user } = useAuth();

return (
    <div className="max-w-4xl mx-auto p-6">
      <h1 className="text-2xl font-bold mb-6">Profile Management</h1>
      
      <ProfileManager
        user={user}
        onProfileUpdate={(profile) => {
          console.log('Profile updated:', profile);
        }}
        onProfilePublish={async (profileId) => {
          console.log('Publishing profile:', profileId);
          // Return transaction ID after publishing
          return { txid: 'abc123...' };
        }}
        onProfileSwitch={(profileId) => {
          console.log('Switched to profile:', profileId);
        }}
      />
    </div>
  );
}
```

## Advanced Usage

### Complete Profile Management System

```tsx
import { ProfileManager } from 'bigblocks';
import { useState, useEffect } from 'react';

export default function AdvancedProfileManager() {
  const [user, setUser] = useState(null);
  const [loading, setLoading] = useState(true);

useEffect(() => {
    const loadUser = async () => {
      try {
        const userData = await fetchCurrentUser();
        setUser(userData);
      } catch (error) {
        console.error('Failed to load user:', error);
      } finally {
        setLoading(false);
      }
    };

loadUser();
  }, []);

if (loading) {
    return <div>Loading profile manager...</div>;
  }

return (
    <ProfileManager
      user={user}
      onProfileUpdate={handleProfileUpdate}
      onProfilePublish={handleProfilePublish}
      onProfileCreate={handleProfileCreate}
      onProfileSwitch={handleProfileSwitch}
      showPublisher={true}
      maxProfiles={10}
      enableProfileSync={true}
      maxDiscoveryAttempts={5}
    />
  );
}
```

### Organization Profile Management

```tsx
import { ProfileManager } from 'bigblocks';

export default function OrganizationProfileManager({ organization }) {
  const handleOrgProfileUpdate = async (profile) => {
    // Validate organization-specific fields
    if (!profile.legalName || !profile.address) {
      toast.error('Organization profiles require legal name and address');
      return;
    }

try {
      await updateOrganizationProfile(profile.id, profile);
      toast.success('Organization profile updated!');
    } catch (error) {
      toast.error('Failed to update organization profile');
    }
  };

const handleOrgProfilePublish = async (profileId) => {
    try {
      // Organization profiles require additional verification
      const verification = await verifyOrganization(profileId);
      
      if (!verification.verified) {
        toast.error('Organization verification required before publishing');
        throw new Error('Verification required');
      }

const result = await publishOrganizationProfile(profileId);
      toast.success('Organization profile published and verified!');
      return result;
    } catch (error) {
      toast.error('Failed to publish organization profile');
      throw error;
    }
  };

return (
    <div>
      <h2 className="text-xl font-semibold mb-4">Organization Profiles</h2>
      
      <ProfileManager
        user={organization}
        onProfileUpdate={handleOrgProfileUpdate}
        onProfilePublish={handleOrgProfilePublish}
        showPublisher={true}
        maxProfiles={3} // Limit for organizations
        className="border-2 border-blue-200 rounded-lg"
      />
    </div>
  );
}
```

### Multi-tenant Profile Management

```tsx
import { ProfileManager } from 'bigblocks';

export default function MultiTenantProfileManager({ tenantId }) {
  const [users, setUsers] = useState([]);
  const [selectedUser, setSelectedUser] = useState(null);

useEffect(() => {
    const loadTenantUsers = async () => {
      const tenantUsers = await fetchTenantUsers(tenantId);
      setUsers(tenantUsers);
      setSelectedUser(tenantUsers[0]);
    };

loadTenantUsers();
  }, [tenantId]);

return (
    <div className="grid grid-cols-1 lg:grid-cols-4 gap-6">
      {/* User selector */}
      <div className="lg:col-span-1">
        <h3 className="font-semibold mb-3">Select User</h3>
        <div className="space-y-2">
          {users.map(user => (
            <button
              key={user.id}
              onClick={() => setSelectedUser(user)}
              className={`w-full text-left p-3 rounded ${
                selectedUser?.id === user.id
                  ? 'bg-blue-100 text-blue-700'
                  : 'bg-gray-50 hover:bg-gray-100'
              }`}
            >
              {user.profiles[0]?.name || user.address}
            </button>
          ))}
        </div>
      </div>

{/* Profile manager */}
      <div className="lg:col-span-3">
        {selectedUser && (
          <ProfileManager
            key={selectedUser.id}
            user={selectedUser}
            onProfileUpdate={handleBulkProfileUpdate}
            showPublisher={false} // Disable for tenant management
            maxProfiles={3}
          />
        )}
      </div>
    </div>
  );
}
```

### Profile Manager with Sync

```tsx
import { ProfileManager } from 'bigblocks';

export default function SyncedProfileManager() {
  const [user, setUser] = useState(null);
  const [syncStatus, setSyncStatus] = useState('idle');

useEffect(() => {
    // Subscribe to profile sync events
    const unsubscribe = subscribeToProfileSync((event) => {
      switch (event.type) {
        case 'sync_started':
          setSyncStatus('syncing');
          break;
        case 'sync_completed':
          setSyncStatus('completed');
          // Reload user profiles
          loadUserProfiles();
          break;
        case 'sync_failed':
          setSyncStatus('failed');
          toast.error('Profile sync failed');
          break;
      }
    });

return unsubscribe;
  }, []);

return (
    <div>
      {syncStatus === 'syncing' && (
        <div className="mb-4 p-3 bg-blue-100 text-blue-700 rounded">
          Syncing profiles across devices...
        </div>
      )}
      
      {syncStatus === 'failed' && (
        <div className="mb-4 p-3 bg-red-100 text-red-700 rounded">
          Profile sync failed. Some changes may not be reflected.
        </div>
      )}
      
      <ProfileManager
        user={user}
        enableProfileSync={true}
        maxDiscoveryAttempts={5}
        onProfileUpdate={async (profile) => {
          await updateProfile(profile.id, profile);
          // Trigger sync after update
          await triggerProfileSync();
        }}
      />
    </div>
  );
}
```

## Tab Interface

The ProfileManager provides a tabbed interface with the following tabs:

### View Tab

* Displays current profile information
* Shows publication status
* Profile address and details
* Avatar and basic information

### Edit Tab

* Profile editing form
* Real-time validation
* Image URL input with preview
* Save/cancel actions

### Publish Tab (if `showPublisher` is true)

* Blockchain publishing interface
* Transaction status
* Publication confirmation
* TXID display after successful publish

### Switch Tab

* List of all user profiles
* Active profile indicator
* Switch profile actions
* Profile creation option

## Profile Creation

When creating new profiles:

```tsx
const handleProfileCreate = async () => {
  try {
    // Generate new profile
    const newProfile = {
      id: generateProfileId(),
      address: generateNewAddress(),
      isPublished: false,
      name: '',
      description: '',
      image: ''
    };

// Save to backend
    const savedProfile = await createProfile(newProfile);
    
    return savedProfile;
  } catch (error) {
    console.error('Profile creation failed:', error);
    throw error;
  }
};
```

## Profile Discovery

When `enableProfileSync` is true, the component will attempt to discover profiles across devices:

```tsx
const discoverProfiles = async (maxAttempts = 3) => {
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    try {
      const discoveredProfiles = await searchBlockchainProfiles(user.address);
      
      if (discoveredProfiles.length > 0) {
        // Merge with existing profiles
        await mergeDiscoveredProfiles(discoveredProfiles);
        break;
      }
    } catch (error) {
      if (attempt === maxAttempts) {
        console.error('Profile discovery failed after', maxAttempts, 'attempts');
      }
    }
  }
};
```

## Common Patterns

### Profile Management Dashboard

```tsx
import { ProfileManager, WalletOverview } from 'bigblocks';

export default function UserDashboard() {
  const { user } = useAuth();

return (
    <div className="min-h-screen bg-gray-50">
      <div className="max-w-6xl mx-auto py-8 px-4">
        <div className="grid grid-cols-1 lg:grid-cols-3 gap-8">
          {/* Profile management */}
          <div className="lg:col-span-2">
            <ProfileManager
              user={user}
              onProfileUpdate={handleProfileUpdate}
              onProfilePublish={handleProfilePublish}
            />
          </div>

{/* Wallet sidebar */}
          <div className="lg:col-span-1">
            <WalletOverview address={user?.address} />
          </div>
        </div>
      </div>
    </div>
  );
}
```

### Mobile Profile Manager

```tsx
import { ProfileManager } from 'bigblocks';

export default function MobileProfileManager({ user }) {
  return (
    <div className="min-h-screen bg-white">
      <div className="px-4 py-6">
        <h1 className="text-xl font-bold mb-4">Profile Settings</h1>
        
        <ProfileManager
          user={user}
          className="w-full"
          showPublisher={true}
          maxProfiles={3} // Limit for mobile
          onProfileUpdate={handleMobileProfileUpdate}
        />
      </div>
    </div>
  );
}
```

### Admin Profile Manager

```tsx
import { ProfileManager } from 'bigblocks';

export default function AdminProfileManager({ userToManage }) {
  const { user: adminUser } = useAuth();
  
  if (!adminUser?.isAdmin) {
    return <div>Access denied</div>;
  }

return (
    <div>
      <div className="mb-6 p-4 bg-yellow-100 text-yellow-800 rounded">
        <strong>Admin Mode:</strong> Managing profiles for {userToManage.address}
      </div>
      
      <ProfileManager
        user={userToManage}
        onProfileUpdate={async (profile) => {
          // Admin update with audit log
          await adminUpdateProfile(profile.id, profile, adminUser.id);
        }}
        onProfilePublish={async (profileId) => {
          // Admin publish with approval
          const result = await adminPublishProfile(profileId, adminUser.id);
          return result;
        }}
        showPublisher={true}
        maxProfiles={10}
      />
    </div>
  );
}
```

## User Data Structure

```typescript
interface AuthUser {
  id: string;
  address: string;
  idKey: string;
  profiles: ProfileInfo[];
  activeProfileId: string;
  ordinalsAddress?: string;
  identityAddress?: string;
}

interface ProfileInfo {
  id: string;
  address: string;
  isPublished: boolean;
  name?: string;
  description?: string;
  image?: string;
  // ... other profile fields
}
```

## Features

* **Tabbed Interface**: Organized tabs for view, edit, publish, and switch operations
* **Profile Creation**: Create new profiles with validation
* **Profile Switching**: Switch between multiple profiles seamlessly
* **Blockchain Publishing**: Publish profiles to Bitcoin blockchain
* **Profile Synchronization**: Sync profiles across devices (optional)
* **Profile Discovery**: Discover existing profiles on blockchain
* **Responsive Design**: Works on desktop and mobile devices
* **Real-time Updates**: Live updates when profiles change

## Publishing Process

1. **Validation**: Ensure profile has required fields
2. **Transaction Creation**: Create Bitcoin transaction with profile data
3. **Signing**: Sign transaction with profile's private key
4. **Broadcasting**: Broadcast transaction to Bitcoin network
5. **Confirmation**: Wait for transaction confirmation
6. **Status Update**: Update profile publication status

## Synchronization

When `enableProfileSync` is enabled:

* Profiles are synced across devices
* Changes are propagated to all connected devices
* Conflict resolution for simultaneous edits
* Backup and restore functionality

## Error Handling

The component handles various error scenarios:

* Network connectivity issues
* Invalid profile data
* Publishing failures
* Sync conflicts
* Validation errors

## Best Practices

1. **Profile Limits**: Set reasonable `maxProfiles` limits
2. **Validation**: Validate profile data before saving
3. **Error Feedback**: Provide clear error messages
4. **Loading States**: Show loading indicators for async operations
5. **Confirmation**: Confirm destructive actions like publishing

## Troubleshooting

### Profiles Not Loading

* Check user authentication status
* Verify backend API connectivity
* Check browser console for errors

### Publishing Failures

* Verify Bitcoin network connectivity
* Check private key access
* Ensure sufficient network fees

### Sync Issues

* Check network connectivity
* Verify sync service status
* Clear local cache if needed

## Related Components

* [ProfileViewer](/docs/components/profile-viewer) - Display profiles
* [ProfileEditor](/docs/components/profile-editor) - Edit profiles
* [ProfileSwitcher](/docs/components/profile-switcher) - Quick profile switching
* [ProfileDropdownMenu](/docs/components/profile-dropdown-menu) - Profile selection menu

## API Integration

The component integrates with profile management APIs:

```typescript
// Get user with profiles
GET /api/users/{id}/profiles

// Update profile
PUT /api/profiles/{id}

// Publish profile
POST /api/profiles/{id}/publish

// Create profile
POST /api/profiles

// Switch active profile
POST /api/users/{id}/switch-profile
```

## Notes for Improvement

**Enhanced Implementation**: The actual component provides more sophisticated features than the basic prompt described:

* Complete tabbed interface for all profile operations
* Profile synchronization and discovery capabilities
* Better error handling and user feedback
* Support for multiple profile types (Person/Organization)
* Advanced publishing workflow with transaction tracking
* Real-time profile updates and conflict resolution

# ProfilePopover
URL: /docs/components/profiles/profile-popover

Interactive profile preview component with hover/click functionality

***

title: ProfilePopover
description: Interactive profile preview component with hover/click functionality
category: profile-management
----------------------------

import { ProfilePopoverDemo } from '@/components/docs/demos/ProfilePopoverDemo'

Interactive popover that displays user profile information with actions for editing, switching, and viewing details.

ProfilePopover combines [ProfileCard](/docs/components/profile-card) with the [Radix Popover primitive](https://www.radix-ui.com/themes/docs/components/popover) to provide an interactive profile preview that can be triggered by hover or click.

## Installation

```bash
npx bigblocks add profile-popover
```

## Import

```tsx
import { ProfilePopover } from 'bigblocks';
```

## API Reference

This component extends the [Popover primitive](https://www.radix-ui.com/themes/docs/components/popover) and inherits all its props.

| Prop          | Type                                     | Default    | Description                             |
| ------------- | ---------------------------------------- | ---------- | --------------------------------------- |
| profile\*     | `ProfileInfo`                            | -          | Profile data to display                 |
| children\*    | `React.ReactNode`                        | -          | Trigger element for the popover         |
| onEdit        | `() => void`                             | -          | Callback when edit is clicked           |
| onSwitch      | `() => void`                             | -          | Callback when switch profile is clicked |
| onViewDetails | `() => void`                             | -          | Callback when view details is clicked   |
| openOnHover   | `boolean`                                | `true`     | Open popover on hover vs click          |
| align         | `'start' \| 'center' \| 'end'`           | `'center'` | Popover alignment                       |
| side          | `'top' \| 'right' \| 'bottom' \| 'left'` | `'bottom'` | Popover position                        |
| className     | `string`                                 | -          | Additional CSS classes                  |

\* Required props

## Basic Usage

```tsx
import { ProfilePopover } from 'bigblocks';

export default function UserDisplay() {
  const profile = {
    name: 'Satoshi Nakamoto',
    id: 'bap123456789',
    address: '1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa',
    isPublished: true,
    alternateName: '@satoshi',
    description: 'Creator of Bitcoin',
    image: 'https://api.dicebear.com/7.x/avataaars/svg?seed=satoshi'
  };

return (
    <ProfilePopover
      profile={profile}
      onViewDetails={() => router.push(`/profile/${profile.id}`)}
    >
      <img 
        src={profile.image} 
        alt={profile.name}
        className="w-10 h-10 rounded-full cursor-pointer"
      />
    </ProfilePopover>
  );
}
```

## Profile Actions

ProfilePopover provides three optional action callbacks:

```tsx
<ProfilePopover
  profile={profile}
  onEdit={() => openEditModal()}
  onSwitch={() => showProfileSwitcher()}
  onViewDetails={() => router.push(`/profile/${profile.id}`)}
>
  <button className="flex items-center gap-2">
    <BitcoinAvatar src={profile.image} alt={profile.name} fallback="U" size="2" />
    <span>{profile.name}</span>
  </button>
</ProfilePopover>
```

## Interaction Modes

Control whether the popover opens on hover or click:

```tsx
// Hover mode (default) - good for quick previews
<ProfilePopover 
  profile={profile}
  openOnHover={true}
>
  <span className="text-blue-600 hover:underline">
    @{profile.alternateName}
  </span>
</ProfilePopover>

// Click mode - better for mobile and touch devices
<ProfilePopover
  profile={profile}
  openOnHover={false}
  onViewDetails={() => console.log('View profile')}
>
  <button className="btn-primary">
    View Profile
  </button>
</ProfilePopover>
```

For positioning options (side, align, etc.), see the [Radix Popover documentation](https://www.radix-ui.com/themes/docs/components/popover).

## Profile Data Structure

```tsx
interface ProfileInfo {
  id: string;
  name: string;
  address: string;
  alternateName?: string;
  description?: string;
  image?: string;
  isPublished: boolean;
}
```

## Related Components

* [ProfileCard](/docs/components/profile-card) - Profile display component
* [BitcoinAvatar](/docs/components/bitcoin-avatar) - Avatar with Bitcoin URL support
* [ProfileSwitcher](/docs/components/profile-switcher) - Switch between multiple profiles

# ProfileSwitcher
URL: /docs/components/profiles/profile-switcher

Switch between multiple Bitcoin identities (BAP profiles) with a dropdown interface

***

title: ProfileSwitcher
description: Switch between multiple Bitcoin identities (BAP profiles) with a dropdown interface
categories: \['profiles', 'navigation', 'ui']
providers: \['BitcoinAuthProvider']
-----------------------------------

import { ProfileSwitcherDemo } from '@/components/docs/demos/ProfileSwitcherDemo'
import { ComponentBadges } from '@/components/docs/ComponentBadges'

ProfileSwitcher combines the [Radix DropdownMenu primitive](https://www.radix-ui.com/themes/docs/components/dropdown-menu) with Bitcoin identity management, enabling users to switch between multiple BAP profiles and create new ones with complete key, data, and context isolation.

## Installation

```bash
npx bigblocks add profile-switcher
```

## Import

```typescript
import { ProfileSwitcher, ProfileSwitcherCompact } from 'bigblocks';
```

This component extends the [DropdownMenu primitive](https://www.radix-ui.com/themes/docs/components/dropdown-menu) and inherits all its props.

## Props

| Prop            | Type                                        | Required | Default   | Description                        |
| --------------- | ------------------------------------------- | -------- | --------- | ---------------------------------- |
| profiles        | `ProfileInfo[]`                             | Yes      | -         | Array of available profiles        |
| activeProfileId | `string`                                    | Yes      | -         | Currently active profile's BAP ID  |
| onSwitch        | `(profileId: string) => void`               | Yes      | -         | Callback when profile is switched  |
| onCreate        | `() => void`                                | No       | -         | Callback for creating new profile  |
| maxProfiles     | `number`                                    | No       | -         | Maximum number of profiles allowed |
| className       | `string`                                    | No       | -         | Additional CSS classes             |
| size            | `'1' \| '2' \| '3' \| '4'`                  | No       | '2'       | Radix Themes size scale            |
| variant         | `'solid' \| 'soft' \| 'ghost' \| 'surface'` | No       | 'surface' | Visual variant style               |

### ProfileInfo Interface

```typescript
interface ProfileInfo {
  id: string;              // BAP identity key
  address: string;         // Bitcoin address
  name?: string;          // Profile display name
  image?: string;         // Avatar URL or ORDFS reference
  description?: string;   // Profile description
  isPublished: boolean;   // BAP profile publication status
}
```

## Basic Usage

```tsx
import { ProfileSwitcher } from 'bigblocks';
import { useProfiles } from '@/hooks/useProfiles';

function Header() {
  const { profiles, activeProfile, switchProfile } = useProfiles();

return (
    <ProfileSwitcher
      profiles={profiles}
      activeProfileId={activeProfile.id}
      onSwitch={switchProfile}
    />
  );
}
```

## Advanced Usage

```tsx
import { ProfileSwitcher, type ProfileInfo } from 'bigblocks';
import { useRouter } from 'next/navigation';

function NavigationBar() {
  const router = useRouter();
  const [profiles, setProfiles] = useState<ProfileInfo[]>([]);
  const [activeId, setActiveId] = useState('');

const handleProfileSwitch = async (profileId: string) => {
    // Switch to new profile context
    await switchToProfile(profileId);
    
    // Navigate to profile-specific dashboard
    router.push(`/dashboard/${profileId}`);
    
    // Update local state
    setActiveId(profileId);
  };

const handleCreateProfile = () => {
    // Navigate to profile creation flow
    router.push('/profiles/create');
  };

return (
    <ProfileSwitcher
      profiles={profiles}
      activeProfileId={activeId}
      onSwitch={handleProfileSwitch}
      onCreate={handleCreateProfile}
      maxProfiles={5}
      size="3"
      variant="soft"
    />
  );
}
```

## Common Patterns

### Multi-Profile Management

Each Bitcoin identity (BAP profile) is completely isolated with its own:

* **Private/Public Keys**: Separate key derivation paths
* **Bitcoin Address**: Unique payment and identity address
* **Settings & Data**: Profile-specific preferences
* **Social Connections**: Independent follow/follower lists
* **Transaction History**: Separate wallet activity

```tsx
import { ProfileSwitcher, BitcoinAuthProvider } from 'bigblocks';

function MultiProfileApp() {
  const [currentProfile, setCurrentProfile] = useState<ProfileInfo>();
  
  // Switch entire app context when profile changes
  const handleSwitch = async (profileId: string) => {
    const profile = profiles.find(p => p.id === profileId);
    if (!profile) return;
    
    // Update auth context with new profile
    await updateAuthContext(profile);
    
    // Clear cached data from previous profile
    clearProfileCache();
    
    // Load new profile data
    await loadProfileData(profileId);
    
    setCurrentProfile(profile);
  };

return (
    <BitcoinAuthProvider profile={currentProfile}>
      <ProfileSwitcher
        profiles={profiles}
        activeProfileId={currentProfile?.id}
        onSwitch={handleSwitch}
      />
    </BitcoinAuthProvider>
  );
}
```

### Profile Creation Flow

```tsx
function ProfileManagement() {
  const { createProfile } = useProfiles();
  const [isCreating, setIsCreating] = useState(false);

return (
    <ProfileSwitcher
      profiles={profiles}
      activeProfileId={activeId}
      onSwitch={switchProfile}
      onCreate={handleCreateNew}
      maxProfiles={10} // Limit total profiles
    />
  );
}
```

### Compact Version

For space-constrained areas like mobile headers:

```tsx
import { ProfileSwitcherCompact } from 'bigblocks';

function MobileHeader() {
  return (
    <ProfileSwitcherCompact
      profiles={profiles}
      activeProfileId={activeId}
      onSwitch={handleSwitch}
      className="w-full"
    />
  );
}
```

### With Profile Status Indicators

```tsx
function ProfileSwitcherWithStatus() {
  // Enhance profiles with additional status info
  const enhancedProfiles = profiles.map(profile => ({
    ...profile,
    name: profile.isPublished 
      ? `${profile.name} ✓` 
      : `${profile.name} (Unpublished)`,
    description: profile.isPublished
      ? 'Published to blockchain'
      : 'Local profile only'
  }));

return (
    <ProfileSwitcher
      profiles={enhancedProfiles}
      activeProfileId={activeId}
      onSwitch={onSwitch}
    />
  );
}
```

## Authentication Requirements

ProfileSwitcher requires the Bitcoin authentication context to manage profile switching:

```tsx
import { 
  BitcoinAuthProvider, 
  BitcoinQueryProvider,
  ProfileSwitcher 
} from 'bigblocks';

function App() {
  return (
    <BitcoinQueryProvider>
      <BitcoinAuthProvider config={{ apiUrl: '/api' }}>
        <ProfileSwitcher {...props} />
      </BitcoinAuthProvider>
    </BitcoinQueryProvider>
  );
}
```

## API Integration

### Profile Loading

The component expects profiles to be loaded from your backend:

```typescript
// GET /api/users/profiles
{
  "profiles": [
    {
      "id": "bap-id-1",
      "address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
      "name": "Personal",
      "image": "ordfs://tx-id/0",
      "description": "My personal profile",
      "isPublished": true
    },
    {
      "id": "bap-id-2",
      "address": "1BvBMSEYstWetqTFn5Au4m4GFg7xJaNVN2",
      "name": "Business",
      "image": "https://example.com/avatar.jpg",
      "description": "Professional identity",
      "isPublished": false
    }
  ]
}
```

### Profile Switching

When switching profiles, the component triggers authentication updates:

```typescript
// POST /api/auth/switch-profile
{
  "profileId": "bap-id-2",
  "signature": "bitcoin-signature-proof"
}

// Response updates session with new profile context
{
  "success": true,
  "profile": { /* ProfileInfo */ },
  "sessionToken": "new-jwt-token"
}
```

## Bitcoin Identity Concepts

### BAP (Bitcoin Attestation Protocol)

Each profile is a BAP identity with:

* **Hierarchical Deterministic Keys**: Derived from master seed
* **Identity Attestations**: On-chain identity claims
* **Cryptographic Proofs**: All actions are signed

### Profile Isolation

Different profiles provide:

* **Privacy Separation**: No linking between identities
* **Use Case Segregation**: Personal vs Business vs Anonymous
* **Risk Management**: Separate keys for different activities

### Key Derivation

Profiles use BIP32 HD derivation:

```
Master Seed → m/44'/236'/0'/0'/0  (Profile 1)
            → m/44'/236'/0'/1'/0  (Profile 2)
            → m/44'/236'/0'/2'/0  (Profile 3)
```

## Troubleshooting

### Profile Not Switching

```typescript
// Ensure profile data is properly loaded
const handleSwitch = async (profileId: string) => {
  try {
    // Clear existing session data
    sessionStorage.removeItem('activeProfile');
    
    // Load new profile's decrypted backup
    const backup = await loadProfileBackup(profileId);
    sessionStorage.setItem('decryptedBackup', JSON.stringify(backup));
    
    // Update auth context
    await updateAuthContext(profileId);
    
    // Reload app data
    window.location.reload();
  } catch (error) {
    console.error('Profile switch failed:', error);
  }
};
```

### Missing Profile Data

Ensure profiles include all required fields:

```typescript
// Validate profile data
profiles.forEach(profile => {
  if (!profile.id || !profile.address) {
    console.error('Invalid profile:', profile);
  }
});
```

### Maximum Profiles Reached

```tsx
<ProfileSwitcher
  profiles={profiles}
  activeProfileId={activeId}
  onSwitch={onSwitch}
  onCreate={profiles.length < 5 ? handleCreate : undefined}
  maxProfiles={5}
/>
```

## Keyboard Navigation

* `Space/Enter`: Open dropdown menu
* `↑/↓`: Navigate between profiles
* `Enter`: Select highlighted profile
* `Escape`: Close dropdown
* `Tab`: Move to next focusable element

## Accessibility

* **ARIA Labels**: Proper labeling for screen readers
* **Focus Management**: Keyboard navigation support
* **Status Announcements**: Profile changes announced
* **High Contrast**: Works with system preferences

## Related Components

* [ProfileEditor](/docs/components/profile-editor) - Edit profile details
* [ProfileManager](/docs/components/profile-manager) - Manage all profiles
* [ProfileViewer](/docs/components/profile-viewer) - Display profile information
* [ProfilePublisher](/docs/components/profile-publisher) - Publish profiles to blockchain
* [ProfilePopover](/docs/components/profile-popover) - Hover profile preview

## API Reference

### ProfileSwitcher Exports

```typescript
// Main component
export function ProfileSwitcher(props: ProfileSwitcherProps): JSX.Element

// Compact variant
export function ProfileSwitcherCompact(
  props: Pick<ProfileSwitcherProps, 
    'profiles' | 'activeProfileId' | 'onSwitch' | 'className'
  >
): JSX.Element

// Type exports
export type { ProfileInfo, ProfileSwitcherProps }
```

### Custom Styling

Apply custom styles using className:

```tsx
<ProfileSwitcher
  className="custom-switcher"
  profiles={profiles}
  activeProfileId={activeId}
  onSwitch={onSwitch}
/>

/* Custom CSS */
.custom-switcher {
  --switcher-bg: rgba(255, 255, 255, 0.1);
  --switcher-border: rgba(255, 255, 255, 0.2);
  --switcher-hover: rgba(255, 255, 255, 0.15);
}
```

### Integration with React Query

```typescript
import { useQuery } from '@tanstack/react-query';

function useProfileSwitcher() {
  const { data: profiles = [] } = useQuery({
    queryKey: ['profiles'],
    queryFn: fetchProfiles,
    staleTime: 5 * 60 * 1000, // 5 minutes
  });

const { data: activeProfile } = useQuery({
    queryKey: ['activeProfile'],
    queryFn: fetchActiveProfile,
  });

return {
    profiles,
    activeProfileId: activeProfile?.id || profiles[0]?.id,
    onSwitch: switchProfile,
  };
}
```

# ProfileViewer
URL: /docs/components/profiles/profile-viewer

Display a complete view of a BAP profile with avatar, information, actions, and status

***

title: ProfileViewer
description: Display a complete view of a BAP profile with avatar, information, actions, and status
category: profiles
------------------

A component for displaying a complete view of a BAP (Bitcoin Attestation Protocol) profile, including avatar, profile information, Bitcoin address, publication status, and action buttons.

## Installation

```bash
npx bigblocks add profile-viewer
```

## Import

```typescript
import { ProfileViewer } from 'bigblocks';
```

## Props

| Prop              | Type                                | Required | Default     | Description                             |
| ----------------- | ----------------------------------- | -------- | ----------- | --------------------------------------- |
| profile           | `ProfileInfo`                       | Yes      | -           | Profile data to display                 |
| showAddress       | `boolean`                           | No       | `true`      | Show Bitcoin address with copy function |
| showPublishStatus | `boolean`                           | No       | `true`      | Show published/unpublished status       |
| showActions       | `boolean`                           | No       | `true`      | Show edit and publish buttons           |
| onEdit            | `() => void`                        | No       | -           | Edit button click handler               |
| onPublish         | `() => void`                        | No       | -           | Publish button click handler            |
| className         | `string`                            | No       | -           | Additional CSS classes                  |
| variant           | `'surface' \| 'classic' \| 'ghost'` | No       | `'surface'` | Visual style variant                    |
| size              | `'1' \| '2' \| '3' \| '4'`          | No       | `'3'`       | Component size                          |

## Basic Usage

```tsx
import { ProfileViewer } from 'bigblocks';

export default function UserProfile() {
  const profile = {
    id: 'bap-123',
    address: '1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa',
    isPublished: true,
    name: 'Bitcoin Builder',
    alternateName: '@btc_builder',
    description: 'Building the future of money on Bitcoin',
    image: 'https://api.dicebear.com/7.x/avataaars/svg?seed=builder',
    url: 'https://bitcoin.org',
    email: 'builder@bitcoin.org',
    paymail: 'builder@moneybutton.com'
  };

return (
    <ProfileViewer
      profile={profile}
      onEdit={() => {
        console.log('Edit profile');
      }}
      onPublish={() => {
        console.log('Publish profile');
      }}
    />
  );
}
```

## Profile Structure

```typescript
interface ProfileInfo {
  id: string;                    // Profile identifier
  address: string;               // Bitcoin address
  isPublished: boolean;          // Publication status
  
  // Basic Information
  '@context'?: string;           // JSON-LD context
  '@type'?: 'Person' | 'Organization';
  name?: string;                 // Display name
  alternateName?: string;        // Username/handle
  description?: string;          // Bio/description
  
  // Images
  image?: string;                // Avatar/profile image
  logo?: string;                 // Organization logo
  banner?: string;               // Banner/cover image
  
  // Contact Information
  url?: string;                  // Website URL
  email?: string;                // Email address
  paymail?: string;             // Bitcoin paymail
  bitcoinAddress?: string;       // Additional Bitcoin address
  
  // Personal Details
  givenName?: string;           // First name
  familyName?: string;          // Last name
  legalName?: string;           // Legal/full name
  
  // Location Information
  location?: string;             // General location
  homeLocation?: string;         // Home location
  streetAddress?: string;        // Street address
  addressLocality?: string;      // City
  addressRegion?: string;        // State/province
  postalCode?: string;           // ZIP/postal code
  addressCountry?: string;       // Country
}
```

## Advanced Usage

### Complete Profile with All Fields

```tsx
import { ProfileViewer } from 'bigblocks';

export default function CompleteProfile() {
  const profile = {
    id: 'bap-456',
    address: '1BvBMSEYstWetqTFn5Au4m4GFg7xJaNVN2',
    isPublished: true,
    '@context': 'https://schema.org',
    '@type': 'Person',
    name: 'Satoshi Nakamoto',
    alternateName: '@satoshi',
    description: 'Creator of Bitcoin. Pseudonymous developer who designed and implemented the world\'s first cryptocurrency.',
    image: 'https://api.dicebear.com/7.x/avataaars/svg?seed=satoshi',
    banner: 'https://images.unsplash.com/photo-1640340434855-6084b1f4901c',
    url: 'https://bitcoin.org',
    email: 'satoshi@gmx.com',
    paymail: 'satoshi@relayx.io',
    givenName: 'Satoshi',
    familyName: 'Nakamoto',
    location: 'Worldwide',
    bitcoinAddress: '1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa'
  };

return (
    <ProfileViewer
      profile={profile}
      variant="surface"
      size="4"
      onEdit={() => {
        // Open profile editor
        setEditMode(true);
      }}
      onPublish={() => {
        // Publish to blockchain
        publishProfile(profile.id);
      }}
    />
  );
}
```

### Read-only Profile View

```tsx
import { ProfileViewer } from 'bigblocks';

export default function PublicProfile({ profile }) {
  return (
    <ProfileViewer
      profile={profile}
      showActions={false}
      showPublishStatus={false}
      variant="classic"
    />
  );
}
```

### Organization Profile

```tsx
import { ProfileViewer } from 'bigblocks';

export default function CompanyProfile() {
  const orgProfile = {
    id: 'org-789',
    address: '3J98t1WpEZ73CNmQviecrnyiWrnqRhWNLy',
    isPublished: true,
    '@type': 'Organization',
    name: 'Bitcoin Foundation',
    legalName: 'Bitcoin Foundation, Inc.',
    description: 'Promoting the responsible adoption of Bitcoin through education, advocacy, and ecosystem development.',
    logo: 'https://bitcoinfoundation.org/logo.png',
    banner: 'https://bitcoinfoundation.org/banner.jpg',
    url: 'https://bitcoinfoundation.org',
    email: 'info@bitcoinfoundation.org',
    streetAddress: '1230 NE 3rd Avenue',
    addressLocality: 'Miami',
    addressRegion: 'FL',
    postalCode: '33132',
    addressCountry: 'US'
  };

return (
    <ProfileViewer
      profile={orgProfile}
      size="4"
      onEdit={() => editOrganization(orgProfile.id)}
      onPublish={() => publishOrganization(orgProfile.id)}
    />
  );
}
```

### With Custom Styling

```tsx
import { ProfileViewer } from 'bigblocks';

export default function StyledProfile({ profile }) {
  return (
    <ProfileViewer
      profile={profile}
      className="shadow-lg border-2 border-orange-200"
      variant="ghost"
      size="3"
      onEdit={() => {
        // Custom edit handler
      }}
    />
  );
}
```

### Different Variants

```tsx
import { ProfileViewer } from 'bigblocks';

export default function ProfileVariants({ profile }) {
  return (
    <div className="space-y-6">
      {/* Surface variant - default */}
      <ProfileViewer
        profile={profile}
        variant="surface"
        onEdit={() => console.log('Edit surface')}
      />
      
      {/* Classic variant */}
      <ProfileViewer
        profile={profile}
        variant="classic"
        onEdit={() => console.log('Edit classic')}
      />
      
      {/* Ghost variant */}
      <ProfileViewer
        profile={profile}
        variant="ghost"
        onEdit={() => console.log('Edit ghost')}
      />
    </div>
  );
}
```

### Different Sizes

```tsx
import { ProfileViewer } from 'bigblocks';

export default function ProfileSizes({ profile }) {
  return (
    <div className="grid grid-cols-2 gap-4">
      {/* Small */}
      <ProfileViewer
        profile={profile}
        size="1"
        onEdit={() => console.log('Edit small')}
      />
      
      {/* Medium */}
      <ProfileViewer
        profile={profile}
        size="2"
        onEdit={() => console.log('Edit medium')}
      />
      
      {/* Large */}
      <ProfileViewer
        profile={profile}
        size="3"
        onEdit={() => console.log('Edit large')}
      />
      
      {/* Extra Large */}
      <ProfileViewer
        profile={profile}
        size="4"
        onEdit={() => console.log('Edit extra large')}
      />
    </div>
  );
}
```

## Common Patterns

### Profile Page Layout

```tsx
import { ProfileViewer, SocialFeed } from 'bigblocks';

export default function ProfilePage({ userId }) {
  const [profile, setProfile] = useState(null);
  const [isEditing, setIsEditing] = useState(false);

useEffect(() => {
    const loadProfile = async () => {
      const profileData = await fetchProfile(userId);
      setProfile(profileData);
    };
    
    loadProfile();
  }, [userId]);

const handleEdit = () => {
    setIsEditing(true);
  };

if (!profile) return <div>Loading...</div>;

return (
    <div className="max-w-4xl mx-auto space-y-6">
      <ProfileViewer
        profile={profile}
        onEdit={handleEdit}
        onPublish={handlePublish}
      />
      
      <div className="mt-8">
        <SocialFeed
          feedType="user"
          userId={userId}
        />
      </div>
    </div>
  );
}
```

### Profile Comparison

```tsx
import { ProfileViewer } from 'bigblocks';

export default function ProfileComparison({ profiles }) {
  return (
    <div className="grid grid-cols-1 md:grid-cols-2 gap-6">
      {profiles.map(profile => (
        <ProfileViewer
          key={profile.id}
          profile={profile}
          showActions={false}
          variant="classic"
          size="3"
        />
      ))}
    </div>
  );
}
```

### Profile with Conditional Actions

```tsx
import { ProfileViewer } from 'bigblocks';
import { useAuth } from 'bigblocks';

export default function ConditionalProfile({ profile }) {
  const { user, isAuthenticated } = useAuth();
  
  const isOwnProfile = isAuthenticated && user?.id === profile.id;
  const canEdit = isOwnProfile || user?.isAdmin;

return (
    <ProfileViewer
      profile={profile}
      showActions={canEdit}
      showPublishStatus={isOwnProfile}
      onEdit={canEdit ? () => editProfile(profile.id) : undefined}
      onPublish={isOwnProfile ? () => publishProfile(profile.id) : undefined}
    />
  );
}
```

### Profile with Status Updates

```tsx
import { ProfileViewer } from 'bigblocks';
import { useState, useEffect } from 'react';

export default function LiveProfile({ profileId }) {
  const [profile, setProfile] = useState(null);
  const [publishing, setPublishing] = useState(false);

useEffect(() => {
    // Subscribe to profile updates
    const unsubscribe = subscribeToProfile(profileId, (updatedProfile) => {
      setProfile(updatedProfile);
    });

return unsubscribe;
  }, [profileId]);

return (
    <div>
      {publishing && (
        <div className="mb-4 p-3 bg-blue-100 text-blue-700 rounded">
          Publishing profile to blockchain...
        </div>
      )}
      
      <ProfileViewer
        profile={profile}
        onPublish={handlePublish}
        onEdit={() => editProfile(profileId)}
      />
    </div>
  );
}
```

### Mobile Responsive Profile

```tsx
import { ProfileViewer } from 'bigblocks';

export default function MobileProfile({ profile }) {
  return (
    <div className="px-4">
      <ProfileViewer
        profile={profile}
        size="2" // Smaller on mobile
        className="w-full"
        onEdit={() => {
          // Open mobile-friendly editor
          openMobileEditor(profile.id);
        }}
      />
    </div>
  );
}
```

## Publishing Status

The component displays different states based on `isPublished`:

### Published Profile

* ✅ Green checkmark with "Published" text
* Profile data is on the blockchain
* Publicly discoverable

### Unpublished Profile

* ⏳ Orange indicator with "Draft" text
* Profile exists locally only
* Not yet on blockchain

## Features

* **Complete Profile Display**: Avatar, name, description, and all profile fields
* **Bitcoin Address**: Displayed with copy-to-clipboard functionality
* **Publication Status**: Visual indicator of blockchain publication state
* **Action Buttons**: Edit and publish controls when enabled
* **Responsive Design**: Adapts to different screen sizes
* **Multiple Variants**: Surface, classic, and ghost styling options
* **Size Options**: Four different size presets
* **Type Support**: Both Person and Organization profiles
* **Schema.org Compliance**: Structured data format support

## Address Display

When `showAddress` is true, the Bitcoin address is displayed with:

* Truncated format for readability
* Copy-to-clipboard button
* Tooltip showing full address
* Visual feedback on copy

## Action Buttons

When `showActions` is true, displays:

* **Edit Button**: Opens profile editor (requires `onEdit` handler)
* **Publish Button**: Publishes to blockchain (requires `onPublish` handler)

## Accessibility

* Screen reader support for all content
* Keyboard navigation for interactive elements
* High contrast support
* Focus indicators on actionable items
* Alternative text for images

## Best Practices

1. **Complete Profiles**: Encourage users to fill all relevant fields
2. **Image Optimization**: Use optimized images for avatars and banners
3. **Privacy Awareness**: Remind users that published data is permanent
4. **Error Handling**: Handle missing or invalid profile data gracefully
5. **Performance**: Lazy load large images and banners

## Troubleshooting

### Profile Not Displaying

* Check that profile object has required `id` and `address` fields
* Verify profile data structure matches `ProfileInfo` interface
* Ensure component is wrapped in proper providers

### Images Not Loading

* Verify image URLs are accessible
* Check for CORS issues with external images
* Provide fallback images for missing avatars

### Actions Not Working

* Ensure `onEdit` and `onPublish` handlers are provided
* Check that `showActions` is true (default)
* Verify user permissions for profile actions

## Related Components

* [ProfileEditor](/docs/components/profile-editor) - Edit profiles
* [ProfileManager](/docs/components/profile-manager) - Manage multiple profiles
* [ProfileDropdownMenu](/docs/components/profile-dropdown-menu) - Profile selection
* [ProfilePopover](/docs/components/profile-popover) - Quick profile preview

## API Integration

The component works with BAP profile APIs:

```typescript
// Get profile data
GET /api/bap/profiles/{id}

// Publish profile
POST /api/bap/profiles/{id}/publish

// Update profile
PUT /api/bap/profiles/{id}
```

## Notes for Improvement

**Enhanced Implementation**: The actual component provides more sophisticated features than the basic prompt described:

* Complete BAP profile schema support with all schema.org fields
* Multiple visual variants and size options for different use cases
* Advanced status indicators for publication state
* Better address handling with copy functionality
* Support for both Person and Organization profile types
* Responsive design optimizations for mobile devices

# BapEncryptionSuite
URL: /docs/components/security/bap-encryption-suite

Comprehensive encryption toolkit using Bitcoin Attestation Protocol (BAP) identities for secure communication and data protection

***

title: BapEncryptionSuite
description: Comprehensive encryption toolkit using Bitcoin Attestation Protocol (BAP) identities for secure communication and data protection
category: bap
-------------

A powerful encryption component that leverages Bitcoin Attestation Protocol (BAP) identities for end-to-end encryption, enabling secure communication and data protection using Bitcoin cryptographic keys. Perfect for building secure messaging, file sharing, and confidential data storage applications.

[View Component Preview →](/component-preview/bap-encryption-suite)

## Installation

```bash
npx bigblocks add bap-encryption-suite
```

## Import

```typescript
import { BapEncryptionSuite } from 'bigblocks';
```

## Props

| Prop           | Type                                | Required | Default                       | Description                                      |
| -------------- | ----------------------------------- | -------- | ----------------------------- | ------------------------------------------------ |
| bapInstance    | `ExtendedBAP`                       | Yes      | -                             | The BAP instance for encryption/decryption       |
| recipientBapId | `ExtendedBAP`                       | No       | -                             | Recipient BAP instance for asymmetric encryption |
| onEncrypted    | `(result: EncryptedData) => void`   | No       | -                             | Callback when content is encrypted               |
| onDecrypted    | `(result: DecryptedData) => void`   | No       | -                             | Callback when content is decrypted               |
| allowedTypes   | `EncryptionContentType[]`           | No       | `['message', 'file', 'json']` | Allowed content types                            |
| useType42      | `boolean`                           | No       | `false`                       | Use Type 42 key derivation                       |
| variant        | `'surface' \| 'ghost' \| 'classic'` | No       | `'surface'`                   | Theme variant                                    |
| size           | `'1' \| '2' \| '3'`                 | No       | `'2'`                         | Component size                                   |

### Type Definitions

```typescript
interface EncryptedData {
  encrypted: string;
  type: EncryptionContentType;
  mode: EncryptionMode;
  recipientPublicKey?: string;
  timestamp: Date;
  metadata?: Record<string, unknown>;
}

interface DecryptedData {
  content: string | ArrayBuffer;
  type: EncryptionContentType;
  decryptedAt: Date;
  senderAddress?: string;
  metadata?: Record<string, unknown>;
}

type EncryptionMode = 'symmetric' | 'asymmetric';
type EncryptionContentType = 'message' | 'file' | 'json';
```

## Basic Usage

```tsx
import { BapEncryptionSuite, useBitcoinAuth } from 'bigblocks';

export default function BasicEncryption() {
  const { bapInstance } = useBitcoinAuth();

const handleEncrypted = (result: EncryptedData) => {
    console.log('Encrypted:', result);
    // Store or transmit encrypted data
  };

const handleDecrypted = (result: DecryptedData) => {
    console.log('Decrypted:', result);
    // Display decrypted content
  };

return (
    <BapEncryptionSuite
      bapInstance={bapInstance}
      onEncrypted={handleEncrypted}
      onDecrypted={handleDecrypted}
    />
  );
}
```

## Advanced Usage

### Secure Messaging System

```tsx
import { BapEncryptionSuite, useBitcoinAuth } from 'bigblocks';
import { useState, useEffect } from 'react';

interface SecureMessage {
  id: string;
  sender: string;
  recipient: string;
  encrypted: string;
  timestamp: Date;
  read: boolean;
}

export default function SecureMessaging() {
  const { bapInstance, address } = useBitcoinAuth();
  const [messages, setMessages] = useState<SecureMessage[]>([]);
  const [recipientBap, setRecipientBap] = useState<ExtendedBAP | null>(null);
  const [selectedMessage, setSelectedMessage] = useState<SecureMessage | null>(null);

// Load recipient's BAP profile
  const loadRecipientBap = async (recipientAddress: string) => {
    try {
      const response = await fetch(`/api/bap/profile/${recipientAddress}`);
      const bapData = await response.json();
      setRecipientBap(bapData);
    } catch (error) {
      console.error('Failed to load recipient BAP:', error);
    }
  };

// Send encrypted message
  const handleSendMessage = async (result: EncryptedData) => {
    if (!recipientBap) return;

const message: SecureMessage = {
      id: crypto.randomUUID(),
      sender: address,
      recipient: recipientBap.address,
      encrypted: result.encrypted,
      timestamp: result.timestamp,
      read: false
    };

// Send to backend
    await fetch('/api/messages', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-Auth-Token': await generateAuthToken()
      },
      body: JSON.stringify(message)
    });

console.log('Message sent securely');
  };

// Decrypt received message
  const handleDecryptMessage = (result: DecryptedData) => {
    if (result.type === 'message') {
      alert(`Message from ${result.senderAddress}: ${result.content}`);
      
      // Mark as read
      if (selectedMessage) {
        markMessageAsRead(selectedMessage.id);
      }
    }
  };

return (
    <div className="secure-messaging">
      <h2>Secure BAP Messaging</h2>
      
      <div className="recipient-selector">
        <input
          type="text"
          placeholder="Recipient Bitcoin address"
          onChange={(e) => loadRecipientBap(e.target.value)}
        />
      </div>

{recipientBap && (
        <BapEncryptionSuite
          bapInstance={bapInstance}
          recipientBapId={recipientBap}
          onEncrypted={handleSendMessage}
          allowedTypes={['message']}
          variant="surface"
          size="2"
        />
      )}

<div className="message-list">
        <h3>Encrypted Messages</h3>
        {messages.map((msg) => (
          <div 
            key={msg.id} 
            className={`message ${msg.read ? 'read' : 'unread'}`}
            onClick={() => setSelectedMessage(msg)}
          >
            <span>From: {msg.sender}</span>
            <span>{new Date(msg.timestamp).toLocaleString()}</span>
          </div>
        ))}
      </div>

{selectedMessage && (
        <BapEncryptionSuite
          bapInstance={bapInstance}
          onDecrypted={handleDecryptMessage}
          allowedTypes={['message']}
          variant="ghost"
        />
      )}
    </div>
  );
}
```

### Encrypted File Sharing

```tsx
import { BapEncryptionSuite, useBitcoinAuth } from 'bigblocks';
import { useState } from 'react';

interface EncryptedFile {
  id: string;
  filename: string;
  size: number;
  mimeType: string;
  encrypted: string;
  owner: string;
  sharedWith: string[];
  createdAt: Date;
}

export default function EncryptedFileSharing() {
  const { bapInstance, address } = useBitcoinAuth();
  const [files, setFiles] = useState<EncryptedFile[]>([]);
  const [selectedFile, setSelectedFile] = useState<File | null>(null);
  const [recipients, setRecipients] = useState<string[]>([]);
  const [decryptedFiles, setDecryptedFiles] = useState<Map<string, Blob>>(new Map());

const handleFileEncryption = async (result: EncryptedData) => {
    if (!selectedFile || result.type !== 'file') return;

const encryptedFile: EncryptedFile = {
      id: crypto.randomUUID(),
      filename: selectedFile.name,
      size: selectedFile.size,
      mimeType: selectedFile.type,
      encrypted: result.encrypted,
      owner: address,
      sharedWith: recipients,
      createdAt: new Date()
    };

// Upload encrypted file
    const response = await fetch('/api/files/encrypted', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-Auth-Token': await generateAuthToken()
      },
      body: JSON.stringify(encryptedFile)
    });

if (response.ok) {
      setFiles([...files, encryptedFile]);
      setSelectedFile(null);
      alert(`File encrypted and shared with ${recipients.length} recipients`);
    }
  };

const handleFileDecryption = (result: DecryptedData) => {
    if (result.type !== 'file' || !selectedFile) return;

// Convert ArrayBuffer to Blob
    const blob = new Blob([result.content as ArrayBuffer], {
      type: selectedFile.mimeType
    });

// Store decrypted file
    setDecryptedFiles(new Map(decryptedFiles.set(selectedFile.id, blob)));

// Create download link
    const url = URL.createObjectURL(blob);
    const a = document.createElement('a');
    a.href = url;
    a.download = selectedFile.filename;
    a.click();
    URL.revokeObjectURL(url);
  };

return (
    <div className="encrypted-file-sharing">
      <h2>Encrypted File Sharing</h2>

<div className="upload-section">
        <h3>Upload & Encrypt File</h3>
        
        <input
          type="file"
          onChange={(e) => setSelectedFile(e.target.files?.[0] || null)}
        />

<div className="recipients">
          <h4>Share with (BAP IDs):</h4>
          <textarea
            placeholder="Enter BAP IDs, one per line"
            onChange={(e) => setRecipients(e.target.value.split('\n').filter(Boolean))}
          />
        </div>

{selectedFile && (
          <BapEncryptionSuite
            bapInstance={bapInstance}
            onEncrypted={handleFileEncryption}
            allowedTypes={['file']}
            useType42={true}
            variant="surface"
            size="3"
          />
        )}
      </div>

<div className="file-list">
        <h3>Encrypted Files</h3>
        {files.map((file) => (
          <div key={file.id} className="encrypted-file">
            <div className="file-info">
              <span className="filename">{file.filename}</span>
              <span className="size">{(file.size / 1024).toFixed(2)} KB</span>
              <span className="date">{file.createdAt.toLocaleDateString()}</span>
            </div>
            
            {(file.owner === address || file.sharedWith.includes(address)) && (
              <button onClick={() => setSelectedFile(file)}>
                Decrypt & Download
              </button>
            )}
          </div>
        ))}
      </div>
    </div>
  );
}
```

## Common Patterns

### Multi-Recipient Encryption

```tsx
import { BapEncryptionSuite, useBitcoinAuth } from 'bigblocks';

export default function MultiRecipientEncryption() {
  const { bapInstance } = useBitcoinAuth();
  const [recipients, setRecipients] = useState<ExtendedBAP[]>([]);
  const [message, setMessage] = useState('');

const loadRecipients = async (addresses: string[]) => {
    const bapProfiles = await Promise.all(
      addresses.map(addr => fetch(`/api/bap/profile/${addr}`).then(r => r.json()))
    );
    setRecipients(bapProfiles.filter(Boolean));
  };

const handleMultiEncryption = async (baseResult: EncryptedData) => {
    // Encrypt for each recipient
    for (const recipient of recipients) {
      const encryptedCopy = {
        ...baseResult,
        recipientPublicKey: recipient.publicKey,
        metadata: {
          ...baseResult.metadata,
          recipientAddress: recipient.address
        }
      };

await sendToRecipient(recipient.address, encryptedCopy);
    }

alert(`Message encrypted and sent to ${recipients.length} recipients`);
  };

return (
    <div className="multi-recipient">
      <h3>Broadcast Encrypted Message</h3>
      
      <textarea
        value={message}
        onChange={(e) => setMessage(e.target.value)}
        placeholder="Enter message to encrypt"
      />

<input
        type="text"
        placeholder="Recipient addresses (comma-separated)"
        onChange={(e) => loadRecipients(e.target.value.split(',').map(s => s.trim()))}
      />

<div className="recipient-list">
        {recipients.map((r) => (
          <span key={r.address} className="recipient-badge">
            {r.name || r.address.slice(0, 8)}...
          </span>
        ))}
      </div>

{recipients.length > 0 && (
        <BapEncryptionSuite
          bapInstance={bapInstance}
          recipientBapId={recipients[0]} // Use first recipient as template
          onEncrypted={handleMultiEncryption}
          allowedTypes={['message']}
        />
      )}
    </div>
  );
}
```

### Encrypted JSON Data Storage

```tsx
import { BapEncryptionSuite, useBitcoinAuth } from 'bigblocks';

interface SensitiveData {
  apiKeys: Record<string, string>;
  passwords: Record<string, string>;
  privateNotes: string[];
  financialData: {
    accounts: Array<{ name: string; balance: number }>;
    transactions: Array<{ date: string; amount: number }>;
  };
}

export default function EncryptedDataVault() {
  const { bapInstance } = useBitcoinAuth();
  const [vaultData, setVaultData] = useState<SensitiveData | null>(null);
  const [encryptedVault, setEncryptedVault] = useState<string | null>(null);

const handleVaultEncryption = async (result: EncryptedData) => {
    if (result.type !== 'json') return;

// Store encrypted vault
    const response = await fetch('/api/vault', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-Auth-Token': await generateAuthToken()
      },
      body: JSON.stringify({
        encrypted: result.encrypted,
        timestamp: result.timestamp,
        metadata: result.metadata
      })
    });

if (response.ok) {
      setEncryptedVault(result.encrypted);
      alert('Vault encrypted and saved');
    }
  };

const handleVaultDecryption = (result: DecryptedData) => {
    if (result.type !== 'json') return;

try {
      const data = JSON.parse(result.content as string) as SensitiveData;
      setVaultData(data);
      console.log('Vault decrypted successfully');
    } catch (error) {
      console.error('Failed to parse decrypted data:', error);
    }
  };

return (
    <div className="encrypted-vault">
      <h2>Encrypted Data Vault</h2>

<div className="vault-editor">
        <h3>Vault Contents</h3>
        <textarea
          value={JSON.stringify(vaultData, null, 2)}
          onChange={(e) => {
            try {
              setVaultData(JSON.parse(e.target.value));
            } catch {}
          }}
          rows={15}
          cols={50}
        />
      </div>

{encryptedVault && (
        <div className="encrypted-preview">
          <h4>Encrypted Vault (Preview)</h4>
          <code>{encryptedVault.slice(0, 100)}...</code>
        </div>
      )}
    </div>
  );
}
```

### Type 42 Key Derivation

```tsx
import { BapEncryptionSuite, useBitcoinAuth } from 'bigblocks';

export default function Type42Encryption() {
  const { bapInstance } = useBitcoinAuth();
  const [useType42, setUseType42] = useState(true);
  const [derivationPath, setDerivationPath] = useState('');

const handleType42Encryption = (result: EncryptedData) => {
    console.log('Encrypted with Type 42:', {
      encrypted: result.encrypted,
      keyDerivation: result.metadata?.type42Path
    });

// Type 42 provides deterministic key derivation
    // Useful for hierarchical access control
  };

return (
    <div className="type42-encryption">
      <h3>Type 42 Key Derivation</h3>
      
      <label>
        <input
          type="checkbox"
          checked={useType42}
          onChange={(e) => setUseType42(e.target.checked)}
        />
        Enable Type 42 Derivation
      </label>

{useType42 && (
        <input
          type="text"
          placeholder="Custom derivation path (optional)"
          value={derivationPath}
          onChange={(e) => setDerivationPath(e.target.value)}
        />
      )}

<div className="type42-info">
        <p>Type 42 Benefits:</p>
        <ul>
          <li>Deterministic key generation</li>
          <li>Hierarchical access control</li>
          <li>Perfect forward secrecy</li>
          <li>Key rotation capability</li>
        </ul>
      </div>
    </div>
  );
}
```

### Encryption with Metadata

```tsx
import { BapEncryptionSuite, useBitcoinAuth } from 'bigblocks';

export default function MetadataEncryption() {
  const { bapInstance, address } = useBitcoinAuth();
  const [tags, setTags] = useState<string[]>([]);
  const [expiresIn, setExpiresIn] = useState(24); // hours

const handleEncryptionWithMetadata = (result: EncryptedData) => {
    const enrichedResult = {
      ...result,
      metadata: {
        ...result.metadata,
        sender: address,
        tags: tags,
        expiresAt: new Date(Date.now() + expiresIn * 60 * 60 * 1000),
        version: '1.0',
        app: 'BigBlocks Secure'
      }
    };

// Store with metadata for filtering/searching
    storeEncryptedWithMetadata(enrichedResult);
  };

return (
    <div className="metadata-encryption">
      <h3>Encrypt with Metadata</h3>

<div className="metadata-inputs">
        <input
          type="text"
          placeholder="Tags (comma-separated)"
          onChange={(e) => setTags(e.target.value.split(',').map(s => s.trim()))}
        />

<label>
          Expires in:
          <select value={expiresIn} onChange={(e) => setExpiresIn(Number(e.target.value))}>
            <option value={1}>1 hour</option>
            <option value={24}>24 hours</option>
            <option value={168}>1 week</option>
            <option value={720}>30 days</option>
          </select>
        </label>
      </div>

<BapEncryptionSuite
        bapInstance={bapInstance}
        onEncrypted={handleEncryptionWithMetadata}
        variant="surface"
      />
    </div>
  );
}
```

## Authentication Requirements

BapEncryptionSuite requires full BAP authentication:

```tsx
import { 
  BitcoinAuthProvider, 
  BitcoinQueryProvider,
  BapEncryptionSuite
} from 'bigblocks';

function App() {
  return (
    <BitcoinQueryProvider>
      <BitcoinAuthProvider config={{ 
        apiUrl: '/api',
        bapEnabled: true // Required for BAP features
      }}>
        <YourEncryptionApp />
      </BitcoinAuthProvider>
    </BitcoinQueryProvider>
  );
}
```

## API Integration

### Encryption Endpoints

```typescript
// Encrypt data
POST /api/bap/encrypt
{
  content: string | ArrayBuffer;
  type: 'message' | 'file' | 'json';
  recipientPublicKey?: string;
  useType42?: boolean;
  metadata?: Record<string, any>;
}

Response:
{
  encrypted: string;
  type: string;
  mode: 'symmetric' | 'asymmetric';
  timestamp: string;
  metadata: Record<string, any>;
}

// Decrypt data
POST /api/bap/decrypt
{
  encrypted: string;
  type: 'message' | 'file' | 'json';
  senderPublicKey?: string;
  useType42?: boolean;
}

Response:
{
  content: string | ArrayBuffer;
  type: string;
  decryptedAt: string;
  senderAddress?: string;
  metadata?: Record<string, any>;
}
```

### Backend Implementation

```typescript
// BAP encryption handler
app.post('/api/bap/encrypt', authenticate, async (req, res) => {
  const { content, type, recipientPublicKey, useType42, metadata } = req.body;
  const { bapId } = req.user;
  
  try {
    // Get user's BAP instance
    const bap = await getBapInstance(bapId);
    
    // Perform encryption
    const encrypted = await bap.encrypt(content, {
      type,
      recipientPublicKey,
      useType42,
      metadata: {
        ...metadata,
        encryptedBy: bapId,
        encryptedAt: new Date().toISOString()
      }
    });
    
    // Log for audit
    await logEncryption({
      bapId,
      type,
      size: content.length,
      recipient: recipientPublicKey,
      timestamp: new Date()
    });
    
    res.json(encrypted);
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});
```

## Security Considerations

### Encryption Best Practices

1. **Key Management**: Never expose private keys
2. **Perfect Forward Secrecy**: Use ephemeral keys when possible
3. **Metadata Privacy**: Be careful what metadata you include
4. **Size Limits**: Implement reasonable file size limits
5. **Access Control**: Verify recipient identity before encryption

### Common Security Patterns

```tsx
// Secure key verification
const verifyRecipient = async (recipientAddress: string) => {
  const profile = await fetchBapProfile(recipientAddress);
  
  // Verify profile signature
  if (!await verifyBapSignature(profile)) {
    throw new Error('Invalid recipient profile');
  }
  
  // Check if profile is recent
  const age = Date.now() - new Date(profile.updatedAt).getTime();
  if (age > 30 * 24 * 60 * 60 * 1000) { // 30 days
    console.warn('Recipient profile may be outdated');
  }
  
  return profile;
};

// Implement encryption policies
const encryptionPolicy = {
  maxFileSize: 50 * 1024 * 1024, // 50MB
  allowedTypes: ['message', 'file', 'json'],
  requireType42ForFiles: true,
  metadataWhitelist: ['tags', 'expiresAt', 'version']
};
```

## Error Handling

### Common Error Scenarios

```tsx
import { BapEncryptionSuite } from 'bigblocks';

export default function ErrorHandling() {
  const handleEncryptionError = (error: Error) => {
    if (error.message.includes('Invalid recipient')) {
      alert('Recipient BAP profile not found or invalid');
    } else if (error.message.includes('File too large')) {
      alert('File exceeds maximum size limit');
    } else if (error.message.includes('Unsupported type')) {
      alert('This content type cannot be encrypted');
    } else if (error.message.includes('Key derivation failed')) {
      alert('Type 42 key derivation error - check BAP configuration');
    } else {
      alert(`Encryption failed: ${error.message}`);
    }
  };

return (
    <BapEncryptionSuite
      bapInstance={bapInstance}
      onEncrypted={(result) => {
        try {
          processEncrypted(result);
        } catch (error) {
          handleEncryptionError(error);
        }
      }}
      onDecrypted={(result) => {
        try {
          processDecrypted(result);
        } catch (error) {
          handleDecryptionError(error);
        }
      }}
    />
  );
}
```

## Performance Optimization

### Large File Handling

```tsx
// Chunk large files for efficient encryption
const chunkFile = async (file: File, chunkSize = 1024 * 1024) => {
  const chunks: Blob[] = [];
  let offset = 0;
  
  while (offset < file.size) {
    const chunk = file.slice(offset, offset + chunkSize);
    chunks.push(chunk);
    offset += chunkSize;
  }
  
  return chunks;
};

// Encrypt chunks in parallel
const encryptLargeFile = async (file: File, bap: ExtendedBAP) => {
  const chunks = await chunkFile(file);
  
  const encryptedChunks = await Promise.all(
    chunks.map((chunk, index) => 
      bap.encrypt(chunk, {
        type: 'file',
        metadata: { 
          chunkIndex: index, 
          totalChunks: chunks.length,
          filename: file.name
        }
      })
    )
  );
  
  return {
    chunks: encryptedChunks,
    metadata: {
      filename: file.name,
      size: file.size,
      chunks: chunks.length
    }
  };
};
```

## Styling

```css
/* Custom styling for encryption suite */
.bap-encryption-suite {
  padding: 1rem;
  border-radius: 8px;
  background: var(--surface-color);
}

.encryption-mode-toggle {
  display: flex;
  gap: 1rem;
  margin-bottom: 1rem;
}

.encryption-input {
  width: 100%;
  min-height: 100px;
  margin-bottom: 1rem;
}

.encryption-actions {
  display: flex;
  gap: 0.5rem;
}

.encryption-result {
  margin-top: 1rem;
  padding: 1rem;
  background: var(--code-bg);
  border-radius: 4px;
  word-break: break-all;
}
```

## Troubleshooting

### Encryption not working

* Verify BAP instance is properly initialized
* Check recipient has valid BAP profile
* Ensure content type is supported
* Verify size limits aren't exceeded

### Decryption failing

* Confirm you have the correct private key
* Check if data was encrypted for your public key
* Verify data integrity (not corrupted)
* Ensure metadata matches expected format

### Type 42 issues

* BAP instance must support Type 42
* Derivation paths must be valid
* Check for conflicting key derivations

### Performance problems

* Chunk large files before encryption
* Use web workers for heavy computation
* Implement proper caching strategies

## Related Components

* [BapFileSigner](/docs/components/bap-file-signer) - Sign files with BAP identity
* [BapKeyRotation](/docs/components/bap-key-rotation) - Rotate encryption keys
* [ShamirSecretSharing](/docs/components/shamir-secret-sharing) - Split secrets securely
* [Type42KeyDerivation](/docs/components/type42-key-derivation) - Advanced key derivation

## API Reference

### BapEncryptionSuite Props

```typescript
interface BapEncryptionSuiteProps {
  bapInstance: ExtendedBAP;
  recipientBapId?: ExtendedBAP;
  onEncrypted?: (result: EncryptedData) => void;
  onDecrypted?: (result: DecryptedData) => void;
  allowedTypes?: EncryptionContentType[];
  useType42?: boolean;
  variant?: 'surface' | 'ghost' | 'classic';
  size?: '1' | '2' | '3';
}
```

### Hook Usage

```typescript
import { useBapEncryption } from 'bigblocks';

function EncryptionHookExample() {
  const { encrypt, decrypt, isEncrypting, isDecrypting } = useBapEncryption({
    useType42: true
  });

const handleEncrypt = async (content: string) => {
    const result = await encrypt(content, {
      type: 'message',
      recipientPublicKey: 'recipient-key'
    });
    console.log('Encrypted:', result);
  };

return (
    <button onClick={() => handleEncrypt('Secret message')} disabled={isEncrypting}>
      {isEncrypting ? 'Encrypting...' : 'Encrypt'}
    </button>
  );
}
```

# ShamirSecretSharing
URL: /docs/components/security/shamir-secret-sharing

Split sensitive data into multiple shares using Shamir's Secret Sharing algorithm. Reconstruct the secret only when a threshold of shares are combined.

***

title: ShamirSecretSharing
description: Split sensitive data into multiple shares using Shamir's Secret Sharing algorithm. Reconstruct the secret only when a threshold of shares are combined.
--------------------------------------------------------------------------------------------------------------------------------------------------------------------

Split sensitive data into multiple shares using Shamir's Secret Sharing algorithm. Reconstruct the secret only when a threshold of shares are combined. Essential for secure key backup and multi-party custody.

[View ShamirSecretSharing examples →](/component-preview/shamir-secret-sharing)

## Installation

```bash
npm install bigblocks
```

## Usage

```tsx
import { ShamirSecretSharing } from 'bigblocks';

export default function KeyBackup() {
  return (
    <ShamirSecretSharing
      privateKey="L1aW4aubDFB7yfras2S1mN3bqg9nwySY8nkoLmJebSLD5BWv3ENZ"
      onKeyReconstructed={(wif) => {
        console.log('Private key reconstructed:', wif);
      }}
    />
  );
}
```

## Props

| Prop                 | Type                    | Default | Description                                     |
| -------------------- | ----------------------- | ------- | ----------------------------------------------- |
| `privateKey`         | `string`                | -       | Private key in WIF format to split              |
| `onKeyReconstructed` | `(wif: string) => void` | -       | Callback when key is successfully reconstructed |
| `className`          | `string`                | -       | Additional CSS classes                          |

## Features

* **Cryptographically Secure**: Uses proven Shamir's Secret Sharing algorithm
* **Threshold Schemes**: Configure minimum shares needed for reconstruction
* **WIF Key Support**: Works with Bitcoin private keys in WIF format
* **Visual Interface**: User-friendly splitting and reconstruction UI
* **Security Validation**: Ensures threshold requirements are met
* **Share Distribution**: Guidance for secure share distribution

## Examples

### Basic Key Splitting

```tsx
<ShamirSecretSharing
  privateKey="L1aW4aubDFB7yfras2S1mN3bqg9nwySY8nkoLmJebSLD5BWv3ENZ"
  onKeyReconstructed={(reconstructedKey) => {
    console.log('Key reconstructed successfully');
    // Store or use the reconstructed private key
    setPrivateKey(reconstructedKey);
  }}
/>
```

### Interactive Key Recovery

```tsx
function KeyRecoveryFlow() {
  const [recoveredKey, setRecoveredKey] = useState('');
  const [recoveryComplete, setRecoveryComplete] = useState(false);

return (
    <div className="space-y-6">
      <h2>Recover Your Private Key</h2>
      
      <ShamirSecretSharing
        onKeyReconstructed={(wif) => {
          setRecoveredKey(wif);
          setRecoveryComplete(true);
          toast.success('Private key recovered successfully!');
        }}
        className="max-w-2xl mx-auto"
      />
      
      {recoveryComplete && (
        <div className="success-message">
          <h3>✅ Recovery Complete</h3>
          <p>Your private key has been successfully reconstructed.</p>
          <button 
            onClick={() => importWallet(recoveredKey)}
            className="btn-primary"
          >
            Import Wallet
          </button>
        </div>
      )}
    </div>
  );
}
```

### Backup Creation Workflow

```tsx
function CreateBackup() {
  const [walletKey, setWalletKey] = useState('');
  const [backupCreated, setBackupCreated] = useState(false);

const generateWallet = () => {
    // Generate new wallet
    const newWallet = createWallet();
    setWalletKey(newWallet.privateKey);
  };

return (
    <div className="backup-workflow">
      {!walletKey ? (
        <div>
          <h2>Generate New Wallet</h2>
          <button onClick={generateWallet}>
            Generate New Wallet
          </button>
        </div>
      ) : (
        <div>
          <h2>Create Secure Backup</h2>
          <p>Split your private key into multiple shares for secure storage.</p>
          
          <ShamirSecretSharing
            privateKey={walletKey}
            onKeyReconstructed={(reconstructed) => {
              if (reconstructed === walletKey) {
                setBackupCreated(true);
                console.log('Backup verification successful');
              }
            }}
          />
          
          {backupCreated && (
            <div className="backup-success">
              ✅ Backup created and verified successfully!
            </div>
          )}
        </div>
      )}
    </div>
  );
}
```

### Multi-Signature Setup

```tsx
function MultiSigSetup() {
  const [memberKeys, setMemberKeys] = useState([]);
  const [threshold, setThreshold] = useState(2);

return (
    <div className="multisig-setup">
      <h2>Multi-Signature Wallet Setup</h2>
      <p>Create a {threshold}-of-{memberKeys.length} wallet</p>
      
      {memberKeys.map((key, index) => (
        <div key={index} className="member-key">
          <h3>Member {index + 1} Key Backup</h3>
          <ShamirSecretSharing
            privateKey={key}
            onKeyReconstructed={(reconstructed) => {
              console.log(`Member ${index + 1} key verified`);
            }}
          />
        </div>
      ))}
    </div>
  );
}
```

### Enterprise Key Management

```tsx
function EnterpriseKeyBackup() {
  const [masterKey, setMasterKey] = useState('');
  const [distributionPlan, setDistributionPlan] = useState(null);

return (
    <div className="enterprise-backup">
      <h2>Enterprise Key Backup</h2>
      
      <div className="backup-config">
        <h3>Distribution Plan</h3>
        <ul>
          <li>CEO: Share 1</li>
          <li>CTO: Share 2</li>
          <li>Safe Deposit Box: Share 3</li>
          <li>Legal Counsel: Share 4</li>
          <li>Board Chair: Share 5</li>
        </ul>
        <p>Threshold: 3 of 5 shares required</p>
      </div>
      
      <ShamirSecretSharing
        privateKey={masterKey}
        onKeyReconstructed={(reconstructed) => {
          console.log('Enterprise key backup verified');
          setDistributionPlan({
            shares: 5,
            threshold: 3,
            verified: true
          });
        }}
        className="enterprise-widget"
      />
    </div>
  );
}
```

## Required Context

The component requires the following providers:

```tsx
import { 
  BitcoinAuthProvider, 
  BitcoinQueryProvider 
} from 'bigblocks';

function App() {
  return (
    <BitcoinAuthProvider>
      <BitcoinQueryProvider>
        <ShamirSecretSharing
          privateKey={privateKey}
          onKeyReconstructed={handleReconstruction}
        />
      </BitcoinQueryProvider>
    </BitcoinAuthProvider>
  );
}
```

## Security Considerations

### ⚠️ Critical Security Guidelines

1. **Share Distribution**
   * Never store all shares in the same location
   * Use different storage methods (physical, digital, cloud)
   * Consider geographic distribution

2. **Threshold Selection**
   * 2-of-3: Good for personal use
   * 3-of-5: Recommended for business
   * 5-of-9: Enterprise-grade security

3. **Share Security**
   * Each share reveals nothing about the secret
   * Shares can be encrypted with additional passwords
   * Consider using secure channels for distribution

4. **Recovery Testing**
   * Always test reconstruction before relying on backup
   * Verify shares are readable and correct
   * Document recovery procedures

### Best Practices

```tsx
// Good: 3-of-5 scheme for business
<ShamirSecretSharing
  privateKey={businessWalletKey}
  // Configure for 3 of 5 shares
  onKeyReconstructed={(key) => {
    // Verify reconstruction works
    if (verifyPrivateKey(key)) {
      console.log('Backup verified successfully');
    }
  }}
/>
```

### Common Schemes

| Use Case       | Shares | Threshold | Description                |
| -------------- | ------ | --------- | -------------------------- |
| Personal       | 3      | 2         | Simple backup (2-of-3)     |
| Small Business | 5      | 3         | Moderate security (3-of-5) |
| Enterprise     | 7      | 4         | High security (4-of-7)     |
| High Security  | 9      | 5         | Maximum security (5-of-9)  |

## Algorithm Details

### Shamir's Secret Sharing

The component implements Shamir's Secret Sharing over finite fields:

1. **Polynomial Construction**: Secret is encoded as polynomial coefficients
2. **Share Generation**: Evaluate polynomial at different points
3. **Threshold Security**: Any `k` shares can reconstruct the polynomial
4. **Information Theoretic**: Fewer than `k` shares reveal nothing

### Mathematical Foundation

```
f(x) = a₀ + a₁x + a₂x² + ... + aₖ₋₁xᵏ⁻¹ (mod p)

Where:
- a₀ = secret
- a₁, a₂, ..., aₖ₋₁ = random coefficients
- p = large prime number
- Shares are points (x, f(x))
```

## Error Handling

### Common Error Scenarios

```tsx
<ShamirSecretSharing
  privateKey={privateKey}
  onKeyReconstructed={(key) => {
    try {
      // Validate reconstructed key
      if (!isValidWIF(key)) {
        throw new Error('Invalid WIF format');
      }
      
      // Test key functionality
      if (!testPrivateKey(key)) {
        throw new Error('Key reconstruction failed');
      }
      
      console.log('Key reconstruction successful');
    } catch (error) {
      console.error('Reconstruction error:', error.message);
      toast.error('Key reconstruction failed');
    }
  }}
/>
```

### Validation Checks

* **WIF Format**: Ensures proper private key encoding
* **Checksum**: Validates key integrity
* **Threshold**: Ensures minimum shares are provided
* **Share Format**: Validates share structure

## Performance Considerations

* **CPU Intensive**: Polynomial operations can be computationally expensive
* **Memory Usage**: Large polynomials require more memory
* **Share Size**: Shares are proportional to secret size
* **Reconstruction Time**: Increases with threshold and share count

## Related Components

* [Type42KeyDerivation](/docs/components/type42-key-derivation) - Hierarchical key derivation
* [MnemonicDisplay](/docs/components/mnemonic-display) - BIP39 mnemonic phrases
* [BackupDownload](/docs/components/backup-download) - Encrypted backup creation
* [KeyManager](/docs/components/key-manager) - Advanced key management

# Type42KeyDerivation
URL: /docs/components/security/type42-key-derivation

BRC-42 compliant deterministic key derivation for Bitcoin applications. Generate consistent keys across different contexts and applications.

***

title: Type42KeyDerivation
description: BRC-42 compliant deterministic key derivation for Bitcoin applications. Generate consistent keys across different contexts and applications.
---------------------------------------------------------------------------------------------------------------------------------------------------------

BRC-42 compliant deterministic key derivation for Bitcoin applications. Generate consistent keys across different contexts and applications with protocol-specific derivation paths.

[View Type42KeyDerivation examples →](/component-preview/type42-key-derivation)

## Installation

```bash
npm install bigblocks
```

## Usage

```tsx
import { Type42KeyDerivation } from 'bigblocks';

export default function KeyDerivation() {
  return (
    <Type42KeyDerivation
      privateKey="L1aW4aubDFB7yfras2S1mN3bqg9nwySY8nkoLmJebSLD5BWv3ENZ"
      onKeyDerived={(derivedKey) => {
        console.log('Derived key:', derivedKey.address);
        console.log('Invoice:', derivedKey.invoice);
      }}
    />
  );
}
```

## Props

| Prop           | Type                               | Default | Description                            |
| -------------- | ---------------------------------- | ------- | -------------------------------------- |
| `privateKey`   | `string`                           | -       | Master private key in WIF format       |
| `onKeyDerived` | `(derivedKey: DerivedKey) => void` | -       | Callback when key derivation completes |
| `className`    | `string`                           | -       | Additional CSS classes                 |

### DerivedKey Interface

```typescript
interface DerivedKey {
  wif: string;                    // Derived private key in WIF format
  address: string;                // Bitcoin address
  publicKey: string;              // Public key (hex)
  counterpartyPubKey: string;     // Counterparty public key
  invoice: string;                // Payment invoice string
}
```

## Features

* **BRC-42 Compliance**: Follows Bitcoin Request for Comment 42 standard
* **Deterministic Derivation**: Same input always produces same output
* **Protocol Segregation**: Different keys for different applications
* **Invoice Generation**: Automatic payment invoice creation
* **Cross-Application**: Consistent keys across different apps
* **Security Isolation**: Protocol-specific key separation

## Examples

### Basic Key Derivation

```tsx
<Type42KeyDerivation
  privateKey="L1aW4aubDFB7yfras2S1mN3bqg9nwySY8nkoLmJebSLD5BWv3ENZ"
  onKeyDerived={(derived) => {
    console.log('Derived Address:', derived.address);
    console.log('Public Key:', derived.publicKey);
    console.log('Payment Invoice:', derived.invoice);
  }}
/>
```

### Protocol-Specific Derivation

```tsx
function ProtocolKeyManager() {
  const [socialKey, setSocialKey] = useState(null);
  const [messageKey, setMessageKey] = useState(null);
  const [identityKey, setIdentityKey] = useState(null);

const masterKey = "L1aW4aubDFB7yfras2S1mN3bqg9nwySY8nkoLmJebSLD5BWv3ENZ";

return (
    <div className="protocol-keys">
      <div className="key-section">
        <h3>Social Media Keys</h3>
        <Type42KeyDerivation
          privateKey={masterKey}
          onKeyDerived={(key) => {
            setSocialKey(key);
            // Use for social media signing
            configureSocialSigning(key);
          }}
        />
      </div>

<div className="key-section">
        <h3>Messaging Keys</h3>
        <Type42KeyDerivation
          privateKey={masterKey}
          onKeyDerived={(key) => {
            setMessageKey(key);
            // Use for encrypted messaging
            configureMessaging(key);
          }}
        />
      </div>

<div className="key-section">
        <h3>Identity Keys</h3>
        <Type42KeyDerivation
          privateKey={masterKey}
          onKeyDerived={(key) => {
            setIdentityKey(key);
            // Use for identity verification
            configureIdentity(key);
          }}
        />
      </div>
    </div>
  );
}
```

### Application-Specific Keys

```tsx
function AppKeyDerivation() {
  const [appKeys, setAppKeys] = useState({});
  const masterKey = useWallet().privateKey;

return (
    <div className="app-keys">
      <h2>Application Keys</h2>
      
      <div className="app-section">
        <h3>Marketplace App</h3>
        {deriveKeyForApp('marketplace')}
      </div>

<div className="app-section">
        <h3>Gaming App</h3>
        {deriveKeyForApp('gaming')}
      </div>

<div className="app-section">
        <h3>DeFi App</h3>
        {deriveKeyForApp('defi')}
      </div>
    </div>
  );
}
```

### Multi-Purpose Key Management

```tsx
function MultiPurposeKeys() {
  const [keys, setKeys] = useState({
    signing: null,
    encryption: null,
    identity: null,
    payment: null
  });

const masterKey = "L1aW4aubDFB7yfras2S1mN3bqg9nwySY8nkoLmJebSLD5BWv3ENZ";

return (
    <div className="multipurpose-keys">
      <h2>Multi-Purpose Key Derivation</h2>
      
      {Object.entries(keys).map(([purpose, key]) => (
        <div key={purpose} className="key-purpose">
          <h3>{purpose.charAt(0).toUpperCase() + purpose.slice(1)} Key</h3>
          
          <Type42KeyDerivation
            privateKey={masterKey}
            onKeyDerived={(derivedKey) => {
              setKeys(prev => ({
                ...prev,
                [purpose]: derivedKey
              }));
              
              console.log(`${purpose} key derived:`, derivedKey.address);
            }}
          />
          
          {key && (
            <div className="key-info">
              <p>Address: {key.address}</p>
              <p>Invoice: {key.invoice}</p>
            </div>
          )}
        </div>
      ))}
    </div>
  );
}
```

### Enterprise Key Derivation

```tsx
function EnterpriseKeyDerivation() {
  const [departmentKeys, setDepartmentKeys] = useState({});
  const [employeeKeys, setEmployeeKeys] = useState({});

const organizationMasterKey = process.env.ORGANIZATION_MASTER_KEY;

return (
    <div className="enterprise-keys">
      <h2>Enterprise Key Management</h2>
      
      <div className="departments">
        <h3>Department Keys</h3>
        
        <div className="department">
          <h4>Finance Department</h4>
          {deriveDepartmentKey('finance')}
        </div>

<div className="department">
          <h4>Engineering Department</h4>
          {deriveDepartmentKey('engineering')}
        </div>

<div className="department">
          <h4>Legal Department</h4>
          {deriveDepartmentKey('legal')}
        </div>
      </div>
    </div>
  );
}
```

### Development Environment Keys

```tsx
function DevEnvironmentKeys() {
  const [envKeys, setEnvKeys] = useState({});
  const devMasterKey = useDevWallet();

const environments = ['development', 'staging', 'production'];

return (
    <div className="env-keys">
      <h2>Environment-Specific Keys</h2>
      
      {environments.map(env => (
        <div key={env} className="environment">
          <h3>{env.toUpperCase()} Environment</h3>
          
          <Type42KeyDerivation
            privateKey={devMasterKey}
            onKeyDerived={(key) => {
              setEnvKeys(prev => ({
                ...prev,
                [env]: key
              }));
              
              // Configure environment
              configureEnvironment(env, key);
            }}
          />
          
          {envKeys[env] && (
            <div className="env-config">
              <p>Address: {envKeys[env].address}</p>
              <p>Invoice: {envKeys[env].invoice}</p>
              <button onClick={() => deployToEnvironment(env, envKeys[env])}>
                Deploy to {env}
              </button>
            </div>
          )}
        </div>
      ))}
    </div>
  );
}
```

## Required Context

The component requires the following providers:

```tsx
import { 
  BitcoinAuthProvider, 
  BitcoinQueryProvider 
} from 'bigblocks';

function App() {
  return (
    <BitcoinAuthProvider>
      <BitcoinQueryProvider>
        <Type42KeyDerivation
          privateKey={privateKey}
          onKeyDerived={handleKeyDerivation}
        />
      </BitcoinQueryProvider>
    </BitcoinAuthProvider>
  );
}
```

## BRC-42 Standard

### Specification Overview

BRC-42 (Bitcoin Request for Comment 42) defines a standard for deterministic key derivation:

1. **Protocol Identification**: Unique identifiers for different protocols
2. **Derivation Paths**: Hierarchical paths for key generation
3. **Key Segregation**: Separate keys for different purposes
4. **Cross-Application**: Consistent behavior across implementations

### Derivation Formula

```
derivedKey = HMAC-SHA512(masterKey, protocol + purpose + counter)
```

Where:

* `masterKey`: Master private key
* `protocol`: Protocol identifier string
* `purpose`: Key purpose (signing, encryption, identity)
* `counter`: Optional counter for multiple keys

### Standard Protocols

| Protocol      | Purpose                   | Description                 |
| ------------- | ------------------------- | --------------------------- |
| `social`      | Social media interactions | Posts, likes, follows       |
| `messaging`   | Private communications    | Encrypted messages          |
| `identity`    | Identity verification     | Authentication, attestation |
| `payment`     | Financial transactions    | Payments, invoices          |
| `gaming`      | Gaming applications       | In-game assets, scores      |
| `marketplace` | Commerce platforms        | Buying, selling, escrow     |

## Security Considerations

### ⚠️ Critical Security Guidelines

1. **Master Key Security**
   * Store master key securely (hardware wallet, secure enclave)
   * Never transmit master key over network
   * Use strong entropy for master key generation

2. **Protocol Isolation**
   * Use consistent protocol identifiers
   * Never reuse keys across protocols
   * Implement proper access controls

3. **Key Lifecycle**
   * Rotate keys periodically
   * Implement key revocation procedures
   * Monitor for key compromise

4. **Implementation Security**
   * Validate all inputs
   * Use secure random number generators
   * Implement proper error handling

### Best Practices

```tsx
// Good: Secure key derivation
<Type42KeyDerivation
  privateKey={securelyStoredMasterKey}
  onKeyDerived={(key) => {
    // Validate derived key
    if (validateKey(key)) {
      // Use key securely
      useKeySecurely(key);
    } else {
      handleKeyError();
    }
  }}
/>
```

## Performance Considerations

* **CPU Intensive**: Key derivation involves cryptographic operations
* **Memory Usage**: Temporary storage of sensitive key material
* **Caching**: Avoid caching derived keys in memory
* **Batch Operations**: Derive multiple keys efficiently

## Error Handling

### Common Error Scenarios

```tsx
<Type42KeyDerivation
  privateKey={privateKey}
  onKeyDerived={(key) => {
    try {
      // Validate derived key
      if (!validateDerivedKey(key)) {
        throw new Error('Invalid derived key');
      }
      
      // Use key
      applyDerivedKey(key);
      
    } catch (error) {
      console.error('Key derivation error:', error.message);
      handleDerivationError(error);
    }
  }}
/>
```

### Validation Checks

* **WIF Format**: Ensures proper private key encoding
* **Address Generation**: Validates address derivation
* **Public Key**: Verifies public key derivation
* **Invoice Format**: Validates payment invoice

## Related Components

* [ShamirSecretSharing](/docs/components/shamir-secret-sharing) - Secret splitting for backup
* [KeyManager](/docs/components/key-manager) - Advanced key management
* [BapEncryptionSuite](/docs/components/bap-encryption-suite) - Encryption with derived keys
* [IdentityGeneration](/docs/components/identity-generation) - Identity creation

# BitcoinAuthProvider
URL: /docs/components/providers/bitcoin-auth-provider

Core provider component that manages Bitcoin-based authentication state and context throughout the application

***

title: BitcoinAuthProvider
description: Core provider component that manages Bitcoin-based authentication state and context throughout the application
categories: \[authentication, providers, context, blockchain]
-------------------------------------------------------------

import { ComponentBadges } from '@/components/docs/ComponentBadges';
import { BitcoinAuthProviderDemo } from '@/components/docs/demos/BitcoinAuthProviderDemo';

Core provider component that manages Bitcoin-based authentication state and context throughout the application. This provider wraps your app to enable Bitcoin authentication flows, session management, and user state tracking.

## Demo

## API Reference

This component extends the React Context API for state management and uses [AuthManager](/docs/components/auth-manager) for core authentication logic.

## Overview

The `BitcoinAuthProvider` is the foundation of BigBlocks authentication. It creates a React context that provides authentication state and actions to all child components, enabling seamless Bitcoin-based authentication throughout your application.

## Key Features

* **Centralized Auth State**: Manages user authentication status, profile data, and session information
* **Real-time Updates**: Automatically updates components when authentication state changes
* **Event System**: Subscribes to authentication events (login, logout, errors, OAuth linking)
* **Custom Messages**: Supports customizable UI messages for authentication flows
* **Legacy Compatibility**: Maintains backward compatibility with previous API versions

## Props

### config

* **Type**: `BitcoinAuthConfig`
* **Required**: Yes
* **Description**: Configuration object for Bitcoin authentication

```typescript
interface BitcoinAuthConfig {
  apiUrl?: string;           // BigBlocks API base URL
  appId: string;            // Your application ID
  redirectUrl?: string;     // OAuth redirect URL
  storage?: 'localStorage' | 'sessionStorage' | 'memory';
  debug?: boolean;          // Enable debug logging
}
```

### children

* **Type**: `React.ReactNode`
* **Required**: Yes
* **Description**: Child components that will have access to auth context

### messages

* **Type**: `Partial<AuthMessages>`
* **Required**: No
* **Description**: Custom messages for authentication UI elements

```typescript
interface AuthMessages {
  signIn: string;
  signUp: string;
  signOut: string;
  loading: string;
  error: string;
  // ... more message keys
}
```

## Context Value

The provider exposes the following through React context:

### Authentication State

* `isAuthenticated: boolean` - Whether user is logged in
* `user: User | null` - Current user data
* `profile: Profile | null` - Current active profile
* `profiles: Profile[]` - All user profiles
* `isLoading: boolean` - Loading state
* `error: string | null` - Current error message

### Authentication Actions

* `signIn()` - Initiate sign-in flow
* `signUp()` - Initiate sign-up flow
* `signOut()` - Sign out current user
* `selectProfile(id)` - Switch active profile
* `linkOAuth(provider)` - Link OAuth provider

### Configuration

* `config: BitcoinAuthConfig` - The configuration object passed to provider

## Usage

### Basic Setup

```tsx
import { BitcoinAuthProvider } from 'bigblocks';

const config = {
  appId: 'your-app-id',
  apiUrl: 'https://api.bigblocks.io',
  redirectUrl: window.location.origin + '/auth/callback'
};

function App() {
  return (
    <BitcoinAuthProvider config={config}>
      <YourApp />
    </BitcoinAuthProvider>
  );
}
```

### With Custom Messages

```tsx
const customMessages = {
  signIn: 'Connect Bitcoin Wallet',
  signUp: 'Create Bitcoin Account',
  loading: 'Connecting to Bitcoin network...',
  error: 'Bitcoin connection failed'
};

<BitcoinAuthProvider 
  config={config} 
  messages={customMessages}
>
  <YourApp />
</BitcoinAuthProvider>
```

### Accessing Context

```tsx
import { useBitcoinAuth } from 'bigblocks';

function AuthButton() {
  const { isAuthenticated, user, signIn, signOut } = useBitcoinAuth();

if (isAuthenticated) {
    return (
      <div>
        <span>Welcome, {user?.name}</span>
        <button onClick={signOut}>Sign Out</button>
      </div>
    );
  }

return <button onClick={signIn}>Sign In</button>;
}
```

## Event Handling

The provider automatically handles authentication events:

```typescript
// Events are handled internally and update component state
// You can access the current state through the context

useEffect(() => {
  if (isAuthenticated) {
    console.log('User signed in:', user);
  }
}, [isAuthenticated, user]);
```

## Configuration Examples

### Development Setup

```tsx
const devConfig = {
  appId: 'dev-app-123',
  apiUrl: 'http://localhost:3000/api',
  storage: 'sessionStorage',
  debug: true
};
```

### Production Setup

```tsx
const prodConfig = {
  appId: process.env.NEXT_PUBLIC_BIGBLOCKS_APP_ID,
  apiUrl: 'https://api.bigblocks.io',
  redirectUrl: 'https://yourapp.com/auth/callback',
  storage: 'localStorage'
};
```

### Memory-Only (Testing)

```tsx
const testConfig = {
  appId: 'test-app',
  storage: 'memory', // No persistence
  debug: true
};
```

## Integration with Other Providers

### With Theme Provider

```tsx
<ThemeProvider>
  <BitcoinAuthProvider config={config}>
    <BitcoinThemeProvider>
      <YourApp />
    </BitcoinThemeProvider>
  </BitcoinAuthProvider>
</ThemeProvider>
```

### With Query Provider

```tsx
<QueryClientProvider client={queryClient}>
  <BitcoinAuthProvider config={config}>
    <YourAuthenticatedApp />
  </BitcoinAuthProvider>
</QueryClientProvider>
```

## Security Considerations

* Always use HTTPS in production
* Store sensitive config in environment variables
* Use appropriate storage option for your security requirements
* Validate redirect URLs to prevent attacks

## Troubleshooting

### Provider Not Found Error

```
Error: useBitcoinAuth must be used within a BitcoinAuthProvider
```

Ensure your component is wrapped with `BitcoinAuthProvider`:

```tsx
// ❌ Wrong
<YourComponent /> // Will throw error

// ✅ Correct  
<BitcoinAuthProvider config={config}>
  <YourComponent />
</BitcoinAuthProvider>
```

### Authentication Not Working

1. Check your `appId` is correct
2. Verify `apiUrl` is accessible
3. Ensure `redirectUrl` matches your OAuth settings
4. Check browser console for network errors

## Installation

```bash
npm install bigblocks
```

## Related Components

* [AuthButton](/docs/components/auth-button) - Authentication buttons
* [AuthManager](/docs/components/auth-manager) - Core authentication logic
* [useBitcoinAuth](/docs/components/use-bitcoin-auth) - Authentication hook
* [AuthLayout](/docs/components/auth-layout) - Authentication layouts

# BitcoinQueryProvider
URL: /docs/components/providers/bitcoin-query-provider

React Query provider for efficient data caching and state management in Bitcoin applications

***

title: BitcoinQueryProvider
description: React Query provider for efficient data caching and state management in Bitcoin applications
category: providers
-------------------

A React Query-based provider that enables efficient data caching, synchronization, and state management for BigBlocks components. It provides optimized caching for market data, wallet operations, and social features.

## Installation

```bash
npx bigblocks add bitcoin-query-provider
```

## Import

```typescript
import { BitcoinQueryProvider } from 'bigblocks';
```

## Props

| Prop        | Type              | Required | Default        | Description               |
| ----------- | ----------------- | -------- | -------------- | ------------------------- |
| children    | `React.ReactNode` | Yes      | -              | Child components          |
| queryClient | `QueryClient`     | No       | Default client | Custom React Query client |

## Basic Usage

```tsx
import { BitcoinQueryProvider } from 'bigblocks';

function App() {
  return (
    <BitcoinQueryProvider>
      <BitcoinThemeProvider>
        <BitcoinAuthProvider config={{ apiUrl: '/api' }}>
          <YourAppContent />
        </BitcoinAuthProvider>
      </BitcoinThemeProvider>
    </BitcoinQueryProvider>
  );
}
```

## Advanced Usage

### Custom Query Client

```tsx
import { BitcoinQueryProvider } from 'bigblocks';
import { QueryClient } from '@tanstack/react-query';

export default function CustomQueryApp() {
  const queryClient = new QueryClient({
    defaultOptions: {
      queries: {
        staleTime: 5 * 60 * 1000,    // 5 minutes
        cacheTime: 10 * 60 * 1000,   // 10 minutes
        refetchOnWindowFocus: false,
        retry: (failureCount, error) => {
          if (error.status === 401) return false;
          return failureCount < 3;
        },
      },
      mutations: {
        retry: 1,
      },
    },
  });

return (
    <BitcoinQueryProvider queryClient={queryClient}>
      <App />
    </BitcoinQueryProvider>
  );
}
```

### Production Configuration

```tsx
import { BitcoinQueryProvider } from 'bigblocks';
import { QueryClient } from '@tanstack/react-query';

export default function ProductionApp() {
  const queryClient = new QueryClient({
    defaultOptions: {
      queries: {
        staleTime: 2 * 60 * 1000,      // 2 minutes
        cacheTime: 15 * 60 * 1000,     // 15 minutes
        refetchOnWindowFocus: true,
        refetchOnReconnect: true,
        networkMode: 'offlineFirst',
        retry: (failureCount, error) => {
          // Don't retry client errors
          if (error.status >= 400 && error.status < 500) {
            return false;
          }
          return failureCount < 2;
        },
      },
    },
  });

// Set specific defaults for different query types
  queryClient.setQueryDefaults(['balance'], {
    staleTime: 30 * 1000,              // Balance data should be fresh
    refetchInterval: 60 * 1000,        // Auto-refresh every minute
  });

queryClient.setQueryDefaults(['market'], {
    staleTime: 5 * 60 * 1000,          // Market data can be cached longer
  });

return (
    <BitcoinQueryProvider queryClient={queryClient}>
      <App />
    </BitcoinQueryProvider>
  );
}
```

### With Error Handling

```tsx
import { BitcoinQueryProvider } from 'bigblocks';
import { QueryClient, QueryCache } from '@tanstack/react-query';

export default function ErrorHandlingApp() {
  const queryClient = new QueryClient({
    queryCache: new QueryCache({
      onError: (error) => {
        console.error('Query error:', error);
        if (error.status === 401) {
          // Handle authentication errors
          window.location.href = '/signin';
        }
      },
    }),
    defaultOptions: {
      mutations: {
        onError: (error) => {
          console.error('Mutation failed:', error);
          // Show error notification
          toast.error('Operation failed. Please try again.');
        },
      },
    },
  });

return (
    <BitcoinQueryProvider queryClient={queryClient}>
      <App />
    </BitcoinQueryProvider>
  );
}
```

### With DevTools

```tsx
import { BitcoinQueryProvider } from 'bigblocks';
import { QueryClient } from '@tanstack/react-query';
import { ReactQueryDevtools } from '@tanstack/react-query-devtools';

export default function DevelopmentApp() {
  const queryClient = new QueryClient({
    defaultOptions: {
      queries: {
        staleTime: 0,                  // Always refetch in development
        refetchOnWindowFocus: false,   // Disable for development
      },
    },
  });

return (
    <BitcoinQueryProvider queryClient={queryClient}>
      <App />
      {process.env.NODE_ENV === 'development' && (
        <ReactQueryDevtools initialIsOpen={false} />
      )}
    </BitcoinQueryProvider>
  );
}
```

## Common Patterns

### Provider Nesting Order

```tsx
import { 
  BitcoinQueryProvider,
  BitcoinThemeProvider,
  BitcoinAuthProvider 
} from 'bigblocks';

// Correct nesting order (outside to inside):
// 1. BitcoinQueryProvider (provides React Query context)
// 2. BitcoinThemeProvider (provides theme context)
// 3. BitcoinAuthProvider (uses React Query for auth state)

export default function App() {
  return (
    <BitcoinQueryProvider>
      <BitcoinThemeProvider defaultTheme="orange">
        <BitcoinAuthProvider config={{ apiUrl: '/api' }}>
          <YourApp />
        </BitcoinAuthProvider>
      </BitcoinThemeProvider>
    </BitcoinQueryProvider>
  );
}
```

### Memory Optimization

```tsx
import { BitcoinQueryProvider } from 'bigblocks';
import { QueryClient } from '@tanstack/react-query';
import { useEffect } from 'react';

export default function MemoryOptimizedApp() {
  const queryClient = new QueryClient({
    defaultOptions: {
      queries: {
        cacheTime: 5 * 60 * 1000,      // Shorter cache time
        staleTime: 1 * 60 * 1000,      // Data stales quickly
        refetchOnMount: 'always',      // Always fetch fresh data
      },
    },
  });

// Clear cache on logout
  useEffect(() => {
    const handleLogout = () => {
      queryClient.clear();
    };

window.addEventListener('logout', handleLogout);
    return () => window.removeEventListener('logout', handleLogout);
  }, [queryClient]);

return (
    <BitcoinQueryProvider queryClient={queryClient}>
      <App />
    </BitcoinQueryProvider>
  );
}
```

### With Suspense

```tsx
import { BitcoinQueryProvider } from 'bigblocks';
import { QueryClient } from '@tanstack/react-query';
import { Suspense } from 'react';

export default function SuspenseApp() {
  const queryClient = new QueryClient({
    defaultOptions: {
      queries: {
        suspense: true,                // Enable suspense mode
        useErrorBoundary: true,        // Use error boundaries
      },
    },
  });

return (
    <BitcoinQueryProvider queryClient={queryClient}>
      <ErrorBoundary fallback={<ErrorPage />}>
        <Suspense fallback={<LoadingSpinner />}>
          <App />
        </Suspense>
      </ErrorBoundary>
    </BitcoinQueryProvider>
  );
}
```

## Benefits

### 1. Request Deduplication

Multiple components requesting the same data will result in a single network request:

```tsx
// Both components will share the same query
function ComponentA() {
  const { data } = useQuery({ queryKey: ['market'] });
  return <div>{data}</div>;
}

function ComponentB() {
  const { data } = useQuery({ queryKey: ['market'] });
  return <div>{data}</div>;
}
```

### 2. Background Updates

Data is refetched in the background when it becomes stale:

```tsx
// Data will be cached and updated in background
const { data, isStale } = useQuery({
  queryKey: ['balance'],
  staleTime: 30 * 1000,  // Consider stale after 30 seconds
});
```

### 3. Optimistic Updates

Update UI immediately while the mutation is in progress:

```tsx
const mutation = useMutation({
  mutationFn: updateProfile,
  onMutate: async (newData) => {
    // Optimistically update the cache
    queryClient.setQueryData(['profile'], newData);
  },
});
```

### 4. Offline Support

Cached data remains available when offline:

```tsx
const { data, isLoading, isError } = useQuery({
  queryKey: ['profile'],
  networkMode: 'offlineFirst',  // Use cache when offline
});
```

## Working with BigBlocks Components

The BitcoinQueryProvider is required for these components:

* **MarketTable** - Market listings with real-time updates
* **PostButton** - Social post creation
* **SocialFeed** - Social content feed
* **WalletOverview** - Wallet balance and transactions
* **SendBSVButton** - Transaction operations

Example with market components:

```tsx
import { 
  BitcoinQueryProvider,
  MarketTable,
  CreateListingButton 
} from 'bigblocks';

export default function MarketplaceApp() {
  return (
    <BitcoinQueryProvider>
      <BitcoinAuthProvider config={{ apiUrl: '/api' }}>
        <CreateListingButton />
        <MarketTable />
      </BitcoinAuthProvider>
    </BitcoinQueryProvider>
  );
}
```

## Troubleshooting

### Missing QueryClient Error

```
Error: No QueryClient set, use QueryClientProvider to set one
```

**Solution**: Ensure BitcoinQueryProvider wraps all components that need React Query.

### Stale Closure Issues

```tsx
// ❌ Bad - stale closure
const queryClient = new QueryClient();

function App() {
  return <BitcoinQueryProvider queryClient={queryClient}>...</BitcoinQueryProvider>;
}

// ✅ Good - fresh instance
function App() {
  const queryClient = new QueryClient();
  return <BitcoinQueryProvider queryClient={queryClient}>...</BitcoinQueryProvider>;
}
```

### Cache Not Clearing

```tsx
// Clear all queries
queryClient.clear();

// Clear specific queries
queryClient.removeQueries({ queryKey: ['market'] });

// Invalidate to refetch
queryClient.invalidateQueries({ queryKey: ['balance'] });
```

## Best Practices

1. **Provider Order**: Always place BitcoinQueryProvider at the root
2. **Query Keys**: Use consistent, hierarchical query keys
3. **Stale Times**: Set appropriate stale times based on data type
4. **Error Handling**: Implement global error handling
5. **Memory Management**: Clear cache on logout

## Related Components

* [BitcoinAuthProvider](/docs/components/bitcoin-auth-provider) - Authentication provider
* [BitcoinThemeProvider](/docs/components/bitcoin-theme-provider) - Theme provider
* [MarketTable](/docs/components/market-table) - Requires query provider
* [SocialFeed](/docs/components/social-feed) - Requires query provider

## API Reference

### QueryClient Configuration

```typescript
interface QueryClientConfig {
  defaultOptions?: {
    queries?: {
      cacheTime?: number;
      staleTime?: number;
      refetchOnWindowFocus?: boolean;
      refetchOnReconnect?: boolean;
      refetchOnMount?: boolean | 'always';
      retry?: boolean | number | ((failureCount: number, error: any) => boolean);
      retryDelay?: number | ((attemptIndex: number) => number);
      networkMode?: 'online' | 'always' | 'offlineFirst';
    };
    mutations?: {
      retry?: boolean | number;
      retryDelay?: number;
      networkMode?: 'online' | 'always' | 'offlineFirst';
    };
  };
}
```

## Notes for Improvement

**Simplified Implementation**: The actual component is a simple wrapper around React Query's QueryClientProvider. The prompt described many advanced features that would be implemented in the consuming application rather than the provider itself. The actual component focuses on:

* Providing React Query context
* Working around bundler limitations
* Ensuring compatibility with BigBlocks components

The advanced query patterns, real-time updates, and optimization strategies described in the prompt would be implemented by developers using the provider, not within the provider component itself.

# BitcoinThemeProvider
URL: /docs/components/providers/bitcoin-theme-provider

Core theme provider for Bitcoin-inspired theming with extensive color schemes

***

title: BitcoinThemeProvider
description: Core theme provider for Bitcoin-inspired theming with extensive color schemes
category: providers
-------------------

The core theme provider component that enables Bitcoin-inspired theming across your entire application. Built on Radix Themes, it provides extensive color schemes, dark/light mode support, and comprehensive theme customization.

> **Note:** `BitcoinThemeProvider` is an alias for `BigBlocksThemeProvider`. Both names can be used interchangeably.

## Installation

```bash
npx bigblocks add bitcoin-theme-provider
```

## Import

```typescript
import { BitcoinThemeProvider } from 'bigblocks';
```

## Props

| Prop             | Type                                                 | Required | Default             | Description                                                   |
| ---------------- | ---------------------------------------------------- | -------- | ------------------- | ------------------------------------------------------------- |
| children         | `ReactNode`                                          | Yes      | -                   | Child components                                              |
| defaultTheme     | `BigBlocksTheme`                                     | No       | `'purple'`          | Default theme selection                                       |
| appearance       | `'light' \| 'dark' \| 'inherit'`                     | No       | `'inherit'`         | Color mode                                                    |
| storageKey       | `string`                                             | No       | `'bigblocks-theme'` | localStorage key for persistence                              |
| showThemePanel   | `boolean`                                            | No       | `false`             | Show dev theme panel                                          |
| skipThemeWrapper | `boolean`                                            | No       | `false`             | Skip Radix Theme wrapper (useful when already inside a Theme) |
| radius           | `'none' \| 'small' \| 'medium' \| 'large' \| 'full'` | No       | `'medium'`          | Border radius                                                 |
| scaling          | `'90%' \| '95%' \| '100%' \| '105%' \| '110%'`       | No       | `'100%'`            | UI scaling                                                    |
| grayColor        | `string`                                             | No       | `'auto'`            | Custom gray color                                             |
| panelBackground  | `'solid' \| 'translucent'`                           | No       | `'solid'`           | Panel background style                                        |
| hasBackground    | `boolean`                                            | No       | `false`             | Enable background                                             |

## Available Themes

The provider includes all Radix UI colors plus custom Bitcoin-inspired themes:

### Standard Colors

* `purple` - Default theme
* `orange` - Classic Bitcoin orange
* `blue`, `green`, `red`, `cyan`, `gray`
* `yellow`, `amber`, `lime`, `mint`, `sky`, `iris`
* `pink`, `plum`, `crimson`, `indigo`, `teal`, `jade`
* `grass`, `bronze`, `gold`, `brown`, `tomato`, `ruby`

### Custom Themes

* `light`, `dark` - Base light/dark themes
* `neo`, `cyberpunk`, `neon`, `noir` - Futuristic themes
* `aurora`, `nebula`, `prism`, `vortex` - Cosmic themes
* `forest`, `ocean`, `sunset`, `midnight` - Nature themes
* `dawn`, `twilight`, `storm`, `arctic` - Weather themes
* `rose`, `lavender`, `emerald`, `sapphire` - Gem themes
* `ruby`, `topaz`, `onyx`, `pearl` - Precious themes
* `vintage`, `sepia`, `monochrome` - Classic themes
* `pastel`, `vibrant`, `minimal`, `luxury`, `cosmic` - Style themes

## Basic Usage

```tsx
import { BitcoinThemeProvider } from 'bigblocks';

function App() {
  return (
    <BitcoinThemeProvider>
      <YourAppContent />
    </BitcoinThemeProvider>
  );
}
```

## Advanced Usage

### Custom Theme Selection

```tsx
import { BitcoinThemeProvider } from 'bigblocks';

export default function ThemedApp() {
  return (
    <BitcoinThemeProvider 
      defaultTheme="cyberpunk"
      appearance="dark"
      radius="large"
      scaling="105%"
    >
      <App />
    </BitcoinThemeProvider>
  );
}
```

### With Theme Persistence

```tsx
import { BitcoinThemeProvider } from 'bigblocks';

export default function PersistentThemeApp() {
  return (
    <BitcoinThemeProvider
      defaultTheme="ocean"
      appearance="inherit" // Follow system preference
      storageKey="my-app-theme"
    >
      <App />
    </BitcoinThemeProvider>
  );
}
```

### Development with Theme Panel

```tsx
import { BitcoinThemeProvider } from 'bigblocks';

export default function DevApp() {
  return (
    <BitcoinThemeProvider
      defaultTheme="orange"
      showThemePanel={process.env.NODE_ENV === 'development'}
      storageKey="dev-theme"
    >
      <App />
    </BitcoinThemeProvider>
  );
}
```

### Dynamic Theme Switching

```tsx
import { BitcoinThemeProvider, useTheme } from 'bigblocks';
import { useState } from 'react';

function ThemeSwitcher() {
  const { theme, setTheme } = useTheme();
  
  return (
    <select value={theme} onChange={(e) => setTheme(e.target.value)}>
      <option value="orange">Bitcoin Orange</option>
      <option value="cyberpunk">Cyberpunk</option>
      <option value="ocean">Ocean</option>
      <option value="cosmic">Cosmic</option>
    </select>
  );
}

export default function DynamicThemeApp() {
  return (
    <BitcoinThemeProvider defaultTheme="orange">
      <ThemeSwitcher />
      <App />
    </BitcoinThemeProvider>
  );
}
```

## Theme Hook

Use the `useBigBlocksTheme` hook (or the legacy `useTheme` alias) to access and control the current theme:

```tsx
import { useBigBlocksTheme } from 'bigblocks';
// or: import { useTheme } from 'bigblocks';

function ThemedComponent() {
  const { theme, setTheme } = useBigBlocksTheme();
  
  return (
    <div>
      <p>Current theme: {theme}</p>
      <button onClick={() => setTheme('neon')}>
        Switch to Neon
      </button>
    </div>
  );
}
```

## Common Patterns

### Provider Nesting Order

```tsx
import { 
  BitcoinQueryProvider,
  BitcoinThemeProvider,
  BitcoinAuthProvider 
} from 'bigblocks';

// Correct nesting order:
export default function App() {
  return (
    <BitcoinQueryProvider>
      <BitcoinThemeProvider defaultTheme="orange">
        <BitcoinAuthProvider config={{ apiUrl: '/api' }}>
          <YourApp />
        </BitcoinAuthProvider>
      </BitcoinThemeProvider>
    </BitcoinQueryProvider>
  );
}
```

### User-Based Theming

```tsx
import { BitcoinThemeProvider } from 'bigblocks';
import { useBitcoinAuth } from 'bigblocks';

export default function UserThemedApp() {
  const { user } = useBitcoinAuth();
  
  // Different themes for different user types
  const getUserTheme = () => {
    if (!user) return 'orange';
    if (user.isPremium) return 'gold';
    if (user.isDeveloper) return 'cyberpunk';
    if (user.isVerified) return 'emerald';
    return 'orange';
  };
  
  return (
    <BitcoinThemeProvider
      defaultTheme={getUserTheme()}
      storageKey={`theme-${user?.bapId}`}
    >
      <App />
    </BitcoinThemeProvider>
  );
}
```

### Route-Based Theming

```tsx
import { BitcoinThemeProvider } from 'bigblocks';
import { useLocation } from 'react-router-dom';

export default function RouteThemedApp() {
  const location = useLocation();
  
  const getRouteTheme = (pathname: string) => {
    if (pathname.startsWith('/wallet')) return 'gold';
    if (pathname.startsWith('/social')) return 'ocean';
    if (pathname.startsWith('/market')) return 'emerald';
    if (pathname.startsWith('/dev')) return 'cyberpunk';
    return 'orange';
  };
  
  return (
    <BitcoinThemeProvider
      defaultTheme={getRouteTheme(location.pathname)}
      appearance="dark"
    >
      <App />
    </BitcoinThemeProvider>
  );
}
```

### Accessibility Settings

```tsx
import { BitcoinThemeProvider } from 'bigblocks';
import { useEffect, useState } from 'react';

export default function AccessibleApp() {
  const [highContrast, setHighContrast] = useState(false);
  const [largeText, setLargeText] = useState(false);
  
  useEffect(() => {
    const mediaQuery = window.matchMedia('(prefers-contrast: high)');
    setHighContrast(mediaQuery.matches);
    
    const handleChange = (e) => setHighContrast(e.matches);
    mediaQuery.addEventListener('change', handleChange);
    
    return () => mediaQuery.removeEventListener('change', handleChange);
  }, []);
  
  return (
    <BitcoinThemeProvider
      defaultTheme={highContrast ? 'monochrome' : 'orange'}
      scaling={largeText ? '110%' : '100%'}
      radius="medium"
    >
      <App />
    </BitcoinThemeProvider>
  );
}
```

## CSS Variables

The theme provider makes numerous CSS variables available:

```css
/* Accent colors (1-12 scale) */
--accent-1 through --accent-12

/* Gray colors (1-12 scale) */
--gray-1 through --gray-12

/* Semantic colors */
--color-background
--color-panel
--color-overlay

/* Spacing */
--space-1 through --space-9

/* Radius */
--radius-1 through --radius-6

/* Font sizes */
--font-size-1 through --font-size-9

/* Shadows */
--shadow-1 through --shadow-6
```

## Custom Styling

```css
.custom-component {
  /* Use theme colors */
  background-color: var(--accent-3);
  color: var(--accent-11);
  border: 1px solid var(--accent-6);
  
  /* Use theme spacing */
  padding: var(--space-3);
  margin: var(--space-2);
  
  /* Use theme radius */
  border-radius: var(--radius-3);
  
  /* Use theme shadows */
  box-shadow: var(--shadow-2);
}

.custom-component:hover {
  background-color: var(--accent-4);
  box-shadow: var(--shadow-3);
}
```

## SSR Support

```tsx
// pages/_app.tsx (Next.js)
import { BitcoinThemeProvider } from 'bigblocks';

function MyApp({ Component, pageProps }) {
  return (
    <BitcoinThemeProvider
      defaultTheme="orange"
      appearance="inherit"
      storageKey="app-theme"
    >
      <Component {...pageProps} />
    </BitcoinThemeProvider>
  );
}

export default MyApp;
```

## Best Practices

1. **Single Provider**: Use one BitcoinThemeProvider at the app root
2. **Theme Persistence**: Use storageKey for consistent user experience
3. **System Preference**: Use `appearance="inherit"` to respect user settings
4. **Performance**: Theme changes use CSS variables for instant updates
5. **Accessibility**: Test themes with high contrast and color blindness simulators

## Troubleshooting

### Theme Not Persisting

```tsx
// Ensure storageKey is set
<BitcoinThemeProvider storageKey="my-theme">
```

### Hydration Mismatch

```tsx
// Wait for client-side mount
const [mounted, setMounted] = useState(false);

useEffect(() => {
  setMounted(true);
}, []);

if (!mounted) return null;

return <BitcoinThemeProvider>...</BitcoinThemeProvider>;
```

### Theme Not Updating

```tsx
// Ensure useTheme is called within provider
function Component() {
  const { theme, setTheme } = useTheme(); // Must be inside provider
  // ...
}
```

## Related Components

* [BitcoinQueryProvider](/docs/components/bitcoin-query-provider) - Data fetching provider
* [BitcoinAuthProvider](/docs/components/bitcoin-auth-provider) - Authentication provider
* [ThemeToggle](/docs/components/theme-toggle) - Theme switching UI
* [ThemeSelector](/docs/components/theme-selector) - Theme selection dropdown

## API Reference

### BigBlocksTheme Type

// Legacy alias
type BitcoinTheme = BigBlocksTheme;
```

### useBigBlocksTheme Hook

```typescript
interface ThemeContextValue {
  theme: BigBlocksTheme;
  setTheme: (theme: BigBlocksTheme) => void;
}
```

## Special Features

### Skip Theme Wrapper

The `skipThemeWrapper` prop is useful when you need to use BitcoinThemeProvider inside another Radix Theme:

```tsx
// When already inside a Radix Theme
<Theme>
  <BitcoinThemeProvider skipThemeWrapper>
    <App />
  </BitcoinThemeProvider>
</Theme>
```

This prevents the "useThemeContext must be used within a Theme" error when nesting providers.

## Notes for Improvement

**Extended Theme Support**: The actual component supports many more themes than the prompt described, including all Radix UI colors plus extensive custom themes. The implementation is built directly on Radix Themes rather than being a custom solution, providing better compatibility and performance.

# CompactMessageButton
URL: /docs/components/social/compact-message-button

A space-efficient messaging component that opens a popover for composing secure Bitcoin-based messages

***

title: CompactMessageButton
description: A space-efficient messaging component that opens a popover for composing secure Bitcoin-based messages
category: social
----------------

A compact messaging component that provides a clean, space-efficient interface for composing and sending messages via Bitcoin transactions. Perfect for inline messaging in social feeds, user profiles, or chat interfaces where space is at a premium.

[View Component Preview →](/component-preview/compact-message-button)

## Installation

```bash
npx bigblocks add compact-message-button
```

## Import

```typescript
import { CompactMessageButton } from 'bigblocks';
```

## Props

| Prop                 | Type                                          | Required | Default               | Description                             |
| -------------------- | --------------------------------------------- | -------- | --------------------- | --------------------------------------- |
| onMessage            | `(message: Message) => void \| Promise<void>` | Yes      | -                     | Callback when message is sent           |
| recipientName        | `string`                                      | No       | -                     | Display name of the message recipient   |
| recipientAvatar      | `string`                                      | No       | -                     | Avatar URL of the recipient             |
| recipientAddress     | `string`                                      | Yes      | -                     | Bitcoin address of the recipient        |
| defaultContent       | `string`                                      | No       | `''`                  | Pre-filled message content              |
| placeholder          | `string`                                      | No       | `'Type a message...'` | Input placeholder text                  |
| maxLength            | `number`                                      | No       | `500`                 | Maximum message length                  |
| align                | `'start' \| 'center' \| 'end'`                | No       | `'end'`               | Popover alignment                       |
| side                 | `'top' \| 'right' \| 'bottom' \| 'left'`      | No       | `'bottom'`            | Popover side                            |
| iconSize             | `number`                                      | No       | `16`                  | Size of the chat icon in pixels         |
| allowRecipientChange | `boolean`                                     | No       | `false`               | Allow changing recipient in the popover |
| variant              | `ButtonVariant`                               | No       | `'ghost'`             | Button style variant                    |
| size                 | `'1' \| '2' \| '3' \| '4'`                    | No       | `'2'`                 | Button size                             |
| disabled             | `boolean`                                     | No       | `false`               | Disable the button                      |
| className            | `string`                                      | No       | -                     | Additional CSS classes                  |

## Basic Usage

```tsx
import { CompactMessageButton } from 'bigblocks';

function UserProfile({ user }) {
  return (
    <CompactMessageButton
      recipientName={user.name}
      recipientAvatar={user.avatar}
      recipientAddress={user.address}
      onMessage={(message) => {
        console.log('Message sent:', message);
      }}
    />
  );
}
```

## Advanced Usage

```tsx
import { CompactMessageButton } from 'bigblocks';
import { toast } from 'sonner';

return (
    <CompactMessageButton
      recipientName="Alice"
      recipientAvatar="/avatars/alice.jpg"
      recipientAddress="1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa"
      defaultContent="Hey Alice, "
      placeholder="Write your message..."
      maxLength={280}
      align="start"
      side="top"
      iconSize={20}
      variant="soft"
      size="3"
      onMessage={handleMessage}
    />
  );
}
```

## Message Object

The `onMessage` callback receives a message object with the following structure:

```typescript
interface Message {
  txId: string;        // Bitcoin transaction ID of the message
  content: string;     // The actual message text
  recipient: string;   // Recipient's Bitcoin address
  timestamp: number;   // Unix timestamp when message was sent
  contentType: string; // MIME type (default: 'text/plain')
}
```

## Common Patterns

### In User Lists

Display compact message buttons next to user names in lists:

```tsx
import { CompactMessageButton } from 'bigblocks';

function UserList({ users }) {
  return (
    <div className="space-y-2">
      {users.map(user => (
        <div key={user.id} className="flex items-center justify-between p-3 hover:bg-gray-50">
          <div className="flex items-center gap-3">
            <img src={user.avatar} className="w-10 h-10 rounded-full" />
            <span className="font-medium">{user.name}</span>
          </div>
          <CompactMessageButton
            recipientName={user.name}
            recipientAvatar={user.avatar}
            recipientAddress={user.address}
            size="1"
            variant="ghost"
          />
        </div>
      ))}
    </div>
  );
}
```

### In Social Feed Actions

Add messaging to post action bars:

```tsx
import { CompactMessageButton, LikeButton, FollowButton } from 'bigblocks';

function PostActions({ post }) {
  return (
    <div className="flex items-center gap-2 mt-4">
      <LikeButton postId={post.id} />
      <CompactMessageButton
        recipientName={post.author.name}
        recipientAvatar={post.author.avatar}
        recipientAddress={post.author.address}
        size="2"
      />
      <FollowButton userAddress={post.author.address} />
    </div>
  );
}
```

### Direct Message Composer

Allow users to compose messages without a predefined recipient:

```tsx
import { CompactMessageButton } from 'bigblocks';
import { useContacts } from '@/hooks/useContacts';

### Reply to Message

Pre-fill content for replies:

```tsx
function MessageReply({ originalMessage }) {
  return (
    <CompactMessageButton
      recipientName={originalMessage.senderName}
      recipientAddress={originalMessage.senderAddress}
      defaultContent={`Re: ${originalMessage.subject}`}
      onMessage={handleReply}
      size="1"
      variant="ghost"
    />
  );
}
```

## Authentication Requirements

The CompactMessageButton requires Bitcoin authentication to send messages. Wrap your app with the necessary providers:

```tsx
import { 
  BitcoinAuthProvider, 
  BitcoinQueryProvider,
  BitcoinThemeProvider 
} from 'bigblocks';

function App() {
  return (
    <BitcoinQueryProvider>
      <BitcoinAuthProvider config={{ apiUrl: '/api' }}>
        <BitcoinThemeProvider>
          <YourApp />
        </BitcoinThemeProvider>
      </BitcoinAuthProvider>
    </BitcoinQueryProvider>
  );
}
```

When not authenticated, the button will be disabled automatically.

## Popover Interface

The component opens a popover with the following layout:

```
┌─────────────────────────┐
│ Send Message           │
│ To: 👤 John Doe        │
├─────────────────────────┤
│                         │
│ [Message text area]     │
│                         │
│                         │
├─────────────────────────┤
│ 245 chars   Cmd+Enter   │
│            [✉️ Send]    │
└─────────────────────────┘
```

### Character Counter

The character counter provides visual feedback:

* **Green**: More than 50 characters remaining
* **Orange**: Less than 50 characters remaining
* **Red**: Over the character limit (send button disabled)

### Keyboard Shortcuts

* **Cmd/Ctrl + Enter**: Send the message
* **Escape**: Close the popover

## Bitcoin Integration

### On-Chain Messaging

Messages are broadcast as Bitcoin transactions using the MAP (Magic Attribute Protocol) standard:

```typescript
// Example MAP transaction structure
{
  "app": "messaging",
  "type": "message",
  "content": "Hello Alice!",
  "recipient": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
  "timestamp": 1704067200000,
  "contentType": "text/plain"
}
```

### Cost Considerations

* Each message costs approximately $0.001 in transaction fees
* Messages are permanently stored on the blockchain
* Consider implementing off-chain storage for longer conversations

### Privacy Notes

* Messages are public on the blockchain
* Consider encryption for sensitive communications
* Use the component's integration with BAP identity for verified senders

## Styling

The component uses BigBlocks layout constants for consistent sizing:

```tsx
// Internal styling uses:
CONTAINER_WIDTHS.POPOVER_SMALL // 320px popover width
```

### Theme Adaptation

The component automatically adapts to your BitcoinThemeProvider settings:

* Button variants respect theme colors
* Text and borders follow theme contrast ratios
* Dark mode is fully supported

### Custom Styling

Apply custom styles with the className prop:

```tsx
<CompactMessageButton
  className="hover:scale-105 transition-transform"
  recipientAddress={address}
  onMessage={handleMessage}
/>
```

## Error Handling

```tsx
function MessageWithErrorHandling() {
  const handleMessage = async (message: Message) => {
    try {
      // Message is already broadcast, handle additional logic
      await saveToDatabase(message);
    } catch (error) {
      if (error.code === 'INSUFFICIENT_FUNDS') {
        toast.error('Not enough BSV to send message');
      } else if (error.code === 'NETWORK_ERROR') {
        toast.error('Network error. Please try again.');
      } else {
        toast.error('Failed to send message');
      }
    }
  };

return (
    <CompactMessageButton
      recipientAddress="..."
      onMessage={handleMessage}
    />
  );
}
```

## Best Practices

1. **Always Provide Recipient Info**: Include name and avatar when available for better UX
2. **Handle Async Operations**: The onMessage callback can be async for additional processing
3. **Size Appropriately**: Match button size to surrounding UI elements
4. **Provide Feedback**: Show success/error states after message operations
5. **Consider Rate Limiting**: Implement client-side rate limiting for high-traffic applications
6. **Test Authentication States**: Ensure graceful handling when users aren't authenticated

## Accessibility

* **ARIA Labels**: Button includes proper labels for screen readers
* **Keyboard Navigation**: Full keyboard support including focus management
* **Disabled States**: Clear visual indicators when button is disabled
* **Loading States**: Accessible loading indicators during message sending

## Troubleshooting

### Button Disabled

* **Solution**: Ensure user is authenticated with BitcoinAuthProvider
* **Check**: Verify Bitcoin keypair is available in session

### Message Not Sending

* **Solution**: Check Bitcoin balance for transaction fees
* **Verify**: Network connectivity and API endpoint configuration

### Popover Not Opening

* **Solution**: Check z-index conflicts with other UI elements
* **Verify**: No parent elements have `overflow: hidden`

## Related Components

* [PostButton](/docs/components/post-button) - For creating posts
* [MessageDisplay](/docs/components/message-display) - For displaying messages
* [SocialFeed](/docs/components/social-feed) - For message feeds
* [ProfilePopover](/docs/components/profile-popover) - For user profiles

## API Reference

### Message Type

```typescript
interface Message {
  txId: string;        // Bitcoin transaction ID
  content: string;     // Message content
  recipient: string;   // Recipient Bitcoin address
  timestamp: number;   // Unix timestamp
  contentType: string; // MIME type
}
```

### ButtonVariant Type

# CompactPostButton
URL: /docs/components/social/compact-post-button

Space-efficient button for creating on-chain social posts with minimal UI footprint, perfect for toolbars and mobile interfaces

***

title: CompactPostButton
description: Space-efficient button for creating on-chain social posts with minimal UI footprint, perfect for toolbars and mobile interfaces
category: social
----------------

A space-efficient button for creating on-chain posts on the Bitcoin blockchain using the bSocial protocol. Designed for toolbars, sidebars, and mobile interfaces where screen space is limited.

[View Component Preview →](/component-preview/compact-post-button)

## Installation

```bash
npx bigblocks add compact-post-button
```

## Import

```typescript
import { CompactPostButton } from 'bigblocks';
```

## Props

| Prop        | Type                           | Required | Default                | Description                                             |
| ----------- | ------------------------------ | -------- | ---------------------- | ------------------------------------------------------- |
| onSuccess   | `(result: PostResult) => void` | No       | -                      | Callback after successful post with transaction details |
| onError     | `(error: Error) => void`       | No       | -                      | Error callback for handling failures                    |
| placeholder | `string`                       | No       | `'Write something...'` | Input placeholder text                                  |
| maxLength   | `number`                       | No       | `217`                  | Maximum post length in characters                       |
| className   | `string`                       | No       | -                      | Additional CSS classes for customization                |

### PostResult Interface

```typescript
interface PostResult {
  txid: string;           // Transaction ID on blockchain
  content: string;        // Post content
  author: {
    idKey: string;        // BAP identity key
    address: string;      // Bitcoin address
  };
  timestamp: number;      // Creation timestamp
  fee: number;           // Transaction fee in satoshis
}
```

## Basic Usage

```tsx
import { CompactPostButton } from 'bigblocks';

export default function Toolbar() {
  return (
    <div className="toolbar">
      <CompactPostButton />
    </div>
  );
}
```

## Advanced Usage

### With Success Handler

```tsx
import { CompactPostButton } from 'bigblocks';
import { toast } from 'sonner';

export default function SocialToolbar() {
  const handlePostSuccess = (result) => {
    console.log('Posted! TxID:', result.txid);
    toast.success('Post created on blockchain!');
    
    // Update feed or trigger refresh
    refreshFeed();
  };

return (
    <CompactPostButton 
      onSuccess={handlePostSuccess}
      placeholder="Share your thoughts..."
    />
  );
}
```

### Error Handling

```tsx
import { CompactPostButton } from 'bigblocks';
import { useState } from 'react';

export default function PostWithErrorHandling() {
  const [lastError, setLastError] = useState(null);

return (
    <div>
      <CompactPostButton 
        onSuccess={(result) => console.log('Success:', result)}
        onError={handleError}
      />
      
      {lastError && (
        <div className="text-red-500 text-sm mt-2">
          Last error: {lastError.message}
        </div>
      )}
    </div>
  );
}
```

### Custom Character Limit

```tsx
import { CompactPostButton } from 'bigblocks';

export default function TwitterStylePost() {
  return (
    <CompactPostButton 
      maxLength={280}
      placeholder="What's happening?"
      onSuccess={(result) => {
        console.log('Tweet-style post created:', result);
      }}
    />
  );
}
```

### Custom Styling

```tsx
import { CompactPostButton } from 'bigblocks';

export default function StyledCompactPost() {
  return (
    <CompactPostButton 
      className="bg-gradient-to-r from-purple-500 to-pink-500 hover:from-purple-600 hover:to-pink-600"
      placeholder="Share something amazing..."
      onSuccess={(result) => console.log('Styled post:', result)}
    />
  );
}
```

## Common Patterns

### Mobile Navigation Bar

```tsx
import { CompactPostButton } from 'bigblocks';

export default function MobileNav() {
  return (
    <nav className="fixed bottom-0 left-0 right-0 bg-white border-t">
      <div className="flex items-center justify-between p-2">
        <button className="p-2">Home</button>
        <button className="p-2">Search</button>
        
        <CompactPostButton 
          className="flex-1 mx-2"
          placeholder="Quick post..."
          onSuccess={(result) => {
            // Navigate to post
            router.push(`/posts/${result.txid}`);
          }}
        />
        
        <button className="p-2">Messages</button>
        <button className="p-2">Profile</button>
      </div>
    </nav>
  );
}
```

### Floating Action Button

```tsx
import { CompactPostButton } from 'bigblocks';

export default function FloatingPost() {
  return (
    <div className="fixed bottom-4 right-4 z-50">
      <CompactPostButton 
        className="shadow-lg rounded-full"
        placeholder="Share update..."
        onSuccess={(result) => {
          toast.success('Posted!');
          refreshFeed();
        }}
      />
    </div>
  );
}
```

### Sidebar Integration

```tsx
import { CompactPostButton } from 'bigblocks';

export default function SidebarWithPost() {
  return (
    <aside className="w-64 bg-gray-50 p-4">
      <h3 className="font-semibold mb-4">Quick Actions</h3>
      
      <div className="space-y-3">
        <CompactPostButton 
          className="w-full"
          placeholder="Quick update..."
          onSuccess={(result) => console.log('Posted:', result)}
        />
        
        <button className="w-full bg-gray-200 p-2 rounded">
          View Feed
        </button>
        
        <button className="w-full bg-gray-200 p-2 rounded">
          My Posts
        </button>
      </div>
    </aside>
  );
}
```

### Toolbar Integration

```tsx
import { CompactPostButton } from 'bigblocks';

export default function AppToolbar() {
  return (
    <div className="bg-white border-b px-4 py-2">
      <div className="flex items-center space-x-4">
        <h1 className="text-xl font-bold">Social App</h1>
        
        <div className="flex-1 max-w-md">
          <CompactPostButton 
            placeholder="Share something..."
            onSuccess={(result) => {
              // Add to feed immediately
              addToFeed(result);
            }}
          />
        </div>
        
        <div className="flex space-x-2">
          <button>Notifications</button>
          <button>Settings</button>
        </div>
      </div>
    </div>
  );
}
```

### Reply Interface

```tsx
import { CompactPostButton } from 'bigblocks';

export default function ReplyBox({ parentPost }) {
  return (
    <div className="border-l-2 border-gray-200 pl-4 ml-4">
      <CompactPostButton 
        placeholder={`Reply to ${parentPost.author.name}...`}
        maxLength={200}
        className="text-sm"
        onSuccess={(result) => {
          // Link reply to parent post
          linkReply(parentPost.txid, result.txid);
        }}
      />
    </div>
  );
}
```

## Authentication Requirements

The CompactPostButton requires Bitcoin authentication context to create posts:

```tsx
import { BitcoinAuthProvider, BitcoinQueryProvider, CompactPostButton } from 'bigblocks';

function App() {
  return (
    <BitcoinQueryProvider>
      <BitcoinAuthProvider config={{ apiUrl: '/api' }}>
        <CompactPostButton 
          onSuccess={(result) => console.log('Posted:', result)}
        />
      </BitcoinAuthProvider>
    </BitcoinQueryProvider>
  );
}
```

## API Integration

### Post Creation Endpoint

The component integrates with the bSocial protocol API:

```typescript
POST /api/social/posts
{
  content: string;
  contentType: 'text/plain';
}

// Response
{
  success: boolean;
  result: {
    txid: string;
    content: string;
    author: {
      idKey: string;
      address: string;
    };
    timestamp: number;
    fee: number;
  };
}
```

### Error Response

```typescript
{
  success: false;
  error: {
    code: string;
    message: string;
  };
}
```

## Styling and Theming

### Default Styles

The component uses minimal styling to fit various design systems:

```css
.compact-post-button {
  display: inline-flex;
  align-items: center;
  gap: 0.5rem;
  padding: 0.5rem 1rem;
  border-radius: 0.375rem;
  transition: all 0.2s;
}

.compact-post-input {
  flex: 1;
  border: none;
  outline: none;
  background: transparent;
}

.compact-post-submit {
  opacity: 0.6;
  transition: opacity 0.2s;
}

.compact-post-submit:enabled {
  opacity: 1;
  cursor: pointer;
}
```

### Theme Integration

```tsx
import { CompactPostButton, BitcoinThemeProvider } from 'bigblocks';

function ThemedApp() {
  return (
    <BitcoinThemeProvider theme="orange">
      <CompactPostButton 
        className="themed-post-button"
        onSuccess={(result) => console.log('Themed post:', result)}
      />
    </BitcoinThemeProvider>
  );
}
```

## Mobile Considerations

### Touch-Friendly Design

```tsx
import { CompactPostButton } from 'bigblocks';

export default function MobileOptimizedPost() {
  return (
    <CompactPostButton 
      className="min-h-[44px] text-base" // iOS touch target size
      placeholder="Tap to post..."
      onSuccess={(result) => {
        // Haptic feedback on mobile
        if ('vibrate' in navigator) {
          navigator.vibrate(50);
        }
        handleSuccess(result);
      }}
    />
  );
}
```

### Responsive Layout

```tsx
import { CompactPostButton } from 'bigblocks';

export default function ResponsivePost() {
  return (
    <>
      {/* Mobile: Fixed bottom */}
      <div className="md:hidden fixed bottom-0 left-0 right-0 p-2 bg-white border-t">
        <CompactPostButton 
          className="w-full"
          placeholder="Post..."
          onSuccess={handlePost}
        />
      </div>
      
      {/* Desktop: In header */}
      <div className="hidden md:block">
        <CompactPostButton 
          className="max-w-md"
          placeholder="Share your thoughts..."
          onSuccess={handlePost}
        />
      </div>
    </>
  );
}
```

## Performance Optimization

### Debounced Input

The component automatically debounces input to prevent excessive re-renders:

```tsx
import { CompactPostButton } from 'bigblocks';
import { memo } from 'react';

// Memoize for performance in lists
const MemoizedCompactPost = memo(CompactPostButton);

export default function PostList({ items }) {
  return (
    <div>
      {items.map(item => (
        <div key={item.id} className="mb-4">
          <p>{item.content}</p>
          <MemoizedCompactPost 
            placeholder="Reply..."
            onSuccess={(result) => handleReply(item.id, result)}
          />
        </div>
      ))}
    </div>
  );
}
```

## Troubleshooting

### Common Issues

**Post not creating**

* Ensure user is authenticated with Bitcoin wallet
* Check wallet has sufficient BSV balance for fees (\~$0.001)
* Verify API endpoint is accessible

**Character limit not working**

* The `maxLength` prop enforces limit on input
* Default is 217 characters for optimal blockchain storage

**Component not responsive**

* Add responsive classes to `className` prop
* Use container queries for better adaptability

### Debug Mode

```tsx
import { CompactPostButton } from 'bigblocks';

export default function DebugPost() {
  return (
    <CompactPostButton 
      onSuccess={(result) => {
        console.log('Debug - Post Result:', {
          txid: result.txid,
          fee: `${result.fee} satoshis`,
          timestamp: new Date(result.timestamp).toISOString(),
          content: result.content,
          author: result.author
        });
      }}
      onError={(error) => {
        console.error('Debug - Post Error:', {
          code: error.code,
          message: error.message,
          stack: error.stack
        });
      }}
    />
  );
}
```

## Best Practices

1. **Feedback**: Always provide success/error feedback to users
2. **Character Limits**: Set appropriate limits for your use case
3. **Loading States**: Component shows loading state during posting
4. **Error Recovery**: Handle common errors gracefully
5. **Mobile UX**: Ensure touch targets meet accessibility standards

## Related Components

* [PostButton](/docs/components/post-button) - Full-featured post creation component
* [SocialFeed](/docs/components/social-feed) - Display social posts
* [PostCard](/docs/components/post-card) - Individual post display
* [CompactMessageButton](/docs/components/compact-message-button) - Compact messaging interface

## Notes

* Posts are permanently stored on the Bitcoin blockchain
* Each post costs a small transaction fee (\~$0.001)
* Content is limited to text for optimal blockchain efficiency
* Posts are visible globally once confirmed on-chain

# FollowButton
URL: /docs/components/social/follow-button

Follow and unfollow users with Bitcoin-based social interactions

***

title: FollowButton
description: Follow and unfollow users with Bitcoin-based social interactions
categories: \['social', 'actions', 'ui']
providers: \['BitcoinAuthProvider']
-----------------------------------

import { FollowButtonDemo } from '@/components/docs/demos/FollowButtonDemo'
import { ComponentBadges } from '@/components/docs/ComponentBadges'

A social interaction component that allows users to follow and unfollow other users using Bitcoin-based authentication. Integrates with the BigBlocks social system.

## Demo

## Installation

```bash
npx bigblocks add follow-button
```

## Import

```tsx
import { FollowButton } from 'bigblocks';
```

## Basic Usage

```tsx
<FollowButton
  targetAddress="1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa"
  isFollowing={false}
  onFollow={() => console.log('Following user')}
  onUnfollow={() => console.log('Unfollowing user')}
/>
```

## Props

| Prop          | Type                   | Required | Default       | Description                                |
| ------------- | ---------------------- | -------- | ------------- | ------------------------------------------ |
| targetAddress | `string`               | Yes      | -             | Bitcoin address of user to follow          |
| isFollowing   | `boolean`              | Yes      | -             | Current following state                    |
| onFollow      | `() => void`           | Yes      | -             | Callback when follow action is triggered   |
| onUnfollow    | `() => void`           | Yes      | -             | Callback when unfollow action is triggered |
| followText    | `string`               | No       | `'Follow'`    | Text displayed when not following          |
| unfollowText  | `string`               | No       | `'Following'` | Text displayed when following              |
| disabled      | `boolean`              | No       | `false`       | Disable the button                         |
| className     | `string`               | No       | -             | Additional CSS classes                     |
| size          | `'sm' \| 'md' \| 'lg'` | No       | `'md'`        | Button size                                |

## Examples

### Basic Follow Button

```tsx
<FollowButton
  targetAddress="1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa"
  isFollowing={false}
  onFollow={handleFollow}
  onUnfollow={handleUnfollow}
/>
```

### Custom Text

```tsx
<FollowButton
  targetAddress="1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa"
  isFollowing={false}
  followText="Subscribe"
  unfollowText="Subscribed"
  onFollow={handleSubscribe}
  onUnfollow={handleUnsubscribe}
/>
```

### Different Sizes

```tsx
{/* Small */}
<FollowButton
  targetAddress="1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa"
  isFollowing={false}
  size="sm"
  onFollow={handleFollow}
  onUnfollow={handleUnfollow}
/>

{/* Medium (default) */}
<FollowButton
  targetAddress="1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa"
  isFollowing={false}
  size="md"
  onFollow={handleFollow}
  onUnfollow={handleUnfollow}
/>

{/* Large */}
<FollowButton
  targetAddress="1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa"
  isFollowing={false}
  size="lg"
  onFollow={handleFollow}
  onUnfollow={handleUnfollow}
/>
```

### With Loading State

```tsx
<FollowButton
  targetAddress="1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa"
  isFollowing={isFollowing}
  disabled={loading}
  onFollow={async () => {
    setLoading(true);
    await followUser(targetAddress);
    setLoading(false);
  }}
  onUnfollow={async () => {
    setLoading(true);
    await unfollowUser(targetAddress);
    setLoading(false);
  }}
/>
```

## Backend Integration

The FollowButton integrates with the BigBlocks social API endpoints:

### Required Headers

```typescript
headers: {
  'X-Auth-Token': '<BSM signature>',
  'X-Decrypted-Backup': '<optional for multi-profile>',
  'Content-Type': 'application/json'
}
```

### Follow User

```typescript
POST /api/social/follow

Request Body:
{
  targetAddress: string;
}

Response:
{
  success: boolean;
  followId?: string;
  message?: string;
}
```

### Unfollow User

```typescript
DELETE /api/social/follow

Request Body:
{
  targetAddress: string;
}

Response:
{
  success: boolean;
  message?: string;
}
```

## Usage Patterns

### In Profile Cards

```tsx
import { ProfileCard, FollowButton } from 'bigblocks';

export function UserProfile({ user, currentUser }) {
  const [isFollowing, setIsFollowing] = useState(user.isFollowed);

return (
    <ProfileCard profile={user}>
      {currentUser.address !== user.address && (
        <FollowButton
          targetAddress={user.address}
          isFollowing={isFollowing}
          onFollow={() => setIsFollowing(true)}
          onUnfollow={() => setIsFollowing(false)}
        />
      )}
    </ProfileCard>
  );
}
```

### In User Lists

```tsx
import { FollowButton } from 'bigblocks';

export function UserList({ users, followStates, onFollowChange }) {
  return (
    <div className="space-y-4">
      {users.map(user => (
        <div key={user.address} className="flex items-center justify-between p-4 border rounded">
          <div className="flex items-center gap-3">
            <img src={user.avatar} className="w-10 h-10 rounded-full" />
            <div>
              <h3 className="font-medium">{user.name}</h3>
              <p className="text-sm text-muted-foreground">{user.bio}</p>
            </div>
          </div>
          <FollowButton
            targetAddress={user.address}
            isFollowing={followStates[user.address] || false}
            onFollow={() => onFollowChange(user.address, true)}
            onUnfollow={() => onFollowChange(user.address, false)}
          />
        </div>
      ))}
    </div>
  );
}
```

### With Analytics

```tsx
import { FollowButton } from 'bigblocks';
import { analytics } from '@/lib/analytics';

export function TrackedFollowButton({ targetAddress, ...props }) {
  const handleFollow = () => {
    analytics.track('user_followed', {
      targetAddress,
      timestamp: Date.now()
    });
    props.onFollow?.();
  };

const handleUnfollow = () => {
    analytics.track('user_unfollowed', {
      targetAddress,
      timestamp: Date.now()
    });
    props.onUnfollow?.();
  };

return (
    <FollowButton
      {...props}
      targetAddress={targetAddress}
      onFollow={handleFollow}
      onUnfollow={handleUnfollow}
    />
  );
}
```

## State Management

### Using React State

```tsx
import { useState } from 'react';
import { FollowButton } from 'bigblocks';

export function FollowExample() {
  const [follows, setFollows] = useState<Record<string, boolean>>({});

const handleFollow = (address: string) => {
    setFollows(prev => ({ ...prev, [address]: true }));
  };

const handleUnfollow = (address: string) => {
    setFollows(prev => ({ ...prev, [address]: false }));
  };

return (
    <FollowButton
      targetAddress="1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa"
      isFollowing={follows["1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa"] || false}
      onFollow={() => handleFollow("1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa")}
      onUnfollow={() => handleUnfollow("1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa")}
    />
  );
}
```

### Using Context

```tsx
import { createContext, useContext } from 'react';
import { FollowButton } from 'bigblocks';

const SocialContext = createContext();

export function FollowWithContext({ targetAddress }) {
  const { isFollowing, follow, unfollow } = useContext(SocialContext);

return (
    <FollowButton
      targetAddress={targetAddress}
      isFollowing={isFollowing(targetAddress)}
      onFollow={() => follow(targetAddress)}
      onUnfollow={() => unfollow(targetAddress)}
    />
  );
}
```

## Related Components

* [ProfileCard](/docs/components/profile-card) - Display user profiles with follow button
* [ProfilePopover](/docs/components/profile-popover) - Quick profile preview with follow action
* [UserList](/docs/components/user-list) - Lists of users with follow buttons
* [SocialFeed](/docs/components/social-feed) - Social feed with follow interactions

# FriendsDialog
URL: /docs/components/social/friends-dialog

Comprehensive friends management dialog with social networking features for Bitcoin-based applications

***

title: FriendsDialog
description: Comprehensive friends management dialog with social networking features for Bitcoin-based applications
category: social
----------------

import { FriendsDialogDemo } from '@/components/docs/demos/FriendsDialogDemo';

A comprehensive friends management dialog component that provides social networking functionality including friend lists, friend requests, mutual connections, and social discovery for Bitcoin-based applications. This component enables users to build trusted social networks using their Bitcoin identity as the foundation.

[View Component Preview →](/component-preview/friends-dialog)

## Installation

```bash
npx bigblocks add friends-dialog
```

## Import

```typescript
import { FriendsDialog } from 'bigblocks';
```

## Props

| Prop                    | Type                        | Required | Default | Description                     |
| ----------------------- | --------------------------- | -------- | ------- | ------------------------------- |
| isOpen                  | boolean                     | Yes      | -       | Dialog open state               |
| onClose                 | () => void                  | Yes      | -       | Close dialog callback           |
| onFriendRequest         | (bapId: string) => void     | No       | -       | Send friend request callback    |
| onAcceptRequest         | (requestId: string) => void | No       | -       | Accept friend request callback  |
| onRejectRequest         | (requestId: string) => void | No       | -       | Reject friend request callback  |
| onRemoveFriend          | (bapId: string) => void     | No       | -       | Remove existing friend callback |
| onBlockUser             | (bapId: string) => void     | No       | -       | Block user callback             |
| onUnblockUser           | (bapId: string) => void     | No       | -       | Unblock user callback           |
| onMessageFriend         | (bapId: string) => void     | No       | -       | Start conversation callback     |
| showMutualFriends       | boolean                     | No       | true    | Show mutual connections count   |
| enableFriendSuggestions | boolean                     | No       | true    | Show friend suggestions tab     |
| maxResults              | number                      | No       | 50      | Maximum results per section     |
| className               | string                      | No       | -       | Additional CSS classes          |

## Basic Usage

```tsx
import { FriendsDialog } from 'bigblocks';
import { useState } from 'react';

function SocialApp() {
  const [friendsOpen, setFriendsOpen] = useState(false);
  
  return (
    <div>
      <button onClick={() => setFriendsOpen(true)}>
        Friends
      </button>
      
      <FriendsDialog 
        isOpen={friendsOpen}
        onClose={() => setFriendsOpen(false)}
        onFriendRequest={(bapId) => console.log('Friend request sent to:', bapId)}
        onAcceptRequest={(requestId) => console.log('Accepted request:', requestId)}
      />
    </div>
  );
}
```

## Advanced Usage

### With All Features Enabled

```tsx
<FriendsDialog 
  isOpen={isOpen}
  onClose={handleClose}
  onFriendRequest={async (bapId) => {
    const result = await sendFriendRequest(bapId);
    toast.success('Friend request sent!');
  }}
  onAcceptRequest={async (requestId) => {
    await acceptFriendRequest(requestId);
    toast.success('Friend request accepted!');
  }}
  onRejectRequest={async (requestId) => {
    await rejectFriendRequest(requestId);
  }}
  onRemoveFriend={async (bapId) => {
    if (confirm('Remove this friend?')) {
      await removeFriend(bapId);
    }
  }}
  onBlockUser={async (bapId) => {
    if (confirm('Block this user?')) {
      await blockUser(bapId);
      toast.info('User blocked');
    }
  }}
  onMessageFriend={(bapId) => {
    router.push(`/messages/${bapId}`);
  }}
  showMutualFriends={true}
  enableFriendSuggestions={true}
  maxResults={100}
/>
```

## Common Patterns

### Social Discovery Integration

```tsx
function SocialDiscoveryApp() {
  const [activeTab, setActiveTab] = useState('friends');
  const { user } = useBitcoinAuth();
  const { friends, suggestions, nearbyUsers } = useSocialData();
  
  return (
    <FriendsDialog
      isOpen={true}
      onClose={() => {}}
      customTabs={[
        {
          id: 'discovery',
          label: 'Discover',
          content: (
            <div className="discovery-content">
              <div className="discovery-filters">
                <button 
                  className={activeTab === 'suggested' ? 'active' : ''}
                  onClick={() => setActiveTab('suggested')}
                >
                  Suggested for You
                </button>
                <button 
                  className={activeTab === 'nearby' ? 'active' : ''}
                  onClick={() => setActiveTab('nearby')}
                >
                  Nearby Users
                </button>
                <button 
                  className={activeTab === 'mutual' ? 'active' : ''}
                  onClick={() => setActiveTab('mutual')}
                >
                  Friends of Friends
                </button>
              </div>
              
              {activeTab === 'suggested' && (
                <SuggestedUsersList 
                  suggestions={suggestions}
                  onConnect={(bapId) => sendFriendRequest(bapId)}
                />
              )}
              
              {activeTab === 'nearby' && (
                <NearbyUsersList 
                  users={nearbyUsers}
                  onConnect={(bapId) => sendFriendRequest(bapId)}
                />
              )}
              
              {activeTab === 'mutual' && (
                <MutualFriendsList 
                  friends={friends}
                  onConnect={(bapId) => sendFriendRequest(bapId)}
                />
              )}
            </div>
          )
        }
      ]}
    />
  );
}
```

### Gaming Friends System

```tsx
function GamingFriendsManager() {
  const { onlineFriends, recentlyPlayed } = useGamingFriends();
  
  return (
    <FriendsDialog
      isOpen={true}
      onClose={() => {}}
      customTabs={[
        {
          id: 'online',
          label: `Online (${onlineFriends.length})`,
          content: (
            <div className="online-friends">
              {onlineFriends.map(friend => (
                <div key={friend.bapId} className="online-friend">
                  <div className="friend-status online" />
                  <BitcoinAvatar 
                    src={friend.avatar}
                    name={friend.name}
                    size="small"
                  />
                  <div className="friend-info">
                    <h5>{friend.name}</h5>
                    <p className="playing-game">
                      Playing: {friend.currentGame}
                    </p>
                  </div>
                  <div className="friend-actions">
                    <button onClick={() => inviteToGame(friend.bapId)}>
                      Invite
                    </button>
                    <button onClick={() => joinGame(friend.gameId)}>
                      Join
                    </button>
                  </div>
                </div>
              ))}
            </div>
          )
        }
      ]}
    />
  );
}
```

### Professional Networking

```tsx
function ProfessionalNetwork() {
  const { connections, pendingConnections } = useProfessionalNetwork();
  
  return (
    <FriendsDialog
      isOpen={true}
      onClose={() => {}}
      showMutualFriends={true}
      customTabs={[
        {
          id: 'connections',
          label: 'My Network',
          content: (
            <div className="professional-network">
              {connections.map(connection => (
                <div key={connection.bapId} className="connection-card">
                  <BitcoinAvatar 
                    src={connection.avatar}
                    name={connection.name}
                  />
                  <div className="connection-details">
                    <h4>{connection.name}</h4>
                    <p className="title">{connection.title}</p>
                    <p className="company">{connection.company}</p>
                    <div className="mutual-info">
                      {connection.mutualConnections} mutual connections
                    </div>
                  </div>
                  <button 
                    className="message-btn"
                    onClick={() => startConversation(connection.bapId)}
                  >
                    Message
                  </button>
                </div>
              ))}
            </div>
          )
        }
      ]}
    />
  );
}
```

## Authentication Requirements

The FriendsDialog component requires proper Bitcoin authentication context:

```tsx
import { 
  BitcoinAuthProvider, 
  BitcoinQueryProvider,
  BitcoinThemeProvider 
} from 'bigblocks';

function App() {
  return (
    <BitcoinQueryProvider>
      <BitcoinAuthProvider config={{ apiUrl: '/api' }}>
        <BitcoinThemeProvider>
          <YourAppWithFriendsDialog />
        </BitcoinThemeProvider>
      </BitcoinAuthProvider>
    </BitcoinQueryProvider>
  );
}
```

## API Reference

This component extends the Dialog primitive and provides comprehensive social networking functionality for Bitcoin-based applications.

## API Integration

The FriendsDialog component typically requires these backend endpoints:

### Friend Management

* `GET /api/friends` - Fetch user's friend list
* `POST /api/friends/request` - Send friend request
* `POST /api/friends/accept` - Accept friend request
* `POST /api/friends/reject` - Reject friend request
* `DELETE /api/friends/:bapId` - Remove friend
* `POST /api/friends/block` - Block user
* `DELETE /api/friends/block/:bapId` - Unblock user

### Social Discovery

* `GET /api/friends/suggestions` - Get friend suggestions
* `GET /api/friends/mutual/:bapId` - Get mutual friends
* `GET /api/friends/nearby` - Get nearby users (if location enabled)

### Example API Implementation

```typescript
// /api/friends/request
export async function POST(request: Request) {
  const { bapId } = await request.json();
  const session = await getSession();
  
  if (!session?.user?.bapId) {
    return new Response('Unauthorized', { status: 401 });
  }
  
  // Create friend request with Bitcoin signature
  const requestData = {
    from: session.user.bapId,
    to: bapId,
    timestamp: Date.now(),
    status: 'pending'
  };
  
  // Sign the request with user's Bitcoin key
  const signature = await signWithBitcoin(requestData);
  
  // Store in database
  await redis.hset(
    `friend-requests:${bapId}`,
    session.user.bapId,
    JSON.stringify({ ...requestData, signature })
  );
  
  return Response.json({ success: true, requestId: signature });
}
```

## Troubleshooting

### Friends List Not Loading

```tsx
// Ensure BitcoinQueryProvider is wrapping the component
<BitcoinQueryProvider>
  <FriendsDialog {...props} />
</BitcoinQueryProvider>
```

### Friend Requests Not Working

```tsx
// Check that callbacks are properly async
onFriendRequest={async (bapId) => {
  try {
    await sendFriendRequest(bapId);
  } catch (error) {
    console.error('Friend request failed:', error);
  }
}}
```

### Real-time Updates Not Working

```tsx
// Implement WebSocket or polling for real-time updates
useEffect(() => {
  const interval = setInterval(() => {
    refetchFriends();
    refetchRequests();
  }, 30000); // Poll every 30 seconds
  
  return () => clearInterval(interval);
}, []);
```

## Related Components

* [SocialFeed](/docs/components/social-feed) - Display social posts from friends
* [ProfileCard](/docs/components/profile-card) - Show user profile information
* [MessageDisplay](/docs/components/message-display) - Display messages between friends
* [FollowButton](/docs/components/follow-button) - Simple follow/unfollow functionality
* [ProfileDropdownMenu](/docs/components/profile-dropdown-menu) - Quick profile actions

## Advanced Features

### Custom Tab Implementation

```tsx
interface CustomTab {
  id: string;
  label: string;
  content: React.ReactNode;
  badge?: number;
}

const customTabs: CustomTab[] = [
  {
    id: 'groups',
    label: 'Groups',
    badge: 3,
    content: <GroupsList />
  },
  {
    id: 'events',
    label: 'Events',
    content: <EventInvitations />
  }
];

<FriendsDialog
  customTabs={customTabs}
  defaultTab="groups"
/>
```

### Friend Filtering and Sorting

```tsx
const [sortBy, setSortBy] = useState<'name' | 'activity' | 'reputation'>('name');
const [filterBy, setFilterBy] = useState<'all' | 'online' | 'verified'>('all');

### Privacy Controls

```tsx
const privacySettings = {
  showOnlineStatus: true,
  allowFriendRequests: true,
  showMutualFriends: true,
  requireApproval: true,
  blockList: ['bapId1', 'bapId2']
};

<FriendsDialog
  privacySettings={privacySettings}
  onUpdatePrivacy={(newSettings) => updatePrivacySettings(newSettings)}
/>
```

## Security Considerations

1. **Bitcoin Signature Verification**: All friend operations should be signed with the user's Bitcoin private key
2. **Privacy Settings**: Respect user privacy preferences when displaying mutual friends or online status
3. **Rate Limiting**: Implement rate limits on friend requests to prevent spam
4. **Block List Management**: Ensure blocked users cannot view any information about the blocking user
5. **Data Encryption**: Consider encrypting sensitive friend data in transit and at rest

## Best Practices

1. **Pagination**: For large friend lists, implement virtual scrolling or pagination
2. **Caching**: Use React Query or similar for efficient data caching
3. **Optimistic Updates**: Update UI immediately while API calls complete
4. **Error Handling**: Provide clear feedback for failed operations
5. **Mobile Responsiveness**: Ensure the dialog works well on mobile devices
6. **Accessibility**: Include proper ARIA labels and keyboard navigation

# LikeButton
URL: /docs/components/social/like-button

Add on-chain likes and reactions to social posts using the bSocial protocol

***

title: LikeButton
description: Add on-chain likes and reactions to social posts using the bSocial protocol
category: social
----------------

import { LikeButtonDemo } from '@/components/docs/demos/LikeButtonDemo';

A component for adding on-chain likes and reactions to social posts using the bSocial protocol. Supports emoji reactions, like counts, and real-time updates.

## Installation

```bash
npx bigblocks add like-button
```

## Import

```typescript
import { LikeButton, SimpleLikeButton, HeartButton } from 'bigblocks';
```

## Props

| Prop              | Type                      | Required | Default | Description                   |
| ----------------- | ------------------------- | -------- | ------- | ----------------------------- |
| txid              | `string`                  | Yes      | -       | Transaction ID of the post    |
| emoji             | `string`                  | No       | `'👍'`  | Emoji for the reaction        |
| autoFetch         | `boolean`                 | No       | `true`  | Auto-fetch like info          |
| likeInfo          | `LikeInfo`                | No       | -       | Pre-loaded like information   |
| isLiked           | `boolean`                 | No       | -       | Override liked state          |
| currentUserEmoji  | `string`                  | No       | -       | User's current emoji reaction |
| showCount         | `boolean`                 | No       | `true`  | Show like count               |
| enableEmojiPicker | `boolean`                 | No       | `false` | Enable emoji selection        |
| showTooltip       | `boolean`                 | No       | `false` | Show tooltip on hover         |
| onLike            | `(emoji: string) => void` | No       | -       | Like callback                 |
| onUnlike          | `(emoji: string) => void` | No       | -       | Unlike callback               |
| className         | `string`                  | No       | -       | Additional CSS classes        |
| variant           | `string`                  | No       | -       | Button variant                |
| size              | `string`                  | No       | -       | Button size                   |
| disabled          | `boolean`                 | No       | `false` | Disable interactions          |
| loading           | `boolean`                 | No       | `false` | Loading state                 |

## Basic Usage

```tsx
import { LikeButton } from 'bigblocks';

export default function PostActions({ post }) {
  return (
    <LikeButton
      txid={post.txid}
      onLike={(emoji) => {
        console.log(`Liked with ${emoji}`);
      }}
    />
  );
}
```

## Component Variations

### SimpleLikeButton

A basic like button without emoji picker:

```tsx
import { SimpleLikeButton } from 'bigblocks';

export default function SimplePost({ post }) {
  return (
    <SimpleLikeButton
      txid={post.txid}
      emoji="👍"
      onLike={() => console.log('Liked!')}
    />
  );
}
```

### HeartButton

A heart-specific like button:

```tsx
import { HeartButton } from 'bigblocks';

export default function HeartPost({ post }) {
  return (
    <HeartButton
      txid={post.txid}
      onLike={() => console.log('Hearted!')}
    />
  );
}
```

## Advanced Usage

### With Emoji Picker

```tsx
import { LikeButton } from 'bigblocks';

export default function EmojiReactions({ post }) {
  return (
    <LikeButton
      txid={post.txid}
      enableEmojiPicker={true}
      showTooltip={true}
      onLike={(emoji) => {
        console.log(`Reacted with ${emoji}`);
        // Update local state
      }}
      onUnlike={(emoji) => {
        console.log(`Removed ${emoji} reaction`);
      }}
    />
  );
}
```

### With Pre-loaded Data

```tsx
import { LikeButton } from 'bigblocks';

export default function PreloadedLikes({ post, likeInfo }) {
  return (
    <LikeButton
      txid={post.txid}
      likeInfo={likeInfo}
      autoFetch={false}
      currentUserEmoji={likeInfo.userReaction}
      onLike={(emoji) => {
        // Handle like
        updateLikeInfo(post.txid, emoji);
      }}
    />
  );
}
```

### Different States

```tsx
import { LikeButton } from 'bigblocks';

export default function LikeStates({ post }) {
  const [loading, setLoading] = useState(false);

return (
    <div className="space-y-4">
      {/* Normal state */}
      <LikeButton
        txid={post.txid}
        onLike={() => console.log('Liked')}
      />

{/* Loading state */}
      <LikeButton
        txid={post.txid}
        loading={true}
        onLike={() => console.log('Liked')}
      />

{/* Disabled state */}
      <LikeButton
        txid={post.txid}
        disabled={true}
        onLike={() => console.log('Liked')}
      />

{/* Pre-liked state */}
      <LikeButton
        txid={post.txid}
        isLiked={true}
        currentUserEmoji="❤️"
        onLike={() => console.log('Liked')}
      />
    </div>
  );
}
```

### Custom Styling

```tsx
import { LikeButton } from 'bigblocks';

export default function StyledLikes({ post }) {
  return (
    <LikeButton
      txid={post.txid}
      className="hover:scale-110 transition-transform"
      variant="ghost"
      size="large"
      showTooltip={true}
      onLike={(emoji) => {
        console.log('Styled like:', emoji);
      }}
    />
  );
}
```

## Common Patterns

### In Post Card

```tsx
import { LikeButton, PostCard } from 'bigblocks';

export default function SocialPost({ post }) {
  return (
    <div className="border rounded-lg p-4">
      <div className="mb-4">
        <h3 className="font-semibold">{post.author.name}</h3>
        <p>{post.content}</p>
      </div>
      
      <div className="flex items-center gap-4">
        <LikeButton
          txid={post.txid}
          enableEmojiPicker={true}
          onLike={(emoji) => {
            // Update post likes
            updatePostLikes(post.txid, emoji);
          }}
        />
        
        <button className="text-gray-500">
          💬 {post.commentCount}
        </button>
        
        <button className="text-gray-500">
          🔄 {post.shareCount}
        </button>
      </div>
    </div>
  );
}
```

### Multiple Reactions

```tsx
import { LikeButton } from 'bigblocks';

export default function MultipleReactions({ post }) {
  const reactions = ['👍', '❤️', '😂', '😮', '😢', '😡'];

return (
    <div className="flex items-center gap-2">
      {reactions.map(emoji => (
        <LikeButton
          key={emoji}
          txid={post.txid}
          emoji={emoji}
          showCount={false}
          className="min-w-8"
          onLike={() => {
            console.log(`Reacted with ${emoji}`);
          }}
        />
      ))}
      
      <span className="text-sm text-gray-500 ml-2">
        {post.totalLikes} reactions
      </span>
    </div>
  );
}
```

### With Real-time Updates

```tsx
import { LikeButton } from 'bigblocks';
import { useEffect, useState } from 'react';

export default function RealtimeLikes({ post }) {
  const [likeInfo, setLikeInfo] = useState(post.likeInfo);

useEffect(() => {
    // Subscribe to real-time updates
    const eventSource = new EventSource(`/api/social/likes/stream`);
    
    eventSource.onmessage = (event) => {
      const data = JSON.parse(event.data);
      
      if (data.type === 'like_added' && data.postTxid === post.txid) {
        setLikeInfo(prev => ({
          ...prev,
          count: data.count,
          reactions: data.reactions
        }));
      }
    };

return () => eventSource.close();
  }, [post.txid]);

return (
    <LikeButton
      txid={post.txid}
      likeInfo={likeInfo}
      enableEmojiPicker={true}
      onLike={(emoji) => {
        // Optimistic update
        setLikeInfo(prev => ({
          ...prev,
          userReaction: emoji,
          count: prev.count + 1
        }));
      }}
    />
  );
}
```

### Error Handling

```tsx
import { LikeButton } from 'bigblocks';
import { useState } from 'react';

export default function ErrorHandlingLikes({ post }) {
  const [error, setError] = useState(null);

return (
    <div>
      {error && (
        <div className="text-red-500 text-sm mb-2">
          {error}
        </div>
      )}
      
      <LikeButton
        txid={post.txid}
        onLike={handleLike}
      />
    </div>
  );
}
```

## API Reference

This component extends the Button primitive and provides on-chain social reactions using the bSocial protocol.

## Types

```typescript
interface LikeInfo {
  count: number;              // Total likes
  reactions: {
    [emoji: string]: number;  // Count per emoji
  };
  userReaction?: string;      // Current user's emoji
  userLikes: string[];        // All user's emojis
}

interface LikeButtonProps {
  txid: string;               // Post transaction ID
  emoji?: string;             // Default emoji
  autoFetch?: boolean;        // Auto-fetch like data
  likeInfo?: LikeInfo;        // Pre-loaded data
  onLike?: (emoji: string) => void;
  onUnlike?: (emoji: string) => void;
  // ... other props
}
```

## Features

* **Multiple Emojis**: Support for any emoji reaction
* **Real-time Counts**: Live like count updates
* **Optimistic Updates**: Instant visual feedback
* **Emoji Picker**: Built-in emoji selection
* **Tooltip Support**: Hover information
* **Auto-fetch**: Automatic like data loading
* **Variants**: Different button styles and behaviors

## Requirements

* **Authentication**: User must be authenticated
* **Wallet Balance**: Sufficient BSV for transaction fees
* **Network**: Connection to Bitcoin network
* **Provider Context**: BitcoinQueryProvider wrapper

## Best Practices

1. **Optimistic Updates**: Update UI immediately
2. **Error Handling**: Handle network and balance errors
3. **Rate Limiting**: Prevent spam clicking
4. **Accessibility**: Support keyboard navigation
5. **Performance**: Cache like data when possible

## Troubleshooting

### Likes Not Updating

* Check authentication status
* Verify network connectivity
* Ensure sufficient wallet balance

### Emoji Picker Issues

* Verify `enableEmojiPicker` is true
* Check for JavaScript errors
* Ensure proper event handling

### Count Inconsistencies

* Check real-time update subscription
* Verify API response format
* Ensure proper state management

## Related Components

* [PostButton](/docs/components/post-button) - Create posts
* [FollowButton](/docs/components/follow-button) - Follow users
* [PostCard](/docs/components/post-card) - Display posts
* [SocialFeed](/docs/components/social-feed) - Social feed

## API Integration

The component integrates with bSocial protocol APIs:

```typescript
// Like a post
POST /api/social/likes
{
  postTxid: string;
  emoji: string;
}

// Unlike a post
DELETE /api/social/likes
{
  postTxid: string;
  emoji: string;
}

// Get like info
GET /api/social/posts/{txid}/likes
```

## Notes for Improvement

**Enhanced Implementation**: The actual component provides more sophisticated features than the prompt described:

* Integration with bmap-api-types for proper Bitcoin transaction handling
* Multiple component variants (Simple, Heart) for different use cases
* Emoji picker functionality for diverse reactions
* Auto-fetch capabilities for seamless data loading
* Better state management with pre-loaded data support

# PostButton
URL: /docs/components/social/post-button

Create on-chain social posts on the Bitcoin blockchain using the bSocial protocol

***

title: PostButton
description: Create on-chain social posts on the Bitcoin blockchain using the bSocial protocol
category: social
----------------

A component for creating on-chain social posts on the Bitcoin blockchain using the bSocial protocol. Provides a rich text editor with markdown support and content type selection.

## Installation

```bash
npx bigblocks add post-button
```

## Import

```typescript
import { PostButton } from 'bigblocks';
```

## Props

| Prop                    | Type                              | Required | Default  | Description                |
| ----------------------- | --------------------------------- | -------- | -------- | -------------------------- |
| onPost                  | `(post: PostTransaction) => void` | No       | -        | Callback after posting     |
| defaultContent          | `string`                          | No       | -        | Default content in editor  |
| placeholder             | `string`                          | No       | -        | Input placeholder text     |
| maxLength               | `number`                          | No       | -        | Character limit            |
| triggerText             | `string`                          | No       | `'Post'` | Button text                |
| showContentTypeSelector | `boolean`                         | No       | `false`  | Show content type dropdown |
| enableMarkdown          | `boolean`                         | No       | `false`  | Enable markdown support    |
| className               | `string`                          | No       | -        | Additional CSS classes     |
| variant                 | `string`                          | No       | -        | Button variant             |
| size                    | `string`                          | No       | -        | Button size                |
| disabled                | `boolean`                         | No       | `false`  | Disable posting            |

## Basic Usage

```tsx
import { PostButton } from 'bigblocks';

export default function SocialFeed() {
  const handlePost = (post) => {
    console.log('New post created:', post);
    // Refresh feed or add to state
  };

return (
    <PostButton
      onPost={handlePost}
      placeholder="What's on your mind?"
    />
  );
}
```

## Advanced Usage

### With Custom Configuration

```tsx
import { PostButton } from 'bigblocks';

export default function CustomPostButton() {
  return (
    <PostButton
      placeholder="Share your thoughts..."
      maxLength={500}
      triggerText="Share"
      showContentTypeSelector={true}
      enableMarkdown={true}
      onPost={(post) => {
        console.log('Posted:', post);
        toast.success('Post created successfully!');
      }}
    />
  );
}
```

### With Default Content

```tsx
import { PostButton } from 'bigblocks';

export default function PrefilledPost() {
  return (
    <PostButton
      defaultContent="Check out this awesome project!"
      placeholder="Add your thoughts..."
      onPost={(post) => {
        // Handle post creation
        addToFeed(post);
      }}
    />
  );
}
```

### Different Variants and Sizes

```tsx
import { PostButton } from 'bigblocks';

export default function StyledPostButtons() {
  return (
    <div className="space-y-4">
      <PostButton
        size="small"
        variant="outline"
        triggerText="Quick Post"
        onPost={handlePost}
      />
      
      <PostButton
        size="medium"
        variant="solid"
        triggerText="Post"
        onPost={handlePost}
      />
      
      <PostButton
        size="large"
        variant="ghost"
        triggerText="Share Story"
        onPost={handlePost}
      />
    </div>
  );
}
```

### With Markdown Support

```tsx
import { PostButton } from 'bigblocks';

export default function MarkdownPost() {
  return (
    <PostButton
      enableMarkdown={true}
      placeholder="Write your post with **markdown** support..."
      maxLength={1000}
      onPost={(post) => {
        console.log('Markdown post:', post);
      }}
    />
  );
}
```

### Content Type Selection

```tsx
import { PostButton } from 'bigblocks';

export default function ContentTypePost() {
  return (
    <PostButton
      showContentTypeSelector={true}
      placeholder="Select content type and write..."
      onPost={(post) => {
        console.log('Post type:', post.contentType);
        console.log('Content:', post.content);
      }}
    />
  );
}
```

## Common Patterns

### In Social Feed

```tsx
import { PostButton, SocialFeed } from 'bigblocks';
import { useState } from 'react';

export default function SocialApp() {
  const [posts, setPosts] = useState([]);

const handleNewPost = (post) => {
    // Add to feed immediately (optimistic update)
    setPosts(prevPosts => [post, ...prevPosts]);
    
    // Analytics
    analytics.track('post_created', {
      contentLength: post.content.length,
      hasMarkdown: post.enableMarkdown
    });
  };

return (
    <div className="max-w-2xl mx-auto">
      <div className="mb-6">
        <PostButton
          placeholder="What's happening?"
          onPost={handleNewPost}
          enableMarkdown={true}
        />
      </div>
      
      <SocialFeed posts={posts} />
    </div>
  );
}
```

### Reply to Post

```tsx
import { PostButton } from 'bigblocks';

export default function ReplyButton({ parentPost }) {
  return (
    <PostButton
      placeholder={`Reply to ${parentPost.author.name}...`}
      triggerText="Reply"
      size="small"
      defaultContent={`@${parentPost.author.name} `}
      onPost={(reply) => {
        // Handle reply
        addReply(parentPost.txid, reply);
      }}
    />
  );
}
```

### With Error Handling

```tsx
import { PostButton } from 'bigblocks';
import { useState } from 'react';

export default function ErrorHandlingPost() {
  const [error, setError] = useState(null);

return (
    <div>
      {error && (
        <div className="bg-red-100 text-red-700 p-3 rounded mb-4">
          {error}
        </div>
      )}
      
      <PostButton
        onPost={handlePost}
        placeholder="Share your thoughts..."
      />
    </div>
  );
}
```

### Custom Styling

```tsx
import { PostButton } from 'bigblocks';

export default function CustomStyledPost() {
  return (
    <PostButton
      className="bg-gradient-to-r from-purple-500 to-pink-500 text-white rounded-xl"
      placeholder="Create something amazing..."
      triggerText="✨ Create"
      onPost={(post) => {
        console.log('Styled post:', post);
      }}
    />
  );
}
```

### Character Counter

```tsx
import { PostButton } from 'bigblocks';

export default function LimitedPost() {
  return (
    <PostButton
      maxLength={280}
      placeholder="Share in 280 characters or less..."
      triggerText="Tweet"
      onPost={(post) => {
        if (post.content.length > 280) {
          toast.error('Post too long!');
          return;
        }
        handlePost(post);
      }}
    />
  );
}
```

## Post Transaction Type

```typescript
interface PostTransaction {
  txid: string;           // Transaction ID on blockchain
  content: string;        // Post content
  contentType?: string;   // Content type if selector enabled
  author: {
    idKey: string;        // BAP identity key
    name?: string;        // Author name
    address: string;      // Bitcoin address
  };
  timestamp: number;      // Creation timestamp
  block?: {
    height: number;       // Block height
    hash: string;         // Block hash
  };
  fee: number;           // Transaction fee in satoshis
  confirmed: boolean;     // Confirmation status
}
```

## Features

* **Blockchain Storage**: Posts are permanently stored on Bitcoin blockchain
* **Markdown Support**: Rich text formatting with markdown
* **Content Types**: Selectable content types for structured posts
* **Character Limits**: Configurable maximum length
* **Real-time Preview**: Preview formatted content before posting
* **Optimistic Updates**: Immediate UI feedback
* **Error Handling**: Comprehensive error states

## Content Types

When `showContentTypeSelector` is enabled, users can select:

* **Text**: Plain text posts
* **Markdown**: Formatted text with markdown
* **Code**: Code snippets with syntax highlighting
* **Quote**: Quoted text or citations
* **Announcement**: Important announcements
* **Question**: Questions for community
* **Answer**: Answers to questions

## Requirements

* **Authentication**: User must be authenticated with BigBlocks
* **Wallet Balance**: Sufficient BSV for transaction fees
* **Network**: Connection to Bitcoin network
* **Provider Context**: Must be wrapped in BitcoinQueryProvider

## Styling

The component uses Radix Themes and can be customized:

```css
/* Custom post button styles */
.post-button {
  min-height: 120px;
}

.post-editor {
  resize: vertical;
  font-family: inherit;
}

.content-type-selector {
  margin-bottom: 0.5rem;
}

.character-counter {
  text-align: right;
  font-size: 0.875rem;
  color: var(--gray-11);
}

.character-counter.over-limit {
  color: var(--red-11);
}
```

## Best Practices

1. **Content Guidelines**: Encourage meaningful content
2. **Fee Management**: Inform users about posting costs
3. **Error Feedback**: Provide clear error messages
4. **Optimistic Updates**: Show posts immediately
5. **Character Limits**: Set reasonable limits for readability

## Troubleshooting

### Posts Not Appearing

* Check user authentication status
* Verify wallet has sufficient balance
* Ensure network connectivity
* Check for transaction confirmation

### Markdown Not Rendering

* Verify `enableMarkdown` is true
* Check markdown syntax
* Ensure preview is working

### Content Type Issues

* Verify `showContentTypeSelector` is enabled
* Check default content type selection
* Ensure proper type validation

## Related Components

* [SocialFeed](/docs/components/social-feed) - Display posts
* [PostCard](/docs/components/post-card) - Individual post display
* [LikeButton](/docs/components/like-button) - Like posts
* [FollowButton](/docs/components/follow-button) - Follow users

## API Integration

The component integrates with bSocial protocol APIs:

```typescript
// Post creation endpoint
POST /api/social/posts
{
  content: string;
  contentType?: string;
  replyTo?: string;
}

// Response
{
  txid: string;
  post: PostTransaction;
  fee: number;
}
```

## Notes for Improvement

**Focused Implementation**: The actual component is more focused than the prompt described:

* Uses bmap-api-types for proper Bitcoin transaction integration
* Includes content type selection and markdown support
* Simpler props interface focused on essential functionality
* No built-in media upload (handled separately)
* Direct integration with blockchain posting services

# PostCard
URL: /docs/components/social/post-card

Display individual social media posts with author info, content, media, and interaction buttons for on-chain social experiences

***

title: PostCard
description: Display individual social media posts with author info, content, media, and interaction buttons for on-chain social experiences
category: social
----------------

A component for displaying individual social media posts from the Bitcoin blockchain with author information, rich content, media support, and interaction capabilities.

## Installation

```bash
npx bigblocks add post-card
```

## Import

```typescript
import { PostCard } from 'bigblocks';
```

## Preview

[View PostCard examples →](/component-preview/post-card)

## Props

| Prop          | Type                              | Required | Default | Description                              |
| ------------- | --------------------------------- | -------- | ------- | ---------------------------------------- |
| post          | `PostTransaction`                 | Yes      | -       | Post transaction data from blockchain    |
| meta          | `PostMeta`                        | No       | -       | Additional post metadata                 |
| signer        | `BapIdentity`                     | No       | -       | Current user's identity for interactions |
| showActions   | `boolean`                         | No       | `true`  | Show like, reply, share buttons          |
| showAuthor    | `boolean`                         | No       | `true`  | Show author information                  |
| showTimestamp | `boolean`                         | No       | `true`  | Show post timestamp                      |
| compact       | `boolean`                         | No       | `false` | Use compact layout                       |
| onReply       | `(post: PostTransaction) => void` | No       | -       | Reply button callback                    |
| onShare       | `(post: PostTransaction) => void` | No       | -       | Share button callback                    |
| onUserClick   | `(identity: BapIdentity) => void` | No       | -       | Author click callback                    |
| className     | `string`                          | No       | -       | Additional CSS classes                   |

## Basic Usage

```tsx
import { PostCard } from 'bigblocks';

export default function PostDisplay({ post }) {
  const handleReply = (post) => {
    console.log('Replying to post:', post.txid);
    // Open reply composer
  };

const handleShare = (post) => {
    console.log('Sharing post:', post.txid);
    // Open share dialog
  };

const handleUserClick = (identity) => {
    console.log('Viewing user:', identity.idKey);
    // Navigate to user profile
  };

return (
    <PostCard
      post={post}
      onReply={handleReply}
      onShare={handleShare}
      onUserClick={handleUserClick}
    />
  );
}
```

## Advanced Usage

### Social Feed Integration

```tsx
import { PostCard, SocialFeed } from 'bigblocks';
import { useState } from 'react';

export default function SocialFeedWithPosts() {
  const [replyingTo, setReplyingTo] = useState(null);
  const [sharedPost, setSharedPost] = useState(null);

const handleReply = (post) => {
    setReplyingTo(post);
    // Open reply modal/composer
  };

const handleShare = (post) => {
    setSharedPost(post);
    // Open share modal with options
  };

const handleUserClick = (identity) => {
    // Navigate to user profile
    router.push(`/profile/${identity.idKey}`);
  };

return (
    <div className="social-feed">
      <SocialFeed
        feedType="timeline"
        renderPost={(post, meta) => (
          <PostCard
            key={post.txid}
            post={post}
            meta={meta}
            onReply={handleReply}
            onShare={handleShare}
            onUserClick={handleUserClick}
            className="mb-4 border rounded-lg"
          />
        )}
      />
      
      {replyingTo && (
        <ReplyModal
          post={replyingTo}
          onClose={() => setReplyingTo(null)}
        />
      )}
      
      {sharedPost && (
        <ShareModal
          post={sharedPost}
          onClose={() => setSharedPost(null)}
        />
      )}
    </div>
  );
}
```

### Thread View Display

```tsx
import { PostCard } from 'bigblocks';

export default function ThreadView({ thread }) {
  const { rootPost, replies, currentUser } = thread;

return (
    <div className="thread-view">
      {/* Main post */}
      <div className="main-post">
        <PostCard
          post={rootPost}
          meta={rootPost.meta}
          signer={currentUser}
          onReply={(post) => openReplyComposer(post)}
          onShare={(post) => sharePost(post)}
          onUserClick={(identity) => viewProfile(identity)}
          className="border-2 border-orange-200 bg-orange-50"
        />
      </div>
      
      {/* Thread replies */}
      <div className="thread-replies">
        {replies.map((reply, index) => (
          <div 
            key={reply.txid}
            className="ml-8 border-l-2 border-gray-200 pl-4 mt-4"
            style={{ marginLeft: `${reply.depth * 32}px` }}
          >
            <PostCard
              post={reply}
              meta={reply.meta}
              signer={currentUser}
              compact={reply.depth > 2}
              onReply={(post) => openReplyComposer(post)}
              onUserClick={(identity) => viewProfile(identity)}
            />
          </div>
        ))}
      </div>
    </div>
  );
}
```

### User Profile Posts

```tsx
import { PostCard } from 'bigblocks';

export default function UserProfilePosts({ userPosts, profileOwner, currentUser }) {
  return (
    <div className="user-posts">
      <h3>Posts by {profileOwner.name}</h3>
      
      <div className="posts-list">
        {userPosts.map(post => (
          <PostCard
            key={post.txid}
            post={post}
            meta={post.meta}
            signer={currentUser}
            showAuthor={false} // Hide author since it's the profile owner
            onReply={(post) => {
              // Handle reply to user's post
              openReplyDialog(post, profileOwner);
            }}
            onShare={(post) => {
              // Handle sharing user's post
              shareUserPost(post, profileOwner);
            }}
            className="mb-6 border-b pb-6"
          />
        ))}
      </div>
    </div>
  );
}
```

### Compact Post Cards

```tsx
import { PostCard } from 'bigblocks';

export default function CompactPostList({ posts }) {
  return (
    <div className="compact-posts">
      <h3>Recent Activity</h3>
      
      <div className="space-y-2">
        {posts.map(post => (
          <PostCard
            key={post.txid}
            post={post}
            compact={true}
            showActions={false}
            onUserClick={(identity) => {
              // Navigate to user profile
              router.push(`/users/${identity.idKey}`);
            }}
            className="p-3 hover:bg-gray-50 rounded"
          />
        ))}
      </div>
    </div>
  );
}
```

### Post with Rich Media

```tsx
import { PostCard } from 'bigblocks';

export default function MediaPostDisplay({ mediaPost }) {
  const handleMediaClick = (media) => {
    // Open media in fullscreen viewer
    openMediaViewer(media);
  };

return (
    <div className="media-post">
      <PostCard
        post={mediaPost}
        meta={{
          ...mediaPost.meta,
          media: mediaPost.meta.media?.map(item => ({
            ...item,
            onClick: () => handleMediaClick(item)
          }))
        }}
        onReply={(post) => {
          // Reply to media post
          openReplyWithMedia(post);
        }}
        onShare={(post) => {
          // Share media post
          shareMediaPost(post);
        }}
        className="media-post-card"
      />
    </div>
  );
}
```

### Post Analytics Integration

```tsx
import { PostCard } from 'bigblocks';
import { useState, useEffect } from 'react';

export default function PostWithAnalytics({ post, showAnalytics = false }) {
  const [analytics, setAnalytics] = useState(null);
  const [loading, setLoading] = useState(false);

useEffect(() => {
    loadAnalytics();
  }, [post.txid, showAnalytics]);

return (
    <div className="post-with-analytics">
      <PostCard
        post={post}
        onReply={(post) => replyToPost(post)}
        onShare={(post) => sharePost(post)}
        className="border rounded-lg"
      />
      
      {showAnalytics && (
        <div className="analytics-section mt-4 p-4 bg-gray-50 rounded">
          {loading ? (
            <div>Loading analytics...</div>
          ) : analytics ? (
            <div className="analytics-grid">
              <div className="stat">
                <span className="label">Views</span>
                <span className="value">{analytics.views}</span>
              </div>
              <div className="stat">
                <span className="label">Engagement</span>
                <span className="value">{analytics.engagementRate}%</span>
              </div>
              <div className="stat">
                <span className="label">Reach</span>
                <span className="value">{analytics.reach}</span>
              </div>
            </div>
          ) : (
            <div>Analytics not available</div>
          )}
        </div>
      )}
    </div>
  );
}
```

### Interactive Post Actions

```tsx
import { PostCard, LikeButton, FollowButton } from 'bigblocks';
import { useState } from 'react';

export default function InteractivePost({ post, currentUser }) {
  const [isLiked, setIsLiked] = useState(false);
  const [likeCount, setLikeCount] = useState(post.meta?.likes || 0);
  const [isFollowing, setIsFollowing] = useState(false);

return (
    <div className="interactive-post">
      <PostCard
        post={post}
        signer={currentUser}
        onReply={(post) => {
          // Open reply composer
          openReplyComposer(post);
        }}
        onShare={(post) => {
          // Share post
          sharePost(post);
        }}
        onUserClick={(identity) => {
          // View user profile
          router.push(`/profile/${identity.idKey}`);
        }}
      />
      
      {/* Custom action bar */}
      <div className="custom-actions flex justify-between items-center mt-4 p-3 border-t">
        <div className="left-actions flex space-x-4">
          <LikeButton
            txid={post.txid}
            isLiked={isLiked}
            count={likeCount}
            onLike={handleLike}
          />
          
          <button
            onClick={() => openReplyComposer(post)}
            className="text-gray-500 hover:text-blue-500"
          >
            💬 Reply
          </button>
          
          <button
            onClick={() => sharePost(post)}
            className="text-gray-500 hover:text-green-500"
          >
            🔄 Share
          </button>
        </div>
        
        <div className="right-actions">
          {post.bapId !== currentUser?.idKey && (
            <FollowButton
              idKey={post.bapId}
              isFollowing={isFollowing}
              onFollow={handleFollow}
              onUnfollow={handleFollow}
              size="small"
            />
          )}
        </div>
      </div>
    </div>
  );
}
```

## Post Transaction Structure

```typescript
interface PostTransaction {
  txid: string;                    // Transaction ID on blockchain
  timestamp: number;               // Post timestamp
  bapId: string;                   // Author's BAP identity
  content: string;                 // Post content
  app: string;                     // App identifier (e.g., 'bSocial')
  type: 'post';                    // Transaction type
  context?: string;                // Reply context
  // Additional fields from bmap-api-types
}

interface PostMeta {
  likes?: number;                  // Like count
  replies?: number;                // Reply count
  reposts?: number;                // Repost count
  media?: MediaItem[];             // Attached media
  mentions?: Mention[];            // User mentions
  hashtags?: Hashtag[];           // Hashtags
  links?: LinkPreview[];          // Link previews
}

interface BapIdentity {
  idKey: string;                   // BAP identity key
  name?: string;                   // Display name
  avatar?: string;                 // Avatar URL
  // Additional identity fields
}
```

## Features

### Content Display

* **Rich Text**: Markdown support with proper formatting
* **Media Support**: Images, videos, and embedded content
* **Link Previews**: Automatic link metadata display
* **Mentions**: Clickable user mentions
* **Hashtags**: Clickable hashtag links

### Author Information

* **Avatar Display**: User profile pictures with fallbacks
* **Verification Badges**: Verified user indicators
* **User Names**: Display names and handles
* **Profile Links**: Clickable author information

### Interaction Features

* **Like/Unlike**: Heart button with counts
* **Reply**: Comment on posts
* **Share/Repost**: Share posts with others
* **Follow**: Follow post authors
* **User Profiles**: Navigate to author profiles

### Layout Options

* **Standard**: Full-featured post display
* **Compact**: Condensed layout for lists
* **Thread**: Nested conversation view
* **Media-focused**: Emphasis on visual content

## Common Patterns

### Post Feed Component

```tsx
import { PostCard } from 'bigblocks';

export default function PostFeed({ posts, currentUser }) {
  const [interactions, setInteractions] = useState({});

const updateInteraction = (postId, type, value) => {
    setInteractions(prev => ({
      ...prev,
      [postId]: {
        ...prev[postId],
        [type]: value
      }
    }));
  };

return (
    <div className="post-feed space-y-6">
      {posts.map(post => (
        <PostCard
          key={post.txid}
          post={post}
          meta={{
            ...post.meta,
            ...interactions[post.txid]
          }}
          signer={currentUser}
          onReply={(post) => {
            openReplyDialog(post);
          }}
          onShare={(post) => {
            sharePostDialog(post);
          }}
          onUserClick={(identity) => {
            router.push(`/profile/${identity.idKey}`);
          }}
          className="bg-white border rounded-lg shadow-sm hover:shadow-md transition-shadow"
        />
      ))}
    </div>
  );
}
```

### Search Results Display

```tsx
import { PostCard } from 'bigblocks';

export default function SearchResults({ searchResults, query }) {
  return (
    <div className="search-results">
      <h2>Posts matching "{query}"</h2>
      
      <div className="results-list">
        {searchResults.posts.map(post => (
          <PostCard
            key={post.txid}
            post={post}
            meta={post.meta}
            showTimestamp={true}
            onUserClick={(identity) => {
              // Track search result click
              analytics.track('search_result_click', {
                query,
                postId: post.txid,
                authorId: identity.idKey
              });
              
              router.push(`/profile/${identity.idKey}`);
            }}
            className="mb-4 p-4 border rounded hover:bg-gray-50"
          />
        ))}
      </div>
    </div>
  );
}
```

### Trending Posts Widget

```tsx
import { PostCard } from 'bigblocks';

export default function TrendingPosts({ trendingPosts }) {
  return (
    <div className="trending-posts">
      <h3 className="font-bold mb-4">🔥 Trending Now</h3>
      
      <div className="space-y-3">
        {trendingPosts.slice(0, 5).map((post, index) => (
          <div key={post.txid} className="trending-item">
            <div className="flex items-center space-x-2 mb-2">
              <span className="trending-rank">#{index + 1}</span>
              <span className="trending-score">
                {post.meta.trendingScore} points
              </span>
            </div>
            
            <PostCard
              post={post}
              meta={post.meta}
              compact={true}
              showActions={false}
              onUserClick={(identity) => {
                router.push(`/profile/${identity.idKey}`);
              }}
              className="bg-gradient-to-r from-orange-50 to-yellow-50 border border-orange-200 rounded"
            />
          </div>
        ))}
      </div>
    </div>
  );
}
```

## Styling and Customization

### Custom Styling

```tsx
import { PostCard } from 'bigblocks';

export default function StyledPostCard({ post }) {
  return (
    <PostCard
      post={post}
      className="
        bg-white 
        border-2 border-orange-200 
        rounded-xl 
        shadow-lg 
        hover:shadow-xl 
        transition-all 
        duration-300 
        hover:scale-105
      "
      onReply={(post) => handleReply(post)}
      onShare={(post) => handleShare(post)}
    />
  );
}
```

### Dark Mode Support

```tsx
import { PostCard } from 'bigblocks';

export default function ThemedPostCard({ post, darkMode }) {
  return (
    <PostCard
      post={post}
      className={`
        border rounded-lg transition-colors
        ${darkMode 
          ? 'bg-gray-800 border-gray-700 text-white' 
          : 'bg-white border-gray-200 text-gray-900'
        }
      `}
      onReply={(post) => handleReply(post)}
      onShare={(post) => handleShare(post)}
    />
  );
}
```

## Performance Optimization

### Virtualized Posts

```tsx
import { PostCard } from 'bigblocks';
import { FixedSizeList as List } from 'react-window';

export default function VirtualizedPostFeed({ posts }) {
  const PostItem = ({ index, style }) => {
    const post = posts[index];
    
    return (
      <div style={style}>
        <PostCard
          post={post}
          meta={post.meta}
          onReply={(post) => handleReply(post)}
          onShare={(post) => handleShare(post)}
          className="mx-4 mb-4"
        />
      </div>
    );
  };

return (
    <List
      height={600}
      itemCount={posts.length}
      itemSize={200}
      itemData={posts}
    >
      {PostItem}
    </List>
  );
}
```

### Lazy Loading

```tsx
import { PostCard } from 'bigblocks';
import { useInView } from 'react-intersection-observer';

export default function LazyPostCard({ post, onVisible }) {
  const { ref, inView } = useInView({
    threshold: 0.1,
    triggerOnce: true,
    onChange: (inView) => {
      if (inView) {
        onVisible?.(post);
      }
    }
  });

return (
    <div ref={ref}>
      {inView ? (
        <PostCard
          post={post}
          onReply={(post) => handleReply(post)}
          onShare={(post) => handleShare(post)}
        />
      ) : (
        <div className="post-skeleton">
          <div className="animate-pulse bg-gray-200 h-32 rounded" />
        </div>
      )}
    </div>
  );
}
```

## Accessibility

* **Semantic HTML**: Proper article and header structure
* **ARIA Labels**: Screen reader support for actions
* **Keyboard Navigation**: Full keyboard accessibility
* **Focus Management**: Proper focus indicators
* **High Contrast**: Support for high contrast modes
* **Screen Readers**: Descriptive content for assistive technology

## Best Practices

1. **Handle Loading States**: Show skeleton loaders during data fetching
2. **Error Boundaries**: Gracefully handle post loading errors
3. **Performance**: Use virtualization for large post lists
4. **User Feedback**: Provide immediate feedback for interactions
5. **Analytics**: Track user engagement with posts
6. **Content Safety**: Implement content filtering and reporting
7. **Real-time Updates**: Update post stats in real-time when possible

## Troubleshooting

### Posts Not Displaying

* Check that post data structure matches `PostTransaction` interface
* Verify blockchain connection for on-chain posts
* Ensure proper authentication for restricted content

### Interaction Buttons Not Working

* Verify `signer` prop is provided for authenticated actions
* Check that callback functions are properly implemented
* Ensure wallet connectivity for blockchain transactions

### Media Not Loading

* Check media URL accessibility
* Verify CORS settings for external media
* Implement fallback for failed media loads

## Related Components

* [SocialFeed](/docs/components/social-feed) - Display multiple posts
* [PostButton](/docs/components/post-button) - Create new posts
* [LikeButton](/docs/components/like-button) - Like/unlike posts
* [FollowButton](/docs/components/follow-button) - Follow post authors

## API Integration

The component integrates with bSocial protocol APIs:

```typescript
// Get post details
GET /api/social/posts/{txid}

// Get post metadata
GET /api/social/posts/{txid}/meta

// Post interactions
POST /api/social/posts/{txid}/like
POST /api/social/posts/{txid}/reply
POST /api/social/posts/{txid}/share
```

## Notes for Improvement

**Enhanced Implementation**: The actual component provides more sophisticated features than the basic prompt described:

* Full integration with bmap-api-types for proper blockchain data structure
* Support for rich media display with lazy loading
* Real-time interaction capabilities with like/reply/share
* Advanced thread display with proper nesting
* Better performance optimizations for large feeds
* Comprehensive accessibility support
* Integration with BAP identity system for author verification

# SocialFeed
URL: /docs/components/social/social-feed

Display a chronological feed of on-chain social posts with infinite scroll, real-time updates, and filtering

***

title: SocialFeed
description: Display a chronological feed of on-chain social posts with infinite scroll, real-time updates, and filtering
categories: \['social', 'feeds', 'content']
providers: \['BitcoinAuthProvider']
-----------------------------------

import { SocialFeedDemo } from '@/components/docs/demos/SocialFeedDemo'
import { ComponentBadges } from '@/components/docs/ComponentBadges'

SocialFeed combines the [Radix ScrollArea primitive](https://www.radix-ui.com/themes/docs/components/scroll-area) with Bitcoin social protocol data, providing an infinite-scrolling feed of on-chain posts with real-time updates, filtering, and interactive engagement features.

## Installation

```bash
npx bigblocks add social-feed
```

## Import

```typescript
import { SocialFeed } from 'bigblocks';
```

This component extends the [ScrollArea primitive](https://www.radix-ui.com/themes/docs/components/scroll-area) and inherits all its props.

## Props

| Prop           | Type                                                                  | Required | Default      | Description                      |
| -------------- | --------------------------------------------------------------------- | -------- | ------------ | -------------------------------- |
| data           | `PostsResponse`                                                       | No       | -            | Pre-loaded posts data            |
| loading        | `boolean`                                                             | No       | `false`      | Loading state indicator          |
| hasMore        | `boolean`                                                             | No       | `false`      | Whether more posts are available |
| showCreatePost | `boolean`                                                             | No       | `true`       | Show post creation button        |
| showFilters    | `boolean`                                                             | No       | `false`      | Show feed filter controls        |
| feedType       | `'timeline' \| 'following' \| 'trending' \| 'user' \| 'contextual'`   | No       | `'timeline'` | Type of feed to display          |
| userId         | `string`                                                              | No       | -            | User ID for user-specific feeds  |
| context        | `{ type: 'tx' \| 'url' \| 'channel', value: string, label?: string }` | No       | -            | Context for contextual feeds     |
| onLoadMore     | `() => void`                                                          | No       | -            | Callback for loading more posts  |
| onUserClick    | `(identity: BapIdentity) => void`                                     | No       | -            | User profile click handler       |
| onRefresh      | `() => void`                                                          | No       | -            | Pull-to-refresh callback         |
| onPost         | `(content: string) => void`                                           | No       | -            | Callback for contextual posting  |
| className      | `string`                                                              | No       | -            | Additional CSS classes           |
| maxHeight      | `string \| number`                                                    | No       | `'70vh'`     | Maximum height with scroll       |

## Basic Usage

```tsx
import { SocialFeed } from 'bigblocks';

export default function SocialApp() {
  const handleLoadMore = () => {
    // Load more posts
    console.log('Loading more posts...');
  };

return (
    <SocialFeed
      feedType="timeline"
      onLoadMore={handleLoadMore}
      showCreatePost={true}
    />
  );
}
```

## Feed Types

### Timeline Feed

Global public feed of all posts:

```tsx
import { SocialFeed } from 'bigblocks';

export default function GlobalTimeline() {
  return (
    <SocialFeed
      feedType="timeline"
      showCreatePost={true}
      showFilters={true}
      onLoadMore={() => {
        // Load more global posts
      }}
    />
  );
}
```

### Following Feed

Posts from users you follow:

```tsx
import { SocialFeed } from 'bigblocks';

export default function FollowingFeed() {
  return (
    <SocialFeed
      feedType="following"
      showCreatePost={true}
      onLoadMore={() => {
        // Load more following posts
      }}
      onRefresh={() => {
        // Refresh following feed
      }}
    />
  );
}
```

### Trending Feed

Trending posts based on engagement:

```tsx
import { SocialFeed } from 'bigblocks';

export default function TrendingFeed() {
  return (
    <SocialFeed
      feedType="trending"
      showFilters={true}
      onLoadMore={() => {
        // Load more trending posts
      }}
    />
  );
}
```

### User Profile Feed

Posts from a specific user:

```tsx
import { SocialFeed } from 'bigblocks';

export default function UserProfile({ userId }) {
  return (
    <SocialFeed
      feedType="user"
      userId={userId}
      onLoadMore={() => {
        // Load more user posts
      }}
      onUserClick={(identity) => {
        // Navigate to user profile
        router.push(`/profile/${identity.idKey}`);
      }}
    />
  );
}
```

## Advanced Usage

### With Pre-loaded Data

```tsx
import { SocialFeed } from 'bigblocks';
import { useEffect, useState } from 'react';

export default function PreloadedFeed() {
  const [postsData, setPostsData] = useState(null);
  const [loading, setLoading] = useState(true);

useEffect(() => {
    const loadInitialPosts = async () => {
      try {
        const response = await fetch('/api/social/posts');
        const data = await response.json();
        setPostsData(data);
      } catch (error) {
        console.error('Failed to load posts:', error);
      } finally {
        setLoading(false);
      }
    };

loadInitialPosts();
  }, []);

return (
    <SocialFeed
      data={postsData}
      loading={loading}
      hasMore={postsData?.pagination?.hasMore}
      showCreatePost={true}
      onLoadMore={() => {
        // Load next page
        loadMorePosts(postsData.pagination.nextOffset);
      }}
    />
  );
}
```

### With Real-time Updates

```tsx
import { SocialFeed } from 'bigblocks';
import { useEffect, useState } from 'react';

export default function LiveFeed() {
  const [postsData, setPostsData] = useState(null);
  
  useEffect(() => {
    // Subscribe to real-time updates
    const eventSource = new EventSource('/api/social/feed/stream');
    
    eventSource.onmessage = (event) => {
      const update = JSON.parse(event.data);
      
      if (update.type === 'new_post') {
        setPostsData(prev => ({
          ...prev,
          posts: [update.post, ...prev.posts]
        }));
      }
      
      if (update.type === 'post_updated') {
        setPostsData(prev => ({
          ...prev,
          posts: prev.posts.map(post => 
            post.id === update.postId 
              ? { ...post, ...update.updates }
              : post
          )
        }));
      }
    };

return () => eventSource.close();
  }, []);

return (
    <SocialFeed
      data={postsData}
      feedType="timeline"
      showCreatePost={true}
      onRefresh={async () => {
        // Refresh feed data
        const fresh = await fetchLatestPosts();
        setPostsData(fresh);
      }}
    />
  );
}
```

### With Infinite Scroll

```tsx
import { SocialFeed } from 'bigblocks';
import { useState, useCallback } from 'react';

export default function InfiniteScrollFeed() {
  const [posts, setPosts] = useState([]);
  const [loading, setLoading] = useState(false);
  const [hasMore, setHasMore] = useState(true);
  const [offset, setOffset] = useState(0);

return (
    <SocialFeed
      data={{ posts, pagination: { hasMore } }}
      loading={loading}
      hasMore={hasMore}
      onLoadMore={loadMorePosts}
      showCreatePost={true}
    />
  );
}
```

### With Filtering

```tsx
import { SocialFeed } from 'bigblocks';
import { useState } from 'react';

export default function FilteredFeed() {
  const [activeFilters, setActiveFilters] = useState([]);
  const [postsData, setPostsData] = useState(null);

return (
    <div>
      <SocialFeed
        data={postsData}
        showFilters={true}
        feedType="timeline"
        onLoadMore={() => {
          // Load more filtered posts
        }}
      />
    </div>
  );
}
```

### Constrained Height with Scroll

```tsx
import { SocialFeed } from 'bigblocks';

export default function ScrollableFeed() {
  return (
    <div className="h-screen flex flex-col">
      <header className="flex-shrink-0">
        <h1>Social Feed</h1>
      </header>
      
      <div className="flex-1 overflow-hidden">
        <SocialFeed
          feedType="timeline"
          maxHeight="100%"
          showCreatePost={true}
          onLoadMore={() => {
            // Load more posts
          }}
        />
      </div>
    </div>
  );
}
```

## Common Patterns

### Tab-based Feeds

```tsx
import { SocialFeed } from 'bigblocks';
import { useState } from 'react';

export default function TabbedFeeds() {
  const [activeTab, setActiveTab] = useState('timeline');

const tabs = [
    { id: 'timeline', label: 'Timeline', feedType: 'timeline' },
    { id: 'following', label: 'Following', feedType: 'following' },
    { id: 'trending', label: 'Trending', feedType: 'trending' }
  ];

return (
    <div>
      <div className="flex border-b mb-4">
        {tabs.map(tab => (
          <button
            key={tab.id}
            onClick={() => setActiveTab(tab.id)}
            className={`px-4 py-2 ${
              activeTab === tab.id 
                ? 'border-b-2 border-blue-500 text-blue-600' 
                : 'text-gray-500'
            }`}
          >
            {tab.label}
          </button>
        ))}
      </div>

{tabs.map(tab => (
        <div key={tab.id} style={{ display: activeTab === tab.id ? 'block' : 'none' }}>
          <SocialFeed
            feedType={tab.feedType}
            showCreatePost={tab.id === 'timeline'}
            showFilters={tab.id === 'trending'}
            onLoadMore={() => {
              console.log(`Loading more ${tab.feedType} posts`);
            }}
          />
        </div>
      ))}
    </div>
  );
}
```

### Profile Integration

```tsx
import { SocialFeed, ProfileCard } from 'bigblocks';

export default function ProfileWithFeed({ userId }) {
  return (
    <div className="max-w-4xl mx-auto">
      <div className="grid grid-cols-1 lg:grid-cols-3 gap-6">
        <div className="lg:col-span-1">
          <ProfileCard userId={userId} />
        </div>
        
        <div className="lg:col-span-2">
          <SocialFeed
            feedType="user"
            userId={userId}
            onUserClick={(identity) => {
              // Navigate to clicked user profile
              router.push(`/profile/${identity.idKey}`);
            }}
            onLoadMore={() => {
              // Load more user posts
            }}
          />
        </div>
      </div>
    </div>
  );
}
```

### Search Integration

```tsx
import { SocialFeed } from 'bigblocks';
import { useState, useEffect } from 'react';

export default function SearchFeed() {
  const [searchQuery, setSearchQuery] = useState('');
  const [searchResults, setSearchResults] = useState(null);
  const [loading, setLoading] = useState(false);

useEffect(() => {
    const searchPosts = async () => {
      if (!searchQuery.trim()) {
        setSearchResults(null);
        return;
      }

setLoading(true);
      try {
        const response = await fetch(`/api/social/search?q=${encodeURIComponent(searchQuery)}`);
        const data = await response.json();
        setSearchResults(data);
      } catch (error) {
        console.error('Search failed:', error);
      } finally {
        setLoading(false);
      }
    };

const debounceTimer = setTimeout(searchPosts, 300);
    return () => clearTimeout(debounceTimer);
  }, [searchQuery]);

return (
    <div>
      <div className="mb-6">
        <input
          type="text"
          placeholder="Search posts..."
          value={searchQuery}
          onChange={(e) => setSearchQuery(e.target.value)}
          className="w-full px-4 py-2 border rounded-lg"
        />
      </div>

{searchQuery ? (
        <SocialFeed
          data={searchResults}
          loading={loading}
          onLoadMore={() => {
            // Load more search results
          }}
        />
      ) : (
        <SocialFeed
          feedType="timeline"
          showCreatePost={true}
          onLoadMore={() => {
            // Load more timeline posts
          }}
        />
      )}
    </div>
  );
}
```

### Error Handling

```tsx
import { SocialFeed } from 'bigblocks';
import { useState, useEffect } from 'react';

export default function RobustFeed() {
  const [postsData, setPostsData] = useState(null);
  const [error, setError] = useState(null);
  const [loading, setLoading] = useState(true);

useEffect(() => {
    const loadFeed = async () => {
      try {
        setError(null);
        const response = await fetch('/api/social/posts');
        
        if (!response.ok) {
          throw new Error(`HTTP ${response.status}: ${response.statusText}`);
        }
        
        const data = await response.json();
        setPostsData(data);
      } catch (err) {
        setError(err.message);
        console.error('Feed load error:', err);
      } finally {
        setLoading(false);
      }
    };

loadFeed();
  }, []);

if (error) {
    return (
      <div className="text-center py-8">
        <div className="text-red-500 mb-4">
          Failed to load feed: {error}
        </div>
        <button 
          onClick={() => window.location.reload()}
          className="px-4 py-2 bg-blue-500 text-white rounded"
        >
          Retry
        </button>
      </div>
    );
  }

return (
    <SocialFeed
      data={postsData}
      loading={loading}
      showCreatePost={true}
      onLoadMore={() => {
        // Load more with error handling
      }}
      onRefresh={async () => {
        try {
          const fresh = await fetch('/api/social/posts');
          const data = await fresh.json();
          setPostsData(data);
        } catch (err) {
          setError(err.message);
        }
      }}
    />
  );
}
```

## Types

```typescript
interface PostsResponse {
  posts: Post[];
  pagination: {
    total: number;
    hasMore: boolean;
    nextOffset: number;
    limit: number;
  };
  filters?: {
    activeFilters: string[];
    availableFilters: FilterOption[];
  };
}

interface Post {
  id: string;
  txid: string;
  content: string;
  author: BapIdentity;
  timestamp: number;
  stats: {
    likes: number;
    replies: number;
    reposts: number;
  };
  userInteraction?: {
    liked: boolean;
    reposted: boolean;
  };
}

interface BapIdentity {
  idKey: string;
  name?: string;
  address: string;
  avatar?: string;
}
```

## Features

* **Multiple Feed Types**: Timeline, following, trending, and user-specific feeds
* **Infinite Scroll**: Seamless loading of more content
* **Real-time Updates**: Live post updates via WebSocket/SSE
* **Post Creation**: Integrated posting functionality
* **Content Filtering**: Advanced filtering and search capabilities
* **User Interaction**: Click handlers for user profiles
* **Pull-to-Refresh**: Mobile-friendly refresh gesture
* **Optimized Rendering**: Efficient virtualization for large feeds
* **Responsive Design**: Mobile and desktop optimized

## Feed Types Explained

### Timeline

* **Global feed** of all public posts
* **Best for**: Discovery and general browsing
* **Sorting**: Chronological or algorithmic

### Following

* **Personalized feed** from users you follow
* **Best for**: Staying updated with specific users
* **Requires**: Authentication and following relationships

### Trending

* **Popular posts** based on engagement metrics
* **Best for**: Finding viral or important content
* **Metrics**: Likes, replies, reposts, and views

### User

* **Single user's posts** and activity
* **Best for**: Profile pages and user exploration
* **Includes**: Original posts and reposts

## Performance Optimizations

* **Virtual scrolling** for large feeds
* **Image lazy loading** for media content
* **Debounced scroll handlers** for smooth performance
* **Memoized components** to prevent unnecessary re-renders
* **Intelligent caching** of feed data
* **Progressive loading** of post metadata

## Requirements

* **Authentication**: Required for following and user feeds
* **Provider Context**: Must be wrapped in BitcoinQueryProvider
* **Network**: Active internet connection for real-time features
* **Bitcoin Integration**: For posting and interactions

## Best Practices

1. **Implement Error Boundaries**: Handle component crashes gracefully
2. **Optimize Images**: Use compressed images and lazy loading
3. **Cache Strategically**: Cache feed data but keep it fresh
4. **Handle Offline**: Provide offline indicators and cached content
5. **Accessibility**: Support keyboard navigation and screen readers

## Troubleshooting

### Feed Not Loading

* Check authentication status for protected feeds
* Verify API endpoints are accessible
* Ensure proper error handling is implemented

### Infinite Scroll Issues

* Verify `onLoadMore` callback is provided
* Check `hasMore` property is correctly set
* Ensure loading state prevents duplicate requests

### Real-time Updates Not Working

* Check WebSocket/SSE connection
* Verify proper event handling
* Ensure feed type matches subscription

## Related Components

* [PostButton](/docs/components/post-button) - Create posts
* [PostCard](/docs/components/post-card) - Individual post display
* [LikeButton](/docs/components/like-button) - Post interactions
* [FollowButton](/docs/components/follow-button) - Follow users

## API Integration

The component integrates with bSocial protocol APIs:

```typescript
// Get feed posts
GET /api/social/posts?type={feedType}&limit=20&offset=0

// Search posts
GET /api/social/search?q={query}&type=posts

// Real-time updates
GET /api/social/feed/stream
WS /api/social/feed/ws
```

## Notes for Improvement

**Enhanced Implementation**: The actual component is more sophisticated than the basic prompt described:

* Uses bmap-api-types for proper Bitcoin transaction data structure
* Multiple specialized feed types with different behaviors
* Real-time capabilities with WebSocket support
* Advanced filtering and search integration
* Better performance optimizations and caching
* More granular user interaction callbacks

# BitcoinAvatar
URL: /docs/components/ui/bitcoin-avatar

Avatar component that combines Radix Avatar with Bitcoin URL resolution, automatic fallbacks, and Bitcoin-themed styling

***

title: BitcoinAvatar
description: Avatar component that combines Radix Avatar with Bitcoin URL resolution, automatic fallbacks, and Bitcoin-themed styling
category: ui-components
-----------------------

import { BitcoinAvatarDemo } from '@/components/docs/demos/BitcoinAvatarDemo'

Profile picture that supports Bitcoin URLs, with automatic resolution and fallback handling.

BitcoinAvatar combines [BitcoinImage](/docs/components/bitcoin-image) with the [Radix Avatar primitive](https://www.radix-ui.com/themes/docs/components/avatar) to provide a styled avatar component that can resolve Bitcoin protocol URLs (b://, ord://, etc.) while maintaining all the styling capabilities of Radix Themes.

## Installation

```bash
npx bigblocks add bitcoin-avatar
```

## Import

```tsx
import { BitcoinAvatar } from 'bigblocks';
```

## API Reference

This component extends the [Avatar primitive](https://www.radix-ui.com/themes/docs/components/avatar) and inherits all its props.

| Prop         | Type                                                                      | Default  | Description                                                              |
| ------------ | ------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------ |
| src          | `string`                                                                  | -        | Image source - can be blockchain URL (b://, ord://, etc.) or regular URL |
| alt\*        | `string`                                                                  | -        | Alt text for accessibility                                               |
| fallback\*   | `string`                                                                  | -        | Fallback text when image is not available                                |
| showLoading  | `boolean`                                                                 | `false`  | Show loading state for image resolution                                  |
| timeout      | `number`                                                                  | `5000`   | Timeout for Bitcoin URL resolution (ms)                                  |
| size         | `Responsive<"1" \| "2" \| "3" \| "4" \| "5" \| "6" \| "7" \| "8" \| "9">` | `"3"`    | Controls avatar size                                                     |
| variant      | `"solid" \| "soft"`                                                       | `"soft"` | Visual style variant                                                     |
| color        | Radix color                                                               | -        | Color theme                                                              |
| highContrast | `boolean`                                                                 | -        | Increases color contrast                                                 |
| radius       | `"none" \| "small" \| "medium" \| "large" \| "full"`                      | -        | Border radius                                                            |

\* Required props

## Basic Usage

```tsx
import { BitcoinAvatar } from 'bigblocks';

export default function UserProfile() {
  return (
    <BitcoinAvatar
      src="b://abc123def456..."
      alt="User's Bitcoin avatar"
      fallback="JD"
      size="4"
      variant="solid"
      color="orange"
      showLoading={true}
    />
  );
}
```

## Bitcoin URL Support

BitcoinAvatar automatically resolves Bitcoin protocol URLs using [BitcoinImage](/docs/components/bitcoin-image) under the hood:

```tsx
// On-chain image via b:// protocol
<BitcoinAvatar
  src="b://abc123def456..."
  alt="On-chain avatar"
  fallback="BC"
  showLoading={true}
/>

// Ordinal inscription
<BitcoinAvatar
  src="ord://inscription_id"
  alt="Ordinal avatar"
  fallback="OR"
  timeout={10000}
/>

// Regular URLs work too
<BitcoinAvatar
  src="https://example.com/avatar.jpg"
  alt="Regular avatar"
  fallback="US"
/>
```

For styling options (size, variant, color, radius, etc.), see the [Radix Avatar documentation](https://www.radix-ui.com/themes/docs/components/avatar).

## Related Components

* [BitcoinImage](/docs/components/bitcoin-image) - Image component with Bitcoin URL support
* [ProfilePopover](/docs/components/profile-popover) - Profile preview with avatar

# BitcoinImage
URL: /docs/components/ui/bitcoin-image

Image component that handles Bitcoin URLs with automatic resolution and fallbacks

***

title: BitcoinImage
description: Image component that handles Bitcoin URLs with automatic resolution and fallbacks
category: ui-components
-----------------------

import { BitcoinImageDemo } from '@/components/docs/demos/BitcoinImageDemo'

Image component that handles Bitcoin URLs (b://, ord://, etc.) with automatic resolution and graceful fallbacks.

## Installation

```bash
npx bigblocks add bitcoin-image
```

## Import

```tsx
import { BitcoinImage } from 'bigblocks';
```

## API Reference

| Prop        | Type                  | Default | Description                                                              |
| ----------- | --------------------- | ------- | ------------------------------------------------------------------------ |
| src         | `string`              | -       | Image source - can be blockchain URL (b://, ord://, etc.) or regular URL |
| alt\*       | `string`              | -       | Alt text for accessibility                                               |
| style       | `React.CSSProperties` | -       | Additional styles to apply to the image                                  |
| fallback    | `React.ReactNode`     | -       | Fallback content when image fails to load                                |
| showLoading | `boolean`             | `false` | Show loading state                                                       |
| timeout     | `number`              | `5000`  | Timeout for image loading (ms)                                           |

\* Required props

## Examples

### Basic Usage

Simple image display with Bitcoin URL support.

```tsx
<BitcoinImage
  src="https://api.dicebear.com/7.x/avataaars/svg?seed=bitcoin"
  alt="Bitcoin Avatar"
  style={{ width: '12em', height: '12em', borderRadius: '50%' }}
/>
```

### Bitcoin URLs

Automatically resolves Bitcoin protocol URLs.

```tsx
<Flex gap="4">
  <BitcoinImage
    src="b://abc123def456..."
    alt="On-chain Image"
    style={{ width: '12em', height: '12em', borderRadius: '50%' }}
    showLoading={true}
  />
  
  <BitcoinImage
    src="ord://inscription_id"
    alt="Ordinal Image"
    style={{ width: '12em', height: '12em', borderRadius: '50%' }}
    showLoading={true}
    timeout={10000}
  />
</Flex>
```

### Different Sizes

Use CSS styles to control sizing.

```tsx
<Flex gap="4" align="center">
  <BitcoinImage
    src="https://api.dicebear.com/7.x/avataaars/svg?seed=small"
    alt="Small Avatar"
    style={{ width: '3em', height: '3em', borderRadius: '50%' }}
  />
  
  <BitcoinImage
    src="https://api.dicebear.com/7.x/avataaars/svg?seed=medium"
    alt="Medium Avatar"
    style={{ width: '6em', height: '6em', borderRadius: '50%' }}
  />
  
  <BitcoinImage
    src="https://api.dicebear.com/7.x/avataaars/svg?seed=large"
    alt="Large Avatar"
    style={{ width: '12em', height: '12em', borderRadius: '50%' }}
  />
</Flex>
```

### With Fallback

Provide fallback content for failed loads.

```tsx
<Flex gap="4">
  <BitcoinImage
    src="https://api.dicebear.com/7.x/avataaars/svg?seed=valid"
    alt="Valid Image"
    style={{ width: '12em', height: '12em', borderRadius: '50%' }}
  />
  
  <BitcoinImage
    src="invalid-url"
    alt="Invalid Image"
    style={{ width: '12em', height: '12em', borderRadius: '50%' }}
    fallback={<div style={{ 
      width: '12em', 
      height: '12em', 
      borderRadius: '50%',
      backgroundColor: '#f3f4f6',
      display: 'flex',
      alignItems: 'center',
      justifyContent: 'center'
    }}>
      Failed
    </div>}
  />
</Flex>
```

### Loading State

Show loading indicator for slow Bitcoin URL resolution.

```tsx
<BitcoinImage
  src="b://slow-resolving-hash..."
  alt="Loading Image"
  style={{ width: '12em', height: '12em', borderRadius: '50%' }}
  showLoading={true}
  timeout={15000}
/>
```

### Rectangular Images

Not limited to circular avatars - works with any image format.

```tsx
<Flex gap="4" direction="column">
  <BitcoinImage
    src="https://images.unsplash.com/photo-1518546305927-5a555bb7020d?w=400&h=200&fit=crop"
    alt="Landscape Image"
    style={{ width: '20em', height: '10em', borderRadius: '8px' }}
  />
  
  <BitcoinImage
    src="https://images.unsplash.com/photo-1614680376739-414d95ff43df?w=300&h=400&fit=crop"
    alt="Portrait Image"
    style={{ width: '12em', height: '16em', borderRadius: '8px' }}
  />
</Flex>
```

## Related Components

* [BitcoinAvatar](/docs/components/bitcoin-avatar) - Avatar component with Bitcoin URL support
* [ProfilePopover](/docs/components/profile-popover) - Profile preview with image display

# LoadingButton
URL: /docs/components/ui/loading-button

A button component with built-in loading states and animations, perfect for forms and async operations

***

title: LoadingButton
description: A button component with built-in loading states and animations, perfect for forms and async operations
category: ui
------------

A versatile button component that handles loading states automatically, providing visual feedback during asynchronous operations like form submissions, API calls, and blockchain transactions.

[View Component Preview →](/component-preview/loading-button)

## Installation

```bash
npx bigblocks add loading-button
```

## Import

```typescript
import { LoadingButton } from 'bigblocks';
```

## Props

| Prop                | Type        | Required | Default | Description                                       |
| ------------------- | ----------- | -------- | ------- | ------------------------------------------------- |
| loading             | `boolean`   | No       | `false` | Shows loading spinner and optionally loading text |
| loadingText         | `string`    | No       | -       | Text to display when loading (replaces children)  |
| children            | `ReactNode` | Yes      | -       | Button content                                    |
| disabled            | `boolean`   | No       | `false` | Disables the button (auto-disabled when loading)  |
| ...RadixButtonProps | `various`   | No       | -       | All Radix Button props are supported              |

### Inherited Radix Button Props

The LoadingButton extends Radix UI's Button component, inheriting all its props:

| Prop         | Type                                                                  | Default   | Description             |
| ------------ | --------------------------------------------------------------------- | --------- | ----------------------- |
| variant      | `'classic' \| 'solid' \| 'soft' \| 'surface' \| 'outline' \| 'ghost'` | `'solid'` | Button visual style     |
| size         | `'1' \| '2' \| '3' \| '4'`                                            | `'2'`     | Button size             |
| color        | `string`                                                              | -         | Theme color             |
| highContrast | `boolean`                                                             | `false`   | High contrast mode      |
| radius       | `'none' \| 'small' \| 'medium' \| 'large' \| 'full'`                  | -         | Border radius           |
| asChild      | `boolean`                                                             | `false`   | Render as child element |

## Basic Usage

```tsx
import { LoadingButton } from 'bigblocks';
import { useState } from 'react';

export default function BasicExample() {
  const [loading, setLoading] = useState(false);

const handleClick = async () => {
    setLoading(true);
    try {
      await someAsyncOperation();
    } finally {
      setLoading(false);
    }
  };

return (
    <LoadingButton loading={loading} onClick={handleClick}>
      Submit
    </LoadingButton>
  );
}
```

## Advanced Usage

### Complete Form Integration

```tsx
import { LoadingButton } from 'bigblocks';
import { useState } from 'react';
import { useRouter } from 'next/navigation';

export default function LoginForm() {
  const [loading, setLoading] = useState(false);
  const [email, setEmail] = useState('');
  const [password, setPassword] = useState('');
  const router = useRouter();

return (
    <form onSubmit={handleSubmit} className="space-y-4">
      <input
        type="email"
        value={email}
        onChange={(e) => setEmail(e.target.value)}
        placeholder="Email"
        required
        className="w-full p-2 border rounded"
      />
      
      <input
        type="password"
        value={password}
        onChange={(e) => setPassword(e.target.value)}
        placeholder="Password"
        required
        className="w-full p-2 border rounded"
      />
      
      <LoadingButton
        type="submit"
        loading={loading}
        loadingText="Signing in..."
        variant="solid"
        size="3"
        className="w-full"
      >
        Sign In
      </LoadingButton>
    </form>
  );
}
```

### Bitcoin Transaction Example

```tsx
import { LoadingButton } from 'bigblocks';
import { useState } from 'react';
import { useBitcoinAuth } from 'bigblocks';

export default function SendBitcoinButton() {
  const [loading, setLoading] = useState(false);
  const { sendBSV } = useBitcoinAuth();

return (
    <LoadingButton
      loading={loading}
      loadingText="Broadcasting transaction..."
      onClick={handleSend}
      variant="solid"
      color="orange"
    >
      Send 0.001 BSV
    </LoadingButton>
  );
}
```

## Common Patterns

### With Icons

```tsx
import { LoadingButton } from 'bigblocks';
import { DownloadIcon, SaveIcon, TrashIcon } from 'lucide-react';

export default function IconButtons() {
  const [downloading, setDownloading] = useState(false);
  const [saving, setSaving] = useState(false);
  const [deleting, setDeleting] = useState(false);

return (
    <div className="flex gap-4">
      <LoadingButton
        loading={downloading}
        loadingText="Downloading..."
        onClick={handleDownload}
        variant="outline"
      >
        <DownloadIcon className="w-4 h-4 mr-2" />
        Download
      </LoadingButton>

<LoadingButton
        loading={saving}
        loadingText="Saving..."
        onClick={handleSave}
        variant="solid"
        color="green"
      >
        <SaveIcon className="w-4 h-4 mr-2" />
        Save Changes
      </LoadingButton>

<LoadingButton
        loading={deleting}
        loadingText="Deleting..."
        onClick={handleDelete}
        variant="soft"
        color="red"
      >
        <TrashIcon className="w-4 h-4 mr-2" />
        Delete
      </LoadingButton>
    </div>
  );
}
```

### Multiple Actions with Different States

```tsx
import { LoadingButton } from 'bigblocks';
import { useState } from 'react';

export default function MultiActionForm() {
  const [saveLoading, setSaveLoading] = useState(false);
  const [publishLoading, setPublishLoading] = useState(false);
  const [deleteLoading, setDeleteLoading] = useState(false);

const handleSave = async () => {
    setSaveLoading(true);
    await saveDocument();
    setSaveLoading(false);
  };

const handlePublish = async () => {
    setPublishLoading(true);
    await publishDocument();
    setPublishLoading(false);
  };

const handleDelete = async () => {
    if (!confirm('Are you sure?')) return;
    
    setDeleteLoading(true);
    await deleteDocument();
    setDeleteLoading(false);
  };

return (
    <div className="flex gap-2">
      <LoadingButton
        loading={saveLoading}
        loadingText="Saving..."
        onClick={handleSave}
        variant="outline"
      >
        Save Draft
      </LoadingButton>

<LoadingButton
        loading={publishLoading}
        loadingText="Publishing..."
        onClick={handlePublish}
        variant="solid"
        color="blue"
      >
        Publish
      </LoadingButton>

<LoadingButton
        loading={deleteLoading}
        loadingText="Deleting..."
        onClick={handleDelete}
        variant="ghost"
        color="red"
      >
        Delete
      </LoadingButton>
    </div>
  );
}
```

### Error Handling Pattern

```tsx
import { LoadingButton } from 'bigblocks';
import { useState } from 'react';

export default function ErrorHandlingExample() {
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState<string | null>(null);
  const [success, setSuccess] = useState(false);

return (
    <div className="space-y-2">
      <LoadingButton
        loading={loading}
        loadingText="Processing..."
        onClick={handleSubmit}
        variant={error ? 'soft' : 'solid'}
        color={error ? 'red' : success ? 'green' : undefined}
      >
        {error ? 'Retry' : success ? 'Success!' : 'Submit'}
      </LoadingButton>
      
      {error && (
        <p className="text-red-500 text-sm">{error}</p>
      )}
    </div>
  );
}
```

### Async Validation

```tsx
import { LoadingButton } from 'bigblocks';
import { useState } from 'react';

export default function AsyncValidationForm() {
  const [validating, setValidating] = useState(false);
  const [submitting, setSubmitting] = useState(false);
  const [isValid, setIsValid] = useState<boolean | null>(null);

return (
    <div className="space-y-4">
      <LoadingButton
        loading={validating}
        loadingText="Validating..."
        onClick={validateForm}
        variant="outline"
        disabled={submitting}
      >
        Validate
      </LoadingButton>

<LoadingButton
        loading={submitting}
        loadingText="Submitting..."
        onClick={handleSubmit}
        variant="solid"
        disabled={validating || isValid === false}
      >
        Submit
      </LoadingButton>
    </div>
  );
}
```

## Authentication Requirements

While LoadingButton doesn't require authentication itself, it's commonly used within authenticated contexts:

```tsx
import { 
  BitcoinAuthProvider, 
  BitcoinQueryProvider,
  LoadingButton,
  useBitcoinAuth
} from 'bigblocks';

function AuthenticatedAction() {
  const [loading, setLoading] = useState(false);
  const { isAuthenticated, signMessage } = useBitcoinAuth();

return (
    <LoadingButton
      loading={loading}
      loadingText="Authorizing..."
      onClick={handleAction}
      disabled={!isAuthenticated}
    >
      Perform Secure Action
    </LoadingButton>
  );
}

function App() {
  return (
    <BitcoinQueryProvider>
      <BitcoinAuthProvider config={{ apiUrl: '/api' }}>
        <AuthenticatedAction />
      </BitcoinAuthProvider>
    </BitcoinQueryProvider>
  );
}
```

## API Integration

LoadingButton is commonly used with API calls:

```typescript
// API endpoint example
app.post('/api/process', async (req, res) => {
  try {
    // Simulate processing
    await new Promise(resolve => setTimeout(resolve, 2000));
    
    res.json({ success: true, data: processedData });
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

// Frontend usage
const handleProcess = async () => {
  setLoading(true);
  try {
    const response = await fetch('/api/process', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(data)
    });
    
    if (!response.ok) throw new Error('Processing failed');
    
    const result = await response.json();
    console.log('Processed:', result);
  } finally {
    setLoading(false);
  }
};
```

## Styling

LoadingButton uses Radix Themes styling system:

```tsx
// Different variants
<LoadingButton variant="classic" loading={loading}>Classic</LoadingButton>
<LoadingButton variant="solid" loading={loading}>Solid</LoadingButton>
<LoadingButton variant="soft" loading={loading}>Soft</LoadingButton>
<LoadingButton variant="surface" loading={loading}>Surface</LoadingButton>
<LoadingButton variant="outline" loading={loading}>Outline</LoadingButton>
<LoadingButton variant="ghost" loading={loading}>Ghost</LoadingButton>

// Different sizes
<LoadingButton size="1" loading={loading}>Small</LoadingButton>
<LoadingButton size="2" loading={loading}>Medium</LoadingButton>
<LoadingButton size="3" loading={loading}>Large</LoadingButton>
<LoadingButton size="4" loading={loading}>Extra Large</LoadingButton>

// Colors
<LoadingButton color="orange" loading={loading}>Bitcoin Orange</LoadingButton>
<LoadingButton color="blue" loading={loading}>Blue</LoadingButton>
<LoadingButton color="green" loading={loading}>Success</LoadingButton>
<LoadingButton color="red" loading={loading}>Danger</LoadingButton>

// Custom styling
<LoadingButton
  loading={loading}
  className="custom-class"
  style={{ minWidth: '200px' }}
>
  Custom Styled
</LoadingButton>
```

## Error Handling

### Common Error Scenarios

```tsx
import { LoadingButton } from 'bigblocks';

export default function ErrorHandling() {
  const [loading, setLoading] = useState(false);

return (
    <LoadingButton
      loading={loading}
      loadingText="Processing..."
      onClick={handleAction}
    >
      Perform Action
    </LoadingButton>
  );
}
```

## Accessibility

LoadingButton includes built-in accessibility features:

* **ARIA attributes**: Automatically sets `aria-busy` when loading
* **Disabled state**: Prevents interaction during loading
* **Keyboard support**: Full keyboard navigation
* **Screen readers**: Loading state announced to assistive technology

```tsx
// The component automatically handles:
// - aria-busy="true" when loading
// - aria-disabled="true" when disabled or loading
// - role="button"
// - tabIndex for keyboard navigation
```

## Performance Optimization

### Debounced Actions

```tsx
import { LoadingButton } from 'bigblocks';
import { useCallback, useState } from 'react';
import { debounce } from 'lodash';

export default function DebouncedButton() {
  const [loading, setLoading] = useState(false);

const performAction = async () => {
    setLoading(true);
    try {
      await apiCall();
    } finally {
      setLoading(false);
    }
  };

const debouncedAction = useCallback(
    debounce(performAction, 500),
    []
  );

return (
    <LoadingButton
      loading={loading}
      onClick={debouncedAction}
    >
      Debounced Action
    </LoadingButton>
  );
}
```

## Best Practices

1. **Always handle errors**: Use try/catch/finally to ensure loading state is cleared
2. **Provide loading text**: Give users context about what's happening
3. **Disable during loading**: Prevent duplicate submissions (automatic)
4. **Show success feedback**: Update button text or show confirmation
5. **Consider timeout**: Add maximum loading time for better UX

```tsx
// Best practice example
const handleSubmit = async () => {
  setLoading(true);
  
  const timeout = setTimeout(() => {
    setLoading(false);
    alert('Operation timed out. Please try again.');
  }, 30000); // 30 second timeout
  
  try {
    const result = await performOperation();
    clearTimeout(timeout);
    setSuccess(true);
    
    // Reset success state after delay
    setTimeout(() => setSuccess(false), 3000);
  } catch (error) {
    clearTimeout(timeout);
    handleError(error);
  } finally {
    setLoading(false);
  }
};
```

## Troubleshooting

### Button not showing loading state

* Verify `loading` prop is being passed correctly
* Check that state is updating (use React DevTools)
* Ensure async operation isn't completing instantly

### Loading text not appearing

* LoadingText replaces children when loading is true
* Check that loadingText prop has a value
* Verify loading state is true

### Button remains disabled

* Loading automatically disables the button
* Check that loading state is reset in finally block
* Verify no other disabled condition

### Styling issues

* LoadingButton uses Radix Themes styling
* Ensure BitcoinThemeProvider is wrapping the component
* Check for CSS conflicts with custom classes

## Related Components

* [AuthButton](/docs/components/auth-button) - Authentication-specific button
* [SendBSVButton](/docs/components/send-bsv-button) - Bitcoin sending with loading states
* [QuickSendButton](/docs/components/quick-send-button) - Simplified BSV sending
* [Modal](/docs/components/modal) - Often used with loading buttons

## API Reference

### LoadingButton Props

```typescript
interface LoadingButtonProps extends RadixButtonProps {
  loading?: boolean;       // Shows spinner and disables button
  loadingText?: string;    // Text shown when loading
}

### Usage with React Hook Form

```typescript
import { useForm } from 'react-hook-form';
import { LoadingButton } from 'bigblocks';

function FormExample() {
  const { handleSubmit, formState: { isSubmitting } } = useForm();

const onSubmit = async (data) => {
    await processFormData(data);
  };

return (
    <form onSubmit={handleSubmit(onSubmit)}>
      {/* form fields */}
      
      <LoadingButton
        type="submit"
        loading={isSubmitting}
        loadingText="Submitting..."
      >
        Submit Form
      </LoadingButton>
    </form>
  );
}
```

# CompactWalletOverview
URL: /docs/components/wallet/compact-wallet-overview

Space-efficient wallet overview component that displays balance and status in a compact format, perfect for sidebars and widgets

***

title: CompactWalletOverview
description: Space-efficient wallet overview component that displays balance and status in a compact format, perfect for sidebars and widgets
category: wallet
----------------

A space-efficient wallet overview component that displays balance and status in a compact format, perfect for sidebars, widgets, and constrained layouts. Unlike the full WalletOverview, this component focuses purely on displaying balance information without action buttons.

[View Component Preview →](/component-preview/compact-wallet-overview)

## Installation

```bash
npx bigblocks add compact-wallet-overview
```

## Import

```typescript
import { CompactWalletOverview } from 'bigblocks';
```

## Props

| Prop         | Type             | Required | Default | Description                                                          |
| ------------ | ---------------- | -------- | ------- | -------------------------------------------------------------------- |
| balance      | `BSVBalance`     | No       | -       | Wallet balance object with confirmed, unconfirmed, and total amounts |
| showValues   | `boolean`        | No       | `true`  | Whether to show balance values or hide for privacy                   |
| currency     | `'BSV' \| 'USD'` | No       | `'BSV'` | Display currency format                                              |
| exchangeRate | `number`         | No       | -       | BSV to USD exchange rate for conversion                              |
| className    | `string`         | No       | -       | Additional CSS classes                                               |

### BSVBalance Interface

```typescript
interface BSVBalance {
  confirmed: number;      // Confirmed satoshis
  unconfirmed: number;    // Pending satoshis  
  total: number;          // Total satoshis
}
```

## Basic Usage

```tsx
import { CompactWalletOverview } from 'bigblocks';

export default function Sidebar() {
  return (
    <div className="sidebar">
      <h3>Wallet</h3>
      <CompactWalletOverview />
    </div>
  );
}
```

## Advanced Usage

### With Custom Balance

```tsx
import { CompactWalletOverview } from 'bigblocks';

export default function WalletWidget() {
  const balance = {
    confirmed: 150000000,    // 1.5 BSV confirmed
    unconfirmed: 5000000,    // 0.05 BSV pending
    total: 155000000         // 1.55 BSV total
  };

return (
    <CompactWalletOverview 
      balance={balance}
      showValues={true}
      currency="BSV"
    />
  );
}
```

### USD Display with Exchange Rate

```tsx
import { CompactWalletOverview } from 'bigblocks';
import { useState, useEffect } from 'react';

export default function USDWalletWidget() {
  const [exchangeRate, setExchangeRate] = useState<number>();
  
  useEffect(() => {
    // Fetch current BSV/USD rate
    fetch('/api/market/bsv-price')
      .then(res => res.json())
      .then(data => setExchangeRate(data.usd));
  }, []);

return (
    <CompactWalletOverview 
      currency="USD"
      exchangeRate={exchangeRate}
      showValues={true}
    />
  );
}
```

### Privacy Mode Toggle

```tsx
import { CompactWalletOverview } from 'bigblocks';
import { useState } from 'react';

export default function PrivacyWallet() {
  const [showValues, setShowValues] = useState(false);

return (
    <div className="wallet-container">
      <div className="flex justify-between items-center mb-2">
        <h4>Balance</h4>
        <button 
          onClick={() => setShowValues(!showValues)}
          className="text-xs opacity-60 hover:opacity-100"
        >
          {showValues ? '👁️' : '🔒'}
        </button>
      </div>
      
      <CompactWalletOverview 
        showValues={showValues}
        currency="BSV"
      />
    </div>
  );
}
```

## Common Patterns

### Dashboard Widget

```tsx
import { CompactWalletOverview } from 'bigblocks';

export default function DashboardWidget() {
  return (
    <div className="bg-white rounded-lg p-4 shadow">
      <div className="flex items-center justify-between mb-3">
        <h3 className="text-sm font-medium text-gray-900">My Wallet</h3>
        <span className="text-xs text-gray-500">BSV</span>
      </div>
      
      <CompactWalletOverview 
        currency="BSV"
        className="mb-3"
      />
      
      <div className="flex space-x-2">
        <button className="flex-1 text-xs bg-orange-100 text-orange-800 px-2 py-1 rounded">
          Send
        </button>
        <button className="flex-1 text-xs bg-green-100 text-green-800 px-2 py-1 rounded">
          Receive
        </button>
      </div>
    </div>
  );
}
```

### Mobile Navigation Bar

```tsx
import { CompactWalletOverview } from 'bigblocks';

export default function MobileNavBar() {
  return (
    <nav className="fixed bottom-0 left-0 right-0 bg-white border-t">
      <div className="flex items-center justify-between px-4 py-2">
        <div className="text-xs">
          <CompactWalletOverview 
            currency="USD"
            showValues={true}
            className="text-xs"
          />
        </div>
        
        <div className="flex space-x-4">
          <button>Home</button>
          <button>Send</button>
          <button>Receive</button>
          <button>Settings</button>
        </div>
      </div>
    </nav>
  );
}
```

### Header Balance Display

```tsx
import { CompactWalletOverview } from 'bigblocks';

export default function AppHeader() {
  return (
    <header className="bg-gray-900 text-white px-4 py-3">
      <div className="flex items-center justify-between">
        <h1 className="text-xl font-bold">Bitcoin App</h1>
        
        <div className="flex items-center space-x-4">
          <CompactWalletOverview 
            currency="BSV"
            showValues={true}
            className="text-white"
          />
          
          <button className="text-sm bg-orange-600 px-3 py-1 rounded">
            Account
          </button>
        </div>
      </div>
    </header>
  );
}
```

### Responsive Layout

```tsx
import { CompactWalletOverview } from 'bigblocks';

export default function ResponsiveWallet() {
  return (
    <div className="wallet-responsive">
      {/* Desktop: Show in sidebar */}
      <div className="hidden md:block md:w-64 bg-gray-50 p-4">
        <h3 className="font-semibold mb-3">Wallet Overview</h3>
        <CompactWalletOverview 
          currency="BSV"
          showValues={true}
        />
      </div>
      
      {/* Mobile: Show in header */}
      <div className="md:hidden bg-white p-3 border-b">
        <div className="flex justify-between items-center">
          <span className="text-sm font-medium">Balance</span>
          <CompactWalletOverview 
            currency="USD"
            showValues={true}
            className="text-sm"
          />
        </div>
      </div>
    </div>
  );
}
```

## Authentication Requirements

The CompactWalletOverview component requires Bitcoin authentication context to automatically fetch balance data:

```tsx
import { BitcoinAuthProvider, BitcoinQueryProvider, CompactWalletOverview } from 'bigblocks';

function App() {
  return (
    <BitcoinQueryProvider>
      <BitcoinAuthProvider config={{ apiUrl: '/api' }}>
        <CompactWalletOverview />
      </BitcoinAuthProvider>
    </BitcoinQueryProvider>
  );
}
```

## Data Integration

### Automatic Balance Fetching

When no `balance` prop is provided, the component automatically fetches balance from the authenticated user's wallet:

```tsx
// Automatically uses authenticated user's balance
<CompactWalletOverview />

// Override with custom balance
<CompactWalletOverview 
  balance={{
    confirmed: 100000000,
    unconfirmed: 0,
    total: 100000000
  }}
/>
```

### Real-time Updates

The component automatically updates when balance changes through Bitcoin transactions:

```tsx
import { CompactWalletOverview } from 'bigblocks';
import { useBitcoinAuth } from 'bigblocks';

export default function LiveWallet() {
  const { user } = useBitcoinAuth();
  
  return (
    <div>
      <h3>Live Balance for {user?.address}</h3>
      <CompactWalletOverview />
      {/* Balance updates automatically when transactions complete */}
    </div>
  );
}
```

## API Integration

The component integrates with the following API endpoints:

### Get Wallet Balance

```typescript
GET /api/wallet/balance

Response:
{
  success: boolean;
  balance: {
    confirmed: number;      // Confirmed satoshis
    unconfirmed: number;    // Pending satoshis
    total: number;          // Total satoshis
  };
  address: string;
  lastUpdated: number;
}
```

### Get Exchange Rate (for USD display)

```typescript
GET /api/market/bsv-price

Response:
{
  success: boolean;
  price: {
    usd: number;           // Current BSV/USD rate
    change24h: number;     // 24h change percentage
    lastUpdated: number;   // Price timestamp
  };
}
```

## Styling and Theming

### Custom Styling

```tsx
<CompactWalletOverview 
  className="custom-wallet-style"
  currency="BSV"
/>
```

```css
.custom-wallet-style {
  background: linear-gradient(135deg, #f7931a 0%, #ff6b35 100%);
  color: white;
  padding: 1rem;
  border-radius: 8px;
  font-weight: 600;
}

.custom-wallet-style .balance-amount {
  font-size: 1.25rem;
  font-weight: 700;
}

.custom-wallet-style .balance-label {
  opacity: 0.8;
  font-size: 0.875rem;
}
```

### Theme Integration

```tsx
import { CompactWalletOverview, BitcoinThemeProvider } from 'bigblocks';

function ThemedApp() {
  return (
    <BitcoinThemeProvider theme="orange">
      <CompactWalletOverview 
        currency="BSV"
        className="themed-wallet"
      />
    </BitcoinThemeProvider>
  );
}
```

## Accessibility

The component includes proper accessibility features:

* **Screen reader support**: Balance values are announced properly
* **Keyboard navigation**: Focusable when interactive
* **High contrast**: Respects system color preferences
* **Reduced motion**: Respects prefers-reduced-motion settings

```tsx
<CompactWalletOverview 
  currency="BSV"
  aria-label="Current wallet balance"
  role="region"
/>
```

## Performance Considerations

### Optimization Tips

1. **Memoization**: The component automatically memoizes balance calculations
2. **Update Frequency**: Balance updates are debounced to prevent excessive re-renders
3. **Currency Conversion**: Exchange rates are cached for performance

```tsx
import { memo } from 'react';
import { CompactWalletOverview } from 'bigblocks';

// Memoize for performance in lists or frequent updates
const MemoizedWallet = memo(CompactWalletOverview);

export default function WalletList({ wallets }) {
  return (
    <div>
      {wallets.map(wallet => (
        <MemoizedWallet 
          key={wallet.address}
          balance={wallet.balance}
          currency="BSV"
        />
      ))}
    </div>
  );
}
```

## Troubleshooting

### Common Issues

**Balance not displaying**

* Ensure BitcoinAuthProvider is configured with valid API URL
* Verify user is authenticated
* Check API endpoint is returning valid balance data

**USD conversion not working**

* Provide `exchangeRate` prop or ensure `/api/market/bsv-price` endpoint exists
* Check exchange rate API is accessible and returning valid data

**Component not updating**

* Verify BitcoinQueryProvider is wrapping the component
* Check that balance updates are being propagated through React Query
* Ensure API responses include proper cache headers

### Error Handling

```tsx
import { CompactWalletOverview } from 'bigblocks';
import { ErrorBoundary } from 'react-error-boundary';

function WalletErrorFallback({ error }) {
  return (
    <div className="wallet-error">
      <span>Balance unavailable</span>
      <button onClick={() => window.location.reload()}>
        Retry
      </button>
    </div>
  );
}

export default function SafeWallet() {
  return (
    <ErrorBoundary FallbackComponent={WalletErrorFallback}>
      <CompactWalletOverview currency="BSV" />
    </ErrorBoundary>
  );
}
```

## Related Components

* [WalletOverview](/docs/components/wallet-overview) - Full wallet view with actions and transaction history
* [TokenBalance](/docs/components/token-balance) - Display token balances
* [SendBSVButton](/docs/components/send-bsv-button) - Send BSV functionality
* [SimpleTokenBalance](/docs/components/simple-token-balance) - Simplified token display

## API Reference

### Component Props Type

```typescript
interface CompactWalletOverviewProps {
  balance?: BSVBalance;
  showValues?: boolean;
  currency?: 'BSV' | 'USD';
  exchangeRate?: number;
  className?: string;
}

interface BSVBalance {
  confirmed: number;      // Confirmed satoshis
  unconfirmed: number;    // Pending satoshis
  total: number;          // Total satoshis
}
```

### Usage with React Query

```typescript
import { useQuery } from '@tanstack/react-query';
import { CompactWalletOverview } from 'bigblocks';

function WalletWithQuery() {
  const { data: balance } = useQuery({
    queryKey: ['wallet-balance'],
    queryFn: () => fetch('/api/wallet/balance').then(res => res.json()),
    refetchInterval: 30000 // Refresh every 30 seconds
  });

return (
    <CompactWalletOverview 
      balance={balance}
      currency="BSV"
    />
  );
}
```

# DonateButton
URL: /docs/components/wallet/donate-button

Accept Bitcoin donations with customizable preset amounts, QR codes, and a beautiful donation interface

***

title: DonateButton
description: Accept Bitcoin donations with customizable preset amounts, QR codes, and a beautiful donation interface
category: wallet
----------------

Accept Bitcoin donations with customizable preset amounts and a beautiful UI. The DonateButton component provides a complete donation interface with preset amounts, custom amount input, QR code generation, and seamless Bitcoin transaction handling.

[View Component Preview →](/component-preview/donate-button)

## Installation

```bash
npx bigblocks add donate-button
```

## Import

```typescript
import { DonateButton } from 'bigblocks';
// or
import { DonateButton, QuickDonateButton } from 'bigblocks';
```

## Props

| Prop                | Type                                        | Required | Default                                             | Description                          |
| ------------------- | ------------------------------------------- | -------- | --------------------------------------------------- | ------------------------------------ |
| donationAddress     | `string`                                    | No       | `'1BitcoinAuthUi1111111111111111112345'`            | Bitcoin address to receive donations |
| defaultAmounts      | `number[]`                                  | No       | `[1000000, 5000000, 10000000, 50000000, 100000000]` | Preset donation amounts in satoshis  |
| customAmountEnabled | `boolean`                                   | No       | `true`                                              | Allow users to enter custom amounts  |
| variant             | `'solid' \| 'soft' \| 'outline' \| 'ghost'` | No       | `'solid'`                                           | Button visual style                  |
| size                | `'1' \| '2' \| '3' \| '4'`                  | No       | `'2'`                                               | Button size                          |
| buttonText          | `string`                                    | No       | `'Donate'`                                          | Text displayed on the button         |
| dialogTitle         | `string`                                    | No       | `'Make a Donation'`                                 | Title shown in the donation dialog   |
| description         | `string`                                    | No       | -                                                   | Optional description text            |
| onDonate            | `(amount: number, txid: string) => void`    | No       | -                                                   | Callback when donation succeeds      |
| onError             | `(error: Error) => void`                    | No       | -                                                   | Callback when donation fails         |
| showQR              | `boolean`                                   | No       | `true`                                              | Show QR code for mobile wallets      |
| showCopyAddress     | `boolean`                                   | No       | `true`                                              | Show copy address button             |
| disabled            | `boolean`                                   | No       | `false`                                             | Disable the donation button          |

## Basic Usage

```tsx
import { DonateButton } from 'bigblocks';

export default function SupportSection() {
  return (
    <DonateButton
      donationAddress="1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa"
      onDonate={(amount, txid) => {
        console.log(`Received ${amount} satoshis! TX: ${txid}`);
      }}
    />
  );
}
```

## Advanced Usage

### Custom Amounts and Configuration

```tsx
import { DonateButton } from 'bigblocks';

export default function CustomDonations() {
  return (
    <DonateButton
      donationAddress="1YourAddress..."
      defaultAmounts={[500000, 1000000, 5000000, 10000000]} // 0.005, 0.01, 0.05, 0.1 BSV
      customAmountEnabled={true}
      buttonText="Support This Project"
      dialogTitle="Support Development"
      description="Your donations help fund ongoing development and server costs."
      variant="solid"
      size="3"
      onDonate={(amount, txid) => {
        // Track donation analytics
        analytics.track('donation_completed', {
          amount_satoshis: amount,
          amount_bsv: amount / 100000000,
          txid
        });
        
        // Show success message
        toast.success(`Thank you for donating ${amount / 100000000} BSV!`);
      }}
      onError={(error) => {
        console.error('Donation failed:', error);
        toast.error('Donation failed. Please try again.');
      }}
    />
  );
}
```

### Support Page Example

```tsx
import { DonateButton } from 'bigblocks';

export default function SupportPage() {
  const projectAddress = "1YourProjectAddress...";
  
  return (
    <div className="max-w-2xl mx-auto p-8 space-y-6">
      <div className="text-center">
        <h1 className="text-3xl font-bold mb-4">Support Our Work</h1>
        <p className="text-lg text-gray-600 mb-6">
          Your donations help keep this project running and support ongoing development.
        </p>
      </div>
      
      <div className="bg-gray-50 rounded-lg p-6">
        <h2 className="text-xl font-semibold mb-4">Make a Donation</h2>
        <DonateButton
          donationAddress={projectAddress}
          defaultAmounts={[1000000, 5000000, 10000000, 50000000]} // 0.01, 0.05, 0.1, 0.5 BSV
          customAmountEnabled={true}
          buttonText="Donate Bitcoin"
          dialogTitle="Support Development"
          description="All donations go directly to development costs and server infrastructure."
          showQR={true}
          showCopyAddress={true}
          onDonate={(amount, txid) => {
            // Log donation
            console.log('Donation received:', {
              amount_satoshis: amount,
              amount_bsv: amount / 100000000,
              txid,
              timestamp: Date.now()
            });
            
            // Show gratitude
            toast.success('Thank you for your generous support!');
            
            // Optional: redirect to thank you page
            setTimeout(() => {
              router.push('/thank-you');
            }, 2000);
          }}
        />
      </div>
      
      <div className="text-sm text-gray-500 text-center">
        <p>All donations are processed on the Bitcoin SV blockchain.</p>
        <p>Transaction fees are minimal (~$0.001 USD).</p>
      </div>
    </div>
  );
}
```

## QuickDonateButton

For simpler use cases, use the QuickDonateButton component with a preset amount:

```tsx
import { QuickDonateButton } from 'bigblocks';

export default function ArticleDonation() {
  return (
    <div className="flex items-center space-x-4">
      <p>Enjoyed this article?</p>
      <QuickDonateButton
        donationAddress="1AuthorAddress..."
        amount={1000000} // 0.01 BSV
        buttonText="Tip 0.01 BSV"
        size="1"
        variant="outline"
        onDonate={(amount, txid) => {
          toast.success('Thanks for the tip!');
        }}
      />
    </div>
  );
}
```

## Common Patterns

### Donation Goals and Progress

```tsx
import { DonateButton } from 'bigblocks';
import { useState, useEffect } from 'react';

export default function DonationGoal() {
  const [raised, setRaised] = useState(0);
  const goal = 100000000; // 1 BSV goal
  const progress = (raised / goal) * 100;

return (
    <div className="space-y-4">
      <div>
        <div className="flex justify-between text-sm mb-2">
          <span>Progress</span>
          <span>{(raised / 100000000).toFixed(4)} BSV / {(goal / 100000000)} BSV</span>
        </div>
        <div className="w-full bg-gray-200 rounded-full h-2">
          <div 
            className="bg-orange-500 h-2 rounded-full transition-all duration-300"
            style={{ width: `${Math.min(progress, 100)}%` }}
          />
        </div>
        <p className="text-xs text-gray-500 mt-1">{progress.toFixed(1)}% funded</p>
      </div>
      
      <DonateButton
        donationAddress="1FundraisingAddress..."
        onDonate={(amount, txid) => {
          // Update progress
          setRaised(prev => prev + amount);
          
          // Check if goal reached
          if (raised + amount >= goal) {
            toast.success('🎉 Fundraising goal reached! Thank you!');
          } else {
            toast.success('Thank you for your donation!');
          }
        }}
      />
    </div>
  );
}
```

### Multiple Donation Categories

```tsx
import { DonateButton } from 'bigblocks';

export default function DonationCategories() {
  const categories = [
    {
      id: 'development',
      title: 'Development',
      description: 'Support ongoing development and new features',
      address: '1DevAddress...',
      color: 'blue'
    },
    {
      id: 'infrastructure',
      title: 'Infrastructure',
      description: 'Help cover server and hosting costs',
      address: '1InfraAddress...',
      color: 'green'
    },
    {
      id: 'community',
      title: 'Community',
      description: 'Support community events and outreach',
      address: '1CommunityAddress...',
      color: 'purple'
    }
  ];

return (
    <div className="grid md:grid-cols-3 gap-6">
      {categories.map(category => (
        <div key={category.id} className="border rounded-lg p-6">
          <h3 className="text-lg font-semibold mb-2">{category.title}</h3>
          <p className="text-gray-600 mb-4">{category.description}</p>
          
          <DonateButton
            donationAddress={category.address}
            buttonText={`Support ${category.title}`}
            dialogTitle={`Support ${category.title}`}
            description={category.description}
            size="2"
            onDonate={(amount, txid) => {
              analytics.track('category_donation', {
                category: category.id,
                amount,
                txid
              });
              toast.success(`Thank you for supporting ${category.title}!`);
            }}
          />
        </div>
      ))}
    </div>
  );
}
```

## Styling Variants

```tsx
import { DonateButton } from 'bigblocks';

export default function StylingExamples() {
  return (
    <div className="space-y-4">
      {/* Solid (default) */}
      <DonateButton variant="solid" size="2" buttonText="Solid Donate" />
      
      {/* Soft */}
      <DonateButton variant="soft" size="2" buttonText="Soft Donate" />
      
      {/* Outline */}
      <DonateButton variant="outline" size="2" buttonText="Outline Donate" />
      
      {/* Ghost */}
      <DonateButton variant="ghost" size="2" buttonText="Ghost Donate" />
      
      {/* Different sizes */}
      <div className="flex items-center space-x-2">
        <DonateButton size="1" buttonText="Small" />
        <DonateButton size="2" buttonText="Medium" />
        <DonateButton size="3" buttonText="Large" />
        <DonateButton size="4" buttonText="Extra Large" />
      </div>
    </div>
  );
}
```

## Authentication Requirements

The DonateButton component requires Bitcoin authentication to function. Wrap your app with the required providers:

```tsx
import { BitcoinAuthProvider, BitcoinQueryProvider } from 'bigblocks';

function App() {
  return (
    <BitcoinQueryProvider>
      <BitcoinAuthProvider config={{ apiUrl: '/api' }}>
        <YourAppWithDonateButtons />
      </BitcoinAuthProvider>
    </BitcoinQueryProvider>
  );
}
```

## Backend Integration

### API Requirements

The component uses the `useSendBSV` hook which requires these API endpoints:

```typescript
// POST /api/wallet/send
{
  "recipientAddress": "1RecipientAddress...",
  "amount": 1000000, // satoshis
  "message": "Donation" // optional
}

// Response:
{
  "success": true,
  "txid": "abc123...",
  "fee": 500 // transaction fee in satoshis
}
```

### Donation Tracking

```typescript
// Optional: Track donations in your database
CREATE TABLE donations (
  id UUID PRIMARY KEY,
  txid VARCHAR(64) UNIQUE NOT NULL,
  donor_address VARCHAR(64) NOT NULL,
  recipient_address VARCHAR(64) NOT NULL,
  amount BIGINT NOT NULL,
  message TEXT,
  category VARCHAR(50),
  timestamp TIMESTAMP DEFAULT NOW(),
  confirmed BOOLEAN DEFAULT FALSE
);
```

## Troubleshooting

### Common Issues

**"Insufficient funds" error**

* Ensure the user has enough BSV balance
* Check for minimum transaction amount requirements
* Verify fee calculation includes transaction costs

**QR code not displaying**

* Ensure `showQR` prop is set to `true`
* Check that the donation address is valid
* Verify mobile wallet compatibility

**Transaction fails to broadcast**

* Check API endpoint authentication
* Verify the recipient address is valid
* Ensure the transaction is properly signed

### Error Handling

```tsx
<DonateButton
  donationAddress="1YourAddress..."
  onError={(error) => {
    switch (error.message) {
      case 'INSUFFICIENT_FUNDS':
        toast.error('Insufficient BSV balance for this donation');
        break;
      case 'INVALID_ADDRESS':
        toast.error('Invalid donation address');
        break;
      case 'NETWORK_ERROR':
        toast.error('Network error. Please try again.');
        break;
      default:
        toast.error('Donation failed. Please try again.');
    }
  }}
/>
```

## Security Considerations

* **Address Validation**: Always validate donation addresses
* **Amount Limits**: Consider setting maximum donation amounts
* **Rate Limiting**: Implement rate limiting on donation endpoints
* **Audit Trail**: Log all donation attempts for security review

## Related Components

* [QuickDonateButton](/docs/components/quick-donate-button) - Simplified one-click donations
* [SendBSVButton](/docs/components/send-bsv-button) - General BSV sending interface
* [WalletOverview](/docs/components/wallet-overview) - Display wallet balance and info
* [TokenBalance](/docs/components/token-balance) - Show token balances

## API Reference

### Default Amounts

The default preset amounts are:

* 0.01 BSV (1,000,000 satoshis)
* 0.05 BSV (5,000,000 satoshis)
* 0.1 BSV (10,000,000 satoshis)
* 0.5 BSV (50,000,000 satoshis)
* 1 BSV (100,000,000 satoshis)

### QR Code Format

The QR code includes:

```
bitcoin:{address}?amount={amount_in_bsv}&message={message}
```

### Dependencies

* `useBitcoinAuth` - Authentication hook
* `useSendBSV` - Transaction sending hook
* `QRCodeRenderer` - QR code display
* Radix UI components for dialogs and buttons

# HandCashConnector
URL: /docs/components/wallet/handcash-connector

Connect and authenticate with HandCash wallet for seamless Bitcoin SV transactions and identity management

***

title: HandCashConnector
description: Connect and authenticate with HandCash wallet for seamless Bitcoin SV transactions and identity management
category: wallet
----------------

A comprehensive OAuth integration component for connecting with HandCash wallets, enabling seamless Bitcoin SV transactions, balance management, and social features in your application.

[View Component Preview →](/component-preview/handcash-connector)

## Installation

```bash
npx bigblocks add handcash-connector
```

## Import

```typescript
import { HandCashConnector } from 'bigblocks';
```

## Props

| Prop         | Type                             | Required | Default | Description                          |
| ------------ | -------------------------------- | -------- | ------- | ------------------------------------ |
| config       | `HandCashConfig`                 | Yes      | -       | HandCash OAuth configuration         |
| onConnect    | `(user: HandCashUser) => void`   | No       | -       | Callback when connection succeeds    |
| onError      | `(error: HandCashError) => void` | No       | -       | Callback when connection fails       |
| onDisconnect | `() => void`                     | No       | -       | Callback when wallet is disconnected |
| className    | `string`                         | No       | -       | Additional CSS classes               |

### HandCashConfig Interface

```typescript
interface HandCashConfig {
  appId: string;                    // HandCash app ID (required)
  redirectUri?: string;             // OAuth callback URL
  permissions?: HandCashPermission[]; // Requested permissions
  environment?: 'production' | 'sandbox'; // HandCash environment
}

interface HandCashPermission {
  scope: 
    | 'user_profile_read'           // Read user profile data
    | 'wallet_balance_read'         // Read wallet balance
    | 'payments_write'              // Send payments
    | 'friends_read'                // Access friends list
    | 'user_activity_read'          // Read transaction history
    | 'data_storage_write';         // Store app data
  required: boolean;                // Whether permission is mandatory
}
```

### HandCashUser Interface

```typescript
interface HandCashUser {
  handle: string;                   // HandCash handle (@username)
  publicKey: string;                // Bitcoin public key
  paymail: string;                  // Paymail address
  profile?: {
    displayName?: string;           // Display name
    avatarUrl?: string;             // Profile picture URL
    bio?: string;                   // User biography
    verified: boolean;              // Verification status
  };
  wallet: {
    balance: {
      bsv: number;                  // BSV balance
      usd: number;                  // USD equivalent
      pending: number;              // Pending amount
      lastUpdated: number;          // Last update timestamp
    };
    limits: {
      daily: number;                // Daily spending limit
      monthly: number;              // Monthly spending limit
      perTransaction: number;       // Per-transaction limit
      remainingDaily: number;       // Remaining daily limit
      remainingMonthly: number;     // Remaining monthly limit
    };
  };
}
```

## Basic Usage

```tsx
import { HandCashConnector } from 'bigblocks';

export default function WalletConnect() {
  return (
    <HandCashConnector 
      config={{ 
        appId: 'your-handcash-app-id' 
      }}
    />
  );
}
```

## Advanced Usage

### Complete OAuth Integration

```tsx
import { HandCashConnector } from 'bigblocks';
import { useState } from 'react';

export default function HandCashIntegration() {
  const [connectedUser, setConnectedUser] = useState<HandCashUser | null>(null);
  const [error, setError] = useState<string | null>(null);

const handleConnect = (user: HandCashUser) => {
    setConnectedUser(user);
    setError(null);
    console.log('Connected to HandCash:', user.handle);
    console.log('Balance:', user.wallet.balance.bsv, 'BSV');
  };

const handleError = (error: HandCashError) => {
    setError(error.message);
    console.error('HandCash connection failed:', error);
  };

const handleDisconnect = () => {
    setConnectedUser(null);
    setError(null);
    console.log('Disconnected from HandCash');
  };

return (
    <div className="handcash-integration">
      {!connectedUser ? (
        <HandCashConnector 
          config={{
            appId: process.env.NEXT_PUBLIC_HANDCASH_APP_ID!,
            redirectUri: `${window.location.origin}/auth/handcash/callback`,
            permissions: [
              { scope: 'user_profile_read', required: true },
              { scope: 'wallet_balance_read', required: true },
              { scope: 'payments_write', required: false },
              { scope: 'friends_read', required: false }
            ],
            environment: 'production'
          }}
          onConnect={handleConnect}
          onError={handleError}
          onDisconnect={handleDisconnect}
        />
      ) : (
        <div className="connected-wallet">
          <h3>Connected: {connectedUser.handle}</h3>
          <p>Balance: {connectedUser.wallet.balance.bsv} BSV</p>
          <p>USD Value: ${connectedUser.wallet.balance.usd}</p>
          <button onClick={handleDisconnect}>Disconnect</button>
        </div>
      )}
      
      {error && (
        <div className="error-message">
          <p>Error: {error}</p>
        </div>
      )}
    </div>
  );
}
```

### Production Configuration

```tsx
import { HandCashConnector } from 'bigblocks';

export default function ProductionHandCash() {
  return (
    <HandCashConnector 
      config={{
        appId: process.env.NEXT_PUBLIC_HANDCASH_APP_ID!,
        redirectUri: process.env.NEXT_PUBLIC_HANDCASH_REDIRECT_URI!,
        permissions: [
          { scope: 'user_profile_read', required: true },
          { scope: 'wallet_balance_read', required: true },
          { scope: 'payments_write', required: true },
          { scope: 'friends_read', required: false },
          { scope: 'user_activity_read', required: false }
        ],
        environment: 'production'
      }}
      onConnect={(user) => {
        // Store user data securely
        localStorage.setItem('handcash_user', JSON.stringify(user));
        // Navigate to dashboard
        window.location.href = '/dashboard';
      }}
      onError={(error) => {
        // Log error for monitoring
        console.error('HandCash OAuth failed:', error);
        // Show user-friendly error
        alert('Failed to connect HandCash wallet. Please try again.');
      }}
      className="bg-green-50 border-2 border-green-200 rounded-lg p-6"
    />
  );
}
```

### Sandbox Testing

```tsx
import { HandCashConnector } from 'bigblocks';

export default function HandCashSandbox() {
  return (
    <div className="sandbox-testing">
      <h2>HandCash Sandbox Testing</h2>
      <p>Use test credentials for development</p>
      
      <HandCashConnector 
        config={{
          appId: 'sandbox-app-id',
          environment: 'sandbox',
          permissions: [
            { scope: 'user_profile_read', required: true },
            { scope: 'wallet_balance_read', required: true },
            { scope: 'payments_write', required: true }
          ]
        }}
        onConnect={(user) => {
          console.log('Sandbox connection successful:', user);
        }}
        onError={(error) => {
          console.log('Sandbox error (expected):', error);
        }}
      />
    </div>
  );
}
```

## Common Patterns

### Wallet Selection Dashboard

```tsx
import { HandCashConnector, YoursWalletConnector } from 'bigblocks';
import { useState } from 'react';

export default function WalletSelectionDashboard() {
  const [selectedWallet, setSelectedWallet] = useState<string | null>(null);

return (
    <div className="wallet-selection">
      <h2>Connect Your Wallet</h2>
      
      <div className="wallet-options">
        <div className="wallet-option">
          <h3>HandCash</h3>
          <p>Popular mobile wallet with social features</p>
          <HandCashConnector 
            config={{ 
              appId: process.env.NEXT_PUBLIC_HANDCASH_APP_ID! 
            }}
            onConnect={(user) => {
              setSelectedWallet('handcash');
              console.log('Connected HandCash:', user.handle);
            }}
          />
        </div>
        
        <div className="wallet-option">
          <h3>Yours Wallet</h3>
          <p>Browser extension wallet</p>
          <YoursWalletConnector 
            onSuccess={(result) => {
              setSelectedWallet('yours');
              console.log('Connected Yours:', result.publicKey);
            }}
          />
        </div>
      </div>
      
      {selectedWallet && (
        <div className="selected-wallet">
          <p>Connected wallet: {selectedWallet}</p>
        </div>
      )}
    </div>
  );
}
```

### Payment Integration

```tsx
import { HandCashConnector } from 'bigblocks';
import { useState } from 'react';

export default function PaymentIntegration() {
  const [user, setUser] = useState<HandCashUser | null>(null);

const sendPayment = async (recipient: string, amount: number) => {
    if (!user) return;

try {
      const response = await fetch('/api/wallets/handcash/payments/send', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          handle: user.handle,
          recipients: [{ 
            destination: recipient, 
            amount: amount * 100000000 // Convert BSV to satoshis
          }],
          description: 'Payment from my app'
        })
      });

const result = await response.json();
      if (result.success) {
        console.log('Payment sent:', result.payment.transactionId);
        alert('Payment sent successfully!');
      }
    } catch (error) {
      console.error('Payment failed:', error);
      alert('Payment failed. Please try again.');
    }
  };

return (
    <div className="payment-integration">
      {!user ? (
        <HandCashConnector 
          config={{
            appId: process.env.NEXT_PUBLIC_HANDCASH_APP_ID!,
            permissions: [
              { scope: 'user_profile_read', required: true },
              { scope: 'wallet_balance_read', required: true },
              { scope: 'payments_write', required: true }
            ]
          }}
          onConnect={setUser}
        />
      ) : (
        <div className="payment-interface">
          <h3>Send Payment</h3>
          <p>Balance: {user.wallet.balance.bsv} BSV</p>
          
          <button onClick={() => sendPayment('@recipient', 0.001)}>
            Send 0.001 BSV to @recipient
          </button>
          
          <button onClick={() => sendPayment('1ABC...xyz', 0.01)}>
            Send 0.01 BSV to address
          </button>
        </div>
      )}
    </div>
  );
}
```

### Social Features Integration

```tsx
import { HandCashConnector } from 'bigblocks';
import { useState, useEffect } from 'react';

export default function SocialFeaturesIntegration() {
  const [user, setUser] = useState<HandCashUser | null>(null);
  const [friends, setFriends] = useState<any[]>([]);

useEffect(() => {
    if (user) {
      fetchFriends();
    }
  }, [user]);

const fetchFriends = async () => {
    if (!user) return;

try {
      const response = await fetch(`/api/wallets/handcash/friends?handle=${user.handle}`);
      const result = await response.json();
      setFriends(result.friends || []);
    } catch (error) {
      console.error('Failed to fetch friends:', error);
    }
  };

return (
    <div className="social-features">
      {!user ? (
        <HandCashConnector 
          config={{
            appId: process.env.NEXT_PUBLIC_HANDCASH_APP_ID!,
            permissions: [
              { scope: 'user_profile_read', required: true },
              { scope: 'friends_read', required: true }
            ]
          }}
          onConnect={setUser}
        />
      ) : (
        <div className="social-interface">
          <h3>Welcome, {user.profile?.displayName || user.handle}!</h3>
          
          <div className="friends-list">
            <h4>Your HandCash Friends ({friends.length})</h4>
            {friends.map((friend) => (
              <div key={friend.handle} className="friend-item">
                <img src={friend.avatarUrl} alt={friend.displayName} />
                <span>{friend.displayName || friend.handle}</span>
                <button onClick={() => sendPayment(friend.handle, 0.001)}>
                  Send Tip
                </button>
              </div>
            ))}
          </div>
        </div>
      )}
    </div>
  );
}
```

## Authentication Requirements

The HandCashConnector requires Bitcoin authentication context for secure operation:

```tsx
import { 
  BitcoinAuthProvider, 
  BitcoinQueryProvider, 
  HandCashConnector 
} from 'bigblocks';

function App() {
  return (
    <BitcoinQueryProvider>
      <BitcoinAuthProvider config={{ apiUrl: '/api' }}>
        <HandCashConnector 
          config={{ appId: 'your-app-id' }}
        />
      </BitcoinAuthProvider>
    </BitcoinQueryProvider>
  );
}
```

## API Integration

The HandCashConnector integrates with several backend endpoints:

### OAuth Flow Endpoints

```typescript
// Initialize OAuth flow
POST /api/wallets/handcash/auth/init
{
  appId: string;
  redirectUri?: string;
  permissions: HandCashPermission[];
}

// Complete OAuth flow
POST /api/wallets/handcash/auth/callback
{
  code: string;
  state: string;
  sessionId: string;
}

// Refresh access token
POST /api/wallets/handcash/auth/refresh
{
  handle: string;
  refreshToken: string;
}
```

### Wallet Operations

```typescript
// Get wallet status
GET /api/wallets/handcash/status?handle=<handle>

// Send payment
POST /api/wallets/handcash/payments/send
{
  handle: string;
  recipients: PaymentRecipient[];
  description?: string;
}

// Get transaction history
GET /api/wallets/handcash/transactions?handle=<handle>&type=<type>

// Get friends list
GET /api/wallets/handcash/friends?handle=<handle>
```

### Real-time Updates

```typescript
// WebSocket for live updates
WS /api/wallets/handcash/stream

// Subscribe to events
{
  type: 'subscribe',
  handle: string,
  events: ['balance', 'transaction', 'friend']
}
```

## Error Handling

### Common Error Types

```typescript
interface HandCashError {
  code: 
    | 'AUTH_FAILED'              // OAuth authentication failed
    | 'INVALID_TOKEN'            // Access token invalid/expired
    | 'INSUFFICIENT_BALANCE'     // Not enough BSV for operation
    | 'LIMIT_EXCEEDED'           // Spending limit exceeded
    | 'WALLET_NOT_FOUND'         // HandCash wallet not found
    | 'PERMISSION_DENIED'        // Required permission not granted
    | 'RATE_LIMITED'             // API rate limit exceeded
    | 'SERVICE_UNAVAILABLE';     // HandCash service temporarily down
  message: string;
  details?: {
    handle?: string;
    requiredPermissions?: string[];
    limitType?: string;
    remaining?: number;
    retryAfter?: number;
  };
}
```

### Error Handling Examples

```tsx
import { HandCashConnector } from 'bigblocks';

export default function ErrorHandlingExample() {
  const handleError = (error: HandCashError) => {
    switch (error.code) {
      case 'AUTH_FAILED':
        console.error('HandCash authentication failed:', error.message);
        alert('Failed to connect to HandCash. Please try again.');
        break;
        
      case 'PERMISSION_DENIED':
        console.error('Permission denied:', error.details?.requiredPermissions);
        alert('Please grant the required permissions to continue.');
        break;
        
      case 'RATE_LIMITED':
        console.error('Rate limited. Retry after:', error.details?.retryAfter);
        alert(`Too many requests. Please wait ${error.details?.retryAfter} seconds.`);
        break;
        
      case 'SERVICE_UNAVAILABLE':
        console.error('HandCash service unavailable');
        alert('HandCash service is temporarily unavailable. Please try again later.');
        break;
        
      default:
        console.error('Unknown HandCash error:', error);
        alert('An unexpected error occurred. Please try again.');
    }
  };

return (
    <HandCashConnector 
      config={{ appId: 'your-app-id' }}
      onError={handleError}
    />
  );
}
```

## Environment Configuration

### Development Setup

```typescript
// .env.local
NEXT_PUBLIC_HANDCASH_APP_ID=your-sandbox-app-id
NEXT_PUBLIC_HANDCASH_REDIRECT_URI=http://localhost:3000/auth/handcash/callback
HANDCASH_APP_SECRET=your-app-secret
HANDCASH_ENVIRONMENT=sandbox
```

### Production Setup

```typescript
// .env.production
NEXT_PUBLIC_HANDCASH_APP_ID=your-production-app-id
NEXT_PUBLIC_HANDCASH_REDIRECT_URI=https://yourapp.com/auth/handcash/callback
HANDCASH_APP_SECRET=your-production-app-secret
HANDCASH_ENVIRONMENT=production
```

## Security Considerations

### Token Security

* Access tokens are encrypted before storage
* Refresh tokens are rotated on each use
* All tokens have expiration times
* OAuth state parameter prevents CSRF attacks

```tsx
// Secure token handling
const handleConnect = (user: HandCashUser) => {
  // Never store tokens in localStorage
  // Use secure HTTP-only cookies instead
  document.cookie = `handcash_session=${user.sessionId}; HttpOnly; Secure; SameSite=Strict`;
};
```

### Permission Management

```tsx
// Request minimal permissions
const minimumPermissions: HandCashPermission[] = [
  { scope: 'user_profile_read', required: true },
  { scope: 'wallet_balance_read', required: false }
];

// Allow users to opt-in to additional permissions
const optionalPermissions: HandCashPermission[] = [
  { scope: 'payments_write', required: false },
  { scope: 'friends_read', required: false }
];
```

## Performance Optimization

### Connection Caching

```tsx
import { HandCashConnector } from 'bigblocks';
import { useEffect, useState } from 'react';

export default function CachedConnection() {
  const [cachedUser, setCachedUser] = useState<HandCashUser | null>(null);

useEffect(() => {
    // Check for existing connection
    const checkExistingConnection = async () => {
      try {
        const response = await fetch('/api/wallets/handcash/status');
        if (response.ok) {
          const user = await response.json();
          setCachedUser(user);
        }
      } catch (error) {
        console.log('No existing connection');
      }
    };

checkExistingConnection();
  }, []);

if (cachedUser) {
    return (
      <div className="cached-connection">
        <p>Already connected: {cachedUser.handle}</p>
        <p>Balance: {cachedUser.wallet.balance.bsv} BSV</p>
      </div>
    );
  }

return (
    <HandCashConnector 
      config={{ appId: 'your-app-id' }}
      onConnect={setCachedUser}
    />
  );
}
```

## Troubleshooting

### Common Issues

**OAuth flow fails silently**

* Verify `appId` is correct for the environment
* Check `redirectUri` matches registered callback URL
* Ensure app has the correct permissions configured

**Connection established but balance is zero**

* User may be on testnet vs mainnet
* Check environment configuration
* Verify HandCash app has correct network settings

**Payments fail with "insufficient balance"**

* Check actual balance vs displayed balance
* Account for transaction fees (\~0.0001 BSV)
* Verify spending limits aren't exceeded

**Token expires quickly**

* Implement automatic token refresh
* Handle token expiration gracefully
* Store refresh tokens securely

### Debug Mode

```tsx
<HandCashConnector 
  config={{ 
    appId: 'your-app-id',
    environment: 'sandbox'  // Use sandbox for debugging
  }}
  onConnect={(user) => {
    console.log('HandCash connection debug:', {
      handle: user.handle,
      balance: user.wallet.balance,
      permissions: user.permissions
    });
  }}
  onError={(error) => {
    console.error('HandCash error debug:', error);
  }}
/>
```

## Related Components

* [YoursWalletConnector](/docs/components/yours-wallet-connector) - Alternative wallet connection
* [SendBSVButton](/docs/components/send-bsv-button) - Send BSV transactions
* [WalletOverview](/docs/components/wallet-overview) - Display wallet information
* [DonateButton](/docs/components/donate-button) - Accept Bitcoin donations

## API Reference

### HandCashConnector Component

```typescript
interface HandCashConnectorProps {
  config: HandCashConfig;
  onConnect?: (user: HandCashUser) => void;
  onError?: (error: HandCashError) => void;
  onDisconnect?: () => void;
  className?: string;
}
```

### Usage with React Query

```typescript
import { useQuery, useMutation } from '@tanstack/react-query';
import { HandCashConnector } from 'bigblocks';

function HandCashWithQuery() {
  const { data: connectionStatus } = useQuery({
    queryKey: ['handcash-status'],
    queryFn: () => fetch('/api/wallets/handcash/status').then(res => res.json()),
    refetchInterval: 30000 // Refresh every 30 seconds
  });

const connectMutation = useMutation({
    mutationFn: (authCode: string) => 
      fetch('/api/wallets/handcash/auth/callback', {
        method: 'POST',
        body: JSON.stringify({ code: authCode })
      }).then(res => res.json()),
    onSuccess: (user) => {
      console.log('Connected:', user.handle);
    }
  });

return (
    <HandCashConnector 
      config={{ appId: 'your-app-id' }}
      onConnect={(user) => connectMutation.mutate(user.authCode)}
    />
  );
}
```

# QuickDonateButton
URL: /docs/components/wallet/quick-donate-button

A streamlined donation button for accepting Bitcoin SV donations with preset amounts and one-click processing

***

title: QuickDonateButton
description: A streamlined donation button for accepting Bitcoin SV donations with preset amounts and one-click processing
category: wallet
----------------

A streamlined donation button component that provides a frictionless experience for accepting Bitcoin SV donations with smart preset amounts, real-time validation, and comprehensive transaction tracking.

[View Component Preview →](/component-preview/quick-donate-button)

## Installation

```bash
npx bigblocks add quick-donate-button
```

## Import

```typescript
import { QuickDonateButton } from 'bigblocks';
```

## Props

| Prop             | Type                                  | Required | Default                | Description                            |
| ---------------- | ------------------------------------- | -------- | ---------------------- | -------------------------------------- |
| recipientAddress | `string`                              | Yes      | -                      | Bitcoin address to receive donations   |
| amounts          | `number[]`                            | No       | `[0.001, 0.005, 0.01]` | Preset BSV amounts for quick selection |
| defaultAmount    | `number`                              | No       | First amount           | Default selected amount                |
| onSuccess        | `(txid: string) => void`              | No       | -                      | Callback when donation succeeds        |
| onError          | `(error: QuickDonationError) => void` | No       | -                      | Callback when donation fails           |
| label            | `string`                              | No       | `'Donate'`             | Button label text                      |
| compact          | `boolean`                             | No       | `true`                 | Use compact display mode               |
| className        | `string`                              | No       | -                      | Additional CSS classes                 |

### QuickDonationError Interface

```typescript
interface QuickDonationError {
  code: 
    | 'INSUFFICIENT_FUNDS'        // Not enough BSV for donation
    | 'INVALID_ADDRESS'           // Malformed recipient address
    | 'AMOUNT_TOO_SMALL'          // Below minimum donation amount
    | 'AMOUNT_TOO_LARGE'          // Above maximum transaction limit
    | 'DAILY_LIMIT_EXCEEDED'      // Daily donation limit reached
    | 'RATE_LIMITED'              // Too many requests
    | 'RECIPIENT_BLOCKED';        // Recipient not allowed
  message: string;
  details?: {
    minimumAmount?: number;       // Minimum required amount
    maximumAmount?: number;       // Maximum allowed amount
    dailyLimit?: number;          // Daily limit amount
    dailyUsed?: number;           // Amount used today
    resetTime?: number;           // When limits reset
    available?: number;           // Available balance
    required?: number;            // Required amount
  };
}
```

## Basic Usage

```tsx
import { QuickDonateButton } from 'bigblocks';

export default function DonationSection() {
  return (
    <QuickDonateButton 
      recipientAddress="1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa"
      amounts={[0.001, 0.01, 0.1]}
      onSuccess={(txid) => {
        console.log('Donation sent! TxID:', txid);
      }}
    />
  );
}
```

## Advanced Usage

### Complete Donation Integration

```tsx
import { QuickDonateButton } from 'bigblocks';
import { useState } from 'react';

export default function AdvancedDonation() {
  const [donationHistory, setDonationHistory] = useState<string[]>([]);
  const [isProcessing, setIsProcessing] = useState(false);

return (
    <div className="donation-section">
      <h2>Support Our Project</h2>
      <p>Your donations help us continue building amazing Bitcoin applications.</p>
      
      <QuickDonateButton 
        recipientAddress="1BitcoinDeveloperAddressHere..."
        amounts={[0.001, 0.005, 0.01, 0.05, 0.1]}
        defaultAmount={0.005}
        onSuccess={handleDonationSuccess}
        onError={handleDonationError}
        label="Support Development"
        compact={false}
        className="bg-gradient-to-r from-orange-500 to-red-500 text-white font-bold"
      />
      
      {donationHistory.length > 0 && (
        <div className="donation-history mt-4">
          <h3>Your Recent Donations</h3>
          <ul className="text-sm text-gray-600">
            {donationHistory.slice(0, 5).map((txid) => (
              <li key={txid}>
                <a 
                  href={`https://whatsonchain.com/tx/${txid}`}
                  target="_blank"
                  rel="noopener noreferrer"
                  className="hover:underline"
                >
                  {txid.slice(0, 8)}...{txid.slice(-8)}
                </a>
              </li>
            ))}
          </ul>
        </div>
      )}
    </div>
  );
}
```

### Smart Presets with Dynamic Amounts

```tsx
import { QuickDonateButton } from 'bigblocks';
import { useEffect, useState } from 'react';

export default function SmartPresetDonation() {
  const [smartAmounts, setSmartAmounts] = useState<number[]>([0.001, 0.005, 0.01]);

useEffect(() => {
    // Fetch smart presets based on recipient and donor history
    const fetchSmartPresets = async () => {
      try {
        const response = await fetch('/api/wallet/quick-donate/presets?currency=BSV&recipient=1BitcoinAddress...');
        const data = await response.json();
        
        if (data.presets) {
          const amounts = data.presets.map((preset: any) => 
            parseFloat(preset.amountBSV)
          );
          setSmartAmounts(amounts);
        }
      } catch (error) {
        console.error('Failed to fetch smart presets:', error);
      }
    };

fetchSmartPresets();
  }, []);

return (
    <div className="smart-donation">
      <h3>Smart Donation Amounts</h3>
      <p>Amounts personalized based on your donation history and recipient preferences.</p>
      
      <QuickDonateButton 
        recipientAddress="1BitcoinRecipientAddress..."
        amounts={smartAmounts}
        onSuccess={(txid) => {
          console.log('Smart donation successful:', txid);
          // Update user's donation profile for better future recommendations
        }}
        className="border-2 border-blue-500 hover:bg-blue-50"
      />
    </div>
  );
}
```

### Charity Campaign Integration

```tsx
import { QuickDonateButton } from 'bigblocks';
import { useState, useEffect } from 'react';

interface CampaignInfo {
  name: string;
  goal: number;
  raised: number;
  description: string;
  endDate: string;
}

export default function CharityCampaign() {
  const [campaign, setCampaign] = useState<CampaignInfo | null>(null);
  const [progress, setProgress] = useState(0);

useEffect(() => {
    // Fetch campaign information
    const fetchCampaign = async () => {
      // This would typically come from your API
      setCampaign({
        name: "Bitcoin Education Fund",
        goal: 10, // 10 BSV
        raised: 6.5, // 6.5 BSV raised so far
        description: "Help us educate developers about Bitcoin applications",
        endDate: "2025-12-31"
      });
    };

fetchCampaign();
  }, []);

useEffect(() => {
    if (campaign) {
      setProgress((campaign.raised / campaign.goal) * 100);
    }
  }, [campaign]);

if (!campaign) return <div>Loading campaign...</div>;

return (
    <div className="charity-campaign">
      <div className="campaign-info mb-6">
        <h2 className="text-2xl font-bold">{campaign.name}</h2>
        <p className="text-gray-600 mb-4">{campaign.description}</p>
        
        <div className="progress-section mb-4">
          <div className="flex justify-between text-sm mb-2">
            <span>{campaign.raised} BSV raised</span>
            <span>{campaign.goal} BSV goal</span>
          </div>
          <div className="w-full bg-gray-200 rounded-full h-2.5">
            <div 
              className="bg-green-600 h-2.5 rounded-full transition-all duration-500"
              style={{ width: `${Math.min(progress, 100)}%` }}
            ></div>
          </div>
          <p className="text-sm text-gray-500 mt-2">
            {Math.round(progress)}% complete • Ends {new Date(campaign.endDate).toLocaleDateString()}
          </p>
        </div>
      </div>
      
      <QuickDonateButton 
        recipientAddress="1CharityBitcoinAddress..."
        amounts={[0.001, 0.01, 0.1, 0.5]}
        defaultAmount={0.01}
        onSuccess={handleCampaignDonation}
        onError={(error) => {
          console.error('Campaign donation failed:', error);
          alert('Donation failed. Please try again.');
        }}
        label="Donate to Campaign"
        className="w-full bg-green-600 hover:bg-green-700 text-white font-semibold py-3"
      />
    </div>
  );
}
```

## Common Patterns

### Multi-Recipient Donation Dashboard

```tsx
import { QuickDonateButton } from 'bigblocks';

const recipients = [
  {
    name: "Open Source Developer",
    address: "1Developer1Address...",
    description: "Building Bitcoin tools",
    category: "development",
    amounts: [0.001, 0.01, 0.1]
  },
  {
    name: "Bitcoin Charity",
    address: "1Charity1Address...",
    description: "Helping those in need",
    category: "charity", 
    amounts: [0.01, 0.1, 1.0]
  },
  {
    name: "Content Creator",
    address: "1Creator1Address...",
    description: "Educational Bitcoin content",
    category: "creator",
    amounts: [0.001, 0.005, 0.01]
  }
];

export default function DonationDashboard() {
  const handleDonation = (recipient: string, txid: string) => {
    console.log(`Donation to ${recipient}: ${txid}`);
    
    // Track donation analytics
    fetch('/api/analytics/donation', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        recipient,
        txid,
        source: 'dashboard',
        timestamp: Date.now()
      })
    });
  };

return (
    <div className="donation-dashboard">
      <h1>Support the Bitcoin Ecosystem</h1>
      
      <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">
        {recipients.map((recipient) => (
          <div key={recipient.address} className="recipient-card p-6 border rounded-lg">
            <h3 className="font-bold text-lg">{recipient.name}</h3>
            <p className="text-gray-600 mb-2">{recipient.description}</p>
            <span className="inline-block bg-blue-100 text-blue-800 text-xs px-2 py-1 rounded mb-4">
              {recipient.category}
            </span>
            
            <QuickDonateButton 
              recipientAddress={recipient.address}
              amounts={recipient.amounts}
              onSuccess={(txid) => handleDonation(recipient.name, txid)}
              label="Support"
              className="w-full"
            />
          </div>
        ))}
      </div>
    </div>
  );
}
```

### Subscription-Style Recurring Donations

```tsx
import { QuickDonateButton } from 'bigblocks';
import { useState } from 'react';

export default function RecurringDonation() {
  const [isRecurring, setIsRecurring] = useState(false);
  const [recurringAmount, setRecurringAmount] = useState(0.01);

return (
    <div className="recurring-donation">
      <h3>Monthly Support</h3>
      
      <div className="recurring-options mb-4">
        <label className="flex items-center">
          <input 
            type="checkbox"
            checked={isRecurring}
            onChange={(e) => setIsRecurring(e.target.checked)}
            className="mr-2"
          />
          Make this a monthly recurring donation
        </label>
      </div>
      
      <QuickDonateButton 
        recipientAddress="1RecurringRecipient..."
        amounts={[0.01, 0.05, 0.1]}
        defaultAmount={recurringAmount}
        onSuccess={handleRecurringDonation}
        label={isRecurring ? "Start Monthly Support" : "One-time Donation"}
        className={isRecurring ? "bg-purple-600 hover:bg-purple-700" : ""}
      />
      
      {isRecurring && (
        <p className="text-sm text-gray-600 mt-2">
          You'll be charged {recurringAmount} BSV monthly. Cancel anytime in settings.
        </p>
      )}
    </div>
  );
}
```

## Authentication Requirements

The QuickDonateButton requires Bitcoin authentication context for wallet operations:

```tsx
import { 
  BitcoinAuthProvider, 
  BitcoinQueryProvider, 
  QuickDonateButton 
} from 'bigblocks';

function App() {
  return (
    <BitcoinQueryProvider>
      <BitcoinAuthProvider config={{ 
        apiUrl: '/api',
        walletMode: 'integrated' // Enables wallet features
      }}>
        <QuickDonateButton 
          recipientAddress="1BitcoinAddress..."
        />
      </BitcoinAuthProvider>
    </BitcoinQueryProvider>
  );
}
```

## API Integration

The QuickDonateButton integrates with several backend endpoints for comprehensive donation processing:

### Core Donation Endpoints

```typescript
// Send quick donation
POST /api/wallet/quick-donate
{
  recipientAddress: string;
  amount: number; // satoshis
  message?: string;
  source?: string;
  metadata?: {
    page?: string;
    context?: string;
    campaign?: string;
  };
}

// Response includes transaction details and updated balance
{
  success: boolean;
  txid: string;
  quickDonation: {
    id: string;
    amount: number;
    recipient: string;
    status: 'pending' | 'confirmed';
    // ... full donation details
  };
  balance: {
    remaining: number;
    canDonateAgain: boolean;
  };
}
```

### Smart Presets API

```typescript
// Get personalized donation amounts
GET /api/wallet/quick-donate/presets?currency=BSV&recipient=<address>

// Returns optimized amounts based on:
// - Recipient category (charity, development, creator)
// - Donor's previous donation history  
// - Current BSV market price
// - Donor's wallet balance
{
  presets: [
    {
      amount: number;
      amountBSV: string;
      amountUSD?: string;
      label: string; // "Small", "Medium", "Large"
      recommended?: boolean;
    }
  ];
  recipient?: {
    name?: string;
    verified?: boolean;
    category?: string;
  };
  limits: {
    minimum: number;
    maximum: number;
    dailyLimit?: number;
  };
}
```

### Validation and Security

```typescript
// Validate donation before processing
POST /api/wallet/quick-donate/validate
{
  recipientAddress: string;
  amount: number;
}

// Comprehensive validation response
{
  valid: boolean;
  validation: {
    address: {
      valid: boolean;
      type?: 'p2pkh' | 'p2sh' | 'p2wpkh';
      network: 'mainnet' | 'testnet';
    };
    amount: {
      valid: boolean;
      withinLimits: boolean;
      belowBalance: boolean;
      aboveDust: boolean;
    };
    fees: {
      estimated: number;
      total: number;
      affordable: boolean;
    };
  };
  warnings?: string[];
  suggestions?: {
    adjustedAmount?: number;
    feeOptimization?: string;
  };
}
```

### Real-time Updates

```typescript
// Server-Sent Events for donation updates
GET /api/wallet/quick-donate/stream

Events:
- donation_sent: { txid: string, amount: number, recipient: string }
- donation_confirmed: { txid: string, confirmations: number }
- balance_updated: { balance: number, canDonate: boolean }
- daily_limit_reached: { limit: number, resetTime: number }
```

## Error Handling

### Comprehensive Error Management

```tsx
import { QuickDonateButton } from 'bigblocks';

export default function RobustDonationHandler() {
  const handleDonationError = (error: QuickDonationError) => {
    switch (error.code) {
      case 'INSUFFICIENT_FUNDS':
        // Show user their balance and suggest smaller amount
        console.log(`Need ${error.details?.required} satoshis, have ${error.details?.available}`);
        showBalanceModal(error.details);
        break;
        
      case 'AMOUNT_TOO_SMALL':
        // Suggest minimum amount
        console.log(`Minimum donation: ${error.details?.minimumAmount} satoshis`);
        suggestMinimumAmount(error.details?.minimumAmount);
        break;
        
      case 'DAILY_LIMIT_EXCEEDED':
        // Show limit info and reset time
        const resetTime = new Date(error.details?.resetTime || 0);
        console.log(`Daily limit exceeded. Resets at ${resetTime.toLocaleTimeString()}`);
        showLimitExceededModal(error.details);
        break;
        
      case 'RATE_LIMITED':
        // Show retry countdown
        console.log('Too many donation attempts. Please wait.');
        showRateLimitWarning();
        break;
        
      case 'INVALID_ADDRESS':
        // Show address validation error
        console.log('Invalid recipient address');
        showAddressError();
        break;
        
      default:
        // Generic error handler
        console.error('Unknown donation error:', error);
        showGenericError(error.message);
    }
  };

return (
    <QuickDonateButton 
      recipientAddress="1BitcoinAddress..."
      amounts={[0.001, 0.01, 0.1]}
      onError={handleDonationError}
      onSuccess={(txid) => {
        console.log('Donation successful:', txid);
        showSuccessNotification(txid);
      }}
    />
  );
}
```

### Error Recovery Patterns

```tsx
import { QuickDonateButton } from 'bigblocks';
import { useState } from 'react';

export default function ErrorRecoveryDonation() {
  const [lastError, setLastError] = useState<QuickDonationError | null>(null);
  const [suggestedAmount, setSuggestedAmount] = useState<number | null>(null);

const retryWithSuggestedAmount = () => {
    setLastError(null);
    setSuggestedAmount(null);
    // Component will re-render with new suggested amount
  };

return (
    <div className="error-recovery-donation">
      <QuickDonateButton 
        recipientAddress="1BitcoinAddress..."
        amounts={suggestedAmount ? [suggestedAmount] : [0.001, 0.01, 0.1]}
        onError={handleError}
        onSuccess={() => {
          setLastError(null);
          setSuggestedAmount(null);
        }}
      />
      
      {lastError && (
        <div className="error-recovery mt-4 p-4 bg-red-50 border border-red-200 rounded">
          <h4 className="font-semibold text-red-800">Donation Failed</h4>
          <p className="text-red-600">{lastError.message}</p>
          
          {suggestedAmount && (
            <div className="mt-2">
              <p className="text-sm text-red-600">
                Suggested amount: {suggestedAmount} BSV
              </p>
              <button 
                onClick={retryWithSuggestedAmount}
                className="mt-2 px-4 py-2 bg-red-600 text-white rounded hover:bg-red-700"
              >
                Retry with {suggestedAmount} BSV
              </button>
            </div>
          )}
        </div>
      )}
    </div>
  );
}
```

## Performance Optimization

### Preset Caching Strategy

```tsx
import { QuickDonateButton } from 'bigblocks';
import { useState, useEffect, useMemo } from 'react';

export default function OptimizedDonation() {
  const [cachedPresets, setCachedPresets] = useState<Map<string, any>>(new Map());
  
  const recipientAddress = "1BitcoinAddress...";
  
  // Memoized preset loading with cache
  const presets = useMemo(() => {
    const cacheKey = `${recipientAddress}:BSV`;
    
    if (cachedPresets.has(cacheKey)) {
      const cached = cachedPresets.get(cacheKey);
      // Check if cache is still valid (5 minute TTL)
      if (Date.now() - cached.timestamp < 300000) {
        return cached.presets;
      }
    }
    
    // Load fresh presets
    fetch(`/api/wallet/quick-donate/presets?currency=BSV&recipient=${recipientAddress}`)
      .then(res => res.json())
      .then(data => {
        setCachedPresets(prev => new Map(prev).set(cacheKey, {
          presets: data.presets.map((p: any) => parseFloat(p.amountBSV)),
          timestamp: Date.now()
        }));
      })
      .catch(console.error);
    
    // Return default while loading
    return [0.001, 0.01, 0.1];
  }, [recipientAddress, cachedPresets]);

return (
    <QuickDonateButton 
      recipientAddress={recipientAddress}
      amounts={presets}
    />
  );
}
```

## Security Considerations

### Rate Limiting and Abuse Prevention

The QuickDonateButton implements several security measures:

* **Transaction Rate Limiting**: Maximum 20 donations per hour per user
* **Daily Spending Limits**: Configurable daily donation limits (default: 1 BSV)
* **Address Validation**: Real-time Bitcoin address format validation
* **Amount Validation**: Enforced minimum (dust limit) and maximum amounts
* **Recipient Verification**: Optional recipient verification system

### Safe Donation Practices

```tsx
import { QuickDonateButton } from 'bigblocks';

export default function SecureDonation() {
  const verifyRecipient = async (address: string) => {
    try {
      const response = await fetch(`/api/wallet/recipients/${address}`);
      const data = await response.json();
      
      return {
        verified: data.recipient?.verified || false,
        trustScore: data.trustScore || 0,
        category: data.recipient?.category
      };
    } catch {
      return { verified: false, trustScore: 0 };
    }
  };

return (
    <div className="secure-donation">
      <div className="security-notice mb-4 p-3 bg-yellow-50 border border-yellow-200 rounded">
        <p className="text-sm text-yellow-800">
          🔒 All donations are processed securely using Bitcoin signatures. 
          Verify recipient addresses before donating.
        </p>
      </div>
      
      <QuickDonateButton 
        recipientAddress="1VerifiedRecipientAddress..."
        amounts={[0.001, 0.01, 0.1]}
        onSuccess={handleSecureDonation}
        onError={(error) => {
          // Log security-related errors
          if (error.code === 'RECIPIENT_BLOCKED') {
            console.warn('Attempted donation to blocked recipient');
          }
        }}
      />
    </div>
  );
}
```

## Troubleshooting

### Common Issues

**Button doesn't respond to clicks**

* Ensure `BitcoinAuthProvider` is properly configured
* Check that user has sufficient balance for minimum donation
* Verify recipient address format is valid

**Donations fail with "insufficient funds"**

* Check user's actual BSV balance
* Account for transaction fees (\~0.0001 BSV)
* Verify no daily spending limits are exceeded

**Preset amounts not loading**

* Check API endpoint `/api/wallet/quick-donate/presets` is accessible
* Verify recipient address is valid
* Check network connectivity for preset fetching

**Daily limit errors**

* Daily limits reset at midnight UTC
* Check user's donation history for the current day
* Limits can be configured per user in admin settings

### Debug Mode

```tsx
import { QuickDonateButton } from 'bigblocks';

export default function DebugDonation() {
  const debugDonation = (txid: string) => {
    console.log('Debug donation success:', {
      txid,
      timestamp: new Date().toISOString(),
      userAgent: navigator.userAgent,
      recipientAddress: '1BitcoinAddress...'
    });
  };

const debugError = (error: QuickDonationError) => {
    console.error('Debug donation error:', {
      code: error.code,
      message: error.message,
      details: error.details,
      timestamp: new Date().toISOString()
    });
  };

return (
    <div className="debug-donation">
      <h3>Debug Mode Donation</h3>
      <QuickDonateButton 
        recipientAddress="1BitcoinAddress..."
        amounts={[0.001, 0.01, 0.1]}
        onSuccess={debugDonation}
        onError={debugError}
        className="border-2 border-gray-300"
      />
    </div>
  );
}
```

## Related Components

* [DonateButton](/docs/components/donate-button) - Full-featured donation interface
* [SendBSVButton](/docs/components/send-bsv-button) - General BSV sending
* [WalletOverview](/docs/components/wallet-overview) - Wallet balance and status
* [CompactWalletOverview](/docs/components/compact-wallet-overview) - Compact wallet display

## API Reference

### QuickDonateButton Component

```typescript
interface QuickDonateButtonProps {
  recipientAddress: string;
  amounts?: number[];
  defaultAmount?: number;
  onSuccess?: (txid: string) => void;
  onError?: (error: QuickDonationError) => void;
  label?: string;
  compact?: boolean;
  className?: string;
}
```

### Advanced Usage with React Query

```typescript
import { useQuery, useMutation } from '@tanstack/react-query';
import { QuickDonateButton } from 'bigblocks';

function QuickDonateWithQuery() {
  // Query for smart presets
  const { data: presets } = useQuery({
    queryKey: ['donation-presets', recipientAddress],
    queryFn: () => fetch(`/api/wallet/quick-donate/presets?currency=BSV&recipient=${recipientAddress}`).then(res => res.json()),
    staleTime: 5 * 60 * 1000, // 5 minutes
    refetchOnWindowFocus: false
  });

// Mutation for donation processing
  const donationMutation = useMutation({
    mutationFn: (donationData: { recipientAddress: string; amount: number }) =>
      fetch('/api/wallet/quick-donate', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(donationData)
      }).then(res => res.json()),
    onSuccess: (data) => {
      console.log('Donation processed:', data.txid);
    },
    onError: (error) => {
      console.error('Donation failed:', error);
    }
  });

const amounts = presets?.presets.map((p: any) => parseFloat(p.amountBSV)) || [0.001, 0.01, 0.1];

return (
    <QuickDonateButton 
      recipientAddress={recipientAddress}
      amounts={amounts}
      onSuccess={(txid) => console.log('Success:', txid)}
      onError={(error) => console.error('Error:', error)}
    />
  );
}
```

# QuickSendButton
URL: /docs/components/wallet/quick-send-button

A streamlined Bitcoin BSV sending component that provides instant access to send transactions without opening a full wallet interface

***

title: QuickSendButton
description: A streamlined Bitcoin BSV sending component that provides instant access to send transactions without opening a full wallet interface
category: wallet
----------------

A streamlined Bitcoin BSV sending component that provides instant access to send transactions through an elegant modal interface, perfect for quick micropayments, tips, and instant transfers without the complexity of a full wallet interface.

[View Component Preview →](/component-preview/quick-send-button)

## Installation

```bash
npx bigblocks add quick-send-button
```

## Import

```typescript
import { QuickSendButton } from 'bigblocks';
```

## Props

| Prop            | Type                                                      | Required | Default      | Description                        |
| --------------- | --------------------------------------------------------- | -------- | ------------ | ---------------------------------- |
| onSuccess       | `(txid: string, amount: number, address: string) => void` | No       | -            | Callback when transaction succeeds |
| onError         | `(error: string) => void`                                 | No       | -            | Callback when transaction fails    |
| defaultAmount   | `number`                                                  | No       | -            | Pre-fill amount in satoshis        |
| defaultAddress  | `string`                                                  | No       | -            | Pre-fill recipient address         |
| buttonText      | `string`                                                  | No       | `'Send BSV'` | Custom button text                 |
| variant         | `'solid' \| 'outline' \| 'ghost'`                         | No       | `'solid'`    | Button style variant               |
| size            | `'small' \| 'medium' \| 'large'`                          | No       | `'medium'`   | Button size                        |
| showBalanceHint | `boolean`                                                 | No       | `false`      | Show current balance hint          |
| maxAmount       | `number`                                                  | No       | -            | Maximum send amount in satoshis    |
| disabled        | `boolean`                                                 | No       | `false`      | Disable the button                 |
| className       | `string`                                                  | No       | -            | Additional CSS classes             |

## Basic Usage

```tsx
import { QuickSendButton } from 'bigblocks';

export default function BasicSendExample() {
  return (
    <div className="send-section">
      <h3>Send BSV Instantly</h3>
      
      <QuickSendButton 
        onSuccess={(txid, amount, address) => {
          console.log(`Sent ${amount} satoshis to ${address}. TxID: ${txid}`);
        }}
        onError={(error) => {
          console.error('Send failed:', error);
        }}
      />
    </div>
  );
}
```

## Advanced Usage

### Complete Send Interface

```tsx
import { QuickSendButton } from 'bigblocks';
import { useState } from 'react';

export default function AdvancedSendInterface() {
  const [transactionHistory, setTransactionHistory] = useState<Array<{
    txid: string;
    amount: number;
    address: string;
    timestamp: number;
  }>>([]);

return (
    <div className="advanced-send-interface">
      <div className="send-controls">
        <h2>Send Bitcoin SV</h2>
        
        <QuickSendButton 
          onSuccess={handleSendSuccess}
          onError={handleSendError}
          showBalanceHint={true}
          maxAmount={100000000} // 1 BSV maximum
          buttonText="💰 Send BSV"
          variant="solid"
          size="large"
          className="bg-gradient-to-r from-blue-500 to-purple-600 text-white font-bold"
        />
      </div>
      
      {transactionHistory.length > 0 && (
        <div className="transaction-history mt-6">
          <h3>Recent Transactions</h3>
          <div className="space-y-2">
            {transactionHistory.slice(0, 5).map((tx) => (
              <div key={tx.txid} className="flex items-center justify-between p-3 bg-gray-50 rounded">
                <div>
                  <span className="font-mono text-sm">
                    {tx.address.slice(0, 10)}...{tx.address.slice(-6)}
                  </span>
                  <span className="ml-2 text-gray-600">
                    {tx.amount.toLocaleString()} sats
                  </span>
                </div>
                <a 
                  href={`https://whatsonchain.com/tx/${tx.txid}`}
                  target="_blank"
                  rel="noopener noreferrer"
                  className="text-blue-500 hover:underline text-sm"
                >
                  View
                </a>
              </div>
            ))}
          </div>
        </div>
      )}
    </div>
  );
}
```

### Pre-filled Quick Send

```tsx
import { QuickSendButton } from 'bigblocks';

export default function PrefilledSendExample() {
  return (
    <div className="prefilled-examples">
      <h3>Quick Send Examples</h3>
      
      {/* Pre-filled with amount */}
      <div className="example-item">
        <h4>Tip 1000 satoshis</h4>
        <QuickSendButton 
          defaultAmount={1000}
          buttonText="💡 Send Tip"
          variant="outline"
          onSuccess={(txid) => console.log('Tip sent:', txid)}
        />
      </div>
      
      {/* Pre-filled with address and amount */}
      <div className="example-item">
        <h4>Donate to Developer</h4>
        <QuickSendButton 
          defaultAddress="1DeveloperAddressHere..."
          defaultAmount={5000}
          buttonText="🚀 Support Development"
          variant="solid"
          onSuccess={(txid, amount, address) => {
            console.log(`Donated ${amount} satoshis to developer`);
            // Show thank you message
            alert('Thank you for supporting open source development!');
          }}
        />
      </div>
      
      {/* Custom styling with balance hint */}
      <div className="example-item">
        <h4>Custom Send with Balance</h4>
        <QuickSendButton 
          showBalanceHint={true}
          buttonText="💸 Send Payment"
          size="large"
          className="border-2 border-green-500 hover:bg-green-50"
          onSuccess={(txid, amount, address) => {
            console.log(`Payment sent: ${amount} sats to ${address}`);
          }}
        />
      </div>
    </div>
  );
}
```

## Common Patterns

### Tip Button for Content Creators

```tsx
import { QuickSendButton } from 'bigblocks';

interface TipCreatorProps {
  creatorAddress: string;
  creatorName: string;
  contentId?: string;
}

export default function TipCreator({ creatorAddress, creatorName, contentId }: TipCreatorProps) {
  const tipAmounts = [500, 1000, 5000, 10000]; // Different tip amounts

return (
    <div className="tip-creator-section">
      <div className="creator-info mb-4">
        <h4>Enjoyed this content?</h4>
        <p>Tip {creatorName} to show your appreciation</p>
      </div>
      
      {/* Quick tip amounts */}
      <div className="tip-amounts mb-4">
        <span className="text-sm text-gray-600">Quick tips:</span>
        <div className="flex gap-2 mt-1">
          {tipAmounts.map((amount) => (
            <QuickSendButton 
              key={amount}
              defaultAddress={creatorAddress}
              defaultAmount={amount}
              buttonText={`${amount} sats`}
              size="small"
              variant="outline"
              onSuccess={(txid) => handleTip(txid, amount)}
              className="text-xs"
            />
          ))}
        </div>
      </div>
      
      {/* Custom amount tip */}
      <QuickSendButton 
        defaultAddress={creatorAddress}
        buttonText={`💡 Tip ${creatorName}`}
        variant="solid"
        onSuccess={(txid, amount) => handleTip(txid, amount)}
        className="bg-orange-500 hover:bg-orange-600 text-white"
      />
    </div>
  );
}
```

### Gaming Micropayments

```tsx
import { QuickSendButton } from 'bigblocks';

interface GameItem {
  id: string;
  name: string;
  price: number; // in satoshis
  description: string;
  icon: string;
}

interface GameShopProps {
  playerId: string;
  gamePaymentAddress: string;
}

export default function GameShop({ playerId, gamePaymentAddress }: GameShopProps) {
  const items: GameItem[] = [
    { id: 'sword', name: 'Magic Sword', price: 2500, description: '+10 Attack', icon: '⚔️' },
    { id: 'shield', name: 'Shield', price: 1500, description: '+8 Defense', icon: '🛡️' },
    { id: 'potion', name: 'Health Potion', price: 500, description: 'Restore 50 HP', icon: '🧪' },
    { id: 'armor', name: 'Dragon Armor', price: 10000, description: '+20 Defense', icon: '🥼' }
  ];

const handleItemPurchase = async (item: GameItem, txid: string) => {
    try {
      // Award item to player
      const response = await fetch('/api/game/purchase', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          playerId,
          itemId: item.id,
          txid,
          amount: item.price,
          timestamp: Date.now()
        })
      });

if (response.ok) {
        console.log(`${item.name} purchased for player ${playerId}`);
        alert(`🎮 ${item.name} added to your inventory!`);
      } else {
        throw new Error('Failed to award item');
      }
    } catch (error) {
      console.error('Purchase processing failed:', error);
      alert('Purchase completed but item delivery failed. Contact support.');
    }
  };

return (
    <div className="game-shop">
      <h2>🏪 Game Shop</h2>
      <p className="text-gray-600 mb-6">Buy items with Bitcoin SV</p>
      
      <div className="grid grid-cols-1 md:grid-cols-2 gap-4">
        {items.map((item) => (
          <div key={item.id} className="shop-item p-4 border rounded-lg bg-white shadow">
            <div className="flex items-center mb-2">
              <span className="text-2xl mr-2">{item.icon}</span>
              <div>
                <h3 className="font-bold">{item.name}</h3>
                <p className="text-sm text-gray-600">{item.description}</p>
              </div>
            </div>
            
            <div className="flex items-center justify-between">
              <span className="font-mono text-lg">
                {item.price.toLocaleString()} sats
              </span>
              
              <QuickSendButton 
                defaultAmount={item.price}
                defaultAddress={gamePaymentAddress}
                buttonText="Buy"
                size="small"
                variant="solid"
                onSuccess={(txid) => handleItemPurchase(item, txid)}
                onError={(error) => {
                  console.error(`Purchase failed for ${item.name}:`, error);
                  alert('Purchase failed. Please try again.');
                }}
                className="bg-green-600 hover:bg-green-700 text-white"
              />
            </div>
          </div>
        ))}
      </div>
      
      <div className="mt-6 p-4 bg-blue-50 border border-blue-200 rounded">
        <p className="text-sm text-blue-800">
          💡 <strong>Pro tip:</strong> Items are delivered instantly upon transaction confirmation. 
          All purchases are recorded on the Bitcoin SV blockchain for permanent ownership proof.
        </p>
      </div>
    </div>
  );
}
```

### Split Payment Interface

```tsx
import { QuickSendButton } from 'bigblocks';
import { useState } from 'react';

interface Recipient {
  name: string;
  address: string;
  percentage?: number;
}

interface SplitPaymentProps {
  recipients: Recipient[];
  totalAmount: number;
}

export default function SplitPayment({ recipients, totalAmount }: SplitPaymentProps) {
  const [selectedRecipients, setSelectedRecipients] = useState<Recipient[]>([]);
  
  const splitAmount = selectedRecipients.length > 0 
    ? Math.floor(totalAmount / selectedRecipients.length)
    : 0;

return (
    <div className="split-payment">
      <h3>Split Payment: {totalAmount.toLocaleString()} sats</h3>
      
      <div className="recipient-selection mb-4">
        <h4 className="mb-2">Select Recipients:</h4>
        {recipients.map((recipient) => (
          <label key={recipient.address} className="flex items-center mb-2">
            <input 
              type="checkbox"
              checked={selectedRecipients.some(r => r.address === recipient.address)}
              onChange={(e) => handleRecipientToggle(recipient, e.target.checked)}
              className="mr-2"
            />
            <span className="flex-1">
              {recipient.name}
            </span>
            <span className="text-sm text-gray-500 font-mono">
              {recipient.address.slice(0, 10)}...{recipient.address.slice(-6)}
            </span>
          </label>
        ))}
      </div>
      
      {selectedRecipients.length > 0 && (
        <div className="split-summary mb-4 p-3 bg-gray-50 rounded">
          <p><strong>Recipients:</strong> {selectedRecipients.length}</p>
          <p><strong>Amount per recipient:</strong> {splitAmount.toLocaleString()} sats</p>
          <p><strong>Total:</strong> {(splitAmount * selectedRecipients.length).toLocaleString()} sats</p>
        </div>
      )}
      
      <QuickSendButton 
        buttonText={selectedRecipients.length > 0 
          ? `Send to ${selectedRecipients.length} recipients`
          : 'Select recipients first'
        }
        disabled={selectedRecipients.length === 0}
        onSuccess={handleSplitPayment}
        onError={(error) => {
          console.error('Split payment failed:', error);
          alert('Split payment initiation failed. Please try again.');
        }}
        className="w-full bg-purple-600 hover:bg-purple-700 text-white font-semibold"
      />
    </div>
  );
}
```

### Subscription Payment

```tsx
import { QuickSendButton } from 'bigblocks';
import { useState } from 'react';

interface SubscriptionPlan {
  id: string;
  name: string;
  price: number; // monthly price in satoshis
  features: string[];
}

export default function SubscriptionPayment() {
  const [selectedPlan, setSelectedPlan] = useState<SubscriptionPlan | null>(null);
  
  const plans: SubscriptionPlan[] = [
    {
      id: 'basic',
      name: 'Basic Plan',
      price: 50000, // 50k satoshis/month
      features: ['Feature A', 'Feature B', 'Email Support']
    },
    {
      id: 'pro',
      name: 'Pro Plan', 
      price: 100000, // 100k satoshis/month
      features: ['Everything in Basic', 'Feature C', 'Feature D', 'Priority Support']
    },
    {
      id: 'enterprise',
      name: 'Enterprise Plan',
      price: 250000, // 250k satoshis/month  
      features: ['Everything in Pro', 'Custom Features', 'Dedicated Support']
    }
  ];

return (
    <div className="subscription-payment">
      <h2>Choose Your Plan</h2>
      
      <div className="grid grid-cols-1 md:grid-cols-3 gap-6 mb-6">
        {plans.map((plan) => (
          <div 
            key={plan.id}
            className={`plan-card p-6 border-2 rounded-lg cursor-pointer transition-all ${
              selectedPlan?.id === plan.id 
                ? 'border-blue-500 bg-blue-50' 
                : 'border-gray-200 hover:border-gray-300'
            }`}
            onClick={() => setSelectedPlan(plan)}
          >
            <h3 className="font-bold text-xl mb-2">{plan.name}</h3>
            <p className="text-2xl font-mono mb-4">
              {plan.price.toLocaleString()} sats/mo
            </p>
            
            <ul className="text-sm space-y-1">
              {plan.features.map((feature, index) => (
                <li key={index} className="flex items-center">
                  <span className="text-green-500 mr-2">✓</span>
                  {feature}
                </li>
              ))}
            </ul>
          </div>
        ))}
      </div>
      
      {selectedPlan && (
        <div className="selected-plan p-4 bg-blue-50 border border-blue-200 rounded mb-4">
          <h4>Selected: {selectedPlan.name}</h4>
          <p>Monthly payment: {selectedPlan.price.toLocaleString()} satoshis</p>
        </div>
      )}
      
      <QuickSendButton 
        defaultAmount={selectedPlan?.price}
        buttonText={selectedPlan 
          ? `Subscribe to ${selectedPlan.name}` 
          : 'Select a plan first'
        }
        disabled={!selectedPlan}
        onSuccess={(txid, amount) => handleSubscription(txid, amount)}
        onError={(error) => {
          console.error('Subscription payment failed:', error);
          alert('Payment failed. Please try again.');
        }}
        className="w-full bg-blue-600 hover:bg-blue-700 text-white font-bold py-3"
      />
      
      {selectedPlan && (
        <p className="text-sm text-gray-600 mt-2 text-center">
          By subscribing, you agree to monthly payments of {selectedPlan.price.toLocaleString()} satoshis. 
          Cancel anytime in your account settings.
        </p>
      )}
    </div>
  );
}
```

## Authentication Requirements

The QuickSendButton requires Bitcoin authentication context for wallet operations:

```tsx
import { 
  BitcoinAuthProvider, 
  BitcoinQueryProvider, 
  QuickSendButton 
} from 'bigblocks';

function App() {
  return (
    <BitcoinQueryProvider>
      <BitcoinAuthProvider config={{ 
        apiUrl: '/api',
        walletMode: 'integrated' // Enables wallet features
      }}>
        <QuickSendButton 
          buttonText="Send BSV"
          showBalanceHint={true}
        />
      </BitcoinAuthProvider>
    </BitcoinQueryProvider>
  );
}
```

## Features

* **Inline Modal Interface**: Quick popup form without full page navigation
* **Balance Validation**: Automatically checks sufficient funds before enabling send
* **Address Validation**: Validates Bitcoin addresses in real-time
* **Amount Formatting**: Smart satoshi/BSV conversion display
* **Transaction Status**: Real-time transaction broadcast status and confirmation
* **Error Handling**: User-friendly error messages with retry options
* **Keyboard Shortcuts**: ESC to close modal, Enter to send
* **Responsive Design**: Optimized for both mobile and desktop
* **Security**: Amount limits and address validation prevent errors

## Best Practices

1. **Clear Intent**: Use descriptive button text that explains what the payment is for
2. **Amount Validation**: Set reasonable max amounts to prevent accidental large sends
3. **Address Verification**: Always validate recipient addresses before enabling send
4. **Transaction Feedback**: Provide clear success/error feedback with transaction IDs
5. **Balance Awareness**: Show current balance to help users understand affordability
6. **Confirmation Steps**: For larger amounts, consider additional confirmation prompts

## Error Handling

### Comprehensive Error Management

```tsx
import { QuickSendButton } from 'bigblocks';

export default function RobustSendHandler() {
  const handleSendError = (error: string) => {
    console.error('Send failed:', error);
    
    if (error.includes('insufficient funds')) {
      // Show balance and suggest smaller amount
      alert('Insufficient balance. Please check your wallet balance and try a smaller amount.');
    } else if (error.includes('invalid address')) {
      // Address format error
      alert('Invalid recipient address. Please check the address format and try again.');
    } else if (error.includes('amount too small')) {
      // Below dust limit
      alert('Amount too small. Minimum send amount is 546 satoshis.');
    } else if (error.includes('network')) {
      // Network connectivity issues
      alert('Network error. Please check your connection and try again.');
    } else if (error.includes('rate limit')) {
      // Too many requests
      alert('Too many transactions. Please wait a moment and try again.');
    } else {
      // Generic error
      alert(`Transaction failed: ${error}`);
    }
  };

return (
    <QuickSendButton 
      onError={handleSendError}
      onSuccess={(txid, amount, address) => {
        console.log(`✅ Sent ${amount} satoshis to ${address}`);
        console.log(`Transaction: https://whatsonchain.com/tx/${txid}`);
        alert('Transaction sent successfully!');
      }}
      maxAmount={10000000} // 0.1 BSV maximum
      showBalanceHint={true}
    />
  );
}
```

## Security Considerations

### Amount Limits and Validation

```tsx
import { QuickSendButton } from 'bigblocks';

export default function SecureSendButton() {
  return (
    <div className="secure-send">
      <div className="security-notice mb-4 p-3 bg-yellow-50 border border-yellow-200 rounded">
        <p className="text-sm text-yellow-800">
          🔒 All transactions are signed with your private key and broadcast securely. 
          Maximum single transaction: 0.1 BSV.
        </p>
      </div>
      
      <QuickSendButton 
        maxAmount={10000000} // 0.1 BSV limit
        buttonText="🔐 Secure Send"
        onSuccess={(txid, amount, address) => {
          // Log transaction for audit trail
          fetch('/api/audit/transaction', {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({
              txid,
              amount,
              address,
              timestamp: Date.now(),
              userAgent: navigator.userAgent
            })
          });
          
          console.log('Secure transaction completed:', txid);
        }}
        onError={(error) => {
          // Log security-related errors
          if (error.includes('amount exceeds')) {
            console.warn('User attempted to exceed maximum amount');
          }
          console.error('Secure send failed:', error);
        }}
      />
    </div>
  );
}
```

## Troubleshooting

### Common Issues

**Button appears disabled/unresponsive**

* Ensure `BitcoinAuthProvider` is properly configured with wallet access
* Check that user has authenticated and unlocked their wallet
* Verify sufficient balance for minimum transaction (546 satoshis + fees)

**Modal doesn't open when clicked**

* Check for JavaScript errors in browser console
* Ensure required Bitcoin context providers are wrapped around the component
* Verify the component is not disabled via props

**Transactions fail with "insufficient funds"**

* User needs more BSV in their wallet
* Account for transaction fees (typically \~0.0001 BSV)
* Check if user has UTXOs available for spending

**Address validation errors**

* Ensure addresses are valid Bitcoin SV format
* Check for correct network (mainnet vs testnet)
* Verify addresses haven't been copy-pasted incorrectly

### Debug Mode

```tsx
import { QuickSendButton } from 'bigblocks';

export default function DebugSendButton() {
  const debugSend = (txid: string, amount: number, address: string) => {
    console.log('🐛 Debug send success:', {
      txid,
      amount,
      address,
      timestamp: new Date().toISOString(),
      userAgent: navigator.userAgent
    });
  };

const debugError = (error: string) => {
    console.error('🐛 Debug send error:', {
      error,
      timestamp: new Date().toISOString(),
      userAgent: navigator.userAgent
    });
  };

return (
    <div className="debug-send">
      <h3>Debug Mode Send</h3>
      <QuickSendButton 
        onSuccess={debugSend}
        onError={debugError}
        buttonText="🐛 Debug Send"
        showBalanceHint={true}
        className="border-2 border-gray-300"
      />
    </div>
  );
}
```

## Related Components

* [SendBSVButton](/docs/components/send-bsv-button) - Full-featured send interface
* [QuickDonateButton](/docs/components/quick-donate-button) - Quick donation interface
* [WalletOverview](/docs/components/wallet-overview) - Complete wallet display
* [CompactWalletOverview](/docs/components/compact-wallet-overview) - Compact wallet info

## API Reference

### QuickSendButton Component

```typescript
interface QuickSendButtonProps {
  onSuccess?: (txid: string, amount: number, address: string) => void;
  onError?: (error: string) => void;
  defaultAmount?: number;
  defaultAddress?: string;
  buttonText?: string;
  variant?: 'solid' | 'outline' | 'ghost';
  size?: 'small' | 'medium' | 'large';
  showBalanceHint?: boolean;
  maxAmount?: number;
  disabled?: boolean;
  className?: string;
}
```

### Usage with React Query

```typescript
import { useQuery, useMutation } from '@tanstack/react-query';
import { QuickSendButton } from 'bigblocks';

function QuickSendWithQuery() {
  // Query for wallet balance
  const { data: balance } = useQuery({
    queryKey: ['wallet-balance'],
    queryFn: () => fetch('/api/wallet/balance').then(res => res.json()),
    refetchInterval: 30000 // Refresh every 30 seconds
  });

// Mutation for sending transactions
  const sendMutation = useMutation({
    mutationFn: (sendData: { address: string; amount: number }) =>
      fetch('/api/wallet/send', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(sendData)
      }).then(res => res.json()),
    onSuccess: (data) => {
      console.log('Transaction sent:', data.txid);
    },
    onError: (error) => {
      console.error('Send failed:', error);
    }
  });

const maxSafeAmount = balance ? Math.floor(balance.satoshis * 0.9) : undefined;

return (
    <QuickSendButton 
      maxAmount={maxSafeAmount}
      showBalanceHint={true}
      onSuccess={(txid, amount, address) => {
        console.log('Success:', { txid, amount, address });
      }}
      onError={(error) => {
        console.error('Error:', error);
      }}
    />
  );
}
```

# SendBSVButton
URL: /docs/components/wallet/send-bsv-button

Send Bitcoin SV with a simple button interface. Handles transaction creation, signing, and broadcasting.

***

title: SendBSVButton
description: Send Bitcoin SV with a simple button interface. Handles transaction creation, signing, and broadcasting.
categories: \['payments', 'actions', 'wallet']
providers: \['BitcoinAuthProvider', 'BitcoinQueryProvider']
-----------------------------------------------------------

import { SendBSVButtonDemo } from '@/components/docs/demos/SendBSVButtonDemo'
import { ComponentBadges } from '@/components/docs/ComponentBadges'

SendBSVButton combines the [Radix Button primitive](https://www.radix-ui.com/themes/docs/components/button) and [Dialog primitive](https://www.radix-ui.com/themes/docs/components/dialog) with Bitcoin transaction logic, providing secure BSV sending with balance validation, fee calculation, and confirmation workflows.

## Installation

```bash
npm install bigblocks
```

## Usage

```tsx
import { SendBSVButton } from 'bigblocks';

export default function WalletActions() {
  return (
    <SendBSVButton
      recipientAddress="1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa"
      amount="0.001"
      onSuccess={(txid) => {
        console.log('Transaction sent:', txid);
      }}
    />
  );
}
```

## Props

| Prop               | Type                                        | Default      | Description                          |
| ------------------ | ------------------------------------------- | ------------ | ------------------------------------ |
| `recipientAddress` | `string`                                    | -            | Recipient Bitcoin address            |
| `amount`           | `string`                                    | -            | Amount in BSV to send                |
| `message`          | `string`                                    | -            | Optional transaction memo            |
| `walletData`       | `WalletUserExtension`                       | -            | Wallet data for transaction          |
| `disabled`         | `boolean`                                   | `false`      | Disable the button                   |
| `loading`          | `boolean`                                   | `false`      | Show loading state                   |
| `className`        | `string`                                    | -            | Additional CSS classes               |
| `variant`          | `'solid' \| 'soft' \| 'outline' \| 'ghost'` | `'solid'`    | Button style variant                 |
| `size`             | `'1' \| '2' \| '3' \| '4'`                  | `'2'`        | Button size                          |
| `maxAmount`        | `number`                                    | -            | Maximum send amount                  |
| `feeRate`          | `number`                                    | -            | Custom fee rate (sat/byte)           |
| `onSuccess`        | `(txid: string) => void`                    | -            | Success callback with transaction ID |
| `onError`          | `(error: Error) => void`                    | -            | Error callback                       |
| `buttonText`       | `string`                                    | `'Send BSV'` | Custom button label                  |
| `dialogTitle`      | `string`                                    | `'Send BSV'` | Dialog title                         |
| `showContacts`     | `boolean`                                   | `false`      | Show contacts selector               |

## Features

* **Transaction Building**: Automatic UTXO selection and fee calculation
* **Interactive Dialog**: User-friendly send interface with address/amount inputs
* **Contact Integration**: Optional contact selector for recipient addresses
* **Real-time Validation**: Address and amount validation with feedback
* **Fee Estimation**: Dynamic fee calculation based on transaction size
* **Error Handling**: Comprehensive error states with user guidance
* **Loading States**: Visual feedback during transaction processing
* **Confirmation Flow**: Built-in confirmation before broadcasting

## Examples

### Basic Send Button

```tsx
<SendBSVButton
  recipientAddress="1BitcoinAddress..."
  amount="0.01"
  onSuccess={(txid) => {
    toast.success(`Transaction sent! TXID: ${txid}`);
  }}
  onError={(error) => {
    toast.error(`Send failed: ${error.message}`);
  }}
/>
```

### Send with Message

```tsx
<SendBSVButton
  recipientAddress="1BitcoinAddress..."
  amount="0.001"
  message="Payment for coffee"
  onSuccess={(txid) => {
    console.log('Payment sent:', txid);
  }}
/>
```

### Interactive Send Dialog

```tsx
<SendBSVButton
  buttonText="Send Payment"
  dialogTitle="Send BSV Payment"
  showContacts={true}
  onSuccess={(txid) => {
    router.push(`/transactions/${txid}`);
  }}
/>
```

### Custom Styling

```tsx
<SendBSVButton
  recipientAddress={address}
  amount={amount}
  variant="outline"
  size="3"
  className="w-full"
  buttonText="Pay Invoice"
  onSuccess={handlePayment}
/>
```

### With Maximum Amount

```tsx
<SendBSVButton
  maxAmount={0.1}
  feeRate={1.5}
  onSuccess={(txid) => {
    console.log('Send completed:', txid);
  }}
  onError={(error) => {
    if (error.message.includes('insufficient')) {
      toast.error('Insufficient balance');
    } else {
      toast.error(error.message);
    }
  }}
/>
```

### In Payment Form

```tsx
function PaymentForm() {
  const [recipient, setRecipient] = useState('');
  const [amount, setAmount] = useState('');
  
  return (
    <div className="space-y-4">
      <input
        value={recipient}
        onChange={(e) => setRecipient(e.target.value)}
        placeholder="Recipient address"
        className="w-full p-2 border rounded"
      />
      <input
        type="number"
        value={amount}
        onChange={(e) => setAmount(e.target.value)}
        placeholder="Amount (BSV)"
        className="w-full p-2 border rounded"
      />
      <SendBSVButton
        recipientAddress={recipient}
        amount={amount}
        disabled={!recipient || !amount}
        buttonText="Send Payment"
        onSuccess={(txid) => {
          toast.success('Payment sent successfully!');
          setRecipient('');
          setAmount('');
        }}
      />
    </div>
  );
}
```

### With Wallet Integration

```tsx
import { useWallet, SendBSVButton } from 'bigblocks';

### Quick Send Variant

```tsx
import { QuickSendButton } from 'bigblocks';

<QuickSendButton
  amount="0.001"
  recipient="1BitcoinAddress..."
  variant="soft"
  size="1"
  onSuccess={(txid) => {
    console.log('Quick send completed:', txid);
  }}
/>
```

## Required Context

The component requires the following providers:

```tsx
import { 
  BitcoinAuthProvider, 
  BitcoinQueryProvider 
} from 'bigblocks';

function App() {
  return (
    <BitcoinAuthProvider>
      <BitcoinQueryProvider>
        <SendBSVButton
          recipientAddress="1Address..."
          amount="0.001"
          onSuccess={handleSuccess}
        />
      </BitcoinQueryProvider>
    </BitcoinAuthProvider>
  );
}
```

## API Integration

### Required Backend Endpoints

The component expects these API endpoints:

#### 1. Get Wallet Balance

```typescript
GET /api/wallet/balance

Response:
{
  confirmed: number;    // BSV amount
  unconfirmed: number;  // BSV amount
  total: number;        // BSV amount
  satoshis: {
    confirmed: number;
    unconfirmed: number;
    total: number;
  };
}
```

#### 2. Build Transaction

```typescript
POST /api/wallet/send

Request:
{
  recipientAddress: string;
  amount: string;       // BSV amount
  message?: string;     // Optional OP_RETURN memo
  feeRate?: number;     // Custom fee rate
}

Response:
{
  success: boolean;
  txid?: string;
  error?: string;
  fee?: number;
  size?: number;
}
```

#### 3. Get UTXOs

```typescript
GET /api/wallet/utxos

Response:
{
  utxos: Array<{
    txid: string;
    vout: number;
    satoshis: number;
    script: string;
    confirmed: boolean;
  }>;
  totalSatoshis: number;
}
```

### Authentication Headers

All wallet API calls require authentication:

```typescript
headers: {
  'X-Auth-Token': '<BSM signature>',
  'Content-Type': 'application/json'
}
```

## Error Handling

The component handles various error scenarios:

```tsx
<SendBSVButton
  recipientAddress={address}
  amount={amount}
  onError={(error) => {
    switch (error.message) {
      case 'INSUFFICIENT_FUNDS':
        toast.error('Not enough BSV to send');
        break;
      case 'INVALID_ADDRESS':
        toast.error('Invalid Bitcoin address');
        break;
      case 'AMOUNT_TOO_SMALL':
        toast.error('Amount below minimum threshold');
        break;
      case 'NETWORK_ERROR':
        toast.error('Network connection failed');
        break;
      default:
        toast.error(`Transaction failed: ${error.message}`);
    }
  }}
/>
```

## Security Considerations

* **Private Keys**: Never transmitted - signing happens client-side
* **Address Validation**: Both client and server-side validation
* **Amount Limits**: Configurable maximum send amounts
* **Confirmation Dialogs**: Prevent accidental transactions
* **Rate Limiting**: Backend protection against spam
* **UTXO Verification**: Server validates UTXO ownership

## Related Components

* [DonateButton](/docs/components/donate-button) - Accept donations
* [WalletOverview](/docs/components/wallet-overview) - Display balance
* [TokenBalance](/docs/components/token-balance) - Show token balances
* [QuickSendButton](/docs/components/quick-send-button) - Simplified send interface

# SimpleTokenBalance
URL: /docs/components/wallet/simple-token-balance

A lightweight, minimal token balance display component that shows cryptocurrency balances with clean formatting

***

title: SimpleTokenBalance
description: A lightweight, minimal token balance display component that shows cryptocurrency balances with clean formatting
category: wallet
----------------

A lightweight, minimal token balance display component that provides clean and customizable cryptocurrency balance formatting, perfect for compact UIs, dashboards, sidebar displays, and anywhere you need to show token balances without the overhead of a full wallet interface.

[View Component Preview →](/component-preview/simple-token-balance)

## Installation

```bash
npx bigblocks add simple-token-balance
```

## Import

```typescript
import { SimpleTokenBalance } from 'bigblocks';
```

## Props

| Prop               | Type                  | Required | Default | Description                               |
| ------------------ | --------------------- | -------- | ------- | ----------------------------------------- |
| symbol             | `string`              | Yes      | -       | Token symbol (BSV, PEPE, USD, etc.)       |
| balance            | `number`              | Yes      | -       | Balance amount to display                 |
| decimals           | `number`              | No       | `8`     | Number of decimal places to show          |
| showSymbol         | `boolean`             | No       | `true`  | Whether to show the token symbol          |
| prefix             | `string`              | No       | -       | Prefix character (e.g., "$", "€")         |
| suffix             | `string`              | No       | -       | Suffix text to append                     |
| loading            | `boolean`             | No       | `false` | Show loading state                        |
| error              | `string`              | No       | -       | Error message to display                  |
| onClick            | `() => void`          | No       | -       | Click handler for interactive balances    |
| compactNotation    | `boolean`             | No       | `false` | Use compact notation (1.23K, 1.23M)       |
| scientificNotation | `boolean`             | No       | `false` | Use scientific notation for small numbers |
| thousandsSeparator | `string`              | No       | `','`   | Thousands separator character             |
| decimalSeparator   | `string`              | No       | `'.'`   | Decimal separator character               |
| className          | `string`              | No       | -       | Additional CSS classes                    |
| style              | `React.CSSProperties` | No       | -       | Inline styles                             |

## Basic Usage

```tsx
import { SimpleTokenBalance } from 'bigblocks';

export default function WalletSidebar() {
  return (
    <div className="wallet-sidebar">
      <h3>Balances</h3>
      
      {/* Basic BSV balance */}
      <SimpleTokenBalance 
        symbol="BSV"
        balance={0.12345678}
        showSymbol={true}
      />
      
      {/* Token balance with custom formatting */}
      <SimpleTokenBalance 
        symbol="PEPE"
        balance={1000000}
        decimals={0}
        showSymbol={true}
        className="token-balance"
      />
      
      {/* USD value display */}
      <SimpleTokenBalance 
        symbol="USD"
        balance={45.67}
        decimals={2}
        prefix="$"
        showSymbol={false}
      />
    </div>
  );
}
```

## Advanced Usage

### Complete Balance Display System

```tsx
import { SimpleTokenBalance } from 'bigblocks';
import { useState, useEffect } from 'react';

interface TokenData {
  symbol: string;
  balance: number;
  usdValue?: number;
  change24h?: number;
}

export default function AdvancedTokenDisplay() {
  const [tokens, setTokens] = useState<TokenData[]>([]);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState<string | null>(null);

useEffect(() => {
    fetchTokenBalances();
  }, []);

if (loading) {
    return (
      <div className="token-display">
        <SimpleTokenBalance symbol="BSV" balance={0} loading={true} />
        <SimpleTokenBalance symbol="USD" balance={0} loading={true} />
      </div>
    );
  }

if (error) {
    return (
      <SimpleTokenBalance 
        symbol="BSV" 
        balance={0} 
        error={error}
        onClick={() => fetchTokenBalances()} // Retry on click
      />
    );
  }

return (
    <div className="advanced-token-display">
      <h2>Your Portfolio</h2>
      
      <div className="balance-grid">
        {tokens.map((token) => (
          <div key={token.symbol} className="balance-item">
            <SimpleTokenBalance 
              symbol={token.symbol}
              balance={token.balance}
              decimals={token.symbol === 'BSV' ? 8 : 0}
              onClick={() => handleBalanceClick(token.symbol)}
              className="hover:opacity-80 cursor-pointer"
            />
            
            {token.usdValue && (
              <SimpleTokenBalance 
                symbol="USD"
                balance={token.usdValue}
                decimals={2}
                prefix="$"
                showSymbol={false}
                className="text-sm text-gray-500"
              />
            )}
            
            {token.change24h && (
              <span className={`text-xs ${token.change24h >= 0 ? 'text-green-500' : 'text-red-500'}`}>
                {token.change24h >= 0 ? '+' : ''}{token.change24h.toFixed(2)}%
              </span>
            )}
          </div>
        ))}
      </div>
      
      <div className="total-value mt-4 pt-4 border-t">
        <span className="text-lg font-semibold">Total Value:</span>
        <SimpleTokenBalance 
          symbol="USD"
          balance={tokens.reduce((sum, t) => sum + (t.usdValue || 0), 0)}
          decimals={2}
          prefix="$"
          showSymbol={false}
          className="text-xl font-bold"
        />
      </div>
    </div>
  );
}
```

### Large Number Formatting

```tsx
import { SimpleTokenBalance } from 'bigblocks';

export default function LargeNumberExamples() {
  return (
    <div className="large-number-examples">
      <h3>Large Number Formatting</h3>
      
      {/* Compact notation for millions/billions */}
      <div className="example">
        <h4>Total Supply</h4>
        <SimpleTokenBalance 
          symbol="PEPE"
          balance={420690000000000}
          decimals={0}
          compactNotation={true} // Shows as "420.69T PEPE"
          className="text-2xl font-bold"
        />
      </div>
      
      {/* Scientific notation for very small amounts */}
      <div className="example">
        <h4>Dust Amount</h4>
        <SimpleTokenBalance 
          symbol="BSV"
          balance={0.00000546}
          scientificNotation={true} // Shows as "5.46e-6 BSV"
          className="font-mono text-sm"
        />
      </div>
      
      {/* Custom formatting for different regions */}
      <div className="example">
        <h4>European Format</h4>
        <SimpleTokenBalance 
          symbol="EUR"
          balance={1234567.89}
          decimals={2}
          thousandsSeparator="."
          decimalSeparator=","
          prefix="€"
          showSymbol={false} // Shows as "€1.234.567,89"
        />
      </div>
    </div>
  );
}
```

## Common Patterns

### Wallet Overview Widget

```tsx
import { SimpleTokenBalance } from 'bigblocks';
import { useWallet } from 'bigblocks/hooks';

export default function WalletWidget() {
  const { balances, isLoading, error, refetch } = useWallet();

return (
    <div className="wallet-widget">
      <div className="widget-header">
        <h3>Wallet</h3>
        <button onClick={refetch} className="refresh-btn">
          ↻
        </button>
      </div>
      
      <div className="balance-list">
        {/* Main BSV balance */}
        <div className="balance-row">
          <SimpleTokenBalance 
            symbol="BSV"
            balance={balances?.bsv || 0}
            loading={isLoading}
            error={error}
            onClick={() => window.location.href = '/wallet/bsv'}
            className="font-semibold"
          />
        </div>
        
        {/* USD equivalent */}
        <div className="balance-row">
          <span className="text-gray-500">≈</span>
          <SimpleTokenBalance 
            symbol="USD"
            balance={balances?.usdValue || 0}
            decimals={2}
            prefix="$"
            showSymbol={false}
            loading={isLoading}
            className="text-gray-600"
          />
        </div>
        
        {/* Additional tokens */}
        {balances?.tokens?.map((token) => (
          <div key={token.symbol} className="balance-row">
            <SimpleTokenBalance 
              symbol={token.symbol}
              balance={token.balance}
              decimals={token.decimals}
              loading={isLoading}
              onClick={() => window.location.href = `/wallet/token/${token.symbol}`}
            />
          </div>
        ))}
      </div>
      
      {error && (
        <button 
          onClick={refetch}
          className="retry-button text-sm text-blue-500 hover:underline"
        >
          Retry loading balances
        </button>
      )}
    </div>
  );
}
```

### Token Portfolio Display

```tsx
import { SimpleTokenBalance } from 'bigblocks';
import { useState } from 'react';

interface Token {
  symbol: string;
  name: string;
  balance: number;
  decimals: number;
  usdValue: number;
  icon?: string;
}

interface TokenPortfolioProps {
  tokens: Token[];
}

export default function TokenPortfolio({ tokens }: TokenPortfolioProps) {
  const [sortBy, setSortBy] = useState<'value' | 'balance' | 'symbol'>('value');
  const [filterZero, setFilterZero] = useState(true);

const processedTokens = tokens
    .filter(token => !filterZero || token.balance > 0)
    .sort((a, b) => {
      switch (sortBy) {
        case 'value': return b.usdValue - a.usdValue;
        case 'balance': return b.balance - a.balance;
        case 'symbol': return a.symbol.localeCompare(b.symbol);
        default: return 0;
      }
    });

const totalValue = processedTokens.reduce((sum, token) => sum + token.usdValue, 0);

return (
    <div className="token-portfolio">
      <div className="portfolio-header">
        <h2>Token Portfolio</h2>
        
        <div className="portfolio-controls">
          <select 
            value={sortBy} 
            onChange={(e) => setSortBy(e.target.value as any)}
            className="sort-select"
          >
            <option value="value">Sort by Value</option>
            <option value="balance">Sort by Balance</option>
            <option value="symbol">Sort by Symbol</option>
          </select>
          
          <label className="filter-checkbox">
            <input 
              type="checkbox"
              checked={filterZero}
              onChange={(e) => setFilterZero(e.target.checked)}
            />
            Hide zero balances
          </label>
        </div>
      </div>
      
      <div className="token-list">
        {processedTokens.map((token) => (
          <div key={token.symbol} className="token-item">
            <div className="token-info">
              {token.icon && <img src={token.icon} alt={token.symbol} className="token-icon" />}
              <div>
                <h4>{token.name}</h4>
                <span className="text-gray-500">{token.symbol}</span>
              </div>
            </div>
            
            <div className="token-balances">
              <SimpleTokenBalance 
                symbol={token.symbol}
                balance={token.balance}
                decimals={token.decimals}
                showSymbol={false}
                className="font-mono"
              />
              
              <SimpleTokenBalance 
                symbol="USD"
                balance={token.usdValue}
                decimals={2}
                prefix="$"
                showSymbol={false}
                className="text-gray-600"
              />
            </div>
          </div>
        ))}
      </div>
      
      <div className="portfolio-footer">
        <span className="text-lg font-semibold">Total Portfolio Value</span>
        <SimpleTokenBalance 
          symbol="USD"
          balance={totalValue}
          decimals={2}
          prefix="$"
          showSymbol={false}
          className="text-2xl font-bold text-green-600"
        />
      </div>
    </div>
  );
}
```

### Gaming Currency Display

```tsx
import { SimpleTokenBalance } from 'bigblocks';

interface GameCurrency {
  type: 'gold' | 'gems' | 'energy' | 'tickets';
  amount: number;
  icon: string;
}

interface GameWalletProps {
  currencies: GameCurrency[];
  playerLevel: number;
}

export default function GameWallet({ currencies, playerLevel }: GameWalletProps) {
  const getCurrencyConfig = (type: string) => {
    switch (type) {
      case 'gold':
        return { symbol: 'GOLD', icon: '🪙', decimals: 0, color: 'text-yellow-500' };
      case 'gems':
        return { symbol: 'GEMS', icon: '💎', decimals: 0, color: 'text-purple-500' };
      case 'energy':
        return { symbol: 'ENERGY', icon: '⚡', decimals: 0, color: 'text-blue-500' };
      case 'tickets':
        return { symbol: 'TIX', icon: '🎟️', decimals: 0, color: 'text-green-500' };
      default:
        return { symbol: type.toUpperCase(), icon: '🔷', decimals: 0, color: 'text-gray-500' };
    }
  };

return (
    <div className="game-wallet">
      <div className="player-info">
        <span className="text-sm text-gray-600">Level {playerLevel}</span>
      </div>
      
      <div className="currency-grid">
        {currencies.map((currency) => {
          const config = getCurrencyConfig(currency.type);
          
          return (
            <div key={currency.type} className="currency-item">
              <span className="currency-icon text-2xl">{config.icon}</span>
              
              <SimpleTokenBalance 
                symbol={config.symbol}
                balance={currency.amount}
                decimals={config.decimals}
                showSymbol={false}
                compactNotation={currency.amount > 9999}
                className={`font-bold ${config.color}`}
                onClick={() => {
                  console.log(`Clicked ${currency.type}: ${currency.amount}`);
                  // Show shop or exchange interface
                }}
              />
            </div>
          );
        })}
      </div>
      
      <div className="quick-actions">
        <button className="buy-more-btn">
          Buy More 💰
        </button>
      </div>
    </div>
  );
}
```

### Real-time Price Ticker

```tsx
import { SimpleTokenBalance } from 'bigblocks';
import { useState, useEffect } from 'react';

interface PriceData {
  symbol: string;
  price: number;
  change24h: number;
  volume24h: number;
}

export default function PriceTicker() {
  const [prices, setPrices] = useState<PriceData[]>([]);
  const [loading, setLoading] = useState(true);

useEffect(() => {
    // Initial fetch
    fetchPrices();
    
    // Update every 30 seconds
    const interval = setInterval(fetchPrices, 30000);
    
    return () => clearInterval(interval);
  }, []);

return (
    <div className="price-ticker">
      <div className="ticker-header">
        <h3>Market Prices</h3>
        <span className="update-indicator">● Live</span>
      </div>
      
      <div className="ticker-scroll">
        {prices.map((price) => (
          <div key={price.symbol} className="ticker-item">
            <div className="ticker-symbol">{price.symbol}</div>
            
            <SimpleTokenBalance 
              symbol="USD"
              balance={price.price}
              decimals={price.price < 1 ? 6 : 2}
              prefix="$"
              showSymbol={false}
              loading={loading}
              className="font-mono"
            />
            
            <div className={`ticker-change ${price.change24h >= 0 ? 'text-green-500' : 'text-red-500'}`}>
              {price.change24h >= 0 ? '▲' : '▼'} {Math.abs(price.change24h).toFixed(2)}%
            </div>
            
            <div className="ticker-volume">
              <span className="text-xs text-gray-500">Vol:</span>
              <SimpleTokenBalance 
                symbol="USD"
                balance={price.volume24h}
                decimals={0}
                prefix="$"
                showSymbol={false}
                compactNotation={true}
                className="text-xs"
              />
            </div>
          </div>
        ))}
      </div>
    </div>
  );
}
```

## Formatting Options

### Compact Notation for Large Numbers

```tsx
import { SimpleTokenBalance } from 'bigblocks';

export default function CompactNotationExamples() {
  return (
    <div className="compact-examples">
      {/* Thousands */}
      <SimpleTokenBalance 
        symbol="SATS"
        balance={12345}
        decimals={0}
        compactNotation={true} // Shows as "12.3K SATS"
      />
      
      {/* Millions */}
      <SimpleTokenBalance 
        symbol="PEPE"
        balance={123456789}
        decimals={0}
        compactNotation={true} // Shows as "123.5M PEPE"
      />
      
      {/* Billions */}
      <SimpleTokenBalance 
        symbol="SHIB"
        balance={1234567890123}
        decimals={0}
        compactNotation={true} // Shows as "1.23T SHIB"
      />
    </div>
  );
}
```

### Scientific Notation for Small Numbers

```tsx
import { SimpleTokenBalance } from 'bigblocks';

export default function ScientificNotationExamples() {
  return (
    <div className="scientific-examples">
      {/* Very small BSV amounts */}
      <SimpleTokenBalance 
        symbol="BSV"
        balance={0.00000123}
        scientificNotation={true} // Shows as "1.23e-6 BSV"
      />
      
      {/* Dust amounts */}
      <SimpleTokenBalance 
        symbol="BTC"
        balance={0.00000546}
        scientificNotation={true} // Shows as "5.46e-6 BTC"
      />
    </div>
  );
}
```

### Regional Number Formatting

```tsx
import { SimpleTokenBalance } from 'bigblocks';

export default function RegionalFormatting() {
  return (
    <div className="regional-formatting">
      {/* US Format (default) */}
      <SimpleTokenBalance 
        symbol="USD"
        balance={1234567.89}
        decimals={2}
        prefix="$"
        showSymbol={false} // Shows as "$1,234,567.89"
      />
      
      {/* European Format */}
      <SimpleTokenBalance 
        symbol="EUR"
        balance={1234567.89}
        decimals={2}
        thousandsSeparator="."
        decimalSeparator=","
        prefix="€"
        showSymbol={false} // Shows as "€1.234.567,89"
      />
      
      {/* Indian Format */}
      <SimpleTokenBalance 
        symbol="INR"
        balance={12345678.90}
        decimals={2}
        thousandsSeparator=","
        decimalSeparator="."
        prefix="₹"
        showSymbol={false}
        // Custom formatting would show as "₹1,23,45,678.90"
      />
    </div>
  );
}
```

## Authentication Requirements

SimpleTokenBalance is a display-only component and does not require authentication context. However, it's commonly used within authenticated components:

```tsx
import { 
  BitcoinAuthProvider, 
  BitcoinQueryProvider, 
  SimpleTokenBalance 
} from 'bigblocks';

function App() {
  // SimpleTokenBalance can be used without auth context
  return (
    <div>
      {/* Outside auth context - for public display */}
      <SimpleTokenBalance 
        symbol="BSV"
        balance={0.12345}
      />
      
      {/* Inside auth context - for authenticated balance display */}
      <BitcoinQueryProvider>
        <BitcoinAuthProvider config={{ apiUrl: '/api' }}>
          <AuthenticatedBalances />
        </BitcoinAuthProvider>
      </BitcoinQueryProvider>
    </div>
  );
}
```

## Features

* **Minimal Design**: Clean, unobtrusive balance display that fits anywhere
* **Smart Formatting**: Automatic number formatting with locale awareness
* **Loading States**: Built-in loading spinner and skeleton animations
* **Error Handling**: Graceful error display with optional retry
* **Click Interaction**: Optional click handler for balance interaction
* **Responsive Design**: Adapts to container width automatically
* **Theme Integration**: Inherits Bitcoin theme colors and typography
* **Accessibility**: Screen reader friendly with proper ARIA labels
* **Memory Efficient**: Minimal DOM footprint with memoized rendering

## Best Practices

1. **Consistent Decimals**: Use consistent decimal places for the same token type across your app
2. **Loading States**: Always provide loading states for async balance data
3. **Error Handling**: Gracefully handle and display balance loading errors
4. **Responsive Design**: Ensure balance displays work on mobile devices
5. **Currency Symbols**: Use standard currency symbols and token tickers
6. **Click Feedback**: Provide visual feedback when balances are clickable

## Styling

The component uses minimal styling and is designed to inherit from parent containers:

```css
/* Default styles applied to SimpleTokenBalance */
.simple-token-balance {
  display: inline-flex;
  align-items: center;
  gap: 0.25rem;
  font-variant-numeric: tabular-nums; /* Ensures numbers align properly */
}

/* Loading state animation */
.balance-loading {
  opacity: 0.6;
  animation: pulse 2s cubic-bezier(0.4, 0, 0.6, 1) infinite;
}

/* Error state styling */
.balance-error {
  color: var(--color-error, #ef4444);
  font-style: italic;
}

/* Clickable balance hover effect */
.balance-clickable {
  cursor: pointer;
  transition: opacity 0.2s ease-in-out;
}

.balance-clickable:hover {
  opacity: 0.8;
}

/* Skeleton loading animation */
@keyframes pulse {
  0%, 100% {
    opacity: 1;
  }
  50% {
    opacity: 0.5;
  }
}
```

## Performance Optimization

### Memoization for Large Lists

```tsx
import { SimpleTokenBalance } from 'bigblocks';
import { memo } from 'react';

// Memoized balance item for performance
const MemoizedBalanceItem = memo(({ token }: { token: TokenData }) => (
  <SimpleTokenBalance 
    symbol={token.symbol}
    balance={token.balance}
    decimals={token.decimals}
  />
));

export default function LargeTokenList({ tokens }: { tokens: TokenData[] }) {
  return (
    <div className="large-token-list">
      {tokens.map((token) => (
        <MemoizedBalanceItem key={token.symbol} token={token} />
      ))}
    </div>
  );
}
```

## Troubleshooting

### Common Issues

**Balance not updating**

* Ensure you're passing updated balance values as props
* Check that the component isn't memoized with stale data
* Verify data fetching is working correctly

**Formatting issues**

* Check decimal places match the token's standard (BSV uses 8, USD uses 2)
* Verify separator characters are appropriate for the locale
* Ensure numbers are valid JavaScript numbers, not strings

**Click handler not working**

* Verify onClick prop is passed correctly
* Check for event propagation issues in parent components
* Ensure the component isn't disabled or covered by other elements

**Loading state stuck**

* Check that loading prop is properly controlled
* Verify async operations complete and update state
* Look for errors in data fetching logic

## Related Components

* [TokenBalance](/docs/components/token-balance) - Full-featured token balance with charts
* [WalletOverview](/docs/components/wallet-overview) - Complete wallet interface
* [CompactWalletOverview](/docs/components/compact-wallet-overview) - Compact wallet display
* [QuickDonateButton](/docs/components/quick-donate-button) - Quick donation interface

## API Reference

### SimpleTokenBalance Component

```typescript
interface SimpleTokenBalanceProps {
  symbol: string;
  balance: number;
  decimals?: number;
  showSymbol?: boolean;
  prefix?: string;
  suffix?: string;
  loading?: boolean;
  error?: string;
  onClick?: () => void;
  compactNotation?: boolean;
  scientificNotation?: boolean;
  thousandsSeparator?: string;
  decimalSeparator?: string;
  className?: string;
  style?: React.CSSProperties;
}
```

### Usage with Custom Hooks

```typescript
import { SimpleTokenBalance } from 'bigblocks';
import { useTokenBalance } from './hooks/useTokenBalance';

function TokenBalanceWithHook({ tokenSymbol }: { tokenSymbol: string }) {
  const { balance, loading, error, refetch } = useTokenBalance(tokenSymbol);

return (
    <SimpleTokenBalance 
      symbol={tokenSymbol}
      balance={balance || 0}
      loading={loading}
      error={error}
      onClick={error ? refetch : undefined}
    />
  );
}
```

# TokenBalance
URL: /docs/components/wallet/token-balance

Display token balances with icons and formatted values for BSV20, BSV21, and other token standards.

***

title: TokenBalance
description: Display token balances with icons and formatted values for BSV20, BSV21, and other token standards.
----------------------------------------------------------------------------------------------------------------

Display token balances with icons and formatted values for BSV20, BSV21, and other token standards. Features real-time price data, portfolio tracking, and interactive token management.

[View TokenBalance examples →](/component-preview/token-balance)

## Installation

```bash
npm install bigblocks
```

## Usage

```tsx
import { TokenBalance } from 'bigblocks';

export default function WalletTokens() {
  const tokens = [
    {
      symbol: 'MNEE',
      name: 'MNEE Token',
      balance: { confirmed: '1000', unconfirmed: '0', total: '1000' },
      icon: '🪙',
      price: { bsv: 0.001, usd: 0.05 }
    },
    {
      symbol: 'SHUA',
      name: 'SHUA Token', 
      balance: { confirmed: '500', unconfirmed: '0', total: '500' },
      icon: '💎',
      price: { bsv: 0.002, usd: 0.10 }
    }
  ];

return (
    <TokenBalance
      tokens={tokens}
      onViewDetails={(token) => {
        router.push(`/tokens/${token.symbol}`);
      }}
      onSendToken={(token) => {
        setShowSendModal(token);
      }}
    />
  );
}
```

## Props

| Prop             | Type                                | Default | Description                 |
| ---------------- | ----------------------------------- | ------- | --------------------------- |
| `tokens`         | `TokenBalanceType[]`                | `[]`    | Array of token balances     |
| `showValues`     | `boolean`                           | `true`  | Show token values           |
| `onToggleValues` | `() => void`                        | -       | Toggle value visibility     |
| `onViewDetails`  | `(token: TokenBalanceType) => void` | -       | View token details callback |
| `onSendToken`    | `(token: TokenBalanceType) => void` | -       | Send token callback         |
| `currency`       | `'BSV' \| 'USD'`                    | `'BSV'` | Display currency            |
| `loading`        | `boolean`                           | `false` | Show loading state          |
| `className`      | `string`                            | -       | Additional CSS classes      |

### TokenBalanceType Interface

```typescript
interface TokenBalanceType {
  symbol: string;           // Token symbol (e.g., "MNEE")
  name: string;             // Full token name
  contractId?: string;      // Token contract identifier
  balance: {
    confirmed: string;      // Confirmed balance
    unconfirmed: string;    // Pending balance
    total: string;          // Total balance
  };
  decimals?: number;        // Decimal places
  icon?: string;            // Icon URL or emoji
  price?: {
    bsv: number;            // Price in BSV
    usd: number;            // Price in USD
    change24h?: number;     // 24h change percentage
  };
  value?: {
    bsv: number;            // Total value in BSV
    usd: number;            // Total value in USD
  };
  type?: 'BSV20' | 'BSV21' | 'BSV721' | 'custom';
}
```

## Features

* **Multi-Standard Support**: BSV20, BSV21, BSV721, and custom tokens
* **Real-time Pricing**: Live token prices in BSV and USD
* **Portfolio Value**: Calculate total portfolio worth
* **Interactive Actions**: Send, view details, and manage tokens
* **Privacy Controls**: Toggle value visibility
* **Loading States**: Skeleton loading for better UX
* **Responsive Design**: Mobile-optimized layout

## Examples

### Basic Token Display

```tsx
<TokenBalance
  tokens={[
    {
      symbol: 'MNEE',
      name: 'MNEE Token',
      balance: { confirmed: '1000000', unconfirmed: '0', total: '1000000' },
      icon: '🪙',
      decimals: 8
    }
  ]}
/>
```

### With Price Data

```tsx
<TokenBalance
  tokens={[
    {
      symbol: 'PEPE',
      name: 'PEPE Token',
      balance: { confirmed: '420000', unconfirmed: '0', total: '420000' },
      icon: '🐸',
      price: { bsv: 0.000001, usd: 0.00005, change24h: 15.3 },
      value: { bsv: 0.42, usd: 21.0 }
    }
  ]}
  currency="USD"
/>
```

### Interactive Token Management

```tsx
<TokenBalance
  tokens={userTokens}
  onViewDetails={(token) => {
    setSelectedToken(token);
    setShowDetailsModal(true);
  }}
  onSendToken={(token) => {
    setTokenToSend(token);
    setShowSendModal(true);
  }}
  onToggleValues={() => {
    setShowValues(!showValues);
  }}
  showValues={showValues}
/>
```

### Loading State

```tsx
<TokenBalance
  tokens={[]}
  loading={true}
/>
```

### Simple Version

```tsx
import { SimpleTokenBalance } from 'bigblocks';

<SimpleTokenBalance
  tokens={tokens}
  currency="BSV"
  className="compact-tokens"
/>
```

### Portfolio Overview

```tsx
function TokenPortfolio() {
  const [tokens, setTokens] = useState([]);
  const [totalValue, setTotalValue] = useState({ bsv: 0, usd: 0 });
  const [showValues, setShowValues] = useState(true);

useEffect(() => {
    const total = tokens.reduce((acc, token) => ({
      bsv: acc.bsv + (token.value?.bsv || 0),
      usd: acc.usd + (token.value?.usd || 0)
    }), { bsv: 0, usd: 0 });
    
    setTotalValue(total);
  }, [tokens]);

return (
    <div className="token-portfolio">
      <div className="portfolio-header">
        <h2>Token Portfolio</h2>
        <div className="total-value">
          <span className="value">
            {showValues ? `${totalValue.bsv.toFixed(8)} BSV` : '••••••••'}
          </span>
          <span className="usd-value">
            {showValues ? `$${totalValue.usd.toFixed(2)}` : '$••••'}
          </span>
        </div>
      </div>
      
      <TokenBalance
        tokens={tokens}
        showValues={showValues}
        onToggleValues={() => setShowValues(!showValues)}
        onViewDetails={(token) => {
          router.push(`/portfolio/token/${token.symbol}`);
        }}
        onSendToken={(token) => {
          router.push(`/send?token=${token.symbol}`);
        }}
      />
    </div>
  );
}
```

### Token Watchlist

```tsx
function TokenWatchlist() {
  const [watchedTokens, setWatchedTokens] = useState([]);
  const [priceAlerts, setPriceAlerts] = useState({});

return (
    <div className="token-watchlist">
      <h3>Watched Tokens</h3>
      
      <TokenBalance
        tokens={watchedTokens}
        onViewDetails={(token) => {
          // Show token details with price history
          showTokenAnalytics(token);
        }}
        onSendToken={(token) => {
          // Quick send for watched tokens
          quickSendToken(token);
        }}
      />
      
      {Object.entries(priceAlerts).map(([symbol, alert]) => (
        <div key={symbol} className="price-alert">
          🚨 {symbol} price {alert.type}: {alert.price}
        </div>
      ))}
    </div>
  );
}
```

### Multi-Wallet Token View

```tsx
function MultiWalletTokens() {
  const [wallets, setWallets] = useState([]);
  const [selectedWallet, setSelectedWallet] = useState(0);

return (
    <div className="multi-wallet-tokens">
      <div className="wallet-selector">
        {wallets.map((wallet, index) => (
          <button
            key={index}
            onClick={() => setSelectedWallet(index)}
            className={selectedWallet === index ? 'active' : ''}
          >
            {wallet.name}
          </button>
        ))}
      </div>
      
      <TokenBalance
        tokens={wallets[selectedWallet]?.tokens || []}
        onViewDetails={(token) => {
          // Show token details for selected wallet
          showWalletTokenDetails(selectedWallet, token);
        }}
        onSendToken={(token) => {
          // Send from selected wallet
          sendFromWallet(selectedWallet, token);
        }}
      />
    </div>
  );
}
```

### Token Trading Interface

```tsx
function TokenTradingInterface() {
  const [tokens, setTokens] = useState([]);
  const [marketData, setMarketData] = useState({});

return (
    <div className="token-trading">
      <TokenBalance
        tokens={tokens.map(token => ({
          ...token,
          // Add market data
          price: marketData[token.symbol]?.price,
          value: {
            bsv: parseFloat(token.balance.total) * (marketData[token.symbol]?.price?.bsv || 0),
            usd: parseFloat(token.balance.total) * (marketData[token.symbol]?.price?.usd || 0)
          }
        }))}
        onViewDetails={(token) => {
          // Show trading view
          router.push(`/trade/${token.symbol}`);
        }}
        onSendToken={(token) => {
          // Quick sell option
          setTokenToSell(token);
          setShowSellModal(true);
        }}
      />
    </div>
  );
}
```

## Required Context

The component requires the following providers:

```tsx
import { 
  BitcoinAuthProvider, 
  BitcoinQueryProvider 
} from 'bigblocks';

function App() {
  return (
    <BitcoinAuthProvider>
      <BitcoinQueryProvider>
        <TokenBalance
          tokens={tokens}
          onViewDetails={handleViewDetails}
          onSendToken={handleSendToken}
        />
      </BitcoinQueryProvider>
    </BitcoinAuthProvider>
  );
}
```

## API Integration

### Required Backend Endpoints

The component expects these API endpoints:

#### 1. Get Token Balances

```typescript
GET /api/wallet/tokens?address=<address>

Response:
{
  tokens: Array<{
    symbol: string;
    name: string;
    contractId: string;
    balance: {
      confirmed: string;
      unconfirmed: string;
      total: string;
    };
    decimals: number;
    icon?: string;
    type: 'BSV20' | 'BSV21' | 'BSV721';
  }>;
  totalValue: {
    bsv: number;
    usd: number;
  };
}
```

#### 2. Get Token Prices

```typescript
GET /api/tokens/prices?symbols=<symbol1,symbol2>

Response:
{
  prices: {
    [symbol: string]: {
      bsv: number;
      usd: number;
      change24h: number;
      volume24h: number;
    };
  };
  lastUpdated: number;
}
```

#### 3. Get Token Details

```typescript
GET /api/tokens/{symbol}/details

Response:
{
  token: {
    symbol: string;
    name: string;
    description: string;
    contractId: string;
    type: string;
    decimals: number;
    totalSupply: string;
    website?: string;
    social?: object;
  };
  market: {
    price: TokenPrice;
    marketCap: number;
    volume24h: number;
    holders: number;
  };
}
```

### Authentication Headers

For authenticated token operations:

```typescript
headers: {
  'X-Auth-Token': '<BSM signature>',
  'Content-Type': 'application/json'
}
```

## Token Standards

### BSV20 Tokens

Fungible tokens following the BSV20 standard:

```typescript
{
  type: 'BSV20',
  symbol: 'MNEE',
  name: 'MNEE Token',
  decimals: 8,
  totalSupply: '21000000'
}
```

### BSV21 Tokens

Enhanced tokens with metadata:

```typescript
{
  type: 'BSV21',
  symbol: 'SHUA',
  name: 'SHUA Token',
  decimals: 8,
  metadata: {
    description: 'Community token',
    image: 'https://example.com/icon.png',
    website: 'https://shua.com'
  }
}
```

### BSV721 NFTs

Non-fungible tokens:

```typescript
{
  type: 'BSV721',
  contractId: 'collection-123',
  tokenId: 'nft-456',
  name: 'Rare Art #456',
  metadata: {
    image: 'https://example.com/nft-456.png',
    attributes: [
      { trait_type: 'Color', value: 'Blue' },
      { trait_type: 'Rarity', value: 'Legendary' }
    ]
  }
}
```

## Real-time Updates

### WebSocket Integration

```tsx
function LiveTokenBalance() {
  const [tokens, setTokens] = useState([]);

useEffect(() => {
    const ws = new WebSocket('/api/wallet/tokens/stream');
    
    ws.onmessage = (event) => {
      const data = JSON.parse(event.data);
      
      switch (data.type) {
        case 'balance_updated':
          setTokens(prev => 
            prev.map(token => 
              token.symbol === data.symbol 
                ? { ...token, balance: data.balance }
                : token
            )
          );
          break;
          
        case 'price_updated':
          setTokens(prev => 
            prev.map(token => 
              token.symbol === data.symbol 
                ? { ...token, price: data.price }
                : token
            )
          );
          break;
      }
    };

return () => ws.close();
  }, []);

return (
    <TokenBalance
      tokens={tokens}
      onViewDetails={handleViewDetails}
      onSendToken={handleSendToken}
    />
  );
}
```

## Performance Considerations

* **Lazy Loading**: Load token prices on demand
* **Caching**: Cache token data and prices
* **Debounced Updates**: Prevent excessive re-renders
* **Virtual Scrolling**: Handle large token lists efficiently

## Error Handling

### Common Error Scenarios

```tsx
function RobustTokenBalance() {
  const [tokens, setTokens] = useState([]);
  const [error, setError] = useState(null);
  const [retrying, setRetrying] = useState(false);

if (error) {
    return (
      <div className="token-error">
        <p>Failed to load tokens: {error}</p>
        <button onClick={retryTokenLoad} disabled={retrying}>
          {retrying ? 'Retrying...' : 'Retry'}
        </button>
      </div>
    );
  }

return (
    <TokenBalance
      tokens={tokens}
      onViewDetails={handleViewDetails}
      onSendToken={handleSendToken}
    />
  );
}
```

## Related Components

* [SimpleTokenBalance](/docs/components/simple-token-balance) - Minimal token display
* [WalletOverview](/docs/components/wallet-overview) - Complete wallet dashboard
* [SendBSVButton](/docs/components/send-bsv-button) - Send BSV transactions
* [MarketTable](/docs/components/market-table) - Token trading interface

# WalletOverview
URL: /docs/components/wallet/wallet-overview

Display comprehensive wallet information including balance, recent transactions, and quick actions.

***

title: WalletOverview
description: Display comprehensive wallet information including balance, recent transactions, and quick actions.
----------------------------------------------------------------------------------------------------------------

Display comprehensive wallet information including balance, recent transactions, and quick actions. A complete wallet dashboard component with BSV/USD conversion and interactive elements.

[View WalletOverview examples →](/component-preview/wallet-overview)

## Installation

```bash
npm install bigblocks
```

## Usage

```tsx
import { WalletOverview } from 'bigblocks';

export default function WalletPage() {
  return (
    <WalletOverview
      balance={{
        confirmed: 150000000, // 1.5 BSV in satoshis
        unconfirmed: 0,
        total: 150000000
      }}
      onSend={() => console.log('Send clicked')}
      onReceive={() => console.log('Receive clicked')}
    />
  );
}
```

## Props

| Prop              | Type             | Default | Description                             |
| ----------------- | ---------------- | ------- | --------------------------------------- |
| `balance`         | `BSVBalance`     | -       | Wallet balance information              |
| `showValues`      | `boolean`        | `true`  | Show balance values                     |
| `currency`        | `'BSV' \| 'USD'` | `'BSV'` | Display currency                        |
| `exchangeRate`    | `number`         | -       | BSV/USD exchange rate                   |
| `previousBalance` | `number`         | -       | Previous balance for change calculation |
| `loading`         | `boolean`        | `false` | Show loading state                      |
| `onSend`          | `() => void`     | -       | Send button callback                    |
| `onReceive`       | `() => void`     | -       | Receive button callback                 |
| `onBuy`           | `() => void`     | -       | Buy BSV button callback                 |
| `onSettings`      | `() => void`     | -       | Settings button callback                |
| `className`       | `string`         | -       | Additional CSS classes                  |

### BSVBalance Interface

```typescript
interface BSVBalance {
  confirmed: number;      // Confirmed satoshis
  unconfirmed: number;    // Pending satoshis
  total: number;          // Total satoshis
}
```

## Features

* **Balance Display**: Confirmed, pending, and total amounts
* **Currency Conversion**: BSV ⟷ USD with live exchange rates
* **Balance Change**: Visual indicators for balance changes
* **Quick Actions**: Send, Receive, Buy, and Settings buttons
* **Loading States**: Skeleton loading while fetching data
* **Responsive Design**: Mobile-optimized layout
* **Privacy Mode**: Toggle balance visibility

## Examples

### Basic Wallet Overview

```tsx
<WalletOverview
  balance={{
    confirmed: 100000000, // 1.0 BSV
    unconfirmed: 0,
    total: 100000000
  }}
  onSend={() => setShowSendModal(true)}
  onReceive={() => setShowReceiveModal(true)}
/>
```

### With USD Display

```tsx
<WalletOverview
  balance={{
    confirmed: 150000000, // 1.5 BSV
    unconfirmed: 0,
    total: 150000000
  }}
  currency="USD"
  exchangeRate={50.25} // $50.25 per BSV
  onSend={handleSend}
  onBuy={handleBuy}
/>
```

### With Pending Balance

```tsx
<WalletOverview
  balance={{
    confirmed: 100000000,  // 1.0 BSV confirmed
    unconfirmed: 50000000, // 0.5 BSV pending
    total: 150000000       // 1.5 BSV total
  }}
  previousBalance={100000000} // Show +0.5 BSV change
  onReceive={handleReceive}
/>
```

### Loading State

```tsx
<WalletOverview
  loading={true}
  onSend={handleSend}
  onReceive={handleReceive}
/>
```

### Compact Version

```tsx
import { CompactWalletOverview } from 'bigblocks';

<CompactWalletOverview
  balance={{
    confirmed: 75000000,
    unconfirmed: 0,
    total: 75000000
  }}
  currency="USD"
  exchangeRate={48.50}
/>
```

### Complete Dashboard

```tsx
function WalletDashboard() {
  const [balance, setBalance] = useState(null);
  const [loading, setLoading] = useState(true);
  const [currency, setCurrency] = useState('BSV');
  const [showValues, setShowValues] = useState(true);

useEffect(() => {
    fetchWalletBalance().then(setBalance).finally(() => setLoading(false));
  }, []);

return (
    <div className="wallet-dashboard">
      <div className="header">
        <h1>My Wallet</h1>
        <div className="controls">
          <button onClick={() => setCurrency(currency === 'BSV' ? 'USD' : 'BSV')}>
            Switch to {currency === 'BSV' ? 'USD' : 'BSV'}
          </button>
          <button onClick={() => setShowValues(!showValues)}>
            {showValues ? 'Hide' : 'Show'} Values
          </button>
        </div>
      </div>
      
      <WalletOverview
        balance={balance}
        loading={loading}
        currency={currency}
        showValues={showValues}
        exchangeRate={50.0}
        onSend={() => router.push('/send')}
        onReceive={() => router.push('/receive')}
        onBuy={() => router.push('/buy')}
        onSettings={() => router.push('/settings')}
        className="main-wallet"
      />
    </div>
  );
}
```

### Multi-Wallet View

```tsx
function MultiWalletView() {
  const wallets = [
    { id: 'main', name: 'Main Wallet', balance: { confirmed: 200000000, unconfirmed: 0, total: 200000000 } },
    { id: 'savings', name: 'Savings', balance: { confirmed: 500000000, unconfirmed: 0, total: 500000000 } },
    { id: 'business', name: 'Business', balance: { confirmed: 100000000, unconfirmed: 25000000, total: 125000000 } }
  ];

return (
    <div className="multi-wallet">
      {wallets.map(wallet => (
        <div key={wallet.id} className="wallet-card">
          <h3>{wallet.name}</h3>
          <WalletOverview
            balance={wallet.balance}
            currency="BSV"
            onSend={() => handleSend(wallet.id)}
            onReceive={() => handleReceive(wallet.id)}
            className="compact"
          />
        </div>
      ))}
    </div>
  );
}
```

### With Real-time Updates

```tsx
function LiveWalletOverview() {
  const [balance, setBalance] = useState(null);
  const [exchangeRate, setExchangeRate] = useState(50.0);

// WebSocket for real-time balance updates
  useEffect(() => {
    const ws = new WebSocket('/api/wallet/stream');
    
    ws.onmessage = (event) => {
      const data = JSON.parse(event.data);
      if (data.type === 'balance_updated') {
        setBalance(data.balance);
      } else if (data.type === 'exchange_rate_updated') {
        setExchangeRate(data.rate);
      }
    };

return () => ws.close();
  }, []);

return (
    <WalletOverview
      balance={balance}
      exchangeRate={exchangeRate}
      currency="USD"
      onSend={handleSend}
      onReceive={handleReceive}
    />
  );
}
```

### Enterprise Wallet

```tsx
function EnterpriseWallet() {
  const [walletData, setWalletData] = useState(null);
  const [permissions, setPermissions] = useState({});

return (
    <div className="enterprise-wallet">
      <WalletOverview
        balance={walletData?.balance}
        currency="USD"
        exchangeRate={walletData?.exchangeRate}
        onSend={permissions.canSend ? handleSend : undefined}
        onReceive={handleReceive}
        onBuy={permissions.canBuy ? handleBuy : undefined}
        onSettings={permissions.isAdmin ? handleSettings : undefined}
        className="enterprise-style"
      />
      
      {!permissions.canSend && (
        <div className="permission-notice">
          Contact administrator for send permissions
        </div>
      )}
    </div>
  );
}
```

## Required Context

The component requires the following providers:

```tsx
import { 
  BitcoinAuthProvider, 
  BitcoinQueryProvider 
} from 'bigblocks';

function App() {
  return (
    <BitcoinAuthProvider>
      <BitcoinQueryProvider>
        <WalletOverview
          balance={balance}
          onSend={handleSend}
          onReceive={handleReceive}
        />
      </BitcoinQueryProvider>
    </BitcoinAuthProvider>
  );
}
```

## API Integration

### Required Backend Endpoints

The component expects these API endpoints:

#### 1. Get Wallet Balance

```typescript
GET /api/wallet/balance

Response:
{
  confirmed: number;      // Confirmed satoshis
  unconfirmed: number;    // Pending satoshis
  total: number;          // Total satoshis
  bsv: {
    confirmed: string;    // BSV amount "1.50000000"
    unconfirmed: string;
    total: string;
  };
  usd?: {
    confirmed: string;    // USD value "$75.00"
    unconfirmed: string;
    total: string;
    rate: number;         // Exchange rate
  };
  lastUpdated: number;    // Timestamp
}
```

#### 2. Get Exchange Rate

```typescript
GET /api/wallet/exchange-rate?currency=USD

Response:
{
  currency: 'USD';
  rate: number;           // BSV price in USD
  timestamp: number;
  change24h: number;      // 24h change percentage
  source: string;         // Rate provider
}
```

#### 3. Real-time Updates

```typescript
// WebSocket connection
WS /api/wallet/stream

Events:
- balance_updated: { balance: BSVBalance }
- exchange_rate_updated: { rate: number, currency: string }
- transaction_received: { amount: number, txid: string }
```

### Authentication Headers

For authenticated requests:

```typescript
headers: {
  'X-Auth-Token': '<BSM signature>',
  'Content-Type': 'application/json'
}
```

## Currency Conversion

### BSV ⟷ USD Conversion

```tsx
function CurrencyConverter() {
  const [amount, setAmount] = useState(1.0);
  const [fromCurrency, setFromCurrency] = useState('BSV');
  const exchangeRate = 50.25; // $50.25 per BSV

const convertedAmount = fromCurrency === 'BSV' 
    ? amount * exchangeRate 
    : amount / exchangeRate;

return (
    <div className="converter">
      <WalletOverview
        balance={{
          confirmed: amount * 100000000, // Convert BSV to satoshis
          unconfirmed: 0,
          total: amount * 100000000
        }}
        currency={fromCurrency === 'BSV' ? 'USD' : 'BSV'}
        exchangeRate={exchangeRate}
      />
      
      <div className="conversion-info">
        {amount} {fromCurrency} = {convertedAmount.toFixed(8)} {fromCurrency === 'BSV' ? 'USD' : 'BSV'}
      </div>
    </div>
  );
}
```

## Privacy Features

### Balance Visibility Toggle

```tsx
function PrivateWallet() {
  const [showBalance, setShowBalance] = useState(false);

return (
    <div className="private-wallet">
      <div className="privacy-controls">
        <button onClick={() => setShowBalance(!showBalance)}>
          {showBalance ? '👁️ Hide' : '👁️‍🗨️ Show'} Balance
        </button>
      </div>
      
      <WalletOverview
        balance={balance}
        showValues={showBalance}
        onSend={handleSend}
        onReceive={handleReceive}
      />
    </div>
  );
}
```

## Styling Customization

### Custom Themes

```tsx
// Dark theme
<WalletOverview
  balance={balance}
  className="bg-gray-900 text-white border-gray-700"
  onSend={handleSend}
/>

// Colorful theme
<WalletOverview
  balance={balance}
  className="bg-gradient-to-r from-purple-500 to-pink-500 text-white"
  onSend={handleSend}
/>

// Minimal theme
<WalletOverview
  balance={balance}
  className="border-none shadow-none bg-transparent"
  onSend={handleSend}
/>
```

## Performance Considerations

* **Balance Caching**: Cache balance data for 30 seconds
* **Exchange Rate**: Update rates every 5 minutes
* **Debounced Updates**: Prevent excessive API calls
* **Skeleton Loading**: Show placeholders while loading

## Error Handling

### Common Error Scenarios

```tsx
function RobustWalletOverview() {
  const [balance, setBalance] = useState(null);
  const [error, setError] = useState(null);
  const [loading, setLoading] = useState(true);

useEffect(() => {
    fetchBalance()
      .then(setBalance)
      .catch(setError)
      .finally(() => setLoading(false));
  }, []);

if (error) {
    return (
      <div className="wallet-error">
        <p>Failed to load wallet: {error.message}</p>
        <button onClick={() => window.location.reload()}>
          Retry
        </button>
      </div>
    );
  }

return (
    <WalletOverview
      balance={balance}
      loading={loading}
      onSend={handleSend}
      onReceive={handleReceive}
    />
  );
}
```

## Related Components

* [CompactWalletOverview](/docs/components/compact-wallet-overview) - Minimal wallet display
* [SendBSVButton](/docs/components/send-bsv-button) - Send functionality
* [TokenBalance](/docs/components/token-balance) - Token balances
* [SimpleTokenBalance](/docs/components/simple-token-balance) - Basic token display

# YoursWalletConnector
URL: /docs/components/wallet/yours-wallet-connector

Connect to Yours Wallet browser extension for Bitcoin SV transactions and identity management.

***

title: YoursWalletConnector
description: Connect to Yours Wallet browser extension for Bitcoin SV transactions and identity management.
-----------------------------------------------------------------------------------------------------------

Connect to Yours Wallet browser extension for Bitcoin SV transactions and identity management. Provides a complete UI for wallet detection, connection management, and error handling.

[View YoursWalletConnector examples →](/component-preview/yours-wallet-connector)

## Installation

```bash
npm install bigblocks
```

## Usage

```tsx
import { YoursWalletConnector } from 'bigblocks';

export default function WalletConnect() {
  return (
    <YoursWalletConnector
      onSuccess={(result) => {
        console.log('Connected to Yours Wallet:', result.publicKey);
      }}
      onError={(error) => {
        console.error('Connection failed:', error);
      }}
    />
  );
}
```

## Props

| Prop        | Type                             | Default | Description                       |
| ----------- | -------------------------------- | ------- | --------------------------------- |
| `onSuccess` | `(result: WalletResult) => void` | -       | Success callback with wallet data |
| `onError`   | `(error: string) => void`        | -       | Error callback with error message |
| `className` | `string`                         | -       | Additional CSS classes            |

### WalletResult Interface

```typescript
interface WalletResult {
  publicKey: string;          // Wallet public key
  idKey?: string;             // Optional identity key
  encryptedBackup?: string;   // Optional encrypted backup data
}
```

## Features

* **Extension Detection**: Automatically detects Yours Wallet installation
* **Installation Prompts**: Guides users to install extension if missing
* **Connection Management**: Handles wallet connection flow
* **Error Handling**: Comprehensive error messages and recovery options
* **Loading States**: Visual feedback during connection process
* **Security**: Secure authentication with cryptographic signatures

## Examples

### Basic Connection

```tsx
<YoursWalletConnector
  onSuccess={(result) => {
    console.log('Wallet connected!');
    console.log('Public Key:', result.publicKey);
    if (result.idKey) {
      console.log('Identity Key:', result.idKey);
    }
  }}
/>
```

### With Error Handling

```tsx
<YoursWalletConnector
  onSuccess={(result) => {
    // Store wallet connection
    setWalletConnected(true);
    setPublicKey(result.publicKey);
    
    // Navigate to dashboard
    router.push('/dashboard');
  }}
  onError={(error) => {
    switch (error) {
      case 'EXTENSION_NOT_FOUND':
        toast.error('Please install Yours Wallet extension');
        break;
      case 'WALLET_LOCKED':
        toast.error('Please unlock your Yours Wallet');
        break;
      case 'CONNECTION_REFUSED':
        toast.error('Connection was refused');
        break;
      default:
        toast.error(`Connection failed: ${error}`);
    }
  }}
/>
```

### Custom Styling

```tsx
<YoursWalletConnector
  className="w-full max-w-md mx-auto"
  onSuccess={(result) => {
    console.log('Connected successfully');
  }}
/>
```

### In Authentication Flow

```tsx
function WalletAuthPage() {
  const [isConnecting, setIsConnecting] = useState(false);
  const [walletData, setWalletData] = useState(null);

return (
    <div className="auth-container">
      <h1>Connect Your Wallet</h1>
      <p>Connect your Yours Wallet to get started</p>
      
      <YoursWalletConnector
        onSuccess={(result) => {
          setWalletData(result);
          setIsConnecting(false);
          
          // Create session or redirect
          createWalletSession(result);
        }}
        onError={(error) => {
          setIsConnecting(false);
          setError(error);
        }}
      />
      
      {walletData && (
        <div className="success-message">
          ✅ Wallet connected successfully!
        </div>
      )}
    </div>
  );
}
```

### With Backup Integration

```tsx
import { YoursWalletConnector, BackupManager } from 'bigblocks';

function WalletSetup() {
  const [backupCreated, setBackupCreated] = useState(false);

return (
    <div className="space-y-6">
      <YoursWalletConnector
        onSuccess={async (result) => {
          console.log('Wallet connected:', result.publicKey);
          
          // Check if backup exists
          if (result.encryptedBackup) {
            console.log('Backup found, restoring...');
            await restoreFromBackup(result.encryptedBackup);
          } else {
            console.log('No backup found, creating new identity...');
          }
        }}
      />
      
      {backupCreated && (
        <BackupManager
          onBackupCreated={(backup) => {
            console.log('Backup created and saved');
          }}
        />
      )}
    </div>
  );
}
```

## Required Context

The component requires the following providers:

```tsx
import { 
  BitcoinAuthProvider, 
  BitcoinQueryProvider 
} from 'bigblocks';

function App() {
  return (
    <BitcoinAuthProvider>
      <BitcoinQueryProvider>
        <YoursWalletConnector
          onSuccess={handleWalletConnection}
          onError={handleConnectionError}
        />
      </BitcoinQueryProvider>
    </BitcoinAuthProvider>
  );
}
```

## Browser Extension Requirements

### Yours Wallet Extension

The component requires the Yours Wallet browser extension:

1. **Chrome Web Store**: Search for "Yours Wallet"
2. **Firefox Add-ons**: Available on Mozilla Add-ons
3. **Minimum Version**: v1.0.0 or higher

### Extension Permissions

The following permissions are requested:

* **Active Tab**: Access to current webpage
* **Storage**: Local wallet data storage
* **Web Requests**: Bitcoin network requests
* **Cryptography**: Transaction signing

## API Integration

### Required Backend Endpoints

The component expects these API endpoints for full functionality:

#### 1. Verify Wallet Connection

```typescript
POST /api/auth/yours-wallet/verify

Request:
{
  publicKey: string;
  signature: string;
  message: string;
  timestamp: number;
}

Response:
{
  success: boolean;
  walletId: string;
  verified: boolean;
  session?: {
    token: string;
    expiresAt: number;
  };
}
```

#### 2. Store Wallet Session

```typescript
POST /api/auth/yours-wallet/session

Request:
{
  publicKey: string;
  walletId: string;
  signature: string;
  metadata?: {
    userAgent: string;
    extensionVersion: string;
  };
}

Response:
{
  sessionId: string;
  token: string;
  expiresAt: number;
}
```

#### 3. Get Wallet Info

```typescript
GET /api/wallets/yours-wallet/info?publicKey=<key>

Response:
{
  address: string;
  balance: {
    confirmed: number;
    unconfirmed: number;
    total: number;
  };
  hasBackup: boolean;
  lastActivity: number;
}
```

### Authentication Headers

For authenticated requests after connection:

```typescript
headers: {
  'X-Auth-Token': '<BSM signature>',
  'X-Wallet-Type': 'yours',
  'X-Public-Key': '<wallet public key>',
  'Content-Type': 'application/json'
}
```

## Error Handling

The component handles various error scenarios:

### Common Errors

| Error Code            | Description                   | User Action       |
| --------------------- | ----------------------------- | ----------------- |
| `EXTENSION_NOT_FOUND` | Yours Wallet not installed    | Install extension |
| `WALLET_LOCKED`       | Wallet is locked              | Unlock wallet     |
| `CONNECTION_REFUSED`  | User denied connection        | Try again         |
| `NETWORK_ERROR`       | Network connectivity issues   | Check connection  |
| `INVALID_SIGNATURE`   | Signature verification failed | Reconnect wallet  |
| `SESSION_EXPIRED`     | Wallet session expired        | Reconnect         |

### Error Recovery

```tsx
<YoursWalletConnector
  onError={(error) => {
    switch (error) {
      case 'EXTENSION_NOT_FOUND':
        // Show installation guide
        setShowInstallGuide(true);
        break;
        
      case 'WALLET_LOCKED':
        // Prompt to unlock
        toast.error('Please unlock your Yours Wallet and try again');
        break;
        
      case 'CONNECTION_REFUSED':
        // Allow retry
        setConnectionAttempts(prev => prev + 1);
        if (connectionAttempts < 3) {
          toast.error('Connection refused. Please try again.');
        }
        break;
        
      default:
        // Generic error handling
        console.error('Wallet connection error:', error);
        toast.error('Connection failed. Please try again.');
    }
  }}
/>
```

## Security Considerations

* **Private Key Safety**: Private keys never leave the wallet extension
* **Signature Verification**: All connections verified cryptographically
* **Session Management**: Secure session tokens with expiration
* **Permission Model**: Users explicitly approve connections
* **Network Security**: HTTPS required for all communications

## Browser Compatibility

| Browser | Supported | Extension Store  |
| ------- | --------- | ---------------- |
| Chrome  | ✅         | Chrome Web Store |
| Firefox | ✅         | Firefox Add-ons  |
| Safari  | ❌         | Not available    |
| Edge    | ✅         | Edge Add-ons     |

## Troubleshooting

### Extension Not Detected

1. Verify extension is installed and enabled
2. Refresh the page
3. Check browser console for errors
4. Try disabling/re-enabling extension

### Connection Failures

1. Ensure wallet is unlocked
2. Check network connectivity
3. Verify website is not blocked
4. Clear browser cache and cookies

### Performance Issues

1. Close unnecessary browser tabs
2. Disable conflicting extensions
3. Update to latest extension version
4. Restart browser if needed

## Related Components

* [HandCashConnector](/docs/components/handcash-connector) - HandCash wallet integration
* [SendBSVButton](/docs/components/send-bsv-button) - Send BSV transactions
* [WalletOverview](/docs/components/wallet-overview) - Display wallet balance
* [OAuthProviders](/docs/components/oauth-providers) - Alternative auth methods