feat: refactor ICQ module documentation [NTRN-349]

app/proposals_allowlisting.go

@@ -68,7 +68,7 @@ func isSdkMessageWhitelisted(msg sdk.Msg) bool {
 		*ibcclienttypes.MsgRecoverClient,
 		*ibcclienttypes.MsgIBCSoftwareUpgrade,
 		*tokenfactorytypes.MsgUpdateParams,
-		*interchainqueriestypes.MsgUpdateParams,
+		*interchainqueriestypes.MsgUpdateParamsRequest,
 		*interchaintxstypes.MsgUpdateParams,
 		*feeburnertypes.MsgUpdateParams,
 		*feerefundertypes.MsgUpdateParams,

proto/neutron/interchainqueries/genesis.proto

@@ -8,57 +8,56 @@ import "neutron/interchainqueries/params.proto";
 
 option go_package = "github.com/neutron-org/neutron/v4/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-typed Interchain Queries.
   repeated KVKey keys = 4;
-
-  // The filter for transaction search ICQ
+  // A stringified list of filters for remote transactions search. Only applicable for the TX-typed
+  // Interchain Queries. Example: "[{\"field\":\"tx.height\",\"op\":\"Gte\",\"value\":2644737}]".
   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.
+  // Duration in blocks that is required to pass since the query registration/update for the
+  // query to become available for anybody to be removed.
   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;
 }
 
+// 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 first half of the storage path. It is supposed to be a substore name for the query
+  // (e.g. bank, staking, etc.).
   string path = 1;
-  // Key you want to read from the storage
+  // The second half of the storage path. The remaining part of a full path to an IAVL storage node.
   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/params.proto

@@ -6,21 +6,18 @@ import "gogoproto/gogo.proto";
 
 option go_package = "github.com/neutron-org/neutron/v4/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 amount of blocks required to pass since an Interchain Query registration/update for the
+  // query to become available for removal by anybody.
   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;
 }

proto/neutron/interchainqueries/query.proto

@@ -10,78 +10,99 @@ import "neutron/interchainqueries/tx.proto";
 
 option go_package = "github.com/neutron-org/neutron/v4/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.
+  // Queries the current parameters of the module.
   rpc Params(QueryParamsRequest) returns (QueryParamsResponse) {
     option (google.api.http).get = "/neutron/interchainqueries/params";
   }
-
+  // Queries all the registered Interchain Queries in the module with filtration by owner and/or
+  // connection ID.
   rpc RegisteredQueries(QueryRegisteredQueriesRequest) returns (QueryRegisteredQueriesResponse) {
     option (google.api.http).get = "/neutron/interchainqueries/registered_queries";
   }
-
+  // Queries a registered Interchain Query by ID.
   rpc RegisteredQuery(QueryRegisteredQueryRequest) returns (QueryRegisteredQueryResponse) {
     option (google.api.http).get = "/neutron/interchainqueries/registered_query";
   }
-
-  rpc QueryResult(QueryRegisteredQueryResultRequest) returns (QueryRegisteredQueryResultResponse) {
+  // Queries the last successfully submitted result of an Interchain Query.
+  rpc QueryResult(QueryQueryResultRequest) returns (QueryQueryResultResponse) {
     option (google.api.http).get = "/neutron/interchainqueries/query_result";
   }
-
-  rpc LastRemoteHeight(QueryLastRemoteHeight) returns (QueryLastRemoteHeightResponse) {
+  // Queries the last height of a remote chain known to the IBC client behind a given connection ID.
+  rpc LastRemoteHeight(QueryLastRemoteHeightRequest) 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.
+  // Stores 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;
 }
 
-message QueryRegisteredQueryResultRequest {
+// Request type for the Query/QueryResult RPC method.
+message QueryQueryResultRequest {
+  // ID of an Interchain Query.
   uint64 query_id = 1;
 }
 
-message QueryRegisteredQueryResultResponse {
+// Response type for the Query/QueryResult RPC method.
+message QueryQueryResultResponse {
+  // The last successfully submitted result of an Interchain Query.
   QueryResult result = 1;
 }
 
-message Transaction {
-  uint64 id = 1;
-  uint64 height = 2;
-  bytes data = 3;
-}
-
-message QueryLastRemoteHeight {
+// Request type for the Query/LastRemoteHeight RPC method.
+message QueryLastRemoteHeightRequest {
+  // 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;
 }