Project Management

Sozo provides a complete development lifecycle for Dojo projects, from initial scaffolding to production deployment. This page covers the essential workflows and commands that take you from idea to deployed world.

Development Workflow

Building a Dojo project follows a predictable cycle that Sozo streamlines with intelligent automation:

1. Project Setup: Initialize structure and configure accounts
2. Development Cycle: Write, build, and test your contracts iteratively
3. Deployment: Deploy to local/remote networks with automatic state management
4. Updates: Iterate with automatic diff detection and minimal migrations

From Zero to Deployed

# 1. Create and set up new project
sozo init my-game
cd my-game
 
# 2. Set up development account (using starkli or other account tool)
# Note: Account management is handled separately from Sozo
 
# 3. Development cycle
sozo build                    # Compile contracts
sozo test                     # Run tests
sozo clean                    # Clean artifacts if needed
 
# 4. Deploy to local Katana
katana --dev --dev.no-fee &   # Start local sequencer
sozo migrate                  # Deploy world and all resources
 
# 5. Make changes and update
# Edit your contracts...
sozo build && sozo test       # Rebuild and test
sozo migrate                  # Automatic diff and deploy only changes
 
# 6. Deploy to other environments
sozo migrate --profile staging    # Deploy to testnet
sozo migrate --profile prod       # Deploy to mainnet

Key Concepts

Automatic State Management: Sozo tracks your world's state across deployments, automatically detecting changes and generating minimal migration transactions.

Profile-Based Configuration: Manage multiple environments (dev, staging, prod) with separate configuration files, allowing seamless deployment across networks.

Incremental Development: The build-test-migrate cycle is optimized for rapid iteration, with Sozo handling the complexity of blockchain state management.

Project Setup

sozo init

Create a new Dojo project with the standard structure and example code:

sozo init my-game                # Create project
sozo init my-game --git          # Create project + initialize git repo
 
# Use a custom template
sozo init my-game --template https://github.com/myorg/custom-dojo-template
sozo init my-game --template myorg/custom-dojo-template  # Short form

Account Management: Sozo uses accounts defined in your dojo_<profile>.toml files. See the configuration guide for more information.

Development Cycle

The core development loop involves building, testing, and iterating on your contracts:

sozo build

Compile your Cairo contracts and generate deployment artifacts:

sozo build                    # Compile all contracts
sozo build --unity            # Compile + generate Unity bindings
sozo build --typescript       # Compile + generate TypeScript bindings

• Compiles Cairo contracts using Scarb
• Validates contract syntax and imports
• Generates Dojo manifests for deployment
• (Optional) Creates language bindings for client integration

sozo test

Run your Cairo tests to verify contract behavior:

sozo test                     # Run all tests

Tests are Cairo functions marked with #[test]. Sozo runs them using the Cairo test runner, giving you confidence in your logic before deployment. See the testing guide for more information about testing your Dojo contracts.

sozo clean

Remove stale build files when needed:

sozo clean                    # Clean current profile manifest files
sozo clean --all-profiles     # Clean all profile manifest files

• After major contract restructuring
• When build artifacts seem corrupted
• Before important deployments to ensure fresh state

• Manifest files for the current profile (or all profiles with --all-profiles)
• Generated metadata and artifacts
• Does NOT clean Scarb's target/ directory (use scarb clean for that)

sozo bindgen

Create client bindings for various platforms after building:

sozo bindgen                  # Generate all configured bindings
sozo bindgen --typescript     # Generate TypeScript bindings only
sozo bindgen --unity          # Generate Unity bindings only

Bindgen reads from your build artifacts to create platform-specific client code for interacting with your world.

sozo dev

Automatically rebuild and migrate your world when files change during development:

sozo dev                             # Watch files and auto-rebuild
sozo dev --unity                     # Watch + generate Unity bindings
sozo dev --typescript                # Watch + generate TypeScript bindings
 
# With contract verification
sozo dev --verify voyager            # Auto-verify on Voyager after each rebuild

This starts a file watcher that automatically runs sozo build and sozo migrate whenever you modify Cairo contracts. Perfect for rapid development iteration without manual rebuilds.

• File watching: Monitors Cairo source files for changes
• Automatic rebuild: Runs build + migrate when files change
• Binding generation: Can generate client bindings on each rebuild
• Hot reload: Instant feedback loop for development

• Development with live-reloading game clients
• Rapid contract iteration and testing
• Continuous integration during development
• Client binding updates alongside contract changes

Deployment and Updates

Sozo's migration system is the heart of Dojo deployment, automatically handling the complex process of deploying and updating worlds.

sozo migrate

Deploy your world for the first time or update existing deployments:

# First deployment to local Katana
katana --dev --dev.no-fee &   # Start local sequencer
sozo migrate                  # Deploy world and all resources
 
# Deploy to testnet (requires profile configuration)
sozo migrate --profile staging
 
# Deploy to mainnet
sozo migrate --profile prod

How Migration Works

Automatic Diff Analysis: Sozo compares your local world state against the deployed state, identifying exactly what has changed:

• New or modified models, systems, events, libraries
• Updated class hashes and resource registrations
• Permission changes (writers and owners)

Intelligent Updates: Instead of redeploying everything, Sozo generates minimal migration transactions:

• Declares only new or changed classes
• Updates only modified resources
• Applies permission changes incrementally
• Initializes new contracts as needed

Multi-Environment Management: Each profile tracks its own deployment state:

sozo migrate                    # Uses 'dev' profile (local Katana)
sozo migrate --profile staging  # Uses 'staging' profile (testnet)
sozo migrate --profile prod     # Uses 'prod' profile (mainnet)

For subsequent deployments, record the world address in your profile:

[env]
world_address = "0x06171ed98331e849d6084bf2b3e3186a7ddf35574dd68cab4691053ee8ab69d7"
rpc_url = "https://starknet-sepolia.public.blastapi.io/rpc/v0_7"
account_address = "0x..."
private_key = "0x..."

This tells Sozo to update the existing world rather than deploy a new one.

Local Development

# Standard local development flow
katana --dev --dev.no-fee &      # Start local sequencer
sozo build && sozo test          # Build and test
sozo migrate                     # Deploy to local Katana
 
# Test your world...
# Update your contracts...
 
sozo migrate                     # Deploy any changes (automatic diff)

Remote Deployment

# Final validation before production
sozo build && sozo test
sozo clean && sozo build         # Clean build for production
 
# Deploy to mainnet
sozo migrate --profile prod

Development Utilities

sozo hash

Debug and verify resource deployments:

# Compute hash for a resource
sozo hash compute Position         # Get hash for Position model
sozo hash compute Actions          # Get hash for Actions system
 
# Find resource by hash
sozo hash find 0x1234... --namespaces ns --resources Position,Actions

sozo walnut

Verify your contracts on Walnut for debugging:

sozo walnut verify                # Verify all contracts on Walnut

This uploads your contract source and ABIs to Walnut for debugging and inspection. For more details, refer to Walnut documentation.