Stellar custom-asset (issued token) send builder

[truthixify]

Labels: Stellar Wave, stellar, feature, drips, help-wanted
Tier: L (1–2 weeks)
Type: feature

Context

The Stellar chain module currently builds stealth payments for native XLM. Real Stellar usage involves issued assets: USDC (issued by Circle on Stellar), bridged tokens, and project-specific tokens. Without custom-asset support, Wraith on Stellar is a "send XLM privately" tool, not a "send anything privately" tool.

Scope

Add a builder buildSendStellarAsset to sdk/src/chains/stellar/builders.ts (create if missing). It must:

1. Accept { recipientMetaAddress, amount, asset: { code: string, issuer: string }, sourceAccount, options? }.
2. Verify the recipient stealth address has a trustline for the asset, OR include trustline-establishment as part of the transaction:
   • Option A: Build a single tx with ChangeTrust + Payment ops, signed by both source and stealth account.
   • Option B: Use a fee-bump pattern where source funds the stealth account first, then pays.
   • Picking the right model is part of the issue; argue both in the PR.
3. Build the Stellar transaction with both the payment and the announcement (Soroban call), atomically.
4. Return the same { transaction, stealthAddress, ephemeralPubKey, viewTag } shape the existing XLM builder uses, so consumers can stay consistent.

Open design questions

• Trustlines cost reserve. Who pays it? Should the stealth address need to be pre-funded to hold a trustline before receiving?
• Asset code validation — Stellar codes are 4 or 12 characters. Validate before building.
• Issuer address validation — must be a valid G... strkey.
• Authorization-required assets — if the issuer requires authorization (authRequired), the stealth address can't receive. Detect and error out cleanly.

Acceptance criteria

• buildSendStellarAsset implemented.
• Unit tests covering: trustline present, trustline absent (auto-create or error), invalid asset code, invalid issuer, auth-required asset rejection.
• Integration test against testnet with a real testnet-issued asset (use a token deployed for this purpose; document the issuer).
• Demo follow-up issue filed for adding asset selection in the UI.
• Spectre follow-up issue filed for connector-level support.
• Docs updated (docs/sdk/chains/stellar.mdx) with examples.

Why this matters

USDC on Stellar is the closest thing to "money" most users care about. Without it, Stellar Wraith is a demo. With it, Wraith is a payments product.

Files

• sdk/src/chains/stellar/builders.ts (likely create new)
• sdk/src/chains/evm/builders.ts::buildSendERC20 (reference for the EVM equivalent)
• Stellar SDK trustline docs: https://developers.stellar.org/docs/learn/fundamentals/transactions/list-of-operations#change-trust

[Euvouserdoutor]

Hi! I can take this task quickly and deliver a focused PR. Before I start, can you confirm: (1) budget/reward, (2) expected timeline, and (3) payout method (PayPal preferred)? I can start right after your approval.

[mordabdul1]

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

Hi maintainer, I would like to work on this issue

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

[bbkenny]

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

Hi! I'm a TypeScript developer with experience writing custom SDK wrappers for Stellar. I notice the SDK currently only builds stealth payments for native XLM and lacks support for custom issued assets like USDC. I've integrated Circle's USDC Stellar assets into other developer libraries. My approach will be to implement buildSendStellarAsset in the SDK with complete test coverage. Ready to build!

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

[drips-wave]

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

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