🎮 ColorSnap Game

A Decentralized Multi-Chain Color Matching Game

📖 Overview

ColorSnap is a revolutionary decentralized puzzle game where players match colored bottles to target configurations on the blockchain. Connect your wallet, compete globally, and earn points in this engaging multi-chain experience.

🎮 Interactive Game Preview (Click to expand)

🧪 Current Game State: [🔴][🔵][🟢][🟡][🟣]
🎯 Target Pattern:     [🟣][🟢][🔴][🔵][🟡]

Actions Available:
┌─ 🔄 Swap bottles     ┌─ 👁️ Peek at solution (after 5 moves)
├─ ✅ Submit solution  ├─ 🚫 Forfeit game  
└─ 📊 Check progress   └─ 🏆 View leaderboard

🏃‍♂️ Try the sequence: Swap(1,5) → Swap(2,4) → Swap(1,3) → Submit!

🎯 Core Gameplay

🧪 Match colored bottles to hidden target patterns
🔄 Swap bottle positions strategically
👁️ Peek at solutions after 5 moves (with cooldown)
🏆 Earn 10 points per completed puzzle
📊 Compete globally on the leaderboard

🛠️ Technology Stack

Component	Technology	Version	📊 Usage
Smart Contracts	+	Latest	🔗 Core Logic
Frontend	+	15.x	🎨 UI/UX
Web3 Integration	+	Latest	🔌 Web3 Connectivity
Styling		3.x	💅 Responsive Design
Default Network		8453	⛓️ Blockchain Layer

🌐 Deployed Contracts

Our smart contracts are live across multiple networks for maximum accessibility:

🌟 Network	📍 Contract Address	⛓️ Chain ID	📊 Status
🔵 Base Mainnet	`0x62dcaAdAd6D5E6CA4B594CEB636A147537aE7F8f` 📋 Copy Address	`8453`	🟢 LIVE
🟡 Somnia Testnet	`0xc2dc20E9F389114578F78a7f3C3B071db0b8e8dC` 📋 Copy Address	`50312`	🟡 TESTNET
⚡ Electroneum Testnet	`0xEF7902FeE12ea3D3245eD721767FB048Afa38a2f` 📋 Copy Address	`5201420`	🔵 TESTNET

🔄 Quick Network Setup (Click to expand)

Add Networks to MetaMask

Base Mainnet:

Network Name: Base Mainnet
RPC URL: https://mainnet.base.org
Chain ID: 8453
Currency Symbol: ETH
Block Explorer: https://basescan.org

Somnia Testnet:

Network Name: Somnia Testnet  
RPC URL: https://testnet-rpc.somnia.network
Chain ID: 50312
Currency Symbol: ETH
Block Explorer: https://shannon-explorer.somnia.network

Electroneum Testnet:

Network Name: Electroneum Testnet
RPC URL: https://testnet-rpc.electroneum.com  
Chain ID: 5201420
Currency Symbol: ETN
Block Explorer: https://testnet-explorer.electroneum.com

🦊 Add to MetaMask (Manual)

✨ Features

🔗 Wallet Integration

Connect any EVM-compatible wallet
MetaMask, WalletConnect, and more
Seamless multi-chain support

👤 Player Registration

Set your champion name on-chain
Persistent identity across networks
Global recognition system

🎮 Interactive Gameplay

Intuitive bottle swapping mechanics
Real-time visual feedback
Strategic peek system with cooldowns

🏆 Global Competition

Live leaderboard updates
Cross-network score aggregation
Compete with players worldwide

📱 Responsive Design

Works on all devices
Mobile-optimized interface
Smooth animations and transitions

⚡ Real-time Updates

Live game state monitoring
Instant transaction feedback
Dynamic UI updates

🚀 Quick Start

📋 Prerequisites

Node.js 18+ and npm/yarn
Foundry (for smart contract development)
EVM-compatible wallet
Testnet ETH for transactions

🔧 Interactive Installation

📦 Step 1: Clone & Setup Repository

# 🎯 Clone the repository
git clone https://github.com/7maylord/colorsnap.git
cd colorsnap

