Queries

Make a view call across chains using IQS.

This tutorial demonstrates how to make a simple interchain view call via the Queries API from pre-deployed TestQuerySender contracts to any arbitrary target on which Hyperlane is deployed.

Inputs

• $DESTINATION_DOMAIN: The domain ID of the destination chain. You can use 43113 to send to Fuji, or choose from any of the known Domain identifiers

• $TARGET: The address of the contract on the destination chain you want to query. You could just query for the owner() of the InterchainAccountRouter contract which is found at 0xc61Bbf8eAb0b748Ecb532A7ffC49Ab7ca6D3a39D on every testnet chain

• $TARGET_DATA: The ABI encoded call, if you want to make an owner() call that would be 0x8da5cb5b

• $GAS_AMOUNT: The amount of gas on the destination chain to pay for. For the simple owner() example, we can set this to a generous 200000 gas. See Interchain gas payments to learn more.

How TestQuerySender works

• TestQuerySender calls the InterchainQueryRouter and designates a callback function for the result of the query itself. It will Automatically pay for interchain gas.

function queryAddress(
    uint32 _destinationDomain,
    address _target,
    bytes calldata _targetData,
    uint256 _gasAmount
) public {
    bytes32 _messageId = queryRouter.query(
        _destinationDomain,
        Call({to: _target, data: _targetData}),
        abi.encodePacked(this.handleQueryAddressResult.selector)
    );
    _payForGas(_messageId, _destinationDomain, _gasAmount);
}

function handleQueryAddressResult(address _result) public {
    emit ReceivedAddressResult(_result);
    lastAddressResult = _result;
}

Make a query

Using Metamask

Getting the Interchain Gas Payment Quote

1. The TestQuerySender contract uses the DefaultIsmInterchainGasPaymaster to pay for interchain gas. Navigate to this contract page on Etherscan (or whatever chain you want to send from, see DefaultIsmInterchainGasPaymaster contract addresses)
2. Under the Contract tab, select Read Contract.

3. Expand the quoteGasPayment function.

4. For the destination domain, enter $DESTINATION_DOMAIN.

5. For gas amount, enter $GAS_AMOUNT, which is 200000.

6. Click Query and make note of the amount returned as $GAS_PAYMENT_QUOTE. For example, at the time of writing, the quote is 1 wei.

Making the Query

1. Navigate to the TestQuerySender 0x96D7D6Eba6C635e3EaC12b593Ef8B2eE1F6E6683 contract page on Etherscan (or whatever chain you want to send from - on testnets the TestQuerySender is always found at 0x96D7D6Eba6C635e3EaC12b593Ef8B2eE1F6E6683, and on mainnets it's 0x8566F965f613cB47A5Bd59879d07186122590895)

2. Under the Contract tab, find the Write Contract button.

3. Click on the Connect to Web3 button to connect your Wallet (i.e. Metamask). Make sure that you are on the correct network.

4. Expand the queryAddress box.

5. For the payable amount, Etherscan expects an amount quoted in ether, while our $GAS_PAYMENT_QUOTE is in wei. To convert from wei to ether, input the amount $GAS_PAYMENT_QUOTE, which is in wei, into https://eth-converter.com/ and copy the ether amount. Use this ether amount as the payable amount.

6. For destination domain, enter $DESTINATION_DOMAIN.

7. For the target, enter $TARGET, i.e. the address of the contract you like to query on the destination.

8. For target data, enter $TARGET_DATA, i.e. the ABI encoded call of the query itself.

9. For gas amount, enter $GAS_AMOUNT.

10. Submit the transaction via your wallet/Metamask

Using cast

We can get an interchain gas payment quote and call TestQuerySender directly using cast.

Getting the Interchain Gas Payment Quote

The $IGP_ADDRESS is the address of the DefaultIsmInterchainGasPaymaster, which is used by the TestQuerySender.

First, we use the $IGP_ADDRESS to get a quote for how much your gas payment will cost, and we save this in an environment variable called $GAS_PAYMENT_QUOTE:

cast call $IGP_ADDRESS "quoteGasPayment(uint32,uint256)" $DESTINATION_DOMAIN $GAS_AMOUNT --rpc-url $RPC_URL

Making the Query

You can call the TestQuerySender directly using cast. Make sure that you have a valid RPC URL for the origin chain and a private key with which you can pay for gas. The TestQuerySender address is 0x96D7D6Eba6C635e3EaC12b593Ef8B2eE1F6E6683 on testnets and 0x8566F965f613cB47A5Bd59879d07186122590895 on mainnets.

cast send 0x96D7D6Eba6C635e3EaC12b593Ef8B2eE1F6E6683 'queryAddress(uint32,address,bytes,uint256)' $DESTINATION_DOMAIN 0xc61Bbf8eAb0b748Ecb532A7ffC49Ab7ca6D3a39D $(cast calldata "owner()") $GAS_AMOUNT --rpc-url $RPC_URL --private-key $PRIVATE_KEY --value $GAS_PAYMENT_QUOTE

If you view the transaction on a block explorer, you should be able to see the Dispatch event. You can see an example message sending transaction here.

Confirm query

You can use the Hyperlane Explorer to show the delivery of the message for the query to the destination. When it gets delivered (example), the delivery transaction will actually be also the origin tx hash for the delivery of the result back to the origin. Once again, you can use the Message Explorer to check on the delivery of that message (example). When all is done, you can see how the query result was persisted on the TestQuerySender contract by going to the Contract => Read Contract page and expanding the lastAddressResult section.