Skip to content

docs: add Stellar payment links guide#58

Open
baedboibidex-cmyk wants to merge 3 commits into
wraith-protocol:developfrom
baedboibidex-cmyk:docs/stellar-payment-links
Open

docs: add Stellar payment links guide#58
baedboibidex-cmyk wants to merge 3 commits into
wraith-protocol:developfrom
baedboibidex-cmyk:docs/stellar-payment-links

Conversation

@baedboibidex-cmyk

Copy link
Copy Markdown
Contributor

docs: Stellar payment links guide (#37)

Summary

Adds guides/stellar-payment-links.mdx — a complete guide for generating, signing, and receiving Wraith stealth payment links on Stellar.

What changed

  • New page guides/stellar-payment-links.mdx covering:
    • URL schema (to, amount, asset, memo, exp, sig params) with a working example URL
    • HMAC-SHA256 tamper-protection signature — canonical payload construction, constant-time verification, and an Express route example
    • Deep-linking into native apps (React Native / Expo custom scheme + universal links)
    • QR code generation with qrcode — file output and in-memory data URL for <img> tags
    • Expiry handling — server-side rejection and client-side countdown, with a table of recommended expiry windows by use case
    • StellarPaymentLink.tsx reference implementation walkthrough — QR display, countdown timer, and payment confirmation polling via the Wraith agent
    • Webhook receiver — signature verification, event parsing, and payload shape for payment.confirmed
  • docs.json — page registered under Guides → Operations
  • sdk/chains/stellar.mdx — See Also cross-link added
  • guides/privacy-best-practices.mdx — See Also cross-link added

Acceptance criteria

  • Page committed
  • Working example URL (https://pay.example.com/pay?to=alice.wraith&amount=10&asset=XLM&memo=INV-2024-001&exp=1735689600&sig=...)
  • Reference implementation code excerpts (StellarPaymentLink.tsx component, Next.js invoice page usage)
  • Linked from SDK Stellar page (See Also)
  • StellarPaymentLink.tsx component documented inline (demo directory not present in repo; component code included as excerpts per acceptance criteria)

Design decisions

  • Signature covers a canonical alphabetically-sorted query string (excluding sig itself) to make signing deterministic regardless of URL parameter order.
  • crypto.timingSafeEqual used in both link verification and webhook verification to prevent timing attacks.
  • Polling vs. webhooks: both patterns documented — polling in the React component for SPAs, webhooks for server-side fulfillment. Using both simultaneously is safe (idempotent on your end).
  • exp is optional — permanent links are valid for recurring billing; short-lived links for point-of-sale.

Notes

  • demo/src/components/StellarPaymentLink.tsx listed in scope was not present as an existing file in the repo (no demo/ directory on develop). The component is documented as a complete code excerpt inside the guide, satisfying the "reference implementation code excerpts" acceptance criterion.

Closes #37

- Add guides/stellar-payment-links.mdx covering URL schema, optional
  HMAC-SHA256 tamper-protection signature, deep-linking into native
  apps, QR code generation, expiry handling, StellarPaymentLink
  reference implementation walkthrough, and webhook receiver patterns
- Register page in docs.json under Guides > Operations
- Add cross-link from sdk/chains/stellar.mdx See Also section
- Add cross-link from guides/privacy-best-practices.mdx See Also section

Closes wraith-protocol#37
@baedboibidex-cmyk baedboibidex-cmyk force-pushed the docs/stellar-payment-links branch from b141e8e to a53fe39 Compare June 25, 2026 15:50
@drips-wave

drips-wave Bot commented Jun 25, 2026

Copy link
Copy Markdown

@baedboibidex-cmyk Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

@truthixify

Copy link
Copy Markdown
Contributor

Now conflicts on docs.json and sdk/chains/stellar.mdx because #57 just landed. Same cascade as your other PRs:

git fetch origin
git rebase origin/develop
git push --force-with-lease

Content is clean; just keep both sides of the conflicts in docs.json and sdk/chains/stellar.mdx.

@baedboibidex-cmyk

Copy link
Copy Markdown
Contributor Author

Now conflicts on docs.json and sdk/chains/stellar.mdx because #57 just landed. Same cascade as your other PRs:

git fetch origin
git rebase origin/develop
git push --force-with-lease

Content is clean; just keep both sides of the conflicts in docs.json and sdk/chains/stellar.mdx.

Conflicts resolved.

@truthixify

Copy link
Copy Markdown
Contributor

Sorry @baedboibidex-cmyk#53 just landed which means the same docs.json cascade hits again. One more rebase:

git fetch origin
git rebase origin/develop
# docs.json: keep both sides (the merge marker will be in the same section)
# privacy-best-practices.mdx: keep both your addition and the new one from #53
git push --force-with-lease

Your remaining PRs (#55, #58, #63) all need this same step. After this round they'll all merge in sequence.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Stellar payment-link / invoicing guide

2 participants