Hyperledger Irohaドキュメンテーション¶

ようこそ！ Hyperledger Iroha（いろは）は、ビザンチンフォールトトレラントなコンセンサスに適合するパーミッションベースのブロックチェーンを実現することで、信頼性が高く、安全で、高速なアプリケーションを作成するためのシンプルな構造に設計されたブロックチェーンプラットフォームです。無料でオープンソースで、LinuxやMac OS上で動作し、さまざまなモバイル用とデスクトップ用ライブラリが利用できます。

Hyperledger Irohaのソースコードと最新のリリースは、`GitHub page <https://github.com/hyperledger/iroha>`_からダウンロードできます。

このドキュメンテーションでは、イロハネットワークのインストール、導入、および起動、アプリケーションの作成方法が説明されています。また、現在どのユースケースシナリオが実現可能であるのかを確認し、また今後どのようなものが実装予定なのかについても確認します。

Hyperledger Irohaはオープンソースプロジェクトであるため、プロジェクトへの寄付に関することや、作業プロセスについても説明します。

注釈

外部APIドキュメントのため別個のウェブサイト`Iroha API <https://hyperledger.github.io/iroha-api>` _があります。現在、このいろはプロジェクトのドキュメンテーションは移行段階にあり、将来的にはRTD（Read the Docs）だけが維持・更新されるようになっています。

いろはの概要¶

いろはの主な特長は何ですか？¶

簡単な導入とメンテナンス
開発者向けのさまざまなライブラリ
役割に基づいたアクセス制限
コマンドとクエリの分離によって行われるモジュール型設計
資産とアイデンティティ管理

品質モデルで私たちは以下の点に重点を置いています：

信頼性（耐障害性、回復性）
パフォーマンス効率（とりわけ時間挙動とリソースの使用効率）
ユーザビリティ（学習可能性、ユーザー・エラー保護、妥当性の評価可能性）

Irohaはどこで使えますか？¶

Hyperledger Irohaは、デジタルアセット、ID、およびシリアル化されたデータを管理する際に汎用的に使用できるパーミッション型ブロックチェーンシステムです。銀行間決済、中央銀行のデジタル通貨、決済システム、国内ID、および物流分野などのアプリケーションとして役立ちます。

詳細は、ユースケースシナリオ<http://iroha.readthedocs.io/en/latest/use_cases/> `_を参照してください。

BitcoinやEthereumとはどのような点が違うのですか？¶

BitcoinとEthereumは、誰もが参加しすべてのデータにアクセスできる、パーミッションレス型レジャーになるように設計されています。また、システムと相互作用するために独自の暗号化通貨もあります。

イロハには固有の暗号通貨はありません。その代わりに、企業のニーズを満たすためシステム内での通信が許可に基づいて行われうるようになっています。つまり、アクセス権を持つユーザーだけがシステムとやり取りできます。さらに、すべてのデータへのアクセスを制御できるように、クエリ（情報照会）も許可に基づい行われるようにされています。

特にEthereumとの主な違いの1つは、Hyperledger Irohaではシステムに組み込まれたコマンドを用いて、デジタルアセットの作成や転送といった共通機能を実行できることです。これにより、スマートコントラクトの記述やテストといった面倒で難しい作業の必要がなくなり、開発者は単純なタスクをより迅速かつ低リスクで行うことができます。

その他のHyperledgerフレームワークや他のパーミッション・ブロックチェーンとはどのように違いますか？¶

イロハには、高性能で待ち時間が少なくかつ取引ファイナリティを可能にする、ビザンチンフォールトトレラント・コンセンサスアルゴリズム（YAC [＃f1] _）が採用されています。その他のフレームワークは、ナカモト合意のようなの確率的合意形成に重点を置くものや、ビザンチンフォールトトレランスの特性が犠牲にされていたりします。

またIrohaの組み込みコマンドでは、デジタル資産の作成、アカウント登録、アカウント間の資産移転といった共通タスクを実行するのが非常に簡単であるため、他のプラットフォームと比較しても大きな利点です。さらに、攻撃のベクトルを狭め、システムの全体的なセキュリティ水準を向上させます。これはシステム機能が停止しうる箇所が少ないためです。

最後に、Irohaは強力な権限システムを持つ唯一の分散型台帳であり、すべてのコマンド、クエリ、およびネットワークへの参加に対する権限を設定できます。

[1]	Yet Another Consensus

どのようなアプリケーションを「いろは」と関連して構築できますか？¶

みなさまのアプリケーションにブロックチェーンの力をもたらすためには、はじめにそのアプリケーションがIrohaピアとどのように連携するのかを考えなければなりません。そのためにまずはじめにトランザクションとクエリが正確に何であるかや、アプリケーションのユーザーがIrohaとどのようにやりとりするのかを説明している項`コアコンセプトセクション<http://iroha.readthedocs.io/en/latest/core_concepts/>` _がありますので、それを参照してみてください。

また、システム開発者が電子署名やコマンドといったIrohaの構成要素を作成するためのツールを提供しているクライアントライブラリもいくつか用意されています。

はじめる¶

このガイドでは、基本的ないろはネットワークを作成し、立ち上げ、いくつかのトランザクションを作成し、台帳に記録されたデータを確認します。単純にするために、Dockerを利用します。

注釈

Ledger is the synonym for a blockchain, and Hyperledger Iroha is known also as Distributed Ledger Technology framework — which in essence is the same as "blockchain framework". You can check the rest of terminology used in the 重要事項 section.

前提となる環境¶

For this guide, you need a machine with Docker installed. You can read how to install it on a Docker's website.

注釈

Of course you can build Iroha from scratch, modify its code and launch a customized node! If you are curious how to do that — you can check Building Iroha section. In this guide we will use a standard distribution of Iroha available as a docker image.

いろはノードを起動する¶

Dockerネットワークを作成する¶

Irohaが動作するためには PostgreSQL データベースが必要です。 PostgresとIroha用のコンテナが同じ仮想ネットワーク上で実行され、正常に通信が行われるようにするため、まずはDockerネットワークの作成から始めましょう。本ガイドでは、「iroha-network」と呼んでいますが、任意の名前を使用することができます。任意の名前を使用するためには、ターミナル上で次のコマンドを実行します。

docker network create iroha-network

PostgreSQLのコンテナを起動する¶

では次に、コンテナ内でPostgreSQLを実行し、これまでに作成したネットワークに接続し、通信用ポートを公開します。これらのステップを以下に示します。

docker run --name some-postgres \
-e POSTGRES_USER=postgres \
-e POSTGRES_PASSWORD=mysecretpassword \
-p 5432:5432 \
--network=iroha-network \
-d postgres:9.5 \
-c 'max_prepared_transactions=100'

注釈

If you already have Postgres running on a host system on default port (5432), then you should pick another free port that will be occupied. For example, 5433: -p 5433:5432

Blockstoreを作成する¶

Before we run Iroha container, we may create a persistent volume to store files, storing blocks for the chain. It is done via the following command:

docker volume create blockstore

Preparing the configuration files¶

注釈

To keep things simple, in this guide we will create a network containing only a single node. To understand how to run several peers, follow いろはを運用・導入する

Now we need to configure our Iroha network. This includes creating a configuration file, generating keypairs for a users, writing a list of peers and creating a genesis block.

Don't be scared away — we have prepared an example configuration for this guide, so you can start testing Iroha node now. In order to get those files, you need to clone the Iroha repository from Github or copy them manually (cloning is faster, though).

git clone -b master https://github.com/hyperledger/iroha --depth=1

ヒント

--depth=1 option allows us to download only the latest commit and save some time and bandwidth. If you want to get a full commit history, you can omit this option.

There is a guide on how to set up the parameters and tune them with respect to your environment and load expectations: 設定. We don't need to do this at the moment.

Irohaコンテナを起動する¶

We are almost ready to launch our Iroha container. You just need to know the path to configuration files (from the step above).

Let's start Iroha node in Docker container with the following command:

docker run --name iroha \
-d \
-p 50051:50051 \
-v $(pwd)/iroha/example:/opt/iroha_data \
-v blockstore:/tmp/block_store \
--network=iroha-network \
-e KEY='node0' \
hyperledger/iroha:latest

If you started the node successfully you would see the container id in the same console where you started the container.

Let's look in details what this command does:

docker run --name iroha \ creates a container iroha
-d \ runs container in the background
-p 50051:50051 \ exposes a port for communication with a client (we will use this later)
-v YOUR_PATH_TO_CONF_FILES:/opt/iroha_data \ is how we pass our configuration files to docker container. The example directory is indicated in the code block above.
-v blockstore:/tmp/block_store \ adds persistent block storage (Docker volume) to a container, so that the blocks aren't lost after we stop the container
--network=iroha-network \ adds our container to previously created iroha-network for communication with PostgreSQL server
-e KEY='node0' \ - here please indicate a key name that will identify the node allowing it to confirm operations. The keys should be placed in the directory with configuration files mentioned above.
hyperledger/iroha:latest is a reference to the image pointing to the latest release

You can check the logs by running docker logs iroha.

You can try using one of sample guides in order to send some transactions to Iroha and query its state.

Try other guides¶

ユースケース例¶

Hyperledger Irohaで運用・導入できる多くのユースケース例と具体的な利点を挙げています。 Hyperledger Irohaを使用したこれらのアプリケーションやユースケース例が、開発者やクリエイターによってさらに革新させられることを願っています。

教育やヘルスケア分野における証書¶

ハイパーレジャーいろは（Hyperledger Iroha）は、大学、学校、医療機関などさまざまな認証を必要とする機関のシステムへ組み込むことができます。 Hyperledger Irohaで用いられる柔軟な権限モデルによって、アイデンティティ認証や証書作成、証明書の付与が可能になります。ユーザーアカウントに明示的および暗黙的な情報を格納することにより、さまざまな評判・信用およびIDシステムを構築することができます。

Hyperledger Irohaを使用することにより、各教育機関または医療証明書が、特定の認証機関によって発行されたということを確認することができます。データの不変性と明確な検証規則によって、偽の証明書の使用を大幅に減らし、健康と教育分野へ透明性を提供します

例¶

例えば、Hyperledger Iroha上に「病院」ドメインとして登録された医療機関を想像してみてください。このドメインには、認定され登録された従業員がいます。医師、療法士、看護師など、それぞれがそれぞれの役割を持っています。病院の各患者はそれぞれのアカウントを保有しており、それらに過去のすべての病歴が記載されています。各医療記録は、血液検査結果のように、JSON key/valuesとして各患者の口座に安全かつ機密的に保管されます。「病院」ドメインのルールは、認定された医療従事者とユーザーだけが個人情報にアクセスできるように定義されています。クエリによって返された医療データは、信頼できるソースから取得されたものであるのかが確認されます。

病院は、例えば特定の地域内でにのみ個人情報を保存するといったように、その場所における個人情報保護に関する法的規則に従って、特定の場所に結ばれます（「プライバシー規則」_）。 Hyperledger Irohaのマルチドメインアプローチでは、法的ルールに違反を犯さずに複数の国々間での情報共有を可能にします。例えば、 "makoto @ hospital"というユーザが他の国の医療機関と個人の病歴を共有することを決定した場合、ユーザは `` can_get_my_acc_detail``で許可した上で `` grant``コマンドを使用して行うことができます。

医療機関でのケースと同様に、Hyperledger Irohaに登録された大学機関には、卒業生に情報を送信・公開する権限を持つことができます。卒業証書または証明書は、いわば認定された大学の署名付きの卒業証明です。こうした方法を利用すると、採用プロセスを簡素化するのにも役立ち、例えば雇用主は採用候補者がこれまで獲得したスキルや能力に関する情報を得るためにHyperledger Irohaに問い合わせを行います。

国際間の資産移転（授受）¶

Hyperledger Irohaは、マルチサインアカウントとアトミックエクスチェンジ機能を用いて、迅速かつ明確な取引環境、および決済規則を提供します。資産管理においては、中央集中的に管理されたシステムのように簡単で、必要なセキュリティ保証を提供します。資産の作成や移転に必要なルールとコマンドを簡素化することで、システム内への侵入障壁を低く抑え、同時に高いセキュリティ水準を保証、維持します。

例¶

たとえば[＃f1] _のように、あるユーザーは車の所有権を譲渡したいという場合があるかもしれません。ユーザーの``haruto``は``sora``というブランド名の車（資産）に対する所有権が登録されています。関連するパラメーターはそれぞれ、 {"id": "34322069732074686520616E73776572", "color": "red", "size": "small"}``です。この所有権は、システムの基盤となるデータベースに固定的に記録されており、各々の検証ピアにその写しが記録されています。資産の移転を行うために、ユーザー``haruto``は、別のユーザー``haru``宛てにオファーを行います。つまり``haru``宛てに車の識別子を「転送」するのと、 haru``から `` haruto``へ `` usd``のトークンを「転送」するという2つのコマンドが含まれた複数署名トランザクションを生成します。``haru``はマルチ署名トランザクションに署名することで``haruto``からのオファーを受け取ります。この場合、このトランザクションはシステム内でコミットされます（アトミックエクスチェンジ機能）。

Hypeledger Iroha自体にトークンは組み込まれていませんが、さまざまな資産とそれらを保有するクリエイターのタイプを扱うことができます。こうしたアプローチによって、分散型の交換市場を構築することが可能になります。例えば、このシステム上で異なる国における中央銀行がそれぞれの資産を発行するといったことができます。

[1]	現段階では実装されていません

金融業務におけるアプリケーション¶

Hyperleger Irohaは、監査業務で非常に役立ちます。各情報はそれぞれのビジネスルールによって検証され、異なるネットワーク参加者によって常時管理されます。いくつかの暗号化機能と共に、アクセス制御に関するルールによって所望のプライバシーが維持されます。アクセス制御ルールは、ユーザーレベル、ドメインレベルまたはシステムレベルといった異なるレベルで定義することができます。ユーザーレベルでは、特定個人向けのプライバシールールが定義されています。ドメインまたはシステムレベルでのアクセスルールが定義されると、ドメイン内のすべてのユーザーにそれらが適用されます。 Hyperledger Irohaでは、各役割ごとに特定の権限が付与されるといった役割ベースの便利なアクセス制御ルールが提供されています。

トランザクションは、ローカルデータベースを使用して追跡できます。 Iroha-API Auditorを使用すると、データに対してクエリを実行し、分析を実行し、特定の監査ソフトウェアの機能を行うことができます。 Hyperledger Iroha（いろは）は、分析ソフトウェアを展開する上でさまざまなシナリオをサポートしています。ローカルコンピュータ上での実行や、特定のミドルウェアでコードを実行することもできます。こうしたアプローチにより、HadoopやApacheなどのビッグデータアプリケーション分析を行うことができます。 Hypeledger Irohaは、データの完全性と機密性を保証する役割を果たします（クエリ権限の制限による）。

例¶

たとえば、監査は金融アプリケーションにおいて役立つかもしれません。監査役アカウントは、ユーザーを悩ますことなく、ドメイン内のユーザー関連情報にアクセスする権限を有する「監査役」の役割を担います。アカウントハイジャックの確率を減らし、監査人が悪意のあるクエリを送信するのを防ぐため、監査人は通常、複数署名アカウントとして定義されます。つまり、監査人は複数の異なるIDからの署名を持つクエリのみを作成することができます。監査人は、口座データおよび残高情報を取得するだけでなく、ユーザーの全取引情報も取得できます（例えば、ドメイン "konoha"内のユーザー "haruto"が行ったすべての移転取引といった具合）。イロハの各ノードは、分析ソフトウェアと連携して100万ユーザーのデータを効率的に分析することができます。

