# SYSTEM DESIGN & OPERATIONAL SPECIFICATIONS: THE OUTCAST BAZAAR & CROSS-PLATFORM PAYMENTS
# FREEEXILE PROJECT: GRIMDARK SAVAGE PRIMAL EXILE ARPG 2.5D

> **Responsible Departments**: Executive Producer (`studio_producer`), Lead Documentation Architect (`lead_documentation_architect`), Lead Server Systems Architect (`server_systems_architect`), Localization Lead (`localization_lead`).  
> **Document Version**: 1.0.0-RELEASE  
> **Applies to**: FreeExile Server Clusters, iOS Client (StoreKit 2), Android Client (Google Play), Web Direct Portal, and Web3 Crypto Payment Gateway.

---

## 1. SYSTEM OVERVIEW

- **System Name**: `The Outcast Bazaar` (Vietnamese: `Hắc Thị Hoang Vực`, Chinese: `荒域黑市`).
- **Nature**: The exclusive official **Publisher First-Party Store**, operating concurrently with but strictly isolated from the player-to-player **Consignment Vault (Ký Gửi Hoang Vực)**.
- **Store Currency**:
  - **Outcast Blood Coins (Huyết Cổ Tệ)**: In-game premium hard currency.
  - **Base Conversion**: $\$1.00\text{ USD} = 100\text{ Blood Coins}$.
- **Fair Play Primal Philosophy**:
  - The Bazaar **strictly forbids selling pay-to-win combat stats**, uncapped bone nodes, or overpowered gear.
  - Offerings focus entirely on **Primal Bone Weapon Skins & Cuirasses**, **Survival Convenience Items**, **Transparent Bone Chests**, and **Seasonal Wasteland Battle Passes**.

---

## 2. FIVE PRIMARY PRODUCT CATEGORIES

```
[FREEEXILE OUTCAST BAZAAR]
┌────────────────────────────────────────────────────────────────────────┐
│ 1. BLOOD COIN PACKS (COINS)                                            │
│    - 100, 500, 1,000, 2,500, 6,000, 13,000 Blood Coin Packs            │
│    - Exile Supply Pack: 50% First-Time Purchase Discount (Limit 1/acc) │
├────────────────────────────────────────────────────────────────────────┤
│ 2. BEAST WEAPONS & CUIRASS SKINS (COSMETICS)                           │
│    - Savage Beast Bone Cleaver (Serrated jawbone cleaver with dried gore)│
│    - Blood Yaksha Cuirass (Rough hide vest with broken beast tusks)    │
│    - Primeval Bone Warbeast Mount (Sabertooth mount with barbed chains)│
├────────────────────────────────────────────────────────────────────────┤
│ 3. CONVENIENCE & SURVIVAL ITEMS (ITEMS)                                │
│    - Merchant Stash Tab (Unlocks Premium Merchant Tab, 500 Blood Coins)│
│    - Wasteland Portal Scrolls (Pack of 50 beast hide teleport writs)   │
│    - Beast Hide Pouch (Expands 100 inventory slots)                    │
│    - Bone-Marrow Extraction Juice (Full reset of physical bone nodes)  │
├────────────────────────────────────────────────────────────────────────┤
│ 4. PRIMAL BONE CHESTS (TRANSPARENT GACHA)                              │
│    - Primal Bone Chest & Abyssal Reliquary with 100% disclosed rates   │
├────────────────────────────────────────────────────────────────────────┤
│ 5. SEASONAL BATTLE PASSES & BLOOD PACTS (PASSES)                       │
│    - Exile Blood Pact (Daily 100 Blood Coins for 30 days)              │
│    - Wasteland Battle Pass Season 1 (100 tiers, exclusive cleaver skin)│
└────────────────────────────────────────────────────────────────────────┘
```

---

## 3. LOOT BOX TRANSPARENCY GUARANTEE

1. **100% Probability Disclosure**: Every mystery chest explicitly displays the exact mathematical drop chance down to $0.01\%$ in the preview UI.
2. **Pity Counter Protection**:
   - 50 consecutive opens without a Rare item activates a $100\%$ Rare guarantee on open 51.
   - 100 consecutive opens without a Unique/Mythic artifact guarantees a Unique drop on open 101.

