QuizChain

QuizChain: The High-Stakes Web3 Trivia Arena

1. Project Vision & Introduction QuizChain is a decentralized, real-time competitive trivia platform that transforms casual quizzing into a high-stakes, "skill-to-earn" experience. By integrating Web3 wallets, token-staking, and the high-speed settlement capabilities of the Yellow Network, QuizChain creates a verifiable, incentive-driven ecosystem where knowledge is not just tested—it's rewarded.

Forget ad-supported trivia apps with meaningless points. QuizChain is for the new era of the internet, where players can stake real value on their expertise, compete in sleek, futuristic arenas, and receive instant, on-chain payouts. It’s where the thrill of a game show meets the financial infrastructure of DeFi.

1. The Player Journey: From Lobby to Victory The user experience is designed to be seamless, immersive, and professional, guiding the player from discovery to payout in a few intuitive steps.

Connect & Onboard: The journey begins in a stunning, professionally designed lobby. The UI, built with Next.js 14 and styled with Tailwind CSS, features a dark, futuristic aesthetic with glassmorphism, ambient glows, and subtle grid textures. The first step is to connect a Web3 wallet, powered by RainbowKit, which provides broad support for providers like MetaMask, WalletConnect, and Ledger.

Explore the Arenas: Instead of a boring list, players are greeted with the "Pick Your Arena" showcase—a dynamic grid of quiz categories inspired by modern game platforms like CrazyGames.

Interactive UI: The grid comes alive with a cursor-following radial glow and parallax-effect floating badges (MetaMask, Ledger logos) that drift in the periphery, creating a sense of depth without obstructing the view. Dynamic Filtering: Players can instantly filter categories by playstyle—such as 'Speed Play', 'Strategy', or 'Finance'—with smooth UI updates. Create or Join a Room:

Create a Room: Clicking a category pre-fills the "Room Builder." The host configures the match parameters: the entry fee (e.g., 10 USDC), the token asset, the maximum number of players, and whether the room is public or requires a password. Join a Room: A real-time list of available public rooms is displayed, showing the number of players and the quiz topic. Players can join an open room with a single click or enter a code to access a private match. The Quiz Battle: Once the host starts the game, all participants are seamlessly transitioned into the quiz interface.

Real-Time Sync: The entire game state is synchronized across all clients via a Node.js/Express backend using Socket.IO. Fast-Paced Action: Each question is presented with a tense 10-second timer, demanding quick thinking. Live Leaderboard: A sidebar displays a live-updating leaderboard, showing player scores and rankings as the game progresses. Results & Instant Payout: When the final question is answered, the game concludes and the results view appears.

Personalized Victory/Defeat Banner: A prominent, elegantly styled banner at the top of the screen delivers a personalized message. Winners are greeted with "Congrats, you're the champion! 🎉", while other participants see an encouraging "Better luck next time! 💪". Detailed Rankings: A final, detailed leaderboard displays the rankings, scores, and correct answer counts for all players. On-Chain Payout Receipt: A "Payout Receipt" section provides a transparent summary of the prize distribution, handled by the Yellow Network SDK. It details the winner, the total prize pot, the network, and the transaction status. For the demo, this is simulated, but the architecture is built for live, on-chain settlements.

How QuizChain Was Made: The Nitty-Gritty Details QuizChain was born from a desire to build a Web3 application that is not just functional, but genuinely fun, polished, and professional. Our core philosophy was to use blockchain technology where it shines—verifiable ownership and economic incentives—while leveraging best-in-class web technologies to create a fast, real-time user experience that could rival any Web2 application.

Here’s a deep dive into how we pieced it all together.

1. The Architectural Blueprint: A Decoupled, Real-Time System From the outset, we decided on a decoupled architecture:

A Modern Frontend: A Next.js 14 application responsible for the entire user experience, from wallet connection to rendering the game board. A Real-Time Backend: A lightweight Node.js/Express server acting as the central authority for game logic, state management, and real-time communication. This separation allowed us to iterate on the complex, interactive UI independently while building a robust, centralized engine to keep all players in sync.

