Skip to content

Commit 571012c

Browse files
0xrinegade0xrinegade
authored
Merge pull request #75 from openSVM/copilot/fix-74
Replace Solana wallet adapter with Swig wallet for OAuth-based authentication
2 parents 185d5a7 + 7c9754b commit 571012c

28 files changed

+5434
-8692
lines changed

‎.env.example‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
# Environment Variables for Swig Wallet Integration
2+
3+
# Para SDK API Key (required for OAuth authentication)
4+
# Get your API key from: https://para.build/
5+
#
6+
# ⚠️ SECURITY WARNING:
7+
# - NEXT_PUBLIC_PARA_API_KEY is exposed to the browser (public prefix)
8+
# - Only use API keys with read-only/limited scopes for frontend
9+
# - Never include admin/write permissions in this key
10+
# - Ensure the key only has OAuth authentication permissions
11+
NEXT_PUBLIC_PARA_API_KEY=your_para_api_key_here
12+
13+
# Alternative environment variable name (fallback)
14+
PARA_API_KEY=your_para_api_key_here
15+
16+
# ⚠️ IMPORTANT: Never commit .env.local with real API keys to version control!
17+
18+
# Network Configuration
19+
# Options: localnet, devnet, mainnet-beta
20+
NEXT_PUBLIC_SOLANA_NETWORK=devnet
21+
22+
# Development Settings
23+
NODE_ENV=development
24+
NEXT_PUBLIC_APP_ENV=development
25+
26+
# Example .env.local file (copy this to .env.local and update values)
27+
# ⚠️ NEVER commit .env.local to git - it should contain your real API keys
28+
# NEXT_PUBLIC_PARA_API_KEY=your_actual_api_key_here

‎SWIG_WALLET_INTEGRATION.md‎

