Redemption

How investors exit positions. Payout is locked at NAV-at-request time. Yield is claimed separately (not included in redemption payout). Single-stage: Admin approve → reserve check → payout. For how NAV changes are calculated and applied, see Writedown & NAV. 🟡 BD3 🟡 BD2 🟡 BD6

Payout Formula (Yield claimed separately)

Token value       tokens_minted × nav_at_request
Early penalty     calculated per penalty_type (if applicable)
──────────────────────────────────────────────
Total redemption  token_value - penalty

Yield is claimed separately via claimYield() — not included in redemption.

3-State Redemption Model (R16)

⚠️ Deposit → Lockup End → Maturity → ∞

lockup_end = invested_at + pool.lockup_daysmaturity_date = invested_at + pool.maturity_days

State	Condition	Behavior
🔒 LOCKED	now < lockup_end	Button disabled. Cannot redeem. Exception: penalty_type = 'NO_EARLY' → redeem allowed, no penalty.
⚠️ EARLY REDEMPTION	lockup_end ≤ now < maturity	Can redeem with penalty.
✅ FREE	now ≥ maturity	No penalty. Standard confirm.

Edge: If lockup_days = 0, skip Locked. If maturity_days = null, Free after lockup (no early window).

4 Penalty Types

Type	Formula	Description
NO_EARLY	—	No penalty. Investor can redeem at any time.
FLAT_FEE	penalty = penalty_fee_amount (fixed $)	Fixed dollar amount → pool reserve.
PRINCIPAL_BASED	penalty = nominal_amount × penalty_rate	% of principal → pool reserve.
YIELD_BASED	penalty = accrued_yield × penalty_rate	% of accrued yield forfeited → pool reserve. (e.g., 0.50 = 50%)

YIELD_BASED edge case (yield already claimed): from_unclaimed = min(unclaimed_yield, penalty), from_principal = penalty - from_unclaimed. If fully claimed → penalty from principal.

All penalties → pool reserve. Admin cannot waive.

Investor-Facing Status Labels

Internal Status	Investor Sees
PROCESSING	Processing
COMPLETED	Completed

Redemption by NAV Scenario

Category A: Standard Entry (invested at $1.00)

✅ A1 — Normal Redemption

NAV at investment: $1.00 · NAV at redemption: $1.00

Deposit           $10,000 at NAV $1.00 → 10,000 tokens
Token Value       10,000 × $1.00 = $10,000.00
Penalty           None (FREE state)
──────────────────────────────────────────────
Redemption Payout $10,000.00

Full principal returned. Yield is claimed separately via claimYield().

⚠️ A2 — Redemption During Writedown

NAV at investment: $1.00 · NAV at redemption: $0.85

Deposit           $10,000 at NAV $1.00 → 10,000 tokens
Token Value       10,000 × $0.85 = $8,500.00
Penalty           None (FREE state)
──────────────────────────────────────────────
Redemption Payout $8,500.00

Investor absorbs 15% NAV loss on token value. Yield is claimed separately via claimYield() — still accrues on nominal $10,000. NAV is locked at request time — if NAV drops further after request, investor keeps $0.85.

Category B: Discounted Entry (invested below $1.00 — "Fair Entry") — 3 scenarios

📈 B1 — Invested Low, NAV Recovered

NAV at investment: $0.80 · NAV at redemption: $0.95

Deposit           $10,000 at NAV $0.80 → 12,500 tokens
Token Value       12,500 × $0.95 = $11,875.00
Penalty           None (FREE state)
──────────────────────────────────────────────
Redemption Payout $11,875.00

Investor gained from NAV recovery ($0.80 → $0.95). Got 12,500 tokens instead of 10,000 — the "fair entry" principle with upside.

➡️ B2 — NAV Unchanged, Yield Only

NAV at investment: $0.85 · NAV at redemption: $0.85

Deposit           $10,000 at NAV $0.85 → 11,765 tokens
Token Value       11,765 × $0.85 = $10,000.25
Penalty           None (FREE state)
──────────────────────────────────────────────
Redemption Payout $10,000.25

