Eigenen Client erstellen

Dieser Leitfaden enthält Empfehlungen, damit Universal Ledger-Clientimplementierungen sicher und zuverlässig mit einem Netzwerk interagieren können. Sie erfahren, wie Sie:

  • die Netzwerktopologie für Hochverfügbarkeit nutzen.
  • Transaktionen senden und Ausführungsergebnisse verstehen.
  • Polling-, Zeitlimit- und Wiederholungsstrategien implementieren.

Netzwerktopologie und Hochverfügbarkeit

Ein Universal Ledger-Netzwerk besteht aus einer Reihe von Validatoren, die auf mehrere Zonen und Regionen verteilt sind. So wird eine hohe Verfügbarkeit für das gesamte Netzwerk gewährleistet.

  • Zonenausfälle:Wenn ein einzelner Validator in einer Cloud-Zone ausfällt, verarbeiten andere Validatoren in derselben Region Anfragen nahtlos weiter.

  • Regionale Ausfälle:Wenn eine ganze Region nicht mehr verfügbar ist, bleiben die Validatoren in anderen Regionen betriebsbereit. Um weiterhin Transaktionen zu senden, kann Ihr Client auf einen anderen Endpunkt zurückgreifen und versuchen, Transaktionen noch einmal zu senden.

Merkmale der Transaktionsausführung

  • Atomare Ausführung:Transaktionen sind entweder vollständig erfolgreich oder vollständig fehlgeschlagen. Eine teilweise Transaktionsausführung, z. B. die Übertragung nur eines Teils der angeforderten Mittel aufgrund eines unzureichenden Guthabens, kommt nie vor. Dazu gehören Transaktionsketten, mit denen Sie mehrere beliebige Transaktionen zu einer einzigen atomaren Sequenz kombinieren können.

  • Keine automatischen Wiederholungen:Das Netzwerk versucht, eine gesendete Transaktion genau einmal auszuführen. Wenn die Ausführung fehlschlägt, wird die Transaktion nicht automatisch in die Warteschlange gestellt oder wiederholt.

  • Idempotente erneute Übermittlung:Für jede gesendete Transaktion wird eine eindeutige Transaktions-ID basierend auf der genauen serialisierten Nutzlast (einschließlich Sequenznummer und Absender) generiert. Wenn Sie genau dieselbe Nutzlast mehrmals senden, wird dieselbe Transaktions-ID generiert. Das Ledger sorgt dafür, dass eine Transaktion höchstens einmal ausgeführt wird. Daher können Sie dieselbe Transaktionsnutzlast sicher an einen anderen Endpunkt senden, wenn einer der Endpunkte nicht verfügbar ist.

    Weitere Informationen finden Sie auf der SubmitTransactionRequest Referenzseite.

Latenz, Polling und Wiederholungsstrategie

Wenn Sie eine Transaktion senden, führt der Validator zuerst eine schnelle Überprüfung durch, um sicherzustellen, dass die Signaturen und Sequenznummern gültig sind. Bei Erfolg antwortet die Universal Ledger API sofort mit einer SubmitTransactionResponse einschließlich der zugewiesenen Transaktions-ID.

Die meisten Transaktionen werden innerhalb von 3 Sekunden abgeschlossen. Um den Transaktions status zu prüfen, rufen Sie die QueryTransactionState Methode mit der angegebenen Transaktions-ID ab.

  • Wenn der Transaktionsstatus weiterhin PENDING lautet, rufen Sie den Status mit einer exponentiellen Backoff-Strategie noch einmal ab. Fragen Sie beispielsweise in Intervallen von 3 Sekunden, 9 Sekunden, 27 Sekunden und 60 Sekunden ab.

  • Wenn QueryTransactionState NOT_FOUND zurückgibt, senden Sie die Transaktion noch einmal.

Sobald ein Transaktionsversuch FINALIZED ist, enthält die Antwort auch ein TransactionCertificate mit verschiedenen Details, z. B.:

  • Die Round-ID, bei der die Transaktion abgeschlossen wurde.
  • Der Ausführungsstatus (OK oder fehlgeschlagen).
  • Transaktionsereignisse, einschließlich aller Transaktionsausgaben.

Zeitlimitprotokoll

In dem unwahrscheinlichen Fall, dass eine Transaktion nach 60 Sekunden noch den Status PENDING oder NOT_FOUND hat, gehen Sie davon aus, dass der Validator, der Ihre Anfragen verarbeitet, nicht mit anderen Validatoren im Netzwerk mithalten kann. Führen Sie diese Schritte aus:

  1. Wählen Sie einen anderen Endpunkt in einer anderen Netzwerkregion aus.
  2. Senden Sie genau dieselbe signierte Transaktionsnutzlast noch einmal.
  3. Melden Sie das Problem per E-Mail an gcul-help@google.com, damit das Universal Ledger-Team es untersuchen kann.

Wenn Sie den Transaktionsstatus prüfen, kann die Antwort mehrere TransactionAttempt Nachrichten enthalten, wenn Sie dieselbe Nutzlast mehrmals gesendet haben. Höchstens ein Versuch wird mit dem Transaktionsstatus „OK“ abgeschlossen, der in den TransactionEffects zu finden ist. Andere Versuche haben entweder den Status „Ausstehend“ oder „Fehlgeschlagen“. Das ist das erwartete Verhalten. Das Ledger hat eine der Transaktionsübermittlungen erfolgreich ausgeführt und die doppelten erneuten Übermittlungen korrekt abgelehnt oder wird sie schließlich ablehnen.

Netzwerkkonsistenz

  • Abgeschlossene Transaktionen:Sobald eine Transaktion von einem Validator als abgeschlossen gemeldet wird, müssen alle anderen Validatoren im selben Netzwerk die Transaktion verarbeiten und genau dieselben Ergebnisse reproduzieren. Wenn Sie eine QueryAccountRequest mit der Round-ID senden, bei der die Transaktion abgeschlossen wurde, wie sie im in seinem TransactionCertificate, zu finden ist, erhalten Sie auf allen synchronisierten Validatoren identische Ergebnisse.

  • Nicht abgeschlossene Transaktionen:Da sich Transaktionen asynchron im Netzwerk ausbreiten, kann es je nach Validator variieren, ob eine Transaktion als abgeschlossen gemeldet wird.

    Ein Validator, der sich von einem Ausfall erholt oder eine Synchronisierungsverzögerung aufweist, meldet eine abgeschlossene Transaktion möglicherweise vorübergehend als PENDING oder NOT_FOUND. Der Transaktionsstatus wird aufgelöst, sobald der Validator aufgeholt hat.

Pflichten des Clients und Fehlerbehebung

  • Transaktions-Tracking:Clientanwendungen müssen den Status aller gesendeten Transaktionen verfolgen, bis sie abgeschlossen sind.

  • Fehlerbehebung: Wenn eine Transaktion fehlschlägt, rufen Sie die Fehler details ab, die im TransactionCertificate enthalten sind, und prüfen Sie sie, um die entsprechende Korrektur auf Geschäftsebene auszulösen.

Nächste Schritte