Lines changed: 162 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,162 @@
1+
# Swig Wallet Integration
2+
3+
This document describes the replacement of Solana wallet adapter with Swig wallet integration.
4+
5+
## Overview
6+
7+
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.
8+
9+
## Key Changes
10+
11+
### Dependencies
12+
13+
**Removed:**
14+
- `@solana/wallet-adapter-react`
15+
- `@solana/wallet-adapter-react-ui`
16+
- `@solana/wallet-adapter-wallets`
17+
- `@solana/wallet-adapter-base`
18+
19+
**Added:**
20+
- `@getpara/web-sdk`
21+
- `@swig-wallet/classic`
22+
- `@swig-wallet/coder`
23+
- `@noble/curves`
24+
- `@noble/hashes`
25+
26+
### Components
27+
28+
1. **SwigWalletProvider** - Replaces `SafeWalletProvider`
29+
- Provides OAuth authentication
30+
- Manages wallet state
31+
- Supports both Solana (Ed25519) and EVM (Secp256k1) wallets
32+
33+
2. **SwigWalletButton** - Replaces `WalletMultiButton`
34+
- Shows authentication modal
35+
- Handles OAuth login flow
36+
- Compatible interface with existing code
37+
38+
3. **OAuthButtons** - New component
39+
- Provides OAuth login options (Google, Apple, Farcaster)
40+
- Handles authentication flow
41+
42+
### Authentication Flow
43+
44+
1. User clicks "Connect Wallet"
45+
2. Authentication modal opens with OAuth options
46+
3. User selects OAuth provider (Google, Apple, or Farcaster)
47+
4. User completes OAuth flow in popup window
48+
5. Para SDK creates or accesses existing wallet
49+
6. Application receives wallet connection confirmation
50+
51+
### Wallet Types
52+
53+
- **Solana (Ed25519)** - Traditional Solana wallets
54+
- **EVM (Secp256k1)** - Ethereum-compatible wallets
55+
56+
Users can switch between wallet types in their settings.
57+
58+
## Environment Setup
59+
60+
### Required Environment Variables
61+
62+
```bash
63+
# Para SDK API Key (required)
64+
NEXT_PUBLIC_PARA_API_KEY=your_para_api_key_here
65+
66+
# Alternative fallback
67+
PARA_API_KEY=your_para_api_key_here
68+
```
69+
70+
### Getting a Para API Key
71+
72+
1. Visit [Para SDK](https://para.build/)
73+
2. Sign up for an account
74+
3. Create a new application
75+
4. Copy your API key
76+
5. Add it to your `.env.local` file
77+
78+
## Migration Guide
79+
80+
### For Developers
81+
82+
The Swig wallet integration maintains backward compatibility:
83+
84+
```javascript
85+
// Old way (still works)
86+
import { useSafeWallet } from '../contexts/WalletContextProvider';
87+
88+
// New way (recommended)
89+
import { useSwigWallet } from '../contexts/SwigWalletProvider';
90+
91+
// Both provide the same interface:
92+
const { connected, publicKey, connect, disconnect } = useSwigWallet();
93+
```
94+
95+
### For Users
96+
97+
- No wallet extension installation required
98+
- Sign in with existing accounts (Google, Apple, Farcaster)
99+
- Seamless wallet creation and management
100+
- Multi-chain support (Solana and EVM)
101+
102+
## Features
103+
104+
### OAuth Authentication
105+
- Google OAuth
106+
- Apple OAuth
107+
- Farcaster OAuth
108+
- Secure popup-based flow
109+
110+
### Wallet Management
111+
- Automatic wallet creation
112+
- Multi-chain support
113+
- Secure key management
114+
- Session persistence
115+
116+
### Error Handling
117+
- Comprehensive error messages
118+
- Automatic retry logic
119+
- Graceful fallbacks
120+
- User-friendly troubleshooting
121+
122+
## Troubleshooting
123+
124+
### Common Issues
125+
126+
1. **"Para API key not found" error**
127+
- Solution: Add `NEXT_PUBLIC_PARA_API_KEY` to your environment variables
128+
129+
2. **OAuth popup blocked**
130+
- Solution: Allow popups for the application domain
131+
132+
3. **Authentication fails**
133+
- Solution: Check network connection and try different OAuth provider
134+
135+
### Development Mode
136+
137+
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.
138+
139+
## Security
140+
141+
- OAuth flows are handled by Para SDK
142+
- Private keys never leave Para's secure infrastructure
143+
- Application only receives public keys and signatures
144+
- All transactions require user approval
145+
146+
## Testing
147+
148+
The integration includes comprehensive tests for:
149+
- Wallet provider functionality
150+
- OAuth authentication flow
151+
- Component rendering
152+
- Error handling
153+
- Backward compatibility
154+
155+
Run tests with:
156+
```bash
157+
npm test src/tests/swig-wallet-integration.test.js
158+
```
159+
160+
## API Reference
161+
162+
See [wallet-operations.md](./docs/api/wallet-operations.md) for detailed API documentation.

‎SWIG_WALLET_MIGRATION.md‎

Lines changed: 158 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,158 @@
1+
# Swig Wallet Migration Guide
2+
3+
## Migration Timeline
4+
5+
### Phase 1: Deprecation Warnings (Current)
6+
- `useSafeWallet` hook displays deprecation warnings in console
7+
- `WalletMultiButton` component shows deprecation warning
8+
- All functionality remains intact
9+
- **Timeline**: Current release
10+
11+
### Phase 2: Migration Support (v1.5.0)
12+
- Add migration tool to scan codebase for deprecated usage
13+
- Provide automated migration scripts
14+
- Enhanced documentation and examples
15+
- **Timeline**: Next minor release
16+
17+
### Phase 3: Removal (v2.0.0)
18+
- Remove deprecated aliases completely
19+
- Clean up legacy code paths
20+
- **Timeline**: Next major release
21+
22+
## New Features & Improvements
23+
24+
### Enhanced Error Handling System
25+
The new Swig wallet integration includes a categorized error handling system:
26+
27+
#### Error Categories
28+
- **Critical Errors**: Authentication failures, API issues (persistent toasts)
29+
- **System Errors**: Network issues, connection problems (actionable toasts)
30+
- **Informational Errors**: Form validation, user input (inline or brief toasts)
31+
- **Success Messages**: Brief confirmation toasts
32+
33+
#### Usage Examples
34+
```javascript
35+
const { toast } = useToast();
36+
37+
// Critical errors - persistent with retry actions
38+
toast.criticalError('Authentication failed', {
39+
action: <button onClick={retry}>Retry</button>
40+
});
41+
42+
// System errors - connection issues with fallbacks
43+
toast.systemError('Connection lost', {
44+
action: <button onClick={reconnect}>Reconnect</button>
45+
});
46+
47+
// Success messages - brief confirmations
48+
toast.success('Wallet connected successfully');
49+
```
50+
51+
### Improved Reconnection Logic
52+
- **Exponential backoff with jitter** prevents thundering herd problems
53+
- **Comprehensive timeout cleanup** prevents memory leaks
54+
- **Progress tracking UI** shows reconnection attempts to users
55+
- **Cancellation support** allows users to stop reconnection
56+
57+
### Enhanced Popup Handling
58+
- **Better popup blocker detection** including mobile browsers
59+
- **Fallback options** for blocked popups (same-tab navigation)
60+
- **Sequential popup management** reduces blocker issues
61+
- **User-friendly error messages** with actionable buttons
62+
63+
### Accessibility Improvements
64+
- **Focus trapping** in modals for keyboard navigation
65+
- **ARIA labels** for screen readers
66+
- **Escape key support** for modal dismissal
67+
- **Proper focus restoration** after modal close
68+
69+
## Migration Steps
70+
71+
### 1. Update Hook Usage
72+
73+
**Before (Deprecated):**
74+
```javascript
75+
import { useSafeWallet } from './contexts/SwigWalletProvider';
76+
77+
const MyComponent = () => {
78+
const wallet = useSafeWallet();
79+
// ...
80+
};
81+
```
82+
83+
**After (Recommended):**
84+
```javascript
85+
import { useSwigWallet } from './contexts/SwigWalletProvider';
86+
87+
const MyComponent = () => {
88+
const wallet = useSwigWallet();
89+
// ...
90+
};
91+
```
92+
93+
### 2. Update Component Usage
94+
95+
**Before (Deprecated):**
96+
```javascript
97+
import { WalletMultiButton } from './components/SwigWalletButton';
98+
99+
const MyComponent = () => (
100+
<WalletMultiButton />
101+
);
102+
```
103+
104+
**After (Recommended):**
105+
```javascript
106+
import { SwigWalletButton } from './components/SwigWalletButton';
107+
108+
const MyComponent = () => (
109+
<SwigWalletButton />
110+
);
111+
```
112+
113+
### 3. Update Provider Usage
114+
115+
**Before (Legacy):**
116+
```javascript
117+
import { SafeWalletProvider } from './contexts/SwigWalletProvider';
118+
```
119+
120+
**After (Current):**
121+
```javascript
122+
import { SwigWalletProvider } from './contexts/SwigWalletProvider';
123+
```
124+
125+
## Breaking Changes in v2.0.0
126+
127+
1. **Removed Exports:**
128+
- `useSafeWallet` hook
129+
- `WalletMultiButton` component alias
130+
- `SafeWalletProvider` component alias
131+
132+
2. **Updated Interface:**
133+
- All wallet context properties now use consistent naming
134+
- Error handling moved to toast notifications by default
135+
136+
## Migration Tool Usage
137+
138+
Run the migration tool to automatically update your codebase:
139+
140+
```bash
141+
npm run migrate-wallet-hooks
142+
```
143+
144+
This will:
145+
- Scan your codebase for deprecated usage
146+
- Automatically replace deprecated hooks and components
147+
- Generate a migration report
148+
- Backup original files
149+
150+
## Need Help?
151+
152+
- Check the updated documentation in `SWIG_WALLET_INTEGRATION.md`
153+
- Review the example implementations in the `/examples` folder
154+
- Create an issue if you encounter migration problems
155+
156+
## Compatibility Promise
157+
158+
We guarantee backward compatibility through v1.x releases. All deprecated features will continue to work with warnings until v2.0.0.

0 commit comments

Comments
 (0)