Merge pull request #646 from neutron-org/feat/refactor-icq-module-documentation

Author: pr0n00gler

docs/static/swagger.yaml

@@ -8,57 +8,59 @@ import "neutron/interchainqueries/params.proto";
 
 option go_package = "github.com/neutron-org/neutron/v5/x/interchainqueries/types";
 
+// Information about an Interchain Query registered in the interchainqueries module.
 message RegisteredQuery {
   // The unique id of the registered query.
   uint64 id = 1;
-
-  // The address that registered the query.
+  // The address of the contract that registered the query.
   string owner = 2;
-
-  // The query type identifier: `kv` or `tx` now
+  // The query type identifier: `kv` or `tx`.
   string query_type = 3;
-
-  // The KV-storage keys for which we want to get values from remote chain
+  // The KV-storage keys for which to get values from the remote chain. Only applicable for the
+  // KV Interchain Queries. Max amount of keys is limited by the module's `max_kv_query_keys_count`
+  // parameters.
   repeated KVKey keys = 4;
-
-  // The filter for transaction search ICQ
+  // A stringified list of filters for remote transactions search. Only applicable for the TX
+  // Interchain Queries. Example: "[{\"field\":\"tx.height\",\"op\":\"Gte\",\"value\":2644737}]".
+  // Supported operators: "eq", "lt", "gt", "lte", "gte". Max amount of filter conditions is limited
+  // by the module's `max_transactions_filters` parameters.
   string transactions_filter = 5;
-
-  // The IBC connection ID for getting ConsensusState to verify proofs
+  // The IBC connection ID to the remote chain (the source of querying data). Is used for getting
+  // ConsensusState from the respective IBC client to verify query result proofs.
   string connection_id = 6;
-
-  // Parameter that defines how often the query must be updated.
+  // Parameter that defines the minimal delay between consecutive query executions (i.e. the
+  // minimal delay between query results update).
   uint64 update_period = 7;
-
-  // The local chain last block height when the query result was updated.
+  // The local chain block height of the last query results update.
   uint64 last_submitted_result_local_height = 8;
-
-  // The remote chain last block height when the query result was updated.
+  // The remote chain block height that corresponds to the last query result update.
   ibc.core.client.v1.Height last_submitted_result_remote_height = 9;
-
-  // Amount of coins deposited for the query.
+  // Amount of coins paid for the Interchain Query registration. The deposit is paid back to the
+  // remover. The remover can be either the query owner (during the submit timeout) or anybody.
   repeated cosmos.base.v1beta1.Coin deposit = 10 [
     (gogoproto.castrepeated) = "github.com/cosmos/cosmos-sdk/types.Coins",
     (gogoproto.nullable) = false
   ];
-
-  // Timeout before query becomes available for everybody to remove.
+  // The duration, measured in blocks, that must pass since the query's registration or its last
+  // result submission before the query becomes eligible for removal by anyone.
   uint64 submit_timeout = 11;
-
-  // The local chain height when the query was registered.
+  // The local chain block height of the Interchain Query registration.
   uint64 registered_at_height = 12;
 }
 
+// Represents a path to an IAVL storage node.
 message KVKey {
-  // Path (storage prefix) to the storage where you want to read value by key
-  // (usually name of cosmos-sdk module: 'staking', 'bank', etc.)
+  // The substore name used in an Interchain Query. Typically, this corresponds to the keeper's
+  // storeKey, usually the module's name, such as "bank", "staking", etc.
   string path = 1;
-  // Key you want to read from the storage
+  // A bytes field representing the key for specific data in the module's storage.
   bytes key = 2;
 }
 
-// GenesisState defines the interchainqueries module's genesis state.
+// The interchainqueries module's genesis state model.
 message GenesisState {
+  // The parameters of the module.
   Params params = 1 [(gogoproto.nullable) = false];
+  // A list of registered Interchain Queries.
   repeated RegisteredQuery registered_queries = 2;
 }

proto/neutron/interchainqueries/genesis.proto

@@ -6,22 +6,20 @@ import "gogoproto/gogo.proto";
 
 option go_package = "github.com/neutron-org/neutron/v5/x/interchainqueries/types";
 
