Skip to content

Commit 99f61d9

Browse files
lzmrdlzmrd
committed
Add Social Pot lottery example using Pyth Entropy
1 parent b48bc74 commit 99f61d9

File tree

1,066 files changed

+179097
-0
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

1,066 files changed

+179097
-0
lines changed

‎entropy/theSocialPot/.gitignore‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
# Dependencies
2+
node_modules/
3+
package-lock.json
4+
5+
# Build artifacts
6+
**/artifacts/
7+
**/cache/
8+
**/typechain-types/
9+
**/coverage/
10+
11+
# Environment variables
12+
.env
13+
.env.local
14+
.env.*.local
15+
16+
# IDE
17+
.vscode/
18+
.idea/
19+
*.swp
20+
*.swo
21+
*~
22+
23+
# OS
24+
.DS_Store
25+
Thumbs.db
26+
27+
# Logs
28+
*.log
29+
npm-debug.log*
30+

‎entropy/theSocialPot/README.md‎

Lines changed: 308 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,308 @@
1+
# The Social Pot 🍀
2+
3+
> **WIN. GIVE. GROW.**
4+
5+
A revolutionary blockchain lottery that combines winning, earning, and social impact. Buy tickets, win daily drawings, receive guaranteed monthly payments for 10 years, and help finance social projects addressing global crises.
6+
7+
## 🌟 Overview
8+
9+
**The Social Pot** is a decentralized lottery built on Base blockchain that offers:
10+
11+
- **Daily Drawings**: New winner selected every day at midnight UTC using provably fair randomness from Pyth Entropy
12+
- **10-Year Monthly Payouts**: Winners receive guaranteed monthly payments for 120 months through Aave lending protocol
13+
- **Social Impact**: Interest generated from funds (~$7M annually) finances projects addressing:
14+
- 🏥 **Health Crisis**: Medical facilities, healthcare access, emergency response
15+
- 🏠 **Housing Crisis**: Affordable housing, shelter programs, housing assistance
16+
- 🍽️ **Food Crisis**: Food banks, nutrition programs, sustainable agriculture
17+
18+
## 🎯 Key Features
19+
20+
### For Players
21+
- **Low Entry Cost**: Just 1 USDC per ticket
22+
- **Daily Chances**: New drawing every day at midnight UTC
23+
- **Referral Rewards**: Earn 30% commission on tickets sold through your referral link
24+
- **Transparent & Fair**: Powered by Pyth Entropy for verifiable randomness
25+
- **Long-Term Income**: Monthly payments for 10 years (120 months)
26+
27+
### For Winners
28+
- **Instant First Payment**: Receive 1/120th of jackpot immediately
29+
- **Monthly Payouts**: Receive your payment each month for the next 119 months
30+
- **Growing Returns**: Funds deposited on Aave generate interest, increasing your total payout
31+
- **Social Impact**: Your winnings help fund critical social projects
32+
33+
## 🏗️ Architecture
34+
35+
### Smart Contracts
36+
37+
```
38+
MegaYieldLottery.sol
39+
├── Manages daily lottery drawings
40+
├── Integrates with Pyth Entropy for randomness
41+
├── Handles ticket purchases and jackpot distribution
42+
└── Coordinates with MegaYieldVesting for payouts
43+
44+
MegaYieldVesting.sol
45+
├── Manages 10-year monthly vesting schedule
46+
├── Integrates with Aave for lending
47+
└── Handles monthly payment claims
48+
49+
PythIntegration.sol
50+
└── Wrapper for Pyth Entropy V2 API
51+
52+
AaveIntegration.sol
53+
└── Wrapper for Aave V3 lending protocol
54+
```
55+
56+
### Technology Stack
57+
58+
**Backend:**
59+
- Solidity ^0.8.24
60+
- Foundry (testing & deployment)
61+
- Hardhat (development)
62+
- OpenZeppelin Contracts
63+
- Pyth Entropy SDK
64+
- Aave V3 Core
65+
66+
**Frontend:**
67+
- Next.js 16
68+
- React 19
69+
- TypeScript
70+
- Wagmi v3 (Web3 integration)
71+
- Viem (Ethereum utilities)
72+
- Tailwind CSS
73+
- Radix UI
74+
75+
**Blockchain:**
76+
- Base Sepolia (testnet)
77+
- Base Mainnet (production)
78+
- Pyth Entropy smart contracts
79+
80+
## 📋 Prerequisites
81+
82+
- Node.js 18+ and npm
83+
- Foundry (for contract testing)
84+
- A Web3 wallet (MetaMask recommended)
85+
- USDC tokens on Base Sepolia/Base
86+
87+
## 🚀 Getting Started
88+
89+
### Backend Setup
90+
91+
```bash
92+
cd backend
93+
94+
# Install dependencies
95+
npm install
96+
97+
# Install Foundry (if not already installed)
98+
curl -L https://foundry.paradigm.xyz | bash
99+
foundryup
100+
101+
# Compile contracts
102+
forge build
103+
# or
104+
npm run compile
105+
106+
# Run tests
107+
forge test
108+
# or
109+
npm test
110+
```
111+
112+
### Frontend Setup
113+
114+
```bash
115+
cd frontend
116+
117+
# Install dependencies
118+
npm install
119+
120+
# Run development server
121+
npm run dev
122+
123+
# Build for production
124+
npm run build
125+
```
126+
127+
### Environment Variables
128+
129+
Create a `.env` file in the `backend` directory:
130+
131+
```env
132+
BASE_SEPOLIA_RPC_URL=https://sepolia.base.org
133+
PRIVATE_KEY=your_private_key_here
134+
ETHERSCAN_API_KEY=your_etherscan_api_key
135+
```
136+
137+
## 📁 Project Structure
138+
139+
```
140+
megaYield/
141+
├── backend/
142+
│ ├── contracts/ # Smart contracts
143+
│ │ ├── MegaYieldLottery.sol
144+
│ │ ├── MegaYieldVesting.sol
145+
│ │ ├── PythIntegration.sol
146+
│ │ └── AaveIntegration.sol
147+
│ ├── test/ # Test files
148+
│ │ ├── MegaYieldLottery.test.ts
149+
│ │ ├── PythReal.t.sol
150+
│ │ └── PythVerification.t.sol
151+
│ ├── script/ # Deployment scripts
152+
│ │ └── DeployLottery.s.sol
153+
│ └── config/ # Configuration
154+
│ └── addresses.ts
155+
│
156+
└── frontend/
157+
├── src/
158+
│ ├── app/ # Next.js pages
159+
│ ├── components/ # React components
160+
│ ├── hooks/ # Custom hooks
161+
│ ├── lib/ # Utilities
162+
│ └── config/ # Frontend config
163+
└── public/ # Static assets
164+
```
165+
166+
## 🎮 How It Works
167+
168+
### 1. Buy Tickets
169+
- Purchase tickets for 1 USDC each
170+
- Use a referral code to support friends (they get 30% commission)
171+
- 70% goes to jackpot, 30% to referrals
172+
173+
### 2. Daily Drawing
174+
- Every day at midnight UTC, a winner is selected
175+
- Uses Pyth Entropy for provably fair randomness
176+
- Winner receives first payment immediately (1/120th of jackpot)
177+
178+
### 3. Monthly Payouts
179+
- Remaining funds deposited on Aave lending protocol
180+
- Winner can claim monthly payment for 119 months
181+
- Interest generated increases total payout over time
182+
183+
### 4. Social Impact
184+
- Interest from Aave deposits (~$7M annually) funds social projects
185+
- Projects address health, housing, and food crises
186+
- 100% of interest goes to verified social initiatives
187+
188+
## 🔐 Security
189+
190+
- **Provably Fair**: Pyth Entropy provides verifiable randomness
191+
- **Audited Libraries**: Uses OpenZeppelin's battle-tested contracts
192+
- **Reentrancy Protection**: ReentrancyGuard on critical functions
193+
- **Ownable**: Owner-only functions for administrative tasks
194+
- **SafeERC20**: Safe token transfers using OpenZeppelin's SafeERC20
195+
196+
## 🧪 Testing
197+
198+
### Foundry Tests
199+
200+
```bash
201+
# Run all tests
202+
forge test
203+
204+
# Run specific test
205+
forge test --match-test testPythRealRandomNumber
206+
207+
# Run with fork (requires RPC URL)
208+
forge test --fork-url https://sepolia.base.org
209+
```
210+
211+
### Hardhat Tests
212+
213+
```bash
214+
npm test
215+
```
216+
217+
## 📦 Deployment
218+
219+
### Deploy to Base Sepolia
220+
221+
```bash
222+
cd backend
223+
224+
# Using Foundry
225+
forge script script/DeployLottery.s.sol:DeployLotteryScript \
226+
--rpc-url $BASE_SEPOLIA_RPC_URL \
227+
--private-key $PRIVATE_KEY \
228+
--broadcast \
229+
--verify
230+
231+
# Using Hardhat
232+
npm run deploy:testnet
233+
```
234+
235+
### Deploy to Base Mainnet
236+
237+
```bash
238+
npm run deploy:mainnet
239+
```
240+
241+
## 🌐 Contract Addresses
242+
243+
### Base Sepolia (Testnet)
244+
245+
- **Lottery**: `0x28645Ac9f3FF24f1623CbD65A6D7d9122d6b9a07`
246+
- **Vesting**: `0x7314251E4CEb115fbA106f84BB5B7Ef8a6ABae3E`
247+
- **Pyth Integration**: `0x0f3AcD9aF35f1970A8ceef26dF5484E7C2245840`
248+
- **USDC**: `0x036CbD53842c5426634e7929541eC2318f3dCF7e`
249+
- **Pyth Entropy**: `0x41c9e39574F40Ad34c79f1C99B66A45eFB830d4c`
250+
251+
## 📊 Economic Model
252+
253+
### Revenue Distribution
254+
- **70%** → Jackpot (winner's payout)
255+
- **30%** → Referral rewards (if referrer provided)
256+
257+
### Payout Structure
258+
- **First Payment**: Immediate (1/120th of jackpot)
259+
- **Monthly Payments**: 119 payments over 10 years
260+
- **Interest**: Generated from Aave deposits increases total payout
261+
262+
### Social Impact Funding
263+
- **Source**: Interest from Aave deposits
264+
- **Amount**: ~$7M annually (with 1M USDC daily deposits at 4% APY)
265+
- **Allocation**: 100% to social projects
266+
267+
## 🔗 Integrations
268+
269+
### Pyth Entropy
270+
- **Purpose**: Provably fair random number generation
271+
- **Version**: V2 API
272+
- **Fee**: Dynamic (currently ~0.000022 ETH on Base Sepolia)
273+
- **Pattern**: Callback-based for asynchronous randomness
274+
275+
### Aave V3
276+
- **Purpose**: Lending protocol for generating interest
277+
- **Token**: USDC
278+
- **Benefit**: Winners earn interest on top of monthly payments
279+
280+
### Base Blockchain
281+
- **Network**: Base Sepolia (testnet) / Base Mainnet
282+
- **Benefits**: Low fees, fast transactions, Ethereum compatibility
283+
284+
## 🤝 Contributing
285+
286+
Contributions are welcome! Please feel free to submit a Pull Request.
287+
288+
## 📝 License
289+
290+
MIT License
291+
292+
## 🙏 Acknowledgments
293+
294+
- **Pyth Network** for provably fair randomness
295+
- **Aave** for lending infrastructure
296+
- **Base** for blockchain infrastructure
297+
- **OpenZeppelin** for secure contract libraries
298+
299+
## 📞 Support
300+
301+
For questions or support, please open an issue on GitHub.
302+
303+
---
304+
305+
**The Social Pot** - Where winning meets giving. 🍀
306+
307+
WIN. GIVE. GROW.
308+

‎entropy/theSocialPot/app/.gitignore‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
2+
3+
# dependencies
4+
/node_modules
5+
/.pnp
6+
.pnp.*
7+
.yarn/*
8+
!.yarn/patches
9+
!.yarn/plugins
10+
!.yarn/releases
11+
!.yarn/versions
12+
13+
# testing
14+
/coverage
15+
16+
# next.js
17+
/.next/
18+
/out/
19+
20+
# production
21+
/build
22+
23+
# misc
24+
.DS_Store
25+
*.pem
26+
27+
# debug
28+
npm-debug.log*
29+
yarn-debug.log*
30+
yarn-error.log*
31+
.pnpm-debug.log*
32+
33+
# env files (can opt-in for committing if needed)
34+
.env*
35+
36+
# vercel
37+
.vercel
38+
39+
# typescript
40+
*.tsbuildinfo
41+
next-env.d.ts

0 commit comments

Comments
 (0)