Fix/partial settlement issue 7

[KevinMB0220]

Description

Implemented a Partial-Settlement Model for the invoice-escrow contract to address issue #7, where underpayments were stranding funds in the contract balance after settlement.

The contract now:

1. Tracks cumulative payments through a new paid_amt field in EscrowData.
2. Allows multiple record_payment calls until the full invoice amount is reached.
3. Proportionally releases the investor's initial funding (collateral) back to the Seller during each payment, ensuring the contract balance returns to zero upon full settlement.
4. Correctly calculates and returns only the remaining, un-released collateral during a refund.

Closes #7

Complexity / points: High (200 points) - maintainer label: points-200-high

Type of Change

• 🐛 Bug fix (non-breaking change which fixes an issue)
• ✨ New feature (non-breaking change which adds functionality)
• 💥 Breaking change (fix or feature that would cause existing functionality to not work as expected)
• 📝 Documentation update
• 🎨 UI/UX improvement
• ♻️ Code refactoring
• ✅ Test addition or update
• 🔧 Configuration change

Checklist

• My code follows the code style of this project
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• Any dependent changes have been merged and published

Testing

Comprehensive testing was performed to ensure correct settlement and balance tracking.

How to Test

1. Run all unit and integration tests: cargo test -p invoice-escrow.
2. Inspect the new test cases in contracts/invoice-escrow/src/test.rs specifically:
   • test_partial_payment_lifecycle: Confirms statuses remain Funded during underpayment and transition to Settled correctly on final payment.
   • test_refund_after_partial_payment: Confirms only the remaining balance is refunded to the investor.
3. Check the integration test test_integration_escrow_lifecycle_happy_path in contracts/invoice-escrow/src/integration_test.rs to verify that the contract balance is 0 and the seller holds the full funding amount post-settlement.

Test Coverage

• Unit tests added/updated
• Integration tests added/updated
• E2E tests added/updated (if applicable)
• Manual testing completed

Screenshots (if applicable)

N/A

Additional Notes

The fix chosen was the "Partial-settlement model" which tracks remaining amounts and ensures that for every token received from the payer, a proportional amount of the investor's buy-in is released to the seller. This completely resolves the "stranded funds" problem and supports use cases with multiple payment increments.

For Reviewers

• Code quality and readability
• Test coverage
• Security implications
• Performance impact
• Breaking changes

[drips-wave]

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