-// Params defines the parameters for the module.
+// The parameters for the module.
 message Params {
   option (gogoproto.goproto_stringer) = false;
-  // Defines amount of blocks required before query becomes available for
-  // removal by anybody
+  // The duration, measured in blocks, that must pass since the query's registration or its last
+  // result submission before the query becomes eligible for removal by anyone. Is used to set
+  // `submit_timeout` on Interchain Query registration.
   uint64 query_submit_timeout = 1;
-
-  // Amount of coins deposited for the query.
+  // Amount of coins required to be provided as deposit on Interchain Query registration.
   repeated cosmos.base.v1beta1.Coin query_deposit = 2 [
     (gogoproto.castrepeated) = "github.com/cosmos/cosmos-sdk/types.Coins",
     (gogoproto.nullable) = false
   ];
-
-  // Amount of tx hashes to be removed during a single EndBlock. Can vary to
-  // balance between network cleaning speed and EndBlock duration. A zero value
-  // means no limit.
+  // Amount of tx hashes to be removed during a single EndBlock. Can vary to balance between
+  // network cleaning speed and EndBlock duration. A zero value means no limit.
   uint64 tx_query_removal_limit = 3;
 
   // Maximum amount of keys in a registered key value query

proto/neutron/interchainqueries/params.proto

@@ -10,65 +10,87 @@ import "neutron/interchainqueries/tx.proto";
 
 option go_package = "github.com/neutron-org/neutron/v5/x/interchainqueries/types";
 
-// Query defines the gRPC querier service.
+// Defines the Query interface of the module.
 service Query {
-  // Parameters queries the parameters of the module.
+  // Fetches the current parameters of the interchainqueries module.
   rpc Params(QueryParamsRequest) returns (QueryParamsResponse) {
     option (google.api.http).get = "/neutron/interchainqueries/params";
   }
-
+  // Retrieves all registered Interchain Queries in the module, with optional filtering by owner
+  // and/or connection ID.
   rpc RegisteredQueries(QueryRegisteredQueriesRequest) returns (QueryRegisteredQueriesResponse) {
     option (google.api.http).get = "/neutron/interchainqueries/registered_queries";
   }
-
+  // Fetches details of a registered Interchain Query using its ID.
   rpc RegisteredQuery(QueryRegisteredQueryRequest) returns (QueryRegisteredQueryResponse) {
     option (google.api.http).get = "/neutron/interchainqueries/registered_query";
   }
-
+  // Retrieves the most recent successfully submitted result of an Interchain Query. This is only
+  // applicable for KV Interchain Queries.
   rpc QueryResult(QueryRegisteredQueryResultRequest) returns (QueryRegisteredQueryResultResponse) {
     option (google.api.http).get = "/neutron/interchainqueries/query_result";
   }
-
+  // Retrieves the most recent height of a remote chain as known by the IBC client associated with
+  // a given connection ID.
   rpc LastRemoteHeight(QueryLastRemoteHeight) returns (QueryLastRemoteHeightResponse) {
     option (google.api.http).get = "/neutron/interchainqueries/remote_height";
   }
 }
 
-// QueryParamsRequest is request type for the Query/Params RPC method.
+// Request type for the Query/Params RPC method.
 message QueryParamsRequest {}
 
-// QueryParamsResponse is response type for the Query/Params RPC method.
+// Response type for the Query/Params RPC method.
 message QueryParamsResponse {
-  // params holds all the parameters of this module.
+  // Contains all parameters of the module.
   Params params = 1 [(gogoproto.nullable) = false];
 }
 
+// Request type for the Query/RegisteredQueries RPC method.
 message QueryRegisteredQueriesRequest {
+  // A list of owners of Interchain Queries. Query response will contain only Interchain Queries
+  // that are owned by one of the owners in the list. If none, Interchain Queries are not filtered
+  // out by the owner field.
   repeated string owners = 1;
+  // IBC connection ID. Query response will contain only Interchain Queries that have the same IBC
+  // connection ID parameter. If none, Interchain Queries are not filtered out by the connection ID
+  // field.
   string connection_id = 2;
+  // Pagination parameters for the request. Use values from previous response in the next request
+  // in consecutive requests with paginated responses.
   cosmos.base.query.v1beta1.PageRequest pagination = 3;
 }
 
+// Response type for the Query/RegisteredQueries RPC method.
 message QueryRegisteredQueriesResponse {
+  // A list of registered Interchain Queries.
   repeated RegisteredQuery registered_queries = 1 [(gogoproto.nullable) = false];
-
-  // pagination defines the pagination in the response.
+  // Current page information. Use values from previous response in the next request in consecutive
+  // requests with paginated responses.
   cosmos.base.query.v1beta1.PageResponse pagination = 2;
 }
 
+// Request type for the Query/RegisteredQuery RPC method.
 message QueryRegisteredQueryRequest {
+  // ID of an Interchain Query.
   uint64 query_id = 1;
 }
 
+// Response type for the Query/RegisteredQuery RPC method.
 message QueryRegisteredQueryResponse {
+  // A registered Interchain Query.
   RegisteredQuery registered_query = 1;
 }
 
+// Request type for the Query/QueryResult RPC method.
 message QueryRegisteredQueryResultRequest {
+  // ID of an Interchain Query.
   uint64 query_id = 1;
 }
 
+// Response type for the Query/QueryResult RPC method.
 message QueryRegisteredQueryResultResponse {
+  // The last successfully submitted result of an Interchain Query.
   QueryResult result = 1;
 }
 
@@ -78,10 +100,17 @@ message Transaction {
   bytes data = 3;
 }
 
+// Request type for the Query/LastRemoteHeight RPC method.
 message QueryLastRemoteHeight {
+  // Connection ID of an IBC connection to a remote chain. Determines the IBC client used in query
+  // handling.
   string connection_id = 1;
 }
 
+// Response type for the Query/LastRemoteHeight RPC method.
 message QueryLastRemoteHeightResponse {
+  // The height of the chain that the IBC client is currently on.
   uint64 height = 1;
+  // The revision of the chain that the IBC client is currently on.
+  uint64 revision = 2;
 }