feat: Multi-asset donations via Stellar path payments — donate any asset, treasury receives USDC

[Anuoluwapo25]

Summary

Build multi-asset donations via Stellar path payments — a donor contributes in XLM, EURC, or any asset with DEX liquidity, and the treasury receives USDC, atomically, in a single transaction. New feature; donations today assume the donor already holds the treasury asset (server/src/services/horizon-verify.service.ts verifies a plain payment).

Background

Every donor turned away for holding "the wrong asset" is funding LearnVault never received. A European sponsor holds EURC; a Stellar-native holds XLM; a regional donor holds an anchored local-currency token. Asking each of them to go swap first loses most of them at that step.

Stellar's path_payment_strict_receive does the conversion inside the payment itself through the built-in DEX and AMM liquidity pools — no external swap, no bridge, no second transaction that can half-fail. The treasury's accounting stays denominated in one asset while donors pay in whatever they hold.

What to build

1. Path discovery

• GET /api/donate/paths?from=XLM&amount=100 → call Horizon's /paths/strict-send and /paths/strict-receive, return viable payment paths with the estimated destination amount.
• Show the donor the real rate and the price impact before they sign. A donor who discovers slippage after the fact does not donate twice.

2. Donation transaction builder

• POST /api/donate/build constructs a path_payment_strict_receive where:
  • destAsset = treasury USDC, destAmount = the exact amount the treasury should receive
  • sendMax = quoted amount plus a donor-selected slippage tolerance (default 0.5%)
  • path = the discovered intermediate assets
  • destination = the treasury account
• Return XDR for wallet signing. The server never holds donor keys.

3. Trustline preflight

• Check whether the donor holds a trustline for the asset they are sending, and whether the treasury has one for USDC.
• If the treasury lacks a trustline for an incoming path, that path must be excluded from the results rather than offered and then failing at submission.

4. Verification and accounting

• Extend horizon-verify.service.ts to recognize path payments: verify the destination amount and asset actually credited to the treasury, not the source amount. Crediting a donor for sendMax rather than what arrived is the bug this feature invites — guard it with a test.
• Record both legs (sent_asset/sent_amount and received_usdc) so impact reporting stays denominated in USDC.
• Migration server/src/db/migrations/029_multi_asset_donations.sql plus its .undo.sql adding the source-asset columns to the existing donation table.

5. Frontend

• Asset picker on the donate flow, defaulting to assets the donor actually holds (read their balances).
• Live quote: "You send ~102.3 XLM → Treasury receives 10.00 USDC", refreshing on a timer, with the slippage control visible.
• Clear failure message when no path exists, naming the asset rather than showing a generic error.

6. Tests

• Path lookup with a mocked Horizon.
• sendMax correctly reflects slippage tolerance.
• Verification credits the received USDC amount, not the sent amount.
• No-path-available and missing-trustline cases are handled and surfaced.

Acceptance criteria

• Donor can contribute in XLM or EURC and the treasury receives USDC in one transaction
• Quote with price impact is shown before signing, and slippage is configurable
• Paths requiring a trustline the treasury lacks are never offered
• Verification credits the destination amount actually received
• Donation records retain both the source asset and the received USDC
• Tests cover the slippage and verification math

Notes for contributors

• Path payments: https://developers.stellar.org/docs/learn/encyclopedia/transactions-specialized/path-payments
• Use strict_receive (not strict_send) so the treasury receives an exact, predictable amount — this keeps treasury accounting clean.
• Test on testnet where DEX liquidity is thin: assert on path structure, not on specific rates, or the suite will be flaky.

[Bidex-cmyk]

I would like to apply for issue #1056 to build multi-asset donations via Stellar path payments on learnvault. I have deep hands-on experience developing full-stack Web3 applications on Stellar, working with the Stellar SDK, Horizon APIs, TypeScript/Node.js backends, database migrations, and React UI components.

Here is my planned execution strategy:

Path Discovery & Preflight Filtering (GET /api/donate/paths):

Integrate Horizon's /paths/strict-receive to fetch viable conversion paths to treasury USDC.

Add trustline preflight verification to filter out any payment paths requiring a trustline that the treasury account currently lacks.

Calculate real-time exchange rates, estimated source amounts, and price impact for transparent donor preview.

Transaction Builder (POST /api/donate/build):

Construct path_payment_strict_receive operations where destAsset is treasury USDC and destAmount is fixed.

Apply configurable donor slippage tolerance (defaulting to 0.5%) to compute sendMax.

Return unsigned XDR for donor wallet signature without handling private keys server-side.

Backend Verification & Database Schema Migration:

Create migration 029_multi_asset_donations.sql (and .undo.sql) adding sent_asset and sent_amount columns to the donation schema.

Update horizon-verify.service.ts to inspect path payment operations, strictly verifying and crediting the actual destination USDC received rather than the source asset amount.

Frontend Donate Flow:

Build an interactive asset picker that auto-detects and defaults to assets held in the donor's wallet balance.

Implement live quote auto-refreshing with visual slippage controls and clear error states when liquidity paths do not exist.

Comprehensive Testing:

Write unit/integration tests with mocked Horizon responses covering path discovery, slippage boundary math, verification logic against received USDC, missing trustlines, and no-path scenarios.

[grantfox-oss]

🦊 GrantFox — @baedboibidex-cmyk has been assigned to this issue as part of the Third Campaign campaign!

Next steps:

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

Good luck! Track your progress on GrantFox.