Learn & Earn with Blockchain-Powered Education
Live Demo β’ Documentation β’ Report Bug β’ Request Feature
This application has been fully tested and verified to work seamlessly with MiniPay! The app has been tested using the MiniPay Mini App Test tool with ngrok tunneling, ensuring complete compatibility with MiniPay's mobile wallet environment. All features including wallet connection, quiz creation, participation, and cUSD transactions have been verified to work perfectly on MiniPay.
- Overview
- Features
- Architecture
- Getting Started
- User Guide
- Technical Documentation
- Smart Contracts
- Deployment
- Contributing
- Support
Scholaric is a decentralized educational platform built on the Celo blockchain that rewards learners with cUSD (Celo Dollars) for answering quiz questions correctly. Create educational quizzes, fund prize pools, and earn real cryptocurrency rewards while learning.
Built for the Celo MiniPay Hackathon - Educational Games category.
Scholaric is a learn-to-earn platform that combines education with blockchain technology. Students can participate in quizzes on various subjects, answer questions correctly, and earn cUSD rewards. Teachers and content creators can create quizzes, fund prize pools, and build engaging educational experiences.
The platform uses smart contracts on the Celo blockchain to ensure transparent, fair, and secure reward distribution. All quiz data is stored on IPFS (InterPlanetary File System) for decentralization and permanence.
CHECK OUT THE APP DEMO HERE (Kindly click on the below image to see the video)
Traditional education platforms face several challenges:
| Challenge | Impact | Solution |
|---|---|---|
| Lack of Motivation | Low student engagement | Financial incentives via cUSD rewards |
| Limited Accessibility | High costs exclude many students | Free access with blockchain rewards |
| No Transparency | Opaque reward systems | On-chain transparent reward distribution |
| High Transaction Costs | Expensive micro-payments | Low-cost Celo blockchain transactions |
| Geographic Barriers | Currency and payment restrictions | Global access via cryptocurrency |
Scholaric solves these problems through:
- β Blockchain Rewards: Students earn cUSD (stable cryptocurrency) for correct answers, providing real financial motivation
- β Transparent System: All quiz results and rewards are recorded on the blockchain, ensuring fairness
- β Low-Cost Transactions: Built on Celo blockchain with MiniPay support for gas-free transactions
- β Global Access: Anyone with a crypto wallet can participate, regardless of location
- β Decentralized Storage: Quiz content stored on IPFS ensures permanence and accessibility
- β Fair Distribution: Smart contracts automatically distribute rewards based on performance
DO YOU KNOW YOU CAN ALSO FILTER THE QUIZZES HERE FOR BEST UX...
| Feature | Description | Benefit |
|---|---|---|
| Browse Quizzes | Explore a catalogue of educational quizzes on various subjects | Easy discovery of learning opportunities |
| Join Quizzes | Participate in active quizzes by connecting your wallet | Simple onboarding process |
| Answer Questions | Submit answers using a secure commit-reveal pattern | Prevents cheating and ensures fairness |
| Earn Rewards | Receive cUSD rewards based on your quiz performance | Financial motivation to learn |
| View Leaderboards | See how you rank compared to other participants | Gamification and competition |
| Track Rewards | Monitor your earnings and reward history | Transparent reward tracking |
| Feature | Description | Benefit |
|---|---|---|
| Create Quizzes | Build custom quizzes with multiple-choice, true/false, or short-answer questions | Flexible content creation |
| Fund Prize Pools | Add cUSD to quiz prize pools to incentivize participation | Control over reward amounts |
| Manage Quizzes | Set quiz duration, maximum participants, and start times | Full control over quiz parameters |
| View Analytics | Track quiz participation and performance metrics | Data-driven insights |
- Secure Commit-Reveal: Answers are committed as hashes first, then revealed after the quiz ends, preventing cheating
- Proportional Rewards: Rewards are distributed proportionally based on scores
- IPFS Storage: Quiz metadata stored on decentralized IPFS network
- MiniPay Integration: β Fully tested and verified - Seamless wallet connection with MiniPay support, tested using MiniPay Mini App Test tool
- Mobile-First Design: Responsive design optimized for mobile devices
- Real-Time Updates: Live updates on quiz status and participant counts
graph TB
subgraph "Frontend Layer"
A[Next.js Web App] --> B[React Components]
B --> C[Wagmi/Viem]
C --> D[RainbowKit]
end
subgraph "Blockchain Layer"
D --> E[Celo Network]
E --> F[QuizManager Contract]
F --> G[cUSD Token]
end
subgraph "Storage Layer"
A --> H[IPFS Network]
H --> I[Quiz Metadata]
H --> J[Question Data]
end
subgraph "Wallet Integration"
D --> K[MiniPay]
D --> L[MetaMask]
D --> M[WalletConnect]
end
style F fill:#35D07F
style E fill:#35D07F
style K fill:#FFD700
stateDiagram-v2
[*] --> Created: Creator creates quiz
Created --> Upcoming: Quiz scheduled
Upcoming --> Live: Start time reached
Live --> CommitPhase: Participants join
CommitPhase --> RevealPhase: Quiz ends
RevealPhase --> Scoring: Answers revealed
Scoring --> Rewards: Scores calculated
Rewards --> Completed: Rewards distributed
Completed --> [*]
Created --> Cancelled: Creator cancels
Cancelled --> [*]
flowchart TD
Start([User Visits Scholaric]) --> Connect{Connect Wallet}
Connect -->|Success| Dashboard[View Dashboard]
Connect -->|Fail| Start
Dashboard --> Browse[Browse Catalogue]
Browse --> Select{Select Quiz}
Select -->|Join| Join[Join Quiz]
Select -->|Create| Create[Create Quiz]
Join --> Wait[Wait for Start]
Wait --> StartQuiz[Quiz Starts]
StartQuiz --> Answer[Answer Questions]
Answer --> Commit[Commit Answers]
Commit --> WaitEnd[Wait for End]
WaitEnd --> Reveal[Reveal Answers]
Reveal --> Score[Calculate Score]
Score --> Reward[Receive Reward]
Reward --> Claim[Claim cUSD]
Claim --> End([Complete])
Create --> Fund[Fund Prize Pool]
Fund --> Manage[Manage Quiz]
Manage --> End
sequenceDiagram
participant U as User
participant F as Frontend
participant C as Contract
participant IPFS as IPFS
Note over U,IPFS: Quiz Creation Phase
U->>F: Create Quiz
F->>IPFS: Upload Quiz Metadata
IPFS-->>F: Return IPFS Hash
F->>C: createQuiz(ipfsHash)
C-->>F: Quiz Created
Note over U,IPFS: Participation Phase
U->>F: Join Quiz
F->>C: joinQuiz(quizId)
C-->>F: Joined Successfully
Note over U,IPFS: Commit Phase
U->>F: Answer Questions
F->>F: Hash Answers + Salt
F->>C: commitAnswer(quizId, hash)
C-->>F: Answer Committed
Note over U,IPFS: Reveal Phase
U->>F: Reveal Answers
F->>C: revealAnswer(quizId, answers, salt)
C->>C: Verify Hash
C->>C: Calculate Score
C-->>F: Score Calculated
Note over U,IPFS: Reward Phase
C->>C: Distribute Rewards
C-->>F: Rewards Distributed
F->>U: Display Rewards
| Category | Technology | Version | Purpose |
|---|---|---|---|
| Frontend Framework | Next.js | 14 | React framework with App Router |
| Language | TypeScript | 5.2+ | Type-safe JavaScript |
| Styling | Tailwind CSS | Latest | Utility-first CSS framework |
| UI Components | shadcn/ui | Latest | Accessible component library |
| State Management | TanStack Query | Latest | Server state management |
| Blockchain Library | Wagmi | v2 | React hooks for Ethereum |
| Blockchain Utilities | Viem | v2 | TypeScript Ethereum library |
| Wallet Connection | RainbowKit | Latest | Wallet connection UI |
| Form Handling | React Hook Form | Latest | Performant forms |
| Validation | Zod | Latest | Schema validation |
| Icons | Lucide React | Latest | Icon library |
| Blockchain | Celo | Mainnet | Proof-of-stake blockchain |
| Smart Contracts | Solidity | 0.8.20 | Smart contract language |
| Development | Hardhat | Latest | Ethereum development environment |
| Storage | IPFS | - | Decentralized storage |
| Monorepo | Turborepo | Latest | Build system |
| Package Manager | pnpm | 8.0+ | Fast package manager |
| Deployment | Vercel | - | Frontend hosting |
Frontend Stack:
βββ Next.js 14 (App Router)
β βββ Server Components
β βββ Client Components
β βββ API Routes
βββ TypeScript
β βββ Type Safety
βββ Tailwind CSS
β βββ Utility-first Styling
βββ shadcn/ui
β βββ Radix UI Components
βββ State Management
βββ React Query (Server State)
βββ React Context (Client State)
Blockchain Stack:
βββ Wagmi v2
β βββ React Hooks for Ethereum
βββ Viem v2
β βββ TypeScript Ethereum Library
βββ RainbowKit
β βββ Wallet Connection UI
βββ Celo Network
βββ Mainnet (Production)
βββ Testnets (Development)
| Requirement | Version | Purpose |
|---|---|---|
| Node.js | β₯18.0.0 | JavaScript runtime |
| pnpm | β₯8.0.0 | Package manager |
| Git | Latest | Version control |
| Crypto Wallet | - | MetaMask, WalletConnect, or MiniPay |
git clone https://github.com/adamstosho/Scholaric.git
cd Scholaricpnpm installCreate a .env.local file in the apps/web directory:
cd apps/web
cp .env.example .env.localFill in the required environment variables (see Environment Variables section).
# From the root directory
pnpm devThe app will be available at http://localhost:3000
cd apps/contractsCreate a .env file:
PRIVATE_KEY=your_private_key_here
CELOSCAN_API_KEY=your_celoscan_api_key # optionalpnpm compilepnpm testpnpm deploy:sepolia
# OR
pnpm deploy:alfajoresflowchart LR
A[1. Connect Wallet] --> B[2. Browse Quizzes]
B --> C[3. Join Quiz]
C --> D[4. Answer Questions]
D --> E[5. Commit Answers]
E --> F[6. Reveal Answers]
F --> G[7. Claim Rewards]
Step-by-Step Instructions:
-
Connect Your Wallet
- Click the "Connect Wallet" button on the homepage
- Choose your wallet (MetaMask, WalletConnect, or MiniPay)
- Approve the connection request
- You'll be redirected to your dashboard
-
Browse Available Quizzes
- Click "Catalogue" in the navigation menu
- Browse through available quizzes
- Use filters to find quizzes by subject, difficulty, or status
- Each quiz shows:
- Subject and difficulty level
- Prize pool amount
- Number of participants
- Start time and duration
-
Join a Quiz
- Click on a quiz you want to join
- Review the quiz details
- Click "Join Quiz" button
- Confirm the transaction in your wallet
- Wait for the quiz to start
-
Take the Quiz
- Once the quiz starts, you'll see the questions
- Select your answers for each question
- Click "Commit Answers" to submit (answers are hashed for security)
- Wait for the quiz to end
-
Reveal Your Answers
- After the quiz ends, click "Reveal Answers"
- Your score will be calculated automatically
- Rewards will be distributed based on your performance
-
Claim Your Rewards
- Go to the "Rewards" page
- View your earned rewards
- Click "Claim" to receive cUSD in your wallet
Step-by-Step Instructions:
-
Create a New Quiz
- Click "Create Quiz" in the navigation menu
- Fill in the quiz details:
- Title and description
- Subject and difficulty
- Grade level
- Start time and duration
- Maximum number of participants
- Add questions:
- Question text
- Answer options (for multiple choice)
- Correct answer
- Click "Create Quiz"
- Confirm the transaction
-
Fund the Prize Pool
- After creating a quiz, you can add funds to the prize pool
- Click "Fund Quiz" on the quiz page
- Enter the amount of cUSD you want to add
- Confirm the transaction
- The prize pool will be updated
-
Manage Your Quiz
- View quiz statistics on your dashboard
- Monitor participant count
- End the quiz early if needed (only creator can do this)
| Page | Description | Access |
|---|---|---|
| Home | Landing page with features and information | / |
| Catalogue | Browse all available quizzes | /catalogue |
| Dashboard | Your personal dashboard with quiz history | /dashboard |
| Create | Create a new quiz | /create |
| Leaderboard | View top performers across all quizzes | /leaderboard |
| Rewards | View and claim your earned rewards | /rewards |
Scholaric/
βββ apps/
β βββ web/ # Next.js frontend application
β β βββ src/
β β β βββ app/ # Next.js app router pages
β β β β βββ catalogue/ # Quiz catalogue page
β β β β βββ create/ # Quiz creation page
β β β β βββ dashboard/ # User dashboard
β β β β βββ leaderboard/ # Leaderboard page
β β β β βββ quiz/ # Quiz pages (join, session, results)
β β β β βββ rewards/ # Rewards page
β β β βββ components/ # React components
β β β β βββ ui/ # shadcn/ui components
β β β β βββ ... # Custom components
β β β βββ hooks/ # Custom React hooks
β β β βββ lib/ # Utility functions and contracts
β β β β βββ contracts/ # Contract ABIs and addresses
β β β β βββ utils/ # Helper functions
β β β βββ styles/ # Global styles
β β βββ public/ # Static assets
β β βββ package.json
β β
β βββ contracts/ # Smart contracts
β βββ contracts/ # Solidity contract files
β β βββ QuizManager.sol # Main contract
β β βββ libraries/ # Contract libraries
β βββ test/ # Contract tests
β βββ scripts/ # Deployment scripts
β βββ hardhat.config.ts # Hardhat configuration
β
βββ package.json # Root package.json
βββ turbo.json # Turborepo configuration
βββ pnpm-workspace.yaml # pnpm workspace config
βββ README.md # This file
All contracts deployed to Celo Mainnet (Chain ID: 42220) are listed below.
| Contract Name | Address | Deployer | Block Number | Deployment Date | Explorer |
|---|---|---|---|---|---|
| QuizManager | 0x1469beF9638eE24Bdb39835fD3429D45F7833827 |
0x1A0A85fd9E79562e85A0861c509E0c2239a6d0D5 |
53,563,768 | 2025-12-11 | View on Celoscan |
| Contract | Status | Verified |
|---|---|---|
| QuizManager | β Deployed | β Verified |
These are existing Celo mainnet token contracts used by the platform:
| Token | Address | Symbol | Purpose |
|---|---|---|---|
| cUSD | 0x765de816845861e75a25fca122bb6898b8b1282a |
cUSD | Primary reward token |
| USDC | 0xcebA9300f2b948710d2653dD7B07f33A8B32118C |
USDC | Alternative stablecoin |
| USDT | 0x48065fbBE25f71C9282ddf5e1cD6D6A887483D5e |
USDT | Alternative stablecoin |
Note: Token contracts are existing Celo mainnet contracts and are not deployed by this project.
The main smart contract that handles all quiz operations on the Celo blockchain.
| Property | Value |
|---|---|
| Network | Celo Mainnet |
| Chain ID | 42220 |
| Address | 0x1469beF9638eE24Bdb39835fD3429D45F7833827 |
| Explorer | View on Celoscan |
| Solidity Version | 0.8.20 |
| License | MIT |
| Deployment Block | 53,563,768 |
| Deployment Date | December 11, 2025 |
| Function | Description | Access Control |
|---|---|---|
createQuiz() |
Create a new quiz with metadata | Public |
fundQuiz() |
Add funds to a quiz prize pool | Public |
joinQuiz() |
Join an active quiz | Public |
commitAnswer() |
Submit answer hash (commit phase) | Participant only |
revealAnswer() |
Reveal answers and calculate score | Participant only |
distributeRewards() |
Distribute rewards to participants | Public |
endQuiz() |
End a quiz early | Creator only |
cancelQuiz() |
Cancel a quiz and refund participants | Creator only |
pause() |
Pause contract operations | Owner only |
unpause() |
Unpause contract operations | Owner only |
| Feature | Description |
|---|---|
| Commit-Reveal Pattern | Prevents cheating by hiding answers until quiz ends |
| Access Control | Only quiz creators can end or cancel their quizzes |
| Pausable | Contract can be paused by owner in case of emergencies |
| Reentrancy Protection | Protected against reentrancy attacks using OpenZeppelin's ReentrancyGuard |
| Ownable | Contract ownership for administrative functions |
sequenceDiagram
participant Creator
participant Participant
participant Contract
participant IPFS
Creator->>IPFS: Upload Quiz Metadata
IPFS-->>Creator: Return IPFS Hash
Creator->>Contract: createQuiz(ipfsHash, params)
Contract-->>Creator: Quiz Created (Event)
Creator->>Contract: fundQuiz(quizId, amount)
Contract-->>Creator: Prize Pool Funded
Participant->>Contract: joinQuiz(quizId)
Contract-->>Participant: Joined Successfully
Participant->>Contract: commitAnswer(quizId, hash)
Contract-->>Participant: Answer Committed
Note over Contract: Quiz Ends
Participant->>Contract: revealAnswer(quizId, answers, salt)
Contract->>Contract: Verify & Calculate Score
Contract-->>Participant: Score Calculated
Contract->>Contract: distributeRewards(quizId)
Contract-->>Participant: Rewards Distributed
| Variable | Description | Example |
|---|---|---|
NEXT_PUBLIC_QUIZ_MANAGER_ADDRESS |
Smart contract address on Celo | 0x1469beF9638eE24Bdb39835fD3429D45F7833827 |
NEXT_PUBLIC_CHAIN_ID |
Celo network chain ID | 42220 (Mainnet) |
NEXT_PUBLIC_NETWORK_NAME |
Network name | Celo Mainnet |
NEXT_PUBLIC_EXPLORER_URL |
Block explorer URL | https://celoscan.io |
NEXT_PUBLIC_WEB3_STORAGE_TOKEN |
Web3.Storage API token | eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... |
NEXT_PUBLIC_IPFS_GATEWAY |
IPFS gateway URL | https://ipfs.io/ipfs/ |
| Variable | Description | Example |
|---|---|---|
NEXT_PUBLIC_WC_PROJECT_ID |
WalletConnect Project ID | your_project_id |
NEXT_PUBLIC_PINATA_JWT_TOKEN |
Pinata JWT token (alternative to Web3.Storage) | eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... |
NEXT_PUBLIC_APP_NAME |
Application name | Scholaric |
NEXT_PUBLIC_APP_URL |
Application URL | http://localhost:3000 |
NEXT_PUBLIC_ENV |
Environment | development or production |
| Variable | Description | Required |
|---|---|---|
PRIVATE_KEY |
Private key for contract deployment | Yes |
CELOSCAN_API_KEY |
Celoscan API key for contract verification | No |
- Visit web3.storage
- Sign up for a free account
- Create an API token
- Copy and paste into
NEXT_PUBLIC_WEB3_STORAGE_TOKEN
- Visit cloud.walletconnect.com
- Create a new project
- Copy the Project ID
- Paste into
NEXT_PUBLIC_WC_PROJECT_ID
- Visit pinata.cloud
- Sign up for an account
- Generate a JWT token
- Paste into
NEXT_PUBLIC_PINATA_JWT_TOKEN
| Step | Task | Status |
|---|---|---|
| 1 | Set up environment variables | β¬ |
| 2 | Deploy smart contracts | β¬ |
| 3 | Verify smart contracts | β¬ |
| 4 | Update frontend contract address | β¬ |
| 5 | Deploy frontend | β¬ |
| 6 | Test all features | β¬ |
| 7 | Update documentation | β¬ |
git push origin main- Go to vercel.com
- Click "Add New Project"
- Import your GitHub repository
- Set Root Directory to
apps/web - Add all environment variables
- Click "Deploy"
| Setting | Value |
|---|---|
| Framework | Next.js (auto-detected) |
| Build Command | pnpm build |
| Install Command | pnpm install |
| Root Directory | apps/web |
cd apps/contracts
pnpm deploy:celopnpm verify --network celo- Update
NEXT_PUBLIC_QUIZ_MANAGER_ADDRESSin.env.localwith the new contract address - Ensure
NEXT_PUBLIC_CHAIN_ID=42220for mainnet
For testnet deployments, use:
# Celo Alfajores Testnet
pnpm deploy:alfajores
# Celo Sepolia Testnet
pnpm deploy:sepolia# Run linting
pnpm lint
# Type checking
pnpm type-check
# Build for production
pnpm buildcd apps/contracts
# Run all tests
pnpm test
# Run tests with coverage
pnpm test --coverage
# Run specific test file
pnpm test test/QuizManager.test.ts| Component | Target Coverage |
|---|---|
| Smart Contracts | β₯90% |
| Frontend Components | β₯80% |
| Utility Functions | β₯85% |
We welcome contributions! Please follow these steps:
-
Fork the repository
git clone https://github.com/your-username/Scholaric.git
-
Create a feature branch
git checkout -b feature/amazing-feature
-
Make your changes
- Write clean, documented code
- Add tests for new features
- Update documentation as needed
-
Commit your changes
git commit -m 'Add some amazing feature' -
Push to the branch
git push origin feature/amazing-feature
-
Open a Pull Request
- Provide a clear description
- Reference any related issues
- Wait for code review
| Guideline | Description |
|---|---|
| TypeScript | Follow TypeScript best practices and use strict mode |
| Formatting | Use ESLint and Prettier for code formatting |
| Commits | Write meaningful commit messages following conventional commits |
| Tests | Add tests for new features and ensure existing tests pass |
| Documentation | Update README and code comments for new features |
graph LR
A[Fork Repo] --> B[Create Branch]
B --> C[Make Changes]
C --> D[Write Tests]
D --> E[Commit]
E --> F[Push]
F --> G[Create PR]
G --> H[Code Review]
H --> I{Merge?}
I -->|Yes| J[Merge]
I -->|No| C
This project is licensed under the MIT License - see the LICENSE file for details.
- Celo Foundation for the blockchain infrastructure
- Celo Africa DAO for hosting the hackathon
- MiniPay for seamless mobile wallet integration
- IPFS for decentralized storage
- All open-source contributors whose libraries made this project possible
| Channel | Link |
|---|---|
| GitHub Issues | Create an issue |
| omoridoh111@gmail.com | |
| Documentation | See Documentation |
If you find a bug, please create an issue with:
- Description of the bug
- Steps to reproduce
- Expected behavior
- Actual behavior
- Screenshots (if applicable)
Have an idea? Create a feature request with:
- Description of the feature
- Use case
- Proposed implementation (optional)
β TESTED AND VERIFIED ON MINIPAY
This application has been thoroughly tested using the MiniPay Mini App Test tool with ngrok tunneling. All core functionalities including wallet connection, quiz operations, and cUSD transactions have been verified to work seamlessly on MiniPay.
- Event: Celo MiniPay Hackathon
- Category: Educational Games
- Status: β Completed
- Verification: β MiniPay Tested








