This site requires Javascript to be enabled.

Query data

Your CW20 token contract provides various query operations to retrieve information about the token and its state. To perform a query, we use the "smart" mode of the contract-state query. This approach enables us to send specific arguments to the contract, allowing for targeted information retrieval without downloading entire datasets or metadata.

The general structure for querying your CW20 token is:

archway contracts query-smart <contract-address> --args '<query_message>'

Replace:

  • <contract-address> with your token contract's address
  • <query_message> with the specific query message in JSON format

Different query types provide access to various aspects of your token's state and configuration. In the following sections, we'll explore some of the most common query operations available for your CW20 token.

Important notes:

  • Queries do not modify the contract state and do not require gas fees.
  • The response format will depend on the specific query type.
  • You can use queries to build interfaces, monitor token activity, or verify contract state.

Balance query

One of the most common queries for CW20 tokens is checking the balance of a specific account. Here's how to perform this query:

archway contracts query smart <contract-name> --args '{
  "balance": {
    "address": "archway1..."
  }
}'

Replace:

  • <contract-name> with your token contract's name
  • archway1... with the address you want to check the balance for

Example output:

{
  "balance": "1000000"
}

Understanding the query structure

The query structure {"balance": {"address": "archway1..."}} corresponds to the contract's internal logic for handling queries. Let's break this down:

  1. In src/contract.rs, you'll find the main query function:
pub fn query(deps: Deps, _env: Env, msg: QueryMsg) -> StdResult<Binary> {  match msg {    QueryMsg::Balance { address } => to_binary(&query_balance(deps, address)?),    // other cases...  }}
  1. The QueryMsg enum in src/msg.rs defines all possible query types, including Balance.
  2. The #[serde(rename_all = "snake_case")] attribute ensures that enum variants like Balance are converted to "balance" in JSON, matching the contract's expectations.

Token info

The Token Info query retrieves essential information about your CW20 token, including its name, symbol, decimals, and total supply. This query is crucial for understanding the basic configuration and current state of your token.

To execute a Token Info query, use the following command:

archway contracts query smart <contract-name> --args '{
  "token_info": {}
}'

Replace <contract-name> with your token contract's name.

Example output:

{  "name": "My CW20 Token",  "symbol": "MCT",  "decimals": 6,  "total_supply": "1000000000000"}

Important notes:

  • The name field shows the full name of your token.
  • The symbol is the ticker used to represent your token.
  • decimals indicates the number of decimal places used for token amounts.
  • total_supply represents the current total number of tokens in circulation.

This query is particularly useful for:

  • Displaying token information in wallets or interfaces
  • Verifying token configuration
  • Monitoring the total supply of tokens

Allowance

The Allowance query allows you to check the amount of tokens that an owner has permitted a spender to use on their behalf. This query is essential for managing and verifying permissions in token transactions, particularly in scenarios involving delegated spending.

To execute an Allowance query, use the following command:

archway contracts query smart <contract-name> --args '{
  "allowance": {
    "owner": "<owner_address>",
    "spender": "<spender_address>"
  }
}'

Replace:

  • <contract-name> with your token contract's name
  • <owner_address> with the address of the token owner
  • <spender_address> with the address of the account granted the allowance

Example output:

{  "allowance": "1000000",  "expires": {    "never": {}  }}

Important notes:

  • The allowance field shows the current amount the spender is allowed to use.
  • The expires field indicates when the allowance expires, if applicable.
  • If no allowance has been set, the query will return zero.
  • This query does not modify the contract state or require gas fees.

Use cases for the Allowance query include:

  • Checking remaining allowance before executing a transfer_from operation
  • Verifying permissions granted to third-party services or smart contracts
  • Monitoring delegated spending limits in decentralized applications

All accounts

The All Accounts query retrieves a list of all addresses that currently hold your CW20 token. This query is particularly useful for applications that need to display or audit token distribution across all holders.

To execute an All Accounts query, use the following command:

archway contracts query smart <contract-name> --args '{
  "all_accounts": {
    "start_after": "<optional_address>",
    "limit": <optional_number>
  }
}'

Replace:

  • <contract-name> with your token contract's name
  • <optional_address> (optional) with an address to start the list after
  • <optional_number> (optional) with the maximum number of accounts to return

Example:

archway contracts query smart archway1... --args '{
  "all_accounts": {
    "limit": 10
  }
}'

Example output:

{  "accounts": [    "archway1...",    "archway2...",    "archway3...",    ...  ]}

Important notes:

  • This query can potentially return a large amount of data, especially for tokens with many holders.
  • Use the start_after and limit parameters to paginate through results if needed.
  • The accounts are typically returned in lexicographical order of their addresses.
  • This query does not provide balance information; use it in conjunction with individual balance queries if needed.

Use cases for the All Accounts query include:

  • Generating token holder reports
  • Implementing governance features based on token ownership
  • Analyzing token distribution patterns

Minter

The Minter query retrieves information about the current minter of your CW20 token. This query is essential for understanding who has control over the token minting process and any associated caps on token creation.

To execute a Minter query, use the following command:

archway contracts query smart <contract-address> --args '{
  "minter": {}
}'

Replace <contract-address> with your token contract's address.

Example output:

{  "minter": "archway1...",  "cap": "1000000000000"}

Important notes:

  • The minter field shows the address currently authorized to mint new tokens.
  • The cap field, if present, indicates the maximum number of tokens that can be minted.
  • If minting is not enabled for the token, this query might return null or an empty response.
  • This query does not modify the contract state or require gas fees.

Use cases for the Minter query include:

  • Verifying the current minting authority
  • Checking the remaining mintable supply (by comparing the cap with the current total supply)
  • Ensuring transparency in token issuance policies