Skip to content

Commit e66d19b

Browse files
LarkoooLarkooo
committed
feat(skill): add torii operator skill
1 parent a8b3476 commit e66d19b

File tree

5 files changed

+491
-0
lines changed

5 files changed

+491
-0
lines changed

‎.agents/skills/torii-operator/SKILL.md‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
---
2+
name: torii-operator
3+
description: Operate Torii (Dojo Starknet indexer) end-to-end: start and configure torii, explain and tune CLI/TOML options, verify protocol endpoints, and query indexed game data through SQL, gRPC, GraphQL, MCP, static artifact routes, metadata reindex, and metrics. Use when requests involve running torii, debugging indexing/query behavior, or extracting onchain game data from torii storage APIs.
4+
---
5+
6+
# Torii Operator
7+
8+
Execute this workflow to run and query Torii with source-accurate behavior.
9+
10+
## Workflow
11+
12+
1. Identify the user intent.
13+
- Start or tune indexer runtime.
14+
- Query existing indexed data.
15+
- Debug missing data, schema, endpoint, or performance issues.
16+
17+
2. Choose startup shape.
18+
- Use `references/startup-and-options.md` for bootstrapping, config files, and flags.
19+
- Favor explicit `--db-dir` for persistent state.
20+
- Confirm provider spec compatibility before deep debugging.
21+
22+
3. Validate service surfaces after startup.
23+
- Check HTTP root, GraphQL, SQL (if enabled), MCP, gRPC, and metrics (if enabled).
24+
- Use endpoint checks from `references/querying-and-interfaces.md`.
25+
26+
4. Choose query interface by task.
27+
- Use GraphQL for app-facing queries/subscriptions.
28+
- Use gRPC for typed retrieval/subscription/search/offchain publish.
29+
- Use SQL for direct investigation and schema-first debugging.
30+
- Use MCP when an MCP client needs schema/query tools.
31+
32+
5. Query safely.
33+
- Prefer read-only SQL for diagnostics.
34+
- Use schema discovery before writing complex SQL.
35+
- Treat `ExecuteSql` and `/sql` as privileged surfaces and confirm they are enabled.
36+
37+
6. Escalate to protocol-specific references.
38+
- Startup and options: `references/startup-and-options.md`
39+
- Interface usage and examples: `references/querying-and-interfaces.md`
40+
- Full gRPC RPC map: `references/grpc-rpcs.md`
41+
42+
## Source Of Truth
43+
44+
- CLI and defaults: `crates/cli/src/args.rs`, `crates/cli/src/options.rs`
45+
- Runtime wiring: `crates/runner/src/lib.rs`
46+
- HTTP proxy/handlers: `crates/server/src/proxy.rs`, `crates/server/src/handlers/`
47+
- GraphQL schema/runtime: `crates/graphql/src/schema.rs`, `crates/graphql/src/server.rs`
48+
- gRPC API: `crates/proto/proto/world.proto`, `crates/proto/proto/types.proto`, `crates/grpc/server/src/lib.rs`
49+
- Storage/search behavior: `crates/sqlite/sqlite/src/storage.rs`, `crates/migrations/`
50+

‎.agents/skills/torii-operator/agents/openai.yaml‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
interface:
2+
display_name: "Torii Operator"
3+
short_description: "Run Torii and query SQL, gRPC, GraphQL"
4+
default_prompt: "Use $torii-operator to run Torii, tune options, and query data over SQL, gRPC, GraphQL, and MCP."
5+

‎.agents/skills/torii-operator/references/grpc-rpcs.md‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
# gRPC RPC Map
2+
3+
Service: `world.World`
4+
5+
Use this as a quick RPC inventory. For field-level detail, inspect:
6+
- `crates/proto/proto/world.proto`
7+
- `crates/proto/proto/types.proto`
8+
9+
## World metadata and entity/model APIs
10+
11+
- `Worlds`
12+
- `RetrieveEntities`
13+
- `SubscribeEntities`
14+
- `UpdateEntitiesSubscription`
15+
- `RetrieveEventMessages`
16+
- `SubscribeEventMessages`
17+
- `UpdateEventMessagesSubscription`
18+
- `RetrieveEvents`
19+
- `SubscribeEvents`
20+
- `RetrieveControllers`
21+
- `RetrieveContracts`
22+
23+
## Token and transfer APIs
24+
25+
- `RetrieveTokens`
26+
- `SubscribeTokens`
27+
- `UpdateTokensSubscription`
28+
- `RetrieveTokenBalances`
29+
- `SubscribeTokenBalances`
30+
- `UpdateTokenBalancesSubscription`
31+
- `RetrieveTokenTransfers`
32+
- `SubscribeTokenTransfers`
33+
- `UpdateTokenTransfersSubscription`
34+
- `RetrieveTokenContracts`
35+
36+
## Transactions
37+
38+
- `RetrieveTransactions`
39+
- `SubscribeTransactions`
40+
41+
## Aggregations, activity, achievements
42+
43+
- `RetrieveAggregations`
44+
- `SubscribeAggregations`
45+
- `UpdateAggregationsSubscription`
46+
- `RetrieveActivities`
47+
- `SubscribeActivities`
48+
- `UpdateActivitiesSubscription`
49+
- `RetrieveAchievements`
50+
- `RetrievePlayerAchievements`
51+
- `SubscribeAchievementProgressions`
52+
- `UpdateAchievementProgressionsSubscription`
53+
54+
## Search and SQL
55+
56+
- `Search`
57+
- `ExecuteSql`
58+
59+
## Offchain messaging
60+
61+
- `PublishMessage`
62+
- `PublishMessageBatch`
63+

