React Native compatibility audit + fixes

[truthixify]

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

Context

The Wraith whitepaper roadmap includes a mobile app. That app will use React Native (Expo, almost certainly). RN has notoriously sharp edges for crypto libraries: no Buffer by default, no crypto.getRandomValues without polyfills, Hermes engine has subtly different BigInt semantics in older versions, and atob/btoa aren't always there. Right now the SDK is web-only — nobody has tried it on RN.

We need a structured audit + the polyfills needed to ship.

Scope

1. Spin up a fresh Expo app under examples/react-native-stellar/ (Expo SDK 51+ with the new architecture).
2. Try to use @wraith-protocol/sdk/chains/stellar end-to-end:
   • deriveStealthKeys from a sample signature
   • generateStealthAddress
   • scanAnnouncements over a small fixture
3. For each failure, document:
   • Root cause (missing global, type mismatch, native module missing, etc.)
   • Whether the fix belongs in:
     • The SDK itself (we should be cross-platform out of the box)
     • A @wraith-protocol/sdk-rn-polyfills companion package
     • The consumer's app entry point (with documentation)
4. Implement the fixes.
5. Document the integration in docs/guides/react-native-setup.mdx.

Specific things to expect

• crypto.getRandomValues polyfill via expo-crypto or react-native-get-random-values.
• Buffer polyfill via buffer if anything uses it.
• TextEncoder / TextDecoder polyfills (Hermes has them since v0.74).
• atob/btoa polyfills.
• BigInt literal compatibility on Hermes — should be fine on recent versions but verify.
• Metro bundler config that resolves the SDK's subpath exports correctly.

Acceptance criteria

• examples/react-native-stellar/ works end-to-end on iOS Simulator and Android emulator.
• All necessary polyfills documented.
• Setup guide in docs.
• If a companion polyfill package is needed, scaffolded and published as @wraith-protocol/sdk-rn-polyfills.
• CI: smoke test that runs the example through Expo's CLI to confirm it builds.

Why this matters

Mobile is the Stellar use case for most LATAM and Asia-Pacific users. Without RN compatibility, Wraith on Stellar is desktop-only — a massive addressable-market cut.

[Buchi-Einstein]

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

Hi maintainer! i can implement this effectively

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

[drips-wave]

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

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