複数署名取引は、Hyperledger Irohaの強力なツールであり、既存の税制を混乱させる可能性があります。特定のドメイン内の各トランザクションは、ユーザーからの署名（例えば、資産の譲渡の際）と課税権限を有する特殊なノード（課税ノード）からの第2署名を含んだマルチ署名トランザクションとして扱うことができます。課税ノードには、Iroha-APIを使用して書かれた特別な検証ルールが規定されています。例えば、商品売上の際に加盟店は税金を支払わなければならないようにするといった事案です。つまり、有効とみなされる購入取引には、店舗への送金（商品購入）と政府への送金（納税）の2つのコマンドが含まれている必要があります。

アイデンティティマネジメント¶

Hyperledger Irohaには、ID管理のための本質的なサポートがあります。システム内の各ユーザーは、個人情報が関連づけられ、かつ一意に識別されたアカウントを保有し、各取引はその都度署名され、特定のユーザーに関連付けられます。こうすることで、Hyperledger IrohaはKYC（本人確認）機能を持つさまざまなアプリケーションに最適なソリューションを提供します。

例¶

例えば、保険会社におけるユースケースでは、取得情報の真実性を心配することなく、ユーザーの取引情報を照会するといった便利なことが可能になります。一方ユーザーは、認証された個人情報をブロックチェーンに登録しておくことで、保険請求処理に要する時間を短縮されるといった便益を享受することができます。ユーザーがローンを組みたいといった状況を想像してみてください。現在のローン事前審査は、収入や借入状況の収集およびそれらの情報検証に多大な時間がかけられています。 Hyperledger Irohaの各ユーザーは、保有資産、職位、債務状況などの認証済み個人情報が関連づけられたアカウントを保有しています。ユーザーの所得や借入状況と言いた情報は、 `` GetAccountTransactions`のクエリーを使用して、保有資産は `` GetAccountAssets``のクエリーで、ユーザーの職位に関すること情報は`` GetAccountDetail``を使用して追跡・管理することができます。各クエリは検証済みの情報を返すため、ローン審査に要する処理時間が劇的に短縮されます。個人情報を共有するようユーザーにインセンティブを与えるために、さまざまな企業がそれぞれのビジネスプロセスを考え出すことができます。例えば、保険会社はフィットネスを行っているユーザーに対してボーナス割引を適用することができます。フィットネスアプリケーションは、個人の活動証明をシステムにプッシュすることができます。ユーザーは事後的に、 `` can_get_my_acc_detail``で情報共有許可を与え、 `` GrantPermission``で保険会社と情報を共有することができます。

サプライチェーン¶

分散システムのガバナンスと法規制をシステムコードとして規定することは、あらゆるサプライチェーンシステムにおいて不可欠な組み合わせです。 Hyperledger Irohaで使用される認証システムでは、物理的なアイテムのトークン化とそれらのシステムへの埋め込みが可能です。各項目には「何を、いつ、どこで、なぜ」といった関連情報が付けられています。

許可システムと安全かつその数が制限された主要なコマンド群は、攻撃ベクトルを狭め、基本的なプライバシーを提供します。各トランザクションはハッシュ値を持ち、作成者の証明書または証明書によってシステム内で追跡できます。

例¶

食品分野におけるサプライチェーンは、農家、食品倉庫、食料品店、顧客など、複数の異なる人たちが共有するシステムです。その最終的な目標は、農家の畑から顧客のテーブルに食品を配達することです。製品は多くの段階を経て、各段階において共有空間に記録されます。顧客は、モバイルデバイスを介してイロハクエリが埋め込まれた製品コードを読み取ります。コードに含まれるイロハのクエリ情報によって、全段階、製品情報そして農家に関する情報を含む全履歴が提供されます。

例えば、「gangreen」は登録農家のひとつで、「トマト」という資産の生産者であり、イロハシステム内での「トマト」という項目情報と実際のトマトを関連付ける、言い換えれば、物理的な品物をトークン化する保証人です。資産の新規作成と配布に関わるプロセスは、ネットワーク参加者にとって完全な透明性が実現されます。こうして、イロハ上の「トマト」は多数のベンダーを通る旅に出て、ついに一人のユーザー「チャド」に届けられます。

いろはでは、複雑なスマートコントラクトを作成せずに、新たなアセットの作成を「CreateAsset」という単一のコマンドによって集約し、単純化しました。 Hyperledger Irohaの主な利点の1つは、開発者がアプリケーションを提供することで生まれる価値に集中できるようになることです。

Fund Management¶

With the support of multisignature transactions it is possible to maintain a fund by many managers. In that scheme investment can only be made after the confirmation of the quorum participants.

例¶

The fund assets should be held at one account. Its signatories should be fund managers, who are dealing with investments and portfolio distributions. That can be added via AddSignatory command. All of the assets should be held within one account, which signatories represent the fund managers. Thus the concrete exchanges can be performed with the multisignature transaction so that everyone will decide on a particular financial decision. The one may confirm a deal by sending the original transaction and one of managers' signature. Iroha will maintain the transaction sending so that the deal will not be completed until it receives the required number of confirmation, which is parametrized with the transaction quorum parameter.

重要事項¶

「いろは」はなぜネットワーク上で動くのでしょうか。システムの内部と外部のオブジェクトをどのようにすれば理解できるのでしょうか。ネットワーク上のピアはどのように協力してブロックチェーンに入れるべきデータを決定するのでしょうか。本セクションでは、こうしたいろはシステムの基本的な部分を見ていきましょう。

警告

ドキュメントは常に更新され、このセクションも今後改善される予定です。内容が編集されている間は用語集ページを確認してください。

Sections¶

Account (アカウント、口座)¶

指定された一連のアクションを実行できるIrohaエンティティ。各アカウントは既存のドメイン<#domain> __のいずれかに属します。

アカウントにはいくつかの role <#role> __（noneにすることができます）があります。これは権限の集合です。付与可能なアクセス権<＃grantable-permission> __だけがアカウントに直接割り当てられます。

Ametsuchi¶

Irohaのストレージコンポーネント。取引ブロックと、ブロックから生成された状態を保存します。これは、「World State View <＃world-state-view>」と呼ばれます。クライアント<#client> __がAmetsuchiと直接対話する方法はありません。

Asset（資産、アセット）¶

数えられる商品や価値。各アセットは、システム内の既存のドメイン<#domain> __に関連づけられています。たとえば、資産（アセット）は通貨単位、金の延べ棒、不動産など、さまざまな種類の単位を表すことができます。

Block (ブロック)¶

トランザクションデータはブロックと呼ばれるファイルに永続的に記録されます。ブロックは、時間の経過とともに連続的・線形的に[＃f1] _に編成されてゆきます。ブロックチェーンとも呼ばれます。

ブロックは、Iroha peers <#peer> __における暗号署名で署名され、 consensus <＃conssensus> __中にいろはノード（ピア）がこのブロックに投票します。署名可能なコンテンツはペイロードと呼ばれるため、ブロックの構造は次のようになります。

Outside payload

デジタル署名 - ピアが作成した署名、合意形成ラウンドでブロックへの投票に使用される

Inside payload

高さ - ブロックチェーン内における当該ブロックまでのブロック数

タイムスタンプ - ブロック生成時ピアによって刻まれるUNIX時間（ミリ秒単位）

array of transactions, which successfully passed validation and consensus step

hash of a previous block in the chain

rejected transactions hashes — array of transaction hashes, which did not pass stateful validation step; this field is optional

Block Creator¶

stateless <#stateless-validation>`__検証と`stateful <#stateful-validation>`__検証が完了した一連のトランザクションからなるブロックを作成するシステムコンポーネントで、作成されたブロックはその後`コンセンサス<#consensus> __へ伝播されます。

Client¶

イロハを使用するアプリケーションはすべてクライアントとして扱われます。

Irohaの特徴は、クライアントがピアネットワークと通信する際に単純なクライアント/サーバー型における抽象化を使用していることです。ブロックチェーン関連システムに特有の抽象化を使用していません。たとえばBitcoinシステムでは、クライアントもブロックを検証する必要がありますし、ハイパーレジャーFabricでは複数のピアがポーリングしてトランザクションがブロックに取り込められたのか確認する必要がありますが、Irohaではクライアントは単一のサーバーとの通信時と同様にいずれかのIrohaピアと相互通信します。

コマンド¶

コマンドは`state <＃world-state-view>` __を変更する意図を示します。たとえば、Irohaで新しい role <#role> __を作成するには、 Create role <../ api / commands.html＃create-role> __コマンドを送信する必要があります。

コンセンサス (合意)¶

計算機科学の分野におけるコンセンサスアルゴリズムとは、分散プロセスやシステム内で特定の単一データ値に対する合意形成に使用されるプロセスを意味します。コンセンサスアルゴリズムは、複数かつ信頼できないノードを含むネットワークにおいて信頼性を達成するように設計されています。「合意形成問題」として知られているこの問題を解決することは、分散コンピューティングとマルチエージェントシステムにおいて重要なことです。

*アルゴリズムとしてのコンセンサス *

ネットワーク内のピア間でブロックへの合意を達成するためのアルゴリズム。これをシステムに組み込むことにより、信頼性が向上します。

システム構成部分としてのコンセンサス

ピアネットワーク内の peer <#peer> __の間で一貫した状態 (state)を維持します。 IrohaはYet Another Consensus（YAC）という独自のコンセンサスアルゴリズムを使用しています。このアルゴリズムの特徴は、スケーラビリティ（拡張性）、パフォーマンス（処理能力）、および Byzantine fault tolerance <https://en.wikipedia.org/wiki/Byzantine_fault_tolerance> _です。もし欠落しているブロックがあった場合、それらは Synchronizer <#synchronizer> __経由で別のピアからダウンロードされます。コミットされたブロックは `Ametsuchi <#ametsuchi>`ブロックストレージに格納されます。

ドメイン¶

accounts <#account> __と assets <#asset> __をグループ化するために、名称を与え抽象化したもの。

Ordering Gate (検証作業の要求経路)¶

Peer Communication Service <＃peer-communication-service> __から Ordering Service <＃ordering-service>`へ`トランザクション<#transaction> __を渡すIrohaの内部コンポーネント。 Ordering Gateは、最終的にOrdering Serviceから proposals <#proposal> __を受け取り、それらに対して`` Stateful validation <＃stateful-validation> __を行うために Simulator <#simulator> `__に送ります。

Ordering Service¶

stateless validation <＃stateless-validation> __を通過したものとして渡された`トランザクション<#transaction>` __ を`proposal <#proposal>` __として組み合わせる作業を担うIrohaの内部コンポーネントです。プロポーザルの作成は、次のいずれかのイベントによって引き起こされます。

取引収集のための時間が制限を超えた場合。
オーダーリングサービスが、1つのプロポーザルに許可された最大取引量を受け取った場合。

両方のパラメータ（タイムアウトとプロポーザルに付与する最大サイズ）は設定可能です（環境パラメータ<../guides/configuration.html＃環境固有パラメータ> _のページをご確認ください）。

両方のトリガーに共通する前提条件は、少なくとも1つのトランザクションがオーダリングサービスに到達しているということです。それ以外の場合、プロポーザルは作成されません。

ピア（ネットワークノード）¶

Irohaネットワークを構成するノード。ピアはコンセンサス<#consensus> _形成プロセスに参加しています。

ピア間通信サービス (PCS)¶

イロハの内部構成要素の１つ - 鳥居<#torii> __から送られてくる transaction <#transaction> __を`Ordering Gate <＃ordering-gate>`へ送信します。 PCSの主な目的は、コンセンサスの実装とそれ以外における相互通信の複雑さを隠すことです。

権限 (Permission)¶

コマンドの実行権限を与えるルールで、それぞれに名称が付けられています。 Permission **は account <#account> __に直接付与することはできません。代わりに、アカウントには権限の集合体であるロール、役割が与えられています。

List of Iroha permissions.

付与可能な権限¶

与えられた権限だけが`account <#account>` __に与えられます。付与することのできる権限を持つアカウントは、別のアカウントに代わって特定のアクションを実行できます。たとえばa@domain1というアカウントがb@domain2というアカウントに対して、アセットを転送できるようにする権限をb@domain2に与えると、b@domain2はa@domain1のアセットを誰にでも転送することができます。

プロポーザル（新規ブロックの提案）¶

stateless validation <＃stateless-validation> __だけを通過した一連の transactions <#transaction> __

検証済みのプロポーザル¶

A set of transactions that have been passed stateless and stateful validation, but were not committed yet.

クエリー（問い合わせ）¶

イロハへのリクエストは、 `state <#world-state-view>`__を変更しません。情報の照会を実行することにより、クライアントは状態に関する照会したい情報（例えば、彼の口座の残高、取引履歴など）を得ることができます。

Quorum¶

In the context of transactions signing, quorum number is a minimum amount of signatures required to consider a transaction signed. The default value is 1. Each account can link additional public keys and increase own quorum number.

役割 (Role)¶

permissions <#permission> __(複数可) がグループ化され、役割として抽象化されたもの。

Signatory¶

Represents an entity that can confirm multisignature transactions for some account. It can be attached to account via AddSignatory and detached via RemoveSignatory.

シミュレーター (Simulator)¶

`Verified Proposal Creator <#verified-proposal-creator>`__を参照してください。

シンクロナイザー¶

`consensus <#consensus>`__の一部です。不足しているブロックを `peers' <#peer>`__に追加します。（他のピアからダウンロードします）

Torii（鳥居）¶

⛩ clients <#client> __のエントリポイント。 gRPCをトランスポート層で使用します。 Irohaと通信するには、 Commands <../ api / commands.html> __と Queries <../ api / queries.html> __の項で記述されているgRPCエンドポイントを使用するか、クライアントライブラリ <../ guides / libraries.html> `__を使用してください。

トランザクション¶

台帳に原子的（atomically）に適用される順序付けられた commands <#command> __です。トランザクション内に無効なコマンドが含まれていると、検証処理中にトランザクション全体が拒否されます。

Transaction Structure¶

Payload stores all transaction fields, except signatures:

Time of creation (unix time, in milliseconds)

Account ID of transaction creator (username@domain)

Quorum field (indicates required number of signatures)

Repeated commands which are described in details in commands section

Batch meta information (optional part). See Batch of Transactions for details

Signatures contain one or many signatures (ed25519 public key + signature)

Reduced Transaction Hash¶

Reduced hash is calculated over transaction payload excluding batch meta information. Used in Batch of Transactions.

Transaction Statuses¶

Hyperledger Iroha supports both push and pull interaction mode with a client. A client that uses pull mode requests status updates about transactions from Iroha peer by sending transaction hashes and awaiting a response. In contrary push interaction is done over the listening of an event stream for each transaction. In any of these modes, the set of transaction statuses is the same:

Transaction Status Set¶

NOT_RECEIVED: requested peer does not have this transaction.

ENOUGH_SIGNATURES_COLLECTED: this is a multisignature transaction which has enough signatures and is going to be validated by the peer.

MST_PENDING: this transaction is a multisignature transaction which has to be signed by more keys (as requested in quorum field).

MST_EXPIRED: this transaction is a multisignature transaction which is no longer valid and is going to be deleted by this peer.

STATELESS_VALIDATION_FAILED: the transaction was formed with some fields, not meeting stateless validation constraints. This status is returned to a client, who formed transaction, right after the transaction was sent. It would also return the reason — what rule was violated.

STATELESS_VALIDATION_SUCCESS: the transaction has successfully passed stateless validation. This status is returned to a client, who formed transaction, right after the transaction was sent.

STATEFUL_VALIDATION_FAILED: the transaction has commands, which violate validation rules, checking state of the chain (e.g. asset balance, account permissions, etc.). It would also return the reason — what rule was violated.

