External Wallets - Para Docs

Overview

Para v2 supports authentication with external wallets, allowing users to connect their existing MetaMask, Phantom, or other wallets to authenticate with your Flutter application. The Flutter SDK maintains blockchain packages (web3dart, solana_web3) to provide direct access to external wallet functionality while integrating with Para’s unified wallet architecture. This guide covers how to implement external wallet authentication and interaction using Para’s connector classes.

Prerequisites

Before implementing external wallet support, ensure you have:

Para SDK set up in your Flutter project (see the Setup Guide)
Deep linking configured for your app
Target external wallet apps installed on the device

Deep Link Configuration

External wallet authentication requires deep linking to redirect users back to your app after wallet interaction. Configure this in both iOS and Android.

Android Configuration

Add an intent filter to your android/app/src/main/AndroidManifest.xml:

<activity
    android:name="com.linusu.flutter_web_auth_2.CallbackActivity"
    android:exported="true">
    <intent-filter android:label="flutter_web_auth_2">
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <data android:scheme="yourapp" />
    </intent-filter>
</activity>

iOS Configuration

Add your URL scheme to ios/Runner/Info.plist:

<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleTypeRole</key>
    <string>Editor</string>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>yourapp</string>
    </array>
  </dict>
</array>

External Wallet Authentication

Para v2 provides a unified method for external wallet authentication:

import 'package:para/para.dart';

Future<void> authenticateWithExternalWallet(
  String externalAddress,
  String walletType,
) async {
  try {
    // Login with external wallet address
    await para.loginExternalWallet(
      externalAddress: externalAddress,
      type: walletType, // "EVM" or "SOLANA"
    );
    
    // Check if authentication was successful
    final isActive = await para.isSessionActive().future;
    if (isActive) {
      final wallets = await para.fetchWallets().future;
      print('Authenticated with ${wallets.length} wallets');
    }
  } catch (e) {
    print('External wallet authentication failed: $e');
  }
}

Working with Specific Wallets

Para provides dedicated connectors for popular external wallets:

MetaMask Integration

Para includes a MetaMask connector for EVM interactions:

import 'package:para/para.dart';

class MetaMaskService {
  late ParaMetaMaskConnector _connector;
  
  void initialize() {
    _connector = ParaMetaMaskConnector(
      para: para,
      appUrl: 'https://yourapp.com',
      appScheme: 'yourapp',
    );
  }
  
  Future<void> connectMetaMask() async {
    try {
      await _connector.connect();
      print('MetaMask connected');
    } catch (e) {
      print('Failed to connect MetaMask: $e');
    }
  }
  
  Future<String> signMessage(String message) async {
    if (_connector.accounts.isEmpty) {
      throw Exception('No accounts connected');
    }
    
    final signature = await _connector.signMessage(
      message,
      _connector.accounts.first,
    );
    
    return signature;
  }
  
  Future<String> sendTransaction({
    required String toAddress,
    required BigInt value,
  }) async {
    if (_connector.accounts.isEmpty) {
      throw Exception('No accounts connected');
    }
    
    final transaction = Transaction(
      from: EthereumAddress.fromHex(_connector.accounts.first),
      to: EthereumAddress.fromHex(toAddress),
      value: EtherAmount.inWei(value),
      maxGas: 100000,
      gasPrice: EtherAmount.inWei(BigInt.from(20000000000)), // 20 Gwei
    );
    
    final txHash = await _connector.sendTransaction(
      transaction,
      _connector.accounts.first,
    );
    
    return txHash;
  }
}

Phantom Integration

Para includes a Phantom connector for Solana interactions:

import 'package:para/para.dart';
import 'package:solana_web3/solana_web3.dart';

class PhantomService {
  late ParaPhantomConnector _connector;
  
  void initialize() {
    _connector = ParaPhantomConnector(
      para: para,
      appUrl: 'https://yourapp.com', 
      appScheme: 'yourapp',
    );
  }
  
  Future<void> connectPhantom() async {
    try {
      await _connector.connect();
      print('Phantom connected');
    } catch (e) {
      print('Failed to connect Phantom: $e');
    }
  }
  
  Future<String> signMessage(String message) async {
    final signature = await _connector.signMessage(message);
    return signature;
  }
  
  /// Sign a transaction using serialized transaction bytes
  /// Returns: Base58 encoded signed transaction that must be sent to the network
  Future<String> signTransactionBytes(Uint8List transactionBytes) async {
    final signedTxBase58 = await _connector.signTransactionBytes(transactionBytes);
    return signedTxBase58;
  }
}

Example: Complete External Wallet Flow

Here’s a complete example showing external wallet authentication and usage:

import 'package:flutter/material.dart';
import 'package:para/para.dart';

class ExternalWalletScreen extends StatefulWidget {
  @override
  _ExternalWalletScreenState createState() => _ExternalWalletScreenState();
}

class _ExternalWalletScreenState extends State<ExternalWalletScreen> {
  ParaMetaMaskConnector? _metamaskConnector;
  ParaPhantomConnector? _phantomConnector;
  bool _isConnected = false;
  
  @override
  void initState() {
    super.initState();
    _initializeConnectors();
  }
  
