Crie seu próprio cliente

Este guia oferece recomendações para garantir que as implementações do cliente do Universal Ledger interajam com uma rede de forma segura e confiável. Saiba como realizar as seguintes ações:

  • Aproveite a topologia de rede para alta disponibilidade.
  • Enviar transações e entender os resultados da execução.
  • Implemente estratégias de pesquisa, tempos limite e novas tentativas.

Topologia de rede e alta disponibilidade

Uma rede de Universal Ledger é composta por vários validadores distribuídos entre várias zonas e regiões, garantindo assim alta disponibilidade para a rede como um todo.

  • Falhas na zona:se um único validador falhar em uma zona do Cloud, outros validadores na mesma região continuarão processando solicitações sem problemas.

  • Interrupções regionais:se uma região inteira ficar indisponível, os validadores em outras regiões vão continuar funcionando. Para continuar enviando transações, é seguro para seu cliente fazer fallback e tentar reenviar transações por um endpoint diferente.

Características de execução da transação

  • Execução atômica:as transações são totalmente bem-sucedidas ou totalmente falhas. A execução parcial de transações, como a transferência de apenas uma parte dos fundos solicitados devido a um saldo insuficiente, nunca ocorre. Isso inclui cadeias de transações, permitindo combinar várias transações arbitrárias em uma única sequência atômica.

  • Sem novas tentativas automáticas:a rede tenta executar uma transação enviada exatamente uma vez. Se a execução falhar, o razão não vai enfileirar nem tentar novamente a transação automaticamente.

  • Reenvio idempotente:cada transação enviada gera um ID exclusivo com base na carga útil serializada exata (incluindo número de sequência e remetente). Enviar o mesmo payload várias vezes produz o mesmo ID da transação. O razão garante que uma transação seja executada no máximo uma vez, tornando seguro reenviar a mesma carga útil de transação para um endpoint diferente se um deles parecer indisponível.

    Para mais detalhes, consulte a página de referência SubmitTransactionRequest.

Latência, pesquisa e estratégia de novas tentativas

Quando você envia uma transação, o validador primeiro faz uma verificação rápida para garantir que as assinaturas e os números de sequência sejam válidos. Se for bem-sucedida, a API Universal Ledger vai responder imediatamente com um SubmitTransactionResponse incluindo o ID de transação atribuído.

A maioria das transações é concluída em até 3 segundos. Para verificar o status da transação, faça uma pesquisa do método QueryTransactionState usando o ID da transação fornecido.

  • Se o status da transação ainda for PENDING, recupere-o novamente usando uma estratégia de espera exponencial. Por exemplo, consulte em intervalos de 3 segundos, 9 segundos, 27 segundos e 60 segundos.

  • Se QueryTransactionState retornar NOT_FOUND, reenvie a transação.

Quando uma tentativa de transação for FINALIZED, a resposta também vai incluir um TransactionCertificate com vários detalhes, como:

  • O ID da rodada em que a transação foi concluída.
  • O status da execução (OK ou falha).
  • Eventos de transação, incluindo saídas de transação.

Protocolo de tempo limite

Na improvável situação de uma transação permanecer no estado PENDING ou NOT_FOUND após 60 segundos, suponha que o validador que atende às suas solicitações não esteja acompanhando outros validadores na rede. Conclua as etapas a seguir:

  1. Selecione um endpoint diferente em uma região de rede diferente.
  2. Envie novamente o mesmo payload de transação assinada.
  3. Envie um e-mail para gcul-help@google.com para que a equipe do Universal Ledger investigue o problema.

Ao verificar o status da transação, a resposta pode incluir várias mensagens TransactionAttempt se você enviou o mesmo payload várias vezes. No máximo, uma tentativa será finalizada com um status de transação OK, encontrado em TransactionEffects, enquanto outras tentativas ficarão pendentes ou terão um status de falha. Esse é o comportamento esperado. O razão executou com sucesso um dos envios de transação e rejeitou corretamente, ou vai rejeitar, os reenvios duplicados.

Consistência da rede

  • Transações finalizadas:quando uma transação é informada como finalizada por um validador, espera-se que todos os outros validadores na mesma rede processem a transação e reproduzam exatamente os mesmos resultados. Enviar um QueryAccountRequest usando o ID da rodada em que a transação foi finalizada, conforme pode ser encontrado no TransactionCertificate, gera resultados idênticos em todos os validadores sincronizados.

  • Transações não finalizadas:como as transações são propagadas pela rede de forma assíncrona, a finalização de uma transação pode variar entre diferentes validadores.

    Um validador que está se recuperando de uma interrupção ou passando por um atraso de sincronização pode informar temporariamente uma transação finalizada como PENDING ou NOT_FOUND. O status da transação será resolvido assim que o validador for atualizado.

Responsabilidades do cliente e tratamento de erros

  • Acompanhamento de transações:os aplicativos cliente precisam acompanhar o estado de todas as transações enviadas até que sejam concluídas.

  • Tratamento de erros:se uma transação falhar, recupere e inspecione os detalhes da falha incluídos no TransactionCertificate para acionar a correção adequada no nível comercial.

A seguir