Ludo Game Monetization — Complete Revenue Engineering Guide

# STEADY-STATE COIN EQUILIBRIUM
# Emission Rate = Sink Rate at equilibrium (currency doesn't inflate or deflate)

EMISSION_per_DAU_per_day = SINK_per_DAU_per_day

# Where:
#   EMISSION  = coins generated through gameplay (daily login, wins, quests, ads)
#   SINK      = coins consumed (entry fees, power-ups, cosmetics, room stakes)

# BREAK-EVEN COIN PURCHASE THRESHOLD
# A player must purchase coins when:
#   balance + emission_rate * days_until_event < entry_fee

# LTV BREAK-EVEN FORMULA
LTV  =  ARPU  *  Gross_Margin  *  Avg_Session_Days
CAC  =  Cost_per_Acquisition
ROI  =  (LTV - CAC) / CAC

# Target: LTV > 3 * CAC for sustainable growth

{
  "coin_packages": [
    { "coins": 500,   "price_INR": 10,  "bonus_pct": 0,   "label": "Starter Pack" },
    { "coins": 1200,  "price_INR": 20,  "bonus_pct": 20,  "label": "Bronze Bundle" },
    { "coins": 3300,  "price_INR": 50,  "bonus_pct": 65,  "label": "Silver Bundle" },
    { "coins": 7000,  "price_INR": 100, "bonus_pct": 100, "label": "Gold Bundle" },
    { "coins": 38000, "price_INR": 500, "bonus_pct": 160, "label": "Platinum Bundle" },
    { "coins": 80000, "price_INR": 999, "bonus_pct": 200, "label": "Crown Bundle" }
  ],
  "exchange_rate_INR": 80,   // 1 INR = 80 coins at base rate
  "min_withdrawal": 5000, // Minimum coin balance for real-money withdrawal
  "withdrawal_rate": 1     // 5000 coins = 62.5 INR (withdrawal fee embedded)
}

// ============================
// UNITY — AdMob Integration
// ============================
// Requires: GoogleMobileAds.Api, UnityEngine.Advertisements (or MAX)

using UnityEngine;
using GoogleMobileAds;
using GoogleMobileAds.Api;
using GoogleMobileAds.Common;

public class LudoAdManager : MonoBehaviour
{
    private string  appId        = "ca-app-pub-xxxxx~xxxxx";
    private string  adUnitId     = "ca-app-pub-xxxxx/xxxxx";
    private InterstitialAd interstitialAd;
    private RewardedAd     rewardedAd;

    void Start()
    {
        MobileAds.SetiOSAppPauseOnBackground(true);
        MobileAds.Initialize(initStatus => {
            Debug.Log("AdMob initialized");
            RequestInterstitial();
            RequestRewardedAd();
        });
    }

    // --- INTERSTITIAL ---
    void RequestInterstitial()
    {
        var adRequest = new AdRequest.Builder().Build();
        InterstitialAd.Load(adUnitId, adRequest,
            (InterstitialAd ad, AdError error) => {
                if error != null) { Debug.LogWarning(error.GetMessage()); return; }
                interstitialAd = ad;
                RegisterInterstitialEvents(interstitialAd);
            });
    }

    public void ShowInterstitialAfterRound()
    {
        if (interstitialAd != null && interstitialAd.CanShowAd())
        {
            interstitialAd.Show();
        }
    }

    // --- REWARDED VIDEO ---
    void RequestRewardedAd()
    {
        var adRequest = new AdRequest.Builder().Build();
        RewardedAd.Load(adUnitId, adRequest,
            (RewardedAd ad, AdError error) => {
                if (error != null) { Debug.LogWarning(error.GetMessage()); return; }
                rewardedAd = ad;
            });
    }

    public void ShowRewardedAdForCoins(int coinReward)
    {
        if (rewardedAd != null && rewardedAd.CanShowAd())
        {
            rewardedAd.Show(reward => {
                Debug.Log($"Rewarded ad completed. Granting {coinReward} coins");
                LudoCoinManager.GrantCoins(reward.GetType().Name, coinReward);
                RequestRewardedAd();  // Preload next ad
            });
        }
    }

    void OnDestroy()
    {
        interstitialAd?.Destroy();
    }
}

