Contract: Implement Basic Insurance Pool and Claims Management System #513
Description
Description:
Build a smart contract that manages a simple insurance pool where users can purchase coverage for their shipments and file claims for losses or damages.
Contract Purpose:
Provide a decentralized insurance mechanism where shippers can insure their cargo, pay premiums, and receive payouts for valid claims, all managed transparently on-chain.
Core Functionality to Implement:
1. Data Structures
InsurancePolicy:
- policy_id (unique identifier)
- shipment_id (one policy per shipment)
- policyholder_address (shipper)
- cargo_value (declared value)
- premium_amount (calculated as % of cargo value)
- coverage_amount (maximum payout, usually 80-100% of cargo value)
- start_timestamp
- end_timestamp (coverage period)
- status (Active, Expired, Claimed, Cancelled)
- is_paid (premium payment status)
InsuranceClaim:
- claim_id (unique identifier)
- policy_id
- claimant_address (policyholder)
- claim_type (enum)
- claimed_amount
- evidence_hashes (array of document/photo hashes)
- claim_reason_hash (detailed explanation)
- submission_timestamp
- review_deadline
- status (Pending, Approved, Rejected, Paid)
- reviewer_address (who reviewed)
- payout_amount (actual amount paid, may differ from claimed)
- review_notes_hash
ClaimType Enum:
- TotalLoss (complete loss of cargo)
- PartialLoss (some cargo lost/damaged)
- Damage (cargo damaged but usable)
- Delay (severe delay compensation)
- Theft
ClaimStatus Enum:
- Pending
- UnderReview
- Approved
- Rejected
- Paid
PolicyStatus Enum:
- Active
- Expired
- Claimed
- Cancelled
2. Storage
- Map of policy_id to InsurancePolicy
- Map of shipment_id to policy_id (one per shipment)
- Map of claim_id to InsuranceClaim
- Map of policy_id to claim_id (one claim per policy)
- Insurance pool balance (total funds available)
- Total premiums collected
- Total claims paid
- Premium percentage (configurable, e.g., 5% of cargo value)
- Coverage percentage (configurable, e.g., 90% of cargo value)
3. Contract Functions
Purchase Insurance:
- Takes shipment_id, cargo_value, coverage_period_days
- Validates shipment exists and not yet departed
- Calculates premium (cargo_value * premium_percentage)
- Validates caller sends exact premium amount
- Creates InsurancePolicy with Active status
- Adds premium to insurance pool
- Sets start/end timestamps
- Emits PolicyPurchased event
- Returns policy_id
Get Policy:
- Takes policy_id
- Returns complete InsurancePolicy struct
- Public read function
Get Policy by Shipment:
- Takes shipment_id
- Returns policy_id if exists
- Public read function
File Claim:
- Takes policy_id, claim_type, claimed_amount, evidence_hashes, reason_hash
- Validates caller is policyholder
- Validates policy is Active
- Validates policy hasn't expired
- Validates no existing claim for this policy
- Validates claimed_amount <= coverage_amount
- Creates InsuranceClaim with Pending status
- Sets review_deadline (e.g., 14 days from submission)
- Changes policy status to Claimed
- Emits ClaimFiled event
- Returns claim_id
Submit Additional Evidence:
- Takes claim_id, new_evidence_hash
- Validates caller is claimant
- Validates claim is Pending or UnderReview
- Adds evidence to claim's evidence array
- Emits EvidenceAdded event
Review Claim:
- Takes claim_id
- Only callable by authorized reviewers (Admin or Claims Adjuster role)
- Changes status to UnderReview
- Assigns reviewer
- Emits ClaimUnderReview event
Approve Claim:
- Takes claim_id, approved_amount, review_notes_hash
- Only callable by assigned reviewer
- Validates approved_amount <= claimed_amount <= coverage_amount
- Validates sufficient pool balance
- Changes status to Approved
- Records approved amount and notes
- Emits ClaimApproved event
Reject Claim:
- Takes claim_id, rejection_reason_hash
- Only callable by assigned reviewer
- Changes status to Rejected
- Records rejection reason
- Changes policy status back to Active (if not expired)
- Emits ClaimRejected event
Payout Claim:
- Takes claim_id
- Only callable after claim Approved
- Validates pool has sufficient balance
- Transfers approved_amount to policyholder
- Deducts from pool balance
- Changes claim status to Paid
- Changes policy status to Claimed
- Emits ClaimPaid event
Cancel Policy:
- Takes policy_id
- Only callable by policyholder
- Only if shipment not yet departed
- Refunds partial premium (e.g., 80% refund, 20% admin fee)
- Changes policy status to Cancelled
- Emits PolicyCancelled event
Get Pool Balance:
- Returns current insurance pool balance
- Public read function
Get Pool Statistics:
- Returns total_premiums, total_claims, pool_balance
- Calculates loss_ratio (claims / premiums)
- Public read function
Update Premium Rate:
- Takes new_premium_percentage
- Only callable by Admin
- Updates premium calculation rate
- Emits PremiumRateUpdated event
Update Coverage Rate:
- Takes new_coverage_percentage
- Only callable by Admin
- Updates coverage percentage
- Emits CoverageRateUpdated event
4. Events
- PolicyPurchased(policy_id, shipment_id, policyholder, cargo_value, premium, timestamp)
- ClaimFiled(claim_id, policy_id, claim_type, claimed_amount, timestamp)
- EvidenceAdded(claim_id, evidence_hash, timestamp)
- ClaimUnderReview(claim_id, reviewer, timestamp)
- ClaimApproved(claim_id, approved_amount, reviewer, timestamp)
- ClaimRejected(claim_id, reason_hash, reviewer, timestamp)
- ClaimPaid(claim_id, payout_amount, timestamp)
- PolicyCancelled(policy_id, refund_amount, timestamp)
- PremiumRateUpdated(old_rate, new_rate, timestamp)
- CoverageRateUpdated(old_rate, new_rate, timestamp)
5. Premium Calculation
Premium = Cargo Value × Premium Percentage
Example: $10,000 cargo × 5% = $500 premium
Coverage = Cargo Value × Coverage Percentage
Example: $10,000 × 90% = $9,000 max coverage
Claim Review Process:
- Policyholder files claim with evidence
- Claim goes to Pending status
- Reviewer assigned → UnderReview
- Reviewer examines evidence:
- Photos of damage
- Police reports (for theft)
- Delivery receipts
- Milestone records (for proof of location)
- Decision made → Approved or Rejected
- If approved, payout executed → Paid
Pool Management:
- Pool starts with initial capital (funded by platform)
- Grows with premium payments
- Depletes with claim payouts
- Target loss ratio: 60-70% (sustainable insurance model)
- If pool balance low, may need to increase premiums or reduce coverage
Integration Points:
- Integrates with Shipment contract (verify shipment exists)
- Integrates with Milestone contract (verify events for claims)
- Integrates with Document contract (evidence verification)
- Access Control for reviewer permissions
Acceptance Criteria:
- Purchase insurance calculates premium correctly
- Premium payment validated (exact amount)
- Get policy returns accurate data
- File claim validates all requirements
- Cannot file duplicate claims
- Submit evidence restricted to claimant
- Review claim restricted to authorized reviewers
- Approve/reject claim restricted to assigned reviewer
- Payout validates pool balance
- Payout transfers correct amount
- Cancel policy provides appropriate refund
- Pool statistics calculate correctly
- Update rates restricted to Admin
- All events emit correctly
- Unit tests cover all functions (>80% coverage)
- Integration tests with other contracts
- Gas-optimized operations