Transactions Ethereum en attente : nonce, remplacement et annulation

Après la signature d’une transaction Ethereum, votre portefeuille peut l’envoyer à un client d’exécution ou à un service de transactions. Les nœuds qui l’acceptent peuvent la relayer à leurs pairs, puis un proposant de bloc peut l’inclure dans un bloc. Tant qu’elle n’est pas incluse, la transaction n’a pas modifié l’état canonique de la chaîne. Dans un portefeuille ou un explorateur, le statut « en attente » signifie généralement que le service connaît la transaction, mais ne l’a pas encore observée dans un bloc ; il ne désigne pas une file d’attente unique partagée par tout le réseau. Le guide des transactions d’Ethereum.org décrit le parcours entre la signature, la diffusion et l’inclusion dans un bloc.

Une transaction peut attendre pour plusieurs raisons. Ses plafonds de frais peuvent ne pas remplir les conditions d’inclusion dans un bloc, une transaction antérieure du même compte peut rester sans solution, un nœud peut ne pas l’avoir reçue ou le portefeuille peut afficher des informations obsolètes ou propres à un fournisseur. Chaque cause nécessite des vérifications différentes. Augmenter les frais ne corrige pas la sélection d’un mauvais réseau, et envoyer un second paiement sans vérifier le premier peut entraîner un doublon.

« En attente » ne signifie pas non plus « confirmée », « finalisée » ou « échouée ». Le hachage d’une transaction peut être visible avant qu’un reçu existe ; celui-ci est disponible une fois la transaction incluse. Les blocs Ethereum progressent ensuite au fil des états du consensus. Les portefeuilles et les explorateurs peuvent employer ces termes différemment. Vérifiez donc le hachage de la transaction, le bloc, le reçu et l’état actuel de la chaîne au lieu de vous fier à un libellé de statut succinct.

Un compte Ethereum ordinaire contrôlé par une clé externe (EOA) dispose d’une nonce qui ordonne ses transactions. La nonce est un compteur, pas des frais, un horodatage ni un hachage de transaction unique. Pour chaque compte, la chaîne n’accepte une transaction que si elle utilise la prochaine nonce attendue selon l’état du compte. Un même compte ne peut pas exécuter deux transactions ayant la même nonce sur la chaîne canonique. La documentation des comptes d’Ethereum.org décrit la nonce comme le compteur des transactions du compte et un mécanisme de protection contre les rejeux.

Supposons que la prochaine nonce inutilisée d’un compte soit 41. Sa prochaine transaction valide utilise la nonce 41 ; après son inclusion et son exécution, la suivante utilise la nonce 42. La nonce est liée au compte émetteur, pas à l’adresse de destination. Deux comptes différents peuvent chacun avoir une transaction numéro 41 au même moment, puisque chacun possède sa propre séquence.

Il est possible de signer une transaction avec une nonce supérieure à la nonce actuelle du compte sur la chaîne, mais elle ne peut pas sauter la séquence lors de son exécution. Il faut d’abord que la nonce antérieure manquante soit consommée. Une transaction dont la nonce a déjà été consommée par le compte est obsolète et ne peut plus être exécutée comme nouvelle transaction. Cet ordre permet au réseau de traiter les transactions de chaque compte dans la séquence, même si elles sont diffusées à des moments différents ou arrivent par des nœuds distincts.

La règle de nonce s’applique aux transactions EOA ordinaires sur la couche d’exécution d’Ethereum. Elle ne décrit pas toutes les abstractions de portefeuille, tous les séquenceurs de rollup ou toutes les chaînes. Les smart accounts peuvent ajouter leurs propres règles pour les opérations et les nonces, abordées plus loin dans ce guide.

Ethereum ne dispose pas d’une salle d’attente unique et synchronisée que chaque portefeuille, nœud, explorateur de blocs et proposant voit exactement de la même manière. Chaque client d’exécution conserve un pool local des transactions qu’il a reçues et qu’il estime admissibles selon ses propres limites et politiques. Une transaction peut figurer dans le pool d’un nœud et manquer dans celui d’un autre. La documentation RPC txpool de Geth présente les groupes locaux pending et queued de ce client et indique que plusieurs transactions peuvent être associées au même émetteur et à la même nonce.

Dans la terminologie de Geth, pending désigne généralement les transactions pouvant être traitées dans l’ordre des nonces à partir de l’état actuel du compte ; queued peut inclure des transactions ayant une nonce future qui attendent que l’écart soit comblé. Ces termes décrivent une interface client, pas des états de consensus que tous les logiciels Ethereum doivent afficher. Un portefeuille peut appeler « en attente » toute sa liste de transactions non confirmées, tandis qu’un explorateur peut n’afficher que celles observées par ses fournisseurs de données.

