A full-stack decentralized puzzle game built on Starknet, where players solve cryptographic puzzles to earn $KIBI tokens and level up their pirate NFTs. Features AI-generated daily puzzles, user-created challenges, and a dynamic NFT progression system.
Kibi Dango is a One Piece-inspired puzzle game where players:
- Solve Daily Puzzles - AI-generated challenges with automatic rewards
- Create & Solve Community Puzzles - User-generated content with bounties
- Earn $KIBI Tokens - ERC-20 rewards for puzzle solving
- Level Up Pirate NFTs - Dynamic progression based on achievements
- Compete on Leaderboards - Track performance and rankings
kibi-dango/
├── packages/
│ ├── snfoundry/ # Smart Contracts (Cairo)
│ │ ├── contracts/ # Core game contracts
│ │ ├── scripts-ts/ # Deployment scripts
│ │ └── deployments/ # Contract addresses
│ └── nextjs/ # Frontend Application
│ ├── app/ # Next.js 15 App Router
│ ├── components/ # React components
│ ├── lib/ # Utilities & API
│ └── services/ # Web3 services
└── pirate-nft-metadata/ # NFT metadata & assets
- AI-Generated Daily Puzzles - Unique challenges every day using Google Gemini
- User-Created Puzzles - Community-driven content with custom bounties
- Cryptographic Verification - Hash commitments prevent front-running
- Difficulty Levels - Easy, Medium, Hard with different reward tiers
- Dynamic Ranks - 8 progression levels from TamedBeast to LeadPerformer
- Automatic Upgrades - NFT evolves based on puzzles solved
- SRC5 Metadata - Dynamic token URIs reflecting current rank
- Achievement Tracking - Visual progression through pirate ranks
- $KIBI ERC-20 - Game reward token with controlled minting
- Bounty System - User-created puzzles with custom rewards
- Rank Multipliers - Higher-ranked players earn more from AI puzzles
- Escrow System - Secure bounty management through KibiBank
- Cairo 2.11.4 - Starknet's native language
- OpenZeppelin Cairo - Battle-tested contract components
- Starknet Foundry - Testing and deployment framework
- Upgradeable Contracts - Future-proof architecture
- Next.js 15 - React framework with App Router
- TypeScript - Type-safe development
- Starknet.js - Web3 library for Starknet
- TailwindCSS - Utility-first CSS framework
- Radix UI - Accessible component primitives
- MongoDB - Off-chain puzzle and user data
- Mongoose - MongoDB ODM for Node.js
- API Routes - Next.js serverless functions
- Google Gemini AI - Puzzle generation
- Scarb - Cairo package manager
- Vitest - Unit testing framework
- ESLint & Prettier - Code quality tools
- Vercel - Deployment platform
- Node.js (v18+)
- Scarb (Cairo package manager)
- Argent X or Braavos wallet
- MongoDB database
- Google Gemini API key
# Clone the repository
git clone https://github.com/truthixify/kibi-dango
cd kibi-dango
# Install dependencies
yarn install
# Build smart contracts
cd packages/snfoundry/contracts
scarb build
# Set up environment variables
cd ../../nextjs
cp .env.example .envCreate .env file in packages/nextjs/:
# Database
MONGO_URI=mongodb://localhost:27017/kibidango
# AI Services
GEMINI_API_KEY=your_gemini_api_key
PROMPT=your_puzzle_generation_prompt
# Starknet
NEXT_PUBLIC_STARKNET_NETWORK=sepolia
NEXT_PUBLIC_CONTRACT_ADDRESSES={"PuzzleGame":"0x...","KibiToken":"0x...","PirateNFT":"0x...","KibiBank":"0x..."}
# Optional: Analytics & Monitoring
NEXT_PUBLIC_VERCEL_ANALYTICS_ID=your_analytics_id# Start frontend development server
cd packages/nextjs
yarn dev
# Run smart contract tests
cd ../snfoundry/contracts
scarb test
# Deploy contracts (configure first)
cd ../scripts-ts
npm run deploy- Daily Puzzle Challenge - AI-generated puzzle with automatic rewards
- Quick Stats - Player's rank, tokens earned, puzzles solved
- Recent Activity - Latest puzzle completions and achievements
- Solve Challenges - Submit solutions with cryptographic verification
- Create Puzzles - Design and publish custom challenges with bounties
- Pirate Profile - NFT display with current rank and stats
- Achievement History - Track puzzle-solving progress
- Token Balance - $KIBI earnings and transaction history
- Global Rankings - Top players by puzzles solved and tokens earned
- Rank Categories - Leaderboards for each pirate rank
- Achievement Tracking - Milestone celebrations and rewards
- Contract Management - Admin tools for game parameters
- Puzzle Generation - AI prompt configuration and testing
- Reward Settings - Bounty minimums and difficulty multipliers
// Standard ERC-20 with controlled minting
- transfer(), approve(), allowance() - Standard token functions
- mint() - Only callable by PuzzleGame contract
- upgrade() - Upgradeable contract architecture// Dynamic NFT with rank progression
- mint_if_needed() - Automatic NFT creation for new players
- increment_solved_count() - Update stats and rank
- get_rank() - Return current pirate rank
- tokenURI() - Dynamic metadata based on rank// Core game mechanics
- create_puzzle() - Submit puzzle with hash commitment
- submit_solution() - Verify solution and distribute rewards
- get_puzzle() - Retrieve puzzle data
- upgrade() - Contract upgradeability// Secure bounty management
- deposit_for_puzzle() - Lock tokens for puzzle bounty
- release_bounty() - Transfer bounty to solver
- get_deposit_info() - Query deposit statusgraph TD
A[Player] --> B[PuzzleGame]
B --> C[KibiToken]
B --> D[PirateNFT]
B --> E[KibiBank]
C --> F[Mint Rewards]
D --> G[Update Rank]
E --> H[Release Bounty]
// Daily Puzzles
POST /api/daily-puzzle - Create AI-generated daily puzzle
GET /api/daily-puzzle?address={address} - Get user's daily puzzle
PUT /api/daily-puzzle - Mark puzzle as solved
// Community Puzzles
GET /api/puzzles - List all available puzzles
POST /api/puzzles - Create new user puzzle
PUT /api/puzzles - Update puzzle status
GET /api/puzzles/[puzzleId] - Get specific puzzle details// User Profiles
GET /api/user/[address] - Get user profile and stats
POST /api/user - Register new user
PUT /api/user/[address] - Update user information// Puzzle Generation
POST /api/daily-puzzle/generate - Generate AI puzzle
GET /api/daily-puzzle/generate - Test puzzle generation- WalletConnect - Starknet wallet integration
- PuzzleCard - Display puzzle information and solve interface
- PirateProfile - NFT display with rank progression
- Leaderboard - Player rankings and achievements
- PuzzleForm - Create and submit puzzles
- Minimal Design - Clean, modern interface
- Responsive Layout - Mobile-first approach
- Dark/Light Themes - Theme switching support
- Loading States - Smooth user experience
- Success/Error Feedback - Clear transaction status
- Access Control - Only authorized contracts can perform critical operations
- Hash Commitments - Prevent front-running and solution theft
- Minimum Bounties - Prevent spam and low-quality puzzles
- Upgradeable Contracts - Security patches and improvements
- Input Validation - Client-side and server-side validation
- Rate Limiting - Prevent API abuse
- Error Handling - Graceful failure handling
- Transaction Confirmation - Clear feedback for all operations
# Run all tests
cd packages/snfoundry/contracts
scarb test
# Run specific test file
snforge test --path tests/test_contract.cairo
# Run with coverage
snforge test --coverage# Run unit tests
cd packages/nextjs
yarn test
# Run with coverage
yarn coverage
# Run E2E tests (if configured)
yarn test:e2e# Deploy to Sepolia testnet
cd packages/snfoundry/scripts-ts
npm run deploy:sepolia
# Deploy to mainnet
npm run deploy:mainnet
# Verify contracts
npm run verify -- --contract PuzzleGame --address 0x...# Deploy to Vercel
cd packages/nextjs
vercel --prod
# Or build and deploy manually
yarn build
yarn start- Configure Environment Variables - Set up all required API keys and contract addresses
- Deploy Smart Contracts - Deploy in order: KibiToken → PirateNFT → KibiBank → PuzzleGame
- Update Contract Addresses - Update frontend configuration with deployed addresses
- Set Up Database - Configure MongoDB connection and indexes
- Configure AI Services - Set up Google Gemini API for puzzle generation
- Fork Repository - Create your own fork
- Create Feature Branch -
git checkout -b feature/amazing-feature - Make Changes - Implement your feature or fix
- Add Tests - Ensure all functionality is tested
- Run Linting -
yarn lintandyarn format - Submit Pull Request - Create PR with detailed description
- TypeScript - Strict type checking enabled
- ESLint - Follow linting rules
- Prettier - Consistent code formatting
- Conventional Commits - Standard commit message format
- Cairo Book - Official Cairo documentation
- Starknet Book - Starknet development guide
- OpenZeppelin Cairo - Contract library docs
- Next.js Documentation - React framework guide
- Starknet.js - Web3 library documentation
- TailwindCSS - CSS framework reference
- GitHub Issues - Report bugs and request features
- Documentation - Check the docs for detailed guides
- Smart Contracts - Check
packages/snfoundry/contracts/README.md - Frontend - Review component documentation and examples
- API - Test endpoints using provided examples
This project is licensed under the MIT License - see the LICENSE file for details.
- Starknet Foundation - For the amazing L2 ecosystem
- OpenZeppelin - For battle-tested contract components
- One Piece - For the pirate theme inspiration
- Community Contributors - For feedback and improvements
Built with ❤️ on Starknet
May your puzzles be challenging and your rewards be plentiful! 🏴☠️