STATEFUL_VALIDATION_SUCCESS: the transaction has successfully passed stateful validation.

COMMITTED: the transaction is the part of a block, which gained enough votes and is in the block store at the moment.

REJECTED: this exact transaction was rejected by the peer during stateful validation step in previous consensus rounds. Rejected transactions' hashes are stored in block store. This is required in order to prevent replay attacks.

Pending Transactions¶

Any transaction that has lesser signatures at the moment than quorum of transaction creator account is considered as pending. Pending transaction will be submitted for stateful validation as soon as multisignature mechanism will collect required amount of signatures for quorum.

Transaction that already has quorum of signatures can also be considered as pending in cases when the transaction is a part of batch of transactions and there is a not fully signed transaction.

Batch of Transactions¶

Transactions batch is a feature that allows sending several transactions to Iroha at once preserving their order.

Each transaction within a batch includes batch meta information. Batch meta contains batch type identifier (atomic or ordered) and a list of reduced hashes of all transactions within a batch. The order of hashes prescribes transactions sequence.

Batch can contain transactions created by different accounts. Any transaction within a batch can require single or multiple signatures (depends on quorum set for an account of transaction creator). At least one transaction inside a batch should have at least one signature to let the batch pass stateless validation.

Atomic Batch¶

All the transactions within an atomic batch should pass stateful validation for the batch to be applied to a ledger.

Ordered Batch¶

Ordered batch preserves only the sequence of transactions applying to a ledger. All the transactions that able to pass stateful validation within a batch will be applied to a ledger. Validation failure of one transaction would NOT directly imply the failure of the whole batch.

Multisignature Transactions¶

A transaction which has the quorum greater than one is considered as multisignature (also called mst). To achieve stateful validity the confirmation is required by the signatories of the creator account. These participants need to send the same transaction with their signature.

検証作業（Validator）¶

検証にはステートレスとステートフルの2種類があります。

ステートレス検証 (Sateless Validation)¶

Torii <#torii> __で実行されます。電子署名を含むオブジェクトが正しく構成されているか否かチェックします。

ステートフル検証 (Sateful Validation)¶

Verified Proposal Creator<#verified-proposal-creator> __で実行されます。 World State View <＃world-state-view> __に対して検証が行われます。

Verified Proposal Creator¶

受信された`proposal <#proposal>` __に格納されている`トランザクション<#transaction>` __に対してステートフル検証<#stateful-validation> _を実行するIrohaの内部コンポーネントです。ステートフル検証を通過したトランザクションをもとに、検証済みプロポーザル（ブロックの提案）**が作成され、 `Block Creator <＃block-creator> __に渡されます。ステートフル検証をパスしなかったトランザクションはすべて破棄され、それらはプロポーザルには含まれません。

World State View¶

WSVは現在のシステム状態を反映したスナップショットと捉えることができます。たとえば、WSVには現在account <#account> __が持っている`assets <#asset>` __の量に関する情報が保持されていますが、transaction <#transaction> __ フローに関する履歴情報は記録されていません。

[1]	https://en.bitcoin.it/wiki/Block

Entity-relationship model¶

Each Hyperledger Iroha peer has a state, called "World State View", which is represented by a set of entities and relations between them. To explain you more which entities exist in the system and what are the relations, this sections includes ER diagram and an explanation of its components.

ER diagram¶

core_concepts/./../../image_assets/er-model.png

Peer¶

address — network address and internal port, is used for synchronization, consensus, and communication with the ordering service

public_key — key, which will be used for signing blocks during consensus process

Asset¶

asset_id — identifier of asset, formatted as asset_name#domain_id

domain_id — identifier of domain, where the asset was created, references existing domain

precision — size of fractional part

data — JSON with arbitrary structure of asset description

Signatory¶

public_key — a public key

Domain¶

domain_id — identifier of a domain

default_role — a default role per user created in the domain, references existing role

Role¶

role_id — identifier of role

RoleHasPermissions¶

role_id — identifier of role, references existing role

permission_id — an id of predefined role

Account¶

account_id — identifier of account, formatted as account_name@domain_id

domain_id — identifier of domain where the account was created, references existing domain

quorum — number of signatories required for creation of valid transaction from this account

transaction_count – counter of transactions created by this account

data — key-value storage for any information, related to the account. Size is limited to 268435455 bytes (0x0FFFFFFF) (PostgreSQL JSONB field).

AccountHasSignatory¶

account_id — identifier of account, references existing account

public_key — a public key (which is also called signatory), references existing signatory

AccountHasAsset¶

account_id — identifier of account, references existing account

asset_id — identifier of asset, references existing asset

amount — an amount of the asset, belonging to the account

AccountHasRoles¶

account_id — identifier of account, references existing account

role_id — identifier of role, references existing role

AccountHasGrantablePermissions¶

account_id — identifier of account, references existing account. This account gives grantable permission to perform operation over itself to permittee.

permittee_account_id — identifier of account, references existing account. This account is given permission to perform operation over account_id.

permission_id — identifier of grantable_permission

ガイドと実行方法¶

Building Iroha¶

In this guide we will learn how to install all dependencies, required to build Iroha and how to build it.

注釈

You don't need to build Iroha to start using it. Instead, you can download prepared Docker image from the Hub, this process explained in details in the はじめる page of this documentation.

Preparing the Environment¶

In order to successfully build Iroha, we need to configure the environment. There are several ways to do it and we will describe all of them.

Currently, we support Unix-like systems (we are basically targeting popular Linux distros and macOS). If you happen to have Windows or you don't want to spend time installing all dependencies you might want to consider using Docker environment. Also, Windows users might consider using WSL

Technically Iroha can be built under Windows natively in experimental mode. This guide covers that way too. All the stages related to native Windows build are separated from the main flow due to its significant differences.

ヒント

Having troubles? Check FAQ section or communicate to us directly, in case you were stuck on something. We don't expect this to happen, but some issues with an environment are possible.

Docker¶

注釈

You don't need Docker to run Iroha, it is just one of the possible choices.

First of all, you need to install docker and docker-compose. You can read how to install it on the Docker's website

注釈

Please, use the latest available docker daemon and docker-compose.

Then you should clone the Iroha repository to the directory of your choice.

git clone -b master https://github.com/hyperledger/iroha --depth=1

ヒント

--depth=1 option allows us to download only latest commit and save some time and bandwidth. If you want to get a full commit history, you can omit this option.

After it, you need to run the development environment. Run the scripts/run-iroha-dev.sh script:

bash scripts/run-iroha-dev.sh

ヒント

Please make sure that Docker is running before executing the script. macOS users could find a Docker icon in system tray, Linux user could use systemctl start docker

After you execute this script, following things happen:

1. The script checks if you don't have containers with Iroha already running. Successful completion finishes with the new container shell.

2. The script will download hyperledger/iroha:develop-build and postgres images. hyperledger/iroha:develop-build image contains all development dependencies and is based on top of ubuntu:16.04. postgres image is required for starting and running Iroha.

Two containers are created and launched.

4. The user is attached to the interactive environment for development and testing with iroha folder mounted from the host machine. Iroha folder is mounted to /opt/iroha in Docker container.

Now your are ready to build Iroha! Please go to Building Iroha section.

Linux¶

Boost¶

Iroha requires Boost of at least 1.65 version. To install Boost libraries (libboost-all-dev), use current release from Boost webpage. The only dependencies are thread, system and filesystem, so use ./bootstrap.sh --with-libraries=thread,system,filesystem when you are building the project.

Other Dependencies¶

To build Iroha, you need following packages:

build-essential automake libtool libssl-dev zlib1g-dev libc6-dbg golang git tar gzip ca-certificates wget curl file unzip python cmake

Use this code to install dependencies on Debian-based Linux distro.

apt-get update; \
apt-get -y --no-install-recommends install \
build-essential automake libtool \
libssl-dev zlib1g-dev \
libc6-dbg golang \
git tar gzip ca-certificates \
wget curl file unzip \
python cmake

注釈

If you are willing to actively develop Iroha and to build shared libraries, please consider installing the latest release of CMake.

macOS¶

If you want to build it from scratch and actively develop it, please use this code to install all dependencies with Homebrew.

xcode-select --install
brew install cmake boost postgres grpc autoconf automake libtool golang soci

ヒント

To install the Homebrew itself please run

ruby -e "$(curl -fsSL https://raw.githubusercontent.com/homebrew/install/master/install)"

Windows¶

All the listed commands are desinged for building 64-bit version of Iroha.

Chocolatey Package Manager¶

First of all you need chocolatey package manager installed. Please refer the guide for chocoloatey installation.

Build Toolset¶

Install CMake, Git, Microsoft compilers via chocolatey being in Administrative mode of command prompt:

choco install cmake git visualstudio2017-workload-vctools

ヒント

Despite PostgreSQL is not a build dependency it is recommended to install Postgres now for the testing later.

choco install postgresql
# Don't forget the password you set!

Vcpkg Dependency Manager¶

Although Vcpkg is aimed to control dependency hell among the C++ libraries, unfortunately, we cannot install its default version. The first problem is that Iroha dependency called SOCI is not able to work with the latest Boost. The second reason - Vcpkg does not provide Postgres related libraries for Debug build.

The solution is to use Vcpkg from a pull request (until it is merged):

git clone https://github.com/Microsoft/vcpkg.git --depth=1
cd vcpkg
git fetch origin pull/6328/head:vcpkg_for_iroha
git checkout vcpkg_for_iroha

Then follow Vcpkg installation guide:

# execute in Power shell
.\bootstrap-vcpkg.bat
.\vcpkg.exe integrate install

After the installation of vcpkg you will be provided with a CMake build parameter like -DCMAKE_TOOLCHAIN_FILE=C:/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake. Save it somewhere for the later use.

Vcpkg Packages¶

Install C++ dependencies via vcpkg:

# Execute this from cmd.exe NOT from Power Shell

vcpkg.exe install ^
protobuf:x64-windows ^
grpc:x64-windows ^
tbb:x64-windows ^
gtest:x64-windows ^
gflags:x64-windows ^
soci[boost,postgresql]:x64-windows ^
boost-filesystem:x64-windows ^
boost-system:x64-windows ^
boost-thread:x64-windows ^
boost-variant:x64-windows ^
boost-multiprecision:x64-windows ^
boost-bimap:x64-windows ^
boost-format:x64-windows ^
boost-circular-buffer:x64-windows ^
boost-assign:x64-windows ^
boost-uuid:x64-windows ^
boost-accumulators:x64-windows ^
boost-property-tree:x64-windows ^
boost-process:x64-windows

注釈

If you plan to build 32-bit version of Iroha - you will need to install all the mentioned librares above prefixed with x86 term instead of x64.

Build Process¶

Cloning the Repository¶

Clone the Iroha repository to the directory of your choice.

git clone -b master https://github.com/hyperledger/iroha
cd iroha

ヒント

If you have installed the prerequisites with Docker, you don't need to clone Iroha again, because when you run run-iroha-dev.sh it attaches to Iroha source code folder. Feel free to edit source code files with your host environment and build it within docker container.

Building Iroha¶

Building on Windows differs from the main flow and the guide is here.

To build Iroha, use those commands

mkdir build; cd build; cmake ..; make -j$(nproc)

Alternatively, you can use these shorthand parameters (they are not documented though)

cmake -H. -Bbuild;
cmake --build build -- -j$(nproc)

注釈

On macOS $(nproc) variable does not work. Check the number of logical cores with sysctl -n hw.ncpu and put it explicitly in the command above, e.g. cmake --build build -- -j4

CMake Parameters¶

We use CMake to build platform-dependent build files. It has numerous flags for configuring the final build. Note that besides the listed parameters cmake's variables can be useful as well. Also as long as this page can be deprecated (or just not complete) you can browse custom flags via cmake -L, cmake-gui, or ccmake.

ヒント

You can specify parameters at the cmake configuring stage (e.g cmake -DTESTING=ON).

Main Parameters¶

Parameter	Possible values	Default	Description
TESTING	ON/OFF	ON	Enables or disables build of the tests
BENCHMARKING		OFF	Enables or disables build of the Google Benchmarks library
COVERAGE		OFF	Enables or disables lcov setting for code coverage generation

Packaging Specific Parameters¶

Parameter	Possible values	Default	Description
ENABLE_LIBS_PACKAGING	ON/OFF	ON	Enables or disables all types of packaging
PACKAGE_ZIP		OFF	Enables or disables zip packaging
PACKAGE_TGZ		OFF	Enables or disables tar.gz packaging
PACKAGE_RPM		OFF	Enables or disables rpm packaging
PACKAGE_DEB		OFF	Enables or disables deb packaging

Running Tests (optional)¶

After building Iroha, it is a good idea to run tests to check the operability of the daemon. You can run tests with this code:

cmake --build build --target test

Alternatively, you can run following command in the build folder

cd build
ctest . --output-on-failure

注釈

Some of the tests will fail without PostgreSQL storage running, so if you are not using scripts/run-iroha-dev.sh script please run Docker container or create a local connection with following parameters:

docker run --name some-postgres \
-e POSTGRES_USER=postgres \
-e POSTGRES_PASSWORD=mysecretpassword \
-p 5432:5432 \
-d postgres:9.5

Building Iroha on Windows¶

Configure the CMake project using configuration parameter acquired from vcpkg.

cmake -HC:\path\to\iroha -BC:\path\to\build ^
-DCMAKE_TOOLCHAIN_FILE=C:\path\to\vcpkg\scripts\buildsystems\vcpkg.cmake ^
-G "Visual Studio 15 2017 Win64" -T host=x64

注釈

To build a 32-bit version of Iroha change -G "Visual Studio 15 2017 Win64" to -G "Visual Studio 15 2017"

注釈

-T host=x64 indicates only the fact that 64-bit system is used as a host, where Iroha is going to be compiled.

Build irohad and iroha-cli:

cmake --build C:\path\to\build --target irohad
cmake --build C:\path\to\build --target iroha-cli

Running Iroha on Windows¶

Set the correct path and PostgreSQL password in config-win.sample

C:\path\to\irohad.exe ^
--config C:\path\to\iroha\example\config-win.sample ^
--genesis_block C:\path\to\iroha\example\genesis-win.block ^
--keypair_name C:\path\to\iroha\example\node0

As we stated before Windows build support is on experimental stage, that is why there no much details regarding the process. If you want to explore the maximum of Windows-related works around Iroha please take a look at these pull requests: 1, 2, 3.

設定¶

このセクションでは、Irohaの設定方法を説明します。まず「example/config.sample」を見てみましょう。

{
  "block_store_path": "/tmp/block_store/",
  "torii_port": 50051,
  "internal_port": 10001,
  "pg_opt": "host=localhost port=5432 user=postgres password=mysecretpassword",
  "max_proposal_size": 10,
  "proposal_delay": 5000,
  "vote_delay": 5000,
  "mst_enable" : false,
  "mst_expiration_time" : 1440,
  "max_rounds_delay": 3000,
  "stale_stream_max_rounds": 2
}

ご覧の通り、設定ファイルは有効な `json`の構造体です。それでは、行ごとに各パラメータが何を意味するのかを見てゆきましょう。

運用時のパラメーター¶

`block_store_path`は、ブロックが格納されているフォルダへのパスを設定します。
`torii_port`は、外部通信用のポートを設定します。クエリーとトランザクションがここに送られます。
`internal_port`は、内部通信用のポートを設定します。内部通信には、注文サービス（ordering service）、コンセンサス（consensus）、ブロックローダー（block loader）があります。
pg_optは、PostgreSQLの認証情報の設定に使用されます。認証情報には、ホスト名、ポート、ユーザ名、パスワードがあります。
log is an optional parameter controlling log output verbosity and format (see below).

