Dojo Deployment

Deploy your Dojo world to local Katana sequencer, Sepolia testnet, or Starknet mainnet.

When to Use This Skill

• "Deploy my world to Katana"
• "Start Katana sequencer"
• "Deploy to Sepolia testnet"
• "Deploy to mainnet"

What This Skill Does

Handles deployment workflows:

• Start and configure Katana sequencer
• Deploy worlds with sozo migrate
• Verify deployments
• Manage world addresses
• Configure network settings

Quick Start

Local development:

"Start Katana and deploy my world"

Testnet deployment:

"Deploy my world to Sepolia"

Mainnet deployment:

"Deploy to Starknet mainnet"

Deployment Workflow

1. Local Development (Katana)

Start Katana:

bash
1katana --dev --dev.no-fee

This launches Katana with:

• RPC server at http://localhost:5050
• 10 pre-funded accounts
• Instant block mining
• Gas fees disabled

Build and deploy:

bash
1sozo build && sozo migrate

Verify:

bash
1# Preview deployment
2sozo inspect
3
4# Execute a system
5sozo execute dojo_starter-actions spawn

2. Testnet Deployment (Sepolia)

Configure profile:

toml
1# dojo_sepolia.toml
2[world]
3name = "My Game"
4seed = "my-game-sepolia"
5
6[env]
7rpc_url = "https://api.cartridge.gg/x/starknet/sepolia"
8account_address = "YOUR_ACCOUNT"
9private_key = "YOUR_KEY"
10
11[namespace]
12default = "my_game"
13
14[writers]
15"my_game" = ["my_game-actions"]

Deploy:

bash
1sozo build --profile sepolia
2sozo migrate --profile sepolia

3. Mainnet Deployment

Configure profile:

toml
1# dojo_mainnet.toml
2[world]
3name = "My Game"
4seed = "my-game-mainnet"
5
6[env]
7rpc_url = "https://api.cartridge.gg/x/starknet/mainnet"
8account_address = "YOUR_ACCOUNT"
9keystore_path = "~/.starknet_accounts/mainnet.json"
10
11[namespace]
12default = "my_game"
13
14[writers]
15"my_game" = ["my_game-actions"]

Deploy:

bash
1sozo build --profile mainnet
2sozo migrate --profile mainnet

Katana Configuration

See the Katana configuration guide for all available TOML options.

TOML Configuration

Most Dojo projects use a katana.toml config file rather than CLI flags. Recommended starter config:

toml
1[dev]
2dev = true
3no_fee = true
4
5[cartridge]
6controllers = true
7
8[server]
9http_cors_origins = "*"

Start with config file:

bash
1katana --config katana.toml

Cartridge Controller on Katana

When using Cartridge Controller locally, Katana must deploy Controller contracts at genesis. Without this, Controller transactions fail with "Requested contract address ... is not deployed".

toml
1# katana.toml
2[cartridge]
3paymaster = true  # Enables paymaster AND deploys Controller contracts at genesis

Note: paymaster = true implicitly enables controllers = true. See the Controller setup docs for client-side configuration.

Quick Start (CLI flags)

bash
1katana --dev --dev.no-fee

Mining Modes

Instant (default):

bash
1katana --dev --dev.no-fee

Mines block immediately on transaction.

Interval:

bash
1katana --block-time 10000

Mines block every 10 seconds.

Persistent Storage

bash
1katana --db-dir ./katana-db

Network Forking

Fork Starknet mainnet:

bash
1katana --fork.provider https://api.cartridge.gg/x/starknet/mainnet

Fork at specific block:

bash
1katana --fork.provider https://api.cartridge.gg/x/starknet/mainnet --fork.block 1000000

Sozo Commands

Build

bash
1sozo build

Inspect (Preview Deployment)

bash
1# See what will be deployed/changed
2sozo inspect

Migrate (Deploy)

bash
1# Deploy with default dev profile
2sozo migrate
3
4# Deploy with specific profile
5sozo migrate --profile sepolia

Execute System

bash
1# Call a system function
2sozo execute <CONTRACT_TAG> <FUNCTION> [ARGS...]
3
4# Example: spawn
5sozo execute dojo_starter-actions spawn
6
7# Example: move with argument
8sozo execute dojo_starter-actions move 1

Deployment Checklist

Pre-Deployment

• All tests passing (sozo test)
• Code reviewed (dojo-review skill)
• Configuration set (dojo-config skill)
• Target network funded (for gas)
• Private key secured (not committed)

Deployment

