Feat/blockchain

.claude/settings.local.json

@@ -0,0 +1,57 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(npx hardhat compile:*)",
+      "Bash(where npx:*)",
+      "Bash(where:*)",
+      "Bash(where.exe:*)",
+      "Bash(cmd.exe:*)",
+      "Bash(powershell.exe -Command \"Get-Command node -ErrorAction SilentlyContinue | Select-Object -ExpandProperty Source; Get-Command npm -ErrorAction SilentlyContinue | Select-Object -ExpandProperty Source; Get-Command npx -ErrorAction SilentlyContinue | Select-Object -ExpandProperty Source\")",
+      "Bash(/c/Users/andre/AppData/Local/ms-playwright-go/1.50.1/node.exe:*)",
+      "Bash(docker --version:*)",
+      "Bash(MSYS_NO_PATHCONV=1 docker run:*)",
+      "Bash(git log:*)",
+      "Bash(node -e:*)",
+      "Bash(ls:*)",
+      "Bash(\"C:\\\\James\\\\Programming\\\\Hackathon\\\\fluffy-engine\\\\contracts\\\\node_modules\\\\.bin\\\\ts-node\" -e \"const { ethers } = require\\(''ethers''\\); const w = ethers.Wallet.createRandom\\(\\); console.log\\(''Address:'', w.address\\); console.log\\(''Private Key:'', w.privateKey\\);\")",
+      "Bash(python3:*)",
+      "Bash(python:*)",
+      "Bash(printenv:*)",
+      "Bash(echo:*)",
+      "Bash(find:*)",
+      "Bash(export:*)",
+      "Bash($NODE -e \"const { ethers } = require\\(''ethers''\\); const w = new ethers.Wallet\\(''0x30cc37df21c1dd9da4f61e0baa4ad62f0da7a34a6f1fbb504e2a7d675c354e23''\\); console.log\\(''Address:'', w.address\\);\")",
+      "Bash($NODE -e \"const { ethers } = require\\(''./node_modules/ethers''\\); const w = new ethers.Wallet\\(''0x30cc37df21c1dd9da4f61e0baa4ad62f0da7a34a6f1fbb504e2a7d675c354e23''\\); console.log\\(''Address:'', w.address\\);\")",
+      "Bash($NODE -e \"\nconst { ethers } = require\\(''./node_modules/ethers''\\);\nasync function main\\(\\) {\n    const provider = new ethers.JsonRpcProvider\\(''https://coston2-api.flare.network/ext/C/rpc''\\);\n    const balance = await provider.getBalance\\(''0x6cF81eEf8594c10142a0608D2e986182e2c8E422''\\);\n    console.log\\(''Balance:'', ethers.formatEther\\(balance\\), ''C2FLR''\\);\n}\nmain\\(\\).catch\\(console.error\\);\n\")",
+      "WebFetch(domain:faucet.flare.network)",
+      "Bash(curl:*)",
+      "WebSearch",
+      "Bash(tr:*)",
+      "Bash(NODE=/c/Users/andre/AppData/Local/ms-playwright-go/1.50.1/node.exe:*)",
+      "Bash($NODE node_modules/hardhat/internal/cli/bootstrap.js run scripts/deploy-pool.ts --network localhost)",
+      "Bash($NODE -e \"\nconst { ethers } = require\\(''./node_modules/ethers''\\);\nconsole.log\\(''RNG:'', ethers.getAddress\\(''0x5CdF9eAF3EB8b44fB696F8d6a062eF6b1e1Fd909''.toLowerCase\\(\\)\\)\\);\nconsole.log\\(''FTSO:'', ethers.getAddress\\(''0x3d893C53D9e8056135C26C8c638B76C8b60Df726''.toLowerCase\\(\\)\\)\\);\n\")",
+      "Bash($NODE /c/Users/andre/AppData/Local/ms-playwright-go/1.50.1/package/lib/cli/cli.js)",
+      "Bash($NODE -e \"\nconst { execSync } = require\\(''child_process''\\);\n// Node v22 ships with corepack which includes npm\n// Try to find npm-cli.js\nconst path = require\\(''path''\\);\nconst nodeDir = path.dirname\\(process.execPath\\);\nconst fs = require\\(''fs''\\);\n// Check for npm in node''s directory\nconst candidates = [\n  path.join\\(nodeDir, ''node_modules'', ''npm'', ''bin'', ''npm-cli.js''\\),\n  path.join\\(nodeDir, ''..'', ''lib'', ''node_modules'', ''npm'', ''bin'', ''npm-cli.js''\\),\n  path.join\\(nodeDir, ''..'', ''node_modules'', ''npm'', ''bin'', ''npm-cli.js''\\),\n];\nfor \\(const c of candidates\\) {\n  if \\(fs.existsSync\\(c\\)\\) {\n    console.log\\(''Found npm at:'', c\\);\n    process.exit\\(0\\);\n  }\n}\nconsole.log\\(''npm not found in node directory:'', nodeDir\\);\nconsole.log\\(''Contents:'', fs.readdirSync\\(nodeDir\\)\\);\n\")",
+      "Bash($NODE -e \"\nconst https = require\\(''https''\\);\nconst fs = require\\(''fs''\\);\nconst path = require\\(''path''\\);\n\n// Download npm tarball\nconst url = ''https://registry.npmjs.org/npm/-/npm-10.9.2.tgz'';\nconst tmpFile = path.join\\(process.env.TEMP || ''/tmp'', ''npm.tgz''\\);\n\nconsole.log\\(''Downloading npm...''\\);\nconst file = fs.createWriteStream\\(tmpFile\\);\nhttps.get\\(url, \\(response\\) => {\n    if \\(response.statusCode === 302 || response.statusCode === 301\\) {\n        https.get\\(response.headers.location, \\(r2\\) => {\n            r2.pipe\\(file\\);\n            file.on\\(''finish'', \\(\\) => { file.close\\(\\); console.log\\(''Downloaded to'', tmpFile\\); }\\);\n        }\\);\n    } else {\n        response.pipe\\(file\\);\n        file.on\\(''finish'', \\(\\) => { file.close\\(\\); console.log\\(''Downloaded to'', tmpFile\\); }\\);\n    }\n}\\).on\\(''error'', \\(e\\) => console.error\\(e\\)\\);\n\")",
+      "Bash(NPM_CLI=/c/Users/andre/AppData/Local/Temp/npm-pkg/package/bin/npm-cli.js)",
+      "Bash($NODE $NPM_CLI install)",
+      "Bash($NODE node_modules/.bin/ts-node src/index.ts)",
+      "Bash(npm install:*)",
+      "Bash(npx tsc:*)",
+      "Bash(npx hardhat test)",
+      "mcp__ide__getDiagnostics",
+      "Bash(lsof:*)",
+      "mcp__MCP_DOCKER__browser_navigate",
+      "Bash(docker start:*)",
+      "mcp__MCP_DOCKER__browser_take_screenshot",
+      "mcp__MCP_DOCKER__browser_click",
+      "mcp__MCP_DOCKER__browser_fill_form",
+      "mcp__MCP_DOCKER__browser_snapshot",
+      "mcp__MCP_DOCKER__browser_console_messages",
+      "mcp__MCP_DOCKER__browser_network_requests",
+      "Bash(npx hardhat run:*)",
+      "Bash(npx hardhat console:*)",
+      "WebFetch(domain:www.plasma.to)"
+    ]
+  }
+}