Par exemple, si un nœud connaît une transaction de nonce 41 et une autre de nonce 43, il ne peut pas exécuter la 43 avant la 42. Il peut garder la 43 en file jusqu’à l’arrivée de la 42 ou jusqu’à une autre progression de l’état du compte. Un autre nœud qui n’a jamais reçu la 43 ne l’affichera pas. C’est pourquoi deux explorateurs peuvent diverger sur le fait qu’une transaction soit en attente ou introuvable, sans qu’aucun des deux écrans prouve ce que tous les validateurs ont vu.

Certains clients autorisent aussi plusieurs transactions candidates non confirmées pour un même émetteur et une même nonce. Ce sont des solutions de remplacement concurrentes pour le même rang, pas deux transactions qui peuvent être appliquées l’une après l’autre. La capacité du pool, la durée de conservation des transactions et les règles de remplacement sont des politiques d’implémentation qui peuvent changer selon les versions du logiciel. Les options configurables du pool de transactions de Geth comprennent, par exemple, un seuil d’augmentation de prix propre à ce client ; il ne faut pas le prendre pour une règle générale de frais d’Ethereum. Consultez la référence des options de ligne de commande de Geth pour connaître la portée de ces options.

Imaginons que la prochaine nonce sur la chaîne d’un compte soit 41. Vous diffusez la transaction A avec la nonce 41, puis la transaction B avec la nonce 42. Tant que A n’est pas résolue, B ne peut pas être exécutée avant elle. B peut rester dans une file locale, apparaître en attente uniquement dans le portefeuille ou être absente d’un explorateur qui ne l’a pas reçue. Le point déterminant est l’ordre des nonces, pas l’ordre dans lequel le portefeuille a créé ou affiché les deux transactions.

Si A est finalement incluse, la nonce du compte passe à 42 et B peut alors devenir admissible, sous réserve de sa validité, de ses frais et des politiques du pool. Si A est remplacée par une autre transaction valide de nonce 41, le remplacement occupe le même rang s’il est inclus. Si une autre transaction du compte a consommé la nonce 41, l’ancienne candidate de nonce 41 est obsolète et ne peut plus être exécutée.

C’est pourquoi envoyer une nouvelle transaction avec une nonce supérieure n’est pas une méthode générale pour débloquer une transaction bloquée. Cela ajoute une autre transaction derrière l’écart. Annuler B ne résout pas non plus A si B est déjà la transaction ultérieure. Commencez par la nonce non résolue la plus basse du compte et vérifiez son statut avant toute modification.

L’écart peut être temporaire ou persistant. La transaction précédente n’a peut-être pas atteint le nœud que vous consultez, ses paramètres de frais peuvent être peu attractifs ou insuffisants dans les conditions actuelles, ou elle a pu être retirée du pool d’un nœud. Un portefeuille peut aussi afficher une transaction en file créée sur un autre appareil. L’écran seul ne permet pas de savoir ce qui s’est produit ; comparez la nonce confirmée du compte, les hachages des transactions et plusieurs vues fiables.

L’ordre des nonces et l’admissibilité des frais sont deux contraintes distinctes. Une transaction ayant la prochaine nonce correcte peut encore attendre si ses paramètres de frais ne remplissent pas les conditions d’inclusion dans un bloc. Une transaction de nonce supérieure ne peut pas passer devant en proposant simplement un pourboire plus élevé. Augmenter les frais de la nonce 42 ne fait pas disparaître la nonce 41.

Pour une transaction EIP-1559 standard, les frais maximum doivent pouvoir couvrir les frais de base du bloc qui l’inclut, et les frais prioritaires peuvent influer sur le choix du proposant de bloc. Les frais de base et l’espace disponible dans les blocs peuvent changer pendant l’attente. Les frais maximum constituent un plafond ; les augmenter ne garantit pas un délai précis de confirmation. Le guide des frais de gas d’Ethereum explique ces champs et la détermination des frais effectifs.

Un nœud ou un portefeuille peut appliquer des règles supplémentaires de relais ou de remplacement. Ces politiques déterminent ce que le service concerné accepte ou transmet ; elles ne relèvent pas toutes du consensus. Geth expose, par exemple, un seuil d’augmentation de prix configurable pour remplacer une transaction en attente dans son propre pool. Un autre client, fournisseur, portefeuille ou version du logiciel peut se comporter différemment. Ne vous fiez pas à un pourcentage mémorisé ou à un délai d’attente fixe comme à une garantie valable pour tout le réseau.

