Hyperledger Fabric公式サンプル fabric-samples 徹底解説

2025/07/08に開催されたLFDT Tokyo Meetup #4で登壇発表したfabric-samples関連の内容です。
https://www.linuxfoundation.jp/events/2025/06/lf-decentralized-trust-tokyo-meetup-on-july-8/

Transcript

1. ©Hitachi, Ltd. 2025. All rights reserved Hyperledger Fabric公式サンプル fabric-samples 徹底解説 LF Decentralized Trust Tokyo Meetup #4 2025/7/8 佐藤 竜也 (Tatsuya Sato) 日立製作所 研究開発グループ
2. ©Hitachi, Ltd. 2025. All rights reserved 佐藤竜也 (Tatsuya Sato) ⚫ 日立製作所 研究開発グループ 主任研究員 ⚫ 主な研究分野: ⬦ ブロックチェーン・Web3 ⬦ ITシステム運用管理、クラウドサービス ⚫ LFDT/HyperledgerコミュニティにてOSS活動推進中 ⬦ LFDT Japan Chapter Leads ⬦ Hyperledger Fabricメンテナ ✓ fabric-samples ✓ fabric core ⬦ Hyperledger Labs プロジェクトオーナー 自己紹介 本日のトピック 2
3. ©Hitachi, Ltd. 2025. All rights reserved 3 ⚫ fabric-samplesはHyperledger Fabricコミュニティによる公式サンプル集であり、Fabric公式 ドキュメントのチュートリアルの中でも活用されています。 ⚫ 実は、チュートリアルでは触れられていないサンプルや機能も多く存在しています。 ⬦ Docker以外の稼働環境向けのテストネットワーク ⬦ Asset Transfer Basic以外の様々な種類のスマートコントラクトやアプリケーションサンプル ⚫ 本日はfabric-samplesの基本部分からあまり知られていないところも含めて網羅的にご紹介し、 みなさまのHyperledger Fabric利用に役立つ情報を提供できればと思います。 ⬦ fabric-samplesの全体構造が理解できる ⬦ 用途別にどのサンプルを使うべきか判断できる ⬦ 自分の検証環境への応用のヒントが得られる 本セッションについて
4. ©Hitachi, Ltd. 2025. All rights reserved 4 ⚫ テストネットワーク: ローカル環境上で検証用のシンプルな Fabricネットワークを稼働させるスクリプト群を提供。 Dockerコンテナベースのテストネットワークが標準サンプル だが、Kubernetes(K8s)版とバイナリ版も用意。 ⚫ チェーンコード: Fabricのコア機能やユースケースごとのスマー トコントラクト実装を提供。テストネットワークの種類には 原則依存しておらず、任意の組合せで実行可能。 ⚫ アプリケーション: FabricのクライアントSDKを用いてチェーン コードにトランザクションを発行するアプリケーションのサンプ ル実装。上記のチェーンコードとセットで用意されている。 fabric-samplesの全体像 主に「テストネットワーク」「チェーンコード」「アプリケーション」から構成される 主要サンプルは公式ドキュメントのチュートリアルで活用される他、それ以外にも様々なサンプルを含む https://github.com/hyperledger/fabric-samples チェーンコード (スマートコントラクト) テスト ネットワーク アプリケーション Docker ベース (test-network) K8s ベース (test-network -k8s) バイナリ ベース (test-network -nano-bash) Asset Transfer シリーズ ERC 参照 実装 その他 full- stack- asset- transfer -guide チェーンコード ネットワーク アプリ fabric-samplesリポジトリ全体像
5. ©Hitachi, Ltd. 2025. All rights reserved 5 ⚫ テストネットワーク: ローカル環境上で検証用のシンプルな Fabricネットワークを稼働させるスクリプト群を提供。 Dockerコンテナベースのテストネットワークが標準サンプル だが、K8s版とバイナリ版も用意。 ⚫ チェーンコード: Fabricのコア機能やユースケースごとのスマー トコントラクト実装を提供。テストネットワークの種類には 原則依存しておらず、任意の組合せで実行可能。 ⚫ アプリケーション: FabricのクライアントSDKを用いてチェーン コードにTXを発行するアプリケーションのサンプル実装。 上記のチェーンコードとセットで用意されている。 fabric-samplesの全体像 主に「テストネットワーク」「チェーンコード」「アプリケーション」から構成される 主要サンプルは公式ドキュメントのチュートリアルで活用される他、それ以外にも様々なサンプルを含む https://github.com/hyperledger/fabric-samples チェーンコード (スマートコントラクト) テスト ネットワーク アプリケーション Docker ベース (test-network) K8s ベース (test-network -k8s) バイナリ ベース (test-network -nano-bash) チュートリアル範囲 Asset Transfer シリーズ ERC 参照 実装 その他 full- stack- asset- transfer -guide fabric-samplesリポジトリ全体像 チェーンコード ネットワーク アプリ (参考)公式ドキュメントのチュートリアルとの対応関係 • 初期インストール • テストネットワークの利用 1. Fabricのテストネットワーク(Docker版)の起動 2. チャネルの作成 3. チェーンコード(asset-transfer-basic)のデプロイ 4. Fabricネットワークとのインタラクション 1. CLIを介したInvokeトランザクション発行 2. CLIを介したQueryトランザクション発行 • Fabricアプリケーションの実行 • Private Data Collectionの利用 • チャネルへの組織追加/削除 • ・・・
6. ©Hitachi, Ltd. 2025. All rights reserved 6 テストネットワークスクリプト群の比較 (test-network-*) 共通: 検証用のシンプルなFabricネットワークを数コマンドで簡単に起動できるスクリプト群 実装バリエーション: Docker版、Kubernetes版、Fabricバイナリ版を提供 → 環境に応じて選択可能 種類 概要 チュート リアル Fabric バージョン CA Couch DB BFT Orderer (v3.0以降) test-network Docker Composeを使ってコンテナベースのテスト用ネットワークを構築・起動す るスクリプト群。機能が豊富でチュートリアル・サンプルはこれを使って動かす想定。 • v2.5, v3.x • • • test-network- k8s Kubernetes(K8s)環境版のテスト用ネットワークを構築・起動するスクリプト群。 (現状はローカルK8s環境(KIND)で試すことを想定) v2.5, v3.x ▪ ▪ • test-network- nano-bash Fabricバイナリを直接使用し、Docker等を使わずにテスト用ネットワークを構 築・起動するbashスクリプト群。 v2.5, v3.x • • •: サポート、▪: サポート(本機能で固定) test-network系スクリプトの共通部分: ⚫ FabricのLTS版(v2.5)と最新版(v3.x)両方に対応 ⬦ v3.xに関しては新機能のBFT Ordererも対応しており、試すことができる ⚫ Fabricネットワーク起動、チャネル作成、チェーンコードデプロイなどの各ネットワーク操作に関するサブコマンドを提供 実装バリエーション: ⚫ Docker版のtest-networkをベースに、Kubernetes版のtest-network、Fabricバイナリ版のtest-network-nano-bashを提供 ⚫ ネットワーク構成や提供機能の細部には若干の違いがあるが、使用方法や使用感はほぼ同じ チェーンコード ネットワーク アプリ (※) LTS: Long Term Support, KIND: Kubernetes IN Docker BFT: Byzantine Fault Tolerance
7. ©Hitachi, Ltd. 2025. All rights reserved test-network: Dockerコンテナ版テストネットワーク ネットワーク構成: 2Peer組織(Org1, Org2)と1Orderer組織(OrdererOrg) OrdererOrg Org1 Peer Org2 Peer Org3 Peer Channel Chaincode (Endorsement: MAJORITY) CA CA CA CA Orderer1 CFTプロトコル (Raft) 種類 概要 チュート リアル Fabric バージョン CA Couch DB BFT Orderer (v3.0以降) test-network Docker Composeを使ってコンテナベースのテスト用ネットワークを構築・起動す るスクリプト群。機能が豊富でチュートリアル・サンプルはこれを使って動かす想定。 • v2.5, v3.x • • • 固有部分の補足: ⚫ Peer組織(Org3)追加シナリオが用意 されている。 ⚫ Prometheusで集めたテストネットワーク からメトリックスをGrafanaのダッシュボー ドで表示するスクリプトも存在。 •: サポート、▪: サポート(本機能で固定) チェーンコード ネットワーク アプリ Orderer1 Orderer2 Orderer3 Orderer4 BFTプロトコル (SmartBFT) OrdererOrg Org1 Peer Org2 Peer Org3 Peer Channel Chaincode (Endorsement: MAJORITY) CA CA CA CA 通常 BFT Orderer利用時 (※) CFT: Crash Fault Tolerance, BFT: Byzantine Fault Tolerance 7
8. ©Hitachi, Ltd. 2025. All rights reserved Peer Org2 Peer Fabric CA Cert Manager test-network-k8s: Kubernetes版テストネットワーク ネットワーク構成: 2Peer組織(Org1, Org2)と1Orderer組織(Org0) Org0 Orderer1 Orderer2 Orderer3 Orderer4 BFTプロトコル (SmartBFT) CFTプロトコル (Raft) 種類 概要 チュート リアル Fabric バージョン CA Couch DB BFT Orderer (v3.0以降) test-network- k8s Kubernetes(K8s)環境版のテスト用ネットワークを構築・起動するスクリプト群 (現状はローカルK8s環境(KIND)で試すことを想定) v2.5, v3.x ▪ ▪ • 固有部分の補足: ⚫ Peerは各組織で二重化構成 ⚫ Fabric CAはECertのみ発行し、 TLSはCert Managerが発行 ⚫ チェーンコードをK8s環境のポッドとして動か す必要あり→ Chaincode as a Service パターンなどの利用を前提とした手順 ⚫ REST APIアプリとの連動手順 ⚫ Hyperledger Caliper連携手順も用意 ⚫ ※: クラウドベースのK8s環境上で動かすに は手直しが必要 •: サポート、▪: サポート(本機能で固定) Fabric CA Cert Manager Peer Org1 Peer Channel Chaincode Fabric CA Cert Manager (Endorsement: Org1 OR Org2) Peer Org2 Peer Fabric CA Cert Manager Org0 Orderer1 Orderer2 Orderer3 Fabric CA Cert Manager Peer Org1 Peer Channel Chaincode Fabric CA Cert Manager (Endorsement: Org1 OR Org2) チェーンコード ネットワーク アプリ 通常 BFT Orderer利用時 8 (※) CFT: Crash Fault Tolerance, BFT: Byzantine Fault Tolerance
9. ©Hitachi, Ltd. 2025. All rights reserved Peer Org2 Peer Fabric CA test-network-nano-bash: バイナリ版テストネットワーク ネットワーク構成: 2Peer組織(Org1, Org2)と1Orderer組織(Orderer) Orderer Orderer1 Orderer2 Orderer3 Orderer4 BFTプロトコル (SmartBFT) CFTプロトコル (Raft) 種類 概要 チュート リアル Fabric バージョン CA Couch DB BFT Orderer (v3.0以降) test-network- nano-bash Fabricバイナリを直接使用し、Docker等を使わずにテスト用ネットワークを構 築・起動するbashスクリプト群。 v2.5, v3.x • • 固有部分の補足: ⚫ Peerは各組織で二重化構成 ⚫ チェーンコードの起動方法については、手順 の中でいくつかの選択肢が提示されている ⬦ Dockerコンテナとして起動 ⬦ バイナリとして起動 ⬦ Chaincode as a Serviceとして起動 •: サポート、▪: サポート(本機能で固定) Fabric CA Peer Org1 Peer Channel Chaincode Fabric CA (Endorsement: Org1 OR Org2) Peer Org2 Peer Fabric CA Orderer Orderer1 Orderer2 Orderer3 Fabric CA Peer Org1 Peer Channel Chaincode Fabric CA (Endorsement: Org1 OR Org2) チェーンコード ネットワーク アプリ 通常 BFT Orderer利用時 9 (※) CFT: Crash Fault Tolerance, BFT: Byzantine Fault Tolerance
10. ©Hitachi, Ltd. 2025. All rights reserved 10 Asset Transferシリーズ Asset Transfer(資産の登録と移転)を題材として、Fabricのコア機能ごとのチェーンコードサンプルを用意 本シリーズとチュートリアルをなぞることで、チェーンコードの書き方、Fabricのコア機能・SDKの使い方を一通り理解できる スマートコントラクト 概要 チュート リアル チェーンコード言語 アプリケーション言語 Go Java JS TS Go Java JS TS Basic Asset Transferの基本サンプル。チェーンコードの書き方(データ更新/参 照)やFabricネットワークとのやり取りの基本をおさえることができる。 • • • • • ★ • • ★ Ledger queries 台帳に対する様々なクエリ方法(範囲クエリやCouchDBのリッチクエ リ)に関するサンプル。 • • • • △ △ Private data プライベートデータコレクション(PDC)のサンプル。 • • • • • • State-Based Endorsement ステートベースエンドースメント(SBE: チェーンコードのキーレベルでエンドース メントポリシーを設定可能)のサンプル。 • • • △ Secured agreement 2組織間のセキュアな資産移転を題材に、暗黙的なPDC、Transient 引数、SBE、組織(MSPID)ベースのアクセス制御などを高度に活用。 • • • Events チェーンコードからのイベント発行を行うサンプル。 • • • • • • Attribute-based access control Attribute-Based Access Control(ABAC)機能を用いて資産のアク セス制御を行うサンプル。 • •: サポート、★: 通常のアプリに加えREST APIサンプルも提供、 △: 旧SDK利用(v2.2以前でのみ動作) ※: サンプルによって実装言語のサポート状況はまちまちなので注意 チェーンコード ネットワーク アプリ (※) JS: JavaScript, TS: TypeScript MSP: Membership Service Provider
11. ©Hitachi, Ltd. 2025. All rights reserved 11 ERCトークンの参照実装 Ethereumの標準規格(ERC)に準拠した主要なトークンの参照実装をHyperledger Fabricコミュニティが提供 トークン種別 概要 チェーンコード言語 Go Java JS TS ERC-20 FT (Fungible Token) のスマートコントラクト。 • • • ERC-721 NFT (Non-Fungible Token) のスマートコントラクト。 • • • ERC-1155 Multi Token Standardのスマートコントラクト。 • •: サポート チェーンコード ネットワーク アプリ ⚫ Fabricはネイティブトークンを持たないが、スマートコントラクトを使って独自にトークン (FT/NFT) を実装可能 ⚫ Fabricコミュニティでは、ERC-20、ERC-721、ERC-1155といった主要な標準仕様(ERC: Ethereum Request for Comments)に準拠したスマートコントラクトの参照実装が公開されている ⬦ ドキュメントに沿ってテストネットワーク上でのトークンの発行・移転を簡単に試行可能 ⬦ スマートコントラクトをカスタマイズすることで、様々なトークンユースケースに応用可能 (※) JS: JavaScript, TS: TypeScript
12. ©Hitachi, Ltd. 2025. All rights reserved 12 その他の応用サンプル一覧 様々なユースケースやアプリケーションに関するサンプルがまだまだ存在 ※: 一部はメンテナンス状況が若干滞っているため活用時には注意が必要 チェーンコード ネットワーク アプリ サンプル 概要 チェーンコード言語 アプリケーション言語 Go Java JS TS Go Java JS TS Off chain data ブロックイベントを利用して、アプリ側でレポートや分析のためのオフチェーン データベースを構築する方法を提示。 (Asset Transfer Basicを流用) • • • Token SDK (LabsのToken SDKとFabric Smart Clientを用いたサンプル。) (独自) (独自) Token UTXO UTXO(unspent transaction output)モデルを用いたFTのサンプル。 • High throughput 大量のトランザクションが発生する環境において、トランザクションの衝突 を回避するためにスマートコントラクトを設計する方法を提示。 • △ Simple Auction 期間終了まで入札が非公開になるシンプルなブラインドオークション。 • △ Dutch Auction ダッチ・オークションと呼ばれる競り下げ方式の公開オークションのサンプル。 • △ full-stack-asset- transfer-guide Hyperledger Global Forumでのワークショップを基にした高度なサンプル。Asset Transferを題材に、周辺プロジェクトも 駆使したFabricの高度かつ実践的な使い方(スマートコントラクト開発、アプリ開発、K8s上へのデプロイ)を紹介。 •: サポート、△: 旧SDK利用(v2.2以前でのみ動作) チェーンコード ネットワーク アプリ より高度なサンプル/手引き (※) JS: JavaScript, TS: TypeScript
13. ©Hitachi, Ltd. 2025. All rights reserved 13 ⚫ fabric-samples (https://github.com/hyperledger/fabric-samples) は、Hyperledger Fabricの 基本機能から応用的なユースケースまでを網羅する、コミュニティ公式の包括的サンプル集である ⚫ 公式チュートリアルで使われるだけでなく、以下のような多様なサンプルを含む: ⬦ 検証環境に応じた3種のテストネットワーク: Docker / K8s / バイナリ ⬦ ユースケース別のチェーンコード: Asset Transferシリーズ、ERCトークン参照実装 など ⬦ Fabric SDKによるアプリケーション実装例 ⚫ fabric-samplesを有効活用することで、Fabricのスマートコントラクト・アプリケーション開発や検証 環境構築の効率化が期待できる ⬦ Asset Transferシリーズを活用することで、Fabricのコア機能の使い方を効率よく習得 ⬦ ERC参照実装を、Fabricを用いたトークンユースケースの検討・実現に活用 まとめ
14. ©Hitachi, Ltd. 2025. All rights reserved 14 ⚫ LF Decentralized Trust、Hyperledger、Hyperledger Fabricは、The Linux Foundationの商標または登 録商標です ⚫ GitHubは、GitHub Inc.の商標または登録商標です ⚫ その他記載の会社名、製品名、サービス名、その他固有名詞は、それぞれの会社の商標または登録商標です ⚫ 本発表中の文章、図では、TM、🄬マークは表記しておりません Trademarks
15. ©Hitachi, Ltd. 2025. All rights reserved