独自のクライアントを構築する

このガイドでは、Universal Ledger クライアントの実装がネットワークと安全かつ確実にやり取りできるようにするための推奨事項について説明します。学習内容:

  • 高可用性のためにネットワーク トポロジを活用します。
  • トランザクションを送信し、実行結果を把握する。
  • ポーリング、タイムアウト、再試行戦略を実装します。

ネットワーク トポロジと高可用性

ユニバーサル台帳ネットワークは、複数のゾーンとリージョンに分散された複数の検証ツールで構成されているため、ネットワーク全体の高可用性が確保されます。

  • ゾーン障害: Cloud ゾーン内で 1 つの検証ツールに障害が発生した場合、同じリージョン内の他の検証ツールはリクエストの処理をシームレスに続行します。

  • リージョン全体の停止: リージョン全体が利用できなくなっても、他のリージョンのバリデータは引き続き動作します。トランザクションの送信を続行するには、クライアントがフォールバックして、別のエンドポイントを介してトランザクションの再送信を試みても安全です。

トランザクション実行の特徴

  • アトミック実行: トランザクションは完全に成功するか、完全に失敗するかのいずれかです。残高不足のため、リクエストされた資金の一部のみを転送するなど、取引の一部のみが実行されることはありません。これにはトランザクション チェーンが含まれており、複数の任意のトランザクションを単一のアトミック シーケンスに結合できます。

  • 自動再試行なし: ネットワークは、送信されたトランザクションを 1 回だけ実行しようとします。実行が失敗した場合、台帳はトランザクションを自動的にキューに登録したり、再試行したりしません。

  • べき等再送信: 送信されたすべてのトランザクションは、正確なシリアル化されたペイロード（シーケンス番号と送信者を含む）に基づいて一意のトランザクション ID を生成します。同じペイロードを複数回送信すると、同じトランザクション ID が生成されます。台帳では、トランザクションが最大で 1 回実行されるため、いずれかのエンドポイントが使用できない場合は、同じトランザクション ペイロードを別のエンドポイントに安全に再送信できます。

    詳細については、SubmitTransactionRequest リファレンス ページをご覧ください。

レイテンシ、ポーリング、再試行戦略

トランザクションを送信すると、バリデータはまず、署名とシーケンス番号が有効であることを確認する簡単なチェックを行います。成功すると、Universal Ledger API は割り当てられたトランザクション ID を含む SubmitTransactionResponse をすぐに返します。

ほとんどのトランザクションは 3 秒以内に完了します。トランザクションのステータスを確認するには、提供されたトランザクション ID を使用して QueryTransactionState メソッドをポーリングします。

  • トランザクションのステータスが PENDING の場合は、指数バックオフ戦略を使用してステータスを再度取得します。たとえば、3 秒、9 秒、27 秒、60 秒の間隔でクエリを実行します。

  • QueryTransactionState が NOT_FOUND を返した場合は、トランザクションを再送信します。

取引の試行が FINALIZED になると、レスポンスには次のようなさまざまな詳細を含む TransactionCertificate も含まれます。

  • 取引が確定したラウンド ID。
  • 実行ステータス（OK または失敗）。
  • トランザクション イベント（トランザクション出力を含む）。

タイムアウト プロトコル

トランザクションが 60 秒後に PENDING 状態または NOT_FOUND 状態のままになることはまれですが、その場合は、リクエストを処理しているバリデータがネットワーク内の他のバリデータに追いついていないと想定してください。手順は次のとおりです。

  1. 別のネットワーク リージョンで別のエンドポイントを選択します。
  2. 同じ署名付きトランザクション ペイロードを再送信します。
  3. Universal Ledger チームが調査できるよう、gcul-help@google.com 宛てにメールを送信して問題を報告します。

トランザクションのステータスを確認する際、同じペイロードを複数回送信した場合は、レスポンスに複数の TransactionAttempt メッセージが含まれることがあります。TransactionEffects で見つかる OK トランザクション ステータスで完了するのは、最大で 1 回の試行のみです。他の試行は保留中になるか、失敗ステータスになります。これは想定される動作です。台帳は、トランザクション送信の 1 つを正常に実行し、重複する再送信を正しく拒否するか、最終的に拒否します。

ネットワークの整合性

  • 確定したトランザクション: 1 つのバリデータによってトランザクションが確定したと報告されると、同じネットワーク上の他のすべてのバリデータは、最終的にトランザクションを処理し、まったく同じ結果を再現することが期待されます。トランザクションが確定したラウンド ID を使用して QueryAccountRequest を送信すると、TransactionCertificate で確認できるため、同期されたすべてのバリデータで同じ結果が得られます。

  • 確定していないトランザクション: トランザクションはネットワーク全体に非同期で伝播されるため、トランザクションが確定済みとして報告されるかどうかは、バリデータによって異なる場合があります。

    停止から復旧したバリデータや同期の遅延が発生しているバリデータは、確定したトランザクションを一時的に PENDING または NOT_FOUND として報告する可能性があります。バリデータが追いつくと、トランザクションのステータスは解決されます。

クライアントの責任とエラー処理

  • トランザクションの追跡: クライアント アプリケーションは、送信されたすべてのトランザクションの状態を、確定するまで追跡する必要があります。

  • エラー処理: トランザクションが失敗した場合は、TransactionCertificate に含まれる失敗の詳細を取得して検査し、適切なビジネスレベルの修復をトリガーします。

次のステップ