XP, Yield matching, وCarry YELD payout

يشرح هذا القسم آلية Yield في backend الحالي (ويُسمى الموديول التقني الداخلي yield).

1) المصطلحات (في النظام الحالي)

• XP: في هذا المستند نسميه XP. في backend الاسم الداخلي هو xp (models/fields: XPCredit, carryLeftXP, carryRightXP).
• USDOL/USDOR: هما فرعا LEFT/RIGHT (جهتا yield).
• Carry YELD: يُخزن في backend باسم carryYeldUsdo (USDO-base) ويعني payout pool المتراكم من yield matching، والذي يُدفع لاحقًا مع weekly caps.

2) حساب XP من الاستثمار

• لكل استثمار، يتم حساب XP كالتالي:
  • xpBase = amountBase * xpPercent / 100
  • تأتي xpPercent من Block settings (الافتراضي: 20%)

3) انتقال XP صعودًا في الشجرة

يمتلك الاستثمار placement side (LEFT أو RIGHT) بناءً على investmentInviteCode:

• يمكن لمستخدم placement أن يستلم XP credit على نفس الجهة
• ثم يتحرك XP credit صعودًا عبر سلسلة referredByUserId حتى root (max depth guard=100)

4) قيد مهم: فقط مستخدمو TIP3 يستقبلون XP credits

في النظام الحالي:

• يتم إنشاء XP credit فقط إذا كان programTier === TIP3 لدى المستخدم المستلم.
• توجد نفس الحماية في yield worker (الموديول الداخلي yield): إذا لم يكن مستلم credit من TIP3، يتم فقط وضع علامة processed على credit دون تغيير carry.

وهذا يعني:

• مستخدمو TIP1/TIP2 لا يراكمون carryLeft/carryRight (yield carry).
• قد تُنشئ استثمارات TIP1/TIP2 قيمة XP، لكن XP credit الفعلي يستلمه فقط ancestor/placement node الذي هو TIP3.

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

يعمل yield worker على سجلات XPCredit (الاسم الداخلي: xp).

• كل credit يزيد carryLeft أو carryRight.
• حجم الزوج ثابت: 10 XP.
• لكل matched pair، يكون payout ثابتًا: 10 USDO.
• بعد matching تنخفض carries وتُضاف قيمة payout إلى carryYeldUsdo.

6) Weekly payout cap (Reward levels)

carryYeldUsdo لا يتحول مباشرةً إلى balance. يتم الدفع عبر job باسم payoutCarryYeld:

• لكل مستخدم reward level (1..4) في userRewardStatus.
• لكل مستوى weekly max payout (افتراضيًا):
  • L1: 2000 USDO/week
  • L2: 4000 USDO/week
  • L3: 6000 USDO/week
  • L4: 8000 USDO/week
• إذا تجاوز carryYeld المتبقي من الحد الأسبوعي، يتم burned للجزء الزائد (لا يُدفع).
• يتم حفظ تقدم weekly payout عبر yieldAccount.weeklyPayoutUsdo + weekKey.

7) Auto payout schedule

• إذا كانت Block settings تحتوي yieldAutoPayoutEnabled=true، تتم إضافة repeat job باسم payoutCarryYeld إلى queue مع cron pattern (dayOfWeek/hour/minute).
• إذا كانت معطلة، يتم إزالة repeat job بأسلوب best-effort.

8) تأثير TIP upgrade على carry

عند ارتفاع tier العام للمستخدم:

• يتم تعليم Pending XP credits على أنها processed حتى لا يحدث payout من الحالة القديمة.
• تتم إعادة yieldAccount.carryLeftXP/carryRightXP إلى 0.
• في investment create flow، تتم أيضًا إعادة carryYeldUsdo إلى 0 (باستثناء upgrade endpoint، حيث تتم إعادة left/right carry فقط).