# Queries — reading chain state

Everything here is read-only. No keys needed, no fees paid, safe to run freely. Use `-o json | jq` to make output script-friendly.

For a session, set:
```bash
RPC=https://juno-rpc.publicnode.com:443     # juno-1 mainnet
# or: RPC=https://juno-testnet-rpc.polkachu.com   # uni-7 testnet
```

All commands below assume `RPC` is exported.

## Bank — balances and supply

```bash
# All balances of an address
junod query bank balances juno1<addr> --node $RPC -o json | jq

# A specific denom's balance
junod query bank balance juno1<addr> ujuno --node $RPC

# Total supply of all denoms
junod query bank total --node $RPC -o json | jq

# Total supply of one denom
junod query bank total --denom ujuno --node $RPC

# Denom metadata (display name, decimals, etc.)
junod query bank denom-metadata --node $RPC -o json | jq
```

## Staking — validators, delegations, rewards

```bash
# All validators (active + jailed + unbonding)
junod query staking validators --node $RPC -o json | jq '.validators[] | {moniker: .description.moniker, status, tokens, operator_address}'

# One validator
junod query staking validator junovaloper1<addr> --node $RPC -o json | jq

# Delegations from one delegator
junod query staking delegations juno1<delegator> --node $RPC -o json | jq

# Delegations TO one validator
junod query staking delegations-to junovaloper1<addr> --node $RPC -o json | jq '.delegation_responses | length'

# Unbonding delegations (in-flight unstakes)
junod query staking unbonding-delegations juno1<delegator> --node $RPC -o json | jq

# Staking pool (total bonded / unbonded)
junod query staking pool --node $RPC

# Reward queries (under x/distribution, not x/staking)
junod query distribution rewards juno1<delegator> --node $RPC -o json | jq
junod query distribution rewards juno1<delegator> junovaloper1<validator> --node $RPC
```

## Governance (chain-level, x/gov)

This is the Cosmos SDK governance module — chain upgrades, param changes. **Not DAO DAO** (that's CosmWasm contracts; see `dao-dao.md`).

```bash
# List proposals
junod query gov proposals --node $RPC -o json | jq '.proposals[] | {id: .id, title: .title, status}'

# Filter by status: PROPOSAL_STATUS_VOTING_PERIOD / PASSED / REJECTED / DEPOSIT_PERIOD
junod query gov proposals --status PROPOSAL_STATUS_VOTING_PERIOD --node $RPC

# One proposal
junod query gov proposal 42 --node $RPC -o json | jq

# Current tally on a proposal
junod query gov tally 42 --node $RPC

# How a specific delegator voted
junod query gov vote 42 juno1<voter> --node $RPC

# All votes on a proposal (paginated)
junod query gov votes 42 --node $RPC -o json | jq
```

## Wasm — CosmWasm contracts

The key insight: a CosmWasm contract is an account (a `juno1...` address) with code attached. Querying it is free.

```bash
# List all uploaded code (paginated)
junod query wasm list-code --reverse --limit 20 --node $RPC -o json | jq '.code_infos[] | {code_id, creator, data_hash}'

# Info about one code ID
junod query wasm code-info 4862 --node $RPC -o json | jq

# Contracts instantiated from a code ID
junod query wasm list-contract-by-code 4862 --reverse --limit 20 --node $RPC

# Info about one contract (creator, admin, label, code_id)
junod query wasm contract juno1<contract-addr> --node $RPC -o json | jq

# Smart query (calls the contract's QueryMsg)
junod query wasm contract-state smart juno1<contract-addr> \
  '{"config":{}}' --node $RPC -o json | jq

# Raw state (key-value, advanced — needs to know the storage layout)
junod query wasm contract-state all juno1<contract-addr> --node $RPC -o json | jq
junod query wasm contract-state raw juno1<contract-addr> <hex-key> --node $RPC
```

**Smart queries are JSON.** Construct them per the contract's QueryMsg schema:

```bash
# A typical DAO DAO query
junod query wasm contract-state smart $PROPOSAL_MODULE \
  '{"list_proposals":{"limit":10}}' --node $RPC -o json | jq

# cw20 balance
junod query wasm contract-state smart $CW20_TOKEN \
  '{"balance":{"address":"juno1..."}}' --node $RPC

# cw4-group member
junod query wasm contract-state smart $CW4_GROUP \
  '{"member":{"addr":"juno1..."}}' --node $RPC
```

Schema discovery — see [`cosmwasm.md`](cosmwasm.md).

## IBC

```bash
# Channels (paginated)
junod query ibc channel channels --node $RPC -o json | jq '.channels[] | {channel_id, port_id, state, counterparty}'

# One channel
junod query ibc channel end transfer channel-1 --node $RPC -o json | jq

# Connections
junod query ibc connection connections --node $RPC -o json | jq

# Denom traces — what an IBC denom decodes to
junod query ibc-transfer denom-traces --node $RPC -o json | jq

# Single denom hash → path lookup
junod query ibc-transfer denom-trace 'C4CFF46FD6...' --node $RPC

# Reverse: path → hash
junod query ibc-transfer denom-hash 'transfer/channel-1/uatom' --node $RPC
```

## Transactions — search by hash or event

```bash
# By hash
junod query tx <HASH> --node $RPC -o json | jq

# By events (search-tx) — slow on public RPCs, beware
junod query txs --events "transfer.recipient=juno1..." --node $RPC -o json | jq

# Newer SDK versions use --query syntax:
junod query txs --query "transfer.recipient='juno1...'" --node $RPC -o json | jq
```

For high-throughput tx queries (e.g., "all txs to this DAO this week"), the canonical answer is **an indexer**, not the RPC. See the `dao-dao-ui` indexer-proxy or the indexer.daodao.zone service.

## Account / authn

```bash
# Account info (sequence, account number, pubkey, vesting schedule if any)
junod query account juno1<addr> --node $RPC -o json | jq

# What this returns:
# - .account_number: the chain's internal account ID (used in signing)
# - .sequence: the next nonce for this account
# - .pub_key: revealed pubkey (null if account hasn't sent any txs yet)
```

If `.pub_key` is `null`, the account exists but has never signed anything. Common for fresh addresses that have only received inbound transfers.

## Status / health checks

```bash
# RPC status (chain-id, latest block, sync state)
curl -sS $RPC/status | jq

# Node info (validator pubkey, p2p info, etc.) — RPC endpoint
curl -sS $RPC/net_info | jq

# Block at height
junod query block --height <H> --node $RPC -o json | jq

# Block by hash
junod query block --type=hash <HASH> --node $RPC
```

For monitoring: `curl $RPC/status` returns in <100ms when healthy. A 5-second timeout on this is a good liveness gate before launching a sequence of txs.

## Module params

When you need to know the chain's current params (gas, slashing, gov thresholds):

```bash
junod query gov params --node $RPC -o json | jq
junod query staking params --node $RPC -o json | jq
junod query slashing params --node $RPC -o json | jq
junod query feemarket params --node $RPC -o json | jq
junod query mint params --node $RPC -o json | jq
junod query distribution params --node $RPC -o json | jq
```

These rarely change (governance acts), but when they do, they affect every subsequent tx. Worth re-checking `feemarket params` before a large signing batch.

## Pagination

Most list queries paginate with `--limit N` and `--page N` (or `--page-key <next-key>`). Default page size is 100. For exhaustive lists:

```bash
junod query staking validators --node $RPC --limit 200 --page 1 -o json
junod query staking validators --node $RPC --limit 200 --page 2 -o json
# ... until .pagination.next_key is null
```

For most reads, the default page size is plenty.

## Performance notes

- Public RPCs have rate limits (~10–60 req/sec typical). If you're scripting heavy reads, throttle or run a local node.
- `wasm contract-state smart` queries are billed at zero gas but consume CPU on the node. Polite throttle: sleep 0.1s between hot-loop queries.
- The `RPC/abci_query` raw path is what `junod query` uses internally — directly hitting it is faster for high-throughput pipelines but loses the human-readable formatting.