# ADbotix — Development Specification

**Module-by-Module Engineering & Business-Logic Document**

| Field | Value |
|---|---|
| Document | ADbotix — Development Specification |
| Version | 1.0 |
| Prepared by | Onexcell |
| Platform base | PHP 8.x · Yii2 · MySQL 8.x (InnoDB) |
| Status | Production baseline — feed to Claude Code module by module |

---

## 0. Purpose & How to Read This Document

This is the authoritative engineering specification for the ADbotix platform. It supersedes the earlier Business Requirement & Project Flow draft and resolves every open numeric and logic question raised during client discussion.

It is organised **by functional module**. Each module follows the same structure so the build can be implemented, tested, and signed off one module at a time:

- **Purpose** — what the module does.
- **Business Rules** — the authoritative logic the code must enforce.
- **Data Model** — tables and key fields.
- **Calculations & Examples** — worked numbers using locked values.
- **Edge Cases** — conditions the build must handle explicitly.
- **Acceptance Criteria** — what "done" means for QA.

**Locked:** All income percentages, the $30 split, matrix structure, rebirth ladder, cap tiers, fees, and withdrawal rules are final and used throughout.

**Open (client to confirm):** Only the items listed in §14. They do not block core development.

---

## 1. System Architecture Overview

### 1.1 Platform Summary

ADbotix is an investment-based earning platform with three independent income engines that operate simultaneously for every user: **Stacking**, **Holding**, and the **Global Auto Pool**. Every investment automatically carves out a fixed $30 per pool entry to the Global Auto Pool; the remainder becomes the **Working Investment** that drives Stacking or Holding returns.

### 1.2 Technology Base

| Layer | Technology | Notes |
|---|---|---|
| Backend framework | PHP 8.x · Yii2 | MVC + ActiveRecord. Reuses existing platform base. |
| Database | MySQL 8.x (InnoDB) | Transactional integrity required for all wallet operations. |
| Frontend | Bootstrap + server-rendered views | Admin and user dashboards. |
| Scheduled jobs | Yii2 console commands (cron) | Daily ROI, daily level income, weekly payout, monthly royalty/rank. |
| Crypto rails | MetaMask deposit · manual admin payout | On-chain verification by tx-hash; no live gateway in phase 1. |

### 1.3 Module Map

| # | Module | Responsibility |
|---|---|---|
| M1 | Authentication & Accounts | Registration, email validation, multi-account, login. |
| M2 | Referral Network & Sponsor Tree | Sponsor linkage, direct counting, genealogy. |
| M3 | Investment & Wallet Core | Deposits, $30 carve-out, wallet ledger, transfers. |
| M4 | Stacking Engine | Fixed-term plans, daily accrual, maturity unlock. |
| M5 | Holding Engine | Tier-based daily ROI, no lock. |
| M6 | Global Auto Pool | Matrix placement, referral, royalty, rebirth. |
| M7 | 30-Level Team Income | Daily level income on combined ROI. |
| M8 | Rank & Reward (60:40) | Qualified business, ranks, rewards, global share. |
| M9 | Capping Engine | 3X investor / 4X leader cap enforcement. |
| M10 | Withdrawal Engine | Requests, fees, weekly processing, tx-hash. |
| M11 | Admin Panel | Approvals, configuration, reports, audit. |
| M12 | Scheduled Jobs | All cron-driven calculations and payouts. |

---

## 2. Global Business Rules (Single Source of Truth)

These values are referenced by every module. Final unless explicitly marked open.

### 2.1 Investment & Split

| Rule | Value |
|---|---|
| Minimum investment | $80 |
| Global Pool carve-out (per pool entry) | $30 (fixed) |
| Working Investment | `Investment − ($30 × pool_entries)` |
| Plans available | Stacking and/or Holding (both allowed at once) |
| Re-topup | Allowed any time; each deposit is independent |

### 2.2 Fees, Limits & Withdrawals

| Rule | Value |
|---|---|
| Minimum withdrawal | $10 |
| Withdrawal fee | 5% on every withdrawal (`net = gross × 0.95`) |
| User-to-user transfer | Allowed; 5% cut on transferred amount |
| Weekly withdrawal limit | None |
| Withdrawal processing cycle | Weekly (manual admin payout, tx-hash recorded) |
| Withdrawable balances | ROI **and** commission both withdrawable |
| Stacking income withdrawal | Request allowed **only after** lock period completes |

### 2.3 Capping

Two cap tiers apply, based on whether a user has become a Leader. The cap counts **only** Rank Rewards, Stacking income, and Holding/level income. Global Auto Pool income (Referral, Royalty, Matrix, Rebirth) is **never** counted toward the cap and never stops.