### Official Probability Table: Primal Bone Chest (`chest_celestial_fortune`)
| Item Name | Tier / Rarity | Translation Key | Probability (%) |
| :--- | :--- | :--- | :--- |
| **Ancient Bone Shard** | Common (Phàm phẩm) | `loot_manh_xuong_co` | **45.0%** |
| **Wasteland Flint** | Magic (Linh phẩm) | `loot_da_lua_hoang_da` | **30.0%** |
| **Primal Bloodstone** | Rare (Cực phẩm) | `loot_huyet_hon_thach` | **20.0%** |
| **Ancient Bone Brand** | Rare (Cực phẩm) | `loot_co_cot_an` | **4.5%** |
| **Savage Blood Mirror** | Unique (Thần thoại) | `loot_huyet_anh_co_kinh` | **0.5% (Pity Target)** |
| **SUM TOTAL** | - | - | **100.0%** |

---

## 4. PLATFORM PAYMENT COMPLIANCE ROUTING

```mermaid
flowchart TD
    Client[Client App Request] --> Router{Payment Gateway Router}
    
    Router -->|iOS Client| Apple[Apple In-App Purchase StoreKit 2 ONLY]
    Router -->|Android PlayStore| Google[Google Play Billing v6+ ONLY]
    Router -->|Web Direct / PC / APK| Web[Stripe, PayPal, Local QR, Web3 Crypto]
    
    Apple --> ServerAuthoritative[Server-Authoritative Verification & 2PC Delivery]
    Google --> ServerAuthoritative
    Web --> ServerAuthoritative
```

### 4.1. iOS Platform (Apple App Store Guideline 3.1.1)
- **Mandatory Policy**: Builds distributed via the Apple App Store **must exclusively route transactions through Apple In-App Purchase (StoreKit 2)**.
- **Strict Prohibition**: Third-party payment buttons, external top-up web links, and crypto wallet addresses are strictly forbidden inside the iOS app binary.
- **Verification**: Validated server-authoritatively via Apple App Store Server API v2 using `SignedTransaction JWS`.

### 4.2. Android Platform (Google Play Store)
- Utilizes Google Play Billing v6/v7 with User Choice Billing (UCB) where legally mandated.

### 4.3. Web Direct Top-Up Portal & Sideload APKs
- Unrestricted by 30% store fees.
- Supports International Credit Cards (Stripe), PayPal, Local QR Gateways, and **Web3 Crypto Wallets**.

---

## 5. PURCHASING POWER PARITY (PPP) PRICING MATRIX

| Regional Tier | Representative Countries | PPP Multiplier | Reference \$10 Pack | Display Currency |
| :--- | :--- | :--- | :--- | :--- |
| **Tier 1 (Standard)** | US, JP, UK, DE | **1.00** | \$9.99 USD (~1,550 JPY) | USD, JPY, EUR, GBP |
| **Tier 2 (Moderate)** | KR, SG, TW | **0.90** | ~12,000 KRW / \$9.00 SGD | KRW, SGD, TWD |
| **Tier 3 (Emerging)** | VN, TH, BR, ID | **0.50** | **125,000 VND** (~180 THB) | VND, THB, BRL |

### Web Direct & Crypto Bonus (+10% Extra Blood Coins)
- Bypassing the 30% app store cut allows rewarding players on Web/Crypto with **+10% Bonus Blood Coins** (\$9.99 yields 1,100 blood coins instead of 1,000).

### Anti-Region Arbitrage Shield
- Server validates that client IP matches the issuing country of the payment method. Mismatches trigger a `REGION_MISMATCH` rejection.

---

## 6. WEB3 CRYPTO PAYMENT ARCHITECTURE

- **Supported Chains**: Arbitrum One, Polygon PoS, Ethereum Mainnet, Solana, BNB Chain.
- **Supported Tokens**: USDT, USDC (1:1 USD Stablecoins), ETH, SOL (Floating Native Assets).
- **Oracle Valuation**: Pyth Network & Chainlink price feeds lock crypto conversion rates with a **15-minute expiration window** (`validity_seconds = 900`).
- **Idempotent Anti-Double-Spending**:
  - On-chain RPC verification confirms confirmations, recipient vault address, token contract, and amount transferred.
  - Transaction hashes are permanently committed to a distributed ledger. Replay attacks trigger immediate `DOUBLE_SPENDING_DETECTED` exceptions.
  - Final delivery executed via distributed **Two-Phase Commit (2PC)**.