Cómo usar getSignatureStatuses

El método RPC getSignatureStatuses te permite obtener el estado de procesamiento y confirmación de una lista de firmas de transacciones. Esto resulta útil para determinar si la red ha procesado, confirmado o finalizado las transacciones. A menos que la opción searchTransactionHistory esté habilitada, este método consulta principalmente una caché de estados recientes en el nodo RPC. Para transacciones más antiguas, es fundamental habilitar searchTransactionHistory.

Evita agrupar solicitudes para mejorar el rendimientoAgrupar métodos de archivo aumenta considerablemente la latencia. No se permiten lotes de más de 10 solicitudes.

Casos de uso comunes

Confirmar la finalidad de una transacción: Verifica si una transacción enviada alcanzó el nivel de confirmación deseado (p. ej., confirmed o finalized).
Consultar estados por lotes: Comprueba de forma eficiente el estado de varias transacciones a la vez, por ejemplo, después de un envío por lotes.
Actualizar la interfaz según el estado de la transacción: Muestra al usuario el estado de una transacción en tiempo real.
Comprobar errores: Identifica si alguna de las transacciones de una lista falló y por qué.

Parámetros de la solicitud

signatures (array de string): (Obligatorio) Un arreglo de firmas de transacciones codificadas en base 58. Puedes consultar hasta 256 firmas en una sola solicitud.
options (object, opcional): Un objeto de configuración opcional con el siguiente campo:
- searchTransactionHistory (boolean, opcional): Si es true, el nodo RPC buscará las firmas en todo su historial de transacciones. Si es false (el valor predeterminado), solo buscará en una caché de estados recientes. Para transacciones antiguas o que podrían haberse descartado, establece este valor en true.

Estructura de la respuesta

El campo result de la respuesta JSON-RPC contiene un objeto con dos campos:

context (object): Un objeto que contiene:
- slot (u64): El slot en el que el nodo RPC procesó esta solicitud.
value (array de object | null): Un arreglo de objetos de estado que corresponde al orden de las firmas en la solicitud. Cada elemento puede ser:
- Un objeto con los siguientes campos si se encuentra la firma:
  - slot (u64): El slot en el que se procesó la transacción.
  - confirmations (number | null): La cantidad de bloques confirmados desde que se procesó la transacción. Es null si la transacción está finalizada (como la finalidad implica que no se revertirá, una cantidad específica de confirmaciones no resulta tan relevante).
  - err (object | null): Un objeto de error si la transacción falló (p. ej., {"InstructionError":[0,{"Custom":1}]}) o null si se completó correctamente.
  - status (object): Un objeto que indica el estado de ejecución de la transacción. Por lo general, es {"Ok":null} para transacciones completadas correctamente o un objeto que detalla el error para las transacciones fallidas.
  - confirmationStatus (string | null): El estado de confirmación del clúster para la transacción (p. ej., processed, confirmed, finalized). Puede ser null si el estado no está disponible en la caché y searchTransactionHistory es false.
- null: Si no se encuentra una firma en la caché de estados y searchTransactionHistory es false (o si realmente no existe ni siquiera al buscar en el historial).

Ejemplos

1. Obtener el estado de una lista de firmas (caché reciente)

Este ejemplo obtiene el estado de dos firmas mediante la caché reciente del nodo.

# 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. Obtener el estado mediante una búsqueda en el historial de transacciones

Este ejemplo obtiene el estado de varias firmas y solicita explícitamente al nodo que busque en su historial de transacciones.

# 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();

Consejos para desarrolladores

searchTransactionHistory: Es fundamental para garantizar la fiabilidad. Si es false (valor predeterminado), el método solo consulta una caché reciente limitada. Si una transacción es antigua o pudo haberse descartado y no está en esta caché, devolverá null como estado de esa firma. Establécelo siempre en true si necesitas confirmar el estado de transacciones que podrían no ser muy recientes.
Límite de firmas: Puedes consultar un máximo de 256 firmas por llamada.
Estado null: Un valor null en el arreglo value para una firma determinada significa que no se encontró su estado. Esto podría deberse a que no está en la caché reciente (si searchTransactionHistory es false), a que la transacción nunca se incluyó o a que es demasiado antigua para el historial del nodo, incluso con searchTransactionHistory: true.
confirmations: null: Esto suele significar que la transacción alcanzó el estado finalized. En este punto, el concepto de una cantidad específica de confirmaciones es menos relevante porque el bloque se considera irreversible.
Manejo de errores: Revisa el campo err dentro de cada objeto de estado para comprobar si una transacción falló. El campo status también proporcionará detalles (p. ej., {"Err":...}).

Usar getSignatureStatuses es una forma eficiente de supervisar el estado de varias transacciones de Solana. Recuerda usar searchTransactionHistory: true para comprobar el estado de forma fiable.

Empieza aquí

Datos en tiempo real

Trading de baja latencia

Datos históricos y de billeteras

Guías de métodos RPC

Preparación para producción

Uso de Orb

Otras guías prácticas

Cómo usar getSignatureStatuses

Casos de uso comunes

Parámetros de la solicitud

Estructura de la respuesta

Ejemplos

1. Obtener el estado de una lista de firmas (caché reciente)

2. Obtener el estado mediante una búsqueda en el historial de transacciones

Consejos para desarrolladores

​Casos de uso comunes

​Parámetros de la solicitud

​Estructura de la respuesta

​Ejemplos

​1. Obtener el estado de una lista de firmas (caché reciente)

​2. Obtener el estado mediante una búsqueda en el historial de transacciones

​Consejos para desarrolladores

Casos de uso comunes

Parámetros de la solicitud

Estructura de la respuesta

Ejemplos

1. Obtener el estado de una lista de firmas (caché reciente)

2. Obtener el estado mediante una búsqueda en el historial de transacciones

Consejos para desarrolladores