| Tier | Condition | Cap | On $1,000 working |
|---|---|---|---|
| Investor | Default (invest only) | 3X | Max $3,000 capped income |
| Leader | Sponsors 2 direct investors | 4X | Max $4,000 capped income |

- **Counts toward cap (stops at limit):** Rank Rewards · Stacking income · Holding / 30-Level income on ROI.
- **Outside cap (never stops):** Global Auto Pool — Referral (15-level), Royalty, Matrix, Rebirth.
- **Leader upgrade is permanent** once the 2 direct investors are achieved; the cap moves from 3X to 4X and is not recalculated downward.

### 2.4 Income Types — Master List

| Income | Engine | Frequency | In Cap? |
|---|---|---|---|
| Stacking profit | Stacking | Accrues daily, withdraw at maturity | Yes |
| Holding ROI | Holding | Daily | Yes |
| 30-Level income | Team | Daily (on combined ROI) | Yes |
| Rank reward | Rank | On achievement (permanent) | Yes |
| Global business share | Rank | Monthly | Yes |
| Referral (15-level) | Global Pool | On pool entry | No |
| Royalty Pool 1 & 2 | Global Pool | Monthly | No |
| Matrix income | Global Pool | On cycle completion | No |
| Rebirth income | Global Pool | On rebirth cycle | No |

---

## M1 — Authentication & Accounts

### M1.1 Purpose
Handle user registration with email validation only (no KYC), support multiple accounts per email, and username-based login.

### M1.2 Business Rules
- Registration requires: unique **Username**, **Email**, **Password**, and **Sponsor Username**.
- Email verification is required before an account can transact. No KYC, Aadhaar, PAN, or selfie.
- **Multi-account:** one email may create multiple accounts (e.g. `john01`, `john02`, `john03`). Each account is independent for investment, wallet, tree, and income.
- Login uses **Username + Password** (not email, since email is shared across accounts).
- Sponsor Username must exist and be a valid account; locked at registration, cannot be changed later.

### M1.3 Data Model

| Table | Key Fields | Notes |
|---|---|---|
| `users` | id, username (unique), email, password_hash, sponsor_id, email_verified_at, status, created_at | `email` NOT unique (multi-account); `username` unique. |
| `email_verifications` | id, user_id, token, expires_at, used_at | One active token per pending account. |
| `login_audit` | id, user_id, ip, user_agent, created_at | Security trail. |

### M1.4 Registration Flow
```
User submits username + email + password + sponsor
  ↓
Validate username unique + sponsor exists
  ↓
Create user (status = pending)
  ↓
Send email verification token
  ↓
User verifies email
  ↓
status = active → may invest
```

### M1.5 Edge Cases
- Duplicate username → reject with clear message.
- Sponsor username not found → reject; do not auto-assign a default sponsor.
- Unverified account attempts deposit → block until verified.
- Same email, many accounts → allowed; each verification is per-account.

### M1.6 Acceptance Criteria
1. A user can register, verify email, and log in by username.
2. One email successfully creates 3+ independent accounts.
3. Registration is impossible without a valid existing sponsor.
4. Unverified accounts cannot deposit or withdraw.

---

## M2 — Referral Network & Sponsor Tree

### M2.1 Purpose
Maintain the sponsor genealogy used by 30-Level income, Rank (60:40), Leader qualification, and Global Pool qualification.

### M2.2 Business Rules
- Each account has exactly one sponsor (set at registration, immutable).
- **Referral link is available once the user has invested.** A user must have an active investment before their referral link counts new joinings toward their directs.
- **Direct** = an account whose `sponsor_id` is this user.
- **Leader qualification:** a user becomes a Leader (4X cap) upon sponsoring **2 direct investors** (directs who have themselves invested). Permanent once achieved.
- **Global Pool qualification:** **3 direct referrals** trigger automatic placement of the user into the Global Auto Pool (see M6).

### M2.3 Data Model

| Table | Key Fields | Notes |
|---|---|---|
| `users` | sponsor_id, is_leader, leader_since, direct_count, direct_invested_count | Counters denormalised for speed; recomputed on events. |
| `tree_closure` | ancestor_id, descendant_id, depth | Closure table for fast N-level descendant queries (30-level + 60:40). |

> **Why a closure table:** 30-Level income and the 60:40 rule both need fast recursive descendant lookups. A closure table (ancestor, descendant, depth) makes "all descendants of X" and "descendants of X at depth N" single indexed queries, avoiding expensive recursion on every daily job.

### M2.4 Leader Qualification Flow
```
Direct referral makes first investment
  ↓
Increment sponsor.direct_invested_count
  ↓
If direct_invested_count >= 2 and not leader
  ↓
Set is_leader = true, leader_since = now, cap_multiplier = 4
```

### M2.5 Edge Cases
- Direct registers but never invests → does not count toward Leader (needs invested directs).
- Direct invests then is refunded/zeroed → Leader status is **permanent** once granted (does not revert).
- User shares link before investing → joinings recorded, but Leader/Pool counters only advance once the referrer is active.