環境設定用パラメーター¶

`max_proposal_size`は1つのプロポーザルに入れることができるトランザクションの最大数であり、それらは全て1つのブロックに格納されます。したがって、この値を変更することによって、新規作成されるブロックのサイズが定義されます。はじめは「10」に設定しておくと良いでしょう。ただし、秒間取引量が多い場合には、この値を大きくすることをお勧めします。
proposal_delay is a timeout in milliseconds that a peer waits a response from the orderding service with a proposal.
`vote_delay`は、次のピア（ネットワークノード）に投票を送るまでの待ち時間（ミリ秒）です。最適な値は、ネットワーク内のいろはピア数に大きく依存します（ノード数が多いほど、「vote_delay」には長い値が必要）。はじめは100〜1000ミリ秒で設定することをお勧めします。
mst_enable enables or disables multisignature transaction network transport in Iroha. Note that MST engine always works for any peer even when the flag is set to false. The flag only allows sharing information about MST transactions among the peers.
mst_expiration_time is an optional parameter specifying the time period in which a not fully signed transaction (or a batch) is considered expired (in minutes). The default value is 1440.
max_rounds_delay is an optional parameter specifying the maximum delay between two consensus rounds (in milliseconds). The default value is 3000. When Iroha is idle, it gradually increases the delay to reduce CPU, network and logging load. However too long delay may be unwanted when first transactions arrive after a long idle time. This parameter allows users to find an optimal value in a tradeoff between resource consumption and the delay of getting back to work after an idle period.
stale_stream_max_rounds is an optional parameter specifying the maximum amount of rounds to keep an open status stream while no status update is reported. The default value is 2. Increasing this value reduces the amount of times a client must reconnect to track a transaction if for some reason it is not updated with new rounds. However large values increase the average number of connected clients during each round.
"initial_peers is an optional parameter specifying list of peers a node will use after startup instead of peers from genesis block. It could be useful when you add a new node to the network where the most of initial peers may become malicious. Peers list should be provided as a JSON array:

"initial_peers" : [{"address":"127.0.0.1:10001", "public_key": "bddd58404d1315e0eb27902c5d7c8eb0602c16238f005773df406bc191308929"}]

Logging¶

In Iroha logging can be adjusted as granularly as you want. Each component has its own logging configuration with properties inherited from its parent, able to be overridden through config file. This means all the component loggers are organized in a tree with a single root. The relevant section of the configuration file contains the overriding values:

"log": {
  "level": "info",
  "patterns": {
    "debug": "don't panic, it's %v.",
    "error": "MAMA MIA! %v!!!"
  },
  "children": {
    "KeysManager": {
      "level": "trace"
    },
    "Irohad": {
      "children": {
        "Storage": {
          "level": "trace",
          "patterns": {
            "debug": "thread %t: %v."
          }
        }
      }
    }
  }
}

Every part of this config section is optional.

level sets the verbosity. Available values are (in decreasing verbosity order):
- trace - print everything
- debug
- info
- warning
- error
- critical - print only critical messages
patterns controls the formatting of each log string for different verbosity levels. Each value overrides the less verbose levels too. So in the example above, the "don't panic" pattern also applies to info and warning levels, and the trace level pattern is the only one that is not initialized in the config (it will be set to default hardcoded value).
children describes the overrides of child nodes. The keys are the names of the components, and the values have the same syntax and semantics as the root log configuration.

いろはを運用・導入する¶

Hyperledger Irohaは、視点と目的に応じてさまざまな方法でシステムを導入することができます。単一ノードでデプロイされている場合もあれば、複数のノードがローカルマシン上の複数のコンテナで実行される場合や、ネットワーク全体に分散している場合もあります。このページでは、さまざまな導入シナリオについて説明し、初めてイロハを試してユーザーの皆さんのためのハウツーガイドとして役立つように意図されています。

１つのインスタンス上で実行する¶

一般的に、まずイロハをローカルで実行してAPIを試し、その機能を試したいと考えています。これはローカルまたはコンテナ環境（Docker）で行うことができます。両方のケースを試してみますが、ピアコンポーネントの運用を簡素化するために、あなたのマシンにDockerをインストールすることをお勧めします。

ローカル環境¶

ローカル環境では、デーモンプロセスとPostgresをコンテナなしで運用することを想定しています。 Dockerを使いこなすことが好まれない場合に役立ちますが、機能をざっくり試してみたいというときに便利な方法です。

postgresサーバーを起動させる¶

postgresサーバーをローカルで実行するには、postgres ウェブサイト<https://www.postgresql.org/docs/current/static/server-start.html> __に移動し、そのページの説明に従ってください。一般に、postgresサーバーは、システムの起動時に自動的に実行されますが、この点についてはシステム設定で確認してください。

いろはデーモン(irohad)を実行する¶

これから先に進む前に、以下の前提条件が満たされていなければなりません：

Postgresサーバーが起動され、実行されている

irohad Iroha daemonのバイナリ形式が構築され、利用可能な状態にある

genesis blockを設定ファイルが生成されている

設定ファイルで有効なpostgres接続の設定がなされている

ピアの鍵ペアが生成されている

これからこのピアのもとにイロハをはじめて実行し、新しいチェーンをこれから作成していく

ヒント

上記の前提条件リストと一致していないものがありますか？この文書の下のセクション、「問題に対処する」の項を参照してください。

全ての条件が整えば、あとは以下のパラメーターを用いてデーモンプロセスを起動させるだけです：

パラメーター	意味
config	Postgresへの接続とシステムを調整するための値を含む設定ファイル
genesis_block	台帳上の１つ目のブロック
keypair_name	ファイル拡張子なしの秘密鍵・公開鍵ファイル名。ブロックに署名する際にピアによって使用されるもの。

注意

Specifying a new genesis block using --genesis_block with blocks already present in ledger requires --overwrite_ledger flag to be set. The daemon will fail otherwise.

いろはデーモンを実行する際のコマンド例は、

irohad --config example/config.sample --genesis_block example/genesis.block --keypair_name example/node0

注意

もし一旦デーモンを停止しさせ、既存のチェーンを使用したい場合は、ジェネシスブロックのパラメータを渡さないでください。

Docker¶

Dockerを用いながら１つのインスタンス上でいろはノードを実行させたい場合は、まずIrohaのイメージをプルしてください：

docker pull hyperledger/iroha:latest

ヒント

最新の安定版は*latest*タグを、最新の開発版は*develop*してください

次に、正常にイメージを実行するための環境づくりをする必要があります。

dockerネットワークを構築する¶

PostgresとIrohaのコンテナは、それぞれ相互に利用できるように、同じ仮想ネットワーク上で実行する必要があります。次のコマンドを入力してネットワークを作成します（ネットワークには任意の名前を使用できますが、例では* iroha-network * nameを使用しています）。

docker network create iroha-network

コンテナ内でPostgresqlを実行させる¶

同様に、postgresサーバーを実行して、これまでに作成したネットワークに接続し、通信用にポートを公開します。

docker run --name some-postgres \
-e POSTGRES_USER=postgres \
-e POSTGRES_PASSWORD=mysecretpassword \
-p 5432:5432 \
--network=iroha-network \
-d postgres:9.5

ブロックの記録・保存用のボリュームを作成する¶

コンテナ内でirohaデーモンを実行する前に、ファイルを格納する永続ボリュームを作成し、チェーンのブロックを格納する必要があります。これらは次のコマンドで行います。

docker volume create blockstore

Dockerコンテナでいろはデーモンを実行する¶

下記の条件が必須です：

PostgreSQLのサーバーが同じdockerネットワークで実行している
各サーバーにconfigファイル及びキーペアが持っているフォルダがある
これからこのピアのもとにイロハをはじめて実行し、新しいチェーンをこれから作成していく

上記の条件が叶えたら、下記のコマンドを実行してください

docker run --name iroha \
# External port
-p 50051:50051 \
# Folder with configuration files
-v ~/Developer/iroha/example:/opt/iroha_data \
# Blockstore volume
-v blockstore:/tmp/block_store \
# Postgres settings
-e POSTGRES_HOST='some-postgres' \
-e POSTGRES_PORT='5432' \
-e POSTGRES_PASSWORD='mysecretpassword' \
-e POSTGRES_USER='postgres' \
# Node keypair name
-e KEY='node0' \
# Docker network name
--network=iroha-network \
hyperledger/iroha:latest

ピアのネットワークを起動する¶

ピアネットワークを設定するには、このセクションで説明するルーチンを実行してください。このバージョンでは、手動での運用設定が可能で、またAnsible Playbookによって自動化されています。セキュリティ基準やその他の要件を満たすオプションを選択してください。

手動で行う方法¶

手動での実行では、自動化された支援なしにイロハ・ピア・ネットワークがセットアップされます。単一のローカルインスタンスを実行するプロセスと似ていますが、違いはジェネシスブロックに複数のピアが含まれていることです。複数のピアを含むブロックを作成する場合、あるいは必要に応じてカスタマイズする必要がある場合は、「問題に対処する」の項を参照してください。

自動で行う方法¶

問題を解決する¶

—"Please, help me, because I…"

Do not have Iroha daemon binary¶

You can build Iroha daemon binary from sources. You can get binaries here

Do not have a config file¶

Check how to create a configuration file by following this link

Do not have a genesis block¶

Create genesis block by generating it via iroha-cli or manually, using the example and checking out permissions

Do not have a keypair for a peer¶

In order to create a keypair for an account or a peer, use iroha-cli binary by passing the name of the peer with --new_account option. For example:

./iroha-cli --account_name newuser@test --new_account

クライアント・ライブラリ¶

Javaライブラリ¶

Client library of Iroha written completely in Java 8, which includes:

SDK to work with Iroha API
async wrapper over Iroha API
testcontainers wrapper for convenient integration testing with Iroha
examples in Java and Groovy

Both options are described in the following sections. Please check readme file in project's repo.

How to use¶

コード例¶

import iroha.protocol.BlockOuterClass;
import iroha.protocol.Primitive.RolePermission;
import java.math.BigDecimal;
import java.security.KeyPair;
import java.util.Arrays;
import jp.co.soramitsu.crypto.ed25519.Ed25519Sha3;
import jp.co.soramitsu.iroha.testcontainers.IrohaContainer;
import jp.co.soramitsu.iroha.testcontainers.PeerConfig;
import jp.co.soramitsu.iroha.testcontainers.detail.GenesisBlockBuilder;
import lombok.val;

public class Example1 {

  private static final String bankDomain = "bank";
  private static final String userRole = "user";
  private static final String usdName = "usd";

  private static final Ed25519Sha3 crypto = new Ed25519Sha3();

  private static final KeyPair peerKeypair = crypto.generateKeypair();

  private static final KeyPair useraKeypair = crypto.generateKeypair();
  private static final KeyPair userbKeypair = crypto.generateKeypair();

  private static String user(String name) {
    return String.format("%s@%s", name, bankDomain);
  }

  private static final String usd = String.format("%s#%s", usdName, bankDomain);

  /**
   * <pre>
   * Our initial state cosists of:
   * - domain "bank", with default role "user" - can transfer assets and can query their amount
   * - asset usd#bank with precision 2
   * - user_a@bank, which has 100 usd
   * - user_b@bank, which has 0 usd
   * </pre>
   */
  private static BlockOuterClass.Block getGenesisBlock() {
    return new GenesisBlockBuilder()
        // first transaction
        .addTransaction(
            // transactions in genesis block can have no creator
            Transaction.builder(null)
                // by default peer is listening on port 10001
                .addPeer("0.0.0.0:10001", peerKeypair.getPublic())
                // create default "user" role
                .createRole(userRole,
                    Arrays.asList(
                        RolePermission.can_transfer,
                        RolePermission.can_get_my_acc_ast,
                        RolePermission.can_get_my_txs,
                        RolePermission.can_receive
                    )
                )
                .createDomain(bankDomain, userRole)
                // create user A
                .createAccount("user_a", bankDomain, useraKeypair.getPublic())
                // create user B
                .createAccount("user_b", bankDomain, userbKeypair.getPublic())
                // create usd#bank with precision 2
                .createAsset(usdName, bankDomain, 2)
                // transactions in genesis block can be unsigned
                .build() // returns ipj model Transaction
                .build() // returns unsigned protobuf Transaction
        )
        // we want to increase user_a balance by 100 usd
        .addTransaction(
            Transaction.builder(user("user_a"))
                .addAssetQuantity(usd, new BigDecimal("100"))
                .build()
                .build()
        )
        .build();
  }

  public static PeerConfig getPeerConfig() {
    PeerConfig config = PeerConfig.builder()
        .genesisBlock(getGenesisBlock())
        .build();

    // don't forget to add peer keypair to config
    config.withPeerKeyPair(peerKeypair);

    return config;
  }

  /**
   * Custom facade over GRPC Query
   */
  public static int getBalance(IrohaAPI api, String userId, KeyPair keyPair) {
    // build protobuf query, sign it
    val q = Query.builder(userId, 1)
        .getAccountAssets(userId)
        .buildSigned(keyPair);

    // execute query, get response
    val res = api.query(q);

    // get list of assets from our response
    val assets = res.getAccountAssetsResponse().getAccountAssetsList();

    // find usd asset
    val assetUsdOptional = assets
        .stream()
        .filter(a -> a.getAssetId().equals(usd))
        .findFirst();

    // numbers are small, so we use int here for simplicity
    return assetUsdOptional
        .map(a -> Integer.parseInt(a.getBalance()))
        .orElse(0);
  }

  public static void main(String[] args) {
    // for simplicity, we will create Iroha peer in place
    IrohaContainer iroha = new IrohaContainer()
        .withPeerConfig(getPeerConfig());

    // start the peer. blocking call
    iroha.start();

    // create API wrapper
    IrohaAPI api = new IrohaAPI(iroha.getToriiAddress());

    // transfer 100 usd from user_a to user_b
    val tx = Transaction.builder("user_a@bank")
        .transferAsset("user_a@bank", "user_b@bank", usd, "For pizza", "10")
        .sign(useraKeypair)
        .build();

    // create transaction observer
    // here you can specify any kind of handlers on transaction statuses
    val observer = TransactionStatusObserver.builder()
        // executed when stateless or stateful validation is failed
        .onTransactionFailed(t -> System.out.println(String.format(
            "transaction %s failed with msg: %s",
            t.getTxHash(),
            t.getErrOrCmdName()
        )))
        // executed when got any exception in handlers or grpc
        .onError(e -> System.out.println("Failed with exception: " + e))
        // executed when we receive "committed" status
        .onTransactionCommitted((t) -> System.out.println("Committed :)"))
        // executed when transfer is complete (failed or succeed) and observable is closed
        .onComplete(() -> System.out.println("Complete"))
        .build();

    // blocking send.
    // use .subscribe() for async sending
    api.transaction(tx)
        .blockingSubscribe(observer);

    /// now lets query balances
    val balanceUserA = getBalance(api, user("user_a"), useraKeypair);
    val balanceUserB = getBalance(api, user("user_b"), userbKeypair);

    // ensure we got correct balances
    assert balanceUserA == 90;
    assert balanceUserB == 10;
  }
}

Javascript library¶

https://img.shields.io/npm/v/iroha-helpers.svg

This library provides functions which will help you to interact with Hyperledger Iroha from your JS program.

Installation¶

Via npm

$ npm i iroha-helpers

Via yarn

$ yarn add iroha-helpers

Commands¶

For usage of any command you need to provide commandOptions as a first argument.

const commandOptions = {
  privateKeys: ['f101537e319568c765b2cc89698325604991dca57b9716b58016b253506cab70'], // Array of private keys in hex format
  creatorAccountId: '', // Account id, ex. admin@test
  quorum: 1,
  commandService: null
}

