9.3.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.
9.3.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
9.3.2.2. Result Pagination¶
Some queries support TxPaginationMeta that allows to customise and sort the query result in different ways what could be used in development. Pagination works together with ordering prameters, similar to ORDER BY in SQL language – “the result rows are sorted according to the specified expression (in Iroha – Field). If two rows are equal according to the leftmost expression, they are compared according to the next expression and so on.”
Here is how the “expression” is specified:
enum Field {
kCreatedTime = 0;
kPosition = 1;
}
There are 2 bases for ordering – on creation time and depending on the number of block.
There is an ascending and descending directions for each Field:
enum Direction {
kAscending = 0;
kDescending = 1;
}
Now, the ordering itself:
message Ordering {
message FieldOrdering {
Field field = 1;
Direction direction = 2;
}
repeated FieldOrdering sequence = 1;
}
After ordering is specified, pagination can be executed:
message TxPaginationMeta {
uint32 page_size = 1;
oneof opt_first_tx_hash {
string first_tx_hash = 2;
}
Ordering ordering = 3;
oneof opt_first_tx_time {
google.protobuf.Timestamp first_tx_time = 4;
}
oneof opt_last_tx_time {
google.protobuf.Timestamp last_tx_time = 5;
}
oneof opt_first_tx_height {
uint64 first_tx_height = 6;
}
oneof opt_last_tx_height {
uint64 last_tx_height = 7;
}
}
9.3.2.2.1. What is added to the request structure in case of pagination¶
Field | Description | Constraint | Example |
---|---|---|---|
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 |
ordering | how the results should be ordered (before pagination is applied) | see fields below | see fields below |
ordering.sequence | ordeing spec, like in SQL ORDER BY | sequence of fields and directions | [{kCreatedTime, kAscending}, {kPosition, kDescending}] |
First tx time | time of the first transaction in query result. If that field is not set - then the transactions starting from first are returned | Google Protocol Buffer Timestamp type | 0001-01-01T00:00:00Z <= first tx time <= 9999-12-31T23:59:59.999999999Z |
Last tx time | time of the last transaction in query result. If that field is not set - then the transactions up to the last are returned | Google Protocol Buffer Timestamp type | 0001-01-01T00:00:00Z <= last tx time <= 9999-12-31T23:59:59.999999999Z |
First tx height | block height of the first transaction in query result. If that field is not set - then the transactions starting from height 1 are returned | first tx height > 0 | 4 |
Last tx height | block height of the last transaction in query result. If that field is not set - then the transactions up to the last one are returned | last tx height > 0 | 6 |
9.3.2.3. Engine Receipts¶
9.3.2.3.1. Purpose¶
Retrieve a receipt of a CallEngine command. Similar to the eth.GetTransactionReceipt API call of Ethereum JSON RPC API. Allows to access the event log created during computations inside the EVM.
9.3.2.3.2. Request Schema¶
message GetEngineReceipts {
string tx_hash = 1; // hex string
}
9.3.2.3.3. Request Structure¶
Field | Description | Constraint | Example |
---|---|---|---|
Transaction Hash | hash of the transaction that has the CallEngine command | hash in hex format | 5241f70cf3adbc180199c1d2d02db82334137aede5f5ed35d649bbbc75ab2634 |
9.3.2.3.4. Response Schema¶
message EngineReceiptsResponse {
repeated EngineReceipt engine_receipt = 1;
}
message EngineReceipt {
int32 command_index = 1;
string caller = 2;
oneof opt_to_contract_address {
CallResult call_result = 3;
string contract_address = 4;
}
repeated EngineLog logs = 5;
}
message CallResult {
string callee = 1;
string result_data = 2;
}
message EngineLog {
string address = 1; // hex string
string data = 2; // hex string
repeated string topics = 3; // hex string
}
9.3.2.3.5. Response Structure¶
Field | Description | Constraint | Example |
---|---|---|---|
command_index | Index of the CallEngine command in the transaction | non-negative integer | 0 |
caller | caller account of the smart contract | <account_name>@<domain_id> | admin@test |
call_result.callee | address of called contract | 20-bytes string in hex representation | 0000000000000000000000000000000000000000 |
call_result.result_data | the value returned by the contract | string in hex representation | 00 |
contract_address | EVM address of a newly deployed contract | 20-bytes string in hex representation | 7C370993FD90AF204FD582004E2E54E6A94F2651 |
logs | Array of EVM event logs created during smart contract execution. | see below | see below |
logs.[].address | the contract caller EVM address | 20-bytes string in hex representation | 577266A3CE7DD267A4C14039416B725786605FF4 |
logs.[].data | the logged data | hex string | 0000000000000000000000007203DF5D7B4F198848477D7F9EE080B207E544DD000000000000000000000000000000000000000000000000000000000000006D |
logs.[].topics | log topic as in Ethereum | 32-byte strings | [3990DB2D31862302A685E8086B5755072A6E2B5B780AF1EE81ECE35EE3CD3345, 000000000000000000000000969453762B0C739DD285B31635EFA00E24C25628] |
9.3.2.3.6. Possible Stateful Validation Errors¶
Code | Error Name | Description | How to solve |
---|---|---|---|
2 | No such permissions | Query’s creator does not have any of the permissions to get the call engine receipt | Grant the necessary permission |
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 |
9.3.2.4. Get Account¶
9.3.2.4.1. Purpose¶
Purpose of get account query is to get the state of an account.
9.3.2.4.2. Request Schema¶
message GetAccount {
string account_id = 1;
}
9.3.2.4.3. Request Structure¶
Field | Description | Constraint | Example |
---|---|---|---|
Account ID | account id to request its state | <account_name>@<domain_id> | alex@morgan |
9.3.2.4.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;
}
9.3.2.4.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} } |
9.3.2.4.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 |
9.3.2.5. Get Block¶
9.3.2.5.1. Purpose¶
Purpose of get block query is to get a specific block, using its height as an identifier
9.3.2.5.2. Request Schema¶
message GetBlock {
uint64 height = 1;
}
9.3.2.5.3. Request Structure¶
Field | Description | Constraint | Example |
---|---|---|---|
Height | height of the block to be retrieved | 0 < height < 2^64 | 42 |
9.3.2.5.4. Response Schema¶
message BlockResponse {
Block block = 1;
}
9.3.2.5.5. Response Structure¶
Field | Description | Constraint | Example |
---|---|---|---|
Block | the retrieved block | block structure | block |
9.3.2.5.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 can_get_block permission |
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 |
3 | Invalid height | Supplied height is not uint_64 or greater than the ledger’s height | Check the height and try again |
Note
Error code 3 is ambiguous for this query. It indicates either invalid signatories or invalid height. Use this method with height = 1 (first block is always present) to check for invalid signatories.
9.3.2.6. Get Signatories¶
9.3.2.6.1. Purpose¶
Purpose of get signatories query is to get signatories, which act as an identity of the account.
9.3.2.6.2. Request Schema¶
message GetSignatories {
string account_id = 1;
}
9.3.2.6.3. Request Structure¶
Field | Description | Constraint | Example |
---|---|---|---|
Account ID | account id to request signatories | <account_name>@<domain_id> | alex@morgan |
9.3.2.6.4. Response Schema¶
message SignatoriesResponse {
repeated bytes keys = 1;
}
9.3.2.6.5. Response Structure¶
Field | Description | Constraint | Example |
---|---|---|---|
Keys | an array of public keys | ed25519 | 292a8714694095edce6be799398ed5d6244cd7be37eb813106b217d850d261f2 |
9.3.2.6.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 |
9.3.2.7. Get Transactions¶
9.3.2.7.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
9.3.2.7.2. Request Schema¶
message GetTransactions {
repeated bytes tx_hashes = 1;
}
9.3.2.7.3. Request Structure¶
Field | Description | Constraint | Example |
---|---|---|---|
Transactions hashes | an array of hashes | array with 32 byte hashes | {hash1, hash2…} |
9.3.2.7.4. Response Schema¶
message TransactionsResponse {
repeated Transaction transactions = 1;
}
9.3.2.7.5. Response Structure¶
Field | Description | Constraint | Example |
---|---|---|---|
Transactions | an array of transactions | Committed transactions | {tx1, tx2…} |
9.3.2.7.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 |
9.3.2.8. Get Pending Transactions¶
9.3.2.8.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.
Note
This query uses pagination for quicker and more convenient query responses. Please read about it and specify pagination before sending the query request as well as the request structure.
9.3.2.8.2. Request Schema¶
message GetPendingTransactions {
TxPaginationMeta pagination_meta = 1;
}
All the user’s semi-signed multisignature (pending) transactions can be queried. Maximum amount of transactions contained in a response can be limited by page_size field. All the pending transactions are stored till they have collected enough signatures or get expired. The mutual order of pending transactions or batches of transactions is preserved for a user. That allows a user to query all transactions sequentially - page by page. Each response may contain a reference to the next batch or transaction that can be queried. A page size can be greater than the size of the following batch (in transactions). In that case, several batches or transactions will be returned. During navigating over pages, the following batch can collect the missing signatures before it gets queried. This will result in stateful failed query response due to a missing hash of the batch.
9.3.2.8.3. Example¶
If there are two pending batches with three transactions each and a user queries pending transactions with page size 5, then the transactions of the first batch will be in the response and a reference (first transaction hash and batch size, even if it is a single transaction in fact) to the second batch will be specified too. Transactions of the second batch are not included in the first response because the batch cannot be devided into several parts and only complete batches can be contained in a response.
9.3.2.8.4. Response Schema¶
message PendingTransactionsPageResponse {
message BatchInfo {
string first_tx_hash = 1;
uint32 batch_size = 2;
}
repeated Transaction transactions = 1;
uint32 all_transactions_size = 2;
BatchInfo next_batch_info = 3;
}
9.3.2.8.5. Response Structure¶
The response contains a list of pending transactions, the amount of all stored pending transactions for the user and the information required to query the subsequent page (if exists).
Field | Description | Constraint | Example |
---|---|---|---|
Transactions | an array of pending transactions | Pending transactions | {tx1, tx2…} |
All transactions size | the number of stored transactions | all_transactions_size >= 0 | 0 |
Next batch info | A reference to the next page - the message might be not set in a response | ||
First tx hash | hash of the first transaction in the next batch | hash in hex format | bddd58404d1315e0eb27902c5d7c8eb0602c16238f005773df406bc191308929 |
Batch size | Minimum page size required to fetch the next batch | batch_size > 0 | 3 |
9.3.2.9. Get Pending Transactions (deprecated)¶
Warning
The query without parameters is deprecated now and will be removed in the following major Iroha release (2.0). Please use the new query version instead: Get Pending Transactions.
9.3.2.9.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.
9.3.2.9.2. Request Schema¶
message GetPendingTransactions {
}
9.3.2.9.3. Response Schema¶
message TransactionsResponse {
repeated Transaction transactions = 1;
}
9.3.2.9.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…} |
9.3.2.9.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 |
9.3.2.10. Get Account Transactions¶
9.3.2.10.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. Please read about it and specify pagination before sending the query request as well as the request structure.
9.3.2.10.2. Request Schema¶
message GetAccountTransactions {
string account_id = 1;
TxPaginationMeta pagination_meta = 2;
}
9.3.2.10.3. Request Structure¶
Field | Description | Constraint | Example |
---|---|---|---|
Account ID | account id to request transactions from | <account_name>@<domain_id> | makoto@soramitsu |
9.3.2.10.4. Response Schema¶
message TransactionsPageResponse {
repeated Transaction transactions = 1;
uint32 all_transactions_size = 2;
oneof next_page_tag {
string next_tx_hash = 3;
}
}
9.3.2.10.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 |
9.3.2.10.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 |
9.3.2.11. Get Account Asset Transactions¶
9.3.2.11.1. Purpose¶
GetAccountAssetTransactions query returns all transactions associated with given account and asset.
Note
This query uses pagination for quicker and more convenient query responses. Please read about it and specify pagination before sending the query request as well as the request structure.
9.3.2.11.2. Request Schema¶
message GetAccountAssetTransactions {
string account_id = 1;
string asset_id = 2;
TxPaginationMeta pagination_meta = 3;
}
9.3.2.11.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 |
9.3.2.11.4. Response Schema¶
message TransactionsPageResponse {
repeated Transaction transactions = 1;
uint32 all_transactions_size = 2;
oneof next_page_tag {
string next_tx_hash = 3;
}
}
9.3.2.11.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 |
9.3.2.11.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 |
9.3.2.12. Get Account Assets¶
9.3.2.12.1. Purpose¶
To get the state of all assets in an account (a balance), GetAccountAssets query can be used.
9.3.2.12.2. Request Schema¶
message AssetPaginationMeta {
uint32 page_size = 1;
oneof opt_first_asset_id {
string first_asset_id = 2;
}
}
message GetAccountAssets {
string account_id = 1;
AssetPaginationMeta pagination_meta = 2;
}
9.3.2.12.3. Request Structure¶
Field | Description | Constraint | Example |
---|---|---|---|
Account ID | account id to request balance from | <account_name>@<domain_id> | makoto@soramitsu |
AssetPaginationMeta.page_size | Requested page size. The number of assets in response will not exceed this value. If the response was truncated, the asset id immediately following the returned ones will be provided in next_asset_id. | 0 < page_size < 32 bit unsigned int max (4294967296) | 100 |
AssetPaginationMeta.first_asset_id | Requested page start. If the field is not set, then the first page is returned. | name#domain | my_asset#my_domain |
9.3.2.12.4. Response Schema¶
message AccountAssetResponse {
repeated AccountAsset account_assets = 1;
uint32 total_number = 2;
oneof opt_next_asset_id {
string next_asset_id = 3;
}
}
message AccountAsset {
string asset_id = 1;
string account_id = 2;
string balance = 3;
}
9.3.2.12.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 |
total_number | number of assets matching query without page limits | 0 < total_number < 32 bit unsigned int max (4294967296) | 100500 |
next_asset_id | the id of asset immediately following curent page | name#domain | my_asset#my_domain |
Note
If page size is equal or greater than the number of assets matching other requested criteria, the next asset id will be unset in the response. Otherwise, it contains the value that clients should use for the first asset id if they want to fetch the next page.
9.3.2.12.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 |
4 | Invalid pagination metadata | Wrong page size or nonexistent first asset | Set a valid page size, and make sure that asset id is valid, or leave first asset id unspecified |
9.3.2.13. Get Account Detail¶
9.3.2.13.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.
9.3.2.13.2. Request Schema¶
message AccountDetailRecordId {
string writer = 1;
string key = 2;
}
message AccountDetailPaginationMeta {
uint32 page_size = 1;
AccountDetailRecordId first_record_id = 2;
}
message GetAccountDetail {
oneof opt_account_id {
string account_id = 1;
}
oneof opt_key {
string key = 2;
}
oneof opt_writer {
string writer = 3;
}
AccountDetailPaginationMeta pagination_meta = 4;
}
Note
Pay attention, that all fields except pagination meta are optional. The reasons for that are described below.
Warning
Pagination metadata can be missing in the request for compatibility reasons, but this behaviour is deprecated and should be avoided.
9.3.2.13.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 |
AccountDetailPaginationMeta.page_size | Requested page size. The number of records in response will not exceed this value. If the response was truncated, the record id immediately following the returned ones will be provided in next_record_id. | 0 < page_size < 32 bit unsigned int max (4294967296) | 100 |
AccountDetailPaginationMeta.first_record_id.writer | requested page start by writer | name#domain | my_asset#my_domain |
AccountDetailPaginationMeta.first_record_id.key | requested page start by key | string | age |
Note
When specifying first record id, it is enough to provide the attributes (writer, key) that are unset in the main query.
9.3.2.13.4. Response Schema¶
message AccountDetailResponse {
string detail = 1;
uint64 total_number = 2;
AccountDetailRecordId next_record_id = 3;
}
9.3.2.13.5. Response Structure¶
Field | Description | Constraint | Example |
---|---|---|---|
Detail | key-value pairs with account details | JSON | see below |
total_number | number of records matching query without page limits | 0 < total_number < 32 bit unsigned int max (4294967296) | 100 |
next_record_id.writer | the writer account of the record immediately following curent page | <account_name>@<domain_id> | pushkin@lyceum.tsar |
next_record_id.key | the key of the record immediately following curent page | string | cold and sun |
9.3.2.13.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 |
4 | Invalid pagination metadata | Wrong page size or nonexistent first record | Set valid page size, and make sure that the first record id is valid, or leave the first record id unspecified |
9.3.2.13.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
}
}
9.3.2.14. Get Asset Info¶
9.3.2.14.1. Purpose¶
In order to get information on the given asset (as for now - its precision), user can send GetAssetInfo query.
9.3.2.14.2. Request Schema¶
message GetAssetInfo {
string asset_id = 1;
}
9.3.2.14.3. Request Structure¶
Field | Description | Constraint | Example |
---|---|---|---|
Asset ID | asset id to know related information | <asset_name>#<domain_id> | jpy#japan |
9.3.2.14.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
9.3.2.14.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 |
9.3.2.15. Get Roles¶
9.3.2.15.1. Purpose¶
To get existing roles in the system, a user can send GetRoles query to Iroha network.
9.3.2.15.2. Request Schema¶
message GetRoles {
}
9.3.2.15.3. Response Schema¶
message RolesResponse {
repeated string roles = 1;
}
9.3.2.15.4. Response Structure¶
Field | Description | Constraint | Example |
---|---|---|---|
Roles | array of created roles in the network | set of roles in the system | {MoneyCreator, User, Admin, …} |
9.3.2.15.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 |
9.3.2.16. Get Role Permissions¶
9.3.2.16.1. Purpose¶
To get available permissions per role in the system, a user can send GetRolePermissions query to Iroha network.
9.3.2.16.2. Request Schema¶
message GetRolePermissions {
string role_id = 1;
}
9.3.2.16.3. Request Structure¶
Field | Description | Constraint | Example |
---|---|---|---|
Role ID | role to get permissions for | existing role in the system | MoneyCreator |
9.3.2.16.4. Response Schema¶
message RolePermissionsResponse {
repeated string permissions = 1;
}
9.3.2.16.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, …} |
9.3.2.16.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 |
9.3.2.17. Get Peers¶
9.3.2.17.1. Purpose¶
A query that returns a list of peers in Iroha network.
9.3.2.17.2. Request Schema¶
message GetPeers {
}
9.3.2.17.3. Response Schema¶
message Peer {
string address = 1;
string peer_key = 2; // hex string
}
message PeersResponse {
repeated Peer peers = 1;
}
9.3.2.17.4. Response Structure¶
A list of peers with their addresses and public keys is returned.
Field | Description | Constraint | Example |
---|---|---|---|
Peers | array of peers from the network | non-empty list of peers | {Peer{“peer.domain.com”, “292a8714694095edce6be799398ed5d6244cd7be37eb813106b217d850d261f2”}, …} |
9.3.2.17.5. Possible Stateful Validation Errors¶
Code | Error Name | Description | How to solve |
---|---|---|---|
1 | Could not get peers | Internal error happened | Try again or contact developers |
2 | No such permissions | Query creator does not have enough permissions to get peers | Append a role with can_get_blocks or can_get_peers permission |
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 |
Warning
Currently Get Peers query uses “can_get_blocks” permission for compatibility purposes. Later that will be changed to “can_get_peers” with the next major Iroha release.
9.3.2.18. Fetch Commits¶
9.3.2.18.1. Purpose¶
To get new blocks as soon as they are committed, a user can invoke FetchCommits RPC call to Iroha network.
9.3.2.18.2. Request Schema¶
No request arguments are needed
9.3.2.18.3. Response Schema¶
message BlockQueryResponse {
oneof response {
BlockResponse block_response = 1;
BlockErrorResponse block_error_response = 2;
}
}
message BlockResponse {
Block block = 1;
}
message BlockErrorResponse {
string message = 1;
}
Please note that it returns a stream of BlockQueryResponse.
9.3.2.18.4. Response Structure¶
Field | Description | Constraint | Example |
---|---|---|---|
Block | Iroha block | only committed blocks | { ‘block_v1’: ….} |
9.3.2.18.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 can_get_block permission |
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 |
Note
BlockErrorResponse contains only message field. In case of stateful validation error it will be “stateful invalid”. GetBlock requires same can_get_block permission. Therefore, it can be used with height = 1 (first block is always present) to check for invalid signatories or insufficient permissions.
9.3.2.18.6. Example¶
You can check an example how to use this query here: https://github.com/x3medima17/twitter