Intégrer un portefeuille Web3 dans une application Flutter
Un guide clair pour comprendre comment connecter un portefeuille Web3 dans Flutter avec WalletConnect, une WebView ou une approche native on-chain.
Comprendre le problème avant de coder
Sur mobile, le Web3 ne fonctionne pas exactement comme sur le web. Un portefeuille comme MetaMask ou Rabby n'est pas une simple bibliothèque à brancher dans votre code : c'est un environnement externe qui signe les transactions à la place de l'utilisateur.
Cela change tout. Dans une application Flutter, votre rôle n'est généralement pas de stocker la clé privée d'un utilisateur. Votre rôle est de demander une connexion, récupérer une adresse, proposer une action, puis attendre qu'un portefeuille valide la signature.
Avant de choisir une solution, posez-vous une question simple : voulez-vous seulement lire des données on-chain, ou voulez-vous aussi faire signer des actions par l'utilisateur ? La réponse détermine la meilleure architecture.
Les trois approches les plus courantes
Il existe trois façons réalistes d'intégrer le Web3 dans Flutter :
- WalletConnect pour connecter votre app à un portefeuille externe
- WebView avec bridge JavaScript pour réutiliser une dApp web existante
- Accès natif avec
web3dartpour des interactions simples côté chaîne
Le bon choix dépend surtout de votre niveau d'exigence sur l'expérience utilisateur, la sécurité et le temps de développement.
Approche 1 - WalletConnect
WalletConnect est souvent la meilleure solution par défaut. Le principe est simple : votre application demande une connexion, le portefeuille externe affiche la requête, puis l'utilisateur valide manuellement.
L'avantage est énorme : vous ne touchez pas à la clé privée de l'utilisateur, et vous vous appuyez sur un standard largement adopté.
Le flux général ressemble à ceci :
- l'utilisateur clique sur "Connecter le portefeuille"
- l'application génère une demande de pairing
- le wallet ouvre la session et affiche les comptes disponibles
- l'utilisateur approuve ou refuse
- votre app récupère l'adresse publique et l'état de connexion
// Exemple simplifié : les API exactes dépendent du package WalletConnect choisi.
final metadata = PairingMetadata(
name: 'Mon App',
description: 'Application de paiement',
url: 'https://monapp.com',
icons: ['https://monapp.com/icon.png'],
);
// 1. Créer une session
// 2. Ouvrir le wallet via deep link ou QR code
// 3. Attendre l'approbation de l'utilisateur
// 4. Récupérer l'adresse et la chaîne sélectionnée
WalletConnect est particulièrement adapté si vous voulez :
- une vraie expérience Web3 mobile
- une sécurité correcte sans gérer les clés privées
- une compatibilité avec plusieurs wallets
Approche 2 - WebView + ethers.js
Cette approche est intéressante si vous avez déjà une dApp web fonctionnelle et que vous souhaitez la réutiliser dans Flutter sans la réécrire.
Le principe consiste à charger votre application web dans une WebView, puis à injecter un objet window.ethereum qui relaie les appels vers Flutter.
Le point fort : vous conservez une grande partie du code web existant.
Le point faible : la solution est plus fragile, car vous devez gérer le pont JavaScript, les permissions, les erreurs et les différences entre plateformes.
late final WebViewController controller;
void _injectWeb3Provider() {
controller.runJavaScript('''
window.ethereum = {
request: async ({ method, params }) => {
return await FlutterEthBridge.callMethod(method, params);
},
isMetaMask: true,
};
''');
}
Ensuite, côté Flutter, vous écoutez les messages envoyés par la WebView via un JavascriptChannel :
JavascriptChannel(
name: 'FlutterEthBridge',
onMessageReceived: (message) async {
final call = jsonDecode(message.message);
final result = await _handleEthCall(call['method'], call['params']);
controller.runJavaScript('resolveEthCall(${jsonEncode(result)})');
},
)
Cette approche peut fonctionner correctement, mais elle demande beaucoup de rigueur. Il faut bien valider l'origine des appels, ne jamais exposer d'opérations sensibles sans contrôle, et garder une séparation nette entre le code web et le code natif.
Approche 3 - web3dart (natif)
web3dart est utile lorsque vous voulez interagir directement avec la blockchain sans interface web. C'est pratique pour lire des données, interroger un contrat ou envoyer une transaction dans un contexte contrôlé.
Cette approche est la plus simple pour des opérations on-chain basiques, mais elle ne remplace pas un vrai wallet utilisateur dans une application grand public.
final client = Web3Client('https://sepolia.infura.io/v3/YOUR_KEY', Client());
// Lire un solde
final balance = await client.getBalance(
EthereumAddress.fromHex('0x...'),
);
// Envoyer une transaction
final credentials = EthPrivateKey.fromHex('0x...');
final txHash = await client.sendTransaction(
credentials,
Transaction(
to: EthereumAddress.fromHex('0x...'),
value: EtherAmount.fromUnitAndValue(EtherUnit.ether, 1),
),
);
Attention : pour une application destinée à des utilisateurs finaux, évitez de faire transiter des clés privées dans votre code mobile. Garder une clé dans l'application n'est acceptable que dans des cas très contrôlés, par exemple pour un wallet administratif ou un environnement interne.
Comment choisir la bonne approche
Si vous hésitez, voici une règle simple :
- WalletConnect si l'utilisateur possède déjà son wallet et doit signer lui-même
- WebView si vous avez déjà une dApp web complète à réutiliser
- web3dart si votre besoin est simple, technique et très contrôlé
Dans la majorité des applications sérieuses, WalletConnect est le meilleur point de départ.
Sécurité - points critiques
Le Web3 attire souvent des erreurs de sécurité très coûteuses. Quelques règles sont indispensables :
- ne stockez jamais une clé privée en clair
- utilisez
flutter_secure_storagesi vous devez conserver une donnée sensible côté appareil - vérifiez systématiquement la chaîne ciblée avant une transaction
- contrôlez l'origine des messages dans une WebView
- utilisez un testnet comme Sepolia ou Polygon Amoy avant le mainnet
- limitez les montants et les permissions accordées par l'utilisateur
- privilégiez des smart contracts audités
La sécurité ne doit pas être traitée comme une étape finale. Elle doit être intégrée dès la conception.
Un bon parcours utilisateur Web3
Une intégration réussie ne se limite pas au code. L'expérience utilisateur compte énormément.
Un parcours clair ressemble souvent à ceci :
- expliquer pourquoi la connexion du wallet est nécessaire
- afficher le wallet demandé et le réseau visé
- demander la signature uniquement au bon moment
- confirmer le succès avec un message lisible
- afficher l'état de la transaction jusqu'à sa confirmation
Plus le parcours est transparent, moins l'utilisateur se sent perdu.
Conclusion
Il n'existe pas une solution unique pour tous les projets Web3 sous Flutter. WalletConnect reste la solution la plus propre pour connecter un portefeuille externe. La WebView sert surtout à réutiliser une application web existante. web3dart est utile pour des interactions on-chain simples et très contrôlées.
Le bon choix dépend donc de votre produit, de votre niveau de risque et du parcours utilisateur que vous voulez proposer.