Stuck-funds rescue mechanism for stealth-sender FIXED

[Mitch5000]

Title
Stuck-funds rescue mechanism for stealth-sender

Description
Background
Adds a comprehensive recovery mechanism and mainnet readiness documentation for the Wraith Protocol stealth sender contracts on Stellar (Soroban). This PR addresses #3 - Stealth Sender Atomicity & Rescue Mechanism and #20 - Mainnet Readiness.

What This PR Does

1. Rescue Tool (rescue-stealth-funds.ts)
   Provides a recovery mechanism for the edge case where funds land at a stealth address without a matching on-chain announcement. Scenarios include:

Operator error (UI sends transfer without calling stealth-sender::send)
Direct external sends to a stealth address
Theoretical chain reorganizations
Scanner indexer failures
Key trust properties:

Sender must have the ephemeral private key (funds are cryptographically unrecoverable without it)
Tool never requests the sender's long-term spending key
Recovery only restores findability via on-chain announcement; original tx hash differs
2. Atomicity Audit (POSTMORTEMS.md)
Complete postmortem analysis verifying that stealth-sender::send and stealth-sender::batch_send are atomic under the Soroban execution model:

✅ Finding: No atomicity gap exists — transfer and announcement succeed or both fail together
Explains how Soroban's cross-contract invocation model guarantees atomicity
Analyzes edge cases: malicious token contracts, announcer bugs, wrong addresses, batch failures
3. Mainnet Readiness Checklist (MAINNET_READINESS.md)
Pre-deployment verification guide covering:

Contract audit status (atomicity verified)
Deployment checklist
Pre-mainnet verification steps
Monitoring & incident response procedures
4. Test Coverage (rescue-stealth-funds.test.ts)
Comprehensive test suite (188 lines) for the rescue tool, validating:

Successful fund recovery scenarios
Balance verification
Error handling and edge cases
Integration with ECDH key derivation
Files Added
✨ rescue-stealth-funds.ts (516 lines) — Main rescue implementation
✨ rescue-stealth-funds.test.ts (188 lines) — Test suite
✨ README.md — Rescue tool documentation with scenarios & trust assumptions
✨ MAINNET_READINESS.md — Mainnet deployment readiness checklist
✨ POSTMORTEMS.md — Atomicity audit findings
Key Findings
Atomicity Verified: stealth-sender::send is safe; no code changes required
Rescue Path Documented: Recovery mechanism ready for edge-case scenarios
Stellar Execution Model: All sub-contract calls (token transfer + announcement) are atomic within a single Soroban invocation
No Partial State: Any failure in transfer or announcement triggers full rollback

Closes #22

[drips-wave]

@Mitch5000 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]

This is exactly the right shape for this issue — atomicity confirmed via PM-001, rescue tool built defensively (sender's spending key never touched, refuses to operate if the stealth address has already moved funds), CLI documented with the trust-model warning right at the top.

One small note: there's a separate PR (#31) coming for issue #21 that will put the canonical mainnet readiness doc at stellar/MAINNET_READINESS.md. Your root-level version is fine as a quick reference but we may consolidate later. Not blocking.

Thanks @Mitch5000 — good defensive engineering on the "never request spending key" constraint.