Add Beneficiary Priority & Waterfall Distribution to Inheritance Contract

[ONEONUORA]

Component: Contracts (Inheritance) | Effort: 4-5 days | Priority: MEDIUM

Current State

All beneficiaries have equal priority. No waterfall or priority-based distribution.

Missing Functions

Priority distribution functions:

• set_beneficiary_priority() - Set priority level (1=highest)
• get_beneficiary_priority() - Get priority level
• enable_waterfall_distribution() - Enable priority-based distribution
• calculate_waterfall_amounts() - Calculate amounts based on priority
• claim_by_priority() - Claim respecting priority order

Why This Matters

• Flexibility: Some beneficiaries should receive first (e.g., spouse before children)
• Debt coverage: Pay debts before distributing to heirs
• Legal compliance: Some jurisdictions require priority distribution
• Estate planning: Standard practice in complex estates

Tasks

• Add priority field to Beneficiary struct
• Add waterfall_enabled flag to InheritancePlan
• Implement set_beneficiary_priority() function
• Add enable_waterfall_distribution() function
• Implement calculate_waterfall_amounts() logic
  • Priority 1 beneficiaries get full allocation first
  • Priority 2 only if funds remain after priority 1
  • Continue down priority levels
• Modify claim_inheritance_plan() to respect priority
• Add get_claimable_by_priority() view
• Implement priority validation (no duplicate priorities)
• Add WaterfallEnabled, PrioritySet events
• Add tests for waterfall distribution
• Document priority system

Acceptance Criteria

• Beneficiary priorities can be set
• Waterfall distribution works correctly
• Higher priority beneficiaries claim first
• Insufficient funds handled properly
• Tests cover priority scenarios
• Documentation explains waterfall logic