Smart Contracts (Cairo/Dojo)
Relevant source files
The following files were used as context for generating this wiki page:The smart contracts for OnChain Sage are built on the Starknet network using the Cairo language and the Dojo framework. They form the decentralized backbone of the trading assistant, responsible for managing trading signals, user staking, community validation, and reputation systems. The contracts leverage Dojo's world-based architecture to manage on-chain state and logic.
This system is designed to be modular and extensible, allowing for features like STRK token-based payments, signal staking, and community-driven validation. The integration with the backend service allows for on-chain actions to be triggered by off-chain events and user interactions.
Sources: ARCHITECTURE.md, apps/dojo/README.md, README.md
Architecture and Framework
The smart contract layer is built using Dojo, a full-stack toolchain for building provable games and on-chain worlds with Cairo. It is deployed on the Starknet network. The architecture is centered around a "world" contract that manages various models (data) and systems (logic).
Sources: ARCHITECTURE.md, apps/dojo/Scarb.toml:15
Project Structure
The apps/dojo directory contains all the necessary files for the smart contract implementation.
| Directory/File | Description |
|---|---|
src/ | Contains the core Cairo source code. |
src/models/ | Data structures (schemas) for the application. |
src/systems/ | Contracts that contain the application logic. |
scripts/ | Utility scripts for testing, formatting, and deployment. |
config/ | Environment configuration files. |
Scarb.toml | Package configuration and dependencies. |
dojo_dev.toml | Development environment configuration. |
dojo_release.toml | Production environment configuration. |
Sources: apps/dojo/README.md:100-110
Dependencies
The primary dependency for the smart contracts is the Dojo framework.
| Package | Version/Source | Description |
|---|---|---|
dojo | git = "https://github.com/dojoengine/dojo%22%2C tag = "v1.5.0" | The core Dojo engine framework. |
dojo_cairo_test | git = "https://github.com/dojoengine/dojo%22%2C tag = "v1.5.0" | A library for testing Cairo code with Dojo. |
Sources: apps/dojo/Scarb.toml:15, apps/dojo/Scarb.toml:20
Core Components
The smart contract logic is divided into Models, which define the data structures, and Systems, which implement the business logic that operates on these models.
Sources: ARCHITECTURE.md:65-76
Models
The following diagram illustrates the relationships between the core data models.
This ER diagram shows the data models for user reputation, signals, stakes, and validation votes, and how they are interconnected.
Sources: ARCHITECTURE.md:67-71
| Model | Description |
|---|---|
Signal | Stores trading signal data (e.g., token, buy/sell, confidence score). |
Stake | Tracks user stakes on signals, including the user address and STRK amount. |
ValidationVote | Records community votes on signal credibility, weighted by reputation. |
UserReputation | Manages user reputation scores, which are adjusted based on validation accuracy. |
Sources: ARCHITECTURE.md:67-71
Systems
Systems are contracts that contain the logic to manipulate the state of the models.
| System | Description |
|---|---|
SignalManager | Registers new signals, updates signal metadata, and emits events. |
StakingSystem | Allows users to stake STRK on signals (stake_signal), tracks stakes, and manages reward distribution. |
ValidationSystem | Manages community validation (vote_signal), updates credibility scores, and adjusts user reputation. |
Sources: ARCHITECTURE.md:72-76
Configuration
The project uses .toml files for configuration, separating settings for different environments.
Development Configuration (dojo_dev.toml)
This file configures the Dojo world for local development.
| Key | Value | Description |
|---|---|---|
world.name | OnChain Sage | The name of the Dojo world. |
world.seed | onchainsage_dev | Seed for generating deterministic addresses. |
env.rpc_url | http://localhost:5050/ | RPC endpoint for the local Katana devnet. |
env.account_address | 0x127fd...cfcec | Default Katana account address. |
env.private_key | 0xc5b2f...f912 | Private key for the default account. |
writers | ["onchainsage-actions", "onchainsage-token", "onchainsage-analytics"] | Contracts with write access to the onchainsage namespace. |
Sources: apps/dojo/dojo_dev.toml
Build & Deployment Scripts
Scripts for building, testing, and migrating (deploying) contracts are defined in Scarb.toml.
| Script | Command | Description |
|---|---|---|
migrate | sozo build && sozo migrate | Build and deploy contracts to the default environment. |
deploy-dev | sozo build && sozo migrate --name dev | Build and deploy to the dev environment. |
deploy-testnet | sozo build && sozo migrate --name testnet | Build and deploy to the testnet environment. |
test | sozo test | Run Dojo tests. |
build | sozo build | Build the project. |
Sources: apps/dojo/Scarb.toml:8-14
Backend Integration
The NestJS backend interacts with the Starknet smart contracts via the StarknetService. This service uses the starknet.js library to initialize a provider and communicate with the deployed contracts.
Sources: apps/backend/src/starknet/starknet.service.ts
Interaction Flow
The following sequence diagram shows how the backend might call a smart contract function, such as creating a post. Note that the function names (create_post, vote_post) in starknet.service.ts differ from the system names (SignalManager, etc.) in the architecture document, suggesting different versions or components of the system. The service currently loads postSystemContract and badgeSystemContract.
This diagram shows the sequence of calls from the backend service to the Starknet provider to invoke a function on a deployed contract.
Sources: apps/backend/src/starknet/starknet.service.ts:50-60
Available Service Methods
The StarknetService exposes several methods for blockchain interaction. Some methods appear to be mock implementations.
| Method | Parameters | Description |
|---|---|---|
createPost | author: string, content: string | Invokes the create_post function on the postSystemContract. |
votePost | postId: string, vote: number | Invokes the vote_post function on the postSystemContract. |
awardBadge | user: string, badge: string | Invokes the award_badge function on the badgeSystemContract. |
getUserData | address: string | Retrieves user data by querying the Torii indexer. |
deposit | walletAddress: string, amount: number | Mock implementation for depositing funds. Returns a mock transaction hash. |
upgradeTier | walletAddress: string | Mock implementation for upgrading a user's tier. Returns a mock hash. |
payForCall | walletAddress: string, amount: number | Mock implementation for a one-time payment. Returns a mock hash. |
Sources: apps/backend/src/starknet/starknet.service.ts:50-153
Development and Deployment
The development workflow is managed through sozo (the Dojo command-line tool) and shell scripts.
Development Workflow
The typical development cycle involves writing, formatting, building, and testing the contracts.
This flowchart outlines the steps for developing the smart contracts, from writing code to local deployment.
Sources: apps/dojo/README.md:52-75, apps/dojo/scripts/format.sh
Deployment
Contracts can be deployed to a local Katana node, a testnet, or the Starknet mainnet using predefined scripts.
- Local Deployment: Start a local Katana node and run
sozo migrate. - Testnet/Mainnet Deployment: Configure the respective
.envfile and use the provided deployment scripts (./scripts/deploy-testnet.sh).
Sources: apps/dojo/README.md:77-99
Conclusion
The OnChain Sage smart contracts, built with Cairo and the Dojo framework, are a critical component of the platform's decentralized architecture. They provide the on-chain logic for managing trading signals, user reputation, and economic incentives through staking and validation. The system is designed for modularity, with a clear separation between data (Models) and logic (Systems), and is integrated with the backend services to create a cohesive user experience. The provided tooling and scripts facilitate a structured development and deployment process.