.gitignore

@@ -11,6 +11,11 @@ frontend/cache
 frontend/.next
 frontend/artifacts
 backend/node_modules
-backend/.env
-
 *.gz
+.claude/settings.local.json
+
+# Environment files (keep .env.example, ignore .env with secrets)
+.env
+!.env.example
+*/.env
+!*/.env.example

CLAUDE.md

@@ -95,15 +95,15 @@ PORT                      # API port (default: 3001)
 ### Contracts (.env in contracts/)
 ```bash
 PRIVATE_KEY               # Deployment account private key
-PLASMA_RPC_URL            # Plasma RPC endpoint (default: https://rpc.plasma.to)
+PLASMA_RPC_URL            # Plasma RPC endpoint (default: https://testnet-rpc.plasma.to)
 ```
 
 ## Network Configuration
 
 | Network | Chain ID | RPC URL |
 |---------|----------|---------|
 | Flare Coston2 (testnet) | 114 | https://coston2-api.flare.network/ext/C/rpc |
-| Plasma | — | https://rpc.plasma.to |
+| Plasma | — | https://testnet-rpc.plasma.to |
 
 **Important Flare Contracts**:
 - RandomNumberV2: `0x97702e350CaEda540935d92aAf213307e9069784`

LICENSE

@@ -0,0 +1 @@
+We consider this project entirely proprietary. The visibility of source code is not to be misconstrued.

