SRS: UC_8.2.12 — Flow 17: Pod Leader Vesting Payout

---

1. UC Index

---

UC_8.2.12 — Flow 17: Pod Leader Vesting Payout

---

2. Trigger

Event: Scheduled Job — monthly, fires on the 1st of every month.

Zapier is a scheduler only in this flow. It calls a single endpoint and waits for the JSON response. All batch logic executes inside Middleware.

(Source: Zapier Integration V7.pdf §Flow 17 line 2085)

---

3. Pre-conditions

---

4. Post-conditions

---

5. Basic Flow

Step 1. Scheduled Job Fires (Zapier)

• Monthly scheduled trigger fires at 00:00:00 UTC on the 1st of each month. UTC is the only timezone used — no local timezone dependency.
• Zapier calls POST /process-pod-vesting with input: cycle_date = Today (resolved as UTC ISO 8601 date by Middleware).

(Source: Zapier Integration V7.pdf §Flow 17 lines 2085–2086)

Step 2. Query Eligible Leaders (Middleware)

• Middleware queries Pod_Leader_Registry for all records where Pending_Carry_Balance > 0.
• Status gate:
  • Status = 'Active': eligible — proceed to payout routing.
  • Status = 'Suspended' (temporary suspension, e.g. Flow 4B Drawdown Defense): skip — carry balance is frozen (held in the database), not forfeited and not vested. Flow 17 must not dispatch any payout for this leader. Vesting resumes once the leader passes PIP and returns to Status = 'Active'. (Client confirmation 2026-10-30; cross-ref UC_8.2.9 BR_8.2.9.3 / BR_8.2.9.11)
  • Status = 'On_Leave' (approved leave, Flow 13): eligible — treated the same as Active; carry keeps accruing and vesting during leave, proceed to payout routing. (Cross-ref: UC_8.2.10 §7.1.3; QnA_STAGE6_POD_SYSTEM_FLOW10_11.md [POD-XF-18] — client sheet 2026-11-04)
  • Status = 'Terminated' (terminated via Flow 7 / Flow 15C): ineligible — unvested carry is immediately forfeited. Set Pending_Carry_Balance = $0.00 for these leaders without dispatching any payout. No Dots or Rippling call is made.
• Min_Payout_Threshold gate: Applied only to eligible (non-Terminated) leaders. If Pending_Carry_Balance < $100 (sourced from Table C: Min_Payout_Threshold), the leader is excluded from the current cycle. Their balance is not zeroed — it rolls over and accumulates until the next run where the threshold is met.

(Source: RFQ_ Stack Trading Prop Tech V7.pdf §Process Pod Vesting line 1315; Client confirmation 2026-09-20 — "Min_Payout_Threshold = $100 applies to carry balance payouts"; Client supplement 2026-10-06 — Terminated status forfeiture at cycle audit; UC_8.2.10 §7.1.3 / [POD-XF-18] — On_Leave leaders vest normally)

Step 3. Route Payout per Leader (Middleware — loop)

• For each eligible leader, evaluate billing_country, current_level, and compensation_track:
  • Path A — Dots API: billing_country != 'US' (all levels) OR billing_country == 'US' AND current_level < 6. Call POST /v2/payouts with payee_id, amount = Pending_Carry_Balance, memo = "Monthly Pod Leader Carry Vesting - [Month/Year]".
  • Path B — Rippling Off-Cycle Payroll: billing_country == 'US' AND current_level >= 6 AND compensation_track IN ('Standard', 'Flex'). Call POST /api/v1/payroll/off-cycle-payruns with employee_id, earning_type = "DISCRETIONARY_BONUS", amount = Pending_Carry_Balance.
    • Why Off-Cycle (not regular payroll): The carry bonus is a variable performance amount settled on the 1st of each month, independent of the fixed W-2 payroll schedule. Off-Cycle API pays it immediately without waiting for the next regular payroll run.
    • Why DISCRETIONARY_BONUS: Carry is classified as US Supplemental Wages under IRS rules. Rippling automatically applies the correct supplemental tax withholding rate — keeping it separate from regular wages prevents incorrect W-2 tax treatment for the employee.

(Source: Client confirmation 2026-09-22; Client supplement 2026-10-06 — §2 Rippling Off-Cycle API detail)

Step 4. Blockchain Logging (Middleware — within loop)

• After each payout API call completes:
  • Initialize Ethers.js wallet.
  • Call contract.recordMetric() with:
    • metric_category = "Pod Leader Vesting"
    • metric_value = "[Amount] USD Cleared"
    • receipt_hash = [Dots or Rippling Transaction ID]

