Interchain Queries (ICQ)
How To
Step-by-step guides for performing basic operations with the module
Working Example Contract: For a complete, working implementation, see the neutron_interchain_queries example contract in the neutron-sdk repository. Many developers find it easier to learn from working code.
How to choose the right IBC connection ID for an Interchain Query and verify it
This guide explains how to identify and verify an IBC connection between Neutron and CosmosHub.1. Find an existing IBC connection using an explorer
Visit the map of zones. You may find multiple connections between the two chains. For Neutron and CosmosHub, we’ll useconnection-0 (this is the connection ID on the Neutron side).
2. Pick a Neutron RPC node from the chain registry
Go to Neutron’s chain registry page, choose an RPC node from theapis section, and use it in subsequent neutrond queries with the --node flag.
3. Gather Neutron-side information about the chosen IBC connection
Retrieve the IBC client ID and counterparty details forconnection-0.
4. Check the counterparty chain ID for the Neutron-side IBC connection
Ensure that the counterparty chain ID of the Neutron-side IBC client matches the CosmosHub chain ID.5. Pick a CosmosHub RPC node from the chain registry
Visit CosmosHub’s chain registry page, select an RPC node from theapis section, and use it in gaiad queries with the --node flag.
6. Verify that CosmosHub’s counterparty corresponds to Neutron
Using the counterparty information from Step 3, confirm that CosmosHub’s IBC connection and client details match Neutron’s information. By following these steps, you can ensure that the IBC connection ID you choose is valid and correctly corresponds to the intended chains. Might be interesting:How to find out what transaction filter to use
Imagine you need your Interchain Query-based smart contract to track undelegations made bycosmos17s3uhcvrwrsp2ldjvxp8rseyc3ulpchdry87hp on CosmosHub.
1. Find the up-to-date source code of the staking module
- Locate the current version of the
stakingmodule used by CosmosHub. Check the chain registry to find the repository and version in use, e.g.,v21.0.0. - In the
gaiarepository forv21.0.0, locate the cosmos-sdk import in thego.modfile, e.g.,v0.50.9. In this case, thecosmos-sdkversion is replaced with a special release v0.50.9-lsm - Access the
stakingmodule’s source code in the cosmos-sdk with tag v0.50.9-lsm.
2. Find the handler managing undelegations
Identify the Undelegate handler in thestaking module’s keeper.
3. Locate the events emitted during undelegations
Examine the event emission section of the Undelegate handler code.4. Create a transaction filter using the events
Match the event type and attributes emitted. For this scenario, use the filter:unbond.delegator=cosmos17s3uhcvrwrsp2ldjvxp8rseyc3ulpchdry87hpThis corresponds to:
types.EventTypeUnbond.types.AttributeKeyDelegator = cosmos17s3uhcvrwrsp2ldjvxp8rseyc3ulpchdry87hp.
5. Test the query filter
Verify your filter by running the followinggaiad q txs query to ensure it retrieves the expected results.
Might be interesting:
How to register and handle a KV Interchain Query
This guide provides a brief guide to registering a KV Interchain Query and handling its results using the neutron-std and neutron-sdk libraries in a smart contract.1. Find the appropriate helper function in Neutron SDK
Locate the helper function for registering an Interchain Query that suits your requirements in the neutron-sdk. For this example, we’ll use the new_register_balances_query_msg function. If no predefined helper function meets your needs, refer to the How to register a KV Interchain Query with custom keys section.2. Define the Interchain Query registration entry point
Create anexecute message handler in your contract to register the Interchain Query using the helper function as a submessage.
3. Define the Interchain Query registration response handler
In the reply handler, decode the submessage result as a MsgRegisterInterchainQueryResponse to access the assigned Interchain Query ID.4. Define the Interchain Query results processing handler
Retrieve the query result from theinterchainqueries module’s storage using the query_balance function and process it.
5. Register the Interchain Query
Send a ExecuteMsg::RegisterBalancesQuery message to the contract with the required parameters. Might be interesting:- What are entry points and sudo calls?
- Limited gas for sudo calls
- What happens if a sudo callback to a smart contract owning an Interchain Query fails?
How to register and handle a KV Interchain Query with custom keys
If your KV Interchain Query cannot be handled using the helpers from the Interchain Queries related package in neutron-sdk, you can define theKVKeys manually. This example demonstrates registering an Account Interchain Query for cosmos-hub v21.0.0.
1. Figure out the respective data path and model
To determine how the data path is constructed and what the data model is, you need to investigate the module’s code. Start by locating the gRPC handler in the module that corresponds to the data you’re interested in. This handler provides a clue about where the data is stored and what the data model is. For this example:- The store key used at module’s keeper initialisation is
acc. - The data path is the accounts store prefix + hex address representation.
- The data model is
BaseAccount.
2. Define Interchain Query registration entry point
To enable Interchain Query registration, implement anexecute message handler in your smart contract. This handler will broadcast a MsgRegisterInterchainQuery message as a submessage. Use the data path information derived earlier to configure the message.
3. Define Interchain Query registration response handling
In the reply handler, decode the submessage result as a MsgRegisterInterchainQueryResponse to retrieve the assigned Interchain Query ID.4. Implement reconstruction of the query result
Define how the query result should be reconstructed from StorageValue into aBaseAccount instance. This involves decoding the stored values into the appropriate data structure.
5. Define Interchain Query results submission handling
Retrieve the submitted Interchain Query result from theinterchainqueries module’s storage using the query_kv_result helper function. Handle the result by decoding it and performing your contract’s desired logic.
6. Perform Interchain Query registration
Broadcast a ExecuteMsg::RegisterAccountQuery message to the smart contract with the required parameters. Might be interesting:- What are entry points and sudo calls?
- Limited gas for sudo calls
- What happens if a sudo callback to a smart contract owning an Interchain Query fails?
How to register and handle a TX Interchain Query
This guide explains how to register a TX Interchain Query and handle its results using the neutron-std and neutron-sdk libraries in a smart contract.1. Find out what transaction filter to use
Determine the appropriate tx_search query that matches the transactions you want to process. The How to find out what transaction filter to use section provides detailed instructions for crafting a transaction filter.2. Define Interchain Query registration entry point
Implement anexecute message handler in your contract to handle Interchain Query registration. Use the MsgRegisterInterchainQuery message. Populate this message using the tx_search query identified in step 1 as the transactions_filter.
3. Define Interchain Query results submission handling
Implement a handler to process submitted TX Interchain Query results. This includes:- Decoding the transaction and its messages.
- Performing contract-side verification of submitted TX Interchain Query results.
- Handling the results in your business logic.