As second argument you need to provide object that contains properties for required command.

// Example usage of setAccountDetail

const commandService = new CommandService_v1Client(
  '127.0.0.1:50051',
  grpc.credentials.createInsecure()
)

const adminPriv = 'f101537e319568c765b2cc89698325604991dca57b9716b58016b253506cab70'

commands.setAccountDetail({
  privateKeys: [adminPriv],
  creatorAccountId: 'admin@test',
  quorum: 1,
  commandService
}, {
  accountId: 'admin@test',
  key: 'jason',
  value: 'statham'
})

Queries¶

For usage of any query you need to provide queryOptions as a first argument.

const queryOptions = {
  privateKey: 'f101537e319568c765b2cc89698325604991dca57b9716b58016b253506cab70', // Private key in hex format
  creatorAccountId: '', // Account id, ex. admin@test
  queryService: null
}

As second argument you need to provide object that contains properties for required query.

// Example usage of getAccountDetail

const queryService = new QueryService_v1Client(
  '127.0.0.1:50051',
  grpc.credentials.createInsecure()
)

const adminPriv = 'f101537e319568c765b2cc89698325604991dca57b9716b58016b253506cab70'

queries.getAccountDetail({
  privateKey: adminPriv,
  creatorAccountId: 'admin@test',
  queryService
}, {
  accountId: 'admin@test'
})

Example code¶

import grpc from 'grpc'
import {
  QueryService_v1Client,
  CommandService_v1Client
} from '../iroha-helpers/lib/proto/endpoint_grpc_pb'
import { commands, queries } from 'iroha-helpers'

const IROHA_ADDRESS = 'localhost:50051'
const adminPriv =
  'f101537e319568c765b2cc89698325604991dca57b9716b58016b253506cab70'

const commandService = new CommandService_v1Client(
  IROHA_ADDRESS,
  grpc.credentials.createInsecure()
)

const queryService = new QueryService_v1Client(
  IROHA_ADDRESS,
  grpc.credentials.createInsecure()
)

Promise.all([
  commands.setAccountDetail({
    privateKeys: [adminPriv],
    creatorAccountId: 'admin@test',
    quorum: 1,
    commandService
  }, {
    accountId: 'admin@test',
    key: 'jason',
    value: 'statham'
  }),
  queries.getAccountDetail({
    privateKey: adminPriv,
    creatorAccountId: 'admin@test',
    queryService
  }, {
    accountId: 'admin@test'
  })
])
  .then(a => console.log(a))
  .catch(e => console.error(e))

Pythonライブラリ¶

入手先¶

A supported python library for Iroha is available at its own Hyperledger iroha-python repo. Python 3+ is supported.

You can also install Python library via pip:

pip install iroha

コード例¶

from iroha import Iroha, IrohaCrypto, IrohaGrpc

iroha = Iroha('alice@test')
net = IrohaGrpc('127.0.0.1:50051')

alice_key = IrohaCrypto.private_key()
alice_tx = iroha.transaction(
 [iroha.command(
     'TransferAsset',
     src_account_id='alice@test',
     dest_account_id='bob@test',
     asset_id='bitcoin#test',
     description='test',
     amount='1'
 )]
)

IrohaCrypto.sign_transaction(alice_tx, alice_key)
    net.send_tx(alice_tx)

for status in net.tx_status_stream(alice_tx):
    print(status)

iOS Swift Library¶

The library was created to provide convenient interface for iOS applications to communicate with Iroha blockchain including sending transactions/query, streaming transaction statuses and block commits.

Where to get¶

Iroha iOS library is available through CocoaPods. To install it, simply add the following line to your Podfile:

pod 'IrohaCommunication'

Also you can download the source code for the library in its repo

How to use¶

For new Iroha users we recommend to checkout iOS example project. It tries to establish connection with Iroha peer which should be also run locally on your computer to create new account and send some asset quantity to it. To run the project, please, go through steps below:

Follow instructions from Iroha documentation to setup and run iroha peer in Docker container.
Clone iroha-ios repository.
cd Example directory and run pod install.
Open IrohaCommunication.xcworkspace in XCode
Build and Run IrohaExample target.
Consider logs to see if the scenario completed successfully.

Feel free to experiment with example project and don't hesitate to ask any questions in Rocket.Chat.

Installing Dependencies¶

This page contains references and guides about installation of various tools you may need during build of different targets of Iroha project.

注釈

Please note that most likely you do not need to install all the listed tools. Some of them are required only for building specific versions of Iroha Client Library.

Automake¶

Installation on Ubuntu¶

sudo apt install automake
automake --version
# automake (GNU automake) 1.15

Bison¶

Installation on Ubuntu¶

sudo apt install bison
bison --version
# bison (GNU Bison) 3.0.4

CMake¶

Minimum required version is 3.11.4, but we recommend to install the latest available version (3.12.0 at the moment).

Installation on Ubuntu¶

Since Ubuntu repositories contain unsuitable version of CMake, you need to install the new one manually. Here is how to build and install CMake from sources.

wget https://cmake.org/files/v3.11/cmake-3.11.4.tar.gz
tar -xvzf cmake-3.11.4.tar.gz
cd cmake-3.11.4/
./configure
make
sudo make install
cmake --version
# cmake version 3.11.4

Installation on macOS¶

brew install cmake
cmake --version
# cmake version 3.12.1

Git¶

Installation on Ubuntu¶

sudo apt install git
git --version
# git version 2.7.4

Python¶

Installation on Ubuntu¶

For Python 2:

sudo apt install python-dev
python --version
# Python 2.7.12

For Python 3:

sudo apt install python3-dev
python3 --version
# Python 3.5.2

Installation on macOS¶

For Python 2:

brew install python
python --version
# Python 2.7.12

For Python 3:

brew install python3
python3 --version
# Python 3.5.2

PIP¶

Installation on Ubuntu¶

For Python 2:

sudo apt install python-pip
pip --version
# pip 8.1.1 from /usr/lib/python2.7/dist-packages (python 2.7)

For Python 3:

sudo apt install python3-pip
pip3 --version
# pip 8.1.1 from /usr/lib/python3/dist-packages (python 3.5)

Installation on macOS¶

For Python 2:

sudo easy_install pip
pip --version
# pip 9.0.3 from /usr/local/lib/python2.7/site-packages (python 2.7)

For Python 3:

wget https://bootstrap.pypa.io/get-pip.py
sudo python3 get-pip.py
python3 -m pip --version
# pip 9.0.3 from /usr/local/Cellar/python/3.6.4_4/Frameworks/Python.framework/Versions/3.6/lib/python3.6/site-packages (python 3.6)

Boost¶

Installation on Ubuntu¶

git clone https://github.com/boostorg/boost /tmp/boost;
(cd /tmp/boost ; git submodule update --init --recursive);
(cd /tmp/boost ; /tmp/boost/bootstrap.sh);
(cd /tmp/boost ; /tmp/boost/b2 headers);
(cd /tmp/boost ; /tmp/boost/b2 cxxflags="-std=c++14" install);
ldconfig;
rm -rf /tmp/boost

Installation on macOS¶

brew install boost

Protobuf¶

Installation on macOS¶

CMAKE_BUILD_TYPE="Release"
git clone https://github.com/google/protobuf /tmp/protobuf;
(cd /tmp/protobuf ; git checkout 106ffc04be1abf3ff3399f54ccf149815b287dd9);
cmake \
    -DCMAKE_BUILD_TYPE=${CMAKE_BUILD_TYPE} \
    -Dprotobuf_BUILD_TESTS=OFF \
    -Dprotobuf_BUILD_SHARED_LIBS=ON \
    -H/tmp/protobuf/cmake \
    -B/tmp/protobuf/.build;
cmake --build /tmp/protobuf/.build --target install;
ldconfig;
rm -rf /tmp/protobuf

Deploying Iroha on Kubernetes cluster¶

By following this guide you will be able to deploy a Kubernetes cluster from scratch on AWS cloud using Terraform and Kubespray, and deploy a network of Iroha nodes on it.

Prerequisites¶

machine running Linux (tested on Ubuntu 16.04) or MacOS

Python 3.3+

boto3

Ansible 2.4+

ed25519-cli utility for key generation. Statically linked binary (for x86_64 platform) can be found in deploy/ansible/playbooks/iroha-k8s/scripts directory. You may need to compile it yourself.

You do not need the items below if you already have a working Kubernetes (k8s) cluster. You can skip to Generating Iroha configs chapter.

Terraform 0.11.8+

AWS account for deploying a k8s cluster on EC2

Preparation¶

You need to obtain AWS key for managing resources. We recommend to create a separate IAM user for that. Go to your AWS console, head to "My Security Credentials" menu and create a user in "Users" section. Assign "AmazonEC2FullAccess" and "AmazonVPCFullAccess" policies to that user. Click "Create access key" on Security credentials tab. Take a note for values of Access key ID and Secret key. Set these values as environment variables in your console:

export AWS_ACCESS_KEY_ID='<The value of Access key ID>'
export AWS_SECRET_ACCESS_KEY='<The value of Secret key>'

Checkout the source tree from Github:

git clone https://github.com/hyperledger/iroha && cd iroha

Setting up cloud infrastructure¶

We use Hashicorp's Terraform infrastructure management tool for automated deployment of AWS EC2 nodes in multiple regions. Kubespray Ansible module is used for setting up a production-grade k8s cluster.

Terraform module creates 3 AWS instances in 3 different regions: eu-west-1, eu-west-2, eu-west-3 by default. Instance type is c5.large. There is a separate VPC created in every region. All created VPCs are then connected using VPC peering connection. That is to create a seamless network for k8s cluster.

There are several configurable options: number of nodes in each region and its role in k8s cluster (kube-master or kube-node). They can be set either in variables.tf file or via environment variables (using the same variable name but prefixed with TF_VAR. See more in Terraform docs). More options can be configured by tuning parameters in module's variables.tf file.

You must set up SSH key in deploy/tf/k8s/variables.tf as well. Replace public key with your own. It will added on each created EC2 instance.

Navigate to deploy/tf/k8s directory. Terraform needs to download required modules first:

pushd deploy/tf/k8s && terraform init

Then run module execution:

terraform apply && popd

Review the execution plan and type yes to approve. Upon completion you should see an output similar to this:

Apply complete! Resources: 39 added, 0 changed, 0 destroyed.

We are now ready to deploy k8s cluster. Wait a couple of minutes before instances are initialized.

Setting up k8s cluster¶

There is an Ansible role for setting up k8s cluster. It is an external module called Kubespray. It is stored as a submodule in Hyperledger Iroha repository. This means it needs to be initialized first:

git submodule init && git submodule update

This command will download Kubespray from master repository.

Install required dependencies:

pip3 install -r deploy/ansible/kubespray/requirements.txt

Proceed to actual cluster deployment. Make sure you replaced key-file parameter with an actual path to SSH private key that was used previously during Terraform configuration. REGIONS variable corresponds to default list of regions used on a previous step. Modify it accordingly in case you added or removed any. Inventory file is a Python script that returns Ansible-compatible list of hosts filtered by tag.

pushd deploy/ansible && REGIONS="eu-west-1,eu-west-2,eu-west-3" VPC_VISIBILITY="public" ansible-playbook -u ubuntu -b --ssh-extra-args="-o IdentitiesOnly=yes" --key-file=<PATH_TO_SSH_KEY> -i inventory/kubespray-aws-inventory.py kubespray/cluster.yml
popd

Upon successful completion you will have working k8s cluster.

Generating Iroha configs¶

In order for Iroha to work properly it requires to generate a key pair for each node, genesis block and configuration file. This is usually a tedious and error-prone procedure, especially for a large number of nodes. We automated it with Ansible role. You can skip to Deploying Iroha on the cluster chapter if you want to quick start using default configs for k8s cluster with 4 Iroha replicas.

Generate configuration files for N Iroha nodes. replicas variable controls the number of N:

pushd deploy/ansible && ansible-playbook -e 'replicas=7' playbooks/iroha-k8s/iroha-deploy.yml
popd

You should find files created in deploy/ansible/roles/iroha-k8s/files/conf.

Deploying Iroha on the cluster¶

Make sure you have configuration files in deploy/ansible/roles/iroha-k8s/files. Specifically, non-empty conf directory and k8s-iroha.yaml file.

There are two options for managing k8s cluster: logging into either of master node and executing commands there or configure remote management. We will cover the second option here as the first one is trivial.

In case you set up cluster using Kubespray, you can find admin.conf file on either of master node in /etc/kubernetes directory. Copy this file on the control machine (the one you will be running kubectl command from). Make sure server parameter in this file points to external IP address or DNS name of a master node. Usually, there is a private IP address of the node (in case of AWS). Make sure kubectl utility is installed (check out the docs for instructions).

Replace the default kubectl configuration:

export KUBECONFIG=<PATH_TO_admin.conf>

We can now control the remote k8s cluster

k8s-iroha.yaml pod specification file requires the creation of a config-map first. This is a special resource that is mounted in the init container of each pod, and contains the configuration and genesis block files required to run Iroha.

kubectl create configmap iroha-config --from-file=deploy/ansible/roles/iroha-k8s/files/conf/

Each peer will have their public and private keys stored in a Kubernetes secret which is mounted in the init container and copied over for Iroha to use. Peers will only be able read their assigned secret when running Iroha.

kubectl create -f deploy/ansible/roles/iroha-k8s/files/k8s-peer-keys.yaml

Deploy Iroha network pod specification:

kubectl create -f deploy/ansible/roles/iroha-k8s/files/k8s-iroha.yaml

Wait a moment before each node downloads and starts Docker containers. Executing kubectl get pods command should eventually return a list of deployed pods each in Running state.

ヒント

Pods do not expose ports externally. You need to connect to Iroha instance by its hostname (iroha-0, iroha-1, etc). For that you have to have a running pod in the same network.

Iroha installation security tips¶

This guide is intended to secure Iroha installation. Most of the steps from this guide may seem obvious but it helps to avoid possible security problems in the future.

Physical security¶

In case the servers are located locally (physically accessible), a number of security measures have to be applied. Skip these steps if cloud hosting is used.

Establish organisational policy and/or access control system such that only authorized personnel has access to the server room. Next, set BIOS/firmware password and configure boot order to prevent unauthorized booting from alternate media. Make sure the bootloader is password protected if there is such a functionality. Also, it is good to have a CCTV monitoring in place.

Deployment¶

First, verify that official repository is used for downloading source code and Docker images. Change any default passwords that are used during installation, e.g., password for connecting to postgres. Iroha repository contains examples of private and public keys - never use it in production. Moreover, verify that new keypairs are generated in a safe environment and only administrator has access to those keypairs (or at least minimise the number of people). After deploying keys to Iroha peers delete private keys from the host that was used to perform deployment, i.e. private keys should reside only inside Iroha peers. Create an encrypted backup of private keys before deleting them and limit the access to it.

Network configuration¶

Iroha listens on ports 50051 and 10001. Firewall settings must allow incoming/outgoing connections to/from these ports. If possible, disable or remove any other network services with listening ports (FTP, DNS, LDAP, SMB, DHCP, NFS, SNMP, etc). Ideally, Iroha should be as much isolated as possible in terms of networking.

Currently, there is no traffic encryption in Iroha, we strongly recommend using VPN or Calico for setting up Docker overlay network, i.e. any mechanism that allows encrypting communication between peers. Docker swarm encrypts communications by default, but remember to open necessary ports in the firewall configuration. In case VPN is used, verify that VPN key is unavailable to other users.

If SSH is used, disable root login. Apart from that, disable password authentication and use only keys. It might be helpful to set up SSH log level to INFO as well.

If IPv6 is not used, it might be a good idea to disable it.

