Replace Solana wallet adapter with Swig wallet for OAuth-based authentication

.env.example

@@ -0,0 +1,28 @@
+# Environment Variables for Swig Wallet Integration
+
+# Para SDK API Key (required for OAuth authentication)
+# Get your API key from: https://para.build/
+# 
+# ⚠️  SECURITY WARNING: 
+# - NEXT_PUBLIC_PARA_API_KEY is exposed to the browser (public prefix)
+# - Only use API keys with read-only/limited scopes for frontend
+# - Never include admin/write permissions in this key
+# - Ensure the key only has OAuth authentication permissions
+NEXT_PUBLIC_PARA_API_KEY=your_para_api_key_here
+
+# Alternative environment variable name (fallback)
+PARA_API_KEY=your_para_api_key_here
+
+# ⚠️  IMPORTANT: Never commit .env.local with real API keys to version control!
+
+# Network Configuration
+# Options: localnet, devnet, mainnet-beta
+NEXT_PUBLIC_SOLANA_NETWORK=devnet
+
+# Development Settings
+NODE_ENV=development
+NEXT_PUBLIC_APP_ENV=development
+
+# Example .env.local file (copy this to .env.local and update values)
+# ⚠️  NEVER commit .env.local to git - it should contain your real API keys
+# NEXT_PUBLIC_PARA_API_KEY=your_actual_api_key_here

SWIG_WALLET_INTEGRATION.md

