Smart Contract Deployment

Relevant source files

The following files were used as context for generating this wiki page:

• apps/dojo/scripts/deploy-mainnet.sh
• apps/dojo/scripts/deploy-testnet.sh
• apps/dojo/dojo_dev.toml
• apps/dojo/dojo_release.toml
• apps/dojo/Scarb.toml
• apps/dojo/README.md

The OnChain Sage smart contracts, built with the Dojo framework on Starknet, are deployed using a set of shell scripts and configuration files. The process is standardized across different environments (development, testnet, mainnet) but includes specific safety measures for production deployment. The core tool for building and migrating contracts is sozo, the official Dojo toolkit CLI.

This document outlines the architecture, configuration, and step-by-step procedures for deploying the OnChain Sage Dojo contracts. The deployment process is primarily managed through scripts that wrap sozo commands, ensuring consistency and reliability.

Sources: apps/dojo/README.md:10-13, apps/dojo/scripts/deploy-mainnet.sh, apps/dojo/scripts/deploy-testnet.sh

Deployment Architecture

The deployment process relies on a combination of configuration files, environment variables, and shell scripts to manage deployments to different Starknet networks.

The following diagram illustrates the high-level deployment flow:

This diagram shows that a developer initiates a deployment by selecting an environment, configuring the necessary files, and running a script which then uses sozo to build and migrate the contracts to the target Starknet network, producing logs and manifest files as artifacts.

Sources: apps/dojo/README.md:61-86, apps/dojo/scripts/deploy-mainnet.sh, apps/dojo/scripts/deploy-testnet.sh

Configuration

Deployment behavior is controlled by .toml configuration files for world settings and .env files for sensitive data like private keys and RPC endpoints.

Environment Configuration (.env)

For each environment (testnet, mainnet), a corresponding .env file must be created from the template (.env.template). These files are loaded by the deployment scripts.

Sources: apps/dojo/README.md:70-73, apps/dojo/scripts/deploy-testnet.sh:7-12, apps/dojo/scripts/deploy-mainnet.sh:13-18

The following environment variables are required:

Variable	Description	Example (Testnet)
STARKNET_RPC_URL	The RPC endpoint for the target Starknet network.	https://starknet-goerli.infura.io/v3/
ACCOUNT_ADDRESS	The Starknet account address used for deployment.	0x127fd5f1fe78a71f8bcd1fec63e3fe2f0...
PRIVATE_KEY	The private key for the deployment account.	0xc5b2fcab997346f3ea1c00b002ecf6f38...

Sources: apps/dojo/scripts/deploy-mainnet.sh:20-25, apps/dojo/scripts/deploy-testnet.sh:14-19, apps/dojo/dojo_dev.toml:19-21

World Configuration (.toml)

Dojo uses .toml files to configure the world contract's metadata and environment-specific settings.

• dojo_dev.toml: Used for local development, pointing to a local Katana node.
• dojo_release.toml: Used for production (mainnet) deployment, pointing to a mainnet RPC.

Sources: apps/dojo/dojo_dev.toml, apps/dojo/dojo_release.toml

A typical configuration looks like this:

# Example from dojo_dev.toml
[world]
name = "OnChain Sage"
description = "AI-driven decentralized trading assistant..."
seed = "onchainsage_dev"

[env]
rpc_url = "http://localhost:5050/"
# Default account for katana with seed = 0
account_address = "0x127fd5f1fe78a71f8bcd1fec63e3fe2f0486b6ecd5c86a0466c3a21fa5cfcec"
private_key = "0xc5b2fcab997346f3ea1c00b002ecf6f382c5f9c9659a3894eb783c5320f912"

Sources: apps/dojo/dojo_dev.toml:1-21

Deployment Scripts

The project provides shell scripts to automate deployment for testnet and mainnet. These scripts ensure all necessary steps and checks are performed.

Sources: apps/dojo/README.md:104-106

Scarb.toml Scripts

The Scarb.toml file defines aliases for common sozo commands, including environment-specific deployments.

Script	Command	Description
migrate	sozo build && sozo migrate	Builds and migrates for the default environment.
deploy-dev	sozo build && sozo migrate --name dev	Deploys to the 'dev' environment.
deploy-testnet	sozo build && sozo migrate --name testnet	Deploys to the 'testnet' environment.
deploy-mainnet	sozo build && sozo migrate --name mainnet	Deploys to the 'mainnet' environment.
test	sozo test	Runs Dojo tests.
build	sozo build	Builds the project.

Sources: apps/dojo/Scarb.toml:9-15

Testnet Deployment (deploy-testnet.sh)

This script handles deployment to a Starknet testnet.

The process is as follows:

1. Loads environment variables from .env.testnet.
2. Validates that STARKNET_RPC_URL, ACCOUNT_ADDRESS, and PRIVATE_KEY are set.
3. Builds the contracts using sozo build.
4. Migrates the contracts to the testnet using sozo migrate --name testnet.
5. Logs the deployment details to deployment/testnet-deployments.log.

Sources: apps/dojo/scripts/deploy-testnet.sh

Mainnet Deployment (deploy-mainnet.sh)

The mainnet deployment script is more robust and includes several safety checks to prevent accidental or failed deployments.

The mainnet deployment flow includes critical safety checks:

Key safety features include:

• Manual Confirmations: The script prompts the user for confirmation twice before proceeding.
• RPC URL Check: It verifies that the STARKNET_RPC_URL contains the string "mainnet".
• Pre-deployment Testing: It runs the test suite using sozo test and will exit if any tests fail.
• Release Build: It builds the contracts with the --release flag for optimization.

# Mainnet pre-deployment checks
echo "🔍 Performing mainnet pre-deployment checks..."

# Check if this is actually mainnet
if [[ ! "$STARKNET_RPC_URL" == *"mainnet"* ]]; then
    echo "❌ RPC URL does not appear to be mainnet!"
    echo "Current RPC: $STARKNET_RPC_URL"
    exit 1
fi

# Run tests before deployment
echo "🧪 Running tests before mainnet deployment..."
sozo test

Sources: apps/dojo/scripts/deploy-mainnet.sh:28-41

Local Development Deployment

For local development, the process is simplified:

1. Start a local node: Run katana.
2. Deploy: Run sozo migrate. This command reads the dojo_dev.toml configuration by default, which is pre-configured for a local Katana instance.

Sources: apps/dojo/README.md:88-96, apps/dojo/dojo_dev.toml:18