[Feature]: Time-Locked Escrow & Milestone Deadlines

[SudiptaPaul-31]

🔍 Problem Statement

Description

Enhance the Soroban escrow contract with deadline-based protections. This ensures milestones are completed within agreed timelines, prevents misuse of escrow funds, and enforces refund/extension rules directly on-chain.

---

Requirements

• Store milestone deadline — each milestone must include a deadline timestamp at creation.
• Prevent invalid deadline modifications — deadlines cannot be shortened/extended by unauthorized users.
• Detect expired milestones — contract checks if the current block time exceeds the milestone deadline.
• Define behavior after deadline — specify whether funds are refunded, extended, or locked pending dispute.
• Support refund/extension rules — allow client-initiated refunds or arbitrator-approved extensions.

---

Acceptance Criteria

• ✅ Deadline logic enforced on-chain — contract rejects milestone approval/release if deadline has expired.
• ✅ Unauthorized users cannot modify deadlines — only client or arbitrator can request extensions.
• ✅ Expired milestones handled gracefully — funds refunded or locked until resolution.
• ✅ Edge cases tested — multiple milestones expiring simultaneously, disputes raised after expiry, and escrow funded but no submission.
• ✅ Event emission — log DeadlineSet, DeadlineExpired, DeadlineExtended, RefundIssued.

---

Additional Notes

• State machine integration:

  • Add Expired state to milestone lifecycle.
  • Ensure transitions from Expired → Refunded or Expired → Extended.

• Security considerations:

  • Prevent replay attacks by binding deadlines to milestone IDs.
  • Ensure extensions require cryptographic authorization from client/arbitrator.

• Testing:

  • Unit tests for valid/invalid deadline modifications.
  • Edge cases: expired milestones with pending disputes, overlapping deadlines, and refund race conditions.

---

Future Enhancements

• 🔹 Automatic refund after expiry without manual trigger.
• 🔹 DAO-based voting for deadline extensions.
• 🔹 Off-chain notifications/reminders before deadlines.

📈 Expected Impact

High — Would significantly improve user experience

[devkylian-tech]

@devkylian-tech has applied to work on this issue as part of the Stellar Wave Program's 9th wave.

maintainer assign the work to me

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

[yunus-dev-codecrafter]

@yunus-dev-codecrafter has applied to work on this issue as part of the Stellar Wave Program's 9th wave.

Hi! I've carefully reviewed the entire task description and fully understand the requirements and expected outcome.
I have experience working on similar tasks and I'm confident I can complete this within about an hour. I'd be happy to take ownership of this issue and submit a clean, well-tested solution promptly.
If it's available, please assign it to me. Thank you!

ℹ️ Repo Maintainers: To accept this application, review their application or assign @yunus-dev-codecrafter to this issue.

[mexes20]

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

Hello, kindly assign me to work on this issue

ETA: 24 hours

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

[Jentle042]

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

Please assign issue to me .

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

[drips-wave]

Congratulations, @devkylian-tech! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on September 30, 2026.

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