Diretrizes de implementação do cliente

Este guia fornece diretrizes de arquitetura e implementação para desenvolvedores que criam clientes da API Universal Ledger. 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.
  • Implementar estratégias de sondagem, tempos limite e novas tentativas.

Como se conectar a um endpoint de API do Universal Ledger

As solicitações são roteadas pela API Universal Ledger para um endpoint de rede específico. Os endpoints de rede são recursos regionais do Cloud que distribuem solicitações para validadores dentro dessa região. Para acessar um endpoint de rede, os clientes precisam se conectar ao endpoint de API regional (REP, na sigla em inglês) que corresponde à região do Cloud em que esse endpoint de rede está localizado.

Os nomes dos endpoints regionais seguem este formato:

universalledger.REGION.rep.googleapis.com

Substitua REGION pela região com disponibilidade em que o endpoint de rede está localizado.

Topologia de rede e alta disponibilidade

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

  • Falhas de zona: se um único validador falhar em uma zona do Cloud, outros validadores na mesma região vão continuar 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 operacionais. Para continuar enviando transações, é seguro que o cliente volte atrás e tente reenviar as 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 malsucedidas. 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, que permitem 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 livro não colocará a transação em fila nem tentará realizá-la novamente de forma automática.

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

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

Latência, sondagem e estratégia de repetição

Quando você envia uma transação, o validador primeiro realiza 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 da transação atribuído.

A maioria das transações é finalizada em até 3 segundos. Para verificar o status da transação, pesquise o método QueryTransactionState usando o ID da transação fornecido.

  • Se o status da transação ainda for PENDING, recupere o status 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 é FINALIZED, a resposta também inclui um TransactionCertificate com vários detalhes, como:

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

Protocolo de tempo limite

No caso improvável de uma transação permanecer em um estado PENDING ou NOT_FOUND após 60 segundos, presuma que o validador que atende às suas solicitações não está conseguindo acompanhar os outros validadores na rede. Conclua as etapas a seguir:

  1. Selecione um endpoint diferente em outra região de rede.
  2. Reenvie o mesmo payload de transação assinado.
  3. Informe o problema usando o botão "Enviar feedback" na parte de cima desta página para que a equipe do Universal Ledger investigue.

Ao verificar o status da transação, a resposta pode incluir várias mensagens TransactionAttempt se você tiver enviado o mesmo payload várias vezes. No máximo uma tentativa será finalizada com um status de transação OK, encontrado no TransactionEffects, enquanto outras tentativas estarão pendentes ou terão um status de falha. Esse é o comportamento esperado. O livro-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: depois que uma transação é informada como finalizada por um validador, todos os outros validadores na mesma rede precisam processar a transação e reproduzir exatamente os mesmos resultados. O envio de um QueryAccountRequest usando o ID da rodada em que a transação foi finalizada, conforme encontrado no TransactionCertificate, produz resultados idênticos em todos os validadores sincronizados.

  • Transações não finalizadas: como as transações se propagam pela rede de forma assíncrona, o fato de uma transação ser informada como finalizada pode variar entre diferentes validadores.

    Um validador que está se recuperando de uma interrupção ou com atraso na 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

  • Rastreamento de transações: os aplicativos cliente precisam rastrear o estado de todas as transações enviadas até que sejam finalizadas.

  • 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 de negócios.

A seguir