Multi-sig / social recovery for `wraith-names` ownership

[truthixify]

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

Context

wraith-names ownership is currently tied to a single account. If a user loses access to that account (lost key, compromised wallet, custodian failure), their .wraith name is permanently lost — and a third party could potentially register a similar name and impersonate them.

We need a recovery path that doesn't compromise the unlinkability of stealth payments.

Scope

Add to wraith-names:

1. set_guardians(name, guardians: Vec<Address>, threshold: u32):
   • The current owner specifies up to N guardian accounts (recommend N ≤ 7) and a recovery threshold (threshold of guardians.len()).
   • The guardians and threshold are stored alongside the name's meta-address.
2. propose_recovery(name, new_owner, new_meta_address):
   • Any guardian may propose.
   • Stores a recovery proposal with a delay window (e.g., 100,000 ledgers ≈ 5 days).
3. approve_recovery(name):
   • Each guardian signs.
   • Once threshold reached AND delay window elapsed, the name's ownership flips to new_owner and meta-address updates.
4. cancel_recovery(name):
   • The current owner (if still in control) can veto any pending recovery within the delay window.

Design tensions

• The delay window protects against a malicious guardian quorum.
• The guardians' identities are public (on-chain), but this is acceptable for the name (which is already public) — it's the stealth payments that need privacy.
• A user can use a Wraith TEE agent as one guardian, providing high-availability recovery without a single human dependency.

Open questions

• Can guardians be other .wraith names rather than Stellar accounts? (Probably yes — adds composability but increases verification cost.)
• What's the gas cost ceiling for approve_recovery when threshold is high?

Acceptance criteria

• Recovery primitives implemented with full tests.
• Adversarial tests: insufficient threshold, expired delay, post-cancel approval, double-recovery, recovery after voluntary release.
• Audit report following the recovery-flow design — coordinate with the wraith-names full audit.
• Docs follow-up issue filed for the user-facing recovery UX.

Why this matters

Losing a name forever is the kind of UX failure that gets posted to Crypto Twitter with screenshots. Even one such event is enough to chill adoption of .wraith as a permanent identity primitive. Social recovery turns "lost name = lost identity" into "lost name = inconvenient five-day reset."

[Dennis-Ritchie1]

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

Hi, I'd like to apply for this issue.

I'm a full stack developer (3–5 years) comfortable across the entire stack — from database schema and API design to React/TypeScript frontend and deployment. I regularly work on features that touch both layers, so I'm used to tracing bugs that cross the frontend/backend boundary.

For this specific issue, I plan to: [e.g. audit the API response shape, fix the mismatch on the server side, then update the frontend to handle the corrected structure and add a test for both layers]. I've worked with [technologies mentioned in the issue].

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

[drips-wave]

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

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

[truthixify]

Resolved by #32 (merged into develop).