Skip to content

Commit

Permalink
docs: updated docs for ICA queries
Browse files Browse the repository at this point in the history
  • Loading branch information
srdtrk committed Jun 18, 2024
1 parent db38a1a commit bfceaf0
Show file tree
Hide file tree
Showing 3 changed files with 42 additions and 4 deletions.
5 changes: 5 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -173,10 +173,15 @@ Here is an example execute message that delegates tokens to a validator on the h

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.
Expand Down
37 changes: 34 additions & 3 deletions docs/docs/contract-api/02-execute-msg.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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.
Expand All @@ -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
Expand Down Expand Up @@ -76,6 +76,37 @@ 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` ||

:::

### `packet_memo`

This is the IBC packet memo that will be included in the ICS-27 packet. It is optional and defaults to `""`.
Expand Down
4 changes: 3 additions & 1 deletion docs/docs/contract-api/04-callbacks.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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.
Expand Down

0 comments on commit bfceaf0

Please sign in to comment.