A modern Web3 casino platform built with Cairo smart contracts, featuring multiple games and secure token management.
This project implements a decentralized casino platform using Cairo smart contracts. It features multiple casino games, secure token management, and a robust controller system for managing game operations.
src/- Main source code directorylib.cairo- Core library and entry pointtoken.cairo- Token contract implementationcontroller/- Game controller and management systemsafe/- Secure vault implementation for managing fundsgames/- Casino game implementationsbase_game_interface.cairo- Base interface for all gamesroulette/- Roulette game implementationcoinflip/- Coin flip game implementationplinko/- Plinko game implementationcrashgame/- Crash game implementation
tests/- Test suite for all componentsscripts/- Deployment and utility scripts
Scarb.toml- Project dependencies and configurationsnfoundry.toml- Foundry configuration for testingScarb.lock- Locked dependencies
- Multiple casino games (Roulette, Coin Flip, Plinko, Crash Game)
- Secure token management system
- Controller-based game management
- Safe vault for fund management
- Comprehensive test suite
- Install dependencies:
scarb build- Run tests:
scarb testThe project uses Cairo for smart contract development and includes a comprehensive test suite. Each game implements the base game interface, ensuring consistent behavior across all games.
This project is licensed under the terms included in the LICENSE file.
The project implements various security measures:
- Safe vault for fund management
- Controller-based access control
- Secure token management
- Comprehensive testing
Contributions are welcome! Please feel free to submit a Pull Request.
A Starknet smart contract implementation of a Crash Game where players can bet and attempt to cash out before the game crashes.
Starkcrash is a multiplayer betting game where players place bets during a betting phase and try to cash out during the playing phase before the game crashes. The crash point is determined by a provably fair random number system using commit-reveal scheme.
- Transition Phase: Initial state for a new game
- Committed Seed Phase: Operator commits a hashed seed for randomness
- Betting Phase: Players can place their bets
- Playing Phase: Game is live, multiplier increases, players can cash out
- Crashed Phase: Game ends, next game begins
- Provably fair randomness using commit-reveal scheme
- Configurable casino fee (max 6%)
- Adjustable maximum bet limits
- Multiple bets per player allowed (configurable)
- Pausable functionality for emergencies
- Upgradeable design
- ETH-based betting system
place_bet(game_id, amount): Place a bet during betting phaseget_player_bet(player, game_id): Query bet amount for a playerget_game_state(game_id): Check current game state
commit_seed(seed_hash): Commit the seed hash for the next gamestart_betting(): Open betting phasestart_game(): Start playing phaseend_game(seed): End game and reveal seedprocess_cashout(game_id, player, multiplier): Process player cashout
set_max_bet(max_bet): Set maximum bet amountset_min_bet(min_bet): Set minimum bet amountset_casino_fee_basis_points(casino_fee_basis_points): Set casino fee (max 6%)set_casino_address(casino_address): Set casino fee recipientset_operator(operator): Set operator addresspause()/unpause(): Emergency pause/unpause
BetPlaced: Emitted when a player places a betCashoutProcessed: Emitted when a player successfully cashes outGameStarted: Emitted when a new game startsGameEnded: Emitted when a game endsCasinoCut: Emitted when casino fee is collected
- Ownership management using OpenZeppelin's Ownable pattern
- Pausable functionality for emergency situations
- Input validation for all parameters
- Protection against multiple cashouts
- Maximum bet limits
- Casino fee capped at 6%
- OpenZeppelin Contracts (Ownable, Pausable, Upgradeable)
- Starknet Standard Library
- Poseidon Hash function for commit-reveal scheme
This section provides guidance for developers looking to implement new games that integrate with the casino's Controller and Safe contracts.
The casino platform consists of three main components:
- Safe Contract: Securely stores all casino funds and only accepts calls from the Controller
- Controller Contract: Manages game whitelisting, bet limits, and fee collection
- Game Contracts: Individual game implementations that interact with players and the Controller
Player → Game Contract → Controller Contract → Safe Contract
To create a new game that integrates with the system, your contract should:
-
Implement the required interfaces:
IBaseGame: Core game functionalityIGameManagement: Limit and configuration managementIGameLifecycle: Game state transitions
-
Use standard storage patterns:
- Map player bets by game_id and address:
Map<(u64, ContractAddress), u256> - Track processed payouts:
Map<(u64, ContractAddress), bool> - Store game states:
Map<u64, GameState>
- Map player bets by game_id and address:
-
Implement these key functions:
place_bet: Accept player funds and forward to Controllerprocess_cashout: Calculate winnings and request payout from Controller- Game state management (betting, playing, ended, etc.)
All financial operations must go through the Controller:
-
Bet Processing:
// In your place_bet function: let eth = ERC20ABIDispatcher { contract_address: ETH_ADDRESS.try_into().unwrap() }; eth.transferFrom(player, self.controller_address.read(), amount); IControllerDispatcher { contract_address: self.controller_address.read() }.process_bet(amount);
-
Cashout Processing:
// In your process_cashout function: let payout = (bet_amount * multiplier) / 10000; IControllerDispatcher { contract_address: self.controller_address.read() }.process_cashout(player, payout);
-
Game Limits:
// For getting min/max bet limits: IControllerDispatcher { contract_address: self.controller_address.read() }.get_min_bet(get_contract_address()); IControllerDispatcher { contract_address: self.controller_address.read() }.get_max_bet(get_contract_address());
-
Required Access Controls:
- Use OpenZeppelin's
Ownablefor owner-only functions - Ensure only the owner can modify game parameters
- Include
Pausablefunctionality for emergency stops
- Use OpenZeppelin's
-
Critical Checks:
- Validate bet amounts against min/max limits
- Prevent duplicate processing of cashouts
- Enforce game state transitions
- Verify caller permissions for admin functions
-
Funds Handling:
- Never store or transfer ETH directly
- Always route funds through the Controller
- Verify all arithmetic to prevent over/underflows
- USE BASIS POINTS
-
Create comprehensive tests covering:
- Correct interaction with Controller
- Proper game state transitions
- Handling of edge cases (min/max bets, fee calculations)
- Security scenarios (unauthorized access, invalid states)
-
Use the provided test utilities in
tests/utils.cairofor common setup
See the existing CrashGame implementation for a complete example of a game that integrates properly with the Controller and Safe contracts.