This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
This is a parimutuel betting market system built with Rust, consisting of:
- bot/: Telegram bot for user interaction
- contracts/: Zero-knowledge smart contracts (RISC0/RISC-V)
- server/: REST API server and blockchain node interface
The system uses Hyle blockchain SDK (v0.13.0) and implements a decentralized betting platform where users can create markets, place bets, and claim winnings through Telegram.
# Bot development (requires env vars)
cd bot
export TELOXIDE_TOKEN="your_telegram_token"
export CLAUDE_API_KEY="your_claude_api_key"
cargo run
# Server development
cd server
cargo run -- --config ../config.toml
# Contract compilation (reproducible build)
cd contracts
cargo build --features build,contract1
# Contract compilation (local/fast build)
cd contracts
cargo build --features nonreproducible,contract1# Format all code
cargo fmt --all
# Run linter
cargo clippy --all-targets --all-features
# Run tests (limited test coverage currently)
cargo test --workspaceThe project uses Cargo workspaces with centralized dependency management in root Cargo.toml. Key workspace members:
contracts/contract1- Core smart contract logicbot- Telegram interfaceserver- REST API and blockchain integration
Contracts are compiled to RISC-V bytecode for zero-knowledge execution:
- Contract state managed through
MarketStatestruct - Actions include:
Initialize,CreateMarket,PlaceBet,ResolveMarket,ClaimWinnings - Initial user balance: 10,000 units
- Admin-controlled market resolution
- SQLite database for local state (
bot/bot.db) - Commands:
/start,/newbet,/bet,/mybalance,/solve - Claude AI integration for market resolution
- Async command handlers using teloxide
- REST API routes in
server/src/app.rs - Configuration management via
config.tomland environment variables (prefix:HYLE_) - Contract initialization and transaction handling
- RISC0 proof generation and verification
contracts/contract1/src/lib.rs- Core contract logic and state managementbot/src/main.rs- Bot command handlers and Telegram integrationserver/src/app.rs- REST API endpointscontracts/build.rs- RISC0 contract compilation scriptconfig.toml- Runtime configuration (ports, contract name, etc.)
The system uses hierarchical configuration:
- Defaults in
server/src/conf_defaults.toml - Overrides in
config.toml - Environment variables (prefix:
HYLE_)
Key settings:
contract_name: "contract1"rest_server_port: 4001da_read_from: Data availability layer endpointmax_txs_per_proof: Batching limit for proofs
users (user_id, username, balance, created_at)
bets (bet_id, creator_id, description, created_at, status)
wagers (wager_id, bet_id, user_id, amount, side, created_at)
solutions (solution_id, bet_id, solver_id, message_id, created_at)
user_init_status (user_id, initialized, initialized_at)- RISC0 patches applied to RustCrypto for zkVM compatibility
- Reproducible builds use Docker for consistent contract compilation
- Contract metadata generated at build time in
contracts/metadata.rs - Async/await throughout with Tokio runtime
- Error handling with
anyhowand customAppErrortypes