# 📁 Verify project structure
ls -la
# Expected output:
# README.md
# frontend/
# smart-contracts/

✅ Verification Checkpoint

Run this command to verify your setup:

echo "✅ Repository cloned successfully!" && \
echo "📁 Current directory: $(pwd)" && \
echo "📝 Files found: $(ls | wc -l) items"

⛓️ Step 2: Smart Contract Deployment

# Navigate to smart contracts directory
cd smart-contracts

# Install Foundry dependencies
forge install

# Set your environment variables
export RPC_URL="your_rpc_url_here"
export PRIVATE_KEY="your_private_key_here"

# 🚀 Deploy the contract
forge script script/Colorsnap.s.sol --rpc-url $RPC_URL --broadcast

🌐 Network-Specific Deployment Commands

🔵 Base Mainnet:

forge script script/Colorsnap.s.sol \
    --rpc-url https://mainnet.base.org \
    --private-key $PRIVATE_KEY \
    --broadcast --verify

🟡 Somnia Testnet:

forge script script/Colorsnap.s.sol \
    --rpc-url https://testnet-rpc.somnia.network \
    --private-key $PRIVATE_KEY \
    --broadcast

⚡ Electroneum Testnet:

forge script script/DeployElectroneum.s.sol \
    --rpc-url https://testnet-rpc.electroneum.com \
    --private-key $PRIVATE_KEY \
    --broadcast

🔍 Contract Verification

After deployment, verify your contract:

# Get your contract address from deployment output
CONTRACT_ADDRESS="0x..." # Replace with your address

# Verify the contract is deployed
cast code $CONTRACT_ADDRESS --rpc-url $RPC_URL

# Expected: Non-empty bytecode output means success! ✅

🎨 Step 3: Frontend Setup

# Navigate to frontend directory
cd ../frontend

# Install dependencies
yarn install
# or: npm install

# Create environment file
cp .env.example .env.local

⚙️ Environment Configuration

Add these variables to your .env.local:

# 📍 Your deployed contract address
NEXT_PUBLIC_CONTRACT_ADDRESS=0x...

# 🌐 RPC URL for your chosen network
NEXT_PUBLIC_RPC_URL=https://...

# ⛓️ Chain ID for your network
NEXT_PUBLIC_CHAIN_ID=8453

# 🔌 WalletConnect Project ID (get from https://cloud.walletconnect.com)
WALLETCONNECT_PROJECT_ID=your_project_id

📋 Quick Copy Templates

Base Mainnet Template:

NEXT_PUBLIC_CONTRACT_ADDRESS=0x62dcaAdAd6D5E6CA4B594CEB636A147537aE7F8f
NEXT_PUBLIC_RPC_URL=https://mainnet.base.org
NEXT_PUBLIC_CHAIN_ID=8453
WALLETCONNECT_PROJECT_ID=your_project_id

Somnia Testnet Template:

NEXT_PUBLIC_CONTRACT_ADDRESS=0xc2dc20E9F389114578F78a7f3C3B071db0b8e8dC
NEXT_PUBLIC_RPC_URL=https://testnet-rpc.somnia.network
NEXT_PUBLIC_CHAIN_ID=50312
WALLETCONNECT_PROJECT_ID=your_project_id

# 🚀 Start the development server
yarn run dev
# or: npm run dev

🔍 Development Server Status Check

Your development server should be running at:

🌐 Local: http://localhost:3000
🌍 Network: http://your-ip:3000

Verify it's working:

# Check if the server is responding
curl -I http://localhost:3000

# Expected: HTTP/200 OK ✅

Common Issues & Solutions:

❌ Port 3000 in use: Try yarn dev -p 3001
❌ Module not found: Run yarn install again
❌ Environment vars: Check your .env.local file

🎉 Step 4: Launch & Play!

🌐 Open your browser to http://localhost:3000
🦊 Connect your wallet (MetaMask, WalletConnect, etc.)
🏆 Register your champion name on-chain
🎮 Start your first game and begin matching bottles!

