{"id":29763921,"url":"https://github.com/hamzoo0/chainwin","last_synced_at":"2026-04-08T18:02:23.222Z","repository":{"id":306595412,"uuid":"1007153300","full_name":"HAMZOO0/ChainWin","owner":"HAMZOO0","description":"A fully decentralized and automated lottery DApp using Solidity, Hardhat, and Chainlink VRF + Automation. Users enter by paying ETH, and a random winner is picked \u0026 rewarded automatically without any manual intervention.","archived":false,"fork":false,"pushed_at":"2025-07-27T21:44:46.000Z","size":9732,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-06T05:43:56.414Z","etag":null,"topics":["blockchain-technology","chai","chainlink","chianlink","dapp","fullstack-development","hardhat","mocha-tests","netify","nextjs","reactjs","smartcontracts","solidity","tailwindcss","web3"],"latest_commit_sha":null,"homepage":"https://imaginative-creponne-075b15.netlify.app/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/HAMZOO0.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-23T14:41:49.000Z","updated_at":"2025-07-29T11:22:01.000Z","dependencies_parsed_at":"2025-07-26T18:41:03.908Z","dependency_job_id":null,"html_url":"https://github.com/HAMZOO0/ChainWin","commit_stats":null,"previous_names":["hamzoo0/chainwin"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/HAMZOO0/ChainWin","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HAMZOO0%2FChainWin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HAMZOO0%2FChainWin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HAMZOO0%2FChainWin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HAMZOO0%2FChainWin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/HAMZOO0","download_url":"https://codeload.github.com/HAMZOO0/ChainWin/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HAMZOO0%2FChainWin/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31567227,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-08T14:31:17.711Z","status":"ssl_error","status_checked_at":"2026-04-08T14:31:17.202Z","response_time":54,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["blockchain-technology","chai","chainlink","chianlink","dapp","fullstack-development","hardhat","mocha-tests","netify","nextjs","reactjs","smartcontracts","solidity","tailwindcss","web3"],"created_at":"2025-07-26T22:42:18.897Z","updated_at":"2026-04-08T18:02:23.197Z","avatar_url":"https://github.com/HAMZOO0.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🎟️ Decentralized Lottery DApp\n\n\u003e 🟢 **Live Demo Deployed at:** [https://imaginative-creponne-075b15.netlify.app/](https://imaginative-creponne-075b15.netlify.app/)\n\nThis is a fully decentralized lottery smart contract built with Solidity and Hardhat. It allows users to buy lottery tickets and automatically picks a random winner using Chainlink VRF (Verifiable Random Function) and Chainlink Automation (Keepers).\n\n\n\n\n## 🚀 Features\n\n✅ Users can buy tickets by paying a fixed entrance fee  \n✅ Random winner picked using Chainlink VRF  \n✅ Automated winner selection using Chainlink Automation (no need for manual trigger)  \n✅ Fund transfer to the winner  \n✅ Built for Ethereum-compatible testnets (e.g., Sepolia)\n\n---\n\n## 🛠 Tech Stack\n\n| Technology | Use |\n|------------|-----|\n| Solidity   | Smart Contract |\n| Hardhat    | Development Framework |\n| Chainlink VRF | Verifiable Randomness |\n| Chainlink Automation (Keepers) | Automated execution |\n| Ethers.js  | Web3 Interactions (optional frontend) |\n\n---\n\n\n\n## 📂 Project Structure\n```\n.\n├── ChainWin/\n│   ├── frontend/               # Contains the Next.js frontend application.\n│   │   ├── public/             # Static assets for the frontend.\n│   │   ├── src/                # Source code for the Next.js application.\n│   │   │   ├── app/            # Main application pages and components.\n│   │   │   ├── constants/      # ABI and contract addresses.\n│   │   │   └── lib/            # Wagmi configuration.\n│   │   ├── .next/              # Next.js build output.\n│   │   ├── node_modules/       # Frontend dependencies.\n│   │   └── ...                 # Configuration files (tailwind, postcss, etc.)\n│   │\n│   └── smart-contracts/        # Contains the Hardhat smart contracts project.\n│       ├── contracts/          # Solidity smart contracts (Lottery.sol).\n│       ├── deploy/             # Scripts for deploying contracts.\n│       ├── deployments/        # Deployment artifacts for different networks.\n│       ├── script/             # Helper scripts for interacting with contracts.\n│       ├── test/               # Contract tests (unit and staging).\n│       ├── artifacts/          # Contract compilation artifacts.\n│       ├── cache/              # Hardhat cache.\n│       ├── node_modules/       # Backend dependencies.\n│       └── ...                 # Configuration files (hardhat.config.js, etc.)\n│\n├── .git/                       # Git version control directory.\n└── README.md                   # This file.\n```\n\n\n\n---\n\n## ⚙️ How It Works\n\n### 🎫 1. Buying a Ticket\n\nAnyone can call `buyTicket()` and send the required ETH. Their address is added to the players list.\n\n### 🎲 2. Request Random Winner (Chainlink VRF)\n\nThe contract uses Chainlink VRF to request a random number. This happens **automatically** using Chainlink Keepers (Automation).\n\n- **How to Use VRF in This Project:**\n  - Deploy your contract and note the address.\n  - Go to [Chainlink VRF Subscription Manager](https://vrf.chain.link/sepolia)\n  - Create a subscription and fund it with Sepolia ETH or LINK.\n  - Add your deployed contract as a consumer.\n  - Get your Subscription ID, Key Hash, and VRF Coordinator Address (from Chainlink docs).\n  - Update your contract or deployment scripts with these values.\n\n### 🤖 3. Chainlink Automation (Keepers)\n\n- Chainlink Keepers (Automation) regularly call `checkUpkeep()` off-chain to check:\n  - Enough time passed (e.g., 1 min)\n  - At least 1 player entered\n  - Contract has ETH balance\n- If true, it triggers `performUpkeep()`, which requests a random number from VRF.\n\n- **How to Use Automation in This Project:**\n  - Visit [Chainlink Automation App](https://automation.chain.link/)\n  - Register your contract as a Keeper job.\n  - Provide your contract address, gas limit, and time interval (e.g., 60 sec).\n  - Keep your subscription funded.\n\n### 🎉 4. Winner Selection\n\n- Chainlink VRF gets triggered by `requestRandomWords()`\n- After a few blocks, it calls `fulfillRandomWords()` with a random number\n- A random player is selected and sent the prize.\n\n---\n\n## 🧾 Functions Overview\n\n| Function | Description |\n|----------|-------------|\n| `buyTicket()` | Pay and enter the lottery |\n| `requestRandomWinner()` | Internal: Called by `performUpkeep()` |\n| `fulfillRandomWords()` | Called by Chainlink VRF with randomness |\n| `checkUpkeep()` | Called by Chainlink Keeper to check conditions |\n| `performUpkeep()` | Calls `requestRandomWinner()` if needed |\n\n---\n\n## ⚙️ System Workflow\n\nThe lottery operates in a cyclical, automated fashion. Here’s a step-by-step breakdown of the process from a player entering to a winner being chosen.\n\n### 1. Player Buys a Ticket\n\nA user calls the `buyTicket()` function and sends the required `entranceFee` in ETH. Their address is then added to the list of players for the current round.\n\n![Player buying a ticket on Etherscan](pics/image-2.png)\n\n### 2. Chainlink Automation Triggers the Draw\n\nChainlink Automation (Keepers) continuously monitor the contract off-chain by calling `checkUpkeep()`. The upkeep is performed if the following conditions are met:\n- The lottery state is `OPEN`.\n- A specific time interval has passed since the last draw.\n- There is at least one player in the lottery.\n- The contract has a balance to pay the winner.\n\nWhen these conditions are true, the Keeper calls `performUpkeep()`, which begins the process of selecting a winner.\n\n![Chainlink Automation job executing](pics/image.png)\n\n### 3. Requesting a Random Number via Chainlink VRF\n\nThe `performUpkeep()` function requests one or more random numbers from the Chainlink VRF Coordinator. This is a secure, on-chain request for verifiable randomness.\n\n![VRF call transaction on Etherscan](pics/image-1.png)\n\n### 4. Winner Selection and Payout\n\nAfter a few blocks, the Chainlink VRF Coordinator responds by calling the `fulfillRandomWords()` function in our contract, delivering the random number. This function then performs the final steps:\n1.  Uses the random number to select a `recentWinner` from the array of players.\n2.  Transfers the entire contract balance (the prize pool) to the winner.\n3.  Resets the lottery state, clearing the players list and opening it for a new round.\n\n---\n\n\n## 📦 Installation\n\n```bash\ngit clone https://github.com/HAMZOO0/lottery-dapp\ncd lottery-dapp\nnpm install\n```\n\n---\n\n🔐 **.env Setup**\n\nCreate a `.env` file in the root directory:\n\n```\nPRIVATE_KEY=your_private_key\nSEPOLIA_RPC_URL=https://sepolia.infura.io/v3/your_project_id\nETHERSCAN_API_KEY=your_etherscan_key\n```\n\n---\n\n## 📤 Deploy to Sepolia\n\n```bash\nnpx hardhat compile\nnpx hardhat run scripts/deploy.js --network sepolia\n```\n\n---\n\n## 🔗 Chainlink Setup\n\n### ✅ VRF Setup\n\n- Go to [Chainlink VRF Subscription Manager](https://vrf.chain.link/sepolia)\n- Create a subscription and fund it with Sepolia ETH or LINK\n- Add your deployed contract as a consumer\n- Get:\n  - Subscription ID\n  - Key Hash (from docs)\n  - VRF Coordinator Address\n- Update your contract/deployment scripts with these values\n\n![Chainlink VRF V2 Setup](pics/vrf2.png)\n\n### ✅ Automation (Keepers) Setup\n\n- Visit [Chainlink Automation App](https://automation.chain.link/)\n- Register your contract\n- Provide:\n  - Your contract address\n  - Gas limit\n  - Time interval (e.g., 60 sec)\n- Keep your subscription funded\n\n---\n\n## 📜 NPM Scripts\n\nThe following scripts are available in the `package.json` for managing and testing your smart contracts:\n\n| Script                 | Description                                 |\n|------------------------|---------------------------------------------|\n| `npm test`             | Run all unit tests with Hardhat              |\n| `npm run test:staging` | Run tests on the Sepolia testnet             |\n| `npm run test:local`   | Run tests on a local Hardhat/localhost node  |\n| `npm run coverage`     | Generate a Solidity code coverage report     |\n\nYou can run these scripts from the root of your project. For example:\n\n```bash\nnpm run test:staging\n```\n\n---\n\n## 🖥️ Frontend\n\nYou can add your frontend code in the `frontend/` directory. Use JavaScript libraries like ethers.js or web3.js to connect to the deployed contract.\n\n---\n\n## 📸 Screenshots\n\n![alt text](image.png)\n\n![alt text](image-1.png)\n\n![ ](image-2.png)\n---\n\n## 📚 Resources\n\n- [Chainlink VRF Docs](https://docs.chain.link/vrf/v2/introduction/)\n- [Chainlink Automation Docs](https://docs.chain.link/chainlink-automation/introduction/)\n- [Hardhat Documentation](https://hardhat.org/docs)\n- [Ethers.js Documentation](https://docs.ethers.org/)\n\n---\n\nFeel free to contribute or open issues for improvements!\n\n---\n\n## 📊 Additional Diagrams\n\n### Chainlink VRF Workflow\n![VRF Full Diagram](pics/image-3.png)\n\n### Chainlink Automation (Keepers) Workflow\n![Keepers Diagram](pics/image-4.png)\n  ","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhamzoo0%2Fchainwin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhamzoo0%2Fchainwin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhamzoo0%2Fchainwin/lists"}