feat: Path payment support for multi-asset claims

[joelpeace48-cell]

Background & current state

The payout reserve (NEW-010) holds one asset (say USDC), but some users want to receive a different asset (e.g., XLM or a local-currency anchor token). Stellar path payments can convert at claim time when DEX liquidity exists.

Goal

Let a user claim into their preferred asset via a strict-receive path payment from the reserve asset, when a viable path exists; otherwise fail clearly.

Technical design

• Backend builds a PathPaymentStrictReceive (or strict-send) from the reserve asset to the user's chosen asset, using /paths (Horizon path finding) to select a route + max slippage.
• Slippage guard (destMin/sendMax); reject if no path or slippage exceeds tolerance.

Edge cases

• No path / illiquid market → clear NO_PATH error; user can fall back to the reserve asset.
• Slippage beyond tolerance → reject (don't execute a bad swap).
• Partial liquidity → strict-receive guarantees amount or fails.
• Trustline missing for the destination asset → detect + instruct the user to add a trustline.

Task breakdown

• Path-finding integration (Horizon /paths).
• Build + submit path payment with slippage guard.
• Trustline pre-check + guidance.
• Frontend asset selector at claim.
• Integration tests against a seeded testnet path.

Acceptance criteria

• Claiming in asset B succeeds when a path from reserve asset A exists within slippage.
• Clear error when no path / missing trustline / excessive slippage.

Testing & verification

• Integration test against testnet DEX with a seeded path + a no-path case.

Out of scope

• AMM-specific routing beyond Horizon path finding.

Dependencies / related

• Builds on NEW-010 payout reserve.

References

• Path payments; Horizon path finding.

Difficulty: medium · Effort: M · stellar

[Truphile]

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

I've worked on similar Stellar payment flows involving path payments, asset conversion, trustline validation, and slippage protection. I'm familiar with Horizon path-finding, building transaction flows that fail safely when liquidity or trustlines are unavailable, and integrating these capabilities into user-facing claim workflows.

For this task, I'll implement backend path-finding and path payment execution with configurable slippage guards, validate trustlines before submission, add the frontend asset selection flow with clear fallback messaging, and provide integration tests covering successful conversions, missing trustlines, excessive slippage, and no-path scenarios.

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

[lawalajose]

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

kindly allow me work on this issue, would love to contribute

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

[Jayy4rl]

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

I would like to work on this. please assign

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

[trustosaretin]

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

I would love to work on this issue.

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

[grantfox-oss]

🦊 GrantFox — @Jayy4rl 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 #549)
2. Your PR will be reviewed by the FinesseStudioLab maintainers

Good luck! Track your progress on GrantFox.

[drips-wave]

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

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