Fabric Gateway

Fabric Gatewayは、Hyperledger Fabric v2.4のピアに導入されたサービスであり、Fabricネットワークにトランザクションを送信するためのシンプルなAPIを提供します。 これまでクライアントSDKに求められていた複数組織のピアからトランザクションのエンドースメントを収集するなどの作業が、ピア内で実行されるFabric Gatewayサービスに委譲され、v2.4ではアプリケーション開発とトランザクション送信がシンプルになりました。

Writing client applications

Fabric v2.4以降、クライアントアプリケーションは、Fabric Gatewayとのやり取りに最適化されたFabric GatewayクライアントAPI (Go、Node、またはJava) を使用する必要があります。 これらのAPIは、Fabric v1.4で初めて導入されたのと同じ高いレベルのプログラミングモデルを提供します。

Fabric Gateway (別名ゲートウェイ) は以下のトランザクションステップを管理します:

  • トランザクション提案をEvaluate (評価) します。 これにより、スマートコントラクト（チェーンコード）関数を単一のピア上で呼び出し、結果をクライアントに返します。 これは通常、台帳の現在のステートをクエリする際に使用され、台帳の更新は行われません。 ゲートウェイは、ゲートウェイピアと同じ組織のピアを優先的に選択し、台帳ブロックの高さが最も高いピアを選択します。 ゲートウェイの組織内にピアがない場合は、他の組織のピアを選択します。
  • トランザクション提案をEndorse (エンドース) します。 これにより、複数の署名ポリシー (以下参照) を満たすための十分なエンドースメントを収集し、クライアントに署名用のトランザクションエンベロープを返します。
  • トランザクションをSubmit (送信) します。 署名されたトランザクションエンベロープをオーダリングサービスに送信し、トランザクションが台帳にコミットされます。
  • Commit Status (コミットステータス) イベントを待機します。 クライアントはトランザクションの台帳へのコミットを待機し、コミット (有効/無効) ステータスコードを取得できるようにします。
  • Chaincode events (チェーンコードイベント) を受信します。 クライアントアプリケーションは、トランザクションが台帳にコミットされた際にスマートコントラクト関数によって発行されるイベントに応答できるようになります。

Fabric GatewayクライアントAPIは、Endorse/Submit/Commit Statusのアクションを単一ブロックのSubmitTransaction関数に統合し、1行のコードでトランザクション送信をサポートします。 また、個々のアクションを呼び出すことで柔軟なアプリケーションパターンをサポートします。

Client application APIs

ゲートウェイとそのクライアントAPIは、クライアントアプリケーション開発者がFabricネットワークに関連するインフラストラクチャロジックではなく、アプリケーションのビジネスロジックに集中できるように設計されています。 そのため、これらのAPIはピアやチェーンコードなどの運用上の抽象化ではなく、組織や契約といった論理的な抽象化を提供します。 [補足 - 管理APIはこれらの運用上の抽象化を公開したいところですが、これは管理者APIではありません。]

Hyperledger Fabricは現在、以下3つの言語でクライアントアプリケーションの開発サポートをしています:

How the gateway endorses your transaction proposal

トランザクションが台帳に正常にコミットされるためには、エンドースメントポリシーを満たすのに十分な数のエンドースメントが必要です。 ある組織からエンドースメントを得るには、その組織のピアに接続し、そのピアの台帳のコピーに対してトランザクション提案をシミュレーション (実行) する必要があります。 ピアはチェーンコード関数を呼び出し、トランザクション提案に含まれる名前と引数で指定されたとおりに、読み取り/書き込みセットを構築 (及び署名) することで、トランザクションのシミュレーションをします。 この読み取り/書き込みセットには、現在の台帳のステートとその関数内のステートのget/set指示に応じた変更が含まれています。

トランザクションに適用されるエンドースメントポリシーまたは複数のポリシーの組み合わせは、呼び出されるチェーンコード関数の実装に依存し、以下に示す要素の組み合わせである可能性があります:

  • チェーンコードエンドースメントポリシー これは、組織のチェーンコード定義を承認する際にチャネルメンバーが合意するポリシーです。 チェーンコード関数が別のチェーンコードを呼び出す場合は、両方のポリシーを満たす必要があります。
  • プライベートデータコレクションエンドースメントポリシー チェーンコード関数がプライベートデータコレクション内のステートに書き込む場合、そのコレクションのエンドースメントポリシーが、そのステートに対するチェーンコードポリシーを上書きします。 チェーンコード関数がプライベートデータコレクションから読み取る場合は、そのコレクションのメンバーである組織に制限されます。
  • State-basedエンドースメント(SBE)ポリシー キーレベル署名ポリシーとも呼ばれるこれらのポリシーは、個々のステートに適用することができ、チェーンコードポリシーやプライベートデータコレクションのステートに対するコレクションポリシーを上書きします。 これらのエンドースメントポリシーは台帳に保存され、新しいトランザクションによって更新することができます。

トランザクション提案に適用されるエンドースメントポリシーの組み合わせは、チェーンコードの実行時に決定されるため、静的分析から必ずしも導出できるとは限りません。

