Linee guida per l'implementazione del client

Questa guida fornisce linee guida per l'architettura e l'implementazione per gli sviluppatori che creano client API Universal Ledger. Scopri come:

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

Connessione a un endpoint API Universal Ledger

Le richieste vengono instradate tramite l'API Universal Ledger a un endpoint di rete specifico. Gli endpoint di rete sono risorse Cloud regionali che distribuiscono le richieste ai validatori all'interno della regione. Per raggiungere un endpoint di rete, i client devono connettersi all'endpoint API regionale (REP) corrispondente alla regione Cloud in cui si trova l'endpoint di rete.

I nomi degli endpoint regionali hanno il seguente formato:

universalledger.REGION.rep.googleapis.com

Sostituisci REGION con la regione supportata in cui si trova l'endpoint di rete.

Topologia di rete e alta affidabilità

Una rete Universal Ledger è composta da un numero di validator distribuiti tra più zone e regioni, garantendo così un'alta affidabilità per la rete nel suo complesso.

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

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

Caratteristiche di esecuzione delle transazioni

  • Esecuzione atomica: le transazioni vengono eseguite completamente o non vengono eseguite affatto. L'esecuzione parziale delle transazioni, ad esempio il trasferimento di una sola parte dei fondi richiesti a causa di un saldo insufficiente, non si verifica mai. Ciò include le catene di transazioni, che ti consentono di combinare più transazioni arbitrarie in un'unica sequenza atomica.

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

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

    Per maggiori dettagli, consulta la pagina di riferimento di SubmitTransactionRequest.

Latenza, polling e strategia di ripetizione dei tentativi

Quando invii una transazione, il validator 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 risponderà 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 metodo QueryTransactionState utilizzando l'ID transazione fornito.

  • Se lo stato della transazione è ancora PENDING, recuperalo di nuovo 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 nuovamente 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 riuscita).
  • Eventi di transazione, inclusi eventuali output di transazione.

Protocollo di timeout

Nell'improbabile caso in cui una transazione rimanga in uno stato PENDING o NOT_FOUND dopo 60 secondi, supponi che il validatore che gestisce le tue richieste non riesca a stare al passo con gli altri validatori della rete. Completa i seguenti passaggi:

  1. Seleziona un endpoint diverso in un'altra regione di rete.
  2. Invia di nuovo lo stesso payload della transazione firmata.
  3. Segnala il problema utilizzando il pulsante "Invia feedback" nella parte superiore di questa pagina per consentire al team di Universal Ledger di esaminarlo.

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

Coerenza della rete

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

  • Transazioni non finalizzate: poiché le transazioni si propagano nella rete in modo asincrono, la segnalazione di una transazione come finalizzata può variare tra i diversi validator.

    Un validator 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 validator si sarà aggiornato.

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 va a buon fine, recupera ed esamina i dettagli dell'errore inclusi in TransactionCertificate per attivare la correzione appropriata a livello aziendale.

Passaggi successivi