1. The Technology Stack & How It's Pieced Together Frontend: The Interactive Experience Layer

Framework & Language: We chose Next.js 14 (App Router) with TypeScript. This gave us a powerful foundation with React Server Components, a file-based router, and the type safety needed to manage complex state objects like game rooms and player data.

Styling: The futuristic, professional aesthetic was achieved with Tailwind CSS. We went beyond the defaults, defining a custom dark theme, using elegant fonts (Plus Jakarta Sans for UI, JetBrains Mono for data), and implementing glassmorphism (backdrop-blur) and subtle glows to create a premium feel.

Web3 Integration (The Wallet Layer):

We used wagmi and RainbowKit to handle wallet interactions. This was a massive accelerator. RainbowKit provided a beautiful, out-of-the-box "Connect Wallet" modal, while wagmi's React hooks made it incredibly simple to get the connected user's address, which was crucial for identifying players. Real-Time State Management:

The frontend's "nervous system" is a custom React Context (BackendProvider). This context initializes and manages the Socket.IO client instance. useEffect hooks are used extensively to listen for events emitted from the backend (e.g., game:question, game:ended). When an event is received, the hook updates the component's state using useState, triggering a UI re-render. For example, when a game:question event arrives, the currentQuestion state is updated, and the UI seamlessly transitions to show the new question and options. Backend: The Central Game Orchestrator

Framework & Real-Time Layer: We built the backend with Node.js and Express, but the star of the show is Socket.IO. It's the backbone of our real-time functionality.

Event-Driven Logic: The backend is entirely event-driven. Handlers listen for client events like room:create or game:submitAnswer. Room Management: Socket.IO's "rooms" feature is used to broadcast events to specific groups of players. When a player joins a room, their socket is added to that room's channel. This ensures that game events are only sent to the players in that specific game. State Authority: The backend is the single source of truth for the game state. It fetches questions, tracks scores, and determines the winner, preventing any client-side cheating. External Service Integration: We used Axios to fetch quiz questions from the external "Aptitude API." This was a strategic choice to decouple our game logic from the content, allowing us to easily add more question sources in the future without changing the core application.

1. Partner Technology Spotlight: The Yellow Network SDK The integration of the Yellow Network SDK was what elevated QuizChain from a simple online game to a true "skill-to-earn" platform.

How It Benefited Our Project: It provided the critical economic layer. Instead of just playing for points, users could play for real stakes. The SDK abstracted away the complexities of blockchain interaction, allowing us to focus on the game experience. Our Integration Point: We created a dedicated YellowProvider context on the frontend. This context handles: Authentication: Connecting the user's wallet to the Yellow Network. State Channel Interaction: The architecture is designed to use Yellow for managing player stakes and enabling instant, low-fee prize settlements, which is a perfect use case for state channels. Instant Payouts: Upon game completion, the backend determines the winner and triggers a payout function that uses the Yellow SDK. This function is responsible for transferring the entire prize pot to the winner's wallet. The results screen even includes a "Payout Receipt" to give the user transparent feedback on this process. Without the Yellow Network, the economic loop would be incomplete. It provided the missing piece for creating a verifiable and rewarding competitive ecosystem.

1. A "Hacky" But Effective Solution: Backend Discovery One notable challenge was connecting the frontend to the backend in a dynamic development environment. The backend could be running on localhost:5000, localhost:5001, or a different origin entirely when deployed.

To solve this, we implemented a "backend discovery" probe in our BackendProvider. Before attempting to connect the socket, the frontend:

Builds a list of candidate URLs (from environment variables, and by scanning http://localhost:5000 through 5009). It then rapidly sends a fetch request to a /health endpoint on each candidate URL with a short timeout. The first candidate to respond with a successful status code is selected as the resolvedBackendUrl, and the Socket.IO connection is established. This "hack" created a resilient connection process that works seamlessly across different developer machines and deployment environments without requiring manual configuration changes, significantly improving the developer experience.