Fabric Gatewayは、以下のプロセスを使用して、クライアントの代わりにトランザクションエンドースメントの複雑な処理を管理します:

  • Fabric Gatewayは (利用可能な) ピアの中で台帳ブロックの高さが最も高いピアを識別することで、ゲートウェイピアの組織 (MSP ID) からエンドーシングピアを選択します。 ゲートウェイピアに接続するクライアントアプリケーションは、ゲートウェイピアの組織内のすべてのピアを信頼しているという前提になります。
  • 選択されたエンドースメントピア上でトランザクション提案をシミュレーションします。 このシミュレーションでは、アクセスされたステートに関する情報が取得され、それに基づいてエンドースメントポリシーが組み合わせられます (エンドースメントピアの台帳に保存された個々のState-baseエンドースメントポリシーを含みます) 。
  • 取得されたポリシー情報は、ChaincodeInterestプロトコルバッファ構造にまとめられ、提案されたトランザクションに固有のエンドースメントプランを導出するためにディスカバリーサービスに渡されます。
  • ゲートウェイは、エンドースメントプランにて定められたすべてのポリシーを満たすために必要な組織にエンドースメントを要求します。 各組織について、ゲートウェイピアはブロックの高さが最も高い (利用可能な) ピアにエンドースメントを要求します。

ゲートウェイは、利用可能なピアやオーダリングサービスノードの接続情報を取得し、トランザクション提案のエンドースメントに必要なピアの組み合わせを計算するためにディスカバリーサービスに依存しています。 そのため、ゲートウェイサービスが有効化されているピアでは、ディスカバリーサービスも常に有効になっている必要があります。

ゲートウェイのエンドースメントプロセスは、トランザクション提案内の一時データ (Transient data) として渡されるプライベートデータに機密情報や個人情報が含まれることが多く、それらをすべての組織のピアに渡すべきではないため制限的です。 この場合、ゲートウェイはアクセス対象となるプライベートデータコレクション (読み取りまたは書き込み) の組織のみにエンドーシング組織を限定します。 一時データに対するこの制限がエンドースメントポリシーを満たさない場合、ゲートウェイはプライベートデータへのアクセス権がない組織に対して転送するのではなく、クライアントにエラーを返します。 このような場合、クライアントアプリケーションは、どの組織がトランザクションをエンドースすべきかを明確に定義するように作成する必要があります。

Targeting specific endorsement peers

いくつかのケースでは、クライアントアプリケーションがトランザクション提案を評価またはエンドースする組織を明示的に選択する必要があります。 例えば、一時データは個人情報や機密情報が含まれることが多く、それらのデータはプライベートデータコレクションにのみ書き込むべきであり、エンドースメント組織の数を制限する必要があります。 このような場合、クライアントアプリケーションはエンドーシング組織を明示的に指定することでアプリケーションのプライバシーとエンドースメントの要件を満たすことができます。ゲートウェイは、指定された各組織からブロック数が最も多い (利用可能な) エンドーシングピアを選択します。 ただし、クライアントがエンドースメントポリシーを満たさない組織のセットを指定した場合、トランザクションは指定されたピアによってエンドースされ、ordererに送信される可能性はありますが、検証及びコミットフェーズ中にチャネル内のすべてのピアによって無効化されます。 この無効化されたトランザクションは台帳に記録されますが、トランザクションの更新はチャネルピア上のいずれのステートデータベースにも書き込まれません。

Retry and error handling

Fabric Gatewayは、以下のようにノード接続のリトライ、エラー、タイムアウトを処理します。

Retry attempts

ゲートウェイは、ディスカバリーサービスの情報を活用し、利用できないピアやオーダリングノードで失敗したトランザクションをリトライします。 もしある組織が複数のピアやオーダリングノードを動かしている場合には、別の適格なノードが試されます。 ある組織がトランザクション提案のエンドースに失敗した場合、別の組織が選択されます。 ある組織が完全にエンドースできない場合は、エンドースメントポリシーを満たす組織のグループがターゲットとなります。 エンドースメントポリシーを満たす利用可能なピアの組み合わせがない場合にのみゲートウェイはリトライを停止します。 ゲートウェイは、すべての利用可能なエンドーシングピアの組み合わせが一度試されるまで、リトライを続けます。

Error handling

Fabric Gatewayは、ピアネットワークとオーダリングノードへのgRPC接続を管理しています。 ピアネットワークやオーダリングノード (つまり、ゲートウェイの外部) からゲートウェイサービスリクエストエラーが発生した場合、ゲートウェイはエラー、エンドポイント、組織 (MSP ID) 情報をメッセージのDetailsフィールドでクライアントに返します。 Detailsフィールドが空の場合、エラーはゲートウェイピアで発生しています。

Timeouts

Fabric GatewayのEvaluateとEndorseメソッドは、ゲートウェイ外部のピアにgRPCリクエストを送信します。 クライアントがこれらの応答を待つ時間を制限するためには、ピアのcore.yamlファイル内のゲートウェイセクションでpeer.gateway.endorsementTimeout値を設定することで可能になります。

同様に、Fabric GatewayのSubmitメソッドは、承認済みのトランザクションをブロードキャストするために、オーダリングサービスノードにgRPC接続を行います。 クライアントが個々のオーダリングノードからの応答を待つ時間を制限するためには、ピアのcore.yamlファイルのゲートウェイセクションでpeer.gateway.broadcastTimeout値を設定することで可能になります。

また、Fabric GatewayクライアントAPIは、クライアントアプリケーションから呼び出される各ゲートウェイメソッドに対してデフォルトおよび呼び出しごとのタイムアウトを設定する仕組みを提供します。

Listening for events

ゲートウェイはクライアントアプリケーションがチェーンコードイベントを受信するためのシンプルなAPIを提供します。 クライアントAPIは、言語固有の構文を使用してこれらのイベントを処理するためのメカニズムを提供します。