Skip to main content
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

  1. 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.
  2. 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ó.

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.

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.