(Source: RFQ_ Stack Trading Prop Tech V7.pdf §Immutable Ledger Logging lines 1327–1329; Client supplement 2026-10-06 — §3 Step 4)

Step 4a. QuickBooks Online Journal Entry (Middleware — within loop, Path A only) — CHR-139

• Fires only after the Dots API returns a successful transaction ID for the leader.
• Individual entries — no bundling: push one separate QuickBooks Journal Entry per Pod Leader / Founding Mentor in the loop. Never batch multiple leaders into one Journal Entry.
• Dots only: applies to payouts routed via Path A (International Contractors, and US 1099 Contractors / Founding Mentors not on W-2 payroll). For Path B (US Level 6+ W-2 via Rippling Off-Cycle Payroll API), skip the QuickBooks push — Rippling syncs W-2 payroll to QuickBooks natively.
• Account mapping (absolute payout amount on both lines):

(Source: CHR-139; QuickBooks Integration Specification §4.B "Pod Leader Carry/Commission - Flow 17 - Contractors"; Client confirmation 2026-10-30)

Step 5. Zero Out Balance (Middleware — within loop)

• Set Pod_Leader_Registry.Pending_Carry_Balance = $0.00 for the processed leader.
• Set Pod_Leader_Registry.last_vesting_payout_at = NOW().
• Prevents double payment on next cycle.

(Source: RFQ_ Stack Trading Prop Tech V7.pdf §Process Pod Vesting Cleanup line 1330; Client supplement 2026-10-06 — §3 Step 4)

Step 6. Return JSON Response (Middleware → Zapier)

• Middleware returns JSON to Zapier:

  {
    "processed_count": <int>,
    "processed_users": ["email@example.com", ...]
  }

• Zapier waits for this response before proceeding.

(Source: RFQ_ Stack Trading Prop Tech V7.pdf §Process Pod Vesting lines 1315–1316)

Step 7. Notify Ops (Zapier)

• Trigger Slack alert to #finance-ops (Head of Ops):
  • "Monthly Pod Vesting Complete: Processed [X] leaders, Total Paid: $[Y], Polygon Tx: [Hash]"

(Source: Zapier Integration V7.pdf §Flow 17 Notify (Ops) lines 2092–2094; Client supplement 2026-10-06 — §3 Step 5)

Step 8. Notify Leaders (Zapier)

• Send Pod_Leader_Vesting_Paid email to the array of emails in processed_users.
• Content: statement notification confirming carry payouts have cleared to the banking channel.

(Source: Zapier Integration V7.pdf §Flow 17 Notify (Traders) line 2095; §Email Templates line 772)

---

6. Carry Accrual Reference (How Pending_Carry_Balance is Built)

Carry is accrued by Middleware in Flow 6 (Level Transition) — triggered by a mentee's level promotion, not the Pod Leader's own level. When a Mentee (trader inside the Pod) advances to a qualifying level, the system credits the Pod Leader who directly manages that mentee as recognition for their coaching:

Carry accumulates across all promotion events from all mentees in the leader's pod. The monthly Flow 17 payout run pays out the total accumulated Pending_Carry_Balance and resets it to $0.00 after each cycle.

Example: If a Pod Leader has 3 mentees and in one month Mentee A reaches L3 (+$250) and Mentee B reaches L5 (+$500), the leader's Pending_Carry_Balance increases by $750 before the next payout cycle.

(Source: Zapier Integration V7.pdf §Pod Leader Carry Logic lines 1375–1380; Client supplement 2026-10-06 — §1 Carry Accrual mechanism)

---

7. Exceptional Flows

Exc-1 — No leaders with Pending_Carry_Balance > 0:

• Middleware returns { "processed_count": 0, "processed_users": [] }.
• Zapier sends Slack alert: "Pod Vesting Complete. Processed 0 leaders."
• No email sent (empty processed_users array).

Exc-2 — Dots or Rippling API call fails for a specific leader:

• The failed leader is skipped for the current cycle. The loop continues to the next leader — one failure does not halt the batch.
• Pending_Carry_Balance for the failed leader is NOT zeroed — it is preserved and will be included in the next cycle's run.
• An error is fired to Slack #ops-treasury: alert includes leader_id, amount, and the API error.
• All other leaders in the batch are processed normally.

(Source: Client confirmation 2026-09-20 — "Skip that leader, preserve their balance for next month, and fire the error to #ops-treasury")

Exc-3 — contract.recordMetric() blockchain call fails AFTER payout dispatched:

