6.2. 쿼리¶
쿼리는 World State View(블록체인의 최신 상태)의 특정 부분과 관련하여 요청하는 것입니다. 쿼리는 체인 내부의 컨텐츠를 수정하지 않으며 피어가 들어온 쿼리를 처리한 후 즉시 쿼리에 대한 응답이 클라이언트에게 전달될 것입니다.
6.2.1. 검증¶
valid한 모든 커리는 다음을 포함합니다:
- 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)
- 쿼리 생성자의 서명 — 쿼리 생성자의 identity를 확인하는데 사용됩니다.
- 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. 계정 조회하기¶
6.2.2.1. 목적¶
계정 조회하기 쿼리는 계정의 상태를 조회할 때 사용됩니다.
6.2.2.2. Request 스키마¶
message GetAccount {
string account_id = 1;
}
6.2.2.3. Request 구조¶
| 필드명 | 설명 | 조건 | Example |
|---|---|---|---|
| 계정 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 구조¶
| 필드명 | 설명 | 조건 | Example |
|---|---|---|---|
| 계정 ID | 계정 ID | <account_name>@<domain_id> | alex@morgan |
| 도메인 ID | 계정이 생성된 도메인 | RFC1035 [1], RFC1123 [2] | morgan |
| Quorum | 트랜젝션을 valid하게 만들기 위해 필요한 서명의 수 | 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. Request 스키마¶
message GetBlock {
uint64 height = 1;
}
6.2.3.3. Request 구조¶
| 필드명 | 설명 | 조건 | Example |
|---|---|---|---|
| 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 구조¶
| 필드명 | 설명 | 조건 | Example |
|---|---|---|---|
| 블록(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. 서명 조회하기¶
6.2.4.1. 목적¶
서명 조회하기 쿼리는 계정의 identity의 역할을 하는 서명을 조회하는 데 사용합니다.
6.2.4.2. Request 스키마¶
message GetSignatories {
string account_id = 1;
}
6.2.4.3. Request 구조¶
| 필드명 | 설명 | 조건 | Example |
|---|---|---|---|
| 계정 ID | 서명을 조회할 계정의 ID | <account_name>@<domain_id> | alex@morgan |
6.2.4.4. Response 스키마¶
message SignatoriesResponse {
repeated bytes keys = 1;
}
6.2.4.5. Response 구조¶
| 필드명 | 설명 | 조건 | Example |
|---|---|---|---|
| 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. 트랜젝션 조회하기¶
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. Request 스키마¶
message GetTransactions {
repeated bytes tx_hashes = 1;
}
6.2.5.3. Request 구조¶
| 필드명 | 설명 | 조건 | Example |
|---|---|---|---|
| 트랜젝션 해시값 | 해시값의 배열 | 32바이트 해시값의 배열 | {hash1, hash2…} |
6.2.5.4. Response 스키마¶
message TransactionsResponse {
repeated Transaction transactions = 1;
}
6.2.5.5. Response 구조¶
| 필드명 | 설명 | 조건 | Example |
|---|---|---|---|
| 트랜젝션 | 트랜젝션의 배열 | Committed 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. Request 스키마¶
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.
| 필드명 | 설명 | 조건 | Example |
|---|---|---|---|
| 트랜젝션 | 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. 계정의 트랜젝션 조회하기¶
6.2.7.1. 목적¶
계정별 트랜젝션의 리스트가 필요한 경우 GetAccountTransactions 쿼리를 사용할 수 있습니다.
주석
This query uses pagination for quicker and more convenient query responses.
6.2.7.2. Request 스키마¶
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 구조¶
| 필드명 | 설명 | 조건 | Example |
|---|---|---|---|
| 계정 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 구조¶
| 필드명 | 설명 | 조건 | Example |
|---|---|---|---|
| 트랜젝션 | 계정의 트랜젝션의 배열 | 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. 계정과 에셋에 관련된 트랜젝션 조회하기¶
6.2.8.1. 목적¶
GetAccountAssetTransactions 쿼리는 주어진 계정과 에셋에 대응하는 모든 트랜젝션을 반환합니다.
주석
This query uses pagination for query responses.
6.2.8.2. Request 스키마¶
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 구조¶
| 필드명 | 설명 | 조건 | Example |
|---|---|---|---|
| 계정 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 구조¶
| 필드명 | 설명 | 조건 | Example |
|---|---|---|---|
| 트랜젝션 | 주어진 계정과 에셋에 대한 트랜젝션의 배열 | 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 | 설명 | 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. 계정의 에셋 조회하기¶
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. Request 스키마¶
message GetAccountAssets {
string account_id = 1;
}
6.2.9.3. Request 구조¶
| 필드명 | 설명 | 조건 | Example |
|---|---|---|---|
| 계정 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 구조¶
| 필드명 | 설명 | 조건 | Example |
|---|---|---|---|
| 에셋 ID | 잔액 확인을 위해 사용된 에셋의 ID | <asset_name>#<domain_id> | jpy#japan |
| 계정 ID | 잔액 확인한 계정의 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. Request 스키마¶
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 구조¶
| 필드명 | 설명 | 조건 | Example |
|---|---|---|---|
| 계정 ID | account id to get details from | <account_name>@<domain_id> | account@domain |
| 키 | 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 구조¶
| 필드명 | 설명 | 조건 | Example |
|---|---|---|---|
| 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. 에셋 정보 조회하기¶
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. Request 스키마¶
message GetAssetInfo {
string asset_id = 1;
}
6.2.11.3. Request 구조¶
| 필드명 | 설명 | 조건 | Example |
|---|---|---|---|
| 에셋 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.12. 역할 조회하기¶
6.2.12.1. 목적¶
계정에 존재하는 역할에 대해 조회하기 위해 GetRoles 쿼리를 Iroha 네트워크에 보낼 수 있습니다.
6.2.12.2. Request 스키마¶
message GetRoles {
}
6.2.12.3. Response 스키마¶
message RolesResponse {
repeated string roles = 1;
}
6.2.12.4. Response 구조¶
| 필드명 | 설명 | 조건 | Example |
|---|---|---|---|
| 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. 역할의 권한 조회하기¶
6.2.13.1. 목적¶
각 역할이 가능한 권한에 조회하기 위해 GetRolePermissions 쿼리를 Iroha 네트워크에 보낼 수 있습니다.
6.2.13.2. Request 스키마¶
message GetRolePermissions {
string role_id = 1;
}
6.2.13.3. Request 구조¶
| 필드명 | 설명 | 조건 | Example |
|---|---|---|---|
| Role ID | 권한을 조회할 역할 | 시스템 내의 존재하는 역할 | MoneyCreator |
6.2.13.4. Response 스키마¶
message RolePermissionsResponse {
repeated string permissions = 1;
}
6.2.13.5. Response 구조¶
| 필드명 | 설명 | 조건 | Example |
|---|---|---|---|
| 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. Request 스키마¶
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 구조¶
| 필드명 | 설명 | 조건 | Example |
|---|---|---|---|
| 블록(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. Example¶
You can check an example how to use this query here: https://github.com/x3medima17/twitter