  void _initializeConnectors() {
    _metamaskConnector = ParaMetaMaskConnector(
      para: para,
      appUrl: 'https://yourapp.com',
      appScheme: 'yourapp',
    );
    
    _phantomConnector = ParaPhantomConnector(
      para: para,
      appUrl: 'https://yourapp.com',
      appScheme: 'yourapp', 
    );
  }
  
  Future<void> _connectMetaMask() async {
    try {
      await _metamaskConnector!.connect();
      setState(() => _isConnected = true);
      
      // Check if Para session is active after connection
      final isActive = await para.isSessionActive().future;
      if (isActive) {
        ScaffoldMessenger.of(context).showSnackBar(
          SnackBar(content: Text('MetaMask connected and authenticated with Para!')),
        );
      }
    } catch (e) {
      ScaffoldMessenger.of(context).showSnackBar(
        SnackBar(content: Text('Failed to connect MetaMask: $e')),
      );
    }
  }
  
  Future<void> _connectPhantom() async {
    try {
      await _phantomConnector!.connect();
      setState(() => _isConnected = true);
      
      // Check if Para session is active after connection
      final isActive = await para.isSessionActive().future;
      if (isActive) {
        ScaffoldMessenger.of(context).showSnackBar(
          SnackBar(content: Text('Phantom connected and authenticated with Para!')),
        );
      }
    } catch (e) {
      ScaffoldMessenger.of(context).showSnackBar(
        SnackBar(content: Text('Failed to connect Phantom: $e')),
      );
    }
  }
  
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text('External Wallets')),
      body: Padding(
        padding: EdgeInsets.all(16),
        child: Column(
          children: [
            Text(
              'Connect an external wallet to get started',
              style: Theme.of(context).textTheme.headlineSmall,
            ),
            SizedBox(height: 32),
            
            // MetaMask Connection
            ElevatedButton.icon(
              onPressed: _connectMetaMask,
              icon: Icon(Icons.account_balance_wallet),
              label: Text('Connect MetaMask'),
              style: ElevatedButton.styleFrom(
                minimumSize: Size(double.infinity, 50),
              ),
            ),
            SizedBox(height: 16),
            
            // Phantom Connection  
            ElevatedButton.icon(
              onPressed: _connectPhantom,
              icon: Icon(Icons.account_balance_wallet),
              label: Text('Connect Phantom'),
              style: ElevatedButton.styleFrom(
                minimumSize: Size(double.infinity, 50),
              ),
            ),
          ],
        ),
      ),
    );
  }
}

Security Considerations

When working with external wallets:

Validate Connections: Always verify the wallet connection before performing operations
Handle Errors Gracefully: External wallet apps may not be installed or might reject connections
User Experience: Provide clear instructions for users on wallet installation and connection
Permissions: Ensure your app requests appropriate permissions for wallet interactions
Deep Link Security: Validate deep link callbacks to prevent malicious redirects

Troubleshooting

Common issues and solutions:

Connection Failures

Future<void> connectWithRetry(VoidCallback connectFunction) async {
  int retries = 3;
  
  while (retries > 0) {
    try {
      await connectFunction();
      return;
    } catch (e) {
      retries--;
      if (retries == 0) {
        throw Exception('Failed to connect after 3 attempts: $e');
      }
      await Future.delayed(Duration(seconds: 2));
    }
  }
}

Phantom Transaction Errors

When working with Phantom, use the transaction helper for proper encoding:

import 'package:para/para.dart';

// Convert signed transaction for network submission
final signedTxBase64 = ParaPhantomTransactionHelper.signedTransactionToBase64(signedTxBase58);

// Send to Solana network
final signature = await solanaClient.rpcClient.sendTransaction(signedTxBase64);

Wallet App Not Installed

Future<bool> isWalletInstalled(String walletScheme) async {
  try {
    return await canLaunchUrl(Uri.parse('$walletScheme://'));
  } catch (e) {
    return false;
  }
}

Future<void> openWalletInstallPage(String storeUrl) async {
  if (await canLaunchUrl(Uri.parse(storeUrl))) {
    await launchUrl(Uri.parse(storeUrl));
  }
}

Network Issues

Ensure you have the correct network selected in your external wallet:

Phantom: Check that you’re on the intended Solana network (mainnet-beta, devnet, testnet)
MetaMask: Verify you’re connected to the correct Ethereum network
Transactions: Use testnet/devnet for development to avoid spending real funds

Key Features

Para’s Flutter SDK provides:

Unified Architecture: External wallets integrate seamlessly with Para’s unified wallet system
Direct Blockchain Access: Uses web3dart for Ethereum and solana_web3 for Solana interactions
Deep Link Support: Handles wallet app redirections automatically
Transaction Helpers: Utility classes for transaction encoding/decoding
Error Handling: Comprehensive error handling for wallet interactions

Resources

For more information about external wallet integration:

​Overview

​Prerequisites

​Deep Link Configuration

​Android Configuration

​iOS Configuration

​External Wallet Authentication

​Working with Specific Wallets

​MetaMask Integration

​Phantom Integration

​Example: Complete External Wallet Flow

​Security Considerations

​Troubleshooting

​Connection Failures

​Phantom Transaction Errors

​Wallet App Not Installed

​Network Issues

​Key Features

​Resources