### M2.6 Acceptance Criteria
1. Sponsoring 2 invested directs flips the account to Leader with 4X cap, permanently.
2. Closure table returns correct descendant sets at any depth.
3. 3 directs trigger Global Pool placement exactly once per entry.

---

## M3 — Investment & Wallet Core

### M3.1 Purpose
Process deposits, perform the $30 Global Pool carve-out, create plan records, and maintain a fully auditable wallet ledger including user-to-user transfers.

### M3.2 Business Rules — Deposit & Split
- Minimum investment is **$80**.
- **Every deposit creates at least one Global Pool entry.** $30 per entry is carved out before the Working Investment is computed.
- **Multiple pool entries on one deposit:** a large deposit can open several $30 pool entries. Example: a $1,000 deposit may open multiple pool accounts at $30 each, per the configured rule.
- If the same user deposits 10 times, **10 (or more) independent Global Pool entries** are created — each carries its own $30 and its own matrix position.
- Working Investment drives Stacking/Holding ROI; the pool $30 is never part of the ROI base.

### M3.3 Worked Example — Single Pool Entry

| Step | Value |
|---|---|
| Deposit | $1,000 |
| Pool entries created | 1 |
| Global Pool carve-out | 1 × $30 = $30 |
| Working Investment | $970 |
| ROI base (Stacking/Holding) | $970 |

### M3.4 Worked Example — Multiple Pool Entries

A $1,000 deposit electing **3 pool entries**:

| Step | Value |
|---|---|
| Deposit | $1,000 |
| Pool entries created | 3 |
| Global Pool carve-out | 3 × $30 = $90 |
| Working Investment | $910 |
| Matrix positions seeded | 3 independent positions |

> **Confirm with client:** whether the number of pool entries per deposit is user-selectable, auto-derived from deposit size, or fixed at one. The build supports all three; the admin panel exposes the rule (M11).

### M3.5 Wallet Structure

A single wallet per account holds all income types in a unified balance, but every credit is tagged by source for reporting and cap calculation.

| Table | Key Fields | Notes |
|---|---|---|
| `wallets` | id, user_id, balance, capped_earned, created_at | `capped_earned` tracks cap progress (Stacking+Holding+Level+Rank only). |
| `wallet_ledger` | id, user_id, type, source, amount, direction, ref_id, balance_after, created_at | `source ∈ {stacking, holding, level, rank, referral, royalty, matrix, rebirth, transfer_in, transfer_out, withdrawal, fee}` |
| `deposits` | id, user_id, amount, pool_entries, pool_amount, working_amount, plan_type, tx_hash, status, created_at | `status ∈ {pending, approved, rejected}` |
| `transfers` | id, from_user, to_user, gross, fee, net, created_at | 5% fee on transfers. |

### M3.6 User-to-User Transfer
```
Sender requests transfer of $X to a username
  ↓
Validate balance >= $X and recipient exists
  ↓
fee = X × 5% ; net = X − fee
  ↓
Debit sender $X ; credit recipient net ; record fee
```

### M3.7 Edge Cases
- Deposit below $80 → reject.
- Deposit not yet admin-approved → ROI does not accrue; **but royalty volume counts from all deposits** (see M6.3.2).
- Transfer to self / unknown user → reject.
- Insufficient balance for transfer/withdrawal → reject atomically (DB transaction).
- Every wallet mutation must be inside a DB transaction and write a ledger row — no silent balance edits.

### M3.8 Acceptance Criteria
1. `$30 × pool_entries` is carved before Working Investment on every deposit.
2. 10 deposits create 10+ independent pool entries.
3. Transfers apply exactly 5% fee and balance the ledger.
4. Wallet balance always equals the sum of its ledger rows.

---

## M4 — Stacking Engine

### M4.1 Purpose
Fixed-term investment plans. The user locks the Working Investment for a chosen term and earns a fixed percentage, accrued daily and withdrawable at maturity.

### M4.2 Term & Rate Table

| Lock Period | Return | Coin Share of Monthly Global Business |
|---|---|---|
| 30 days | 8% | 1% |
| 60 days | 10% | 1% |
| 90 days | 12% | 2% |
| 180 days | 15% | 3% |
| 365 days | 20% | 5% |

### M4.3 Business Rules
- **Profit only at maturity.** Stacking returns the profit; the principal (Working Investment) is not returned as a separate payout.
- **Daily accrual, maturity withdrawal.** The fixed return accrues to the dashboard daily across the term, but a withdrawal request for Stacking income can be made **only after** the lock period completes.
- Multiple active Stacking plans are allowed; each deposit creates a separate plan with its own term and maturity date.
- Stacking income counts toward the 3X/4X cap.
- The 30-Level team income is paid daily on the Stacking daily accrual (see M7).

