Feat/533 protection fund

[CHKM001]

PR #533 Protocol-Risk Protection Fund / Deposit Insurance

Summary

Adds a platform-funded reserve pool that makes depositors partially or fully whole after a covered protocol-level loss event. Funded by a configurable revenue skim, governed by explicit published coverage terms.

What's Included

Data Model

• ProtectionFundBalance — platform-owned treasury tier tracking fund balance per asset
• ProtectionFundContribution — transparent ledger of all fund inflows (revenue skim, manual, treasury transfer)
• CoverageEvent — admin-declared protocol-loss incident with dual-review workflow
• CoverageClaim — per-user, per-position claim with automatic computation from position history
• Migration 20260930120000_add_protection_fund with rollback

Service Layer (src/protectionFund/service.ts)

• getCoverageTerms() — published coverage terms (covered causes, exclusions, caps)
• recordContribution() — fund inflow with audit ledger entry
• declareCoverageEvent() — admin declares event, enters PENDING_REVIEW
• reviewCoverageEvent() — dual-review approval/rejection, triggers claim computation
• computeClaimsForEvent() — automatic per-user claim computation from position history
• executePayout() — payout via outbox pattern
• getMyCoverage() — per-user exposure and estimated coverage
• getProtectionFundStatus() — public fund status and historical events

Routes (src/routes/protection-fund.ts)

Method	Path	Description	Auth
GET	/api/v1/protection-fund/status	Public fund balance, coverage terms, historical events	None
GET	/api/v1/protection-fund/my-coverage	User's exposure + estimated coverage	User
POST	/api/v1/protection-fund/events	Declare coverage event	Admin
POST	/api/v1/protection-fund/events/:eventId/review	Approve/reject event	Admin
POST	/api/v1/protection-fund/contributions	Record fund contribution	Admin
POST	/api/v1/protection-fund/claims/:claimId/payout	Execute claim payout	Admin

Configuration (src/config/env.ts)

• PROTECTION_FUND_REVENUE_SKIM_FRACTION (default: 0 = off)
• PROTECTION_FUND_PER_USER_CAP (default: 10,000 USDC)
• PROTECTION_FUND_MIN_HOLD_DURATION_MS (default: 7 days)
• PROTECTION_FUND_DEFAULT_ASSET (default: USDC)

Coverage Terms

Covered Events

• EXPLOIT — smart-contract exploit or hack
• INSOLVENCY — protocol cannot honor withdrawals
• GOVERNANCE_FAILURE — governance attack resulting in loss of funds

Excluded Events

• MARKET_PRICE_LOSS — normal market-price movement (investing risk)
• USER_ERROR — wrong address, phishing, etc.
• NORMAL_RISK — any loss that is not a protocol-level failure

Safety Invariants

• Dual-review: Coverage-event declaration requires approval by a second admin
• Pro-rated payouts: When fund is underfunded, payouts are pro-rated transparently
• Min hold duration: Positions must be held for minHoldDurationMs before eligible (anti-gaming)
• Per-user cap: No single user can claim more than perUserCoverageCap per event
• Audit ledger: All fund flows recorded on the Tamper-Evident Hash-Chained Audit Ledger #315 audit chain
• Treasury reuse: Fund custody reuses existing treasury/multisig tiering (Treasury Sweep Policies, Emergency Sweep Path & Signer Rotation #528)

Test Results

• tests/unit/protectionFund/service.test.ts — 8 tests covering fund balance, contributions, event declaration, review, claim computation, and queries

Documentation

• docs/PROTECTION_FUND.md — full coverage terms, exclusions, transparency reporting, and API reference

Out of Scope (v1)

• Third-party insurance underwriting integration
• Coverage for user error (wrong address, phishing)
• Guaranteeing full coverage regardless of fund size

Closes #533

[drips-wave]

@CHKM001 Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits