[Feature]: Soroban Milestone Escrow State Machine

[SudiptaPaul-31]

🔍 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

[Carlys17]

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

I'd like to work on this. I'll implement a formal state machine for milestone escrow with guarded transitions across Created/Funded/InProgress/Submitted/Approved/Released and dispute handling, with typed errors and events.

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

[CodeNinjaStephen]

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

Hello, I'd like to work on this one if it's still available. Happy to be assigned. Thanks!

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

[drips-wave]

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

🧑‍💻 @CodeNinjaStephen: 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 🌊