Stellar troubleshooting & error reference

[truthixify]

Labels: Stellar Wave, stellar, docs, drips, help-wanted, good-first-issue
Tier: M (2–4 days)
Type: writing

Context

Stellar-specific errors are some of the most opaque in the entire stack: account not found (which account?), tx_bad_seq, op_underfunded for trustlines, Soroban-specific HostError: contract trapped (Code: ...), and friendbot rate limits. A new user hits any of these and Googles in vain because Wraith's error messages don't tell them where to look.

We want one page with every common error → root cause → fix.

Scope

Write docs/guides/stellar-troubleshooting.mdx. Each error gets:

1. The exact string Wraith / Freighter / Horizon / Soroban surfaces.
2. What it means in plain language.
3. The most common cause.
4. The fix, including a code snippet if applicable.

Categories to cover

• Account / balance: account not found, op_underfunded, base reserve below threshold, low balance for fee.
• Network: 429 from friendbot, 502 from Horizon, Soroban RPC retention exceeded.
• Signing: Freighter not installed, network mismatch (testnet vs. mainnet), user rejected sign.
• Stealth-address-specific: derived address matches recipient's known address (shouldn't happen but check), zero-balance scan returning matches (means key derivation is wrong), name resolution returning null.
• Soroban contract errors: Contract trapped, missing trustline, expired auth signature, replay-protection rejection.

Style

• Use Mintlify's <Accordion> to keep the page navigable.
• Each entry's heading is the literal error string.
• "Last verified" date at the top of the page.

Acceptance criteria

• At least 20 error entries covering the above categories.
• Page committed at docs/guides/stellar-troubleshooting.mdx.
• Linked from docs/guides/stellar-quickstart.mdx (#01) and the SDK Stellar page.
• Each fix is verified — actually reproduce the error in a sandbox and confirm the fix works.

Why good-first-issue

The work is largely catalog-and-write. No architectural decisions. A new contributor can pick a category, work through the errors, and ship an incremental PR per category.