### M4.4 Worked Example

| Step | Value |
|---|---|
| Deposit | $1,000 |
| Global Pool | $30 |
| Working Amount | $970 |
| 90-day plan rate | 12% |
| Total profit | $970 × 12% = $116.40 |
| Daily accrual | $116.40 ÷ 90 = $1.293 / day |
| Withdrawable | After day 90 (maturity) |

> **Profit-only clarification:** the earlier draft showed maturity = working + profit ($1,086.40). **That is superseded.** Stacking pays profit only ($116.40 in this example). The principal remains as the user's working balance per platform policy and is not re-paid as part of Stacking maturity.

### M4.5 Data Model

| Table | Key Fields |
|---|---|
| `stacking_plans` | id, user_id, deposit_id, working_amount, term_days, rate, total_profit, daily_accrual, accrued_to_date, start_date, maturity_date, status |
| `stacking_accruals` | id, plan_id, date, amount, capped (bool) |

### M4.6 Edge Cases
- Cap reached mid-term → stop crediting Stacking accrual once cap hit (see M9); remaining accrual is not paid.
- Early withdrawal request before maturity → reject (income locked until maturity).
- Multiple plans maturing same day → each unlocks independently.

### M4.7 Acceptance Criteria
1. `profit = working × rate`; accrues daily; withdrawable only at maturity.
2. Principal is not double-paid at maturity.
3. Stacking accrual halts exactly when the cap is reached.

---

## M5 — Holding Engine

### M5.1 Purpose
Open-ended daily ROI based on the deposit tier of the Working Investment. No lock period.

### M5.2 Tier Table

| Tier | Deposit Band | Daily ROI | Extra |
|---|---|---|---|
| Bronze | $80 – $1,000 | 0.20% | — |
| Silver | $1,080 – $5,000 | 0.30% | — |
| Gold | $5,080 – $10,000 | 0.40% | — |
| VIP | $10,000 + | 0.50% | Foreign Trip |

### M5.3 Business Rules
- Daily ROI is calculated on the Working Investment of the deposit and credited daily.
- Tier is determined by the deposit band; no lock period applies.
- VIP additionally qualifies for the Foreign Trip reward.
- Holding income counts toward the 3X/4X cap.
- 30-Level team income is paid daily on the Holding ROI (see M7).

### M5.4 Worked Example

| Step | Value |
|---|---|
| Deposit | $5,000 |
| Global Pool | $30 |
| Working Amount | $4,970 |
| Tier | Silver (0.30%) |
| Daily ROI | $4,970 × 0.30% = $14.91 / day |

### M5.5 Data Model

| Table | Key Fields |
|---|---|
| `holding_plans` | id, user_id, deposit_id, working_amount, tier, daily_rate, total_earned, status, created_at |
| `holding_accruals` | id, plan_id, date, amount, capped (bool) |

### M5.6 Edge Cases
- Deposit exactly on a band boundary → bands inclusive as listed ($1,000 = Bronze, $1,080 = Silver).
- Gap between bands ($1,001–$1,079) → confirm rounding/assignment with client; default: nearest lower band.
- Cap reached → daily ROI stops crediting.

### M5.7 Acceptance Criteria
1. Correct tier and daily ROI credited each day on working amount.
2. Holding ROI halts at cap.
3. VIP flag sets Foreign Trip eligibility.

---

## M6 — Global Auto Pool

### M6.1 Purpose
A company-wide matrix reward system funded by the $30 carved from every pool entry. It pays three income types — **Referral (15-level)**, **Royalty (monthly)**, and **Matrix + Rebirth** — none of which count toward the 3X/4X cap.

### M6.2 The $30 Split

| Stream | % of $30 | Amount | Purpose |
|---|---|---|---|
| Referral Income | 30% | $9.00 | 15-level referral payout |
| Royalty Income | 5% | $1.50 | Royalty Pool 1 (3%) + Pool 2 (2%) |
| Matrix Pool Distribution | 23% | $6.90 | 1/3/9/27 matrix + cascade |
| **Total distributed** | **58%** | **$17.40** | |
| Company main wallet | 42% | $12.60 | Retained |

### M6.3 Pool Entry & Placement
- **Qualification:** an account is placed into the Global Auto Pool after completing **3 direct referrals**.
- **Placement:** separate from the sponsor tree. Positions are filled **sequentially in a FIFO queue** — the next qualifier takes the next open global slot company-wide.
- **Per-entry:** each $30 entry is an independent matrix position; one user can hold many positions (one per deposit/entry).

```
Account completes 3 directs
  ↓
System auto-places account into Global Pool (FIFO)
  ↓
$30 entry begins filling the 1/3/9/27 matrix
```