No NAV movement — investor gets principal back. Yield claimed separately.

🔻 B3 — Invested Low, NAV Dropped Further

NAV at investment: $0.85 · NAV at redemption: $0.70

Deposit           $10,000 at NAV $0.85 → 11,765 tokens
Token Value       11,765 × $0.70 = $8,235.50
Penalty           None (FREE state)
──────────────────────────────────────────────
Redemption Payout $8,235.50

Discounted entry does NOT guarantee safety. NAV dropped further $0.85 → $0.70. Investor loses ~14% on token value.

📋 In all 5 scenarios

Redemption payout = token_value - penalty. Yield is claimed separately via claimYield() — not included in redemption. Yield accrues on nominal deposit amount ($10,000), never on NAV-adjusted token value. NAV is locked at the moment of redemption request and cannot be recalculated after submission.

Payout Example

Joob EWA Fund · NAV $0.92 · 10,000 tokens held
──────────────────────────────────────────────
Token Value       10,000 tokens × $0.92 = $9,200.00
Penalty           None (FREE state)
──────────────────────────────────────────────
Redemption Payout $9,200.00

Formula: redemption = (tokens × nav_at_request) - penalty
Yield ($184.93 accrued) is claimed separately via claimYield().

Redemption Flow (By Pool Type)

Roles: 🔵 Investor · 🟣 Fund Manager · 🟢 System / Smart Contract

Fund Pool

Investor requests redemption 🔵 Investor

Confirmation modal: token count, NAV price, token value, accrued yield, penalty (if applicable), total payout.

NAV snapshot locked → REQUESTED 🟢 System

nav_at_request captured. Payout = tokens × nav_at_request + yield - penalty. FIFO queue.

Fund Manager acknowledges → FM_ACCEPTED 🟣 Fund Manager

FM reviews request, confirms fund has liquidity → status = FM_ACCEPTED.

Fund sends USDC directly → PROCESSING → COMPLETED 🟣 Fund Manager

transfer_source = 'FUND'. payout_tx_hash confirmed on-chain.

AS Pool — Smart Contract Escrow

Investor requests redemption 🔵 Investor

NAV snapshot locked → status = REQUESTED.

Contract validates LP burn → auto-releases USDC 🟢 System

contract_validated_at → auto_released_at → PROCESSING → COMPLETED. transfer_source = 'PLATFORM'

AS Pool — Multi-Sig Escrow (Deprecated)

Investor requests redemption 🔵 Investor

NAV snapshot locked → status = REQUESTED.

Approval requested → co-signers sign → USDC released 🟢 System

approval_requested_at → cosigned_at → PROCESSING → COMPLETED. transfer_source = 'PLATFORM'

Fund Pool — No Escrow (Deprecated)

Investor requests redemption 🔵 Investor

NAV snapshot locked → status = REQUESTED.

Fund notified → fund sends USDC → transfer confirmed 🟢 System

fund_notified_at → fund_sent_at → transfer_confirmed_at → PROCESSING → COMPLETED. transfer_source = 'FUND'

🚨 Failure Path (all flows)

If transfer fails → status = FAILED. failure_type + error_message logged. Admin can retry. Legacy REJECTED status kept for backward compat but FAILED is preferred for new records.

Key Rules

📸 NAV Snapshot

nav_at_request is locked at request time from pools.nav_per_token. If NAV drops further after request, investor keeps the higher NAV. If NAV recovers, payout stays at the lower request-time NAV. Redemption payout = tokens × nav_at_request - penalty. Yield is claimed separately via claimYield().

📊 Yield Basis

Accrued yield calculated on nominal balance (not NAV-adjusted token value). Full yield paid to incentivize patience even in writedown pools.

🔒 Early Redemption

If redemption during lockup period → per-pool penalty applies (e.g., 50% of accrued yield forfeited). Configurable per pool.

📋 FIFO (First-In, First-Out) Processing

Oldest requests processed first. Admin checks pool liquidity before approval. Insufficient liquidity → request stays in queue (not rejected).