XP, Yield matching, Carry YELD payout

This section describes Yield mechanics in the current backend (the internal technical module is called yield).

1) Terms (in the current system)

  • XP: in this document we call it XP. In the backend the internal name is xp (models/fields: XPCredit, carryLeftXP, carryRightXP).
  • USDOL/USDOR: these are the LEFT/RIGHT branches (yield sides).
  • Carry YELD: stored in the backend as carryYeldUsdo (USDO-base) and means the payout pool accumulated from yield matching, which is later paid out with weekly caps.

2) XP calculation from an investment

  • For each investment, XP is calculated as:
    • xpBase = amountBase * xpPercent / 100
    • xpPercent comes from Block settings (default: 20%)

3) XP propagation up the tree

An investment has a placement side (LEFT or RIGHT) based on investmentInviteCode:

  • The placement user can receive an XP credit on the same side
  • Then the XP credit “moves upward” via the referredByUserId chain up to the root (max depth guard=100)

4) Important limitation: only TIP3 users receive XP credits

In the current system:

  • An XP credit is created only if the recipient user’s programTier === TIP3.
  • The same guard exists in the yield worker (internal module yield): if the credit receiver is not TIP3, the credit is simply marked processed without changing carry.

This means:

  • TIP1/TIP2 users do not accumulate carryLeft/carryRight (yield carry).
  • TIP1/TIP2 investments may “create” XP, but the actual XP credit is received only by the ancestor/placement node that is TIP3.

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

The yield worker operates on XPCredit records (internal name: xp).

  • Each credit increases carryLeft or carryRight.
  • Pair size is fixed: 10 XP.
  • For each matched pair, payout is fixed: 10 USDO.
  • After matching, carries decrease and payout is added to carryYeldUsdo.

6) Weekly payout cap (Reward levels)

carryYeldUsdo does not instantly “become balance”. Payment is done by the payoutCarryYeld job:

  • Each user has a reward level (1..4) in userRewardStatus.
  • Each level has a weekly max payout (defaults):
    • L1: 2000 USDO/week
    • L2: 4000 USDO/week
    • L3: 6000 USDO/week
    • L4: 8000 USDO/week
  • If the user’s carryYeld exceeds the remaining weekly allowance, overflow is burned (not paid).
  • Weekly payout progress is stored using yieldAccount.weeklyPayoutUsdo + weekKey.

7) Auto payout schedule

  • If Block settings has yieldAutoPayoutEnabled=true, a repeat job payoutCarryYeld is added to the queue with a cron pattern (dayOfWeek/hour/minute).
  • If disabled, the repeat job is removed on a best-effort basis.

8) Effect of TIP upgrade on carry

When a user’s overall tier increases:

  • Pending XP credits are marked processed so that payout does not happen from the old state.
  • yieldAccount.carryLeftXP/carryRightXP are reset to 0.
  • In the investment create flow, carryYeldUsdo is also reset to 0 (except in the upgrade endpoint, where only left/right carry is reset).