✅ Success Checklist

✅ Repository cloned and navigated
⛓️ Smart contract deployed successfully
📦 Frontend dependencies installed
⚙️ Environment variables configured
🚀 Development server running
🌐 Application accessible in browser
🦊 Wallet connected to correct network
🏆 Champion name registered
🎮 First game started

🎊 Congratulations! You're ready to play ColorSnap!

🔧 Quick Troubleshooting

Common Issues

🚫 "Cannot connect to network"

# Check your RPC URL is working
curl -X POST -H "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' \
  $RPC_URL

🚫 "Transaction failed"

# Check your balance
cast balance $YOUR_WALLET_ADDRESS --rpc-url $RPC_URL

# Check gas price
cast gas-price --rpc-url $RPC_URL

🚫 "Contract not found"

# Verify contract deployment
cast code $CONTRACT_ADDRESS --rpc-url $RPC_URL
# Should return bytecode, not 0x

📁 Project Structure

colorsnap/
├── 📁 frontend/                    # Next.js Application
│   ├── 📁 src/
│   │   ├── 📁 components/          # React Components
│   │   │   ├── 🧪 Bottle.tsx              # Individual bottle component
│   │   │   ├── 🎮 ColorSnapGame.tsx       # Main game logic
│   │   │   ├── 🏆 CongratsMessage.tsx     # Victory celebration
│   │   │   ├── 📖 InstructionsModal.tsx   # Game instructions
│   │   │   ├── 🔗 WalletConnectButton.tsx # Wallet integration
│   │   │   └── 📊 Leaderboard components
│   │   ├── 📁 hooks/               # Custom React Hooks
│   │   │   ├── 🔗 useContractInteractions.ts  # Contract calls
│   │   │   ├── 👂 useGameCompletedListener.ts # Event listening
│   │   │   └── 🔒 useTargetRevealLockout.ts   # Peek cooldown
│   │   ├── 📁 app/                 # Next.js App Router
│   │   │   ├── 🎮 game/                    # Game page
│   │   │   ├── 🏆 leaderboard/             # Leaderboard page
│   │   │   └── 🎨 globals.css              # Global styles
│   │   ├── 📁 abi/                 # Contract ABI
│   │   ├── 📁 config/              # Configuration files
│   │   └── 📁 context/             # React Context providers
│   └── 📖 README.md                # Frontend documentation
├── 📁 smart-contracts/             # Solidity Contracts
│   ├── 📁 src/                     # Contract Source Code
│   │   └── 📜 Colorsnap.sol               # Main game contract
│   ├── 📁 script/                  # Deployment Scripts
│   │   ├── 🚀 Colorsnap.s.sol             # Main deployment
│   │   ├── 🌐 DeployBase.s.sol            # Base network deployment
│   │   └── ⚡ DeployElectroneum.s.sol     # Electroneum deployment
│   ├── 📁 test/                    # Contract Tests
│   │   └── 🧪 ColorSnap.t.sol             # Test suite
│   └── 📖 README.md                # Smart contract documentation
└── 📖 README.md                    # This documentation

🎮 How to Play ColorSnap

🎯 Getting Started

Step 1: Connect Your Wallet 🦊

Use any EVM-compatible wallet (MetaMask, WalletConnect, etc.)
Ensure you're connected to the correct network
Have some testnet ETH ready for transactions

Step 2: Register Your Champion Name 🏆

Enter your display name (max 31 characters)
Click "🏆 Register Champion" to save it on-chain
This name will appear on the global leaderboard

Step 3: Start Your Challenge 🚀

Click "🎮 Start New Challenge" to begin
Receive 5 colored bottles in random positions
A hidden target configuration is generated

🧪 Game Mechanics

🎯 The Objective

Match your bottle arrangement to the target configuration exactly. Each bottle must be in the correct position with the correct color.

🌈 Available Colors

Color	Symbol	Description
🔴 Red	R	The fiery starter
🔵 Blue	B	The cool challenger
🟢 Green	G	The nature warrior
🟡 Yellow	Y	The bright contender
🟣 Purple	P	The royal challenger

🔄 Swapping Mechanics

Select First Bottle: Click the first bottle to move
Select Second Bottle: Click the second bottle to swap with
Automatic Swap: Bottles exchange positions instantly
Move Counter: Each swap counts as one move

👁️ Peek System

🔒 Locked Until 5 Moves: Must make 5 swaps to unlock
⏱️ 3-Second Peek: View the target for 3 seconds
🕐 3-Minute Cooldown: Wait before next peek
📋 Strategic Planning: Use peeks wisely!

🏆 Scoring & Strategy

📊 Scoring System

🎯 10 Points per Puzzle: Earned for each completion
🎪 Move Efficiency: Fewer moves = better strategy
🌍 Global Ranking: Compete worldwide
💎 Permanent Storage: Points stored on-chain forever

🧠 Winning Strategies

🔰 Beginner Tips

Start with bottles already in correct positions
Work from outside positions inward
Count each color to verify you have the right mix
Don't peek too early - try solving independently first

🎯 Advanced Techniques

Recognize patterns in target arrangements
Plan multiple swaps in advance
Group similar colors when possible
Focus on efficiency and fewer moves

🏅 Pro Tips

Memorize patterns quickly during peeks
Work backwards from the target
Use the "✅ Matched" counter strategically
Take time to plan - no rush penalties

🎉 Game Completion

✅ Successful Submission

🎯 Exact Match Required: All bottles in correct positions
🏆 10 Points Awarded: Added to your total score
🎊 Celebration Animation: Victory message displayed
📈 Instant Leaderboard Update: See your new ranking

� Forfeiting a Game

� No Points Lost: Existing points remain safe
🚀 Immediate Restart: Start new game right away
⚡ No Penalties: No negative consequences

� Progress Tracking

🔄 Swap Counter: Number of moves made
✅ Match Counter: Correct bottle positions
🎯 Target Display: Configuration to achieve
⚡ Transaction Status: Real-time updates

🛠️ Development

📋 Development Environment Setup

Prerequisites

Node.js 18.0 or higher
npm or yarn package manager
Foundry for smart contract development
Git for version control

Local Development

# Clone the repository
git clone https://github.com/yourusername/colorsnap.git
cd colorsnap

# Install dependencies for both frontend and contracts
cd frontend && yarn install
cd ../smart-contracts && forge install

# Start development servers
cd ../frontend && yarn dev          # Frontend at localhost:3000
forge test                          # Run contract tests

🧪 Testing

Smart Contract Tests

cd smart-contracts

# Run all tests
forge test

# Run tests with gas reporting
forge test --gas-report

# Run specific test
forge test --match-test testGameFlow

Frontend Testing

cd frontend

# Run unit tests
npm test

# Run e2e tests
npm run test:e2e

# Generate test coverage
npm run test:coverage

⚙️ Configuration

Environment Variables

Create .env.local in the frontend directory:

NEXT_PUBLIC_CONTRACT_ADDRESS=0x...
NEXT_PUBLIC_RPC_URL=https://...
NEXT_PUBLIC_CHAIN_ID=8453
WALLETCONNECT_PROJECT_ID=your_project_id

Network Configuration

Networks are configured in frontend/src/config/chains.ts:

Base Mainnet (Primary)
Somnia Testnet
Electroneum Testnet

🚀 Deployment

📦 Smart Contract Deployment

Deploy to Base Mainnet

cd smart-contracts

# Set environment variables
export PRIVATE_KEY="your_private_key"
export RPC_URL="https://mainnet.base.org"

# Deploy contract
forge script script/Colorsnap.s.sol \
    --rpc-url $RPC_URL \
    --private-key $PRIVATE_KEY \
    --broadcast \
    --verify

Deploy to Testnets

# Somnia Testnet
forge script script/Colorsnap.s.sol \
    --rpc-url https://testnet-rpc.somnia.network \
    --private-key $PRIVATE_KEY \
    --broadcast

