Dojo Framework

Dojo is a developer-friendly framework designed for building provable Games, Autonomous Worlds, and other applications. It is built as an extension of Cairo, a language that supports zero-knowledge proofs to attest to computation validity.

Key characteristics include:

• Provable: Uses ZK proofs to ensure computation validity.
• Composable & Extensible: Designed for native interoperability.
• Permissionless & Persistent: Built for decentralized, long-running applications.
• Scalable: Enables exponential scaling of onchain computation while maintaining Ethereum's security properties.

Dojo provides zero-cost abstractions for defining applications and a complete toolchain for building, migrating, deploying, proving, and settling these worlds in production.

The dojo-bindgen crate is responsible for generating language-specific bindings from Cairo ABI. It leverages cainome to parse the Cairo ABI into an intermediate representation (IR) of tokens.

Key components include:

• PluginManager: The primary interface used by the sozo CLI tool. It accepts an artifacts path and a list of plugins to trigger specific code generation tasks.
• BuiltinPlugin: Lightweight, Rust-based plugins integrated directly into the crate and the Dojo toolchain.

Future updates will introduce a Plugin interface (similar to protobuf) that allows users to define custom plugins communicating via stdin for increased flexibility.

To begin building provable applications with Dojo, follow the official tutorials provided in the Dojo Book. The recommended starting point is the Dojo Starter tutorial.

• Dojo Starter Tutorial: https://book.dojoengine.org/tutorials/dojo-starter
• Full Documentation: https://book.dojoengine.org/

Install the dojoup CLI tool by running the official installation script via curl. This script downloads and executes the necessary components to set up the Dojo environment on your system.

curl -L https://install.dojoengine.org | bash

To verify that the RPC endpoints are functioning correctly, you can run a local instance of Katana and execute the Hurl test suite.

1. Start Katana locally. By default, it will run on port 5050.
2. Run the Hurl tests sequentially against the running Katana instance to validate the endpoints.

# 1. Run Katana locally
cargo run --bin katana

# 2. Execute hurl tests sequentially
hurl --test examples/rpc/**/*.hurl

You can install or update the Dojo toolchain using the dojoup installation script. This is the recommended way to set up the environment for working with Dojo contracts and the sozo CLI.

Run the following command in your terminal:

curl -L https://install.dojoengine.org | bash

To set up a Dojo ECS environment, use the sozo CLI to build the world from your contract definitions and then migrate the world to deploy it.

1. Build the world: Compiles the contracts and prepares the world state.
2. Migrate the world: Deploys the contracts to the network/local environment.

# Build the world
sozo build

# Migrate the world
sozo migrate

To use Dojo's Cairo procedural macros in your project, add dojo_cairo_macros to your Scarb.toml dependencies file.

[dependencies]
dojo_cairo_macros = "1.7.0"

To propose a new release, manually trigger the release-dispatch GitHub action. You must provide a version value using semantic versioning or a release level: patch, minor, or major.

Once triggered, the workflow creates a Pull Request with the versioned repository. Merging this PR triggers the release flow and creates a draft release.

To use the core Dojo framework functions and utilities in your Cairo project, add the dojo dependency to your Scarb.toml file.

[dependencies]
dojo = "1.7.0"

If you need to use Dojo's procedural macros in your project, add the dojo_cairo_macros dependency to your Scarb.toml file.

[dependencies]
dojo_cairo_macros = "1.7.0"

If you modify the dojo-core or dojo-lang crates, you must rebuild the database artifacts. This requires a compatible version of Katana to be available in your $PATH or located in your /tmp/ directory.

Option 1: Using Katana in your $PATH

If a compatible Katana is already in your path, run:

bash scripts/rebuild_test_artifacts.sh

Option 2: Building Katana from source

If you need to build a specific version of Katana:

1. Clone and build Katana:

git clone https://github.com/dojoengine/katana.git && cd katana
cargo build --bin katana -r

2. Copy the binary to /tmp/ (Dojo looks for katana in /tmp/ by convention):

cp target/release/katana /tmp/

3. Return to the Dojo directory and run the rebuild script:

bash scripts/rebuild_test_artifacts.sh