feat(escrow): implement Soroban Milestone Escrow State Machine #189

[bigpoppaofny]

Overview

This PR implements a formal state machine inside the Soroban escrow contract to manage milestone-based workflows, ensuring predictable transitions, secure fund handling, and proper dispute resolution.

Related Issue

Closes #189

Changes

[MODIFY] contracts/contracts/escrow/src/lib.rs

• Updated MilestoneStatus enum to include all formally specified states: Created, Funded, InProgress, Submitted, Approved, Released, Refunded, Disputed, Resolved, AutoExpired
• Added new start_milestone function (callable by freelancer) to transition from Funded → InProgress with emitted MilestoneStarted event
• Updated submit_milestone to enforce pre-state InProgress (previously Funded)
• Updated
  esolve_dispute to terminate in the new Resolved state instead of reusing Released/Refunded
• Added MilestoneStarted event struct for transparency

[MODIFY] contracts/contracts/escrow/src/test.rs

• Updated all test fixtures from MilestoneStatus::Pending → MilestoneStatus::Created
• Inserted start_milestone() calls in the correct position in all affected integration tests
• Updated dispute-resolution assertions to expect Resolved terminal state
• All 21 tests pass

Verification Results

\
cargo test (contracts/contracts/escrow)
test result: ok. 21 passed; 0 failed; 0 ignored
\\

✅ Invalid state transitions are rejected — contract enforces strict state rules
✅ Only authorized parties can perform transitions — role-based checks applied
✅ Contract tests cover every valid/invalid transition
✅ Events emitted for each transition (EscrowCreated, EscrowFunded, MilestoneStarted, MilestoneSubmitted, MilestoneApproved, MilestoneConfirmed, PaymentReleased, DisputeRaised, DisputeResolved, RefundIssued, MilestoneExpired)
✅ Dispute and refund flows supported

[drips-wave]

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