feat(escrow): enforce dispute state transitions and cover dispute edge cases (#220)

[Tinu-ola]

Overview

Hardens the Soroban dispute escrow mechanism in contracts/contracts/escrow so the dispute lifecycle matches the state machine required by the issue: Submitted -> Disputed -> Resolved -> Released/Refunded.

The escrow contract already exposed dispute() / resolve_dispute() and the DisputeRaised / DisputeResolved events. This PR closes the remaining gaps between that implementation and the issue's acceptance criteria, and adds the edge-case tests the issue explicitly asks for.

Related Issue

Closes #220

Changes

contracts/contracts/escrow/src/lib.rs

• [MODIFY] dispute()
  • Role-based access: the authorized arbitrator can now raise a dispute, in addition to the client and freelancer (issue requirement: "only authorized parties ... client or arbitrator"). Anything else still returns Unauthorized (404 Not Found Page #7).
  • No lifecycle bypass: a dispute may only be raised once the milestone has been funded and submitted (Submitted/Approved). Disputing a Pending/Funded milestone now returns InvalidMilestoneStatus (Design logo for the website #6), so a dispute can no longer skip milestone submission.
• [MODIFY] release()
  • Adds an explicit Disputed guard returning InvalidMilestoneStatus (Design logo for the website #6). Escrowed funds are frozen while a dispute is open and release() is blocked until the arbitrator resolves it.

contracts/contracts/escrow/src/test.rs

Added an edge-case suite for the dispute mechanism:

• test_dispute_without_funding_fails - dispute cannot bypass escrow funding.
• test_dispute_before_submission_fails - dispute cannot bypass milestone submission.
• test_arbiter_can_raise_dispute - the arbitrator is an authorized disputer.
• test_release_blocked_while_disputed - payments are frozen during a dispute.
• test_refund_blocked_while_disputed - refunds are frozen during a dispute.
• test_multiple_disputes_rejected - a resolved milestone is terminal.
• test_resolve_without_dispute_fails - resolution requires an open dispute.
• test_dispute_events_are_emitted - DisputeRaised / DisputeResolved are emitted.

Verification

• Statically reviewed: changes are limited to the escrow contract and its test module; no public ABI, event schema, or error numbering was changed (dispute access is only widened to the arbiter; the new failure path reuses the existing InvalidMilestoneStatus = Design logo for the website #6).
• Existing behaviour preserved: the pre-existing dispute tests (test_dispute_and_resolve_to_freelancer, test_dispute_and_resolve_to_client, test_dispute_clears_approvals, test_unauthorized_dispute_fails, test_dispute_after_release_fails) still hold under the new guards - they dispute milestones in Submitted/Approved state.
• Not run locally: this change was authored through the GitHub REST API with no local checkout, so cargo test --workspace (contracts CI job) was not executed here. The new tests follow the existing #[should_panic(expected = "HostError: Error(Contract, #N)")] and event-count conventions already used in test.rs.

[drips-wave]

@Tinu-ola 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