// ============================
// REACT NATIVE — AdMob Integration
// ============================
import React, { useEffect } from 'react';
import {
  InterstitialAd,
  RewardedAd,
  AdEventType,
  TestIds,
} from 'react-native-google-mobile-ads';

const adUnitId = __DEV__
  ? TestIds.INTERSTITIAL
  : 'ca-app-pub-xxxxx/xxxxx';

const rewardedAdUnitId = __DEV__
  ? TestIds.REWARDED
  : 'ca-app-pub-xxxxx/xxxxx';

const interstitial = InterstitialAd.createForAdRequest(adUnitId, {
  requestNonPersonalizedAdsOnly: true,
});

const rewarded = RewardedAd.createForAdRequest(rewardedAdUnitId, {
  requestNonPersonalizedAdsOnly: true,
});

// Singleton ad manager — keeps ads loaded between screens
export const LudoAdManager = {
  loadInterstitial: () => {
    const unsubscribe = interstitial.addAdEventListener(
      AdEventType.LOADED,
      () => console.log('Interstitial loaded'),
    );
    interstitial.load();
    return unsubscribe;
  },

  showInterstitial: (onClose: () => void) => {
    const unsubscribe = interstitial.addAdEventListener(
      AdEventType.CLOSED,
      () => { onClose(); interstitial.load(); },
    );
    if interstitial.loaded { interstitial.show(); }
  },

  showRewardedAd: (coinReward: number, onReward: () => void) => {
    const unsubscribe = rewarded.addAdEventListener(
      AdEventType.EARNED_REWARD,
      (reward) => {
        console.log(`Earned reward: ${reward.amount} coins`);
        onReward();  // Grant coins via API
      },
    );
    rewarded.load();
    if (rewarded.loaded) { rewarded.show(); }
    return unsubscribe;
  },
};

// Usage in a React component — show rewarded ad for 50 bonus coins
function WatchAdButton() {
  return (
    <button onClick={() =>
      LudoAdManager.showRewardedAd(50, () =>
        fetch('/api/coins/grant', { method: 'POST', body: JSON.stringify({ amount: 50 }) })
      )
    }>
      Watch Ad for 50 Bonus Coins
    </button>
  );
}

# ============================
# KYC VERIFICATION FLOW
# ============================

# STEP 1 — User Onboarding Trigger
# When user attempts first real-money tournament entry (stakes > 0):
# API returns: { status: "KYC_REQUIRED", redirect: "/kyc-verification" }

# STEP 2 — Minimal KYC (eKYC via Aadhaar XML)
# User enters Aadhaar number → OTP sent to registered mobile →
# XML data returned via UIDAI's eKYC service → KUA processes

# STEP 3 — Full KYC for withdrawals above ₹2,500
# PAN verification + Bank account linking required

# STEP 4 — Age Gating
# Users under 18 are blocked from RMG features entirely.
# Aadhaar DOB field used for age verification.

# STEP 5 — Self-Declaration
# User signs digital declaration: "I am 18+ and not playing from
# a restricted state." State list maintained server-side.

# STEP 6 — KYC Approval & Wallet Activation
# KUA returns: { uid: "XXXX", name, dob, gender, state }
# Server verifies state is not in BLOCKED_STATES list.
# If approved: user.rmg_approved = true; activate_withdrawal().

from fastapi import APIRouter, HTTPException, Depends
from pydantic import BaseModel
from datetime import datetime, date
from typing import Optional
import hashlib, os

router = APIRouter(prefix="/api/kyc", tags=["KYC"])