‎.agents/skills/torii-operator/references/querying-and-interfaces.md‎

Lines changed: 170 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,170 @@
1+
# Querying And Interfaces
2+
3+
## Contents
4+
5+
1. Quick health checks
6+
2. SQL over HTTP
7+
3. GraphQL
8+
4. gRPC
9+
5. MCP endpoint
10+
6. Static and metadata endpoints
11+
7. Metrics
12+
13+
## Quick health checks
14+
15+
```bash
16+
curl -s http://127.0.0.1:8080/
17+
```
18+
19+
Expected shape:
20+
- JSON with `service: "torii"` and `version`.
21+
22+
Check GraphQL route:
23+
24+
```bash
25+
curl -i http://127.0.0.1:8080/graphql
26+
```
27+
28+
Check gRPC reflection:
29+
30+
```bash
31+
grpcurl -plaintext 127.0.0.1:50051 list
32+
grpcurl -plaintext 127.0.0.1:50051 describe world.World
33+
```
34+
35+
## SQL over HTTP
36+
37+
HTTP SQL is available only if `--http.sql true` (default true).
38+
39+
Playground:
40+
41+
```bash
42+
open http://127.0.0.1:8080/sql
43+
```
44+
45+
GET query:
46+
47+
```bash
48+
curl -sG http://127.0.0.1:8080/sql \
49+
--data-urlencode 'query=SELECT id, world_address, created_at FROM entities LIMIT 5;'
50+
```
51+
52+
POST query body:
53+
54+
```bash
55+
curl -s http://127.0.0.1:8080/sql \
56+
-X POST \
57+
--data 'SELECT id, transaction_hash, executed_at FROM events ORDER BY executed_at DESC LIMIT 10;'
58+
```
59+
60+
## GraphQL
61+
62+
Endpoint: `http://127.0.0.1:8080/graphql`
63+
64+
Common root query fields:
65+
- `entity`, `entities`
66+
- `eventMessage`, `eventMessages`
67+
- `event`, `events`
68+
- `model`, `models`
69+
- `transaction`, `transactions`
70+
- `controller`, `controllers`
71+
- `tokenBalances`, `tokenTransfers`, `tokens`
72+
- `metadata`, `metadatas`
73+
- Dynamic model resolvers generated from indexed model schema
74+
75+
Mutation:
76+
- `publishMessage(worldAddress, signature, message)`
77+
78+
Subscriptions:
79+
- `entityUpdated`
80+
- `eventMessageUpdated`
81+
- `eventEmitted`
82+
- `modelRegistered`
83+
- `tokenBalanceUpdated`
84+
- `tokenUpdated`
85+
- `transaction`
86+
87+
Example query:
88+
89+
```bash
90+
curl -s http://127.0.0.1:8080/graphql \
91+
-H 'content-type: application/json' \
92+
-d '{
93+
"query":"query { entities(first: 3) { totalCount edges { node { id keys } } } }"
94+
}'
95+
```
96+
97+
## gRPC
98+
99+
Endpoint: `127.0.0.1:50051`
100+
101+
List and inspect:
102+
103+
```bash
104+
grpcurl -plaintext 127.0.0.1:50051 list world.World
105+
grpcurl -plaintext 127.0.0.1:50051 describe world.World
106+
```
107+
108+
Example calls:
109+
110+
```bash
111+
grpcurl -plaintext -d '{}' 127.0.0.1:50051 world.World/Worlds
112+
113+
grpcurl -plaintext -d '{
114+
"query": "SELECT id, world_address FROM entities LIMIT 5;"
115+
}' 127.0.0.1:50051 world.World/ExecuteSql
116+
117+
grpcurl -plaintext -d '{
118+
"query": { "query": "dragon", "limit": 10 }
119+
}' 127.0.0.1:50051 world.World/Search
120+
```
121+
122+
Notes:
123+
- `ExecuteSql` is blocked when `--http.sql false`.
124+
- gRPC supports compressed messages and gRPC-Web in server config.
125+
- Use `torii-grpc-client` or `torii-client` crates for typed Rust integration.
126+
127+
## MCP endpoint
128+
129+
Routes:
130+
- WebSocket/SSE entry: `/mcp`
131+
- SSE message endpoint: `/mcp/message?sessionId=...`
132+
133+
Built-in tools:
134+
- `query` tool: run SQL and return JSON text payload
135+
- `schema` tool: return table/column schema (`sqlite_master` + `pragma_table_info`)
136+
137+
Use MCP for agent-driven DB inspection when raw SQL schema discovery is needed.
138+
139+
## Static and metadata endpoints
140+
141+
Static token/contract image serving:
142+
- `/static/{contract_address}/image`
143+
- `/static/{contract_address}/{token_id}/image`
144+
145+
Optional image sizing query params:
146+
- `?h=...&w=...` (aliases: `height`, `width`)
147+
148+
Metadata reindex endpoint:
149+
- `/metadata/reindex/{contract_address}/{token_id}`
150+
151+
Use metadata reindex to force refresh token metadata from chain and persist updates.
152+
153+
## Metrics
154+
155+
Enable metrics:
156+
157+
```bash
158+
torii --metrics --metrics.addr 0.0.0.0 --metrics.port 9200
159+
```
160+
161+
Query:
162+
163+
```bash
164+
curl -s http://127.0.0.1:9200/metrics | head
165+
```
166+
167+
For Grafana/Prometheus setup, use:
168+
- `docker-compose -f docker-compose.grafana.yml up -d`
169+
- `docs/grafana-setup.md`
170+

0 commit comments

Comments
 (0)