# MegaCharm Documentation

> **The On-Chain Lottery Protocol — Provably Fair, Daily Draws, No Intermediaries**
>
> Website: [megacharm.io](https://megacharm.io) | Network: BNB Smart Chain | Status: ✅ Testnet Live

---

## Table of Contents

1. [Introduction](#introduction)
2. [How It Works](#how-it-works)
3. [Buying Tickets](#buying-tickets)
4. [The Draw](#the-draw)
5. [Claiming Winnings](#claiming-winnings)
6. [The $MEGA Token](#the-mega-token)
7. [VIP Discounts](#vip-discounts)
8. [Contract Architecture](#contract-architecture)
9. [Security](#security)
10. [Contract Addresses](#contract-addresses)
11. [FAQ](#faq)
12. [Legal](#legal)

---

## Introduction

MegaCharm is a decentralized lottery protocol built on BNB Smart Chain. Every day at **12:30 AM UTC**, a cryptographically provable random number is drawn using **Chainlink VRF v2.5**. Anyone who purchased a ticket matching that number wins the jackpot.

**Why MegaCharm?**

| Traditional Lottery | MegaCharm |
|---|---|
| Trust the operator | Trust the code — it's open source |
| Opaque draw | Chainlink VRF — provably fair on-chain |
| Geographic restrictions | Anyone with a crypto wallet |
| Weeks to claim | Claim instantly, 24/7 |
| High overhead, low payouts | 90% of every ticket goes to jackpot |

---

## How It Works

MegaCharm operates in continuous **rounds**. Each round is one day.

```
  12:30 AM UTC         12:00 AM UTC         12:30 AM UTC
       │                     │                     │
       ▼                     ▼                     ▼
  ┌─────────┐          ┌──────────┐          ┌─────────┐
  │  Draw   │          │ Tickets  │          │  Draw   │
  │Round N  │─────────▶│  Close   │─────────▶│Round N+1│
  └─────────┘          └──────────┘          └─────────┘
  VRF picks             No new tickets         Next draw
  winning number        for 30 min             happens
```

**Round lifecycle:**
1. Round starts after the previous draw completes
2. Ticket window: 23 hours
3. At 12:00 AM UTC tickets close (30-min buffer before draw)
4. At 12:30 AM UTC Chainlink Automation triggers the draw
5. Chainlink VRF returns a random number (within ~3 BSC blocks)
6. Winners can claim immediately

---

## Buying Tickets

### What you need
- A Web3 wallet (MetaMask, Trust Wallet, etc.)
- Connected to **BNB Smart Chain** (Chain ID: 56 mainnet / 97 testnet)
- USDT or USDC (stablecoins)

### Steps
1. Go to [megacharm.io/application_page/app.html](https://megacharm.io/application_page/app.html)
2. Connect your wallet
3. Approve the lottery contract to spend your USDT or USDC
4. Choose how many tickets to buy (each ticket = $5)
5. Each ticket is assigned a **random number between 000000 and 999999**
6. Your ticket is recorded on-chain with your wallet address

### Ticket pricing

| Tier | Requirement | Price |
|---|---|---|
| Standard | No $MEGA held | $5.00 |
| Silver VIP | 10,000 $MEGA | $4.50 (10% off) |
| Gold VIP | 50,000 $MEGA | $4.00 (20% off) |
| Diamond VIP | 100,000 $MEGA | $3.00 (40% off) |

> VIP discounts are not yet live on testnet. They activate at mainnet launch.

### No ticket limit
You can buy as many tickets as you want in a single round. More tickets = more chances to win.

---

## The Draw

### How randomness works

MegaCharm uses **Chainlink VRF v2.5** (Verifiable Random Function) — the industry standard for on-chain randomness.

1. At draw time, the contract calls the Chainlink VRF Coordinator
2. Chainlink nodes generate a random number off-chain using cryptographic proofs
3. The proof is verified on-chain before the number is accepted
4. No one — not Chainlink, not MegaCharm — can predict or manipulate the result

### Winning

The winning number is `randomWord % 1,000,000` (giving a number from 000000 to 999999).

Any ticket holder whose number matches wins. If multiple tickets share the same winning number, the jackpot is **split equally** among all winners.

### No winner? Jackpot rolls over

If no ticket matches the winning number, the jackpot rolls over to the next round — exactly like Powerball's jackpot. This means jackpots can grow across multiple rounds until someone wins.

---

## Claiming Winnings

MegaCharm uses a **pull-payment pattern** — winnings are never pushed to your wallet automatically. You come to the app and claim.

### Why pull-payment?
- Gas-safe: the VRF callback doesn't need to send tokens to multiple wallets
- Reentrancy-safe: no external calls during the VRF callback
- Your winnings are always there — no expiry except after 1 year

### How to claim
1. Go to the app
2. Connect your winning wallet
3. Click **"Claim Winnings"**
4. Confirm the transaction

### Unclaimed winnings
If winnings are not claimed within **1 year**, the admin wallet can sweep them back to the protocol treasury. This prevents funds from being stranded forever.

---

## The $MEGA Token

**Contract:** `0xabc41aCF671a5199681540f26aC964c7272bc985` (BSC Testnet)

$MEGA is the MegaCharm utility token. It is not a speculative investment — it exists purely to reward loyal players with cheaper tickets.

### Tokenomics

| Allocation | Amount | % |
|---|---|---|
| Public Sale / Liquidity | 40,000,000 | 40% |
| Ecosystem & Rewards | 25,000,000 | 25% |
| Team (12-month cliff, 24-month vest) | 15,000,000 | 15% |
| Treasury & Operations | 10,000,000 | 10% |
| Marketing & Partnerships | 10,000,000 | 10% |
| **Total Supply** | **100,000,000** | **100%** |

### Buyback & Burn
10% of all protocol fees are used to buy $MEGA on the open market and burn it permanently, creating deflationary pressure.

---

## VIP Discounts

Hold $MEGA in your wallet to automatically get cheaper tickets.

| Tier | $MEGA Required | Discount | Ticket Price |
|---|---|---|---|
| Standard | 0 | 0% | $5.00 |
| Silver | 10,000 $MEGA | 10% | $4.50 |
| Gold | 50,000 $MEGA | 20% | $4.00 |
| Diamond | 100,000 $MEGA | 40% | $3.00 |

Discounts are checked on-chain at ticket purchase time. You don't need to stake or lock — just hold $MEGA in your wallet.

---

## Contract Architecture

### Overview

```
┌─────────────────────────────────────────┐
│           LotteryManager                │
│         (UUPS Upgradeable Proxy)        │
│                                         │
│  ┌─────────────┐  ┌──────────────────┐  │
│  │ Ticket Sale │  │  Draw & Payout   │  │
│  │  (ERC20 in) │  │  (VRF + Claim)   │  │
│  └─────────────┘  └──────────────────┘  │
│                                         │
│  ┌─────────────┐  ┌──────────────────┐  │
│  │ Chainlink   │  │  Chainlink       │  │
│  │ VRF v2.5   │  │  Automation      │  │
│  └─────────────┘  └──────────────────┘  │
└─────────────────────────────────────────┘
```

### Key components

| Component | Description |
|---|---|
| **LotteryManager** | Core contract — handles ticket sales, draws, payouts |
| **UUPS Proxy** | Upgradeable via owner — allows bug fixes without migrating |
| **Chainlink VRF v2.5** | Provably fair randomness for every draw |
| **Chainlink Automation** | Triggers draw at 12:30 AM UTC automatically |
| **MEGA Token** | ERC-20 utility token for VIP discounts |
| **SafeERC20** | Safe token transfer wrapper (prevents bad ERC20s) |
| **ReentrancyGuard** | Protects all state-changing functions |
| **Pausable** | Emergency stop — admin can pause all activity |

### Revenue flow

```
Player pays $5 USDT/USDC
        │
        ├──▶ 90% → Jackpot Pool (held in contract)
        │
        └──▶ 10% → Protocol Fee (claimable by admin)
```

On draw:
```
Jackpot Pool
        │
        ├── Winner found → Split equally among all winners
        │                  → Claimable immediately
        │
        └── No winner    → Entire pool rolls over to next round
```

---

## Security

### Audits
MegaCharm has been internally reviewed with focus on:

- ✅ Reentrancy attacks — protected via `ReentrancyGuardUpgradeable`
- ✅ Front-running — draw window closes 30 min before VRF request
- ✅ VRF manipulation — Chainlink VRF v2.5, cryptographic proof verified on-chain
- ✅ Overflow/underflow — Solidity ^0.8.20 with built-in checks
- ✅ Access control — `OwnableUpgradeable` with all admin functions gated
- ✅ Unclaimed winnings — 1-year expiry, swept to admin (prevents stranded funds)
- ✅ Stuck round recovery — `resetStuckRound()` if VRF callback ever fails
- ✅ Emergency pause — owner can pause all activity instantly
- ✅ UUPS upgrade protection — only owner can authorize upgrades

### What the admin CAN do
- Pause/unpause the protocol
- Change ticket price
- Add/remove supported tokens
- Update Chainlink VRF configuration
- Sweep unclaimed winnings after 1 year
- Upgrade the contract implementation

### What the admin CANNOT do
- Steal jackpot funds (no `emergencyWithdraw` on jackpot pool)
- Manipulate the winning number (VRF is trustless)
- See your tickets before the draw (all on-chain, transparent)

### Bug reporting
Contact: [contact@megacharm.io](mailto:contact@megacharm.io)

---

## Contract Addresses

### BSC Testnet (Current — Chain ID: 97)

| Contract | Address | Explorer |
|---|---|---|
| LotteryManager (Proxy) | `0x61F678143B17614130258Fa87f643eCbBF3Cc48F` | [BSCScan](https://testnet.bscscan.com/address/0x61F678143B17614130258Fa87f643eCbBF3Cc48F) |
| MEGA Token | `0xabc41aCF671a5199681540f26aC964c7272bc985` | [BSCScan](https://testnet.bscscan.com/address/0xabc41aCF671a5199681540f26aC964c7272bc985) |
| Mock USDT (testnet) | `0xFBE7aC4AE36685Cc064690d7811EBa3F5086203F` | [BSCScan](https://testnet.bscscan.com/address/0xFBE7aC4AE36685Cc064690d7811EBa3F5086203F) |
| Mock USDC (testnet) | `0x5B5d479CC1cFAf76fFCfDcd39fAe3b3e350cFAa7` | [BSCScan](https://testnet.bscscan.com/address/0x5B5d479CC1cFAf76fFCfDcd39fAe3b3e350cFAa7) |

### Chainlink Configuration (Testnet)

| Parameter | Value |
|---|---|
| VRF Version | v2.5 |
| VRF Coordinator | `0x6A2AAd07396B36Fe02a22b33cf443582f682c82f` |
| Subscription ID | `1128...1791` |
| Key Hash (500 gwei) | `0xd4bb...05314` |
| Callback Gas Limit | 500,000 |

### BSC Mainnet
> Mainnet deployment is planned after testnet validation and VC funding. Addresses will be published here.

---

## FAQ

**Q: Is MegaCharm fair?**
Every draw uses Chainlink VRF v2.5 — a cryptographically verifiable random number that even MegaCharm cannot predict or manipulate. The proof is verified on-chain before the result is accepted.

**Q: What is the chance of winning?**
Your odds = (number of tickets you own) / (total tickets sold in the round). The winning number is drawn from 0–999,999. If 200 unique tickets are sold, covering 200 different numbers, you have a 1-in-5,000 chance per ticket.

**Q: Can the jackpot grow?**
Yes. If no one holds a ticket matching the winning number, the entire jackpot rolls over to the next round. There is no cap — jackpots accumulate until someone wins.

**Q: How do I get my winnings?**
Connect your wallet at [megacharm.io](https://megacharm.io), click "Claim Winnings", and confirm the transaction. Winnings are in the same token (USDT or USDC) used to buy your tickets.

**Q: What if I forget to claim?**
You have **1 year** to claim from the date of the draw. After that, the admin can sweep unclaimed funds to the protocol treasury.

**Q: Do I need $MEGA tokens to play?**
No — $MEGA is optional. It gives you discounted ticket prices. You can play with just USDT or USDC.

**Q: What blockchain is MegaCharm on?**
BNB Smart Chain (BSC). It's currently on testnet; mainnet launch is planned after VC funding.

**Q: What wallet should I use?**
Any Web3 wallet that supports BSC: MetaMask, Trust Wallet, Binance Web3 Wallet, etc.

**Q: Is the contract upgradeable?**
Yes — it uses the UUPS upgradeable proxy pattern. Only the owner (MegaCharm team) can upgrade the implementation. This allows bug fixes without users needing to interact with a new address. All upgrades will be announced publicly.

**Q: Where is the code?**
Source code is verified on [BSCScan Testnet](https://testnet.bscscan.com/address/0xEa464B45fb2Af29b08572E7316937F7186235933#code).

**Q: Can I buy tickets on mobile?**
Yes — use the in-app browser in Trust Wallet or MetaMask mobile, navigate to megacharm.io.

---

## Legal

MegaCharm is a decentralized smart contract protocol. Participation is subject to the laws and regulations of your jurisdiction. It is your responsibility to determine whether participating in on-chain lottery activities is legal in your location.

MegaCharm does not offer services to residents of jurisdictions where online gambling or lottery activities are prohibited, including but not limited to the United States.

The smart contracts are non-custodial — MegaCharm never holds custody of user funds beyond the jackpot pool defined in the contract. The protocol operates autonomously; the team maintains administrative keys only for configuration updates, emergency pauses, and authorized contract upgrades.

**This documentation is for informational purposes only and does not constitute financial or investment advice.**

---

*MegaCharm — Play Fair. Win Transparently.*  
*[megacharm.io](https://megacharm.io) | [contact@megacharm.io](mailto:contact@megacharm.io)*