XP, Yield matching, Carry YELD payout

Esta seção descreve a mecânica de Yield no backend atual (o módulo técnico interno chama-se yield).

1) Termos (no sistema atual)

  • XP: neste documento chamamos de XP. No backend, o nome interno é xp (models/fields: XPCredit, carryLeftXP, carryRightXP).
  • USDOL/USDOR: estes são os ramos LEFT/RIGHT (yield sides).
  • Carry YELD: armazenado no backend como carryYeldUsdo (base USDO) e significa o payout pool acumulado do yield matching, que depois é pago com caps semanais.

2) Cálculo de XP a partir de um investimento

  • Para cada investimento, XP é calculado como:
    • xpBase = amountBase * xpPercent / 100
    • xpPercent vem das configurações do Block (padrão: 20%)

3) Propagação de XP pela árvore

Um investimento tem um placement side (LEFT ou RIGHT) com base em investmentInviteCode:

  • O usuário de placement pode receber um crédito XP no mesmo lado
  • Depois o crédito XP “sobe” pela cadeia referredByUserId até a root (max depth guard=100)

4) Limitação importante: somente usuários TIP3 recebem créditos XP

No sistema atual:

  • Um crédito XP é criado somente se o programTier === TIP3 do usuário receptor.
  • A mesma guarda existe no worker de yield (módulo interno yield): se o credit receiver não for TIP3, o crédito é apenas marcado como processado sem alterar carry.

Isso significa:

  • Usuários TIP1/TIP2 não acumulam carryLeft/carryRight (yield carry).
  • Investimentos TIP1/TIP2 podem “criar” XP, mas o crédito XP real é recebido somente pelo ancestor/nó de placement que é TIP3.

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

O worker de yield opera em registros XPCredit (nome interno: xp).

  • Cada crédito aumenta carryLeft ou carryRight.
  • O tamanho do par é fixo: 10 XP.
  • Para cada par casado, o payout é fixo: 10 USDO.
  • Após o matching, carries diminuem e o payout é adicionado a carryYeldUsdo.

6) Cap semanal de payout (Reward levels)

carryYeldUsdo não “vira saldo” instantaneamente. O pagamento é feito pelo job payoutCarryYeld:

  • Cada usuário tem um reward level (1..4) em userRewardStatus.
  • Cada nível tem um payout máximo semanal (padrões):
    • L1: 2000 USDO/semana
    • L2: 4000 USDO/semana
    • L3: 6000 USDO/semana
    • L4: 8000 USDO/semana
  • Se o carryYeld do usuário exceder o limite semanal restante, o excedente é burned (não pago).
  • O progresso do payout semanal é armazenado usando yieldAccount.weeklyPayoutUsdo + weekKey.

7) Auto payout schedule

  • Se nas configurações do Block houver yieldAutoPayoutEnabled=true, um repeat job payoutCarryYeld é adicionado à queue com um cron pattern (dayOfWeek/hour/minute).
  • Se desativado, o repeat job é removido em modo best-effort.

8) Efeito de upgrade de TIP sobre carry

Quando o tier geral de um usuário aumenta:

  • Créditos XP pendentes são marcados como processados para que o payout não aconteça a partir do estado antigo.
  • yieldAccount.carryLeftXP/carryRightXP são resetados para 0.
  • No fluxo de criação de investimento, carryYeldUsdo também é resetado para 0 (exceto no endpoint de upgrade, onde só o carry left/right é resetado).