La méthode RPC getSignatureStatuses vous permet de récupérer l’état de traitement et de confirmation d’une liste de signatures de transactions. Ceci est utile pour déterminer si les transactions ont été traitées, confirmées ou finalisées par le réseau.
À moins que l’option searchTransactionHistory ne soit activée, cette méthode interroge principalement un cache d’état récent sur le nœud RPC. Pour les transactions plus anciennes, l’activation de searchTransactionHistory est cruciale.
Évitez le traitement par lots pour de meilleures performancesLe traitement par lots des méthodes d’archivage augmente significativement la latence. Les lots de plus de 10 requêtes ne sont pas autorisés.
Cas d’utilisation courants
- Confirmation de la finalité de la transaction : Vérifier si une transaction soumise a atteint un niveau de confirmation désiré (par exemple,
confirmed ou finalized).
- Recherche de statut par lots : Vérifier efficacement le statut de plusieurs transactions à la fois, par exemple, après un envoi par lots.
- Mise à jour de l’interface utilisateur en fonction de l’état de la transaction : Refléter le statut en temps réel d’une transaction à l’utilisateur.
- Vérification des erreurs : Identifier si une liste de transactions a échoué et pourquoi.
Paramètres de requête
signatures (array de string): (Obligatoire) Un tableau de signatures de transactions encodées en base-58. Vous pouvez interroger jusqu’à 256 signatures en une seule requête.
options (object, optionnel): Un objet de configuration optionnel avec le champ suivant :
searchTransactionHistory (boolean, optionnel): Si true, le nœud RPC recherchera son historique complet de transactions pour les signatures. Si false (par défaut), il ne recherche qu’un cache d’état récent. Pour les transactions anciennes ou potentiellement rejetées, réglez ceci à true.
Structure de la réponse
Le champ result de la réponse JSON-RPC contient un objet avec deux champs :
context (object): Un objet contenant :
slot (u64): La tranche dans laquelle le nœud RPC a traité cette requête.
value (array de object | null): Un tableau d’objets statut, correspondant à l’ordre des signatures dans la requête. Chaque élément peut être :
- Un objet avec les champs suivants si la signature est trouvée :
slot (u64): La tranche dans laquelle la transaction a été traitée.
confirmations (number | null): Le nombre de blocs qui ont été confirmés depuis que la transaction a été traitée. null si la transaction est finalisée (puisque la finalité signifie qu’elle ne sera pas annulée, un nombre spécifique de confirmations n’est pas aussi pertinent).
err (object | null): Un objet erreur si la transaction a échoué (par exemple, {"InstructionError":[0,{"Custom":1}]}), ou null si elle a réussi.
status (object): Un objet indiquant le statut d’exécution de la transaction. Habituellement {"Ok":null} pour les transactions réussies ou un objet détaillant l’erreur pour celles qui ont échoué.
confirmationStatus (string | null): Le statut de confirmation du cluster pour la transaction (par exemple, processed, confirmed, finalized). Peut être null si le statut n’est pas disponible dans le cache et que searchTransactionHistory est false.
null: Si une signature n’est pas trouvée dans le cache d’état et que searchTransactionHistory est false (ou si elle n’existe vraiment pas même avec la recherche historique).
Exemples
1. Obtenir le statut pour une liste de signatures (Cache récent)
Cet exemple récupère le statut pour deux signatures, en se basant sur le cache récent du nœud.
2. Obtenir le statut avec la recherche d’historique des transactions
Cet exemple récupère le statut des signatures et demande explicitement au nœud de rechercher dans son historique des transactions.
Conseils pour les développeurs
searchTransactionHistory: Crucial pour la fiabilité. Si false (par défaut), la méthode vérifie uniquement un cache récent limité. Si une transaction est ancienne ou a potentiellement été rejetée et n’est pas dans ce cache, cela retournera null pour le statut de cette signature. Toujours définir à true si vous devez confirmer le statut de transactions qui pourraient ne pas être très récentes.
- Limite de signature : Vous pouvez interroger un maximum de 256 signatures par appel.
- Statut
null : Un null dans le tableau value pour une signature donnée signifie que son statut n’a pas été trouvé. Cela pourrait être parce qu’il n’est pas dans le cache récent (si searchTransactionHistory est false), que la transaction n’a jamais été validée, ou qu’elle est trop ancienne pour l’historique du nœud même avec searchTransactionHistory: true.
confirmations: null: Cela signifie généralement que la transaction a atteint le statut finalized. À ce stade, le concept d’un nombre spécifique de confirmations est moins pertinent car le bloc est considéré comme irréversible.
- Gestion des erreurs : Vérifiez le champ
err dans chaque objet statut pour voir si une transaction a échoué. Le champ status fournira également des détails (par exemple, {"Err":...}).
Utiliser getSignatureStatuses est un moyen efficace de surveiller l’état de plusieurs transactions Solana. N’oubliez pas d’utiliser searchTransactionHistory: true pour une vérification de statut robuste.