Updates¶

Install the latest operating system security patches and update it regularly. If Iroha is running in Docker containers, update Docker regularly. While being optional, it is considered a good practice to test updates on a separate server before installing to production.

Logging and monitoring¶

Collect and ship logs to a dedicated machine using an agent (e.g., Filebeat).
Collect logs from all Iroha peers in a central point (e.g., Logstash).
Transfer logging and monitoring information via an encrypted channel (e.g., https).
Set up an authentication mechanism to prevent third parties from accessing logs.
Set up an authentication mechanism to prevent third parties from submitting logs.
Log all administrator access.

OS hardening¶

The following steps assume Docker is used for running Iroha.

Enable and configure Docker Content Trust.
Allow only trusted users to control Docker daemon.
Set up a limit for Docker container resources.

いろは（Hyperledger Iroha）のAPIリファレンス¶

APIセクションでは、実際にいろはでの動作を見ながら、いろはを構成する要素について見ていきます。システムが持つコマンドやクエリの種類、およびトランスポート層とアプリケーション層にわたるクライアントライブラリを概観します。

利用可能なコマンド一覧¶

コマンドは、システム内のエンティティ（アセット、アカウント）に対する特定のアクションを実行することにより、システムの状態（World State Viewと呼ばれる）を変更させます。アクションを実行するには、コマンドをトランザクションに含める必要があります。

該当資産の量を追加する¶

目的¶

資産量を追加するコマンド（add asset quantity）の目的は、取引作成者のアカウント内の資産量を増やすことです。ユースケースのシナリオでは、システム内の変更可能な資産の数を増やすことであり、それらは商品（例えば、貨幣や金など）に対する権利として機能します。

スキーム¶

message AddAssetQuantity {
    string asset_id = 1;
    string amount = 2;
}

注釈

Please note that due to a known issue you would not get any exception if you pass invalid precision value. Valid range is: 0 <= precision <= 255

構造¶

フィールド	説明	制約	例
資産ID	資産のID	<asset_name>#<domain_id>	usd#morgan
量	追加すべき資産量（正数）	>0	200.02

検証¶

資産とアカウントがなければなりません
追加された数量の精度は、資産精度と同じである必要があります
トランザクションの作成者は、資産を発行する権限を有している必要があります

Possible Stateful Validation Errors¶

Code	Error Name	説明	How to solve
1	Could not add asset quantity	Internal error happened	Try again or contact developers
2	No such permissions	Command's creator does not have permission to add asset quantity	Grant the necessary permission
3	No such asset	Cannot find asset with such name or such precision	Make sure asset id and precision are correct
4	Summation overflow	Resulting amount of asset is greater than the system can support	Make sure that resulting amount is less than 2^256

ピア（ノード）を追加する¶

目的¶

add peerコマンドの目的は、ピアネットワークに向けてピアが追加された事実を台帳に書き込むことです。 AddPeerが実行されたトランザクションがコミットされた後、コンセンサスおよび同期コンポーネントがそれらの事実を適用し始めます。

スキーム¶

message AddPeer {
    Peer peer = 1;
}

message Peer {
    string address = 1;
    bytes peer_key = 2;
}

構造¶

フィールド	説明	制約	例
アドレス	ネットワーク内の解決可能なアドレス（IPv4、IPv6、ドメイン名など）	解決可能なはずです	192.168.1.1:50541
ピアが保有する鍵	ピアの公開鍵（投票時のサインオフ、コミット、メッセージの拒否といった合意形成アルゴリズムで使用されます）	ed25519 公開鍵	292a8714694095edce6be799398ed5d6244cd7be37eb813106b217d850d261f2

検証¶

Peer key is unique (there is no other peer with such public key)
トランザクションの作成者にはCanAddPeerの権限を有する役割が与えられています
そのようなネットワークアドレスはまだ追加されていません

Possible Stateful Validation Errors¶

Code	Error Name	説明	How to solve
1	Could not add peer	Internal error happened	Try again or contact developers
2	No such permissions	Command's creator does not have permission to add peer	Grant the necessary permission

署名者を追加する¶

目的¶

署名追加のためのコマンドの目的は、アカウントに識別子を与えることです。それら識別子は、他の端末の公開鍵またはユーザの公開鍵が用いられます。

スキーム¶

message AddSignatory {
    string account_id = 1;
    bytes public_key = 2;
}

構造¶

フィールド	説明	制約	例
アカウントID	新たな署名者を追加するアカウント	<account_name>@<domain_id>	makoto@soramitsu
公開鍵	アカウントに追加する署名者	ed25519 公開鍵	359f925e4eeecfdd6aa1abc0b79a6a121a5dd63bb612b603247ea4f8ad160156

検証¶

２つの事例：

ケース1：CanAddSignatoryの権限を有する取引作成者が、署名を自分のアカウントに追加したいと考えています。

ケース2. CanAddSignatoryがトランザクション作成者に付与されました

Possible Stateful Validation Errors¶

Code	Error Name	説明	How to solve
1	Could not add signatory	Internal error happened	Try again or contact developers
2	No such permissions	Command's creator does not have permission to add signatory	Grant the necessary permission
3	No such account	Cannot find account to add signatory to	Make sure account id is correct
4	Signatory already exists	Account already has such signatory attached	Choose another signatory

役割を追加する¶

目的¶

AppendRole（役割の追加）コマンドの目的は、システム内で既に存在する役割をあるアカウントが担うことができるようにすることです。この役割（Role）とは、アカウントがシステム内での特定のアクション（コマンド又はクエリ）を実行するために必要な権限です。

スキーム¶

message AppendRole {
   string account_id = 1;
   string role_name = 2;
}

構造¶

フィールド	説明	制約	例
アカウントID	役割を追加するIDまたはアカウント	既に存在する	makoto@soramitsu
Role name (役割名)	システム内ですでに規定された役割名	既に存在する	貨幣の発行者

検証¶

役割はシステムに存在しているはずです
取引の作成者は役割を追加する権限が必要です（CanAppendRole）
Account, which appends role, has set of permissions in his roles that is a superset of appended role (in other words no-one can append role that is more powerful than what transaction creator is)

Possible Stateful Validation Errors¶

Code	Error Name	説明	How to solve
1	Could not append role	Internal error happened	Try again or contact developers
2	No such permissions	Command's creator does not have permission to append role	Grant the necessary permission
3	No such account	Cannot find account to append role to	Make sure account id is correct
4	No such role	Cannot find role with such name	Make sure role id is correct

アカウントを新規作成する¶

目的¶

CreateAccountコマンドの目的は、トランザクションやクエリの送信、署名者、個人情報および識別子を格納することができるエンティティをシステム内に作成することです。

スキーム¶

message CreateAccount {
    string account_name = 1;
    string domain_id = 2;
    bytes public_key = 3;
}

構造¶

フィールド	説明	制約	例
Account name（アカウント名）	ドメイン内で一意のアカウント名	[a-z_0-9]{1,32}	morgan_stanley
ドメインID	関係するターゲットドメイン	アカウントの前に作成する必要があります	america
公開鍵	アカウントに追加する最初の公開鍵	ed25519 公開鍵	407e57f50ca48969b08ba948171bb2435e035d82cec417e18e4a38f5fb113f83

検証¶

取引作成者にはアカウントを作成する権限があります
domain_idとして渡されたドメインは、すでにシステム内で作成されています
そのような公開鍵は、アカウントの最初の公開鍵として追加されていないか、またはマルチ署名アカウントに追加されていません

Possible Stateful Validation Errors¶

Code	Error Name	説明	How to solve
1	Could not create account	Internal error happened	Try again or contact developers
2	No such permissions	Command's creator either does not have permission to create account or tries to create account in a more privileged domain, than the one creator is in	Grant the necessary permission or choose another domain
3	No such domain	Cannot find domain with such name	Make sure domain id is correct
4	Account already exists	Account with such name already exists in that domain	Choose another name

アセットを発行する¶

目的¶

create assetコマンドの目的は、ドメイン内で一意の新規アセットを作成することです。資産とは、商品の可算表現です。

スキーム¶

message CreateAsset {
    string asset_name = 1;
    string domain_id = 2;
    uint32 precision = 3;
}

注釈

Please note that due to a known issue you would not get any exception if you pass invalid precision value. Valid range is: 0 <= precision <= 255

構造¶

フィールド	説明	制約	例
Asset name (資産名)	ドメイン内で一意のアセット名	[a-z_0-9]{1,32}	soracoin
ドメインID	関係するターゲットドメイン	RFC1035 [1], RFC1123 [2]	japan
Precision (精度)	コンマ/ドットに後につづく桁数	0 <= precision <= 255	2

検証¶

トランザクション作成者にアセットを作成する権限があります
アセット名はドメイン内で一意です

Possible Stateful Validation Errors¶

Code	Error Name	説明	How to solve
1	Could not create asset	Internal error happened	Try again or contact developers
2	No such permissions	Command's creator does not have permission to create asset	Grant the necessary permission
3	No such domain	Cannot find domain with such name	Make sure domain id is correct
4	Asset already exists	Asset with such name already exists	Choose another name

ドメインを作成する¶

目的¶

CreateDomainコマンドの目的は、イロハネットワークに新しいドメインを作成することで、ドメインは複数のアカウントで構成されるひとつのグループです。

スキーム¶

message CreateDomain {
    string domain_id = 1;
    string default_role = 2;
}

構造¶

フィールド	説明	制約	例
ドメインID	作成されたドメインのID	一意に区別される、RFC1035 [1], RFC1123 [2]	japan05
デフォルトでの役割	ドメイン内で作成されたユーザーの役割	既にシステム内に存在する役割	User

検証¶

ドメインIDが一意
トランザクションでこのコマンドを送信するアカウントは、ドメインの作成権限を有する役割を持っていること
既に作成されていたユーザーに割り当てられる役割が、システム内に存在すること

Possible Stateful Validation Errors¶

Code	Error Name	説明	How to solve
1	Could not create domain	Internal error happened	Try again or contact developers
2	No such permissions	Command's creator does not have permission to create domain	Grant the necessary permission
3	Domain already exists	Domain with such name already exists	Choose another domain name
4	No default role found	Role, which is provided as a default one for the domain, is not found	Make sure the role you provided exists or create it

役割を作成する¶

目的¶

CreateRoleコマンドの目的は、一連の権限の中から新しい役割をシステム内に追加することです。イロハのピアネットワークの管理・運営担当者は、異なる権限を役割に組み合わせることで、カスタマイズされたセキュリティモデルを構築することができます。

スキーム¶

message CreateRole {
    string role_name = 1;
    repeated RolePermission permissions = 2;
}

構造¶

フィールド	説明	制約	例
Role name (役割名)	作成する役割の名称	[a-z_0-9]{1,32}	User
RolePermission	既存の権限の配列	渡された一連のアクセス許可は、既存のアクセス許可に全て含まれていること	{can_receive, can_transfer}

検証¶

渡された一連のアクセス許可は、既存のアクセス許可に全て含まれていること
ひとつ以上の権限が設定されていること

Possible Stateful Validation Errors¶

Code	Error Name	説明	How to solve
1	Could not create role	Internal error happened	Try again or contact developers
2	No such permissions	Command's creator does not have permission to create role	Grant the necessary permission
3	Role already exists	Role with such name already exists	Choose another role name

役割を切り離す¶

目的¶

DetachRoleコマンドの目的は、アカウントに付与された役割から特定の役割を切り離すことです。このコマンドを実行することにより、ユーザのシステムで実行可能なアクションの数を減らすことができます。

スキーム¶

message DetachRole {
    string account_id = 1;
    string role_name = 2;
}

構造¶

フィールド	説明	制約	例
アカウントID	役割が削除されるアカウントのID	既に存在する	makoto@soramitsu
Role name (役割名)	削除する役割の名称	既存の役割であること	User

検証¶

削除される役割がシステムに存在する
アカウントが削除される役割を持っている

Possible Stateful Validation Errors¶

Code	Error Name	説明	How to solve
1	Could not detach role	Internal error happened	Try again or contact developers
2	No such permissions	Command's creator does not have permission to detach role	Grant the necessary permission
3	No such account	Cannot find account to detach role from	Make sure account id is correct
4	No such role in account's roles	Account with such id does not have role with such name	Make sure account-role pair is correct
5	No such role	Role with such name does not exist	Make sure role id is correct

権限を与える¶

目的¶

GrantPermissionコマンドの目的は、取引の送信者のアカウントに対して特定のアクションを実行する権限を別のアカウントに与えることです（自分のアカウントに対して何かを行う権限を他者に与える）。

スキーム¶

message GrantPermission {
    string account_id = 1;
    GrantablePermission permission = 2;
}

構造¶

フィールド	説明	制約	例
アカウントID	id of the account to which the rights are granted	既に存在する	makoto@soramitsu
GrantablePermission name	name of grantable permission	許可が拒否される	CanTransferAssets

検証¶

アカウントが存在する
トランザクションの作成者がその許可を与えることができる

Possible Stateful Validation Errors¶

Code	Error Name	説明	How to solve
1	Could not grant permission	Internal error happened	Try again or contact developers
2	No such permissions	Command's creator does not have permission to grant permission	Grant the necessary permission
3	No such account	Cannot find account to grant permission to	Make sure account id is correct

署名者を削除する¶

目的¶

RemoveSignatoryコマンドの目的は、特定のIDと関連付けられた公開鍵をそのアカウントから削除することです

スキーム¶

message RemoveSignatory {
    string account_id = 1;
    bytes public_key = 2;
}

構造¶

フィールド	説明	制約	例
アカウントID	id of the account to which the rights are granted	既に存在する	makoto@soramitsu
公開鍵	削除する署名者	ed25519 公開鍵	407e57f50ca48969b08ba948171bb2435e035d82cec417e18e4a38f5fb113f83

検証¶

署名者の削除が実行された後に、** size（signatories）> = quorum **の不変式が成立するかどうかを調べる必要があります
署名者が削除される以前にアカウントに追加されていた必要があります

２つの事例：

ケース1：トランザクションの作成者が署名者をアカウントから削除したい場合、CanRemoveSignatoryの実行権限を得ていること

ケース2. CanRemoveSignatoryがトランザクション作成者に付与されていたこと

Possible Stateful Validation Errors¶

Code	Error Name	説明	How to solve
1	Could not remove signatory	Internal error happened	Try again or contact developers
2	No such permissions	Command's creator does not have permission to remove signatory from his account	Grant the necessary permission
3	No such account	Cannot find account to remove signatory from	Make sure account id is correct
4	No such signatory	Cannot find signatory with such public key	Make sure public key is correct
5	Quorum does not allow to remove signatory	After removing the signatory account will be left with less signatories, than its quorum allows	Reduce the quorum

権限を取り消す¶

目的¶

RevokePermissionコマンドの目的は、与えられていた権限をネットワーク内の別のアカウントから取り消すことです。

スキーム¶

message RevokePermission {
    string account_id = 1;
    GrantablePermission permission = 2;
}

構造¶

フィールド	説明	制約	例
アカウントID	id of the account to which the rights are granted	既に存在する	makoto@soramitsu
GrantablePermission name	name of grantable permission	実行権限が与えられていたこと	CanTransferAssets

検証¶

トランザクションの作成者は、以前にこの権限をターゲットアカウントに付与している必要があります

Possible Stateful Validation Errors¶

Code	Error Name	説明	How to solve
1	Could not revoke permission	Internal error happened	Try again or contact developers
2	No such permissions	Command's creator does not have permission to revoke permission	Grant the necessary permission
3	No such account	Cannot find account to revoke permission from	Make sure account id is correct

アカウントの詳細を設定する¶

目的¶

