Executing queries

Queries in the CW20-ICS20 contract allow users to retrieve various types of information related to IBC transfers, configurations, and permissions for CW20 tokens.

To execute a query, use the following general format with archwayd:

archwayd query wasm contract-state smart CW20_ICS20_CONTRACT_ADDRESS '<QUERY_JSON>'

Replace CW20_ICS20_CONTRACT_ADDRESS with your contract's address and <QUERY_JSON> with the specific query structure.

The CW20-ICS20 contract supports several types of queries:

Channel: Retrieve information about a specific IBC channel.
Config: Get the contract's configuration details.
List Channels: List all IBC channels the contract is using.
List Tokens: Get a list of all allowed CW20 tokens.

Each query type has its own specific structure and returns different information. In the following sections, we'll explore each query type in detail, providing examples and explaining the returned data.

For more detailed information about the query implementations, you can refer to the cw20-ics20 contract source code.

Port

The Port query retrieves the IBC port ID that is bound to this contract. This port ID is crucial for the IBC setup and is used to identify the contract in cross-chain communications.

To execute the Port query, use the following command:

archwayd query wasm contract-state smart CW20_ICS20_CONTRACT_ADDRESS \'{  "port": {}}'

Parameters:

CW20_ICS20_CONTRACT_ADDRESS: The address of your CW20-ICS20 contract

Response: The query will return a JSON object containing the port ID. For example:

{  "port_id": "wasm.your_contract_address"}

Note:

The port ID is typically in the format "wasm.{contract_address}", where {contract_address} is the bech32-encoded address of your CW20-ICS20 contract.
This port ID is essential for setting up IBC connections and channels.
The port is automatically created and bound to the contract when it's instantiated.

You can use this port ID when configuring IBC connections on other chains or when debugging IBC-related issues.

ListChannels

The ListChannels query retrieves a list of all IBC channels that the contract is connected to, providing a clear view of active channels.

To execute the ListChannels query, use the following command:

archwayd query wasm contract-state smart CW20_ICS20_CONTRACT_ADDRESS \'{  "list_channels": {}}'

Parameters:

CW20_ICS20_CONTRACT_ADDRESS: The address of your CW20-ICS20 contract

Response: The query will return a JSON object containing an array of channel information. For example:

{  "channels": [    {      "id": "channel-0",      "counterparty_endpoint": {        "port_id": "transfer",        "channel_id": "channel-1"      },      "connection_id": "connection-0"    },    {      "id": "channel-2",      "counterparty_endpoint": {        "port_id": "transfer",        "channel_id": "channel-5"      },      "connection_id": "connection-1"    }  ]}

Response Fields:

id: The local channel ID
counterparty_endpoint: Information about the counterparty chain's endpoint
- port_id: The port ID on the counterparty chain
- channel_id: The channel ID on the counterparty chain
connection_id: The ID of the IBC connection this channel is part of

Note:

This query is useful for understanding which channels are available for IBC transfers.
Each channel represents a connection to a specific chain or module on another chain.
The number of channels can vary depending on how many IBC connections have been established.

Channel

The Channel query returns the details of a specific IBC channel identified by its ID, including its state and connection details.

To execute the Channel query, use the following command:

archwayd query wasm contract-state smart CW20_ICS20_CONTRACT_ADDRESS \'{  "channel": {    "id": "CHANNEL_ID"  }}'

Parameters:

CW20_ICS20_CONTRACT_ADDRESS: The address of your CW20-ICS20 contract
CHANNEL_ID: The ID of the specific channel you want to query (e.g., "channel-0")

Response: The query will return a JSON object containing detailed information about the specified channel. For example:

{  "info": {    "id": "channel-0",    "counterparty_endpoint": {      "port_id": "transfer",      "channel_id": "channel-1"    },    "connection_id": "connection-0"  },  "balances": [    {      "denom": "uatom",      "amount": "1000000"    }  ],  "total_sent": [    {      "denom": "uatom",      "amount": "500000"    }  ]}

Response Fields:

info: Basic information about the channel
- id: The local channel ID
- counterparty_endpoint: Information about the counterparty chain's endpoint
- connection_id: The ID of the IBC connection this channel is part of
balances: Current balances of tokens in the channel
total_sent: Total amount of tokens sent through this channel

Note:

This query is useful for getting detailed information about a specific channel.
The balances field shows the current amount of tokens held in the channel.
The total_sent field provides a cumulative total of all tokens sent through this channel since its creation.

If the specified channel ID doesn't exist, the query will return an error.

Config

The Config query retrieves the configuration settings of the CW20-ICS20 contract, including key operational parameters.

To execute the Config query, use the following command:

archwayd query wasm contract-state smart CW20_ICS20_CONTRACT_ADDRESS \'{  "config": {}}'

Parameters:

