6.2. クエリの一覧¶

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

6.2.1. 検証¶

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

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

6.2.2. Get Account¶

6.2.2.1. 目的¶

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

6.2.2.2. リクエスト・スキーマ¶

message GetAccount {
    string account_id = 1;
}

6.2.2.3. Request（内部構造）¶

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

6.2.2.4. 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;
}

6.2.2.5. 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} }

6.2.2.6. 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

6.2.3. Get Block¶

6.2.3.1. 目的¶

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

6.2.3.2. リクエスト・スキーマ¶

message GetBlock {
  uint64 height = 1;
}

6.2.3.3. Request（内部構造）¶

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

6.2.3.4. Response（図表）¶

message BlockResponse {
  Block block = 1;
}

6.2.3.5. Response（内部構造）¶

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

6.2.3.6. 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

6.2.4. Get Signatories¶

6.2.4.1. 目的¶

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

6.2.4.2. リクエスト・スキーマ¶

message GetSignatories {
    string account_id = 1;
}

6.2.4.3. Request（内部構造）¶

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

6.2.4.4. Response（図表）¶

message SignatoriesResponse {
    repeated bytes keys = 1;
}

6.2.4.5. Response（内部構造）¶

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

6.2.4.6. 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

6.2.5. Get Transactions¶

6.2.5.1. 目的¶

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

6.2.5.2. リクエスト・スキーマ¶

message GetTransactions {
    repeated bytes tx_hashes = 1;
}

6.2.5.3. Request（内部構造）¶

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

6.2.5.4. Response（図表）¶

message TransactionsResponse {
    repeated Transaction transactions = 1;
}

6.2.5.5. Response（内部構造）¶

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

6.2.5.6. 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

6.2.6. Get Pending Transactions¶

6.2.6.1. 目的¶

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

6.2.6.2. リクエスト・スキーマ¶

message GetPendingTransactions {
}

6.2.6.3. Response（図表）¶

message TransactionsResponse {
    repeated Transaction transactions = 1;
}

6.2.6.4. Response（内部構造）¶

The response contains a list of pending transactions.

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

6.2.6.5. 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

6.2.7. Get Account Transactions¶

6.2.7.1. 目的¶

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.

6.2.7.2. リクエスト・スキーマ¶

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;
}

6.2.7.3. 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

6.2.7.4. Response（図表）¶

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

6.2.7.5. 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

6.2.7.6. 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

6.2.8. Get Account Asset Transactions¶

6.2.8.1. 目的¶

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

注釈

This query uses pagination for query responses.

6.2.8.2. リクエスト・スキーマ¶

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;
}

6.2.8.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

6.2.8.4. Response（図表）¶

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

6.2.8.5. 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

6.2.8.6. 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

6.2.9. Get Account Assets¶

6.2.9.1. 目的¶

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

6.2.9.2. リクエスト・スキーマ¶

message GetAccountAssets {
    string account_id = 1;
}

6.2.9.3. Request（内部構造）¶

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

6.2.9.4. Response（図表）¶

message AccountAssetResponse {
    repeated AccountAsset acct_assets = 1;
}

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

6.2.9.5. Response（内部構造）¶

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

6.2.9.6. 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

6.2.10. Get Account Detail¶

6.2.10.1. 目的¶

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.

6.2.10.2. リクエスト・スキーマ¶

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.

6.2.10.3. 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

6.2.10.4. Response（図表）¶

message AccountDetailResponse {
  string detail = 1;
}

6.2.10.5. Response（内部構造）¶

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

6.2.10.6. 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

6.2.10.7. 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
    }
}

6.2.11. Get Asset Info¶

6.2.11.1. 目的¶

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

6.2.11.2. リクエスト・スキーマ¶

message GetAssetInfo {
    string asset_id = 1;
}

6.2.11.3. Request（内部構造）¶

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

6.2.11.4. 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

6.2.11.5. 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

6.2.11.6. Response（内部構造）¶

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

6.2.12. Get Roles¶

6.2.12.1. 目的¶

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

6.2.12.2. リクエスト・スキーマ¶

message GetRoles {
}

6.2.12.3. Response（図表）¶

message RolesResponse {
    repeated string roles = 1;
}

6.2.12.4. Response（内部構造）¶

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

6.2.12.5. 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

6.2.13. Get Role Permissions¶

6.2.13.1. 目的¶

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

6.2.13.2. リクエスト・スキーマ¶

message GetRolePermissions {
    string role_id = 1;
}

6.2.13.3. Request（内部構造）¶

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

6.2.13.4. Response（図表）¶

message RolePermissionsResponse {
    repeated string permissions = 1;
}

6.2.13.5. Response（内部構造）¶

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

6.2.13.6. 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

6.2.14. FetchCommits¶

6.2.14.1. 目的¶

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

6.2.14.2. リクエスト・スキーマ¶

No request arguments are needed

6.2.14.3. Response（図表）¶

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

Please note that it returns a stream of BlockQueryResponse.

6.2.14.4. Response（内部構造）¶

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

6.2.14.5. 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

6.2.14.6. 例¶

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