Torii
Torii is the official indexing engine for Dojo worlds, designed to provide real-time synchronization between on-chain game state and client applications. Built in Rust for performance and reliability, Torii automatically tracks all changes to your game's Entity Component System (ECS) data and makes it accessible through multiple API interfaces.
Architecture Overview
Core Components
Torii operates as a multi-layered system that bridges the gap between Starknet blockchain data and client applications:
Indexing Engine: The core component that continuously monitors the blockchain for events related to your Dojo world. It processes transactions, extracts ECS state changes, and maintains a synchronized local database.
Storage Layer: A high-performance SQLite database that stores indexed world state, including entities, models, events, and metadata. The database schema is dynamically generated based on your world's model definitions.
API Layer: Multiple interfaces for accessing indexed data:
- GraphQL API: Provides a flexible, typed interface with real-time subscriptions
- gRPC API: High-performance binary protocol for efficient data fetching
- SQL Endpoint: Direct database access for custom queries
Data Flow
- World Introspection: Torii automatically discovers your world's structure by reading model and system registrations from the World contract
- Event Processing: Monitors for Dojo-specific events (
StoreSetRecord
,StoreUpdateRecord
,StoreDelRecord
, etc.) and ERC token transfers - ECS Synchronization: Translates blockchain events into ECS entity and component updates
- Real-time Broadcasting: Propagates changes to connected clients via GraphQL subscriptions
Scaling and Performance
Torii is designed for production deployment with several performance optimizations:
- Parallel Processing: Events are processed concurrently using a task manager system
- Efficient Batching: Blockchain data is fetched in configurable chunks to optimize RPC usage
- Caching Layer: In-memory caches reduce database load and improve query performance
- Database Optimization: Configurable indices and query optimization for large datasets
Getting Started
Quick Start
Torii leverages world introspection to bootstrap directly from an on-chain deployment:
torii --world <WORLD_ADDRESS>
This starts Torii with default settings:
- GraphQL API at
http://localhost:8080/graphql
- gRPC API at
http://localhost:8080
- In-memory database (for development)
Production Configuration
For production deployments, use persistent storage and custom configuration:
torii --world <WORLD_ADDRESS> --db-dir ./torii-db --config torii_prod.toml
Installation
Torii can be installed via dojoup
, our dedicated package manager:
curl -L https://install.dojoengine.org | bash
# Restart your terminal
dojoup install
Installing with asdf
If you prefer to install with the asdf
version manager:
asdf plugin add torii https://github.com/dojoengine/asdf-torii.git
asdf install torii latest
Building from Source
If you prefer to build from the source code:
git clone https://github.com/dojoengine/torii.git
cargo install --path ./torii/bin/torii --profile local --force
Next Steps
- Configuration Guide: Learn how to configure Torii with TOML files and CLI arguments
- GraphQL API: Explore the GraphQL interface for flexible data queries
- gRPC API: Use the high-performance gRPC interface