#### M6.3.1 Referral Income — 15 Levels (30% / $9)

The $9 referral portion pays across 15 levels; the network triples each level. Each level pays a set percentage of that level's business volume.

| Lvl | IDs | Level Business | % | Income |
|---|---|---|---|---|
| 1 | 3 | $90 | 10% | $9.00 |
| 2 | 9 | $270 | 5% | $13.50 |
| 3 | 27 | $810 | 3% | $24.30 |
| 4 | 81 | $2,430 | 3% | $72.90 |
| 5 | 243 | $7,290 | 2% | $145.80 |
| 6 | 729 | $21,870 | 1% | $218.70 |
| 7 | 2,187 | $65,610 | 0.75% | $492.08 |
| 8 | 6,561 | $196,830 | 0.75% | $1,476.23 |
| 9 | 19,683 | $590,490 | 0.50% | $2,952.45 |
| 10 | 59,049 | $1,771,470 | 0.50% | $8,857.35 |
| 11 | 177,147 | $5,314,410 | 0.50% | $26,572.05 |
| 12 | 531,441 | $15,943,230 | 0.50% | $79,716.15 |
| 13 | 1,594,323 | $47,829,690 | 0.75% | $358,722.68 |
| 14 | 4,782,969 | $143,489,070 | 0.75% | $1,076,168.03 |
| 15 | 14,348,907 | $430,367,210 | 1% | $4,303,672.10 |

> **Note:** this 15-level Referral table is part of the Global Pool and is **distinct from the 30-Level Team Income (M7)**, which pays on daily ROI. Separate income streams, separate tables.

#### M6.3.2 Royalty Income — Monthly (5% / $1.50)

A monthly salary funded from the entire company's monthly $30 pool volume. Qualification resets each calendar month.

| Pool | Unlock (in one month) | Company Share | Worked Example |
|---|---|---|---|
| Royalty Pool 1 | 10 direct sponsors | 3% of monthly pool volume | $300,000 × 3% = $9,000 ÷ 50 = $180 each |
| Royalty Pool 2 | 21 direct sponsors | 2% of monthly pool volume | $300,000 × 2% = $6,000 ÷ 50 = $120 each |

- **Monthly qualification only.** The direct count must be hit within a single calendar month (1st–30th). A split such as 7 + 3 across two months does **not** qualify.
- **Funded from all deposits.** Royalty volume is calculated from **all deposits** in the month, not only admin-approved ones.
- Each pool's fund is divided equally among that month's qualifiers and paid the following month.

#### M6.3.3 Matrix Pool — 1/3/9/27 (23% / $6.90)

Each user heads their own pool tree. Completing all three pools (3 + 9 + 27 = 39 under you, 40 total) completes one cycle.

| Pool | Members | Distribution % | Pool Income |
|---|---|---|---|
| Pool 1 | 3 | 3% | $2.70 |
| Pool 2 | 9 | 3% | $8.10 |
| Pool 3 | 27 | 4% | $32.40 |
| **Cycle total** | **40** | 10% direct + 13% cascade = **23%** | — |

**Cascading shares:** a user's Pool-2 members are first-level for their Pool-1 position, and so on. The direct 3+3+4 = 10% plus the deeper cascade brings total tree distribution to **23%**; any remainder is retained by the company.

#### M6.3.4 First Cycle Economics ($30 entry)

| Step | Amount |
|---|---|
| Tree volume (40 × $30) | $1,200 |
| Distributed (58%: referral + royalty + matrix) | − $696 |
| Remaining | $504 |
| User receives 50% | $252 |
| Remaining 50% | $252 |
| → Company deduct | $152 |
| → Funds 1st rebirth ID | $100 |

> **Key rule — first cycle 58%, every rebirth 23%:** the original $30 entry pays the full income set once (58% total). Every rebirth ID thereafter pays **only the 23% matrix distribution** — referral and royalty are never charged again on a rebirth.

#### M6.3.5 Rebirth Ladder (endless)

Each rebirth ID runs the same 40-person tree at a higher entry value, deducts 23%, pays the user 50%, funds the next rebirth, and the company keeps the remainder.

| Rebirth ID | Tree (×40) | 23% Distrib. | Remaining | User 50% | Next Rebirth | Company |
|---|---|---|---|---|---|---|
| $100 | $4,000 | $920 | $3,080 | $1,540 | $500 | $1,040 |
| $500 | $20,000 | $4,600 | $15,400 | $7,700 | $3,000 | $4,700 |
| $3,000 | $120,000 | $27,600 | $92,400 | $46,200 | $10,000 | $36,200 |
| $10,000 | $400,000 | $92,000 | $308,000 | $154,000 | $40,000 | $114,000 |

The ladder continues indefinitely. The admin panel lets the operator add deeper rebirth levels and set each rebirth amount; the company always retains the leftover.

