fix(stellar): fix #58 storage rent audit and persistent migration

[fhayvy]

Closes #58

PR Description

Soroban contract instances have strict storage capacity limits (64 KB for the entire instance). In the previous implementation of our contracts, user registration data, names, and reverse-lookup mappings in stealth-registry and wraith-names were stored directly in instance storage. Under higher user volumes, this design leads to rapid contract bloat, leading to instances exceeding limits and rendering contracts permanently un-upgradable or unusable. Furthermore, lack of active time-to-live (TTL) management meant that these vital entries risk accidental expiration and archival, necessitating expensive and complex restoration processes.

This PR conducts a comprehensive storage rent audit and performing architectural migrations.

Solutions & Improvements

1. Migration to Persistent Storage:

   • Moved all user registry entries and name mappings from instance storage to persistent storage.
   • Refactored stealth-registry and wraith-names contracts to completely eliminate user data storage on instances, keeping only minimal operational variables in instances if any, thus avoiding the 64 KB limit entirely.

2. Conditional Active TTL Management:

   • Implemented a proactive and conditional TTL extension strategy using Soroban's extend_ttl host functions.
   • Set the TTL_THRESHOLD to 17,280 ledgers (~1 day) and TTL_EXTEND_TO to 518,400 ledgers (~30 days).
   • TTL extensions are triggered on every write, update, and resolve (read) operation. Crucially, the extension is conditional (checked automatically by the host env under the hood), meaning if the entry has more than 1 day remaining, the operation is a cheap no-op, avoiding unnecessary gas fees and transaction overhead while guaranteeing that active entries are never archived.
   • Bumps the contract instance and code TTL along with the data keys on active usage to secure the lifecycles of all deployed contracts.

3. Audit Documentation:

   • Authored the comprehensive storage rent audit document in stellar/STORAGE_RENT.md. This contains complete storage write enumerations (tier, creator, renewal responsibilities), cost models calculated across three scale tiers (10k, 100k, and 1M entries) using current mainnet fees, and strategic recommendations for Soroban state management.

4. Enhanced Test Coverage:

   • Added robust integration and lifecycle tests in stealth-sender covering initialization, token integration, transfer triggers, and TTL extension assertions.

Why It Matters

These improvements resolve the issue by ensuring state sustainability at scale. With this architecture, the contracts can support millions of concurrent users without hitting memory limits, and the active names/registries will remain permanently live via permissionless read/write extensions.

Changed

The following files were modified:

• stellar/stealth-registry/src/lib.rs: Migrated all registry mapping storage operations from instance to persistent storage and integrated conditional TTL extension checks on registrations and lookups.
• stellar/wraith-names/src/lib.rs: Swapped instance storage for persistent storage for all name registrations and reverse lookups, and implemented extend_ttls helper to manage data keys and contract instance lifecycles.
• stellar/stealth-sender/src/lib.rs: Added contract testing covering initialization, batch sends, and fast-forward ledger simulation verifying proactive TTL extensions on the sender contract instance.
• stellar/STORAGE_RENT.md: Created the audit report including contract storage write enumerations, cost formulas, and recommendations.

Testing

Unit and integration tests were executed successfully within the stellar workspace to verify the persistence migration and correct TTL bumping behaviour.

[drips-wave]

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

Conflicts in stealth-registry/src/lib.rs, stealth-sender/src/lib.rs, wraith-names/src/lib.rs. All three contracts have moved on develop. Quick rebase:

git fetch origin
git rebase origin/develop
git push --force-with-lease

STORAGE_RENT.md lands cleanly. The TTL/storage-tier code changes need to be re-applied on top of develop's current contracts.

[fhayvy]

@truthixify kindly merge now conflict resolved

[truthixify]

Clean merge. Persistent-storage migration for stealth-registry, stealth-sender, and wraith-names is exactly the storage-rent fix we needed. STORAGE_RENT.md is a great writeup. Thanks @fhayvy.