• Build succeeds (sozo build)
• Inspect looks correct (sozo inspect)
• Migration succeeds (sozo migrate)
• Manifest generated (check manifest_<profile>.json)
• World address recorded

Post-Deployment

• Deployment verified (execute systems, query models)
• Torii indexer configured (dojo-indexer skill)
• Client connected (dojo-client skill)
• World permissions verified (dojo-world skill)

Development Workflow

Terminal 1: Start Katana

bash
1katana --dev --dev.no-fee

Terminal 2: Build and deploy

bash
1sozo build && sozo migrate

Terminal 3: Start Torii

bash
1torii --world <WORLD_ADDRESS> --indexing.controllers

Sample Deploy Script

This skill includes deploy_local.sh, a template script for automated local development. Copy it into your project's scripts/ directory and customize it for your needs.

Setup:

1. Copy the script to your project: cp deploy_local.sh your-project/scripts/
2. Adjust configuration variables (profile name, URLs) as needed
3. Make executable: chmod +x scripts/deploy_local.sh

Run:

bash
1# Default dev profile
2./scripts/deploy_local.sh
3
4# Specific profile
5PROFILE=staging ./scripts/deploy_local.sh

What it does:

1. Checks for required tools (katana, sozo, torii, jq)
2. Starts Katana with health checking
3. Builds and deploys contracts
4. Extracts addresses from the manifest
5. Starts Torii indexer
6. Cleans up all services on exit (Ctrl+C)

Customization points:

• PROFILE: Default build/deploy profile
• RPC_URL: Katana endpoint (default: http://localhost:5050)
• TORII_URL: Torii endpoint (default: http://localhost:8080)
• Add project-specific post-deploy steps (e.g., seeding data, running migrations)

Slot Deployment (Remote)

Slot provides hosted Katana and Torii instances.

Authentication

bash
1slot auth login

Katana on Slot

Optimistic mode (simplest):

bash
1slot deployments create <PROJECT_NAME> katana --optimistic

With configuration file:

bash
1slot deployments create <PROJECT_NAME> katana --config katana.toml

See the Katana configuration guide for TOML options.

Torii on Slot

Create a torii.toml with your world address and RPC endpoint, then deploy:

bash
1slot deployments create <PROJECT_NAME> torii --config torii.toml --version <DOJO_VERSION>

See the dojo-indexer skill for full Torii configuration details.

Useful Commands

bash
1# Stream logs
2slot deployments logs <PROJECT_NAME> katana -f
3slot deployments logs <PROJECT_NAME> torii -f
4
5# Delete a deployment
6slot deployments delete <PROJECT_NAME> katana
7slot deployments delete <PROJECT_NAME> torii

Manifest File

After deployment, manifest_<profile>.json contains:

• World address
• Model addresses and class hashes
• System/contract addresses
• ABI information

Example:

json
1{
2  "world": {
3    "address": "0x...",
4    "class_hash": "0x..."
5  },
6  "models": [
7    {
8      "tag": "dojo_starter-Position",
9      "address": "0x..."
10    }
11  ],
12  "contracts": [
13    {
14      "tag": "dojo_starter-actions",
15      "address": "0x..."
16    }
17  ]
18}

Troubleshooting

"Account not found"

• Ensure account is deployed on target network
• Check account address in profile config
• Verify account has funds for gas

"Class hash mismatch"

• Run sozo build before migrating
• Check Scarb.toml for correct Dojo version
• Clear target/ and rebuild

"Insufficient funds"

• Fund account with ETH/STRK for gas
• Use Sepolia faucet: https://faucet.starknet.io

"Profile not found"

• Ensure dojo_<profile>.toml exists
• Check spelling matches the --profile flag

Network Information

Katana (Local)

• RPC: http://localhost:5050
• Pre-funded accounts printed on startup

Sepolia (Testnet)

• RPC: https://api.cartridge.gg/x/starknet/sepolia
• Faucet: https://faucet.starknet.io
• Explorer: https://sepolia.voyager.online

Mainnet

• RPC: https://api.cartridge.gg/x/starknet/mainnet
• Explorer: https://voyager.online

Next Steps

After deployment:

1. Use dojo-indexer skill to set up Torii
2. Use dojo-client skill to connect frontend
3. Use dojo-world skill to configure permissions
4. Use dojo-migrate skill for updates

Related Skills

• dojo-config: Configure deployment profiles
• dojo-migrate: Update deployments
• dojo-indexer: Index deployed world
• dojo-client: Connect clients to deployment
• dojo-world: Manage world permissions