# Electroneum Testnet  
forge script script/DeployElectroneum.s.sol \
    --rpc-url https://testnet-rpc.electroneum.com \
    --private-key $PRIVATE_KEY \
    --broadcast

🌐 Frontend Deployment

Deploy to Vercel

# Install Vercel CLI
npm i -g vercel

# Deploy
cd frontend
vercel

# Set environment variables in Vercel dashboard
# NEXT_PUBLIC_CONTRACT_ADDRESS
# NEXT_PUBLIC_RPC_URL
# NEXT_PUBLIC_CHAIN_ID

Deploy to Netlify

# Build the application
cd frontend
npm run build

# Deploy to Netlify
npx netlify deploy --prod --dir=out

Other Hosting Options

GitHub Pages: Static export with next export
AWS S3: Static hosting with CloudFront
Firebase Hosting: Google's hosting platform
IPFS: Decentralized hosting

🤝 Contributing

We welcome contributions from the community! Here's how to get involved:

📝 Contribution Guidelines

Getting Started

Fork the repository
Clone your fork locally
Create a feature branch: git checkout -b feature/amazing-feature
Make your changes
Test thoroughly
Commit with clear messages: git commit -m 'Add amazing feature'
Push to your branch: git push origin feature/amazing-feature
Submit a pull request

Code Standards

TypeScript for type safety
ESLint for code linting
Prettier for code formatting
Conventional Commits for commit messages
Comprehensive tests for new features

Areas for Contribution

🎮 Game Features: New game modes, power-ups, achievements
🎨 UI/UX: Design improvements, animations, accessibility
⛓️ Blockchain: Multi-chain support, gas optimization
📱 Mobile: React Native app, PWA enhancements
📚 Documentation: Tutorials, API docs, translations
🧪 Testing: Unit tests, integration tests, e2e tests

📄 License

MIT License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software.

Connect With Us

Source Code _{Contribute & Star ⭐}	Updates _{Latest news & tips}	Community _{Chat & support}
Documentation _{Detailed guides}	Blog _{Dev insights}	Tutorials _{Video guides}

📊 Project Statistics

Development Activity:

🎯 Latest Release: v1.0.0
📈 Commits This Month: 24
🐛 Open Issues: 3
✅ Closed Issues: 17
👥 Contributors: 4

_{Made with ❤️ by the ColorSnap team}
_{⭐ Star us on GitHub if you like this project!}

Name		Name	Last commit message	Last commit date
Latest commit History 31 Commits
frontend		frontend
smart-contracts		smart-contracts
.gitignore		.gitignore
.gitmodules		.gitmodules
README.md		README.md
interactive-readme-demo.html		interactive-readme-demo.html

Folders and files

Latest commit

History

Repository files navigation

🎮 ColorSnap Game

📖 Overview

🎯 Core Gameplay

🛠️ Technology Stack

🌐 Deployed Contracts

Add Networks to MetaMask

✨ Features

🔗 Wallet Integration

👤 Player Registration

🎮 Interactive Gameplay

🏆 Global Competition

📱 Responsive Design

⚡ Real-time Updates

🚀 Quick Start

📋 Prerequisites

🔧 Interactive Installation

✅ Success Checklist

Common Issues

📁 Project Structure

🎮 How to Play ColorSnap

Step 1: Connect Your Wallet 🦊

Step 2: Register Your Champion Name 🏆

Step 3: Start Your Challenge 🚀

🎯 The Objective

🌈 Available Colors

🔄 Swapping Mechanics

👁️ Peek System

📊 Scoring System

🧠 Winning Strategies

🔰 Beginner Tips

🎯 Advanced Techniques

🏅 Pro Tips

✅ Successful Submission

� Forfeiting a Game

� Progress Tracking

🛠️ Development

Prerequisites

Local Development

Smart Contract Tests

Frontend Testing

Environment Variables

Network Configuration

🚀 Deployment

Deploy to Base Mainnet

Deploy to Testnets

Deploy to Vercel

Deploy to Netlify

Other Hosting Options

🤝 Contributing

Getting Started

Code Standards

Areas for Contribution

📄 License

Connect With Us

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages