Writedown & NAV

How NAV reflects real-world asset value changes. Covers writedown mechanics, oracle update flow, timelock enforcement, and portfolio display guidelines. For redemption payout calculations, see Redemption. 🟡 BD3 🟠 PD5

Dual Loss Protection

🔒 Layer 0: Collateral

collateral_type: FULLY_COLLATERALIZED (backed 1:1 by real assets), PARTIALLY_COLLATERALIZED (with collateral_ratio%), or UNSECURED (no collateral). First line of defense — collateral absorbs loss before reserve is touched. See Risk Transparency in Core Concepts.

🛡 Layer 1: Reserve Fund

reserve_percentage (default 10%) of each pool's deposits. Held in Pool Smart Contract (non-custodial). Covers first-loss events before touching investor principal. Configurable per pool.

📈 Layer 2: NAV Token Price

NAV per token — floats between $0.00 and $1.00 (no floor; PD6 removed). Capped at $1.00 max. New investors always buy at the current fair price.

When losses exceed reserve: nav_per_token drops below $1.00. nav_per_token = $0.92 → 8% writedown reflected in token price.

Consequences when NAV < $1.00:

• New investments stay open — new investors buy at the lower fair price, getting more tokens
• Existing yield continues on nominal deposit amount
• Redemptions pay tokens × nav_at_request + yield
• NAV decreases require 24-hour timelock (a forced waiting period before decrease takes effect; increases apply immediately)

NAV Update Timeline

Oracle posts NAV update 🔵 Oracle

Fund operator reports NAV off-chain → Aset oracle validates → updateNAV() called on PlatformPool. Row created in nav_history with status PENDING.

24-hour timelock (decreases only) 🟢 System

effective_at = now() + 24h. Notification sent to operators + fund issuers. NAV increases apply immediately — no timelock.

NAV takes effect 🟢 System

pools.nav_per_token updated, nav_history row marked APPLIED. Investment stays open — new investors pay the updated fair price.

Offline: Last NAV maintained 🔴 Admin

PD4 decided: No fallback. NAV stays at last known value. Admin can manually pause the pool for serious cases. source = oracle for normal updates.

How Admin Calculates a NAV Writedown

When a loss event occurs (e.g. a borrower defaults), the Oracle posts a new nav_per_token value on-chain via updateNAV(). Here's the step-by-step logic:

📖 Step-by-Step Example

Scenario: Joob EWA Fund pool has $1,000,000 in total deposits. A borrower defaults on a $120,000 loan.

Step 1 — Check the reserve fund first The pool has a 10% reserve = $1,000,000 × 0.10 = $100,000. The reserve covers $100,000 of the $120,000 loss. Remaining uncovered loss = $20,000

Step 2 — Calculate the new NAV The uncovered loss reduces nav_per_token. The formula is:

New NAV = Current NAV × (1 − Uncovered Loss ÷ Total Deposits)

New NAV = $1.00 × (1 − $20,000 ÷ $1,000,000) = $1.00 × 0.98 = $0.98

Step 3 — Apply the 24-hour timelock NAV decreases require a 24-hour waiting period before taking effect. NAV increases (recovery) apply immediately.

• ✓ Decrease is 2% → submitted as a pending NAV update
• ✓ 24-hour timelock applies — stakeholders can review or prepare
• ✓ NAV capped at $1.00 max — cannot increase above initial value

Step 4 — What this means for existing investors An investor who deposited $10,000 now has: Tokens still = 10,000 (from original deposit at $1.00 NAV). Token value = 10,000 × $0.98 = $9,800. They've lost $200 of token value (2%), but their yield still accrues on the full $10,000.

Step 5 — New investor gets fair entry A new investor depositing $10,000 at $0.98 NAV gets: tokens_minted = $10,000 ÷ $0.98 = 10,204 tokens → proportionally more tokens than original investors at $1.00. Fair entry.

🔢 Quick Reference Formula

1. Uncovered Loss = Total Loss − Reserve Fund
2. NAV Decrease % = Uncovered Loss ÷ Total Pool Deposits
3. New NAV = Current NAV × (1 − NAV Decrease %)
4. Existing investor value = tokens_minted × New NAV
5. New investor tokens = deposit_amount ÷ New NAV

If Current NAV is already below $1.00 (a previous writedown happened), use the current NAV in step 3. Writedowns are cumulative.

Portfolio NAV Display — Design Spec ✅ DECIDED

When a pool's NAV is below $1.00, the portfolio page must show the writedown transparently but without alarming design patterns. Investors are sophisticated — hiding information erodes trust faster than showing it.

✓ DO

• Show: "Invested: $1,000 → Current Value: $880 (NAV: $0.88)"
• Use neutral colors (grey/blue info card)
• Link to NAV history timeline for that pool
• Show NAV governance bounds as reassurance

✗ DON'T

• Red warning banners or alarm iconography
• Words like "loss", "default", "danger"
• Hide the writedown behind a click/expand
• Show NAV change without context or governance info

→ See Redemption for payout calculations and NAV scenario examples.