CW20_ICS20_CONTRACT_ADDRESS: The address of your CW20-ICS20 contract

Response: The query will return a JSON object containing the contract's configuration. For example:

{  "default_timeout": 3600,  "gov_contract": "archway1...governance_contract_address",  "default_gas_limit": 200000}

Response Fields:

default_timeout: The default timeout (in seconds) for IBC transfers if not specified in the transfer message
gov_contract: The address of the governance contract that has administrative rights over this contract
default_gas_limit: The default gas limit for contract calls, if set

Note:

The default_timeout is used when a transfer doesn't specify its own timeout.
The gov_contract is the address that has permission to update the contract's configuration, including allowing new tokens.
The default_gas_limit is an optional field. If present, it sets a default gas limit for contract calls. If not present, it means there's no default limit.

This configuration information is crucial for understanding the contract's behavior and operational parameters. It's particularly useful for administrators and developers working with the contract.

Admin

The Admin query retrieves information about the current administrator of the CW20-ICS20 contract.

To execute the Admin query, use the following command:

archwayd query wasm contract-state smart CW20_ICS20_CONTRACT_ADDRESS \'{  "admin": {}}'

Parameters:

CW20_ICS20_CONTRACT_ADDRESS: The address of your CW20-ICS20 contract

Response: The query will return a JSON object containing information about the contract's admin. For example:

{  "admin": "archway1...admin_address"}

Response Fields:

admin: The address of the current administrator of the contract. If this field is null, it means the contract has no admin.

Note:

The admin has special privileges, such as the ability to update the contract's configuration and allow new tokens.
If the admin is set to null, it means the contract is not upgradeable and certain administrative functions may be disabled.
This query is useful for verifying the current administrative control of the contract.

The admin plays a crucial role in the management and security of the contract. They have the authority to perform critical operations like updating the contract's configuration or transferring admin rights to another address.

Allowed

The Allowed query checks if a specific CW20 token contract is allowed for IBC transfers through this CW20-ICS20 contract.

To execute the Allowed query, use the following command:

archwayd query wasm contract-state smart CW20_ICS20_CONTRACT_ADDRESS \'{  "allowed": {    "contract": "TOKEN_CONTRACT_ADDRESS"  }}'

Parameters:

CW20_ICS20_CONTRACT_ADDRESS: The address of your CW20-ICS20 contract
TOKEN_CONTRACT_ADDRESS: The address of the CW20 token contract you want to check

Response: The query will return a JSON object containing information about whether the specified token is allowed and its gas limit. For example:

{  "is_allowed": true,  "gas_limit": 200000}

Response Fields:

is_allowed: A boolean value indicating whether the specified token is allowed (true) or not (false)
gas_limit: If the token is allowed, this field shows the gas limit set for operations with this token. If null, it means there's no specific gas limit for this token.

Note:

If the token is not allowed, the response will be null.
The gas limit, if set, applies to operations involving this specific token.
Only tokens that are explicitly allowed can be used for IBC transfers through this contract.

This query is useful for verifying which CW20 tokens can be used with the CW20-ICS20 contract for IBC transfers. It's particularly important for users and developers to check before attempting to initiate a transfer with a specific token.

ListAllowed

The ListAllowed query retrieves a list of all CW20 token contracts that are allowed for IBC transfers through this CW20-ICS20 contract, with optional pagination.

To execute the ListAllowed query, use the following command:

archwayd query wasm contract-state smart CW20_ICS20_CONTRACT_ADDRESS \'{  "list_allowed": {    "start_after": "OPTIONAL_START_AFTER_CONTRACT",    "limit": OPTIONAL_LIMIT  }}'

Parameters:

CW20_ICS20_CONTRACT_ADDRESS: The address of your CW20-ICS20 contract
OPTIONAL_START_AFTER_CONTRACT: (Optional) The contract address to start the list after (for pagination)
OPTIONAL_LIMIT: (Optional) The maximum number of entries to return

Response: The query will return a JSON object containing a list of allowed tokens and their gas limits. For example:

{  "allowed": [    {      "contract": "archway1...token1_address",      "gas_limit": 200000    },    {      "contract": "archway1...token2_address",      "gas_limit": null    }  ]}

Response Fields:

allowed: An array of objects, each representing an allowed token
- contract: The address of the allowed CW20 token contract
- gas_limit: The gas limit set for operations with this token. If null, it means there's no specific gas limit for this token.

Note:

If no start_after is provided, the list starts from the beginning.
If no limit is set, a default limit (often 10, but may vary) is usually applied.
The gas_limit being null means there's no specific limit set for that token.
This query is useful for getting an overview of all tokens that can be used with the CW20-ICS20 contract.

Pagination:

To paginate through all results, you can use the last contract address from the previous query as the start_after in the next query.
Continue this process until you receive an empty list, indicating you've reached the end of the allowed tokens.