Créer votre propre client

Ce guide fournit des recommandations pour s'assurer que les implémentations clientes d'Universal Ledger interagissent avec un réseau de manière sécurisée et fiable. Découvrez comment :

  • tirer parti de la topologie du réseau pour assurer une haute disponibilité ;
  • envoyer des transactions et comprendre les résultats de l'exécution ;
  • mettre en œuvre des stratégies d'interrogation, de délai avant expiration et de nouvelles tentatives.

Topologie du réseau et haute disponibilité

Un réseau Universal Ledger comprend un certain nombre de validateurs répartis sur 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 continueront 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 revenir en arrière et tenter de les renvoyer via un autre point de terminaison.

Caractéristiques d'exécution des transactions

  • Exécution atomique : les transactions réussissent entièrement ou échouent entièrement. L'exécution partielle des transactions (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, ce qui vous permet 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. En cas d'échec de l'exécution, le registre ne met pas en file d'attente ni ne relance automatiquement la transaction.

  • Renvoyer de manière 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 reprises produit le même ID de transaction. Le registre garantit qu'une transaction est exécutée au maximum une fois, ce qui permet de renvoyer 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 SubmitTransactionRequest page de référence.

Latence, interrogation et stratégie de nouvelles tentatives

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 l'opération réussit, l' API Universal Ledger répond immédiatement avec un SubmitTransactionResponse incluant l'ID de transaction qui lui est attribué.

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

  • Si l'état de la transaction est toujours PENDING, récupérez-le à nouveau à l'aide d'une stratégie d'attente exponentielle. 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 diverses informations, telles que :

  • L'ID de tour auquel la transaction a été finalisée.
  • L'état d'exécution (OK ou échec).
  • Les é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 du réseau.
  2. Renvoyez exactement la même charge utile de transaction signée.
  3. Signalez le problème en envoyant un e-mail à gcul-help@google.com pour que l'équipe Universal Ledger puisse l'examiner.

Lorsque vous vérifiez l'état d'une transaction, la réponse peut inclure plusieurs TransactionAttempt messages si vous avez envoyé la même charge utile plusieurs fois. Au maximum, une tentative sera finalisée avec un état de transaction OK, qui se trouve dans les TransactionEffects, tandis que les autres tentatives seront en attente ou auront un état d'échec. Il s'agit d'un comportement normal : le registre a exécuté l'un des envois de transaction et a refusé, ou finira par refuser, les renvois 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 doivent finir par traiter la transaction et reproduire exactement les mêmes résultats. L'envoi d'une QueryAccountRequest à l'aide de l'ID de tour auquel la transaction a été finalisée, tel qu'il peut être trouvé dans son TransactionCertificate, génère des résultats identiques sur tous les validateurs synchronisés.

  • Transactions non finalisées : comme les transactions se propagent de manière asynchrone sur le réseau, 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 présente un décalage de synchronisation peut temporairement signaler 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 erreurs : en cas d'échec d'une transaction, récupérez et inspectez les détails de l'échec inclus dans le TransactionCertificate pour déclencher la correction appropriée au niveau de l'entreprise.

Étape suivante