XP, Yield matching, Carry YELD payout

Questa sezione descrive la meccanica Yield nel backend attuale (il modulo tecnico interno si chiama yield).

1) Termini (nel sistema attuale)

  • XP: in questo documento lo chiamiamo XP. Nel backend il nome interno è xp (models/fields: XPCredit, carryLeftXP, carryRightXP).
  • USDOL/USDOR: questi sono i rami LEFT/RIGHT (yield sides).
  • Carry YELD: memorizzato nel backend come carryYeldUsdo (base USDO) e indica il payout pool accumulato dal yield matching, che viene poi pagato con caps settimanali.

2) Calcolo XP da un investimento

  • Per ogni investimento, XP è calcolato come:
    • xpBase = amountBase * xpPercent / 100
    • xpPercent proviene dalle impostazioni del Block (predefinito: 20%)

3) Propagazione XP lungo l'albero

Un investimento ha un placement side (LEFT o RIGHT) basato su investmentInviteCode:

  • L'utente di placement può ricevere un credito XP sullo stesso lato
  • Poi il credito XP “sale” tramite la catena referredByUserId fino alla root (max depth guard=100)

4) Limitazione importante: solo utenti TIP3 ricevono crediti XP

Nel sistema attuale:

  • Un credito XP viene creato solo se il programTier === TIP3 dell'utente destinatario.
  • La stessa guardia esiste nel yield worker (modulo interno yield): se il credit receiver non è TIP3, il credito viene semplicemente marcato come processato senza cambiare carry.

Questo significa:

  • Gli utenti TIP1/TIP2 non accumulano carryLeft/carryRight (yield carry).
  • Gli investimenti TIP1/TIP2 possono “creare” XP, ma il credito XP reale viene ricevuto solo dall'ancestor/nodo placement che è TIP3.

5) Yield matching (10 XP + 10 XP → 10 USDO)

Il yield worker opera sui record XPCredit (nome interno: xp).

  • Ogni credito aumenta carryLeft o carryRight.
  • La dimensione coppia è fissa: 10 XP.
  • Per ogni coppia abbinata, il payout è fisso: 10 USDO.
  • Dopo il matching, i carries diminuiscono e il payout viene aggiunto a carryYeldUsdo.

6) Cap payout settimanale (Reward levels)

carryYeldUsdo non “diventa saldo” istantaneamente. Il pagamento è effettuato dal job payoutCarryYeld:

  • Ogni utente ha un reward level (1..4) in userRewardStatus.
  • Ogni livello ha un max payout settimanale (predefiniti):
    • L1: 2000 USDO/settimana
    • L2: 4000 USDO/settimana
    • L3: 6000 USDO/settimana
    • L4: 8000 USDO/settimana
  • Se il carryYeld dell'utente supera il restante limite settimanale, l'eccedenza viene bruciata (non pagata).
  • Il progresso payout settimanale è memorizzato usando yieldAccount.weeklyPayoutUsdo + weekKey.

7) Auto payout schedule

  • Se nelle impostazioni Block c'è yieldAutoPayoutEnabled=true, un repeat job payoutCarryYeld viene aggiunto alla queue con un cron pattern (dayOfWeek/hour/minute).
  • Se disabilitato, il repeat job viene rimosso in modalità best-effort.

8) Effetto dell'upgrade TIP sul carry

Quando il tier complessivo di un utente aumenta:

  • I crediti XP pendenti sono marcati come processati così che il payout non avvenga dallo stato precedente.
  • yieldAccount.carryLeftXP/carryRightXP vengono resettati a 0.
  • Nel flusso di creazione investimento, anche carryYeldUsdo viene resettato a 0 (eccetto nell'endpoint upgrade, dove viene resettato solo il carry left/right).