• DO NOT reverse the payout. Fiat movement is off-chain and already settled via Dots/Rippling. Pending_Carry_Balance stays reset at $0.00 — restoring it would risk double-payout on next cycle.
• Save local audit record to PostgreSQL with Dots/Rippling Transaction ID; set polygon_tx_hash status to PENDING_BLOCKCHAIN_SYNC or FAILED.
• Queue blockchain log payload for async retry with exponential backoff.
• Emit Slack alert to #dev_ops with Leader ID and Payout Transaction ID for Ops/DevOps visibility.

(Source: Client confirmation 2026-09-22; RFQ_ Stack Trading Prop Tech V7.pdf §Immutable Ledger Logging — "fiat currency movement remains entirely off-chain")

Exc-4 — Middleware timeout before response returned to Zapier:

• Zapier auto-retries POST /process-pod-vesting with same cycle_date = Today (Zapier Company Tier exponential retry).
• Three-layer idempotency prevents double-payout:
  • Layer 1 — DB state filter: Middleware re-queries Pending_Carry_Balance > 0. Leaders already paid in the previous run have Pending_Carry_Balance = $0.00 and are bypassed automatically.
  • Layer 2 — Payment gateway idempotency key: For each payout call, Middleware passes Idempotency-Key: VESTING_{leader_id}_{cycle_date} (e.g. VESTING_USR_98765_2026-10-01) to Dots/Rippling. If the payout already completed, Dots/Rippling return HTTP 409 — no new transaction is created.
  • Layer 3 — Blockchain anchor: contract.recordMetric() with receipt_hash = original transaction ID provides on-chain audit trail; Ops can reconcile any gap immediately.

(Source: Client confirmation 2026-09-22)

---

8. Business Rules

BR_8.2.12.1: Zapier is a Scheduler Only — No Middleware Logic Lives in Zapier

For Flow 17, Zapier's only job is to fire the scheduled trigger and call the single POST /process-pod-vesting endpoint. All batch processing — querying leaders, routing payouts, blockchain logging, zeroing balances — is executed inside Middleware. There is no Zapier loop per leader.

(Source: Zapier Integration V7.pdf §Flow 17 lines 2083–2095; RFQ_ Stack Trading Prop Tech V7.pdf §Process Pod Vesting)

BR_8.2.12.2: Carry Payout Routing — Dots vs. Rippling

Payout routing is determined by evaluating three fields on the Users table: billing_country, current_level, and compensation_track.

Path A — Dots API (one-time payout):

• billing_country != 'US' — all international leaders (all levels 1–24)
• OR billing_country == 'US' AND current_level < 6 — US junior contractors (pre-W2)
• Payload: POST /v2/payouts — payee_id, amount, memo

Path B — Rippling Off-Cycle Payroll API:

• billing_country == 'US' AND current_level >= 6 AND compensation_track IN ('Standard', 'Flex')
• compensation_track is set during the Level 6 transition (Flow 6)
• Payload: POST /api/v1/payroll/off-cycle-payruns — employee_id, earning_type = "DISCRETIONARY_BONUS", amount
• Rationale for Off-Cycle (not regular payroll): Carry is a variable performance bonus settled on the 1st of each month, independent of the fixed W-2 payroll schedule. Off-Cycle API settles it immediately without waiting for the next regular payroll run.
• Rationale for DISCRETIONARY_BONUS earning type: Carry qualifies as US Supplemental Wages under IRS rules. Routing through Off-Cycle API with this earning type causes Rippling to automatically apply the correct supplemental tax withholding rate — keeping it separate from regular wages avoids incorrect W-2 tax treatment for the employee.

Minimum payout threshold: If Pending_Carry_Balance < $100 (Min_Payout_Threshold in Table C), the cycle is skipped for that leader and the balance rolls over to the following month to avoid transaction fee leakage.

Founding Mentors (Role_Flag = 'Founding_Mentor'): Follow the exact same routing rules as regular Pod Leaders (US vs. international, level-based). Their Pending_Carry_Balance continues vesting normally even if their personal trading account triggers a drawdown breach — carry vesting is not blocked by drawdown defense.

(Source: Client confirmation 2026-09-22; Client supplement 2026-10-06 — §2 Rippling Off-Cycle API rationale)

BR_8.2.12.3: Blockchain Receipt Hash = Payout Transaction ID

Every payout processed in a vesting cycle must be recorded on the Polygon PoS blockchain via contract.recordMetric(). The receipt_hash field must be set to the Dots or Rippling transaction ID from the payout API response. This is the immutable proof of payment.

(Source: RFQ_ Stack Trading Prop Tech V7.pdf §Immutable Ledger Logging lines 1327–1329)

BR_8.2.12.4: Zero-Out is Mandatory After Each Payout

Pending_Carry_Balance must be set to $0.00 for each leader immediately after their payout is confirmed. This prevents double-payment on the next monthly cycle. The zero-out must occur within the same Middleware processing loop as the payout call.

(Source: RFQ_ Stack Trading Prop Tech V7.pdf §Process Pod Vesting Cleanup line 1330)

BR_8.2.12.5: Carry Amounts are Fixed at Accrual, Not Payout

Carry amounts are accrued at the time of a mentee's level promotion (Flow 6): L3 = $250, L5 = $500, L7 = $1,500. The monthly vesting payout does not recalculate these amounts — it simply pays out whatever accumulated Pending_Carry_Balance exists at payout time. There is no retroactive adjustment.

(Source: Zapier Integration V7.pdf §Pod Leader Carry Logic lines 1375–1380)

BR_8.2.12.6: Ops Notification is Mandatory

A Slack alert to the Head of Ops must be triggered after every vesting run (whether or not leaders were processed). The alert must include the processed_count from the Middleware response. This is the Ops oversight mechanism for the monthly payout cycle.

(Source: Zapier Integration V7.pdf §Flow 17 Notify (Ops) lines 2092–2094)

BR_8.2.12.7: Min_Payout_Threshold Sourced from Table C — Not Hardcoded

The minimum carry balance required to qualify for a payout cycle is Min_Payout_Threshold, read from Table C: Global_Variables. Current value = $100. If a leader's Pending_Carry_Balance < $100 on the 1st of the month, they are skipped — balance is not zeroed, it rolls over to the next cycle. This value must never be hardcoded in Middleware; always read from Table C.

(Source: Client confirmation 2026-09-20 — "Min_Payout_Threshold = $100 applies to carry balance payouts"; Zapier Integration V7.pdf §Table C)

BR_8.2.12.8: Payout Failure — Loop Isolation, Balance Preserved, Alert to #ops-treasury

If a Dots or Rippling payout call fails for a specific leader:

1. The failed leader is skipped; the batch loop continues to the next leader.
2. The failed leader's Pending_Carry_Balance is NOT zeroed — it accumulates and is retried in the next monthly cycle.
3. A Slack error alert fires to #ops-treasury (not #ops-it) with leader_id, amount, and API error details.
4. The remaining leaders in the batch are not affected.

(Source: Client confirmation 2026-09-20 — "Skip that leader, preserve their balance for next month, and fire the error to #ops-treasury")

BR_8.2.12.9: Terminated Leaders — Carry Forfeited at Cycle Audit, No Payout Dispatched

When the Step 2 eligibility audit encounters a leader with Status = 'Terminated' and Pending_Carry_Balance > 0, the unvested carry is immediately forfeited: Pending_Carry_Balance is set to $0.00 without dispatching any Dots or Rippling call. This mirrors the immediate carry zeroing performed by the BPS termination endpoint (Flow 15C / UC_8.2.11 M-3), and catches any residual balance that may have accrued between the termination event and the next payout cycle.

(Source: Client supplement 2026-10-06 — §3 Step 2 Eligibility Audit)

BR_8.2.12.10: QuickBooks Journal Entry — One per Dots Payout, Skip Rippling W-2 (CHR-139)

POST /process-pod-vesting must follow three rules for QuickBooks Online:

1. Individual entries (no bundling): one separate Journal Entry per Pod Leader / Founding Mentor, pushed once the Dots API returns a successful transaction ID. Multiple leaders are never batched into one Journal Entry.
2. Dots only (skip Rippling W-2): Journal Entries are pushed only for payouts routed via the Dots API (Path A). Payouts via Rippling Off-Cycle Payroll API (Path B — US Level 6+ W-2) are skipped, because Rippling syncs W-2 payroll to QuickBooks natively.
3. Account mapping: Debit 5016 POD Leader Bonus Contractor / Credit 1102 DOTS, both for the absolute payout amount.

(Source: CHR-139; QuickBooks Integration Specification §4.B "Pod Leader Carry/Commission - Flow 17 - Contractors"; Client confirmation 2026-10-30)

---

9. Data Model

Table E: Pod_Leader_Registry (relevant fields)

(Source: Zapier Integration V7.pdf §Table E lines 777–790)

---

10. API Reference

(Source: RFQ_ Stack Trading Prop Tech V7.pdf §Process Pod Vesting lines 1315–1316)

---

11. Email Templates

(Source: Zapier Integration V7.pdf §Email Templates line 772; §Flow 17 Notify (Traders) line 2095)

---

12. Acceptance Criteria

---

13. Changelog