Lorsqu’une transaction de token sur Solana échoue pendant la création, la révocation d’autorité ou la création d’un pool de liquidité, l’échec s’explique par une erreur d’exécution précise analysée par le réseau. Les transactions Solana s’exécutent de façon atomique: si une seule instruction échoue, la totalité de la transaction est annulée, aucun changement d’état n’est appliqué et seuls les frais de réseau sont prélevés.
Diagnostiquer une transaction échouée nécessite de vérifier le solde SOL du portefeuille, le statut des nœuds RPC, les conditions d’initialisation des comptes et les journaux de programme sur un explorateur Solana.
Fonctionnement du cycle de vie d’une transaction Solana
Pour comprendre pourquoi une transaction a été rejetée ou annulée, voici les étapes de son traitement sur le réseau:
- Construction: Un outil prépare une transaction contenant des instructions (comme
InitializeMint ou CreateAccount) et y associe une empreinte de bloc récente (blockhash).
- Signature: Votre portefeuille signe la transaction avec la clé privée de l’autorité requise.
- Diffusion: La transaction signée est envoyée à un nœud RPC (Remote Procedure Call) Solana.
- Validation: Le validateur principal évalue les instructions par rapport à l’état actuel du registre.
- Exécution ou Annulation: Si la transaction est valide, les changements sont enregistrés dans un bloc. Si elle est invalide, la transaction est annulée et génère un code d’erreur.
La documentation officielle sur les transactions Solana détaille les limites de transaction, l’expiration des blockhashs et le traitement des instructions.
Erreur 1: SOL insuffisant pour l’exemption de loyer du compte
La cause la plus fréquente d’échec lors de la création d’un token est un solde de portefeuille trop faible pour couvrir l’exemption de loyer du compte.
Sur Solana, chaque nouveau compte (comme un compte de création, un compte de métadonnées ou un compte de token associé) doit conserver un solde minimal en SOL natif pour être stocké de façon permanente dans la mémoire des validateurs. Cette exigence est appelée exemption de loyer (rent exemption).
Il convient de distinguer deux coûts séparés:
- Frais de transaction réseau: Des frais minimes (généralement 0,000005 SOL) versés aux validateurs pour le traitement.
- Dépôt d’exemption de loyer: Un dépôt unique nécessaire à l’ouverture d’un nouveau compte (généralement 0,002 à 0,005 SOL par compte créé).
Si votre portefeuille ne contient que 0,001 SOL, vous avez assez pour couvrir les frais de transaction, mais la transaction échouera par manque de SOL pour payer le loyer des nouveaux comptes. Conservez toujours au moins 0,02 à 0,05 SOL natif sur votre portefeuille avant de créer des tokens ou des pools.
Erreur 2: Congestion des nœuds RPC et expiration du blockhash
Chaque transaction Solana contient un blockhash récent pour empêcher les attaques par rejeu. Un blockhash reste valide pendant environ 150 slots réseau (soit 60 à 90 secondes).
Si le réseau Solana connaît un trafic intense ou si le nœud RPC met du temps à diffuser la transaction:
- La transaction peut rester en attente dans la file RPC jusqu’à l’expiration du blockhash.
- Une fois les 150 slots écoulés, les validateurs rejettent la transaction avec l’erreur
BlockhashNotFound ou TransactionExpired.
- L’interface de votre portefeuille peut afficher un message générique “Délai d’attente dépassé”.
Pour résoudre les échecs liés au RPC:
- Actualisez la page web pour récupérer un blockhash récent.
- Vérifiez l’état du réseau pour déceler d’éventuelles congestions.
- Utilisez une plateforme fiable dotée de nœuds RPC de secours.
- Augmentez légèrement les frais de priorité si le trafic est élevé.
Erreur 3: Compte de token associé (ATA) non initialisé
Lors de l’émission de tokens ou de l’envoi d’offre vers un destinataire, l’adresse cible doit posséder un compte de token associé (ATA) initialisé pour le token concerné.
Si une transaction tente d’envoyer des tokens vers une adresse sans exécuter au préalable l’instruction CreateAssociatedTokenAccount, l’instruction d’envoi échoue avec l’erreur AccountDoesNotExist.
Les outils d’accompagnement intègrent automatiquement la création du compte ATA dans la même transaction que l’émission pour éviter cet échec.
Erreur 4: Discordance d’autorité et rejet de signature
Une transaction est annulée si la signature provient d’un portefeuille qui ne détient pas l’autorité requise pour l’opération:
- Erreur d’émission: Tenter d’émettre des tokens avec un portefeuille qui n’est pas l’autorité d’émission actuelle (ou après sa révocation).
- Erreur de gel: Tenter de geler un compte avec un portefeuille qui ne détient pas l’autorité de gel.
- Erreur de métadonnées: Tenter de modifier les métadonnées avec un portefeuille qui n’est pas l’autorité de mise à jour.
Si vous avez connecté un autre portefeuille ou transféré une clé d’autorité vers une autre adresse, le réseau rejettera la transaction faute de signature valide.
En cas d’erreur, utilisez Solscan pour consulter le journal du programme:
- Ouvrez l’historique de votre portefeuille et copiez la signature (hash) de la transaction échouée.
- Collez la signature sur Solscan.
- Observez la bannière de statut en haut (marquée Failed ou Instruction Error).
- Faites défiler jusqu’à la section Program Logs.
- Recherchez les codes d’erreur explicites:
custom program error: 0x1 (Solde SOL insuffisant pour le loyer ou le transfert).BlockhashNotFound (La transaction a mis trop de temps à être diffusée).ConstraintRaw ou InvalidAccountData (Erreur de clé d’autorité ou compte non initialisé).
Guide de dépannage rapide
Utilisez cette liste de contrôle si une transaction de token échoue:
| Symptôme / Message d’erreur |
Cause principale |
Solution |
| Transaction Failed: Custom Error 0x1 |
Le portefeuille manque de SOL natif pour le loyer. |
Ajoutez au moins 0,02 SOL natif sur votre portefeuille puis réessayez. |
| Blockhash Not Found / Timed Out |
Congestion RPC ou retard de diffusion. |
Actualisez la page pour obtenir un nouveau blockhash puis renvoyez. |
| Account Does Not Exist |
Le compte ATA destinataire n’est pas créé. |
Vérifiez que la transaction inclut l’instruction de création de l’ATA. |
| Signature Verification Failed |
Le portefeuille connecté n’est pas l’autorité actuelle. |
Connectez l’adresse de portefeuille exacte déténant la clé d’autorité. |
| Le volet du portefeuille se ferme seul |
Conflit d’extensions ou blocage du navigateur. |
Déverrouillez le portefeuille manuellement, désactivez les extensions et réessayez. |
Comprendre la mécanique des transactions, conserver suffisamment de SOL pour l’exemption de loyer et consulter les journaux Solscan garantit des opérations fluides et sans erreur sur Solana.