### M6.4 Data Model

| Table | Key Fields |
|---|---|
| `pool_entries` | id, user_id, deposit_id, entry_amount, current_pool_level, position_seq, cycle_status, created_at |
| `pool_positions` | id, pool_entry_id, pool_level, parent_position_id, slot_index, filled_at |
| `pool_referral_ledger` | id, pool_entry_id, beneficiary_user_id, level, pct, amount, created_at |
| `royalty_qualifiers` | id, user_id, month, direct_count, pool1_qualified, pool2_qualified |
| `royalty_payouts` | id, month, pool_no, fund_total, qualifier_count, per_member, paid_at |
| `rebirth_ledger` | id, parent_entry_id, rebirth_level, entry_amount, user_share, company_share, next_amount, created_at |

### M6.5 Edge Cases
- User holds many pool entries → each is independent; placement and rebirth tracked per entry.
- Royalty month with zero qualifiers → fund rolls to company (or carries forward — confirm).
- Matrix slot filled by global spillover vs own referral → same payout logic either way.
- Rebirth beyond configured levels → stop until admin adds a level.

### M6.6 Acceptance Criteria
1. $30 splits exactly 30/5/23/42; 58% distributed.
2. 3 directs auto-place the account into the FIFO pool once per entry.
3. First cycle deducts 58%; every rebirth deducts 23%; 50/50 split holds.
4. Royalty pays only monthly-qualified members, equally split, from all deposits.
5. No Global Pool income is counted toward the 3X/4X cap.

---

## M7 — 30-Level Team Income

### M7.1 Purpose
Pay a percentage of downline daily ROI across 30 levels, gated by the sponsor's number of directs. Paid daily on both Stacking and Holding ROI.

### M7.2 Level Table

| Level | Income (of ROI) | Directs Required |
|---|---|---|
| L1 | 25% | 1 |
| L2 | 15% | 2 |
| L3 | 10% | 3 |
| L4 | 5% | 4 |
| L5 – L9 | 3% | 5 |
| L10 | 2% | 6 |
| L11 – L15 | 1% | 7 |
| L16 – L20 | 0.5% | 8 |
| L21 – L30 | 0.25% | 9 |

### M7.3 Business Rules
- **Base = daily ROI.** Level income is computed on each downline member's daily ROI (Stacking daily accrual + Holding daily ROI).
- A level only pays if the upline meets the directs-required threshold for that level band.
- Paid daily, same cycle as the ROI it is based on.
- Counts toward the 3X/4X cap.

### M7.4 Worked Example
A downline member earns $14.91 Holding ROI today. The L1 upline (with ≥ 1 direct) earns 25% = $3.73 from that member; an L3 upline (with ≥ 3 directs) earns 10% = $1.49, and so on, subject to each upline's direct count.

### M7.5 Data Model

| Table | Key Fields |
|---|---|
| `level_income_ledger` | id, beneficiary_user_id, source_user_id, level, roi_base, pct, amount, date, capped |

### M7.6 Edge Cases
- Upline lacks required directs for a level → that level is skipped (income forfeited, not rolled up unless client specifies compression).
- Source member hits cap → their ROI may stop; downstream level income stops accordingly.
- Beneficiary hits own cap → their level income stops crediting.

### M7.7 Acceptance Criteria
1. Level income is computed daily on combined ROI with correct directs-gating.
2. Level income contributes to cap and stops at cap.

---

## M8 — Rank & Reward (60:40)

### M8.1 Purpose
Award ranks based on qualified team business using the 60:40 rule, granting cash rewards, foreign trips, cars, and a monthly share of global business.

### M8.2 The 60:40 Rule

Ranks use team leg business (not binary, not personal):

1. Compute total business of every direct leg, including all descendants recursively.
2. The highest-business leg is the **Strong Leg**.
3. All remaining legs combined form the **Weak Leg**.
4. `Qualified Business = (Strong Leg × 60%) + (Weak Leg × 40%)`.

> **Worked example:** Strong Leg = $5,600 ; Weak Leg = $11,100 → Qualified Business = (5,600 × 60%) + (11,100 × 40%) = 3,360 + 4,440 = **$7,800**.

### M8.3 Rank Structure

| Rank | Business (60:40) | Condition | Reward |
|---|---|---|---|
| Star | $5,000 | — | $150 |
| 2 Star | $10,000 | — | $400 + Trip + 1% Global Share |
| 3 Star | $20,000 | — | $950 + Trip + 0.50% Global Share |
| 4 Star | $50,000 | — | $2,500 + Trip + 0.50% Global Share |
| 5 Star | $100,000 | 3× 4 Star | $16,000 + Trip + 0.25% Global Share |
| 7 Star | $300,000 | 3× 5 Star | $50,000 + Trip + 0.25% Global Share |
| Diamond | $500,000 | 3× 7 Star | $125,000 + Trip + Car + 0.50% Global Share |
| Double Diamond | $1,500,000 | 3× Diamond | $250,000 + Trip + Car + 0.50% Global Share |
| Triple Diamond | $2,500,000 | 3× Double Diamond | $500,000 + Trip + Car + 1% Global Share |