PLAN.md

@@ -1,10 +1,10 @@
-# LottoLink iBankroll POC - 5 Hour Hackathon Plan
+# LottoLink CaaS POC - 5 Hour Hackathon Plan
 
 ## Context
 
 **Problem:** 200+ US lottery operators hold massive reserves to back jackpots. This locks up funds that should go to charitable causes.
 
-**Solution:** Shared liquidity pool (iBankroll model) where:
+**Solution:** Shared liquidity pool (CaaS model) where:
 - LPs deposit USDT → earn yield from operator premiums
 - Operators pay premiums (% of ticket sales) → access to deep pool liquidity
 - Small lotteries offer big jackpots without big reserves
@@ -355,7 +355,7 @@ npm run frontend:build
 ## Talking Points for Judges
 
 **Q: What's innovative here?**
-A: We're applying the iBankroll model (proven in crypto casinos) to traditional lotteries. Instead of each operator holding idle reserves, they pool risk. Law of large numbers makes aggregate variance predictable.
+A: We're applying the CaaS model (proven in crypto casinos) to traditional lotteries. Instead of each operator holding idle reserves, they pool risk. Law of large numbers makes aggregate variance predictable.
 
 **Q: Why Flare?**
 A: We need all four protocols:

README.md

@@ -2,68 +2,151 @@
 
 Unified lottery infrastructure on **Flare** (Data Truth Layer) and **Plasma** (Money Movement Layer).
 
