Crea il tuo client

Questa guida fornisce consigli per garantire che le implementazioni dei client Universal Ledger interagiscano con una rete in modo sicuro e affidabile. Scopri come:

  • Sfruttare la topologia di rete per l'alta disponibilità.
  • Inviare transazioni e comprendere i risultati dell'esecuzione.
  • Implementare strategie di polling, timeout e nuovi tentativi.

Topologia di rete e alta disponibilità

Una rete Universal Ledger è composta da una serie di validatori distribuiti tra più zone e regioni, garantendo così un'elevata disponibilità per la rete nel suo complesso.

  • Errori a livello di zona: se un singolo validatore non funziona all'interno di una zona Cloud, gli altri validatori della stessa regione continueranno a elaborare le richieste senza problemi.

  • Interruzioni a livello regionale: se un'intera regione diventa non disponibile, i validatori di altre regioni rimangono operativi. Per continuare a inviare transazioni, il client può eseguire il fallback e tentare di inviare di nuovo le transazioni tramite un endpoint diverso.

Caratteristiche di esecuzione delle transazioni

  • Esecuzione atomica: le transazioni vengono completate interamente o non vengono completate. L'esecuzione parziale delle transazioni, ad esempio il trasferimento solo di una parte dei fondi richiesti a causa di un saldo insufficiente, non si verifica mai. Sono incluse le catene di transazioni, che consentono di combinare più transazioni arbitrarie in una singola sequenza atomica.

  • Nessun nuovo tentativo automatico: la rete tenta di eseguire una transazione inviata esattamente una volta. Se l'esecuzione non riesce, il ledger non mette in coda né ritenta automaticamente la transazione.

  • Invio di nuovo idempotente: ogni transazione inviata genera un ID transazione univoco basato sul payload serializzato esatto (inclusi numero di sequenza e mittente). L'invio più volte dello stesso payload produce lo stesso ID transazione. Il ledger garantisce che una transazione venga eseguita al massimo una volta, quindi è sicuro inviare di nuovo lo stesso payload di transazione a un endpoint diverso se uno di questi sembra non essere disponibile.

    Per maggiori dettagli, consulta la SubmitTransactionRequest pagina di riferimento.

Latenza, polling e strategia di nuovi tentativi

Quando invii una transazione, il validatore esegue prima un controllo rapido per assicurarsi che le firme e i numeri di sequenza siano validi. In caso di esito positivo, l' API Universal Ledger risponde immediatamente con un SubmitTransactionResponse che include l'ID transazione assegnato.

La maggior parte delle transazioni viene finalizzata entro 3 secondi. Per controllare lo stato della transazione, esegui il polling del QueryTransactionState metodo utilizzando l'ID transazione fornito.

  • Se lo stato della transazione è ancora PENDING, recupera di nuovo lo stato utilizzando una strategia di backoff esponenziale. Ad esempio, esegui query a intervalli di 3 secondi, 9 secondi, 27 secondi e 60 secondi.

  • Se QueryTransactionState restituisce NOT_FOUND, invia di nuovo la transazione.

Una volta che un tentativo di transazione è FINALIZED, la risposta includerà anche un TransactionCertificate con vari dettagli, ad esempio:

  • L'ID del round in cui è stata finalizzata la transazione.
  • Lo stato di esecuzione (OK o non riuscito).
  • Eventi di transazione, inclusi eventuali output di transazione.

Protocollo di timeout

Nell'improbabile eventualità che una transazione rimanga nello stato PENDING o NOT_FOUND dopo 60 secondi, presupponi che il validatore che gestisce le tue richieste non riesca a tenere il passo con gli altri validatori della rete. Completa i seguenti passaggi:

  1. Seleziona un endpoint diverso in una regione di rete diversa.
  2. Invia di nuovo lo stesso payload di transazione firmato.
  3. Segnala il problema inviando un'email all'indirizzo gcul-help@google.com per consentire al team di Universal Ledger di esaminarlo.

Quando controlli lo stato della transazione, la risposta potrebbe includere più TransactionAttempt messaggi se hai inviato lo stesso payload multiple volte. Al massimo un tentativo verrà finalizzato con uno stato della transazione OK, che si trova in TransactionEffects, mentre gli altri tentativi saranno in attesa o avranno uno stato non riuscito. Questo è il comportamento previsto: il ledger ha eseguito correttamente uno degli invii di transazioni e ha rifiutato, o rifiuterà, gli invii duplicati.

Coerenza di rete

  • Transazioni finalizzate: una volta che una transazione viene segnalata come finalizzata da un validatore, tutti gli altri validatori della stessa rete dovrebbero elaborare la transazione e riprodurre esattamente gli stessi risultati. L'invio di un QueryAccountRequest utilizzando l'ID del round in cui è stata finalizzata la transazione, come si può trovare nel suo TransactionCertificate, produce risultati identici su tutti i validatori sincronizzati.

  • Transazioni non finalizzate: poiché le transazioni si propagano in modo asincrono nella rete, la segnalazione di una transazione come finalizzata può variare a seconda dei validatori.

    Un validatore che si sta riprendendo da un'interruzione o che sta riscontrando un ritardo di sincronizzazione potrebbe segnalare temporaneamente una transazione finalizzata come PENDING o NOT_FOUND. Lo stato della transazione verrà risolto una volta che il validatore avrà recuperato.

Responsabilità del client e gestione degli errori

  • Monitoraggio delle transazioni: le applicazioni client devono monitorare lo stato di tutte le transazioni inviate fino alla loro finalizzazione.

  • Gestione degli errori: se una transazione non riesce, recupera e ispeziona i dettagli dell'errore inclusi in TransactionCertificate per attivare la correzione appropriata a livello aziendale.

Passaggi successivi