# States where RMG is restricted (update as regulations change)
BLOCKED_STATES = {"Andhra Pradesh", "Assam", "Odisha",
                   "Sikkim", "Telangana", "Nagaland",
                   "Tamil Nadu"}

class KYCRequest(BaseModel):
    user_id:        str
    aadhaar_last4:  str       # Last 4 digits only — never store full Aadhaar
    otp:            str
    consent_signed: bool

class KYCResponse(BaseModel):
    status:        str         # "approved" | "pending" | "rejected" | "manual_review"
    reason:        Optional[str] = None
    kyc_tier:      str         # "basic" | "full"

async def verify_kyc(request: KYCRequest, db=Depends(get_db)) -> KYCResponse:
    """
    Initiates Aadhaar eKYC verification via registered KUA.
    Aadhaar number is never stored — only the last 4 digits for reference.
    """
    user = await db.users.find_one({"_id": request.user_id})
    if not user:
        raise HTTPException(status_code=404, detail="User not found")

    if not request.consent_signed:
        raise HTTPException(status_code=400,
            detail="Aadhaar consent declaration must be signed")

    # Call KUA (KYC User Agency) API — e.g., IDfy, SignDesk, Veriff
    kua_response = await call_kua_api(
        aadhaar_ref=hashlib.sha256(request.aadhaar_last4.encode()).hexdigest(),
        otp=request.otp,
        api_key=os.getenv("KUA_API_KEY")
    )

    if kua_response.status == "error":
        return KYCResponse(status="manual_review",
                             reason="KYC provider could not verify. Manual review queued.",
                             kyc_tier="basic")

    uid_data = kua_response.data
    age = calculate_age(uid_data["dob"])

    if age < 18:
        return KYCResponse(status="rejected",
                             reason="User must be 18 years or older",
                             kyc_tier="basic")

    if uid_data["state"] in BLOCKED_STATES:
        return KYCResponse(status="rejected",
                             reason=f"Real-money gaming is restricted in {uid_data['state']}",
                             kyc_tier="basic")

    # Persist KYC record (store minimal PII)
    kyc_record = {
        "user_id":     request.user_id,
        "aadhaar_ref": hashlib.sha256(request.aadhaar_last4.encode()).hexdigest(),
        "name":        uid_data["name"],
        "dob":         uid_data["dob"],
        "state":       uid_data["state"],
        "verified_at": datetime.utcnow(),
        "tier":        "full" if uid_data.get("pan_verified") else "basic",
        "rmg_allowed": True,
    }
    await db.kyc_records.insert_one(kyc_record)
    await db.users.update_one({"_id": request.user_id},
                              {"$set": {"rmg_approved": True, "kyc_tier": kyc_record["tier"]}})

    return KYCResponse(status="approved", kyc_tier=kyc_record["tier"])

def calculate_age(dob_str: str) -> int:
    dob = datetime.strptime(dob_str, "%Y-%m-%d").date()
    today = date.today()
    return today.year - dob.year - ((today.month, today.day) < (dob.month, dob.day))

# ============================
# GST CALCULATION — In-App Purchases
# ============================

GST_RATE = 0.28   # 28% GST on online gaming services (FY 2025-26)
TDS_RATE = 0.05   # 5% TDS on winnings above ₹10,000 (per Income Tax Act Sec.194BA, proposed)

def calculate_gst_on_iap(package_price_inr: float) -> dict:
    """
    For a ₹500 coin package:
    - CGST: 14% of ₹500 = ₹70
    - SGST: 14% of ₹500 = ₹70  (for intrastate)
    - IGST: 28% of ₹500 = ₹140 (for interstate)
    Total GST = ₹140 per ₹500 collected
    """
    base_amount   = package_price_inr / (1 + GST_RATE)
    gst_amount    = package_price_inr - base_amount
    cgst          = gst_amount / 2
    sgst          = gst_amount / 2

    return {
        "package_price":  package_price_inr,
        "base_amount":    round(base_amount, 2),
        "cgst":          round(cgst, 2),
        "sgst":          round(sgst, 2),
        "igst":          round(gst_amount, 2),  # use IGST for interstate
        "total_gst":     round(gst_amount, 2),
        "gst_rate":      "28%",
        "taxable_value": round(base_amount, 2),
    }