@@ -0,0 +1,162 @@
+# Swig Wallet Integration
+
+This document describes the replacement of Solana wallet adapter with Swig wallet integration.
+
+## Overview
+
+The application has been updated to use Swig wallet instead of traditional Solana wallet adapter. This provides OAuth-based authentication and in-app wallet creation, making it easier for users to get started without needing to install browser extensions.
+
+## Key Changes
+
+### Dependencies
+
+**Removed:**
+- `@solana/wallet-adapter-react`
+- `@solana/wallet-adapter-react-ui`
+- `@solana/wallet-adapter-wallets`
+- `@solana/wallet-adapter-base`
+
+**Added:**
+- `@getpara/web-sdk`
+- `@swig-wallet/classic`
+- `@swig-wallet/coder`
+- `@noble/curves`
+- `@noble/hashes`
+
+### Components
+
+1. **SwigWalletProvider** - Replaces `SafeWalletProvider`
+   - Provides OAuth authentication
+   - Manages wallet state
+   - Supports both Solana (Ed25519) and EVM (Secp256k1) wallets
+
+2. **SwigWalletButton** - Replaces `WalletMultiButton`
+   - Shows authentication modal
+   - Handles OAuth login flow
+   - Compatible interface with existing code
+
+3. **OAuthButtons** - New component
+   - Provides OAuth login options (Google, Apple, Farcaster)
+   - Handles authentication flow
+
+### Authentication Flow
+
+1. User clicks "Connect Wallet"
+2. Authentication modal opens with OAuth options
+3. User selects OAuth provider (Google, Apple, or Farcaster)
+4. User completes OAuth flow in popup window
+5. Para SDK creates or accesses existing wallet
+6. Application receives wallet connection confirmation
+
+### Wallet Types
+
+- **Solana (Ed25519)** - Traditional Solana wallets
+- **EVM (Secp256k1)** - Ethereum-compatible wallets
+
+Users can switch between wallet types in their settings.
+
+## Environment Setup
+
+### Required Environment Variables
+
+```bash
+# Para SDK API Key (required)
+NEXT_PUBLIC_PARA_API_KEY=your_para_api_key_here
+
+# Alternative fallback
+PARA_API_KEY=your_para_api_key_here
+```
+
+### Getting a Para API Key
+
+1. Visit [Para SDK](https://para.build/)
+2. Sign up for an account
+3. Create a new application
+4. Copy your API key
+5. Add it to your `.env.local` file
+
+## Migration Guide
+
+### For Developers
+
+The Swig wallet integration maintains backward compatibility:
+
+```javascript
+// Old way (still works)
+import { useSafeWallet } from '../contexts/WalletContextProvider';
+
+// New way (recommended)
+import { useSwigWallet } from '../contexts/SwigWalletProvider';
+
+// Both provide the same interface:
+const { connected, publicKey, connect, disconnect } = useSwigWallet();
+```
+
+### For Users
+
+- No wallet extension installation required
+- Sign in with existing accounts (Google, Apple, Farcaster)
+- Seamless wallet creation and management
+- Multi-chain support (Solana and EVM)
+
+## Features
+
+### OAuth Authentication
+- Google OAuth
+- Apple OAuth  
+- Farcaster OAuth
+- Secure popup-based flow
+
+### Wallet Management
+- Automatic wallet creation
+- Multi-chain support
+- Secure key management
+- Session persistence
+
+### Error Handling
+- Comprehensive error messages
+- Automatic retry logic
+- Graceful fallbacks
+- User-friendly troubleshooting
+
+## Troubleshooting
+
+### Common Issues
+
+1. **"Para API key not found" error**
+   - Solution: Add `NEXT_PUBLIC_PARA_API_KEY` to your environment variables
+
+2. **OAuth popup blocked**
+   - Solution: Allow popups for the application domain
+
+3. **Authentication fails**
+   - Solution: Check network connection and try different OAuth provider
+
+### Development Mode
+
+In development without a Para API key, the application will use mock wallet functions that return safe default values. This allows development to continue without requiring API key setup.
+
+## Security
+
+- OAuth flows are handled by Para SDK
+- Private keys never leave Para's secure infrastructure
+- Application only receives public keys and signatures
+- All transactions require user approval
+
+## Testing
+
+The integration includes comprehensive tests for:
+- Wallet provider functionality
+- OAuth authentication flow
+- Component rendering
+- Error handling
+- Backward compatibility
+
+Run tests with:
+```bash
+npm test src/tests/swig-wallet-integration.test.js
+```
+
+## API Reference
+
+See [wallet-operations.md](./docs/api/wallet-operations.md) for detailed API documentation.

SWIG_WALLET_MIGRATION.md

@@ -0,0 +1,158 @@
+# Swig Wallet Migration Guide
+
+## Migration Timeline
+
+### Phase 1: Deprecation Warnings (Current)
+- `useSafeWallet` hook displays deprecation warnings in console
+- `WalletMultiButton` component shows deprecation warning
+- All functionality remains intact
+- **Timeline**: Current release
+
+### Phase 2: Migration Support (v1.5.0)
+- Add migration tool to scan codebase for deprecated usage
+- Provide automated migration scripts
+- Enhanced documentation and examples
+- **Timeline**: Next minor release
+
+### Phase 3: Removal (v2.0.0)
+- Remove deprecated aliases completely
+- Clean up legacy code paths
+- **Timeline**: Next major release
+
+## New Features & Improvements
+
+### Enhanced Error Handling System
+The new Swig wallet integration includes a categorized error handling system:
+
+#### Error Categories
+- **Critical Errors**: Authentication failures, API issues (persistent toasts)
+- **System Errors**: Network issues, connection problems (actionable toasts)
+- **Informational Errors**: Form validation, user input (inline or brief toasts)
+- **Success Messages**: Brief confirmation toasts
+
+#### Usage Examples
+```javascript
+const { toast } = useToast();
+
+// Critical errors - persistent with retry actions
+toast.criticalError('Authentication failed', {
+  action: <button onClick={retry}>Retry</button>
+});
+
+// System errors - connection issues with fallbacks
+toast.systemError('Connection lost', {
+  action: <button onClick={reconnect}>Reconnect</button>
+});
+
+// Success messages - brief confirmations
+toast.success('Wallet connected successfully');
+```
+
+### Improved Reconnection Logic
+- **Exponential backoff with jitter** prevents thundering herd problems
+- **Comprehensive timeout cleanup** prevents memory leaks
+- **Progress tracking UI** shows reconnection attempts to users
+- **Cancellation support** allows users to stop reconnection
+
+### Enhanced Popup Handling
+- **Better popup blocker detection** including mobile browsers
+- **Fallback options** for blocked popups (same-tab navigation)
+- **Sequential popup management** reduces blocker issues
+- **User-friendly error messages** with actionable buttons
+
+### Accessibility Improvements
+- **Focus trapping** in modals for keyboard navigation
+- **ARIA labels** for screen readers
+- **Escape key support** for modal dismissal
+- **Proper focus restoration** after modal close
+
+## Migration Steps
+
+### 1. Update Hook Usage
+
+**Before (Deprecated):**
+```javascript
+import { useSafeWallet } from './contexts/SwigWalletProvider';
+
+const MyComponent = () => {
+  const wallet = useSafeWallet();
+  // ...
+};
+```
+
+**After (Recommended):**
+```javascript
+import { useSwigWallet } from './contexts/SwigWalletProvider';
+
+const MyComponent = () => {
+  const wallet = useSwigWallet();
+  // ...
+};
+```
+
+### 2. Update Component Usage
+
+**Before (Deprecated):**
+```javascript
+import { WalletMultiButton } from './components/SwigWalletButton';
+
+const MyComponent = () => (
+  <WalletMultiButton />
+);
+```
+
+**After (Recommended):**
+```javascript
+import { SwigWalletButton } from './components/SwigWalletButton';
+
+const MyComponent = () => (
+  <SwigWalletButton />
+);
+```
+
+### 3. Update Provider Usage
+
+**Before (Legacy):**
+```javascript
+import { SafeWalletProvider } from './contexts/SwigWalletProvider';
+```
+
+**After (Current):**
+```javascript
+import { SwigWalletProvider } from './contexts/SwigWalletProvider';
+```
+
+## Breaking Changes in v2.0.0
+
+1. **Removed Exports:**
+   - `useSafeWallet` hook
+   - `WalletMultiButton` component alias
+   - `SafeWalletProvider` component alias
+
+2. **Updated Interface:**
+   - All wallet context properties now use consistent naming
+   - Error handling moved to toast notifications by default
+
+## Migration Tool Usage
+
+Run the migration tool to automatically update your codebase:
+
+```bash
+npm run migrate-wallet-hooks
+```
+
+This will:
+- Scan your codebase for deprecated usage
+- Automatically replace deprecated hooks and components
+- Generate a migration report
+- Backup original files
+
+## Need Help?
+
+- Check the updated documentation in `SWIG_WALLET_INTEGRATION.md`
+- Review the example implementations in the `/examples` folder
+- Create an issue if you encounter migration problems
+
+## Compatibility Promise
+
+We guarantee backward compatibility through v1.x releases. All deprecated features will continue to work with warnings until v2.0.0.