6.2. Queries

A query is a request related to certain part of World State View — the latest state of blockchain. Query cannot modify the contents of the chain and a response is returned to any client immediately after receiving peer has processed a query.

6.2.1. Validation

The validation for all queries includes:

  • timestamp — shouldn’t be from the past (24 hours prior to the peer time) or from the future (range of 5 minutes added to the peer time)
  • signature of query creator — used for checking the identity of query creator
  • query counter — checked to be incremented with every subsequent query from query creator
  • roles — depending on the query creator’s role: the range of state available to query can relate to to the same account, account in the domain, to the whole chain, or not allowed at all

6.2.2. Get Account

6.2.2.1. Purpose

Purpose of get account query is to get the state of an account.

6.2.2.2. Request Schema

message GetAccount {
    string account_id = 1;
}

6.2.2.3. Request Structure

Field Description Constraint Example
Account ID account id to request its state <account_name>@<domain_id> alex@morgan

6.2.2.4. Response Schema

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 Structure

Field Description Constraint Example
Account ID account id <account_name>@<domain_id> alex@morgan
Domain ID domain where the account was created RFC1035 [1], RFC1123 [2] morgan
Quorum number of signatories needed to sign the transaction to make it valid 0 < quorum ≤ 128 5
JSON data key-value account information JSON { genesis: {name: alex} }

6.2.2.6. Possible Stateful Validation Errors

Code Error Name Description 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

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

6.2.3.2. Request Schema

message GetBlock {
  uint64 height = 1;
}

6.2.3.3. Request Structure

Field Description Constraint Example
Height height of the block to be retrieved 0 < height < 2^64 42

6.2.3.4. Response Schema

message BlockResponse {
  Block block = 1;
}

6.2.3.5. Response Structure

Field Description Constraint Example
Block the retrieved block block structure block

6.2.3.6. Possible Stateful Validation Errors

Code Error Name Description 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. Purpose

Purpose of get signatories query is to get signatories, which act as an identity of the account.

6.2.4.2. Request Schema

message GetSignatories {
    string account_id = 1;
}

6.2.4.3. Request Structure

Field Description Constraint Example
Account ID account id to request signatories <account_name>@<domain_id> alex@morgan

6.2.4.4. Response Schema

message SignatoriesResponse {
    repeated bytes keys = 1;
}

6.2.4.5. Response Structure

Field Description Constraint Example
Keys an array of public keys ed25519 292a8714694095edce6be799398ed5d6244cd7be37eb813106b217d850d261f2

6.2.4.6. Possible Stateful Validation Errors

Code Error Name Description 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. Purpose

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. Request Schema

message GetTransactions {
    repeated bytes tx_hashes = 1;
}

6.2.5.3. Request Structure

Field Description Constraint Example
Transactions hashes an array of hashes array with 32 byte hashes {hash1, hash2…}

6.2.5.4. Response Schema

message TransactionsResponse {
    repeated Transaction transactions = 1;
}

6.2.5.5. Response Structure

Field Description Constraint Example
Transactions an array of transactions Committed transactions {tx1, tx2…}

6.2.5.6. Possible Stateful Validation Errors

Code Error Name Description 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. Purpose

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. Request Schema

message GetPendingTransactions {
}

6.2.6.3. Response Schema

message TransactionsResponse {
    repeated Transaction transactions = 1;
}

6.2.6.4. Response Structure

The response contains a list of pending transactions.

Field Description Constraint Example
Transactions an array of pending transactions Pending transactions {tx1, tx2…}

6.2.6.5. Possible Stateful Validation Errors

Code Error Name Description 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. Purpose

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

Note

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

6.2.7.2. Request Schema

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 Structure

Field Description Constraint Example
Account ID account id to request transactions from <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 Schema

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 Description 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 Structure

Field Description Constraint Example
Transactions an array of transactions for given account Committed 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. Purpose

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

Note

This query uses pagination for query responses.

6.2.8.2. Request Schema

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 Structure

Field Description Constraint Example
Account ID account id to request transactions from <account_name>@<domain_id> makoto@soramitsu
Asset ID asset id in order to filter transactions containing this asset <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 Schema

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 Structure

Field Description Constraint Example
Transactions an array of transactions for given account and asset Committed 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 Description 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. Purpose

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

6.2.9.2. Request Schema

message GetAccountAssets {
    string account_id = 1;
}

6.2.9.3. Request Structure

Field Description Constraint Example
Account ID account id to request balance from <account_name>@<domain_id> makoto@soramitsu

6.2.9.4. Response Schema

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 Structure

Field Description Constraint Example
Asset ID identifier of asset used for checking the balance <asset_name>#<domain_id> jpy#japan
Account ID account which has this balance <account_name>@<domain_id> makoto@soramitsu
Balance balance of the asset No less than 0 200.20

6.2.9.6. Possible Stateful Validation Errors

Code Error Name Description 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. Purpose

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. Request Schema

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

Note

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

6.2.10.3. Request Structure

Field Description Constraint Example
Account 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 Schema

message AccountDetailResponse {
  string detail = 1;
}

6.2.10.5. Response Structure

Field Description Constraint Example
Detail key-value pairs with account details JSON see below

6.2.10.6. Possible Stateful Validation Errors

Code Error Name Description 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. Purpose

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

6.2.11.2. Request Schema

message GetAssetInfo {
    string asset_id = 1;
}

6.2.11.3. Request Structure

Field Description Constraint Example
Asset ID asset id to know related information <asset_name>#<domain_id> jpy#japan

6.2.11.4. Response Schema

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

Note

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 Description 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 Structure

Field Description Constraint Example
Asset ID identifier of asset used for checking the balance <asset_name>#<domain_id> jpy#japan
Domain ID domain related to this asset RFC1035 [1], RFC1123 [2] japan
Precision number of digits after comma 0 <= precision <= 255 2

6.2.12. Get Roles

6.2.12.1. Purpose

To get existing roles in the system, a user can send GetRoles query to Iroha network.

6.2.12.2. Request Schema

message GetRoles {
}

6.2.12.3. Response Schema

message RolesResponse {
    repeated string roles = 1;
}

6.2.12.4. Response Structure

Field Description Constraint Example
Roles array of created roles in the network set of roles in the system {MoneyCreator, User, Admin, …}

6.2.12.5. Possible Stateful Validation Errors

Code Error Name Description 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. Purpose

To get available permissions per role in the system, a user can send GetRolePermissions query to Iroha network.

6.2.13.2. Request Schema

message GetRolePermissions {
    string role_id = 1;
}

6.2.13.3. Request Structure

Field Description Constraint Example
Role ID role to get permissions for existing role in the system MoneyCreator

6.2.13.4. Response Schema

message RolePermissionsResponse {
    repeated string permissions = 1;
}

6.2.13.5. Response Structure

Field Description Constraint Example
Permissions array of permissions related to the role string of permissions related to the role {can_add_asset_qty, …}

6.2.13.6. Possible Stateful Validation Errors

Code Error Name Description 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. Purpose

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

6.2.14.2. Request Schema

No request arguments are needed

6.2.14.3. Response Schema

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 Structure

Field Description Constraint Example
Block Iroha block only committed blocks { ‘block_v1’: ….}

6.2.14.5. Possible Stateful Validation Errors

Code Error Name Description 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. Example

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