クライアント実装のガイドライン

このガイドでは、Universal Ledger API クライアントを構築するデベロッパー向けに、アーキテクチャと実装のガイドラインを示します。学習内容:

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

Universal Ledger API エンドポイントへの接続

リクエストは、Universal Ledger API を介して特定のネットワーク エンドポイントにルーティングされます。ネットワーク エンドポイントは、そのリージョン内のバリデータにリクエストを分散するリージョン Cloud リソースです。ネットワーク エンドポイントにアクセスするには、クライアントは、そのネットワーク エンドポイントが配置されている Cloud リージョンと一致するリージョン API エンドポイント（REP）に接続する必要があります。

リージョン エンドポイント名の形式は次のとおりです。

universalledger.REGION.rep.googleapis.com

REGION は、ネットワーク エンドポイントが配置されているサポート対象の地域に置き換えます。

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

Universal Ledger ネットワークは、複数のゾーンとリージョンに分散された多数のバリデータで構成されているため、ネットワーク全体で高可用性が確保されます。

  • ゾーン障害: Cloud ゾーン内で 1 つのバリデータに障害が発生しても、同じリージョン内の他のバリデータがリクエストの処理をシームレスに継続します。

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

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

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

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

  • べき等再送信: 送信されたすべてのトランザクションは、正確なシリアル化されたペイロード（シーケンス番号と送信者を含む）に基づいて一意のトランザクション ID を生成します。まったく同じペイロードを複数回送信すると、同じトランザクション ID が生成されます。台帳により、トランザクションは最大 1 回実行されるため、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 チームが調査できるようにします。

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

ネットワークの整合性

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

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

    障害から回復中のバリデータや、同期ラグが発生しているバリデータは、完了したトランザクションを一時的に PENDING または NOT_FOUND として報告することがあります。バリデータが追いつくと、トランザクション ステータスは解決されます。

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

  • トランザクションのトラッキング: クライアント アプリケーションは、送信されたすべてのトランザクションの状態を、ファイナライズされるまでトラッキングする必要があります。

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

次のステップ