How neu-fi/regen-bingo works
Project Type and Overall Purpose
• This project is a full-stack decentralized application (dApp) with two main parts: a smart contract “backend” (using Hardhat for deployment, testing, and contract management) and a web-based “frontend” (using Next.js, React, wagmi, and RainbowKit for Web3 integration).
• Its core function is to run a trustless Bingo game on-chain, where proceeds fund public goods, with smart contracts handling game logic and randomness (as suggested by integration with Chainlink and VRF components).
File Structure
• There are two main packages: "packages/backend" and "packages/frontend".
• In packages/backend:
– Look for directories like "contracts" (holding the Solidity contracts and subdirectories for different contract sets such as “bokkypoobah” and "chainlink"), "deploy" (multiple deployment scripts with numbered prefixes that indicate sequential deployment steps), "deployments" (containing deployment artifacts for networks such as goerli), and "test" (smart contract tests).
– The Hardhat configurations and environment files (.env, hardhat.config.ts) indicate reliance on the Hardhat framework for contracts management.
• In packages/frontend:
– The directories and files include numerous React components, pages, web3 hooks, and configuration files (e.g., next.config.js, tailwind.config.js), showing a Next.js web application design.
– There’s an explicit link between the frontend and generated contract artifacts (e.g., hardhat_contracts.json) which suggests that the frontend interacts directly with the deployed smart contracts.
Key Components
• Frontend Component:
– The Next.js application with its pages, UI components (e.g., Mint, CardList, Header), and Web3 hooks (for account, network, and contract event watching).
– Integration libraries: wagmi and RainbowKit for wallet connection and blockchain interactions.
• Backend/Deployment Component:
– The Hardhat-based deployment environment that compiles, deploys, and tests the smart contracts.
– Deployment scripts (00_deploy_contract.ts through 04_fund_with_link.ts) indicate sequential tasks such as deploying contracts, minting cards, verifying contracts, and funding with LINK (likely for Chainlink VRF integration).
• Blockchain/Smart Contracts:
– Smart contracts that define game logic (like RegenBingo, RegenBingoMetadata, RegenBingoSVG) and interfaces to external oracles or contracts (Chainlink integrations, VRFCoordinatorV2Mock).
– Deployment artifacts which show that these contracts run on networks like Goerli and are integrated into the dApp.
• External & Integration Components:
– External Web3 services (e.g., Chainlink or similar randomness/oracle services).
– The wallet connection flow in the frontend to allow users to interact with the contracts safely.
Relationships and Interactions
• The user uses the Frontend (browser) which interacts with the smart contracts deployed on the blockchain network via Web3 providers.
• The Frontend communicates with deployed contracts by reading from the provided artifacts (hardhat_contracts.json) and invoking contract functions via the connected wallet.
• The Backend/Deployment scripts use Hardhat to compile, deploy, and verify the smart contracts, and they prepare artifacts that the frontend later consumes.
• External services (e.g., Chainlink VRF) are called by the smart contracts to ensure trustless randomness or other decentralized data inputs if needed.
Architectural Patterns and Design Principles
• Clear separation of concerns: the codebase is split between frontend and smart contract deployment logic.
• Use of layered architecture:
• Deployment Layer (backend package): taking care of contract deployment, configuration, and testing.
• Application Layer (frontend package): presenting the UI and interfacing with the blockchain.
• Blockchain Layer: representing the decentralized, immutable state and business logic.
• Smart contract design is modular, as seen from separate contracts for Bingo game logic and external interfaces.