+---
+
+## Built on Flare
+
+### Network
+
+Flare Coston2 Testnet (Chain ID: 114)
+
+### Integrations
+
+| Protocol | Usage |
+|----------|-------|
+| Secure RNG | Provably fair lottery draws using ~100 independent providers with commit-reveal |
+| FDC (Flare Data Connector) | JsonApi attestation of external Web2 lottery results |
+| FTSO (Flare Time Series Oracle) | Accurate USD/USDT price feeds for settlement |
+
+### Setup
+
+See Quick Start below for installation and running instructions.
+
+---
+
+## Smart Contracts
+
+### Flare Coston2 (Deployed 2026-02-08)
+
+| Contract | Address | Explorer |
+|----------|---------|----------|
+| DrawManager | `0xca4e3CE939030BeF9F6f9Ca436a582eB7877fa69` | [View](https://coston2-explorer.flare.network/address/0xca4e3CE939030BeF9F6f9Ca436a582eB7877fa69) |
+| PayoutCalculator | `0xEC69Fe3D890475cb81010FE798f36d2e296fDB87` | [View](https://coston2-explorer.flare.network/address/0xEC69Fe3D890475cb81010FE798f36d2e296fDB87) |
+| LotteryRegistry | `0x2051233b0bfb28b9A975a65Ed552d6678f22Ce8C` | [View](https://coston2-explorer.flare.network/address/0x2051233b0bfb28b9A975a65Ed552d6678f22Ce8C) |
+| SharedLiquidityPool | `0xf969A46CeA823Da86F5Aa3f945272Aa7D58ca285` | [View](https://coston2-explorer.flare.network/address/0xf969A46CeA823Da86F5Aa3f945272Aa7D58ca285) |
+| MockUSDT | `0x6714F7a8bc580CB9B5FdCf5678Cfad2a4e494022` | [View](https://coston2-explorer.flare.network/address/0x6714F7a8bc580CB9B5FdCf5678Cfad2a4e494022) |
+
+### Plasma Testnet
+
+| Contract | Address | Explorer |
+|----------|---------|----------|
+| LottoEscrow | `0x560DC807d36dCe38BC09bc9fE84d94A34669A3FC` | [View](https://testnet.plasmascan.io/address/0x560DC807d36dCe38BC09bc9fE84d94A34669A3FC) |
+
+### Flare System Contracts (Reference)
+
+| Contract | Address |
+|----------|---------|
+| RandomNumberV2 | `0x97702e350CaEda540935d92aAf213307e9069784` |
+| ContractRegistry | `0xaD67FE66660Fb8dFE9d6b1b4240d8650e30F6019` |
+
+---
+
 ## Features
-- **Provably Fair Draws**: Flare Secure RNG (~100 independent providers, commit-reveal)
-- **Instant Zero-Fee Payouts**: Plasma USDT via EIP-3009 gasless transfers
-- **External Lottery Attestation**: FDC JsonApi for Web2 lottery results
-- **FTSO Price Feeds**: Accurate USD↔USDT conversion at settlement
+
+- **Provably Fair Draws** — Flare Secure RNG with ~100 independent providers and commit-reveal
+- **Instant Zero-Fee Payouts** — Plasma USDT via EIP-3009 gasless transfers
+- **External Lottery Attestation** — FDC JsonApi for Web2 lottery results
+- **FTSO Price Feeds** — Accurate USD/USDT conversion at settlement
+- **Shared Liquidity Pool** — CaaS model enabling small lotteries to offer big jackpots
+
+---
 
 ## Project Structure
+
 ```
 lottolink/
 ├── contracts/         # Solidity (Flare + Plasma)
 ├── backend/           # Node.js API + services
 └── frontend/          # Next.js 14 + Tailwind
 ```
 
+---
+
 ## Quick Start
 
+### Prerequisites
+
+- Node.js 18+
+- npm or yarn
+
 ### Contracts
+
 ```bash
-cd lottolink/contracts
+cd contracts
 npm install
 npx hardhat compile
 npx hardhat run scripts/deploy-flare.ts --network coston2
 ```
 
 ### Backend
+
 ```bash
-cd lottolink/backend
+cd backend
+cp .env.example .env
+# Edit .env with your contract addresses and keys
 npm install
-# Set env vars: DRAW_MANAGER_ADDRESS, PAYOUT_CALC_ADDRESS, ESCROW_ADDRESS, ESCROW_PRIVATE_KEY
 npm run dev
 ```
 
 ### Frontend
+
 ```bash
-cd lottolink/frontend
+cd frontend
 npm install
 npm run dev
+# Visit http://localhost:3000
 ```
 
+---
+
+## Environment Variables
+
+Copy the `.env.example` files and fill in your values:
+
+- `contracts/.env.example` → `contracts/.env`
+- `backend/.env.example` → `backend/.env`
+
+See each `.env.example` for required variables.
+
+---
+
 ## Network Config
 
 | Network | Chain ID | RPC |
 |---------|----------|-----|
 | Flare Coston2 | 114 | https://coston2-api.flare.network/ext/C/rpc |
-| Plasma | — | https://rpc.plasma.to |
+| Plasma Testnet | — | https://testnet-rpc.plasma.to |
 
-**Flare Contracts (Coston2)**:
-- RandomNumberV2: `0x97702e350CaEda540935d92aAf213307e9069784`
-- ContractRegistry: `0xaD67FE66660Fb8dFE9d6b1b4240d8650e30F6019`
-
-**Plasma**:
-- USDT: `0xB8CE59FC3717ada4C02eaDF9682A9e934F625ebb`
+---
 
 ## Hackathon Tracks
-- **Main Track**: Secure RNG + FDC + FTSO
-- **Bonus Track**: FDC JsonApi for external Web2 lottery APIs
 
-## Building on Flare — Developer Experience
-- ✅ Secure RNG integration was straightforward; `isSecureRandom` flag is a great safety feature
-- ✅ FTSO price feeds are well-documented with clear examples
-- ⚠️ FDC workflow has multiple async steps (verifier → FdcHub → DA Layer → verify) — consider a higher-level SDK
-- ⚠️ Testnet faucet occasionally slow; mainnet deployment pricing unclear
+- **Main Track** — Secure RNG + FDC + FTSO
+- **Bonus Track** — FDC JsonApi for external Web2 lottery APIs
+
+---
+
+## Developer Experience Notes
+
+Building on Flare:
+
+- Secure RNG integration was straightforward; the `isSecureRandom` flag is a useful safety feature
+- FTSO price feeds are well-documented with clear examples
+- FDC workflow has multiple async steps (verifier, FdcHub, DA Layer, verify) — a higher-level SDK would help
+- Testnet faucet occasionally slow; mainnet deployment pricing unclear
 
 ---
-MIT License
+
+## License
+
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

backend/.env

@@ -0,0 +1,29 @@
+# ================================================
+# LottoLink Backend Environment Configuration
+# ================================================
+
+# Server
+PORT=4000
+
+# Flare Network (Coston2 Testnet)
+FLARE_RPC=https://coston2-api.flare.network/ext/C/rpc
+
+# Contract Addresses (Coston2 — deployed 2026-02-08)
+DRAW_MANAGER_ADDRESS=0xca4e3CE939030BeF9F6f9Ca436a582eB7877fa69
+PAYOUT_CALC_ADDRESS=0xEC69Fe3D890475cb81010FE798f36d2e296fDB87
+REGISTRY_ADDRESS=0x2051233b0bfb28b9A975a65Ed552d6678f22Ce8C
+POOL_ADDRESS=0xf969A46CeA823Da86F5Aa3f945272Aa7D58ca285
+USDT_ADDRESS=0x6714F7a8bc580CB9B5FdCf5678Cfad2a4e494022
+
+# Plasma Network
+PLASMA_RPC_URL=https://testnet-rpc.plasma.to
+ESCROW_ADDRESS=0x560DC807d36dCe38BC09bc9fE84d94A34669A3FC
+
+# Backend signer (same as deployer for testnet)
+BACKEND_PRIVATE_KEY=0x30cc37df21c1dd9da4f61e0baa4ad62f0da7a34a6f1fbb504e2a7d675c354e23
+
+# Secrets (NEVER commit real values)
+ESCROW_PRIVATE_KEY=0x30cc37df21c1dd9da4f61e0baa4ad62f0da7a34a6f1fbb504e2a7d675c354e23
+PLASMA_RELAYER_API_KEY=
+
+MOCK_MODE=false

backend/.env.example

@@ -0,0 +1,30 @@
+# ================================================
+# LottoLink Backend Environment Configuration
+# ================================================
+
+# Server
+PORT=4000
+
+# Flare Network (Coston2 Testnet)
+FLARE_RPC=https://coston2-api.flare.network/ext/C/rpc
+
+# Contract Addresses (Coston2) — update after deployment
+DRAW_MANAGER_ADDRESS=0x_YOUR_DRAW_MANAGER_ADDRESS
+PAYOUT_CALC_ADDRESS=0x_YOUR_PAYOUT_CALC_ADDRESS
+REGISTRY_ADDRESS=0x_YOUR_REGISTRY_ADDRESS
+POOL_ADDRESS=0x_YOUR_POOL_ADDRESS
+USDT_ADDRESS=0x_YOUR_USDT_ADDRESS
+
+# Plasma Network
+PLASMA_RPC_URL=https://testnet-rpc.plasma.to
+ESCROW_ADDRESS=0x_YOUR_ESCROW_ADDRESS
+
+# Backend signer (DO NOT commit real keys!)
+BACKEND_PRIVATE_KEY=0x_YOUR_BACKEND_PRIVATE_KEY
+
+# Secrets (NEVER commit real values!)
+ESCROW_PRIVATE_KEY=0x_YOUR_ESCROW_PRIVATE_KEY
+PLASMA_RELAYER_API_KEY=
+
+# Mock mode for testing
+MOCK_MODE=false