SetAccountDetailコマンドの目的は、特定のアカウントのキーバリュー情報を設定することです

警告

If there was a value for a given key already in the storage then it will be replaced with the new value

スキーム¶

message SetAccountDetail{
    string account_id = 1;
    string key = 2;
    string value = 3;
}

構造¶

フィールド	説明	制約	例
アカウントID	id of the account to which the key-value information was set	既に存在する	makoto@soramitsu
Key	設定されるキーに関する情報	[A-Za-z0-9_]{1,64}	Name
Value	対応するキーの値	≤ 4096	Makoto

検証¶

２つの事例：

ケース1.取引の作成者が口座の詳細情報を設定したい場合に、その作成者がCanSetAccountInfoの実行権限を得ている

ケース2. CanSetAccountInfoがトランザクション作成者に付与された場合

Possible Stateful Validation Errors¶

Code	Error Name	説明	How to solve
1	Could not set account detail	Internal error happened	Try again or contact developers
2	No such permissions	Command's creator does not have permission to set account detail for another account	Grant the necessary permission
3	No such account	Cannot find account to set account detail to	Make sure account id is correct

アカウントの定足数を設定する¶

目的¶

SetAccountQuorumコマンドの目的は、トランザクションを作成するユーザーの身元を確認するために必要な署名者の定足数を設定することです。ユース・ケース・シナリオにおいては、単一アカウントで異なるユーザー数を設定し、トランザクションをサインオフすることです。

スキーム¶

message SetAccountQuorum {
    string account_id = 1;
    uint32 quorum = 2;
}

構造¶

フィールド	説明	制約	例
アカウントID	定足数を設定するアカウントのID	既に存在する	makoto@soramitsu
Quorum	number of signatories needed to be included within a transaction from this account	0 < quorum ≤ public-key set up to account ≤ 128	5

検証¶

定足数が設定されると、**size(signatories) >= quorum**の不変式が成立するかどうかがチェックされます。

２つの事例：

ケース1.トランザクション作成者がアカウントの定足数を設定し、かつそのユーザーがCanRemoveSignatory権限を持っている場合

ケース2. CanRemoveSignatoryがトランザクション作成者に付与されていたこと

Possible Stateful Validation Errors¶

Code	Error Name	説明	How to solve
1	Could not set quorum	Internal error happened	Try again or contact developers
2	No such permissions	Command's creator does not have permission to set quorum for his account	Grant the necessary permission
3	No such account	Cannot find account to set quorum to	Make sure account id is correct
4	No signatories on account	Cannot find any signatories attached to the account	Add some signatories before setting quorum
5	New quorum is incorrect	New quorum size is less than account's signatories amount	Choose another value or add more signatories

資産量を減らす¶

目的¶

SubtractAssetQuantityコマンドの目的は、取引の作成者のアカウント内の資産量を減らすためです。AddAssetQuantityコマンドの逆の操作になります。

スキーム¶

message SubtractAssetQuantity {
    string asset_id = 1;
    string amount = 2;
}

注釈

Please note that due to a known issue you would not get any exception if you pass invalid precision value. Valid range is: 0 <= precision <= 255

構造¶

フィールド	説明	制約	例
資産ID	資産のID	<asset_name>#<domain_id>	usd#morgan
量	差し引く資産量（正数）	>0	200

検証¶

資産とアカウントがなければなりません
追加された数量の精度は、資産精度と同じである必要があります
トランザクションの作成者は、資産を引き出す権限を持つ役割を持つ必要があります

Possible Stateful Validation Errors¶

Code	Error Name	説明	How to solve
1	Could not subtract asset quantity	Internal error happened	Try again or contact developers
2	No such permissions	Command's creator does not have permission to subtract asset quantity	Grant the necessary permission
3	No such asset found	Cannot find asset with such name or precision in account's assets	Make sure asset name and precision are correct
4	Not enough balance	Account's balance is too low to perform the operation	Add asset to account or choose lower value to subtract

資産を移転させる¶

目的¶

TransferAssetコマンドの目的は、ピアネットワーク内のアカウント間で資産を共有することです。移転元アカウントが資産を移転先ターゲットアカウントに転送する方法です。

スキーム¶

message TransferAsset {
    string src_account_id = 1;
    string dest_account_id = 2;
    string asset_id = 3;
    string description = 4;
    string amount = 5;
}

構造¶

フィールド	説明	制約	例
Source account ID (移転元口座)	ID of the account to withdraw the asset from	既に存在する	makoto@soramitsu
Destination account ID (移転先口座)	ID of the account to send the asset to	既に存在する	alex@california
資産ID	ID of the asset to transfer	既に存在する	usd#usa
説明	Message to attach to the transfer	最大64文字まで	here's my money take it
量	移転する資産の量（金額など）	0 <= precision <= 255	200.20

検証¶

移転元アカウントのAccountHasAssetに当該アセットがあること
移転する量（金額など）が正数で、精度が資産定義項目と一致すること
ソースアカウントに転送する資産が十分にあり、ゼロではないこと
送信元アカウントがお金を転送することができ、宛先アカウントもお金を受け取ることができる（それぞれにこれらの権限が付与されていること）

Possible Stateful Validation Errors¶

Code	Error Name	説明	How to solve
1	Could not transfer asset	Internal error happened	Try again or contact developers
2	No such permissions	Command's creator does not have permission to transfer asset from his account	Grant the necessary permission
3	No such source account	Cannot find account with such id to transfer money from	Make sure source account id is correct
4	No such destination account	Cannot find account with such id to transfer money to	Make sure destination account id is correct
5	No such asset found	Cannot find such asset	Make sure asset name and precision are correct
6	Not enough balance	Source account's balance is too low to perform the operation	Add asset to account or choose lower value to subtract
7	Too much asset to transfer	Resulting value of asset amount overflows destination account's amount	Make sure final value is less than 2^256

[1]	(1, 2, 3) https://www.ietf.org/rfc/rfc1035.txt

[2]	(1, 2) https://www.ietf.org/rfc/rfc1123.txt

クエリの一覧¶

クエリとは、World State Viewの特定の部分（ブロックチェーンの直近の状態）についての情報を問い合わせすることです。クエリ自体はブロックチェーンの内容を変更することはできません。クエリを受信したノードがクエリを処理し、その直後にクライアントに対して応答が返されます。

検証¶

全クエリに対する検証には次のものが含まれます。

タイムスタンプ - 過去（ピア・タイムの24時間前）または将来（ピア・タイムの5分先の範囲）であってはなりません。
クエリー生成者の署名 - クエリー作成者の身元確認のために使用されます
クエリカウンタ - クエリ作成者から送られる後続のクエリごとに増分されていき、その度にこの値がチェックされます
役割 - クエリ作成者の役割に応じて、クエリで問い合わせできる情報の範囲は、同じアカウント、ドメイン内のアカウント、ブロックチェーン全体に関係する、あるいは全く許可されないように設定することが可能です

Get Account¶

目的¶

GetAccountクエリの目的は、アカウントの状態を取得することです。

リクエスト・スキーマ¶

message GetAccount {
    string account_id = 1;
}

Request（内部構造）¶

フィールド	説明	制約	例
アカウントID	状態を問い合わせるアカウントのID	<account_name>@<domain_id>	alex@morgan

Response（図表）¶

message AccountResponse {
    Account account = 1;
    repeated string account_roles = 2;
}

message Account {
    string account_id = 1;
    string domain_id = 2;
    uint32 quorum = 3;
    string json_data = 4;
}

Response（内部構造）¶

フィールド	説明	制約	例
アカウントID	アカウントID	<account_name>@<domain_id>	alex@morgan
ドメインID	アカウントが作成されたドメイン	RFC1035 [1], RFC1123 [2]	morgan
Quorum	トランザクションを有効なものにするために必要な署名者数	0 < quorum ≤ 128	5
JSON data	Key-Valueアカウント情報	JSON	{ genesis: {name: alex} }

Possible Stateful Validation Errors¶

Code	Error Name	説明	How to solve
1	Could not get account	Internal error happened	Try again or contact developers
2	No such permissions	Query's creator does not have any of the permissions to get account	Grant the necessary permission: individual, global or domain one
3	Invalid signatures	Signatures of this query did not pass validation	Add more signatures and make sure query's signatures are a subset of account's signatories

Get Block¶

目的¶

Purpose of get block query is to get a specific block, using its height as an identifier

リクエスト・スキーマ¶

message GetBlock {
  uint64 height = 1;
}

Request（内部構造）¶

フィールド	説明	制約	例
Height	height of the block to be retrieved	0 < height < 2^64	42

Response（図表）¶

message BlockResponse {
  Block block = 1;
}

Response（内部構造）¶

フィールド	説明	制約	例
Block	the retrieved block	block structure	block

Possible Stateful Validation Errors¶

Code	Error Name	説明	How to solve
1	Could not get block	Internal error happened	Try again or contact developers
2	No such permissions	Query's creator does not have a permission to get block	Grant the necessary permission
3	Invalid height	Supplied height is not uint_64 or greater than the ledger's height	Check the height and try again

Get Signatories¶

目的¶

GetSignatoriesクエリの目的は、署名者を取得することです。署名者は、アカウントのIDとして機能します。

リクエスト・スキーマ¶

message GetSignatories {
    string account_id = 1;
}

Request（内部構造）¶

フィールド	説明	制約	例
アカウントID	署名者を要求するアカウントのID	<account_name>@<domain_id>	alex@morgan

Response（図表）¶

message SignatoriesResponse {
    repeated bytes keys = 1;
}

Response（内部構造）¶

フィールド	説明	制約	例
Keys	公開鍵の配列	ed25519	292a8714694095edce6be799398ed5d6244cd7be37eb813106b217d850d261f2

Possible Stateful Validation Errors¶

Code	Error Name	説明	How to solve
1	Could not get signatories	Internal error happened	Try again or contact developers
2	No such permissions	Query's creator does not have any of the permissions to get signatories	Grant the necessary permission: individual, global or domain one
3	Invalid signatures	Signatures of this query did not pass validation	Add more signatures and make sure query's signatures are a subset of account's signatories

Get Transactions¶

目的¶

GetTransactions is used for retrieving information about transactions, based on their hashes. .. note:: This query is valid if and only if all the requested hashes are correct: corresponding transactions exist, and the user has a permission to retrieve them

リクエスト・スキーマ¶

message GetTransactions {
    repeated bytes tx_hashes = 1;
}

Request（内部構造）¶

フィールド	説明	制約	例
トランザクションハッシュ	ハッシュの配列	32バイト長のハッシュの配列	{hash1, hash2…}

Response（図表）¶

message TransactionsResponse {
    repeated Transaction transactions = 1;
}

Response（内部構造）¶

フィールド	説明	制約	例
Transactions	トランザクションの配列	コミットされたトランザクション	{tx1, tx2…}

Possible Stateful Validation Errors¶

Code	Error Name	説明	How to solve
1	Could not get transactions	Internal error happened	Try again or contact developers
2	No such permissions	Query's creator does not have any of the permissions to get transactions	Grant the necessary permission: individual, global or domain one
3	Invalid signatures	Signatures of this query did not pass validation	Add more signatures and make sure query's signatures are a subset of account's signatories
4	Invalid hash	At least one of the supplied hashes either does not exist in user's transaction list or creator of the query does not have permissions to see it	Check the supplied hashes and try again

Get Pending Transactions¶

目的¶

GetPendingTransactions is used for retrieving a list of pending (not fully signed) multisignature transactions or batches of transactions issued by account of query creator.

リクエスト・スキーマ¶

message GetPendingTransactions {
}

Response（図表）¶

message TransactionsResponse {
    repeated Transaction transactions = 1;
}

Response（内部構造）¶

The response contains a list of pending transactions.

フィールド	説明	制約	例
Transactions	an array of pending transactions	Pending transactions	{tx1, tx2…}

Possible Stateful Validation Errors¶

Code	Error Name	説明	How to solve
1	Could not get pending transactions	Internal error happened	Try again or contact developers
2	No such permissions	Query's creator does not have any of the permissions to get pending transactions	Grant the necessary permission: individual, global or domain one
3	Invalid signatures	Signatures of this query did not pass validation	Add more signatures and make sure query's signatures are a subset of account's signatories

Get Account Transactions¶

目的¶

In a case when a list of transactions per account is needed, GetAccountTransactions query can be formed.

注釈

This query uses pagination for quicker and more convenient query responses.

リクエスト・スキーマ¶

message TxPaginationMeta {
    uint32 page_size = 1;
    oneof opt_first_tx_hash {
        string first_tx_hash = 2;
    }
}

message GetAccountTransactions {
    string account_id = 1;
    TxPaginationMeta pagination_meta = 2;
}

Request（内部構造）¶

フィールド	説明	制約	例
アカウントID	トランザクション情報をリクエストするアカウントID	<account_name>@<domain_id>	makoto@soramitsu
Page size	size of the page to be returned by the query, if the response contains fewer transactions than a page size, then next tx hash will be empty in response	page_size > 0	5
First tx hash	hash of the first transaction in the page. If that field is not set — then the first transactions are returned	hash in hex format	bddd58404d1315e0eb27902c5d7c8eb0602c16238f005773df406bc191308929

Response（図表）¶

message TransactionsPageResponse {
    repeated Transaction transactions = 1;
    uint32 all_transactions_size = 2;
    oneof next_page_tag {
        string next_tx_hash = 3;
    }
}

Possible Stateful Validation Errors¶

Code	Error Name	説明	How to solve
1	Could not get account transactions	Internal error happened	Try again or contact developers
2	No such permissions	Query's creator does not have any of the permissions to get account transactions	Grant the necessary permission: individual, global or domain one
3	Invalid signatures	Signatures of this query did not pass validation	Add more signatures and make sure query's signatures are a subset of account's signatories
4	Invalid pagination hash	Supplied hash does not appear in any of the user's transactions	Make sure hash is correct and try again
5	Invalid account id	User with such account id does not exist	Make sure account id is correct

Response（内部構造）¶

フィールド	説明	制約	例
Transactions	指定されたアカウントに関連するトランザクションの配列	コミットされたトランザクション	{tx1, tx2…}
All transactions size	total number of transactions created by the given account		100
Next transaction hash	hash pointing to the next transaction after the last transaction in the page. Empty if a page contains the last transaction for the given account	bddd58404d1315e0eb27902c5d7c8eb0602c16238f005773df406bc191308929

Get Account Asset Transactions¶

目的¶

GetAccountAssetTransactions query returns all transactions associated with given account and asset.

注釈

This query uses pagination for query responses.

リクエスト・スキーマ¶

message TxPaginationMeta {
    uint32 page_size = 1;
    oneof opt_first_tx_hash {
        string first_tx_hash = 2;
    }
}

message GetAccountAssetTransactions {
    string account_id = 1;
    string asset_id = 2;
    TxPaginationMeta pagination_meta = 3;
}

Request（内部構造）¶

フィールド	説明	制約	例
アカウントID	トランザクション情報をリクエストするアカウントID	<account_name>@<domain_id>	makoto@soramitsu
資産ID	このアセットに関連するトランザクションをフィルタするために指定するアセットID	<asset_name>#<domain_id>	jpy#japan
Page size	size of the page to be returned by the query, if the response contains fewer transactions than a page size, then next tx hash will be empty in response	page_size > 0	5
First tx hash	hash of the first transaction in the page. If that field is not set — then the first transactions are returned	hash in hex format	bddd58404d1315e0eb27902c5d7c8eb0602c16238f005773df406bc191308929

Response（図表）¶

message TransactionsPageResponse {
    repeated Transaction transactions = 1;
    uint32 all_transactions_size = 2;
    oneof next_page_tag {
        string next_tx_hash = 3;
    }
}

Response（内部構造）¶

