# Patron & Premium System

## Overview
Advenexus has a premium currency called **Cash (💵)** that is obtained through real-money top-ups via Flutterwave bank transfers (NGN). Cash can be used for exclusive features: creating custom Patron animals, buying evolution stones directly, upgrading inventory capacity, and converting to coins. The Patron animal system lets players design their own unique creatures with custom artwork.

---

## Cash (💵) Currency

### How to Get Cash
Cash is purchased via Nigerian Naira (₦) bank transfers through Flutterwave. Conversion: **₦1 = 1 Cash** (base), with tier-based bonuses for larger purchases.

### Top-Up Tiers

| Amount (₦) | Cash Received | Bonus | Bonus % | Label |
|---|---|---|---|---|
| 500 | 500 💵 | 0 | 0% | — |
| 1,000 | 1,050 💵 | 50 | 5% | — |
| 2,000 | 2,200 💵 | 200 | 10% | — |
| 3,000 | 3,450 💵 | 450 | 15% | — |
| 5,000 | 6,000 💵 | 1,000 | 20% | Most Popular |
| 7,500 | 9,375 💵 | 1,875 | 25% | — |
| 10,000 | 13,500 💵 | 3,500 | 35% | Best Value |

### Payment Flow
1. Player selects a tier on the Account Wallet page
2. Server creates a pending transaction and calls Flutterwave API
3. Player receives a bank transfer reference (bank transfer only, no cards)
4. After payment, Flutterwave sends a webhook to the server
5. Server verifies the HMAC-SHA512 signature, validates the amount, and atomically credits Cash
6. Real-time wallet update is emitted via WebSocket

### Limits
- Max **3 pending transactions** at any time
- Pending transactions expire automatically (cleaned up by server cron)

---

## Cash Purchases

### Evolution Stones

| Stone Tier | Cash Price |
|---|---|
| Mythic | 500 💵 |
| Legendary | 1,500 💵 |
| Fabled | 2,500 💵 |
| Gods | 3,500 💵 |

- Added directly to inventory
- Same stones obtainable for free from dungeons (at much lower rates)

### Inventory Capacity Upgrade
- **Cost:** 100 💵 per upgrade
- **Gives:** +10 inventory slots
- **Max capacity:** 500 slots (default is 100)
- Purchased via Account Wallet page

### Cash → Coins Conversion
- **Rate:** 100 Cash = 10,000 Coins
- Must be in multiples of 100
- **One-way only** — coins cannot be converted back to Cash

### Guild Capacity Upgrade
- **Cost:** 250 💵 per slot
- Increases the maximum number of guild members
- Purchased by the guild leader

---

## Patron Animals

Custom-designed animals with player-uploaded artwork.

### Requirements
- **Cost:** 3,000 💵
- **Level requirement:** Level 20+ **OR** own a Fabled animal
- Created via the Patron panel on the website (REST API, not chat command)

### Creation Process
1. Player uploads a PNG or WEBP image (max 2 MB)
2. Image is processed: resized to **180×200px**, converted to WebP, compressed to < 500 KB
3. Image uploaded to Cloudinary (`advenexus/patron` folder)
4. Player chooses a **name** (2–24 chars, alphanumeric + spaces/underscores/hyphens/apostrophes)
5. Player chooses a **role**: tank, mage, berserker, armored, or speed
6. Animal is created at level 1, stage 0, rarity `patron`

### Patron Animal Stats
- Uses `TIER_BASE_STATS.patron`: HP 11,000 | ATK 450 | DEF 1,200 | SPD 600 | Mana 1,400
- Role bonus applied at creation (stage 0 bonus):
  - Tank: +30% HP
  - Mage: +50% Mana
  - Berserker: +40% ATK
  - Armored: +50% DEF
  - Speed: +30% SPD

### Patron Animal Properties
- **Rarity:** `patron` (unique tier)
- **Zoo points:** 12,000 per animal
- **XP per catch:** 10,000
- **Max level:** 30
- **Evolution:** No evolution (stage 0 only, evolution limit = 0)
- **Cannot be sold or sacrificed** (sell value = 0, sacrifice value = 0)
- **Animal key** = Cloudinary public ID (not from ANIMALS data — it's unique per instance)
- **Custom image** stored in `patron_images` table, joined to animals for display

### Name Rules
- Must be globally unique across all Patron animals
- 2–24 characters
- Allowed: `a-z A-Z 0-9 spaces _ - '`

---

## Cash Transaction Logging

All Cash spending is logged in the `cash_transactions` table:

| Field | Description |
|---|---|
| `tx_type` | `topup` (purchase) or `spend` (usage) |
| `amount_ngn` | NGN paid (0 for spend transactions) |
| `cash_amount` | Cash credited or spent |
| `reference` | Flutterwave reference or spend reference |
| `status` | `pending`, `completed`, or `expired` |
| `description` | Human-readable description of the spend |

Transaction history is viewable on the Account Wallet page (last 50 transactions).

---

## Admin Cash Commands

| Command | Description |
|---|---|
| `.admin01 <amount> cash <user>` | Give Cash to any player (admin only) |

- Admin account: `cybrus`
- Max single grant: 1,000,000,000 Cash
- No webhook verification needed for admin grants

---

## Edge Cases

- Flutterwave webhook validates HMAC-SHA512 signature — unsigned requests are rejected
- Amount in webhook is verified against the stored pending transaction (prevents amount tampering)
- Cash credit and transaction status update are wrapped in a SQLite transaction (atomic)
- Double crediting prevented: completed transactions are skipped if webhook fires twice
- Patron animal names are globally unique — no two Patron animals can share the same name
- Image format restricted to PNG and WEBP only (remove background at remove.bg first)
- If image cannot compress below 500 KB at quality 10, creation fails
- Cash conversions are one-way (Cash → Coins, never Coins → Cash)
- Inventory upgrade is capped at 500 slots maximum