feat(protection): implement insurance fund system

[DaddyMord]

Overview

This PR adds a complete Insurance Fund System to SwapTrade-Backend, providing a multi-layered safety mechanism that automatically covers liquidation shortfalls, monitors fund health in real time, distributes trading-fee contributions, and maintains a full audit trail for all insurance-related transactions.

Related Issue

Closes #380

Changes

🛡️ Protection Domain (src/protection/)

• [ADD] src/protection/entities/insurance-fund-tier.entity.ts

• Added InsuranceFundTier entity supporting LOW, MEDIUM, HIGH, and CRITICAL risk tiers.

• Each tier defines minReserve, maxExposure, and feeContributionPct.

• [ADD] src/protection/entities/insurance-fund.entity.ts

• Added InsuranceFund entity to track balance, target reserve, health percent, and health status per tier/asset pair.

• [ADD] src/protection/entities/insurance-transaction.entity.ts

• Added InsuranceTransaction entity for a complete audit trail.

• Supports DEPOSIT, PAYOUT, FEE_CONTRIBUTION, and REPLENISHMENT transaction types.

• Records balanceBefore, balanceAfter, referenceId, userId, and metadata.

• [ADD] src/protection/entities/liquidation-event.entity.ts

• Added LiquidationEvent entity to track liquidation shortfall coverage and cascade prevention outcomes.

⚙️ Core Services

• [ADD] src/protection/services/insurance-fund.service.ts

• Core insurance fund ledger: initialize multi-tier funds, record transactions, replenish, and fee contributions.

• Seeds four default tiers (LOW → CRITICAL) on initialization.

• [ADD] src/protection/services/liquidation-protection.service.ts

• Automated liquidation shortfall coverage with cascade prevention.

• Iterates tiers in priority order (LOW → CRITICAL) to cover shortfalls.

• Emits LiquidationShortfallEvent and InsurancePayoutEvent on coverage.

• [ADD] src/protection/services/fund-health.service.ts

• Real-time fund health monitoring with dashboard metrics.

• Triggers FundHealthAlertEvent when reserves drop below 20% threshold.

• Resolves health status: HEALTHY, WARNING, CRITICAL, DEPLETED.

• [ADD] src/protection/services/insurance-fee-contribution.service.ts

• Replenishes insurance funds from trading fees based on tier feeContributionPct.

• Integrated via ProtectionListener on trade.executed events.

🌐 REST API Surface

• [ADD] src/protection/insurance-fund.controller.ts

• POST /protection/insurance/initialize — seed multi-tier funds

• GET /protection/insurance/funds — list all funds

• GET /protection/insurance/funds/:id — get fund details

• GET /protection/insurance/tiers — list risk tiers

• GET /protection/insurance/health/dashboard — fund health dashboard

• GET /protection/insurance/health/alerts — active alerts (< 20%)

• GET /protection/insurance/health/funds/:id — per-fund health metrics

• POST /protection/insurance/replenish — manual fund replenishment

• POST /protection/insurance/cover-shortfall — inject insurance for liquidation shortfall

• POST /protection/insurance/contribute-fees — add trading fees to fund

• GET /protection/insurance/transactions — audit trail

• [ADD] src/protection/protection.module.ts

• Dedicated NestJS module for the Protection domain.

• Exported all insurance services for reuse by trading/order modules.

• [ADD] src/protection/listeners/protection.listener.ts

• Event listener for trade.executed (auto fee contribution), liquidation.shortfall, and fund.health.alert.

• [MODIFY] src/app.module.ts

• Registered ProtectionModule and new insurance entities in TypeORM.

🗄️ Database

• [ADD] src/database/migrations/1727516400003-CreateInsuranceFundTables.ts
• Migration for insurance_fund_tiers, insurance_funds, insurance_transactions, and liquidation_events tables.

🔐 Permissions & Configuration

• [MODIFY] src/identity/permissions/constants/permissions.ts

• Added insurance.read, insurance.write, and insurance.admin permissions.

• [MODIFY] src/config/config.schema.ts

• Added FEATURE_INSURANCE_ENABLED, INSURANCE_MIN_RESERVE_PCT, and INSURANCE_FEE_CONTRIBUTION_PCT.

• [MODIFY] src/infrastructure/events/domain.events.ts

• Added LiquidationShortfallEvent, InsurancePayoutEvent, and FundHealthAlertEvent.

🧪 Tests

• [ADD] src/protection/services/fund-health.service.spec.ts

• Unit tests for health percent calculation, status resolution, and 20% alert threshold.

• [ADD] src/protection/services/insurance-fund.service.spec.ts

• Unit tests for transaction recording, fee contributions, and payouts.

• [ADD] src/protection/services/liquidation-protection.service.spec.ts

• Unit tests for full and partial shortfall coverage with cascade prevention.

• [ADD] src/protection/insurance-fund.integration.spec.ts

• Full lifecycle integration test: initialize → fee contribution → cover shortfall → health dashboard → replenish → audit trail → health alert.

Verification Results

Acceptance Criteria	Status
System auto-injects insurance funds to cover liquidation shortfalls	✅
Fund health monitored; alerts trigger when reserves drop below 20%	✅
All insurance transactions logged with complete audit trail	✅
Multiple insurance fund tiers supported for different risk levels	✅
Insurance fund replenished through trading fees	✅
Cascade liquidation prevention logic implemented	✅
Real-time fund health dashboard endpoints available	✅
Protection module tests pass (16/16)	✅
Protection module has zero TypeScript errors	✅