docs: added documentation for ICA queries (#122)

* docs: updated README.md

* docs: updated docs for ICA queries

* docs: updated

README.md

@@ -23,7 +23,7 @@ This is a CosmWasm smart contract that communicates with the golang `ica/host` m
       - [Using `InstantiateMsg`](#using-instantiatemsg)
       - [Using `ExecuteMsg::CreateChannel`](#using-executemsgcreatechannel)
     - [Execute an interchain account transaction](#execute-an-interchain-account-transaction)
-      - [`SendCosmosMsgs`](#sendcosmosmsgs)
+      - [Querying the host chain](#querying-the-host-chain)
     - [Execute a callback](#execute-a-callback)
     - [Channel Closing and Reopening](#channel-closing-and-reopening)
       - [Channel Closing](#channel-closing)
@@ -99,11 +99,9 @@ Learn more about channel closing and reopening [here](#channel-closing-and-reope
 
 ### Execute an interchain account transaction
 
-`ExecuteMsg::SendCosmosMsgs` is used to commit a packet to be sent to the host chain. It accepts `cosmwasm_std::CosmosMsg`s to be sent to the host chain. (The contract then these messages to protobuf messages and sends them to the host chain. You can execute any custom message using `CosmosMsg::Stargate`.
+`ExecuteMsg::SendCosmosMsgs` is used to commit a packet to be sent to the host chain. It accepts `cosmwasm_std::CosmosMsg`s to be sent to the host chain. (The contract then these messages to protobuf messages and sends them to the host chain. You can execute any custom message using `CosmosMsg::Stargate`).
 
-#### `SendCosmosMsgs`
-
-In CosmWasm contracts, `CosmosMsg` are used to execute transactions on the chain that the contract is deployed on. In this contract, we use `CosmosMsg`s to execute transactions on the host chain. This is done by converting the `CosmosMsg`s to an ICA tx based on the encoding of the channel. The ICA tx is then sent to the host chain. The host chain then executes the ICA tx and sends the result back to this contract.
+In CosmWasm contracts, `CosmosMsg` are used to execute transactions on the chain that the contract is deployed on. In this contract, we use `CosmosMsg`s to execute transactions on the host (counterparty) chain. This is done by converting the `CosmosMsg`s to a protobuf ICA tx. The ICA tx is then sent to the host chain. The host chain then executes the ICA tx and sends the result back to this contract.
 
 This execute message allows the user to submit an array of [`cosmwasm_std::CosmosMsg`](https://github.com/CosmWasm/cosmwasm/blob/v1.5.0/packages/std/src/results/cosmos_msg.rs#L27) which are then converted by the contract to an atomic ICA tx.
 
@@ -117,7 +115,15 @@ pub enum ExecuteMsg {
     /// **This is the recommended way to send messages to the ICA host.**
     SendCosmosMsgs {
         /// The stargate messages to convert and send to the ICA host.
+        #[serde_as(deserialize_as = "serde_with::DefaultOnNull")]
         messages: Vec<CosmosMsg>,
+        /// The stargate queries to convert and send to the ICA host.
+        /// The queries are executed after the messages.
+        #[cfg(feature = "query")]
+        #[serde(skip_serializing_if = "Vec::is_empty")]
+        #[serde(default)]
+        #[serde_as(deserialize_as = "serde_with::DefaultOnNull")]
+        queries: Vec<cosmwasm_std::QueryRequest<cosmwasm_std::Empty>>,
         /// Optional memo to include in the ibc packet.
         #[serde(skip_serializing_if = "Option::is_none")]
         packet_memo: Option<String>,
@@ -131,7 +137,7 @@ pub enum ExecuteMsg {
 }
 ```
 
-(`Stargate` allows the user to submit any protobuf message to the host chain.)
+(`CosmosMsg::Stargate` allows the user to submit any protobuf message to the host chain.)
 
 Here is an example execute message that delegates tokens to a validator on the host chain and then votes on a proposal (atomically).
 
@@ -163,6 +169,19 @@ Here is an example execute message that delegates tokens to a validator on the h
 }
 ```
 
+#### Querying the host chain
+
+This contract also supports querying the host chain. To do this, you can submit a `ExecuteMsg::SendCosmosMsgs` with the queries field filled out. The queries are always executed after the messages, and their results are deserialized and returned in the [callbacks](#execute-a-callback).
+
+This feature only works if the host (counterparty) chain is on ibc-go v7.5+. If the host chain is on an older version, then the packet will return an error acknowledgement.
+
+Similarly to `CosmosMsg`, in CosmWasm contracts, `QueryRequest` are used to execute queries on the chain that the contract is deployed on. In this contract, we use `QueryRequest`s to execute queries as transactions on the host (counterparty) chain. This is done by converting the `QueryRequests`s to a protobuf ICA tx. The ICA tx is then sent to the host chain. The host chain then executes the ICA tx and sends the result back to this contract.
+
+Note that if both `messages` and `queries` are provided, the `queries` are executed after the `messages`.
+
+<!-- TODO: Update link below. -->
+Unlike the `messages`, not all query requests are supported, as query execution is not generally deterministic in CosmosSDK. See the documentation for the supported query requests [here](https://srdtrk.github.io/cw-ica-controller/).
+
 ### Execute a callback
 
 This contract supports external contract callbacks. See [`src/types/callbacks.rs`](./src/types/callbacks.rs) to learn what callbacks are supported.
@@ -183,6 +202,20 @@ pub enum ExecuteMsg {
 }
 ```
 
+Note that this crate also includes a proc-macro to add the `ReceiveIcaCallback` variant to the `ExecuteMsg` enum. This is done by adding the following macro to the callback contract:
+
+```rust, ignore
+use cosmwasm_schema::cw_serde;
+use cw_ica_controller::helpers::ica_callback_execute;
+
+#[ica_callback_execute]
+#[cw_serde]
+/// This is the execute message of the contract.
+pub enum ExecuteMsg {
+    // ... other variants
+}
+```
+
 Any contract that imports the `cw-ica-controller` as a library needs to disable the `default-features` of the `cw-ica-controller` crate.
 This is because the `default-features` of the `cw-ica-controller` crate includes the CosmWasm entry points.
 

docs/docs/contract-api/02-execute-msg.mdx

@@ -13,7 +13,7 @@ The `ExecuteMsg` is the message that is used to interact with the `cw-ica-contro
 ## `CreateChannel`
 
 ```rust reference
-https://github.com/srdtrk/cw-ica-controller/blob/v0.5.0/src/types/msg.rs#L27-L37
+https://github.com/srdtrk/cw-ica-controller/blob/7773fbd8d4e227b6c942f0c88575f9800809b4bf/src/types/msg.rs#L29-L39
 ```
 
 This message is used to initiate an ICS-27 channel open handshake. It is only callable by the owner.
@@ -28,7 +28,7 @@ message and save them for future `CreateChannel` messages.
 ## `CloseChannel`
 
 ```rust reference
-https://github.com/srdtrk/cw-ica-controller/blob/v0.5.0/src/types/msg.rs#L38-L39
+https://github.com/srdtrk/cw-ica-controller/blob/7773fbd8d4e227b6c942f0c88575f9800809b4bf/src/types/msg.rs#L40-L41
 ```
 
 This message is used to close the ICS-27 channel. It is only callable by the owner.
@@ -38,7 +38,7 @@ original channel open handshake.
 ## `SendCosmosMsgs`
 
 ```rust reference
-https://github.com/srdtrk/cw-ica-controller/blob/v0.5.0/src/types/msg.rs#L40-L54
+https://github.com/srdtrk/cw-ica-controller/blob/7773fbd8d4e227b6c942f0c88575f9800809b4bf/src/types/msg.rs#L42-L64
 ```
 
 Once an ICS-27 channel open handshake is complete, the owner can control the interchain account on the counterparty
@@ -76,6 +76,41 @@ These will be tested in the future.
 
 :::
 
+### `queries`
+
+This is a list of `QueryRequest`s that the contract will execute on the counterparty chain using the interchain account.
+
+:::warning
+
+This feature only works if the host (counterparty) chain is on ibc-go v7.5+. If the host chain is on an older version, then the packet will return an error acknowledgement.
+
+:::
+
+:::info
+
+If both `messages` and `queries` are provided, then the `messages` will be executed first. If the `messages` are successful, then the `queries` will be executed. If any of the `queries` fail, then the entire execution will fail.
+
+:::
+
+:::note
+
+In CosmosSDK, query execution is not generally deterministic. This is the main reason why not all query requests are supported. The supported query requests are:
+
+|   **QueryRequest**  | `proto3` |
+|:-------------------:|:--------:|
+|     `BankQuery`     |     ✅    |
+|      `Stargate`     |     ✅    |
+|    `StakingQuery`   |     ✅    |
+|      `IbcQuery`     |     ❌    |
+| `DistributionQuery` |     ❌    |
+|     `WasmQuery`     |     ❌    |
+
+Note that not all Stargate queries are supported. Only queries which are marked with [`module_query_safe`](https://github.com/cosmos/cosmos-sdk/blob/27a231ae4816fd8c3ee39a1cc02eccf977fb1b79/proto/cosmos/query/v1/query.proto#L36) tag are supported. You can find a list of supported queries in the [ibc-go documentation](https://ibc.cosmos.network/main/apps/interchain-accounts/messages/#queries) for different versions of ibc-go.
+
+Note that `WasmQuery` support will be added once [this issue](https://github.com/CosmWasm/wasmd/issues/1903) is resolved. Moreover, governance queries (as stargate queries) and `DistributionQuery` will be supported in the next version of the SDK.
+
+:::
+
 ### `packet_memo`
 
 This is the IBC packet memo that will be included in the ICS-27 packet. It is optional and defaults to `""`.

docs/docs/contract-api/04-callbacks.mdx

@@ -81,7 +81,7 @@ If the ICA channel is ordered, cases 2 and 3 will result in the halting of the c
 The `IcaControllerCallbackMsg` enum is the message type that is sent to the callback contract. It contains the following variants:
 
 ```rust reference
-https://github.com/srdtrk/cw-ica-controller/blob/v0.4.1/src/types/callbacks.rs#L15-L46
+https://github.com/srdtrk/cw-ica-controller/blob/7773fbd8d4e227b6c942f0c88575f9800809b4bf/src/types/callbacks.rs#L15-L59
 ```
 
 ### OnChannelOpenAckCallback
@@ -125,6 +125,8 @@ thus, they cannot be included in the IBC packet acknowledgement which is a deter
 
 - **`relayer`**: This is the address of the relayer that relayed the packet to the counterparty chain.
 
+- **`query_result`**: This is the result of the queries that were executed on the counterparty chain. This is only present if the packet contained queries. See [`IcaQueryResult`](https://github.com/srdtrk/cw-ica-controller/blob/7773fbd8d4e227b6c942f0c88575f9800809b4bf/src/types/query_msg.rs#L93-L106)
+
 ### OnTimeoutPacketCallback
 
 The `OnTimeoutPacketCallback` variant is sent to the callback contract when the `cw-ica-controller` receives a timeout packet for a packet that was sent.