def calculate_gst_on_tournament_fee(entry_fee: float, prize_pool_share: float) -> dict:
    """
    Tournament fee is treated as a supply of service.
    GST is payable on the platform's fee (entry_fee - prize_pool_payout).
    
    Example: ₹100 entry fee, 80% goes to prize pool
    - Platform retains: ₹20
    - GST on ₹20 @ 28%: ₹5.60
    - Player effectively pays: ₹100 (inclusive of GST)
    """
    platform_fee = entry_fee * (1 - prize_pool_share)
    gst_on_fee   = platform_fee * GST_RATE
    total_gst    = platform_fee * GST_RATE

    return {
        "entry_fee":        entry_fee,
        "prize_pool_payout": round(entry_fee * prize_pool_share, 2),
        "platform_fee":     round(platform_fee, 2),
        "gst_rate":         "28%",
        "gst_amount":       round(gst_on_fee, 2),
        "net_platform_rev": round(platform_fee - gst_on_fee, 2),
    }

# Example output for ₹500 IAP package:
# { package_price: 500, base_amount: 390.63, igst: 109.37, total_gst: 109.37 }
# Platform receives: ₹390.63 as taxable revenue after remitting ₹109.37 to GSTN

# ============================
# LTV CALCULATION MODEL
# ============================
import pandas as pd

def cohort_ltv(cohort_df: pd.DataFrame,
                 arppu_monthly: float,
                 monthly_churn: float,
                 margin: float = 0.70) -> dict:
    """
    Calculate LTV using the surviving-churn model.
    
    Args:
        cohort_df: DataFrame with columns [user_id, install_date, first_pay_date, total_revenue]
        arppu_monthly: Average Revenue Per Paying User per month
        monthly_churn: Monthly churn rate (0.0 - 1.0). For Ludo: 0.15-0.25 is typical.
        margin: Gross margin after GST, payment gateway fees, and platform cuts.
    
    Returns:
        dict with LTV, CAC ceiling, and ROI metrics
    """
    # Average customer lifespan in months
    avg_lifespan_months = 1 / monthly_churn

    # Simple LTV (no discounting)
    ltv_simple = arppu_monthly * avg_lifespan_months * margin

    # Discounted LTV (monthly discount rate of 5%)
    discount_rate = 0.05
    n = avg_lifespan_months
    ltv_discounted = arppu_monthly * margin * ((1 - (1 + discount_rate)**(-n)) / discount_rate)

    # CAC ceiling for positive ROI (target 3x ROI)
    cac_ceiling = ltv_discounted / 3.0

    # Example: Indian Ludo RMG cohort
    # arppu_monthly = ₹180 (median for paying users in India)
    # monthly_churn = 0.20 (80% monthly retention)
    # margin = 0.70 (after 28% GST + 2% payment gateway)
    return {
        "ltv_simple":     round(ltv_simple, 2),
        "ltv_discounted": round(ltv_discounted, 2),
        "avg_lifespan_months": round(avg_lifespan_months, 1),
        "cac_ceiling":   round(cac_ceiling, 2),
        "roi_target":    "3x",
        "max_cpa_allowed": round(cac_ceiling, 2),
        "annual_budget_per_1k_users": round(cac_ceiling * 1000, 2),
    }

# Example call:
result = cohort_ltv(
    cohort_df=None,
    arppu_monthly=180,    # ₹180 ARPPM for Indian Ludo
    monthly_churn=0.20,   # 80% monthly retention
    margin=0.70,        # After 28% GST + 2% PG fees
)
# Output: { ltv_simple: ₹630.00, ltv_discounted: ₹527.35,
#          avg_lifespan_months: 5.0, cac_ceiling: ₹175.78 }