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:

Project Setup: Initialize structure and configure accounts
Development Cycle: Write, build, and test your contracts iteratively
Deployment: Deploy to local/remote networks with automatic state management
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

What it does:

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

When to clean:

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

What gets cleaned:

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.

Key Features:

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

Common Use Cases:

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.