6.2. Suchanfragen¶
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.
Bemerkung
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.
Bemerkung
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;
}
}
Bemerkung
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;
}
Bemerkung
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.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