Configuration Guide

Torii supports TOML configuration files for complex deployments. Configuration provides structured control over indexing, performance, security, and monitoring settings.

Configuration Priority

Configuration follows the standard priority order used across Dojo toolchain components:

Command-line arguments (highest)
Configuration file (via --config)
Environment variables
Default values (lowest)

CLI Usage

Most configuration options can be passed as command-line arguments:

# Basic usage
torii --world 0x1234...
 
# Configuration options via CLI
torii --world 0x1234... \
  --http.cors_origins "*" \
  --indexing.controllers \
  --indexing.polling_interval 1000
 
# Using configuration file (recommended for complex setups)
torii --config torii_prod.toml
 
# See command-line options
torii --help

For complex deployments, using a configuration file is recommended over lengthy command lines.

TOML Configuration

Basic Configuration

Basic settings for getting Torii running:

world_address = "0x01b2e..."            # World contract to index (optional as of Torii 1.6.1). Can also be passed in the list of contracts.
 
rpc = "http://0.0.0.0:5050"     # Sequencer RPC endpoint (default: http://0.0.0.0:5050)
 
db_dir = "torii.db"             # Persistent database (omit for in-memory)

Runner Configuration

Development and runtime options:

[runner]
explorer = false              # Open World Explorer in browser (default: false)
check_contracts = false       # Verify contracts before starting (default: false)

Indexing Configuration

Control what data to index and how:

[indexing]
# Contracts to index
contracts = [
    "WORLD:0xab931...",
    "WORLD:0xc34da...",
    "ERC20:0x023f8e...",
    "ERC721:0xfe8a1...",
]
 
# Content selection
pending = false                 # Include pending transactions
transactions = true             # Store transaction data
namespaces = ["game", "market"] # Specific namespaces only (empty = all)
models = ["Position", "Move"]   # Specific models only (empty = all)
world_block = 0                 # Starting block number (default: 0)
 
# Performance tuning
events_chunk_size = 1024        # Events per RPC request (default: 1024)
blocks_chunk_size = 10240       # Blocks per DB commit (default: 10240)
polling_interval = 500          # Check interval in ms (default: 500)
max_concurrent_tasks = 100      # Parallel processing (default: 100)
 
# Advanced options
controllers = true              # Index Cartridge controllers (default: false)
strict_model_reader = false     # Read models from registration block (default: false)
batch_chunk_size = 1024         # Batch request chunk size (default: 1024)
 
[events]
raw = false                     # Store raw blockchain events (dev only)

ERC Configuration

Token indexing settings:

[erc]
max_metadata_tasks = 100    # Concurrent metadata tasks (default: 100)
 
# Optional: ERC artifacts storage
artifacts_path = "/path/to/artifacts"

SQL Configuration

SQLite performance and indexing settings:

[sql]
page_size = 32768              # Page size in bytes (default: 32768, range: 512-65536)
cache_size = -500000           # Cache size: negative = KiB, positive = pages (default: -500MB)
all_model_indices = false      # Auto-create all indices (resource intensive)
 
# Database performance tuning
wal_autocheckpoint = 10000     # Pages interval for autocheckpoint (default: 10000)
busy_timeout = 60000           # Database busy timeout in ms (default: 60000)
 
# Historical data retention
historical = ["game-Battle", "market-Trade"]
 
# SQL hooks for events (format: "event:data:statement")
hooks = []
 
# Optional: Custom migrations directory
migrations = "/path/to/migrations"
 
# Custom indices for specific model queries
# Spatial queries
[[sql.model_indices]]
model_tag = "game-Position"
fields = ["external_x", "external_y"]
# Leaderboards
[[sql.model_indices]]
model_tag = "game-Player"
fields = ["external_score", "external_level"]

Snapshot Configuration

Snapshot loading options:

[snapshot]
# Optional: Snapshot URL and version
url = "https://example.com/snapshot.tar.gz"
version = "1.0.0"

Metrics Configuration

Prometheus metrics and observability. If enabled, metrics will be served at the /metrics endpoint.

[metrics]
metrics = true                  # Enable /metrics endpoint
metrics_addr = "127.0.0.1"      # Metrics server address
metrics_port = 9200             # Metrics port

Server Configuration

HTTP API and network settings:

[server]
http_addr = "127.0.0.1"      # Listen address (default: 127.0.0.1)
http_port = 8080             # API port
http_cors_origins = [ "*" ]  # CORS allowed origins
 
# Optional: HTTPS with TLS certificates
tls_cert_path = "/etc/ssl/torii.crt"
tls_key_path = "/etc/ssl/torii.key"

P2P Relay Configuration

Multi-region synchronization and relay:

[relay]
port = 9090                   # TCP/UDP QUIC port
webrtc_port = 9091            # WebRTC port
websocket_port = 9092         # WebSocket port
peers = []                    # List of peer relay addresses
 
# Identity and certificates
local_key_path = "/etc/torii/identity.key"
cert_path = "/etc/torii/webrtc.cert"

Timestamp validation for P2P messaging and cross-chain communication:

[messaging]
max_age = 300                 # Maximum age in seconds for valid timestamps (default: 300)
future_tolerance = 60         # Maximum seconds in future for timestamps (default: 60)
require_timestamp = false     # Whether timestamps required in all messages (default: false)

gRPC Configuration

Settings for gRPC API and subscriptions:

[grpc]
subscription_buffer_size = 256   # Subscription channel buffer size (default: 256)
optimistic = false               # Broadcast optimistic updates (default: false)
tcp_keepalive_interval = 60      # TCP keepalive interval in seconds (default: 60)
http2_keepalive_interval = 30    # HTTP/2 keepalive interval in seconds (default: 30)
http2_keepalive_timeout = 10     # HTTP/2 keepalive timeout in seconds (default: 10)

Configuration Examples

Development

Fast iteration with local Katana:

world_address = "0x1234..."
rpc = "http://0.0.0.0:5050"
# No db_dir = in-memory database
 
[indexing]
polling_interval = 100        # Fast updates (vs default 500ms)
pending = true                # Include pending txs
 
[server]
http_cors_origins = ["*"]     # Allow all origins

Production

Optimized for stability and performance:

world_address = "0x9abc..."
rpc = "https://api.cartridge.gg/x/starknet/mainnet"
db_dir = "/var/lib/torii/production"
 
[indexing]
polling_interval = 1000       # Conservative polling (vs default 500ms)
max_concurrent_tasks = 200    # Scale for load (vs default 100)
pending = false               # Stability over speed
 
[sql]
cache_size = -2000000         # 2GB cache in KiB (vs default -500MB)
page_size = 65536             # Large pages (vs default 32768)
 
[metrics]
metrics = true                # Essential monitoring

Best Practices

Performance:

Use persistent storage (db_dir) in production
Tune chunk sizes based on RPC performance
Enable indices only for frequently queried fields
Monitor memory usage with high concurrency

Security:

Bind to 127.0.0.1 for local-only access
Use specific CORS origins in production
Enable TLS for external-facing deployments
Secure P2P relay certificates

Monitoring:

Always enable metrics in production
Set up Prometheus scraping and alerting
Monitor database growth and query performance
Track indexing lag and error rates