Soroban storage TTL automation for `wraith-names` entries

[truthixify]

Labels: Stellar Wave, stellar, feature, tooling, drips, help-wanted
Tier: M (2–4 days)
Type: feature

Context

Soroban storage entries have a time-to-live (TTL) in ledgers. When an entry's TTL expires, it's archived and re-loading it requires paying restoration fees. For wraith-names, this means a .wraith name registration can "expire" if nobody touches it for long enough — and the user might not notice until someone else tries to resolve and gets nothing back.

We have two options: extend TTLs aggressively (costs more, but invisibly to the user), or build automation that lets anyone extend a name's TTL on its owner's behalf (decentralized care-taking).

This issue is about the second.

Scope

1. Add a function extend_name_ttl(name: String, extend_to_ledger: u32) -> bool to wraith-names:
   • Anyone may call. No auth.
   • Extends the storage TTL of the name entry (and the associated reverse-lookup entry) up to (but not past) extend_to_ledger.
   • Capped at the Soroban maximum extension allowed per call.
   • Idempotent: calling twice in the same ledger is a no-op for the second call.
2. Build a Stellar-side keeper bot at contracts/stellar/scripts/keeper/:
   • Reads all registered names from the contract storage.
   • For each, checks TTL remaining.
   • If TTL < 1000 ledgers (≈ 80 minutes), calls extend_name_ttl to push it out by 1 month.
   • Costs are paid by the keeper account — propose a sustainable funding model (a small protocol fee tip, or a foundation grant).
3. Document the keeper bot in the Spectre repo so we can run it in production.

Open design questions

• Should extensions emit an event so off-chain observers can see "name X extended by Y"? Probably yes for transparency.
• Should we cap how far in the future a single extension can push? Argue.
• Trade-off: cheap extension makes squatting effectively permanent. Is that acceptable for the namespace? (Yes — .wraith is meant to be permanent identity. But state the trade explicitly.)

Acceptance criteria

• extend_name_ttl implemented and tested.
• Keeper bot script with documented run command.
• Cost model documented: how much XLM does keeping 1000 names alive for a year cost?
• CI: a "names are healthy" test against the live testnet (separate non-blocking job).

Why this matters

If user-registered names silently archive and become resolvable-only-after-pay-to-restore, we have a UX failure. This is an invisibility problem — fixing it now avoids a class of support tickets later.

Resources

• Soroban storage TTL semantics: https://developers.stellar.org/docs/build/guides/contract-development/storage/state-archival

[wolfyres]

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

Could you please assign me this issue, thanks.

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

[eleven-smg]

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

I would like to work on this issue
I can start working now

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

[BigJohn-dev]

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

I’m interested in solving meaningful engineering problems and improving real-world software. I have experience with backend development, OOP, APIs, Git workflows, and building maintainable full-stack applications.

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

[drips-wave]

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

🧑‍💻 @BigJohn-dev: 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 🌊