Ibis Query

Ibis Natural Language Query Skill

Translate natural language questions about Starknet indexed data into REST API curl commands (preferred) or ibis query CLI commands (fallback).

When to Use

Activate when the user asks a question about indexed blockchain data, such as:

• "Who has the highest score?"
• "Show me all transfers above 1000 STRK"
• "How many swaps happened in the last hour?"
• "What's the total trading volume?"
• "List all factory children"
• "What contracts were deployed by the factory?"
• "What's the current token price?" (view function)
• "What contracts were discovered?" (discovery)
• "Stream new transfer events" (SSE)

Workflow

Step 1: Discover Available Data

Before constructing a query, understand what data is indexed. Determine the API base URL from the config:

Base URL: http://{api.host}:{api.port}/v1
Default:  http://localhost:8080/v1

Method A — Call the status endpoint (preferred when API server is running):

curl -s http://localhost:8080/v1/status | jq .

This returns all contracts (with cursor positions), factory summaries (child counts, sync status), and view function statuses (last poll time, errors). It is the single best source of truth.

Method B — Run ibis query --list (when ibis binary is installed but API may not be running):

ibis query --list

Method C — Read the config file directly (fallback):

bash ~/.claude/skills/ibis-query/scripts/inspect_config.sh

From discovery, extract:

• Contract names and addresses
• Event names and table types (log, unique, aggregation)
• View functions (contract + function name → view table)
• Factory configurations and child counts
• Discovery configs (class hashes being watched)

Step 2: Map the Question to a Query

Consult the full reference at references/query_reference.md for detailed syntax.

Identify the contract and event. The user may use informal names. Map them to the exact contract and event names from the config. Table names are lowercase(contract_event).

Identify the query type:

Identify filters from natural language:

Identify ordering:

Identify limits:

Step 3: Construct and Execute the Query

Build a curl command targeting the ibis REST API. Default to jq for readable output.

Command template:

curl -s "http://localhost:8080/v1/{contract}/{event}?limit=N&offset=N&order=field.dir&field=op.value" | jq .

SSE streaming template:

curl -N "http://localhost:8080/v1/{contract}/{event}/stream"

With replay from a known position:

curl -N -H "Last-Event-ID: 850000:3" "http://localhost:8080/v1/{contract}/{event}/stream"

CLI fallback (when API server is not running):

ibis query <Contract> <Event> [--limit N] [--offset N] [--order field.dir] [--filter "field=op.value"] [--unique|--aggregate|--latest|--count] [--format table]

Execute the command via Bash and present the results.

Step 4: Present Results with Context

After receiving query output:

• Summarize the key findings in natural language
• Highlight the answer to the user's question
• If the result set is large, point out notable entries
• If no results are found, suggest adjusting filters or checking the config

Step 5: Handle Follow-ups

For follow-up questions, reuse the discovered schema context. Common patterns:

• "Show me more" → increase limit or add offset
• "Sort by X instead" → change order parameter
• "Only show confirmed" → add &status=eq.ACCEPTED_L2
• "What about contract 0x...?" → add &contract_address=eq.0x...
• "Stream those instead" → switch to /stream endpoint
• "What's the current value?" → switch to view table query

View Function Tables

View tables store results from periodic on-chain function calls (e.g., total_supply, get_price). They differ from event tables:

• Table naming: {contract}_{function} (e.g., mytoken_total_supply)
• Metadata columns: block_number, timestamp, contract_address, _view_key
• Missing columns: View tables do NOT have transaction_hash, log_index, event_name, or status
• _view_key: Synthetic key column. For unique view tables, deduplicates to latest polled value. For log view tables, every poll result is appended.

Query view tables the same way as event tables — they use the same REST endpoints:

# Latest polled value
curl -s "http://localhost:8080/v1/Oracle/get_price?order=block_number.desc&limit=1" | jq .

# Current unique value (if view table is unique type)
curl -s "http://localhost:8080/v1/Oracle/get_price/unique" | jq .

# Historical values
curl -s "http://localhost:8080/v1/MyToken/total_supply?order=block_number.asc&limit=100" | jq .

Filter/order view tables by: block_number, timestamp, contract_address, _view_key, plus any decoded view output fields.

Discovery Queries

Discovery mode watches for UDC ContractDeployed events matching specific class hashes and auto-registers new contracts.

Check discovered contracts:

curl -s "http://localhost:8080/v1/discover/0x{classHash}/contracts" | jq .

Response includes each discovered contract's address, deployment_block, current_block, and status (active/syncing/error/backfilling).

Discovery endpoints return contract metadata, not event data. If the user asks about data FROM discovered contracts, query those contracts' event/view tables instead.

SSE Streaming

For real-time event watching, use the /stream endpoint:

# Stream all new Transfer events
curl -N "http://localhost:8080/v1/Token/Transfer/stream"

# Stream with filters
curl -N "http://localhost:8080/v1/Token/Transfer/stream?from_address=eq.0x..."

# Resume from a known position
curl -N -H "Last-Event-ID: 850000:3" "http://localhost:8080/v1/Token/Transfer/stream"

Event format:

id: {block_number}:{log_index}
data: {"block_number":850001,"transaction_hash":"0x...","from_address":"0x...","amount":"1000"}

Filters (eq and neq operators) are applied to both replayed and live events.

Shared Tables

Factory children, discovered contracts, and admin-registered contracts can all use shared tables. Shared tables add a contract_name column for disambiguation.

Filter by specific child contract:

curl -s "http://localhost:8080/v1/DEX/Swap?contract_address=eq.0x..." | jq .

Event Table Metadata Columns

Every event table always contains these columns (available for filtering/ordering):

• block_number — block height (uint64)
• transaction_hash — tx hash (string)
• log_index — position within block (uint64)
• timestamp — block timestamp as unix epoch (uint64)
• contract_address — source contract (string)
• event_name — event type name (string)
• status — confirmation status: PRE_CONFIRMED, ACCEPTED_L2, or ACCEPTED_L1
• contract_name — (shared tables only) which child contract emitted the event

Table Types

• log — Append-only event log. Every emission is stored. Default query type.
• unique — Last-write-wins by unique_key. Query /unique endpoint to get current state per key.
• aggregation — Auto-computed sums/counts/averages. Query /aggregate endpoint to get computed values.

Example Query Mappings

Important Notes

• REST API is preferred — output curl commands unless the user specifically asks for CLI or the API server is not running
• Table names are lowercase(ContractName_EventName) — the API accepts the original casing in URL paths
• Filter values for felt252/address fields must be hex strings starting with 0x
• Multiple filters combine with AND logic: ?field1=op.value1&field2=op.value2
• Factory children queries only need the factory contract name (no event name)
• For shared tables, use ?contract_address=eq.0x... to filter by specific child
• View tables use _view_key instead of event_name and lack transaction_hash/log_index/status
• SSE streaming supports eq and neq filter operators; numeric operators are ignored on replay
• The /v1/status endpoint is the best way to understand what data is available

Source: nagmo-starkware/Ibis — distributed by TomeVault.