feat(invoice-escrow): implement configurable grace period window for …

[neyij]

Description

Implemented a configurable grace period for overdue invoice settlement in the invoice-escrow contract.

The grace period allows payments to be recorded after the invoice due date while the configured grace window is still active. Refunds are only permitted once the grace period has fully expired.

This change adds the grace_period_seconds configuration field, an admin setter for updating the grace period, updated payment and refund deadline checks, and a GracePeriodExpired event when an overdue refund is triggered.

Closes #375

Type of Change

• 🐛 Bug fix (non-breaking change which fixes an existing 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

The invoice-escrow test suite was updated to verify payment and refund behavior before, during, and after the configured grace period.

How to Test

1. Run the invoice escrow test suite:
   cargo test -p invoice-escrow
2. Create and fund an invoice with a configured grace period, then attempt to settle it after the original due date but within the grace period. Verify that the payment succeeds.
3. Attempt to settle the invoice after due_date + grace_period_seconds and verify that the transaction is rejected with Error::EscrowOverdue.
4. Attempt to refund the invoice before the grace period expires and verify that the transaction is rejected with Error::EscrowNotOverdue.
5. Advance the ledger timestamp beyond the grace period and verify that the refund succeeds and the GracePeriodExpired event is emitted.

Test Coverage

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

Screenshots (if applicable)

Not applicable — this change affects the Soroban contract logic and test suite rather than a user interface.

Additional Notes

The overdue threshold is now calculated as:

due_date + grace_period_seconds

Payments remain valid while the current timestamp is within the grace-period window. Refunds become available only after the grace period has fully elapsed.

The grace period can be updated by an authorized admin using set_grace_period, allowing the contract configuration to accommodate different settlement requirements.

For Reviewers

Please focus on:

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

In particular, review the deadline boundary conditions, authorization of set_grace_period, payment eligibility within the grace window, refund eligibility after expiration, and GracePeriodExpired event emission.

[drips-wave]

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