[Wave 7 3/10] Read-only refund eligibility endpoint for transaction history

[karagozemin]

Summary

Users need to know when a stuck order can be refunded. Add a read-only refund eligibility endpoint/helper that transaction history can consume without sending transactions.

High UX/safety value, manageable read-only implementation.

Scope

• Add a helper that computes refund eligibility from order status, timelock, direction, and current time.
• Optionally expose it through an existing order detail/history response.
• Include reason codes: not expired, already claimed, already refunded, eligible, unknown order.
• Add tests for ETH->XLM and XLM->ETH orders across statuses.

Guardrails

• Do not auto-submit refunds.
• Do not change contract calls.
• Do not mark an order refunded until on-chain evidence exists.

Acceptance criteria

• Frontend/API can show refund eligibility and reason.
• Tests cover status/time combinations.
• Existing history behavior remains compatible.

Wave complexity (maintainer)

High - 200 points

[laxjovial]

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

Please assign I can fix this

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

[Peaostrel]

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

i can handle this quickly

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

[drips-wave]

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

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

[Terrajlz]

I'd like to work on this.

Recent work:

• Nobay Protocol: 21/21 Hardhat tests passing, 15-finding security audit, full OZ v5 migration
• DeXe Protocol: identified High-severity tx.origin vulnerability in PoolFactory (SWC-115)
• Audited contracts across Aave V3, GMX, Uniswap V3, MakerDAO, Lido, ENS, Ethena

I can deliver clean, tested code with security audit. Turnaround: 24 hours. Ready to start immediately.