フィールド	説明	制約	例
Transactions	特定のアカウントと資産に関連するトランザクションの配列	コミットされたトランザクション	{tx1, tx2…}
All transactions size	total number of transactions for given account and asset		100
Next transaction hash	hash pointing to the next transaction after the last transaction in the page. Empty if a page contains the last transaction for given account and asset	bddd58404d1315e0eb27902c5d7c8eb0602c16238f005773df406bc191308929

Possible Stateful Validation Errors¶

Code	Error Name	説明	How to solve
1	Could not get account asset transactions	Internal error happened	Try again or contact developers
2	No such permissions	Query's creator does not have any of the permissions to get account asset transactions	Grant the necessary permission: individual, global or domain one
3	Invalid signatures	Signatures of this query did not pass validation	Add more signatures and make sure query's signatures are a subset of account's signatories
4	Invalid pagination hash	Supplied hash does not appear in any of the user's transactions	Make sure hash is correct and try again
5	Invalid account id	User with such account id does not exist	Make sure account id is correct
6	Invalid asset id	Asset with such asset id does not exist	Make sure asset id is correct

Get Account Assets¶

目的¶

To get the state of all assets in an account (a balance), GetAccountAssets query can be used.

リクエスト・スキーマ¶

message GetAccountAssets {
    string account_id = 1;
}

Request（内部構造）¶

フィールド	説明	制約	例
アカウントID	残高情報を請求するアカウントID	<account_name>@<domain_id>	makoto@soramitsu

Response（図表）¶

message AccountAssetResponse {
    repeated AccountAsset acct_assets = 1;
}

message AccountAsset {
    string asset_id = 1;
    string account_id = 2;
    string balance = 3;
}

Response（内部構造）¶

フィールド	説明	制約	例
資産ID	残高確認に使用される資産の識別子	<asset_name>#<domain_id>	jpy#japan
アカウントID	残高を持つアカウント	<account_name>@<domain_id>	makoto@soramitsu
Balance	資産残高	No less than 0	200.20

Possible Stateful Validation Errors¶

Code	Error Name	説明	How to solve
1	Could not get account assets	Internal error happened	Try again or contact developers
2	No such permissions	Query's creator does not have any of the permissions to get account assets	Grant the necessary permission: individual, global or domain one
3	Invalid signatures	Signatures of this query did not pass validation	Add more signatures and make sure query's signatures are a subset of account's signatories

Get Account Detail¶

目的¶

To get details of the account, GetAccountDetail query can be used. Account details are key-value pairs, splitted into writers categories. Writers are accounts, that added the corresponding account detail. Example of such structure is:

{
    "account@a_domain": {
        "age": 18,
        "hobbies": "crypto"
    },
    "account@b_domain": {
        "age": 20,
        "sports": "basketball"
    }
}

Here, one can see four account details - "age", "hobbies" and "sports" - added by two writers - "account@a_domain" and "account@b_domain". All of these details, obviously, are about the same account.

リクエスト・スキーマ¶

message GetAccountDetail {
  oneof opt_account_id {
    string account_id = 1;
  }
  oneof opt_key {
    string key = 2;
  }
  oneof opt_writer {
    string writer = 3;
  }
}

注釈

Pay attention, that all fields are optional. Reasons will be described later.

Request（内部構造）¶

フィールド	説明	制約	例
アカウントID	account id to get details from	<account_name>@<domain_id>	account@domain
Key	key, under which to get details	string	age
Writer	account id of writer	<account_name>@<domain_id>	account@domain

Response（図表）¶

message AccountDetailResponse {
  string detail = 1;
}

Response（内部構造）¶

フィールド	説明	制約	例
Detail	key-value pairs with account details	JSON	see below

Possible Stateful Validation Errors¶

Code	Error Name	説明	How to solve
1	Could not get account detail	Internal error happened	Try again or contact developers
2	No such permissions	Query's creator does not have any of the permissions to get account detail	Grant the necessary permission: individual, global or domain one
3	Invalid signatures	Signatures of this query did not pass validation	Add more signatures and make sure query's signatures are a subset of account's signatories

Usage Examples¶

Again, let's consider the example of details from the beginning and see how different variants of GetAccountDetail queries will change the resulting response.

{
    "account@a_domain": {
        "age": 18,
        "hobbies": "crypto"
    },
    "account@b_domain": {
        "age": 20,
        "sports": "basketball"
    }
}

account_id is not set

If account_id is not set - other fields can be empty or not - it will automatically be substituted with query creator's account, which will lead to one of the next cases.

only account_id is set

In this case, all details about that account are going to be returned, leading to the following response:

{
    "account@a_domain": {
        "age": 18,
        "hobbies": "crypto"
    },
    "account@b_domain": {
        "age": 20,
        "sports": "basketball"
    }
}

account_id and key are set

Here, details added by all writers under the key are going to be returned. For example, if we asked for the key "age", that's the response we would get:

{
    "account@a_domain": {
        "age": 18
    },
    "account@b_domain": {
        "age": 20
    }
}

account_id and writer are set

Now, the response will contain all details about this account, added by one specific writer. For example, if we asked for writer "account@b_domain", we would get:

{
    "account@b_domain": {
        "age": 20,
        "sports": "basketball"
    }
}

account_id, key and writer are set

Finally, if all three field are set, result will contain details, added the specific writer and under the specific key, for example, if we asked for key "age" and writer "account@a_domain", we would get:

{
    "account@a_domain": {
        "age": 18
    }
}

Get Asset Info¶

目的¶

In order to get information on the given asset (as for now - its precision), user can send GetAssetInfo query.

リクエスト・スキーマ¶

message GetAssetInfo {
    string asset_id = 1;
}

Request（内部構造）¶

フィールド	説明	制約	例
資産ID	関連情報を知るための資産ID	<asset_name>#<domain_id>	jpy#japan

Response（図表）¶

message Asset {
    string asset_id = 1;
    string domain_id = 2;
    uint32 precision = 3;
}

注釈

Please note that due to a known issue you would not get any exception if you pass invalid precision value. Valid range is: 0 <= precision <= 255

Possible Stateful Validation Errors¶

Code	Error Name	説明	How to solve
1	Could not get asset info	Internal error happened	Try again or contact developers
2	No such permissions	Query's creator does not have any of the permissions to get asset info	Grant the necessary permission: individual, global or domain one
3	Invalid signatures	Signatures of this query did not pass validation	Add more signatures and make sure query's signatures are a subset of account's signatories

Response（内部構造）¶

フィールド	説明	制約	例
資産ID	残高確認に使用される資産の識別子	<asset_name>#<domain_id>	jpy#japan
ドメインID	このアセットに関連するドメイン	RFC1035 [1], RFC1123 [2]	japan
Precision (精度)	コンマの後の桁数	0 <= precision <= 255	2

Get Roles¶

目的¶

システム内の存在するさまざまな役割に関する情報を得るためには、ユーザは、Irohaネットワークに `GetRoles`クエリを送ることができます。

リクエスト・スキーマ¶

message GetRoles {
}

Response（図表）¶

message RolesResponse {
    repeated string roles = 1;
}

Response（内部構造）¶

フィールド	説明	制約	例
Roles	ネットワーク内に作成された役割の配列	システム内で規定されている役割（ロール）	{MoneyCreator, User, Admin, …}

Possible Stateful Validation Errors¶

Code	Error Name	説明	How to solve
1	Could not get roles	Internal error happened	Try again or contact developers
2	No such permissions	Query's creator does not have any of the permissions to get roles	Grant the necessary permission: individual, global or domain one
3	Invalid signatures	Signatures of this query did not pass validation	Add more signatures and make sure query's signatures are a subset of account's signatories

Get Role Permissions¶

目的¶

システム内の役割ごとに利用可能になっている権限を得るために、ユーザーはIrohaネットワークに `GetRolePermissions`クエリを送ることができます。

リクエスト・スキーマ¶

message GetRolePermissions {
    string role_id = 1;
}

Request（内部構造）¶

フィールド	説明	制約	例
Role ID	権限を付与する役割	システム内で既に規定されている役割	貨幣の発行者

Response（図表）¶

message RolePermissionsResponse {
    repeated string permissions = 1;
}

Response（内部構造）¶

フィールド	説明	制約	例
Permissions	役割に関連した権限 (配列)	ロールに関連するアクセス権 (文字列)	{can_add_asset_qty, …}

Possible Stateful Validation Errors¶

Code	Error Name	説明	How to solve
1	Could not get role permissions	Internal error happened	Try again or contact developers
2	No such permissions	Query's creator does not have any of the permissions to get role permissions	Grant the necessary permission: individual, global or domain one
3	Invalid signatures	Signatures of this query did not pass validation	Add more signatures and make sure query's signatures are a subset of account's signatories

[1]	(1, 2) https://www.ietf.org/rfc/rfc1035.txt

[2]	(1, 2) https://www.ietf.org/rfc/rfc1123.txt

FetchCommits¶

目的¶

To get new blocks as soon as they are committed, a user can invoke FetchCommits RPC call to Iroha network.

リクエスト・スキーマ¶

No request arguments are needed

Response（図表）¶

message BlockQueryResponse {
  oneof response {
    BlockResponse block_response = 1;
    BlockErrorResponse block_error_response = 2;
  }
}

Please note that it returns a stream of BlockQueryResponse.

Response（内部構造）¶

フィールド	説明	制約	例
Block	Iroha block	only committed blocks	{ 'block_v1': ....}

Possible Stateful Validation Errors¶

Code	Error Name	説明	How to solve
1	Could not get block streaming	Internal error happened	Try again or contact developers
2	No such permissions	Query's creator does not have any of the permissions to get blocks	Grant the necessary permission: individual, global or domain one
3	Invalid signatures	Signatures of this query did not pass validation	Add more signatures and make sure query's signatures are a subset of account's signatories

例¶

You can check an example how to use this query here: https://github.com/x3medima17/twitter

メンテナンス¶

本項では、ハードウェア要件、デプロイメントプロセスの詳細、セキュリティ関連項目、設定ファイルに関してすべて説明します。これらの説明は、開発・運用担当者、あるいはシステムの細部まで掘り下げてみてみたい人に役立ちます。

Permissions¶

Hyperledger Iroha uses a role-based access control system to limit actions of its users. This system greatly helps to implement use cases involving user groups having different access levels — ranging from the weak users, who can't even receive asset transfer to the super-users. The beauty of our permission system is that you don't have to have a super-user in your Iroha setup or use all the possible permissions: you can create segregated and lightweight roles.

Maintenance of the system involves setting up roles and permissions, that are included in the roles. This might be done at the initial step of system deployment — in genesis block, or later when Iroha network is up and running, roles can be changed (if there is a role that can do that :)

This section will help you to understand permissions and give you an idea of how to create roles including certain permissions. Each permission is provided with an example written in Python that demonstrates the way of transaction or query creation, which require specific permission. Every example uses commons.py module, which listing is available at Supplementary Sources section.

List of Permissions¶

Permission Name	Category	Type
can_create_account	Account	Command
can_set_detail	Account	Command
can_set_my_account_detail `grantable`	Account	Command
can_create_asset	Asset	Command
can_receive	Asset	Command
can_transfer	Asset	Command
can_transfer_my_assets `grantable`	Asset	Command
can_add_asset_qty	Asset Quantity	Command
can_subtract_asset_qty	Asset Quantity	Command
can_add_domain_asset_qty	Asset Quantity	Command
can_subtract_domain_asset_qty	Asset Quantity	Command
can_create_domain	Domain	Command
can_grant_can_add_my_signatory	Grant	Command
can_grant_can_remove_my_signatory	Grant	Command
can_grant_can_set_my_account_detail	Grant	Command
can_grant_can_set_my_quorum	Grant	Command
can_grant_can_transfer_my_assets	Grant	Command
can_add_peer	Peer	Command
can_append_role	Role	Command
can_create_role	Role	Command
can_detach_role	Role	Command
can_add_my_signatory `grantable`	Signatory	Command
can_add_signatory	Signatory	Command
can_remove_my_signatory `grantable`	Signatory	Command
can_remove_signatory	Signatory	Command
can_set_my_quorum `grantable`	Signatory	Command
can_set_quorum	Signatory	Command
can_get_all_acc_detail	Account	Query
can_get_all_accounts	Account	Query
can_get_domain_acc_detail	Account	Query
can_get_domain_accounts	Account	Query
can_get_my_acc_detail	Account	Query
can_get_my_account	Account	Query
can_get_all_acc_ast	Account Asset	Query
can_get_domain_acc_ast	Account Asset	Query
can_get_my_acc_ast	Account Asset	Query
can_get_all_acc_ast_txs	Account Asset Transaction	Query
can_get_domain_acc_ast_txs	Account Asset Transaction	Query
can_get_my_acc_ast_txs	Account Asset Transaction	Query
can_get_all_acc_txs	Account Transaction	Query
can_get_domain_acc_txs	Account Transaction	Query
can_get_my_acc_txs	Account Transaction	Query
can_read_assets	Asset	Query
can_get_blocks	Block Stream	Query
can_get_roles	Role	Query
can_get_all_signatories	Signatory	Query
can_get_domain_signatories	Signatory	Query
can_get_my_signatories	Signatory	Query
can_get_all_txs	Transaction	Query
can_get_my_txs	Transaction	Query

Supplementary Sources¶

Ansible¶

注意

Contents are missing for now. Please check deploy/ansible folder and README.md file in it.

Hyperledger Irohaドキュメンテーション¶

いろはの概要¶

いろはの主な特長は何ですか？¶

Irohaはどこで使えますか？¶

BitcoinやEthereumとはどのような点が違うのですか？¶

その他のHyperledgerフレームワークや他のパーミッション・ブロックチェーンとはどのように違いますか？¶

どのようなアプリケーションを「いろは」と関連して構築できますか？¶

はじめる¶

前提となる環境¶

いろはノードを起動する¶

Dockerネットワークを作成する¶

PostgreSQLのコンテナを起動する¶

Blockstoreを作成する¶

Preparing the configuration files¶

Irohaコンテナを起動する¶

Try other guides¶

ユースケース例¶

教育やヘルスケア分野における証書¶

例¶

国際間の資産移転（授受）¶

例¶

金融業務におけるアプリケーション¶

例¶

アイデンティティマネジメント¶

例¶

サプライチェーン¶

例¶

Fund Management¶

例¶

関連する研究¶

重要事項¶

Sections¶

Account (アカウント、口座)¶

Ametsuchi¶

Asset（資産、アセット）¶

Block (ブロック)¶

Block Creator¶

Client¶

コマンド¶

コンセンサス (合意)¶

ドメイン¶

Ordering Gate (検証作業の要求経路)¶

Ordering Service¶

ピア（ネットワークノード）¶

ピア間通信サービス (PCS)¶

権限 (Permission)¶

付与可能な権限¶

プロポーザル（新規ブロックの提案）¶

検証済みのプロポーザル¶

クエリー（問い合わせ）¶

Quorum¶

役割 (Role)¶

Signatory¶

シミュレーター (Simulator)¶

シンクロナイザー¶

Torii（鳥居）¶

トランザクション¶

Transaction Structure¶

Reduced Transaction Hash¶

Transaction Statuses¶

Transaction Status Set¶

Pending Transactions¶

Batch of Transactions¶

Atomic Batch¶

Ordered Batch¶

Multisignature Transactions¶

検証作業（Validator）¶

ステートレス検証 (Sateless Validation)¶

ステートフル検証 (Sateful Validation)¶

Verified Proposal Creator¶

World State View¶

Entity-relationship model¶

ER diagram¶

Peer¶

Asset¶

Signatory¶

Domain¶

Role¶

RoleHasPermissions¶

Account¶