# Cross-Chain Queries (ICQ)

BitBadges supports Interchain Queries (ICQ) that allow other Cosmos chains to verify token ownership without transferring tokens. This enables cross-chain gating, proof-of-ownership, and other interoperability use cases.

## Overview

The ICQ system provides two main query types:

1. **OwnershipQuery**: Streamlined lookup for a single (tokenId, ownershipTime) combination - returns the exact balance amount
2. **FullBalanceQuery**: Returns the complete UserBalanceStore including all balances, approvals, and permissions

Tokens remain in the BitBadges "silo" - for value transfer across chains, use the wrapping mechanism to convert to standard IBC-transferable tokens (BADGE, ATOM, etc).

## Packet Types

### OwnershipQueryPacket

Query the balance amount for a specific token ID and ownership time.

| Field            | Type   | Description                                                             |
| ---------------- | ------ | ----------------------------------------------------------------------- |
| `query_id`       | string | Unique identifier for correlation                                       |
| `address`        | string | Address to check (bech32 or 0x hex)                                     |
| `collection_id`  | string | Collection ID to query                                                  |
| `token_id`       | string | Single token ID to check (uint as string)                               |
| `ownership_time` | string | Single ownership time to check (uint as string, typically ms timestamp) |

### OwnershipQueryResponsePacket

Response with ownership verification result.

| Field           | Type   | Description                                                     |
| --------------- | ------ | --------------------------------------------------------------- |
| `query_id`      | string | Correlation ID from request                                     |
| `owns_tokens`   | bool   | True if total\_amount > 0                                       |
| `total_amount`  | Uint   | Exact balance amount for the specified (tokenId, ownershipTime) |
| `balance_proof` | bytes  | Optional IAVL Merkle proof                                      |
| `proof_height`  | uint64 | Block height at which response was generated                    |
| `error`         | string | Error message (empty on success)                                |

### FullBalanceQueryPacket

Query the complete balance store for a user (balances, approvals, permissions).

| Field           | Type   | Description                         |
| --------------- | ------ | ----------------------------------- |
| `query_id`      | string | Unique identifier for correlation   |
| `address`       | string | Address to check (bech32 or 0x hex) |
| `collection_id` | string | Collection ID to query              |

### FullBalanceQueryResponsePacket

Response with the complete UserBalanceStore.

| Field           | Type   | Description                                  |
| --------------- | ------ | -------------------------------------------- |
| `query_id`      | string | Correlation ID from request                  |
| `balance_store` | bytes  | Serialized UserBalanceStore (protobuf bytes) |
| `proof_height`  | uint64 | Block height at which response was generated |
| `error`         | string | Error message (empty on success)             |

The `balance_store` contains:

* `balances` - List of Balance objects (amount, tokenIds ranges, ownershipTimes ranges)
* `outgoingApprovals` - Outgoing transfer approvals
* `incomingApprovals` - Incoming transfer approvals
* `autoApproveSelfInitiatedOutgoingTransfers` - Auto-approve setting
* `autoApproveSelfInitiatedIncomingTransfers` - Auto-approve setting
* `autoApproveAllIncomingTransfers` - Auto-approve setting
* `userPermissions` - User's permissions

### Bulk Queries

`BulkOwnershipQueryPacket` and `BulkOwnershipQueryResponsePacket` allow querying multiple addresses in a single IBC packet (max 100 queries).

## IBC Channel Setup

* **Port:** `tokenization`
* **Version:** `tokenization-1`
* **Channel Ordering:** `UNORDERED`

## Example Usage

### Simple Ownership Check (Single ID/Time)

```go
// Create ownership query packet for a single token ID and time
query := &types.OwnershipQueryPacket{
    QueryId:       "my-query-123",
    Address:       "bb1abc...",      // or "0x..." format
    CollectionId:  "5",
    TokenId:       "1",              // Single token ID
    OwnershipTime: "1609459200000",  // Single timestamp (ms)
}

// Wrap in packet data
packetData := &types.TokenizationPacketData{
    Packet: &types.TokenizationPacketData_OwnershipQuery{
        OwnershipQuery: query,
    },
}

// Send via IBC channel to BitBadges
// Response contains exact balance amount for that token/time
```

### Full Balance Store Query

```go
// Create full balance query packet
query := &types.FullBalanceQueryPacket{
    QueryId:      "my-query-456",
    Address:      "bb1abc...",
    CollectionId: "5",
}

// Wrap in packet data
packetData := &types.TokenizationPacketData{
    Packet: &types.TokenizationPacketData_FullBalanceQuery{
        FullBalanceQuery: query,
    },
}

// Send via IBC channel to BitBadges
// Response contains serialized UserBalanceStore with all data
```

## Use Cases

* **Cross-chain token gating:** Verify badge ownership before allowing access on another chain
* **DeFi collateral verification:** Prove token ownership without transferring
* **Multi-chain identity:** Use BitBadges tokens as credentials across Cosmos ecosystem
* **Governance:** Weight votes based on token holdings verified via ICQ
* **Cross-chain approval checking:** Query full balance store to check approval status


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.bitbadges.io/for-developers/bitbadges-blockchain/cross-chain-queries.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.