### M8.4 Business Rules
- **Rank achievement is permanent** — once achieved it is not recalculated downward monthly.
- **Global Business Share is paid monthly** at the rank's percentage.
- Higher ranks (5 Star+) require a count of lower-rank legs as a condition in addition to business volume.
- Rank rewards and global share count toward the 3X/4X cap.

### M8.5 Data Model

| Table | Key Fields |
|---|---|
| `ranks_catalog` | id, name, business_required, condition_rule, cash_reward, trip, car, global_share_pct |
| `user_ranks` | id, user_id, rank_id, achieved_at (permanent) |
| `global_share_payouts` | id, user_id, rank_id, month, amount, paid_at |
| `business_snapshots` | id, user_id, month, strong_leg, weak_leg, qualified_business |

### M8.6 Edge Cases
- Business drops after rank achieved → rank stays (permanent).
- Multiple ranks crossed in one period → grant highest achieved; record each milestone.
- Global share when company business is zero in a month → zero payout that month.

### M8.7 Acceptance Criteria
1. Qualified business uses 60:40 across recursive leg totals.
2. Ranks are permanent; global share pays monthly at the right %.
3. Rank rewards contribute to cap.

---

## M9 — Capping Engine

### M9.1 Purpose
Enforce the per-account earning cap. Investors are capped at 3X of working investment; Leaders at 4X. The cap applies only to a defined subset of income.

### M9.2 Business Rules
- **Cap base = total working investment** of the account (sum across deposits).
- **Investor = 3X. Leader = 4X** (after sponsoring 2 direct investors; permanent).
- **Counts toward cap:** Stacking income, Holding ROI, 30-Level income, Rank rewards, Global business share.
- **Excluded from cap:** All Global Auto Pool income — Referral, Royalty, Matrix, Rebirth — which continues paying even after the cap is reached.
- When capped income reaches the limit, those income types stop crediting; pool income continues.

### M9.3 Worked Example

| Scenario | Investor (3X) | Leader (4X) |
|---|---|---|
| Working investment | $1,000 | $1,000 |
| Cap on capped-income | $3,000 | $4,000 |
| Stacking + Holding + Level + Rank | Stops at $3,000 | Stops at $4,000 |
| Referral / Royalty / Matrix / Rebirth | Continues | Continues |

### M9.4 Data Model

| Table | Key Fields |
|---|---|
| `users` | cap_multiplier (3 or 4), capped_income_total, cap_limit, cap_reached_at |
| `cap_ledger` | id, user_id, source, amount, running_total, date — appends every capped credit |

### M9.5 Edge Cases
- Account becomes Leader after partially capping → limit raises from 3X to 4X; capped income resumes up to the new limit.
- New deposit increases working investment → cap base and limit increase accordingly.
- A single credit would exceed the cap → credit only up to the cap; discard the remainder of that capped credit.

### M9.6 Acceptance Criteria
1. Capped income halts exactly at 3X (investor) / 4X (leader).
2. Pool income is never blocked by the cap.
3. Leader upgrade raises the cap and resumes capped income.

---

## M10 — Withdrawal Engine

### M10.1 Purpose
Process withdrawal requests of ROI and commission, apply the 5% fee, and pay out manually on a weekly cycle with the blockchain transaction hash recorded.

### M10.2 Business Rules
- Minimum withdrawal: **$10**.
- Fee: **5% on every withdrawal** (`net = gross × 0.95`).
- **No weekly withdrawal limit.**
- ROI and commission are both withdrawable.
- **Stacking income is withdrawable only after** the relevant plan's lock period completes.
- Processing is weekly; admin pays manually and records the tx-hash.

### M10.3 Flow
```
User requests withdrawal (>= $10)
  ↓
System checks balance + Stacking maturity rules
  ↓
fee = gross × 5% ; net = gross − fee
  ↓
Admin review (weekly cycle)
  ↓
Manual blockchain payment
  ↓
Store tx-hash ; mark completed
```

### M10.4 Data Model

| Table | Key Fields |
|---|---|
| `withdrawals` | id, user_id, gross, fee, net, status, requested_at, processed_at, tx_hash, cycle_week |

### M10.5 Edge Cases
- Request below $10 → reject.
- Request includes Stacking income before maturity → reject or pay only matured portion.
- Insufficient balance at processing time → hold/return to pending.
- Duplicate/double-submit → idempotency guard on request.

