Bitcoin Price Prediction Mini-Game – Assignment Explanation

Assignment Overview

This project is a hands-on exercise to help you understand how to build a simple decentralized application (dApp) using the Chopin framework, Next.js, and SQLite. The main goal is to create a mini-game where users log in with a blockchain wallet and predict whether the price of Bitcoin will go up or down in the next interval.

What You Will Learn

• How to integrate blockchain wallet authentication into a web app using Chopin
• How to fetch real-time Bitcoin price data from an external API
• How to design a simple prediction game logic in React/Next.js
• How to store and display user scores on a leaderboard using SQLite
• How to build RESTful API endpoints for your app

How the Mini-Game Works

1. Login: Users authenticate with their blockchain wallet (no email/password needed).
2. Prediction: The user predicts if the Bitcoin price will go up or down in the next round.
3. Result: After a short interval, the app fetches the actual price and checks if the prediction was correct.
4. Scoring: Correct predictions earn points. Scores are saved and shown on a public leaderboard.

Technical Stack

• Frontend: Next.js (React), TypeScript
• Authentication: Chopin framework (blockchain wallet login)
• Database: SQLite (for storing scores)
• APIs: Custom Next.js API routes for leaderboard and price data

How to Run the Project

1. Install Node.js and npm if you haven't already.
2. Install dependencies:

   npm install

3. Start the development server:

   npm run dev

4. Open your browser and go to http://localhost:3000

Assignment Focus

This codebase is intentionally simple and focused only on the Bitcoin prediction game. All unrelated features (such as speed test) have been removed for clarity. The goal is to help you learn the core concepts of dApp development in a clean, easy-to-understand way.

---

======= If you have questions about the assignment or want to extend the mini-game, feel free to ask or contribute!

7a48b8e (Rewrite README to focus only on Bitcoin prediction assignment)

Production Architecture

This diagram illustrates the architecture of the application in a production environment, showing how the user's browser, our Next.js application, and the Chopin services interact.

flowchart LR
    A[User's Browser]
    B["Frontend Server
     (Next.js Pages)"]
    
    D["Chopin Service
     (Authentication, Oracle...)"]
    E["Celestia Blockchain"]
    F["Backend
     (Next.js API with Chopin Middleware)"]

    A -- (1. Loads Pages) --> B
    B -- (2. Renders UI) --> A
    
    A -- (4. POST Results) --> B
    B -- (5. API Request) --> F
    F -- (6. Call Oracle.notarize) --> D
    D -- (7. Send blob) --> E
    D -- (3. Login Redirect) --> A

Loading

Production Data Flow

1. Load Page: The user's browser requests the application from the Frontend Server (e.g., Vercel).
2. Render UI: The server sends back the Next.js application, which renders the UI.
3. Login: The user initiates a login. The browser is redirected to the Chopin Service for authentication. After success, Chopin redirects back and sets a secure session cookie in the user's browser.
4. Submit Results: After a prediction, the frontend sends the results in a POST request to our Backend (a Next.js API route).
5. Middleware Intercepts: The Chopin Middleware, configured in our Next.js app, automatically intercepts this incoming request. It validates the session cookie and injects the user's wallet address into the request headers, making it available to our API logic.
6. Notarize: Our backend API handler calls the Oracle.notarize() function. This sends the data to the Chopin Service's Oracle.
7. Commit to Celestia: The Oracle processes the data, notarizes it by posting a commitment to the Celestia Blockchain, and returns the tamper-proof result to our backend.
8. Save to DB: Our backend saves the notarized result to a production-ready Cloud Database (e.g., Vercel Postgres, Neon, etc.).

Getting Started

Follow these instructions to get the project up and running on your local machine.

Prerequisites

• Node.js (v18 or later)
• npm
• Docker

1. Clone the Repository

git clone <repository-url>
cd demo

2. Install Dependencies

Install the necessary Node.js packages for the Next.js application.

npm install

3. Run the Next.js Application

Start the main application's development server. The chopd command is part of the Chopin framework's tooling and runs a local proxy that simulates the Chopin environment, allowing features like wallet authentication to work correctly.

npx chopd

• The application will be available at http://localhost:4000.

Project Structure for Learning

This project has been organized to clearly highlight the core Chopin framework concepts and make them easy to understand and present. Each component focuses on a specific aspect of decentralized application development.

Core Chopin Framework Integration

• src/middleware.ts: The minimal Chopin middleware configuration that enables automatic wallet session management across your entire Next.js application.
• src/app/prediction/page.tsx: The main page for the Bitcoin prediction mini-game, including authentication and game logic.
• src/app/api/leaderboard/route.ts: The backend API route for leaderboard logic.
• src/app/api/price/route.ts: The backend API route for fetching Bitcoin price.

Component Architecture

• src/app/prediction/page.tsx: The main page component, showing authentication, prediction, and leaderboard.

Business Logic and Utilities

• src/lib/database.ts: SQLite database operations for local development and data persistence.

Database and Infrastructure

• src/lib/database.ts: SQLite database operations for local development and data persistence.