Stellar contract reference completeness audit

[truthixify]

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

Context

docs/contracts/stellar.mdx describes the four Stellar Soroban contracts but was written several releases ago. Functions have been added; event shapes have changed; the deployed testnet addresses may or may not match. We don't know how far the docs have drifted.

Scope

Compare docs/contracts/stellar.mdx against the current source of truth in wraith-protocol/contracts/stellar/*. For each contract (announcer, registry, sender, wraith-names):

1. List every public entrypoint in the source.
2. Check whether it's documented in the MDX.
3. For documented entries, verify:
   • Parameter names match
   • Parameter types match (e.g., Bytes vs. BytesN<64>)
   • Return type matches
   • Event signatures match
   • Authorization requirements match
4. Verify the testnet contract addresses listed are still the current deployments.
5. Produce a "Drift report" markdown file.
6. Patch the MDX to bring it back to source-of-truth parity.

Report format

docs/audits/2026-XX-stellar-contracts.md:

# Stellar contracts docs audit — 2026-XX

## Summary
N undocumented entrypoints, M outdated signatures, K wrong addresses.

## Per-contract findings

### stealth-announcer
| Status | Symbol | Issue |
| ✅ | announce | accurate |
| ❌ | announce_batch | undocumented (added in v0.4) |
...

Constraints

• Don't gloss over informational findings (e.g., "doc says u32, source says i32 — both work but inconsistent"). Capture everything.
• Side-by-side diffs preferred over prose.

Acceptance criteria

• Drift report committed.
• docs/contracts/stellar.mdx patched.
• Follow-up "keep this current" issue filed for contracts repo (idea: a CI check that diffs docs against generated bindings — see contracts #08).

Why this matters

Wrong docs are worse than no docs. A developer who trusts a stale signature loses a debugging hour for every drift case.