### M10.6 Acceptance Criteria
1. 5% fee applied; net computed correctly; $10 minimum enforced.
2. Stacking income blocked until maturity; ROI/commission withdrawable.
3. Weekly processing records tx-hash on completion.

---

## M11 — Admin Panel

### M11.1 Purpose
Operate the platform: approvals, configuration of all percentages and rules, reporting, and full audit.

### M11.2 Capabilities

| Area | Functions |
|---|---|
| User management | View/search users, accounts per email, status, leader flag. |
| Deposits | Review, approve/reject, view tx-hash, see pool entries & working amount. |
| Withdrawals | Weekly queue, approve, record tx-hash, mark completed. |
| Plan config | Stacking terms/rates, Holding tiers/rates. |
| Pool config | $30 split %, pool distribution %, rebirth ladder amounts, add rebirth levels, pool entries-per-deposit rule. |
| Income config | 15-level referral %, 30-level %, royalty thresholds & %. |
| Rank config | Rank catalog, business thresholds, conditions, rewards, global share %. |
| Cap config | Investor 3X / Leader 4X multipliers, leader threshold (2 directs). |
| Reports | Income, team/business, rank, pool, royalty, wallet ledgers, exports. |
| Audit | Immutable log of admin actions and config changes. |

### M11.3 Acceptance Criteria
1. All percentages and rules are editable without code changes.
2. Every approval and config change is audit-logged.
3. Reports reconcile with wallet ledgers.

---

## M12 — Scheduled Jobs (Cron)

### M12.1 Purpose
All time-driven calculations run as Yii2 console commands on a scheduler. Each job is **idempotent** (safe to re-run for a given period).

### M12.2 Job Schedule

| Job | Frequency | Action |
|---|---|---|
| `daily_holding_roi` | Daily | Credit Holding ROI on working amount; apply cap. |
| `daily_stacking_accrual` | Daily | Accrue Stacking profit; lock until maturity; apply cap. |
| `daily_level_income` | Daily | Compute 30-level income on combined ROI; apply cap. |
| `stacking_maturity` | Daily | Unlock matured Stacking plans for withdrawal. |
| `pool_matrix_fill` | Continuous/daily | Place qualifiers (FIFO), fill matrix, trigger rebirth. |
| `monthly_royalty` | Monthly | Compute Pool 1/2 qualifiers and pay per-member shares. |
| `monthly_global_share` | Monthly | Pay rank-based global business share. |
| `monthly_rank_eval` | Monthly | Recompute 60:40 qualified business; grant new ranks (permanent). |
| `weekly_withdrawals` | Weekly | Assemble withdrawal queue for admin processing. |

### M12.3 Reliability Rules
- Each job records a run-log with period key; re-running the same period must not double-credit.
- All credits go through the wallet ledger inside DB transactions.
- Cap checks happen at credit time within each job.

---

## 13. Changes From the Earlier Draft

This specification resolves the following points that were ambiguous or contradictory in the original ADbotix Business Requirement draft.

| Topic | Earlier Draft | This Spec (Final) |
|---|---|---|
| Stacking maturity | Working + profit returned | Profit only |
| Stacking withdrawal | Unspecified | Daily accrual; withdraw at maturity |
| Referral table | Merged with 30-level | Separate: 15-level pool referral + 30-level ROI income |
| Pool distribution % | "to be confirmed" | Pool1 3% / Pool2 3% / Pool3 4%; 23% total |
| Cap tiers | Single 3X | Investor 3X / Leader 4X (2 directs, permanent) |
| Cap scope | "all incomes 200% / 3X" | Only Stacking, Holding, Level, Rank; pool excluded |
| Pool entries per deposit | One implied | One or many ($30 each) |
| Transfers | Not specified | Allowed, 5% fee |
| Withdrawal fee / min | Not specified | 5% fee, $10 minimum, no weekly limit |
| Royalty basis | Unspecified | All deposits, monthly qualification only |

---

## 14. Open Items & Sign-Off

### 14.1 Items to Confirm
1. Pool entries per deposit: user-selectable, auto-derived, or fixed at one.
2. Coin-share token mechanics for Stacking (how the 1–5% coin share is issued).
3. Holding band gap handling for amounts between listed bands.
4. Royalty fund treatment in a month with zero qualifiers.
5. Whether 30-level income uses compression when an upline misses the directs requirement.

### 14.2 Confirmed & Locked
All income percentages, the $30 split, matrix and rebirth math, cap tiers and scope, fees, and withdrawal rules as specified above.

### 14.3 Sign-Off
On client confirmation of the open items, this document becomes the build baseline. Development proceeds module by module (M1–M12) with the acceptance criteria in each section used for QA sign-off.

| Role | Name | Signature | Date |
|---|---|---|---|
| Client | | | |
| Onexcell (Lead) | | | |