XP, Yield matching, Carry YELD payout

このセクションでは、現行 backend における Yield メカニクスを説明します（内部 technical module 名は yield）。

1) Terms（現行システム）

  • XP: 本書では XP と呼びます。backend での内部名は xp（models/fields: XPCredit, carryLeftXP, carryRightXP）。
  • USDOL/USDOR: これらは LEFT/RIGHT branches（yield sides）です。
  • Carry YELD: backend では carryYeldUsdo（USDO-base）として保存され、yield matching で蓄積された payout pool を意味し、後で weekly caps に従って支払われます。

2) investment からの XP 計算

  • 各 investment の XP は次で計算：
    • xpBase = amountBase * xpPercent / 100
    • xpPercent は Block settings 由来（default: 20%）

3) ツリー上方向への XP 伝播

investment は investmentInviteCode に基づく placement side（LEFT または RIGHT）を持ちます：

  • placement user は同じ side で XP credit を受け取れる
  • その後 XP credit は referredByUserId chain を通じて root へ“上がる”（max depth guard=100）

4) 重要な制限: XP credits を受け取れるのは TIP3 のみ

現行システムでは：

  • XP credit は recipient user の programTier === TIP3 の場合のみ作成されます。
  • yield worker（internal module yield）にも同じ guard があり、credit receiver が TIP3 でない場合は carry を変更せず processed 済みにします。

これは次を意味します：

  • TIP1/TIP2 users は carryLeft/carryRight（yield carry）を蓄積しません。
  • TIP1/TIP2 investments は XP を“生成”しても、実際の XP credit は TIP3 の ancestor/placement node にのみ付与されます。

5) Yield matching（10 XP + 10 XP → 10 USDO）

yield worker は XPCredit records（internal name: xp）で動作します。

  • 各 credit は carryLeft または carryRight を増加。
  • Pair size は固定: 10 XP。
  • 各 matched pair の payout は固定: 10 USDO。
  • matching 後、carries は減少し payout は carryYeldUsdo に追加されます。

6) Weekly payout cap（Reward levels）

carryYeldUsdo は即時に “balance化” されません。支払いは payoutCarryYeld job で実行：

  • 各 user には userRewardStatus 内の reward level（1..4）がある。
  • 各 level には weekly max payout（defaults）：
    • L1: 2000 USDO/week
    • L2: 4000 USDO/week
    • L3: 6000 USDO/week
    • L4: 8000 USDO/week
  • user の carryYeld が残り weekly allowance を超えると、overflow は burn（未払い）。
  • Weekly payout progress は yieldAccount.weeklyPayoutUsdo + weekKey で保存。

7) Auto payout schedule

  • Block settings の yieldAutoPayoutEnabled=true なら、cron pattern（dayOfWeek/hour/minute）で repeat job payoutCarryYeld が queue に追加されます。
  • disabled の場合、repeat job は best-effort で削除されます。

8) TIP upgrade が carry に与える影響

ユーザーの overall tier が上がると：

  • Pending XP credits は旧状態から payout が発生しないよう processed に設定されます。
  • yieldAccount.carryLeftXP/carryRightXP は 0 に reset。
  • investment create flow では carryYeldUsdo も 0 に reset（upgrade endpoint では left/right carry のみ reset）。