feat(invoice-escrow): implement complete dispute resolution lifecycle with timeout and default fallback

[chizzy192]

Context & Problem Statement

Commercial trade invoices occasionally experience invoice disputes regarding deliverable quality, delivery delays, or billing discrepancies. Without an on-chain dispute state machine, escrows remain locked in Funded state until the overdue deadline lapses, which can trigger an unfair automatic refund to the buyer.

This issue implements an on-chain dispute state machine with formal transitions (Funded -> Disputed -> Settled/Refunded), dispute metadata tracking, admin resolution with favor assignment, and an automated timeout fallback mechanism.

Architectural Motivation & Technical Requirements

• In contracts/invoice-escrow/src/types.rs:
  • Add EscrowStatus::Disputed variant.
  • Add DisputeData { raiser: Address, reason: Bytes, raised_at: u64, resolved: bool }.
  • Add dispute_timeout_secs: u64 to Config (default: 604800s / 7 days).
• In contracts/invoice-escrow/src/lib.rs:
  • Implement raise_dispute(env, caller: Address, invoice_id: Symbol, reason: Bytes):
    • Asserts escrow is in Funded status.
    • Transitions status to Disputed and records DisputeData.
    • Emits DisputeRaised event.
  • Implement resolve_dispute(env, admin: Address, invoice_id: Symbol, favour: Symbol):
    • If favour == 'seller', settles funds to seller.
    • If favour == 'buyer', refunds funds to buyer.
    • If called after dispute_timeout_secs, executes default fallback (refund to buyer).
• In contracts/invoice-escrow/src/errors.rs:
  • Add NotDisputed, AlreadyResolved, DisputeTimedOut.
• In contracts/invoice-escrow/src/test.rs:
  • Test dispute raise by buyer/seller.
  • Test resolution in favor of seller and buyer.
  • Test timeout expiration triggering default refund.

Acceptance Criteria

• Full dispute lifecycle implemented with all state transitions.
• Timeout fallback behavior verified.
• Unauthorized dispute resolution attempts rejected.
• cargo test -p invoice-escrow passes.

Target Branch: dev
Estimated Effort: 13–24 hours | Delivery: 6–7 days
Difficulty: Hard

[alexitsejames-cpu]

@alexitsejames-cpu has applied to work on this issue as part of the Stellar Wave Program's 8th wave.

Hi maintainer, can you pls assign these issue to me

ℹ️ Repo Maintainers: To accept this application, review their application or assign @alexitsejames-cpu to this issue.

[Engr-Able]

@Engr-Able has applied to work on this issue as part of the Stellar Wave Program's 8th wave.

Hello Maintainer, I’ve read through the issue description and have a clear understanding of the expected outcome. I’d be pleased to take on this task and contribute a quality solution to the project.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Engr-Able to this issue.

[Stephan-Thomas]

@Stephan-Thomas has applied to work on this issue as part of the Stellar Wave Program's 8th wave.

hi, i would like to work on this.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Stephan-Thomas to this issue.

[drips-wave]

Congratulations, @Stephan-Thomas! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on August 31, 2026.

🧑‍💻 @Stephan-Thomas: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.

Warning

When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are awarded when this issue is marked as completed by the maintainer.

🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.

🌊 Happy Wave 🌊