A decentralized lottery platform on Arc blockchain that uses a multi-party commit-reveal pattern to ensure fairness and prevent gaming. The system enables creators to distribute mystery prizes through time-locked lotteries with hidden values.
- Multi-Party Commit-Reveal: Fair randomness using creator secret + participant ticket hashes
- Two-Step Participation: Users commit before the draw, then claim prizes after reveal
- Prize Cascade: Uncommitted tickets don't lock prizes - they cascade to active participants
- Flexible Gas Model: Paymaster for USDC gas + optional sponsored commits + gasless claiming
- Native USDC: Built-in Arc blockchain USDC integration for prizes and gas
- Game Flow Documentation - Visual guide with sequence diagrams, state machines, and flowcharts
- Design Document - Detailed technical design
- Randomness Migration - Multi-party commit-reveal implementation details
The system uses a multi-party commit-reveal approach for fair, unpredictable randomness:
- Creator Secret: Generated and committed before ticket distribution
- Participant Entropy: Each committed ticket contributes randomness
- Combined Seed:
keccak256(creatorSecret + hash(all committed ticket hashes)) - No Block Dependencies: No waiting for future blocks or blockhash availability
- Minimum Participants: Requires at least 1 committed ticket to reveal
Security Properties:
- Creator cannot manipulate alone (secret committed before distribution)
- Participants cannot predict (don't know creator secret or other tickets)
- Collusion resistant (requires knowing ALL participants' secrets)
- Deterministic (same inputs = same output, verifiable fairness)
See GAME_FLOW.md for detailed flow diagrams.
bun installcd contract
forge build # Compile contracts
forge test # Run tests
forge test -vvv # Run tests with verbose outputcd fe
bun install # Install frontend dependencies
bun run dev # Start dev server on port 3000
bun run build # Build for productionSee LOCAL_DEVELOPMENT.md for detailed local testing setup.
blockery/
├── contract/ # Foundry smart contracts
│ ├── src/ # Solidity source files
│ ├── test/ # Contract tests
│ └── script/ # Deployment scripts
├── fe/ # React frontend application
│ ├── src/
│ │ ├── components/ # React components
│ │ ├── hooks/ # Custom hooks (wagmi)
│ │ ├── lib/ # Utilities (crypto, validation)
│ │ └── routes/ # TanStack Router routes
├── .kiro/ # Kiro AI assistant configuration
│ └── specs/ # Feature specifications
├── GAME_FLOW.md # Visual game flow documentation
└── README.md # This file
- Smart Contracts: Solidity + Foundry
- Frontend: React + TanStack Router + Vite
- Web3: wagmi + viem
- Styling: Tailwind CSS + shadcn/ui
- Blockchain: Arc Network (EVM-compatible L2)
- Gas Token: Native USDC
This project was created using bun init in bun v1.2.23. Bun is a fast all-in-one JavaScript runtime.
For development guidelines, see .kiro/steering/guidelines.md.