feat(escrow): add emergency refund pathway with safety guards

[ChukwuemekaP1]

This PR implements an emergency refund mechanism for the LiquiFact Escrow contract, allowing admin-activated proportional refunds to investors in exceptional circumstances.

Changes
escrow/src/lib.rs:

Added emergency_mode field to InvoiceEscrow struct
Added new DataKey enum for storage keys: Escrow, InvestorBalances, RefundedInvestors, ReentrancyGuard
Added new events: EmergencyActivated, EmergencyRefunded
Added MaturityUpdatedEvent as a proper #[contractevent] with #[topic] attribute
Implemented activate_emergency() function with admin-only access control
Implemented emergency_refund() function with:
Reentrancy protection using checks-effects-interactions pattern
Double-claim prevention via RefundedInvestors tracking
Individual investor balance tracking
Updated fund() to track individual investor balances
Updated migrate() to include V1→V2 migration path for emergency mode support
Fixed: Removed duplicate #[contracttype] from MaturityUpdatedEvent (was causing spec_xdr conflicts)
Fixed: Corrected doc comments in emergency_refund to prevent doctest failures
escrow/src/test.rs:

Added comprehensive test coverage for emergency refund functionality (38+ new tests)
Tests include:
Happy paths: emergency activation in open/funded status, single/multi investor refunds
Failure cases: double activation, refund before emergency, double refund, zero balance
Edge cases: many investors with uneven shares, balance accumulation, reentrancy guard verification
Authorization tests for admin/investor roles
Fixed: Updated all &800i64 to &800u64 for type consistency with contract API
README.md:

Added comprehensive documentation for Emergency Refund Mechanism
Documented design decisions, access control, state transitions, and security considerations
Added version history entry for Schema Version 2
Security Considerations
Emergency mode is one-way: once activated, escrow cannot return to normal operation
Only admin can activate emergency mode (consistent with update_maturity pattern)
Reentrancy guard prevents recursive calls during refund processing
Double-claim prevention ensures each investor can only refund once
Checks-effects-interactions pattern strictly followed in emergency_refund
Testing
All 50+ tests passing
Build successful with no errors
Coverage includes happy paths, failure cases, and edge cases
Checklist
Implementation follows existing code patterns
Comprehensive test coverage (95%+ on new code)
Documentation updated
No breaking changes to existing APIs
Build passes: cargo build
Tests pass: cargo test

closes #41

[drips-wave]

@ChukwuemekaP1 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