Como Usar getSignatureStatuses

O método RPC getSignatureStatuses permite que você recupere o status de processamento e confirmação de uma lista de assinaturas de transações. Isso é útil para determinar se as transações foram processadas, confirmadas ou finalizadas pela rede. A menos que a opção searchTransactionHistory esteja ativada, este método consulta principalmente um cache de status recente no nó RPC. Para transações mais antigas, ativar searchTransactionHistory é crucial.

Evite Lotes para Melhor DesempenhoAgrupar métodos de arquivamento aumenta significativamente a latência. Lotes com mais de 10 solicitações não são permitidos.

Casos de Uso Comuns

Confirmando a Finalidade da Transação: Verificar se uma transação enviada alcançou o nível de confirmação desejado (por exemplo, confirmed ou finalized).
Verificação de Status em Lote: Verificar eficientemente o status de várias transações de uma vez, por exemplo, após um envio em lote.
Atualização da Interface com Base no Estado da Transação: Refletir o status em tempo real de uma transação para o usuário.
Verificação de Erro: Identificar se alguma das transações falhou e por quê.

Parâmetros de Solicitação

signatures (array de string): (Obrigatório) Uma matriz de assinaturas de transações codificadas em base-58. Você pode consultar até 256 assinaturas em uma única solicitação.
options (object, opcional): Um objeto de configuração opcional com o seguinte campo:
- searchTransactionHistory (boolean, opcional): Se true, o nó RPC buscará em todo o histórico de transações as assinaturas. Se false (o padrão), ele busca apenas em um cache de status recente. Para transações antigas ou potencialmente descartadas, defina este como true.

Estrutura da Resposta

O campo result da resposta JSON-RPC contém um objeto com dois campos:

context (object): Um objeto contendo:
- slot (u64): O slot no qual o nó RPC processou esta solicitação.
value (array de object | null): Uma matriz de objetos de status, correspondendo à ordem das assinaturas na solicitação. Cada elemento pode ser:
- Um objeto com os seguintes campos se a assinatura for encontrada:
  - slot (u64): O slot em que a transação foi processada.
  - confirmations (number | null): O número de blocos que foram confirmados desde que a transação foi processada. null se a transação estiver finalizada (uma vez que a finalidade implica que não será revertida, então uma contagem específica de confirmações não é tão relevante).
  - err (object | null): Um objeto de erro se a transação falhou (por exemplo, {"InstructionError":[0,{"Custom":1}]}), ou null se teve sucesso.
  - status (object): Um objeto indicando o status de execução da transação. Normalmente {"Ok":null} para transações bem-sucedidas ou um objeto detalhando o erro para aquelas que falharam.
  - confirmationStatus (string | null): O status de confirmação do cluster para a transação (por exemplo, processed, confirmed, finalized). Pode ser null se o status não estiver disponível no cache e searchTransactionHistory for falso.
- null: Se uma assinatura não for encontrada no cache de status e searchTransactionHistory for false (ou se realmente não existir mesmo com a busca no histórico).

Exemplos

1. Obter Status para uma Lista de Assinaturas (Cache Recente)

Este exemplo busca o status de duas assinaturas, confiando no cache recente do nó.

# 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. Obter Status com Busca no Histórico de Transações

Este exemplo busca o status das assinaturas e solicita explicitamente que o nó busque em seu histórico de transações.

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

Dicas para Desenvolvedores

searchTransactionHistory: Crucial para a confiabilidade. Se false (padrão), o método apenas verifica um cache recente limitado. Se uma transação for antiga ou potencialmente descartada e não estiver neste cache, retornará null para o status dessa assinatura. Sempre defina como true se precisar confirmar o status de transações que podem não ser muito recentes.
Limite de Assinaturas: Você pode consultar no máximo 256 assinaturas por chamada.
null Status: Um null no array value para uma determinada assinatura significa que seu status não foi encontrado. Isso pode ser porque não está no cache recente (se searchTransactionHistory é falso), a transação nunca foi registrada ou é muito antiga para o histórico do nó, mesmo com searchTransactionHistory: true.
confirmations: null: Isso geralmente significa que a transação alcançou o status finalized. Neste ponto, o conceito de um número específico de confirmações é menos relevante, pois o bloco é considerado irreversível.
Tratamento de Erros: Verifique o campo err dentro de cada objeto de status para ver se uma transação falhou. O campo status também fornecerá detalhes (por exemplo, {"Err":...}).

Usar getSignatureStatuses é uma forma eficiente de monitorar o estado de várias transações Solana. Lembre-se de usar searchTransactionHistory: true para uma verificação robusta de status.

Comece aqui

Dados em tempo real

Negociação de baixa latência

Dados históricos e de carteiras

Guias de métodos RPC

Preparação para produção

Como usar o Orb

Outros tutoriais

Como Usar getSignatureStatuses

Casos de Uso Comuns

Parâmetros de Solicitação

Estrutura da Resposta

Exemplos

1. Obter Status para uma Lista de Assinaturas (Cache Recente)

2. Obter Status com Busca no Histórico de Transações

Dicas para Desenvolvedores

​Casos de Uso Comuns

​Parâmetros de Solicitação

​Estrutura da Resposta

​Exemplos

​1. Obter Status para uma Lista de Assinaturas (Cache Recente)

​2. Obter Status com Busca no Histórico de Transações

​Dicas para Desenvolvedores

Casos de Uso Comuns

Parâmetros de Solicitação

Estrutura da Resposta

Exemplos

1. Obter Status para uma Lista de Assinaturas (Cache Recente)

2. Obter Status com Busca no Histórico de Transações

Dicas para Desenvolvedores