feat: on-chain order expiry — user-set TTL on limit and stop orders

[abayomicornelius]

Summary

Limit and stop-loss orders currently live in storage indefinitely until executed or manually cancelled. Users have no way to set an automatic expiry, which means stale orders accumulate and clutter keeper queues.

Proposed Design

Add an optional expiry_ledger: Option<u64> field to CreateOrderParams.

• If Some(n), the order is only executable while env.ledger().sequence() <= n
• After expiry, the keeper calls execute_order and it auto-cancels (refunding the user) instead of reverting
• Alternatively, anyone can call cleanup_expired_order(nonce) to cancel and get a small incentive fee

Storage Impact

One extra u64 field per order — negligible.

Acceptance Criteria

• CreateOrderParams includes expiry_ledger: Option<u64>
• Keeper execution after expiry auto-cancels and refunds user
• cleanup_expired_order callable by anyone; caller receives a configurable incentive
• Order with expiry_ledger = None behaves exactly as today (no regression)
• Integration test: limit order expires, user refunded, storage cleared
• Integration test: limit order executed before expiry works normally

Affected Contracts

exchange_router, order_handler, data_store

[GauravKarakoti]

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

Allow me to work on this one

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

[Adesam007-pr3dator]

@Adesam007-pr3dator has applied to work on this issue as part of the Stellar Wave Program's 6th wave.

Hi, I would love to work on this issue because I can

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

[bade22brazy]

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

assign me this issue

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

[drips-wave]

Congratulations, @bade22brazy! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on June 30, 2026.

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

[grantfox-oss]

🦊 GrantFox — @bade22brazy has been assigned to this issue as part of the Official Campaign campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #272)
2. Your PR will be reviewed by the SO4-Markets maintainers

Good luck! Track your progress on GrantFox.