Si votre transaction attend parce qu’une nonce inférieure n’est pas résolue, identifiez d’abord la transaction qui utilise cette nonce. Si elle attend parce que son plafond de frais ne couvre pas les conditions actuelles des frais de base, comprenez les champs de frais avant de les modifier. Le guide des frais de gas d’Ethereum est le complément adapté aux calculs ; cet article porte sur le problème distinct de séquencement.

La fonction « accélérer » d’un portefeuille crée généralement une nouvelle transaction du même compte, avec la même nonce et des paramètres de frais ajustés. Les deux candidates entrent en conflit, car le compte ne peut exécuter qu’une transaction pour cette nonce. Si le remplacement est accepté dans les pools concernés puis inclus, il peut occuper le rang de la nonce ; la transaction d’origine ne peut alors pas être exécutée elle aussi sur la chaîne canonique. Le guide de MetaMask sur les transactions en attente décrit sa fonction d’accélération comme une nouvelle soumission avec la même nonce et des frais plus élevés.

Le remplacement peut conserver la destination et l’action de la transaction d’origine tout en modifiant les champs de frais, mais examinez l’écran de signature au lieu de le supposer. Une implémentation de portefeuille peut présenter d’autres champs ou nommer cette option autrement. Avant de signer un remplacement, vérifiez le compte émetteur, la nonce, la destination, la valeur et les données du contrat. Si le remplacement change ce que fera la transaction, il ne s’agit pas d’un simple ajustement de frais sans conséquence.

Le remplacement n’est pas assuré d’être accepté partout ni d’être inclus rapidement. La transaction d’origine a peut-être déjà été incluse ; un nœud peut refuser le remplacement selon sa politique ; celui-ci peut rester peu intéressant pour un proposant ; ou le service peut ne pas le relayer aux nœuds que vous surveillez. Si la transaction d’origine est déjà confirmée, une nouvelle transaction utilisant la nonce consommée ne peut pas l’annuler et sera généralement rejetée comme obsolète.

Ici, « remplacement » désigne une transaction concurrente émise par le même compte avec la même nonce. N’appliquez pas à Ethereum les procédures RBF ou CPFP de Bitcoin. Bitcoin utilise un modèle de transaction différent, et ses mécanismes d’augmentation des frais ne sont pas des instructions pour les comptes Ethereum.

Une fois une transaction Ethereum signée diffusée, aucune commande d’annulation au niveau du protocole ne la retire de tous les nœuds. Certains portefeuilles proposent une option d’annulation tant que la transaction n’est pas confirmée. Cette option tente généralement de publier une transaction différente du même compte avec la même nonce ; un modèle courant dans certains portefeuilles consiste à envoyer une transaction de valeur nulle à sa propre adresse d’émetteur. Si la candidate d’annulation est acceptée et incluse avant l’originale, elle consomme la nonce et rend la candidate initiale invalide pour une exécution ultérieure. La construction exacte et la disponibilité de cette option dépendent du portefeuille.

La transaction d’origine et la candidate d’annulation peuvent entrer en concurrence. Si l’originale est incluse en premier, une annulation envoyée ensuite ne peut pas en annuler les effets. Si aucune des deux candidates n’est acceptée ou incluse, la nonce peut rester non résolue. Un clic sur le bouton du portefeuille ou un message de réussite ne prouve pas que l’annulation a gagné. Vérifiez le hachage de la transaction obtenue et l’état canonique de la chaîne. Les instructions de MetaMask précisent que sa tentative d’annulation concerne uniquement une transaction encore en attente et qu’une transaction confirmée ne peut pas être annulée.

Avant de signer une transaction d’annulation, vérifiez qu’elle utilise le même compte et la même nonce que la transaction que vous souhaitez écarter, puis examinez tous les champs affichés par le portefeuille. Une autre commission réseau peut être nécessaire si elle est incluse. La candidate d’annulation peut elle-même attendre ou échouer à remplacer l’originale selon les politiques du pool concerné. La mention « annulée » dans un portefeuille ne prouve pas une annulation au niveau du protocole ; vérifiez quelle transaction a consommé la nonce avant de conclure.

Si la transaction a déjà exécuté une approbation de jeton, un appel de contrat ou un transfert, annuler une transaction ultérieure ne peut pas revenir sur ce changement d’état achevé. Certaines actions de contrat ont des méthodes de suivi distinctes, mais leur disponibilité et leurs effets dépendent du contrat. Ne signez pas une transaction inconnue simplement parce qu’une interface la désigne comme une annulation.

