Interchain Queries (ICQ)

The Interchain Query (ICQ) feature enables seamless cross-chain interactions by querying the state of one blockchain from another. This feature allows developers to create intent-based actions that trigger specific behaviors based on the queried data. By utilizing interchain queries, you can automate decision-making processes across multiple blockchains, providing an efficient way to orchestrate complex, multi-chain applications.

How It Works

Interchain queries allow you to access the key-value store of a different blockchain by providing a specific key to query. IBC relayers submit query responses. This queried state can then be used to determine what actions should be triggered, based on predefined conditions. For instance, you can check the balance of a particular account on one blockchain and then execute a corresponding action on another chain, such as staking, transferring, or adjusting governance proposals.

Supported Types and Proto Interfaces

You can query various data types from the state of other chains. There are two primary methods to accomplish this:

1. Supported Types: You can use one of the supported types, which are predefined and commonly used data types within the Cosmos ecosystem.
2. Registered Proto Interfaces: Alternatively, you can utilize the registered protocol buffer interfaces that adhere to Cosmos SDK standards. These provide a more flexible way to query and interpret the state, allowing you to work with complex data structures.

Feedback Loops and Comparisons

Once the queried data is retrieved, it can be used for comparisons or to establish feedback loops. For example, if a queried balance exceeds a certain threshold, you can trigger an action to stake the excess funds. Likewise, if a validator's status on one chain changes, you can automatically adjust delegations or governance votes on another chain.

This capability unlocks numerous possibilities for cross-chain workflows, simplifying multi-chain dApp logic and empowering developers to build more dynamic and responsive applications in the interchain ecosystem.

Integrating ICQs

You can use the ICQ feature by attaching an ICQConfig into comparisons and feedback loops. In the ICQConfig, you specify what to query, where to query it, and how to handle a timeout scenario.

Field	Type	Description
connection_id	string	The ID of the connection to use for the interchain query.
chain_id	string	The ID of the blockchain to query.
timeout_policy	intento.interchainquery.v1.TimeoutPolicy	The policy to apply when a timeout occurs.
timeout_duration	google.protobuf.Duration	The duration to wait before a timeout is triggered.
query_type	string	The type of query to perform (e.g., store/bank/key, store/staking/key).
query_key	string	The key in the store to query (e.g., stakingtypes.GetValidatorKey(validatorAddressBz)).

For example, the query_type can be store/bank/key or store/staking/key. The query_key is the key in the store to query, such as stakingtypes.GetValidatorKey(validatorAddressBz). The generation of query keys is abstracted in the Intento Portal frontend.

// Config for using interchain queries
message ICQConfig {
  string connection_id = 1;
  string chain_id = 2;
  intento.interchainquery.v1.TimeoutPolicy timeout_policy = 3;
  google.protobuf.Duration timeout_duration = 4 [
    (gogoproto.nullable) = false,
    (gogoproto.stdduration) = true
  ];
  string query_type = 5;
  string query_key = 6;
}

If SaveResponses in the Flow Configuration is set to true, query responses are added to the Flow History. Check out the Supported Types page or the Intento Portal Flow Builder for some example queries.

Here’s a tutorial for integratingICQConfig for querying balances and adding connectionId, hostConnectionId, as well as a TrustlessAgentConfig in a new submitFlow.

---

Example: Conditional Transfers with ICQ

A common use case for Interchain Queries is to execute conditional transfers based on account balances. For example, you might want to automatically transfer funds only when an account's balance exceeds a certain threshold.

We've created a detailed tutorial that walks through implementing this scenario:

Conditional Transfers with ICQ - Learn how to create an automated flow that:

• Queries an account's balance using ICQ
• Checks if the balance exceeds a specified amount
• Only executes a transfer if the condition is met
• Uses feedback loops to dynamically set transfer amounts

This tutorial provides complete, working code examples that you can adapt for your own use cases.

ICQ module details - x/interchainqueries

SubmitQueryResponse is used to return the query responses. It is used by IBC Relayers. As we use the Stride implementation, it is the same as with Stride.

message MsgSubmitQueryResponse {
  string chain_id = 1;
  string query_id = 2;
  bytes result = 3;
  tendermint.crypto.ProofOps proof_ops = 4;
  int64 height = 5;
  string from_address = 6;
}

Query PendingQueries lists all queries that have been requested (i.e. emitted but have not had a response submitted yet)

message QueryPendingQueriesRequest {}