`@wraith-protocol/sdk-react` companion package with hooks

[truthixify]

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

Context

Every React integrator of Wraith ends up writing the same useState/useEffect glue: derive keys when wallet connects, cache them, scan periodically, manage in-flight tx state, etc. The demo has 600+ lines of this in StellarReceive.tsx. We should ship the glue as a React hooks package.

Scope

Create a new workspace package packages/sdk-react/ published as @wraith-protocol/sdk-react. Initial Stellar-focused hooks:

1. useStellarStealthKeys(signature: HexString | null)

   • Returns { keys, isReady, error }.
   • Derives once and memoizes; only re-derives when the signature changes.

2. useStellarAnnouncementScan(keys, options?)

   • Returns { matches, isScanning, lastScanAt, error, refetch, cursor }.
   • Auto-polls every options.intervalMs (default 60s).
   • Uses streaming scan (#09) under the hood for memory efficiency.
   • Respects React Strict Mode (no double-fire).

3. useStellarSendStealthPayment()

   • Returns { send, status, txHash, stealthAddress, error, reset }.
   • send(args) returns a Promise + updates internal state for declarative UI.

4. useStellarName(name: string)

   • Returns { metaAddress, isResolving, error }.
   • Debounces input by 300ms.
   • Caches resolutions in module memory.

5. useStellarBalance(address, options?)

   • Returns { xlm, assets, isLoading, error, refetch }.
   • Auto-polls every options.intervalMs (default 30s).

Constraints

• React 18+ only. Use useSyncExternalStore where appropriate.
• No global state library required — hooks must be standalone.
• Strict-mode safe (no side effects in render).
• Work in React Native (after #15 lands).
• Bundle size for a Stellar-only consumer ≤ 5 KB gzipped over the underlying SDK.

Acceptance criteria

• Package scaffolded with the workspace setup matching the SDK.
• Five hooks implemented with full unit tests (Vitest + @testing-library/react).
• examples/react-stellar-app/ consuming the hooks end-to-end.
• Demo refactor follow-up issue filed for replacing the existing glue with these hooks.

Why this matters

Every minute an integrator spends on glue code is a minute they're not spending on their product. The hooks library is the single highest DX leverage point in the entire SDK roadmap.

[Zarmaijemimah]

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

Hi I'll love to work on this issue please kindly assign thank you.

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

[drips-wave]

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

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