Comment utiliser getSignatureStatuses

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.

# Replace <api-key> with your Helius API key
# Replace with actual transaction signatures
curl https://mainnet.helius-rpc.com/?api-key=<api-key> -X POST -H "Content-Type: application/json" -d \
  '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "getSignatureStatuses",
    "params": [
      [
        "5VERv8NMvzbJMEkV8xnrLkEaWRtSz9CosKDYjCJjBRnbJLgp8uirBgmQpjKhoR4tjF3ZpRzrFmBV6UjKdiSZkQUW",
        "2x5YfV29N4p9K2kEFK2gFfC5T5acbs2z2MytTZqrgq17pYjCMfYjW4sAUpkWMkMzxGztD2Qv5v7n92uYJcQY9c7a" 
      ]
    ]
  }'

// Replace <api-key> with your Helius API key
const { Connection } = require('@solana/web3.js');

async function checkRecentSignatures() {
  const connection = new Connection('https://mainnet.helius-rpc.com/?api-key=<api-key>');
  const signatures = [
    '5VERv8NMvzbJMEkV8xnrLkEaWRtSz9CosKDYjCJjBRnbJLgp8uirBgmQpjKhoR4tjF3ZpRzrFmBV6UjKdiSZkQUW',
    '2x5YfV29N4p9K2kEFK2gFfC5T5acbs2z2MytTZqrgq17pYjCMfYjW4sAUpkWMkMzxGztD2Qv5v7n92uYJcQY9c7a' // Replace with another signature
  ];

  try {
    const response = await connection.getSignatureStatuses(signatures);
    console.log("RPC Response Context Slot:", response.context.slot);
    response.value.forEach((status, index) => {
      console.log(`--- Status for Signature ${index + 1} (${signatures[index].substring(0,10)}...) ---`);
      if (status) {
        console.log(`  Slot: ${status.slot}`);
        console.log(`  Confirmations: ${status.confirmations === null ? 'Finalized (or N/A)' : status.confirmations}`);
        console.log(`  Error: ${JSON.stringify(status.err)}`);
        console.log(`  Execution Status: ${JSON.stringify(status.status)}`);
        console.log(`  Confirmation Status: ${status.confirmationStatus}`);
      } else {
        console.log('  Status not found (likely not in recent cache or does not exist).');
      }
    });
  } catch (error) {
    console.error('Error fetching signature statuses:', error);
  }
}

checkRecentSignatures();

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.

# Replace <api-key> with your Helius API key
# Replace with actual transaction signatures
curl https://mainnet.helius-rpc.com/?api-key=<api-key> -X POST -H "Content-Type: application/json" -d \
  '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "getSignatureStatuses",
    "params": [
      [
        "3jPTfHcbzWHeD4jW8q4Y8g3h2D1aBwM81y1sHhDqYQ7Z9x5n7cVy2gD8QWbK9eXwSjJ6aA7FzV2kLpQoEwU9jX", 
        "4SyzjM2fTALqTNjLKMM1yG1bW7kCFu2GvEkKcvKChG9o1KjQW8jLdZ6sWfN9mP1pU3rD7XvA6B2CjHkLwRzYxTnX"  
      ],
      {
        "searchTransactionHistory": true
      }
    ]
  }'

// Replace <api-key> with your Helius API key
const { Connection } = require('@solana/web3.js');

async function checkSignaturesWithHistory() {
  const connection = new Connection('https://mainnet.helius-rpc.com/?api-key=<api-key>');
  const signatures = [
    // Replace with a signature you know is older or might have been dropped
    '3jPTfHcbzWHeD4jW8q4Y8g3h2D1aBwM81y1sHhDqYQ7Z9x5n7cVy2gD8QWbK9eXwSjJ6aA7FzV2kLpQoEwU9jX',
    // Replace with another valid signature
    '4SyzjM2fTALqTNjLKMM1yG1bW7kCFu2GvEkKcvKChG9o1KjQW8jLdZ6sWfN9mP1pU3rD7XvA6B2CjHkLwRzYxTnX' 
  ];

  try {
    const response = await connection.getSignatureStatuses(signatures, { searchTransactionHistory: true });
    console.log("RPC Response Context Slot:", response.context.slot);
    response.value.forEach((status, index) => {
      console.log(`--- Status for Signature ${index + 1} (${signatures[index].substring(0,10)}...) ---`);
      if (status) {
        console.log(`  Slot: ${status.slot}`);
        console.log(`  Confirmations: ${status.confirmations === null ? 'Finalized (or N/A)' : status.confirmations}`);
        console.log(`  Error: ${JSON.stringify(status.err)}`);
        console.log(`  Execution Status: ${JSON.stringify(status.status)}`);
        console.log(`  Confirmation Status: ${status.confirmationStatus}`);
      } else {
        console.log('  Status not found (even with history search, it might not exist or is too old).');
      }
    });
  } catch (error) {
    console.error('Error fetching signature statuses with history:', error);
  }
}

checkSignaturesWithHistory();

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.

Commencer ici

Données en temps réel

Trading à faible latence

Données historiques et de portefeuilles

Guides des méthodes RPC

Préparation à la production

Utilisation d’Orb

Autres guides pratiques

Comment utiliser getSignatureStatuses

Cas d’utilisation courants

Paramètres de requête

Structure de la réponse

Exemples

1. Obtenir le statut pour une liste de signatures (Cache récent)

2. Obtenir le statut avec la recherche d’historique des transactions

Conseils pour les développeurs

​Cas d’utilisation courants

​Paramètres de requête

​Structure de la réponse

​Exemples

​1. Obtenir le statut pour une liste de signatures (Cache récent)

​2. Obtenir le statut avec la recherche d’historique des transactions

​Conseils pour les développeurs

Cas d’utilisation courants

Paramètres de requête

Structure de la réponse

Exemples

1. Obtenir le statut pour une liste de signatures (Cache récent)

2. Obtenir le statut avec la recherche d’historique des transactions

Conseils pour les développeurs