Skip to content

Add error code reference and cross-link troubleshooting guide - #136

Merged
truthixify merged 1 commit into
wraith-protocol:developfrom
Mathew2k-hash:feat/error-codes-reference
Aug 29, 2026
Merged

Add error code reference and cross-link troubleshooting guide#136
truthixify merged 1 commit into
wraith-protocol:developfrom
Mathew2k-hash:feat/error-codes-reference

Conversation

@Mathew2k-hash

Copy link
Copy Markdown
Contributor

Add normative error-code reference and cross-link troubleshooting guide

Fixes the "support keeps re-typing SDK errors in Discord" problem by giving every error a
stable, linkable anchor.

What's new

reference/error-codes.mdx — a new normative reference page with one table per error source:

  • Soroban contract errors (HostError: Error(Contract, #N)) for stealth-registry,
    stealth-sender, and wraith-names — symbolic name, meaning, common cause, and fix for every
    variant
  • SDK Agent Client errors — err.message patterns thrown by Wraith / WraithAgent
  • SDK Stellar Chain Primitives errors — throw-sites in @wraith-protocol/sdk/chains/stellar
    (meta-address decoding, key derivation, ECDH edge cases)
  • CLI errors — all five WRAITH_* exit codes
  • Soroban RPC / indexer errors — retention_window_exceeded, start_ledger_too_old,
    invalid_cursor, contract_not_found, ledger_not_found
  • Quick-reference cross-index mapping all 20 stellar-troubleshooting.mdx entries to the
    canonical row in this table

Cross-links added to guides/stellar-troubleshooting.mdx

Top-of-file callout pointing to the new reference, plus inline Reference: lines at sections 7,
13–20 linking directly to the matching table anchor.

Nav

reference/error-codes added as the first entry in the Reference group in docs.json.

Auto-generation note

The page documents a generate:error-codes script pattern (mirroring
scripts/generate-stellar-reference.ts) for keeping contract error tables in sync from
TypeScript bindings once the script is implemented.

Testing

pnpm run check:snippets passes — 60 MDX files, 572 snippets, 0 failures. The new page has no
code fences so it adds no new CI surface.
closes #121

@drips-wave

drips-wave Bot commented Aug 25, 2026

Copy link
Copy Markdown

@Mathew2k-hash 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

Thanks @Mathew2k-hash. #135 (nav cleanup) merged and restructured docs.json, so that is now your only conflict. reference/error-codes.mdx and the troubleshooting cross-links are clean.

git fetch origin
git rebase origin/develop

On the conflict, take the new nav tree from develop and re-add your Reference entry into it rather than keeping your old version of the file.

- Add reference/error-codes.mdx: normative flat tables for Soroban
  contract errors (#N codes), SDK error messages, CLI error codes, and
  Soroban RPC/indexer errors. Each row has a stable anchor for Discord
  and support citations.
- Add cross-links from every relevant section in
  guides/stellar-troubleshooting.mdx back to the matching table row.
- Add reference/error-codes to the Reference nav group in docs.json.
- Include auto-generation note describing a generate:error-codes script
  pattern mirroring scripts/generate-stellar-reference.ts.
@truthixify
truthixify force-pushed the feat/error-codes-reference branch from 5f5039a to 3cfb155 Compare August 29, 2026 06:19
@truthixify

Copy link
Copy Markdown
Contributor

I have rebased this onto develop and force-pushed to your branch, since the conflict was purely mechanical and you should not have to burn a round trip on it. Your commits are unchanged, only replayed.

The only conflict was the Reference group in docs.json. develop had grown to six pages while this was open, so I took that list and inserted reference/error-codes into it rather than taking either side wholesale.

Verified locally before pushing: check:nav-coverage passes (68 pages, 68 nav entries) and check:snippets passes (600 snippets).

Nothing needed from you unless you disagree with where the nav entry landed. If you have a local copy of this branch, git fetch && git reset --hard origin/feat/error-codes-reference before you continue.

@truthixify
truthixify merged commit c40580e into wraith-protocol:develop Aug 29, 2026
3 checks passed
@truthixify

Copy link
Copy Markdown
Contributor

Merged. Thanks for your patience on the rebase @Mathew2k-hash. Pairing the normative table with cross-links back into the troubleshooting guide is what makes both pages more useful rather than redundant.

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.

Error code reference (tabular + SDK / CLI / indexer coverage)

2 participants