Feat/invoice escrow dispute resolution

[Stephan-Thomas]

Description

Implemented a complete on-chain dispute resolution lifecycle for the invoice-escrow contract.

The new dispute flow introduces a Disputed escrow state and supports raising, resolving, and timing out disputes:

• raise_dispute allows the buyer or seller to raise a dispute while the escrow is in the Funded state.
• resolve_dispute allows an authorized admin to resolve the dispute in favor of either the seller or buyer.
• Disputes that remain unresolved beyond the configured timeout automatically fall back to a buyer refund.

This change also adds dispute metadata tracking, dispute-related errors, the default 7-day dispute timeout, DisputeRaised event emission, and tests covering the complete dispute lifecycle and timeout behavior.

Closes #378

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 the complete dispute lifecycle, authorization requirements, resolution outcomes, and timeout fallback behavior.

How to Test

1. Run the invoice escrow test suite:
   cargo test -p invoice-escrow
2. Create an invoice and fund the escrow, then raise a dispute as the buyer or seller.
3. Verify that the escrow transitions from Funded to Disputed and that the dispute metadata and DisputeRaised event are recorded.
4. Resolve the dispute in favor of the seller and verify that the escrowed funds are released to the seller.
5. Resolve a dispute in favor of the buyer and verify that the escrowed funds are refunded to the buyer.
6. Advance the ledger timestamp beyond the configured dispute timeout and verify that an unresolved dispute triggers the default buyer refund.
7. Verify that unauthorized dispute resolution attempts are rejected.

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 dispute lifecycle introduces the following state transitions:

Funded -> Disputed -> Settled

or

Funded -> Disputed -> Refunded

If a dispute remains unresolved after the configured timeout period, the contract defaults to a buyer refund to prevent disputed escrow funds from remaining indefinitely locked.

The default dispute timeout is 7 days (604800 seconds).

Dispute metadata records the address that raised the dispute, the reason, the timestamp at which it was raised, and whether the dispute has been resolved.

For Reviewers

Please focus on:

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

In particular, review the dispute state transitions, authorization checks for dispute resolution, seller/buyer settlement paths, timeout handling, dispute metadata lifecycle, and the default refund behavior.

[drips-wave]

@Stephan-Thomas 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