Une transaction incluse possède un bloc et un reçu. Si elle réussit, les changements d’état prévus ont pu être appliqués. Si l’exécution de l’EVM est annulée, les changements d’état de cette exécution sont restaurés, mais la transaction a quand même consommé la nonce du compte et peut entraîner des frais de gas. Consultez le reçu et le statut d’exécution au lieu de déduire la réussite d’une notification du portefeuille. Le guide des transactions d’Ethereum et le guide des frais de gas expliquent la différence entre inclusion et résultat de l’exécution.

Une étiquette « abandonnée » ou « introuvable » rend souvent compte de ce qu’observe un seul portefeuille, explorateur, fournisseur RPC ou pool local. Elle ne prouve pas à elle seule que le protocole a annulé la transaction ni que la nonce est libre. Un autre nœud peut encore la connaître ; le portefeuille peut rediffuser la transaction signée ; ou un bloc ultérieur peut révéler que la nonce du compte a déjà avancé. À l’inverse, une ancienne transaction peut être absente des vues consultées alors que la nonce confirmée du compte reste inchangée.

Si vous ne trouvez pas le hachage d’une transaction, vérifiez que vous avez sélectionné la même chaîne et le même compte émetteur que lors de sa création. Comparez la nonce actuelle du compte sur la chaîne à celle de la transaction et examinez les transactions récentes de cet émetteur. Une réponse nonce too low indique que la nonce a peut-être déjà été consommée du point de vue du point de terminaison ; ce n’est pas une raison pour répéter la même requête. Vérifiez quelle transaction l’a utilisée et si son bloc appartient toujours à la chaîne canonique.

Une transaction incluse peut aussi être touchée par une réorganisation de courte durée avant la stabilisation de la chaîne. Les portefeuilles et les explorateurs peuvent mettre à jour leurs libellés lorsque leur vue change. Pour un transfert important, attendez le nombre de confirmations exigé par le service destinataire et, le cas échéant, une finalité de consensus plus forte. « Vue dans un bloc » et « irréversible en toute circonstance » ne sont pas des affirmations équivalentes.

Commencez par confirmer la chaîne, le compte émetteur et le hachage de la transaction. Recherchez ce hachage dans un explorateur fiable pour le bon réseau. Vérifiez s’il a un reçu, quelle nonce il utilise, si l’exécution a réussi et si le compte a envoyé une transaction ultérieure. Ne révélez pas et ne saisissez pas votre phrase de récupération pour vérifier une transaction ; une adresse publique et un hachage suffisent pour consulter les informations d’une chaîne publique.

Si le hachage ne s’affiche pas, comparez la dernière nonce confirmée du compte avec celle indiquée par votre portefeuille. Un développeur ou un opérateur de nœud peut interroger eth_getTransactionCount avec les balises de bloc latest et pending. La référence JSON-RPC d’Ethereum.org définit ces balises : latest renvoie l’état du dernier bloc et pending l’état en attente. Le résultat pending dépend toujours de la vue du point de terminaison RPC ; deux fournisseurs peuvent renvoyer des valeurs différentes. La plupart des utilisateurs peuvent obtenir les premiers indices de la même façon dans l’activité de leur compte et sur un explorateur fiable, sans exécuter de commandes.

Travaillez ensuite à partir de la nonce la plus basse qui n’a pas été consommée. Si la transaction d’origine reste visible et que le portefeuille prend en charge le remplacement, examinez précisément les champs et les paramètres de frais du remplacement avant de le signer. Si elle n’est pas visible, demandez au portefeuille ou au fournisseur RPC comment il gère la rediffusion et le remplacement au lieu de supposer que la transaction a disparu du réseau. Si la nonce a déjà été consommée, identifiez la transaction incluse avant toute autre action. Évitez d’envoyer à répétition de nouvelles transactions avec des nonces ultérieures ; cela peut allonger la file sans combler le premier écart.

Ces étapes concernent les transactions ordinaires de comptes Ethereum externes. Les systèmes d’abstraction de compte peuvent envoyer des UserOperations via des bundlers, et leurs smart accounts peuvent utiliser des clés et des séquences de nonce plus complexes qu’un compteur unique. EIP-4337 définit une structure de nonce pour ces opérations ; un portefeuille utilisant l’abstraction de compte peut donc se comporter autrement que les exemples EOA de cet article. Pour les réseaux de destination, les adresses et le statut des transferts, consultez la liste de vérification des transferts de cryptoactifs.