games_app/docs/PREDICTION-HOUSE-EDGE-CONFIG.md

334 lines
13 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Configuration marge plateforme (prédictions Candle Predict)
Guide pour calibrer les règles de round (gagnant du pool, neutres, Daily revenue) afin de **conserver une marge nette** après les **commissions de parrainage**, destinée à la maintenance et à l’hébergement.
Où configurer : **Admin → Catalog** (Candle Predict) + **Admin → Referral** (niveaux de commission).
---
## Hypothèses économiques
| Paramètre | Valeur retenue dans ce guide |
|-----------|------------------------------|
| Commissions prédiction (somme de tous les niveaux) | **15 %** de la mise |
| Quand la commission est payée | Settle **gagné** ou **perdu** uniquement |
| Quand elle n’est **pas** payée | Round **neutre** (remboursement) |
| Multiplicateur de payout (défaut) | **1,9×** (`payout_multiplier`) |
| Objectifs traités ici | **+10 % nets** ou **+5 % nets** par volume de mises non neutres |
### Formule de base
Marge **jeu** (avant commissions), sur un round non neutre :
\[
H = 1 - M \times w
\]
- \(M\) = multiplicateur de payout (ex. 1,9)
- \(w\) = part des mises du **côté gagnant** / total des mises du round
Marge **nette** plateforme (si toute la volume est commissionnée à 15 %) :
\[
\text{Net} \approx H - 0{,}15
\]
| Objectif net | Marge jeu minimale \(H\) requise |
|-------------|----------------------------------|
| **+10 %** | **≥ 25 %** |
| **+5 %** | **≥ 20 %** |
Avec \(M = 1{,}9\) :
| Objectif net | Part max du côté gagnant \(w\) | Écart min entre pools |
|--------------|--------------------------------|------------------------|
| **+10 %** | ≲ **39,5 %** | ≳ **~21 points** (ex. ≥ 60,5 / 39,5) |
| **+5 %** | ≲ **42,1 %** | ≳ **~16 points** (ex. ≥ 58 / 42) |
> **Important :** le champ **Daily revenue target** cumule le **PnL jeu uniquement** (mises − payouts). Il **ne déduit pas** les 15 % de commissions. Pour un objectif net réel, la cible journalière doit être calée sur \(H\) (25 % ou 20 % du volume), pas sur le net seul.
---
## Deux modes de gagnant du pool
### A. Minority pool wins (smaller total stake)
- Le **plus petit** pool gagne toujours (hors neutre).
- Permet de viser une marge **par round non neutre** en **filtrant** les rounds trop serrés via **min tolerance**.
- Recommandé si l’objectif est « **chaque** round non neutre ≥ X % nets ».
### B. Daily revenue target (random + financial gate)
- Neutres min/max d’abord, puis hasard Long/Short.
- Si le hasard donne la **majorité** et que payer cette majorité ferait passer le PnL du jour **sous** la cible → stratégie overflow :
- **Make the minority win**, ou
- **Declare a neutral round (refund)**.
- Si après le round le PnL reste **≥ cible**, la majorité **peut** gagner (elle peut grignoter le surplus au-dessus du plancher, pas descendre sous la cible).
- Protège surtout le **cumul UTC du jour**, **pas** chaque round individuellement.
---
## Règles de neutralité (min / max)
| Règle | Effet | 50/50 exact |
|-------|--------|-------------|
| **Min tolerance** | Neutre si \|Long% − Short%\| ≤ seuil | Toujours neutre, même si min est OFF |
| **Max tolerance** | Neutre si le plus gros pool ≥ seuil (ex. 95/5, solo 100 %) | — |
- **Min ON** : filet « pools trop proches ».
- **Max ON** : filet « extrême / solo » (remboursement).
- **Max OFF** : les rounds extrêmes se jouent ; en **Minority**, souvent très favorables à la plateforme (la petite side gagne) ; UX plus dure pour un joueur solo.
---
## Configuration pour **+10 % nets** (commissions 15 %)
Marge jeu cible : **25 %**.
### Option 1 — Minority (garantie par round non neutre)
| Paramètre | Valeur |
|-----------|--------|
| Pool winner rule | **Minority pool wins** |
| Payout multiplier | **1,90** (ou voir table ci-dessous) |
| Enable min tolerance | **ON** |
| Min tolerance (%) | **21** (plage 20–22) |
| Enable max tolerance | **ON** (recommandé) |
| Max tolerance (%) | **95** |
Effet : seuls les rounds assez déséquilibrés (écart ≳ 21 %) se jouent ; la minorité gagne ; net ≈ ≥ 10 % après 15 % de commissions (volume pleinement commissionné).
Si vous baissez le multiplicateur :
| Payout \(M\) | Min tolerance ≈ (objectif +10 % nets) |
|--------------|----------------------------------------|
| 1,90 | **21 %** |
| 1,85 | **19 %** |
| 1,80 | **17 %** |
| 1,70 | **12 %** |
### Option 2 — Daily revenue (plancher journalier)
| Paramètre | Valeur |
|-----------|--------|
| Pool winner rule | **Daily revenue target** |
| Overflow | **Make the minority win** |
| Daily revenue target | **`0,25 × volume moyen quotidien (USDT)`** |
| Min tolerance | **ON → 2 %** (filet classique, pas le filtre 21 %) |
| Max tolerance | **ON → 95 %** |
| Payout multiplier | **1,85–1,90** |
#### Cible USDT/jour (10 % nets → plancher jeu 25 %)
| Volume moyen / jour | `dailyRevenueTarget` |
|---------------------|----------------------|
| 200 USDT | **50** |
| 500 USDT | **125** |
| 1 000 USDT | **250** |
| 2 000 USDT | **500** |
| 5 000 USDT | **1 250** |
| 10 000 USDT | **2 500** |
Lire le volume : **Admin → Dashboard** (segments real main+bonus, hors test) sur 7 ou 30 jours, puis ÷ nombre de jours.
---
## Configuration pour **+5 % nets** (commissions 15 %)
Marge jeu cible : **20 %**.
### Option 1 — Minority (garantie par round non neutre)
| Paramètre | Valeur |
|-----------|--------|
| Pool winner rule | **Minority pool wins** |
| Payout multiplier | **1,90** |
| Enable min tolerance | **ON** |
| Min tolerance (%) | **16** (plage 15–17) |
| Enable max tolerance | **ON** (recommandé) |
| Max tolerance (%) | **95** |
| Payout \(M\) | Min tolerance ≈ (objectif +5 % nets) |
|--------------|--------------------------------------|
| 1,90 | **16 %** |
| 1,85 | **14 %** |
| 1,80 | **11 %** |
| 1,70 | **6 %** |
### Option 2 — Daily revenue (plancher journalier)
| Paramètre | Valeur |
|-----------|--------|
| Pool winner rule | **Daily revenue target** |
| Overflow | **Make the minority win** |
| Daily revenue target | **`0,20 × volume moyen quotidien (USDT)`** |
| Min tolerance | **ON → 2 %** |
| Max tolerance | **ON → 95 %** |
#### Cible USDT/jour (5 % nets → plancher jeu 20 %)
| Volume moyen / jour | `dailyRevenueTarget` |
|---------------------|----------------------|
| 200 USDT | **40** |
| 500 USDT | **100** |
| 1 000 USDT | **200** |
| 2 000 USDT | **400** |
| 5 000 USDT | **1 000** |
| 10 000 USDT | **2 000** |
---
## Tableau récapitulatif
| Objectif net | Mode | Min tolerance | Max tolerance | Daily target |
|--------------|------|---------------|---------------|--------------|
| **10 %** | Minority | **21 % ON** | **95 % ON** | n/a |
| **10 %** | Daily revenue | **2 % ON** | **95 % ON** | **0,25 × volume/jour** |
| **5 %** | Minority | **16 % ON** | **95 % ON** | n/a |
| **5 %** | Daily revenue | **2 % ON** | **95 % ON** | **0,20 × volume/jour** |
Overflow Daily revenue recommandé dans les deux cas : **Make the minority win** (plutôt que neutre), pour limiter les remboursements quand la majorité menacerait le plancher.
---
## Commissions (rappel)
- Configurer les **niveaux referral** pour que la somme des % prédiction ≈ **15 %**.
- Payées depuis le **bonus pool** plateforme, pas déduites du compteur Daily revenue.
- Joueurs sans parrain / chaîne courte / caps / Sybil → commission réelle parfois **< 15 %** (marge nette alors un peu meilleure que le modèle).
---
## Max tolerance OFF — que se passe-t-il ?
| | Max ON (95 %) | Max OFF |
|--|---------------|---------|
| Solo / 95/5 | Souvent **neutre** (refund) | Round **joué** |
| Minority | — | Très souvent **favorable** plateforme |
| Daily revenue (cible déjà OK) | Extrêmes souvent neutres | Un gros pool peut encore gagner si le PnL reste ≥ cible |
Désactiver max augmente la rentabilité potentielle en Minority, mais durcit l’expérience solo. Pour un objectif « chaque non-neutre ≥ X % », max OFF reste **compatible** (ces rounds dépassent largement X %) ; max ON est un choix **UX / prudence**.
---
## Multi-bougies (niveaux 2, 3, 4, 5)
Le multi **ne se calibre pas** comme le single (1,9× + part du pool gagnant).
La marge vient surtout du **taux d’échec de la séquence** : le joueur doit enchaîner **N** bonnes directions.
### Règles de settlement (rappel)
| Événement | Joueur | Marge jeu | Commission 15 % |
|-----------|--------|-----------|-----------------|
| Mauvaise direction (n’importe quelle étape) | Perd la mise | **+100 %** de la mise | Oui |
| Séquence complète gagnée | Crédit **M × mise** | **1 − M** | Oui |
| Neutre (n’importe quelle étape) | Remboursement total | **0 %** | Non |
| Bonne étape, pas la dernière | Mise toujours lockée | 0 pour l’instant | Non |
- `payout_multiplier` = gain si la séquence entière est correcte.
- `pool_multiplier` = poids dans le pool Long/Short **uniquement à la dernière bougie** (ne change pas le montant payé au gagnant).
- Où configurer : **Admin → Catalog** → niveaux multi-bougies.
### Hypothèse de calibration
- Environ **50 %** de chance de matcher la direction à chaque étape (surtout les étapes intermédiaires en mode auto).
- Commissions **15 %** sur chaque settle gagné/perdu.
- Marge nette cible : **Net ≈ 0,85 − M × (0,5)^N**.
Pour **+10 % nets** il faut \(H \ge 25\%\) ⇒ \(M \le 0{,}75 / (0{,}5)^N\).
Pour **+5 % nets** il faut \(H \ge 20\%\) ⇒ \(M \le 0{,}80 / (0{,}5)^N\).
### Défauts actuels (seed)
| Niveau | Bougies | Payout défaut | Pool défaut |
|--------|---------|---------------|-------------|
| 2 | 2 | **3×** | 3 |
| 3 | 3 | **6×** | 6 |
| 4 | 4 | **10×** | 10 |
| 5 | 5 | **15×** | 15 |
### Plafonds recommandés (fair ~50 % / étape)
| Niveau | Max \(M\) pour **≥ +10 % nets** | Max \(M\) pour **≥ +5 % nets** | Défaut | Lecture |
|--------|----------------------------------|----------------------------------|--------|---------|
| **2** | **≤ 3,0** | **≤ 3,2** | 3 | Juste à la limite +10 % |
| **3** | **≤ 6,0** | **≤ 6,4** | 6 | Juste à la limite +10 % |
| **4** | **≤ 12** | **≤ 12,8** | 10 | Confortable pour +10 % |
| **5** | **≤ 24** | **≤ 25,6** | 15 | Très confortable ; marge pour monter un peu |
### Valeurs concrètes recommandées
**Objectif sérieux +10 % nets :**
| Niveau | Payout recommandé | Pool (conseil) |
|--------|-------------------|----------------|
| 2 | **2,9** (plage 2,7–3,0) | ≈ payout |
| 3 | **5,8** (plage 5,5–6,0) | ≈ payout |
| 4 | **10** (plage 9–12) | ≈ payout |
| 5 | **15–18** (plafond dur 24) | ≈ payout |
**Objectif +5 % nets (un peu plus attractif marketing) :**
| Niveau | Payout recommandé | Pool (conseil) |
|--------|-------------------|----------------|
| 2 | **3,0–3,1** (≤ 3,2) | ≈ payout |
| 3 | **6,0** (≤ 6,4) | ≈ payout |
| 4 | **10–12** | ≈ payout |
| 5 | **15–20** | ≈ payout |
### Notes multi
1. Ne **pas** dépasser ~**3×** au niveau 2 si l’objectif dur est +10 % nets.
2. Les défauts **3 / 6 / 10 / 15** conviennent déjà pour ~+10 % aux niveaux 4–5 ; **baisser légèrement 2 et 3** donne un vrai coussin.
3. Si les joueurs battent clairement 50 % (skill / biais), les plafonds baissent : ex. à ~55 %/étape, niveau 2 ≈ **≤ 2,5×** pour +10 % nets.
4. Un neutre en cours de multi **rembourse toute la mise** → 0 marge, 0 commission.
5. Minority / Daily revenue influencent surtout la **dernière** bougie (et les maturités partagées avec des singles) ; ce n’est **pas** un substitut au calibrage de \(M\).
---
## Limites à connaître
1. **Aucun mode ne garantit +X % si le multiplicateur et les neutres ne sont pas calés** comme ci-dessus.
2. **Daily revenue** = plancher **jour**, pas round par round ; des rounds majorité au-dessus de la cible peuvent réduire le surplus.
3. Rounds **neutres** : 0 % marge jeu, **0 %** commission.
4. **Multi-bougies** : calibrer via la section dédiée (edge = échec de séquence, pas \(1 - M \cdot w\)).
5. Le modèle « Net = H − 15 % » suppose un volume **pleinement** commissionné à 15 %.
---
## Checklist rapide
**Pour +10 % nets, Minority :**
1. Pool winner = Minority
2. Min = **21 %** ON
3. Max = **95 %** ON
4. Commissions niveaux Σ = **15 %**
5. Payout single ≈ **1,9**
6. Multi payouts ≈ **2,9 / 5,8 / 10 / 15–18**
**Pour +5 % nets, Minority :**
1. Idem avec Min = **16 %** ON
2. Multi payouts ≈ **3,0–3,1 / 6,0 / 10–12 / 15–20**
**Pour Daily revenue :**
1. Overflow = Minority win
2. Target = **0,25 × volume** (10 %) ou **0,20 × volume** (5 %)
3. Min **2 %** / Max **95 %** ON
4. Recalculer la cible quand le volume moyen change
5. Même calibrage multi que ci-dessus
---
## Références code
- Settlement / PnL jour : `backend/src/domain/candle-predict/index.ts`
- Daily revenue + overflow : `backend/src/services/dailyRevenueOutcomeService.ts`
- Neutres min/max : `backend/src/services/candleGenerationService.ts` (`resolvePoolNeutrality`)
- Commissions prédiction : `backend/src/services/referralService.ts` (`processPredictionReferralCommissions`)
- Multi settlement : `backend/src/services/candlePredictMultiService.ts`
- UI admin : `prediqo_web/src/features/catalog/CandlePredictConfigPanel.tsx`
- UI multi levels : `prediqo_web/src/features/catalog/CandlePredictMultiLevelsPanel.tsx`