[Feature]: Soroban Milestone Escrow State Machine #189

🔍 Problem Statement

Description

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

States

• Created → initial contract setup
• Funded → escrow funded by client
• InProgress → milestone work underway
• Submitted → freelancer submits milestone deliverable
• Approved → client approves milestone
• Released → funds released to freelancer

Additional Transitions

• Submitted → Disputed — client raises dispute on submission
• Disputed → Resolved — dispute resolved by arbitrator
• Funded → Refunded — funds returned to client if conditions fail

Tasks

• Define state machine schema — contract-level enum for states and transitions.
• Implement transition functions — enforce valid moves between states.
• Add authorization checks — only client, freelancer, or arbitrator can trigger specific transitions.
• Reject invalid transitions — contract must fail gracefully if unauthorized or invalid.
• Emit events — log state changes for transparency and monitoring.
• Write contract tests — cover every valid and invalid transition path.

Acceptance Criteria

• ✅ 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 — ensuring reliability.
• ✅ Events emitted for each transition — visible in transaction logs.
• ✅ Dispute and refund flows supported — handled securely within state machine.

📈 Expected Impact

High — Would significantly improve user experience