Consignes d'implémentation client

Ce guide fournit des consignes d'architecture et d'implémentation aux développeurs qui créent des clients d'API Universal Ledger. Découvrez comment :

  • Exploitez la topologie du réseau pour assurer la haute disponibilité.
  • Envoyer des transactions et comprendre les résultats d'exécution
  • Implémenter des stratégies d'interrogation, de délai avant expiration et de nouvelle tentative

Se connecter à un point de terminaison de l'API Universal Ledger

Les requêtes sont acheminées via l'API Universal Ledger vers un point de terminaison réseau spécifique. Les points de terminaison du réseau sont des ressources Cloud régionales qui distribuent les requêtes aux validateurs de cette région. Pour atteindre un point de terminaison du réseau, les clients doivent se connecter au point de terminaison de l'API régional (REP) qui correspond à la région Cloud où se trouve ce point de terminaison du réseau.

Les noms des points de terminaison régionaux suivent ce format :

universalledger.REGION.rep.googleapis.com

Remplacez REGION par la région prise en charge où se trouve votre point de terminaison du réseau.

Topologie du réseau et haute disponibilité

Un réseau Universal Ledger comprend un certain nombre de validateurs répartis dans plusieurs zones et régions, ce qui garantit une haute disponibilité pour l'ensemble du réseau.

  • Défaillances de zone : si un seul validateur échoue dans une zone Cloud, les autres validateurs de la même région continuent de traiter les requêtes de manière transparente.

  • Pannes régionales : si une région entière devient indisponible, les validateurs des autres régions restent opérationnels. Pour continuer à envoyer des transactions, votre client peut sans risque revenir en arrière et tenter de renvoyer les transactions via un autre point de terminaison.

Caractéristiques d'exécution des transactions

  • Exécution atomique : les transactions réussissent ou échouent entièrement. L'exécution partielle d'une transaction (par exemple, le transfert d'une partie seulement des fonds demandés en raison d'un solde insuffisant) ne se produit jamais. Cela inclut les chaînes de transactions, qui vous permettent de combiner plusieurs transactions arbitraires en une seule séquence atomique.

  • Aucune nouvelle tentative automatique : le réseau tente d'exécuter une transaction envoyée une seule fois. Si l'exécution échoue, le registre ne met pas la transaction en file d'attente et ne la relance pas automatiquement.

  • Nouvelle soumission idempotente : chaque transaction envoyée génère un ID de transaction unique basé sur sa charge utile sérialisée exacte (y compris le numéro de séquence et l'expéditeur). L'envoi de la même charge utile plusieurs fois génère le même ID de transaction. Le registre garantit qu'une transaction n'est exécutée qu'une seule fois au maximum, ce qui permet de renvoyer en toute sécurité la même charge utile de transaction à un autre point de terminaison si l'un d'eux semble indisponible.

    Pour en savoir plus, consultez la page de référence sur SubmitTransactionRequest.

Latence, interrogation et stratégie de nouvelle tentative

Lorsque vous envoyez une transaction, le validateur effectue d'abord une vérification rapide pour s'assurer que ses signatures et ses numéros de séquence sont valides. Si la requête aboutit, l'API Universal Ledger répond immédiatement avec un SubmitTransactionResponse incluant l'ID de transaction attribué.

La plupart des transactions sont finalisées en trois secondes. Pour vérifier l'état de la transaction, interrogez la méthode QueryTransactionState à l'aide de l'ID de transaction fourni.

  • Si l'état de la transaction est toujours PENDING, récupérez-le à nouveau en utilisant une stratégie de temporisation de retransmission. Par exemple, interrogez à des intervalles de 3 secondes, 9 secondes, 27 secondes et 60 secondes.

  • Si QueryTransactionState renvoie NOT_FOUND, renvoyez la transaction.

Une fois qu'une tentative de transaction est FINALIZED, la réponse inclut également un TransactionCertificate avec divers détails, tels que :

  • ID du tour au cours duquel la transaction a été finalisée.
  • L'état d'exécution (OK ou échec).
  • Événements de transaction, y compris les sorties de transaction.

Protocole de délai avant expiration

Dans le cas peu probable où une transaction reste à l'état PENDING ou NOT_FOUND après 60 secondes, supposez que le validateur qui traite vos requêtes ne parvient pas à rattraper les autres validateurs du réseau. Procédez comme suit :

  1. Sélectionnez un autre point de terminaison dans une autre région réseau.
  2. Renvoyez exactement la même charge utile de transaction signée.
  3. Signalez le problème à l'aide du bouton "Envoyer des commentaires" en haut de cette page pour que l'équipe Universal Ledger puisse l'examiner.

Lors de la vérification de l'état de la transaction, la réponse peut inclure plusieurs messages TransactionAttempt si vous avez envoyé la même charge utile plusieurs fois. Au maximum, une tentative sera finalisée avec l'état de transaction "OK", disponible dans TransactionEffects, tandis que les autres tentatives seront en attente ou auront l'état "Échec". Il s'agit d'un comportement attendu. Le registre a bien exécuté l'un des envois de transaction et a correctement rejeté, ou finira par rejeter, les envois en double.

Cohérence du réseau

  • Transactions finalisées : une fois qu'une transaction est signalée comme finalisée par un validateur, tous les autres validateurs du même réseau sont censés traiter la transaction et reproduire exactement les mêmes résultats. L'envoi d'un QueryAccountRequest à l'aide de l'ID de cycle auquel la transaction a été finalisée, tel qu'il figure dans son TransactionCertificate, donne des résultats identiques sur tous les validateurs synchronisés.

  • Transactions non finalisées : étant donné que les transactions se propagent sur le réseau de manière asynchrone, le fait qu'une transaction soit signalée comme finalisée peut varier d'un validateur à l'autre.

    Un validateur qui se remet d'une panne ou qui subit un retard de synchronisation peut signaler temporairement une transaction finalisée comme PENDING ou NOT_FOUND. L'état de la transaction sera résolu une fois que le validateur aura rattrapé son retard.

Responsabilités du client et gestion des exceptions

  • Suivi des transactions : les applications clientes doivent suivre l'état de toutes les transactions envoyées jusqu'à ce qu'elles soient finalisées.

  • Gestion des exceptions : si une transaction échoue, récupérez et inspectez les détails de l'échec inclus dans TransactionCertificate pour déclencher la correction appropriée au niveau de l'entreprise.

Étapes suivantes