feat(contracts): add storage bump helper for recipient position looku…

[timiturn3r]

Description

Soroban persistent storage entries require active TTL bumps to prevent archival into dead storage. In long-term streaming setups (e.g. 4-year vesting schedules), stream recipients and secondary position keys may remain dormant without invoking state-modifying actions like withdrawals for extended periods.

This PR adds the bump_position_ttl(env: &Env, key: &StorageKey) storage helper in contracts/stream_contract/src/storage.rs and integrates it into try_load_stream, ensuring that every read-only query (such as querying stream metadata, claimable balances, vesting schedules, or completion status) automatically extends the entry's persistent TTL to the contract maximum (518,400 ledgers) whenever remaining TTL falls below the renewal threshold (120,960 ledgers). It also adds a public bump_stream_ttl entrypoint to StreamContract for explicit on-chain renewals.

Type of Change

• 🐛 Bug fix (non-breaking change which fixes an issue)
• ✨ New feature (non-breaking change which adds functionality)
• 💥 Breaking change (fix or feature that would cause existing functionality to not work as expected)
• 📚 Documentation update
• 🔧 Refactoring (no functional changes)
• ⚡ Performance improvement
• 🧪 Test addition or update

Related Issues

Closes #1519

Changes Made

• Storage Layer (contracts/stream_contract/src/storage.rs):
  • Implemented bump_position_ttl(env: &Env, key: &StorageKey) to extend persistent storage TTL to PERSISTENT_BUMP_AMOUNT (518,400 ledgers) with PERSISTENT_LIFETIME_THRESHOLD (120,960 ledgers).
  • Integrated bump_position_ttl into try_load_stream so any read-only query automatically extends TTL for existing stream positions.
  • Refactored save_stream to use bump_position_ttl(env, &key) as the single source of truth for persistent stream TTL renewals.
• Type Definitions (contracts/stream_contract/src/types.rs):
  • Added pub type StorageKey = DataKey; type alias for storage keys.
  • Standardized Stream struct fields with the 16-field persistent storage schema.
• Contract Interface (contracts/stream_contract/src/lib.rs):
  • Added public entrypoint bump_stream_ttl(env: Env, stream_id: u64) -> Result<(), StreamError> allowing callers to explicitly bump a stream's persistent TTL.
  • Exported contract submodules (errors, events, storage, types) and imported bump_position_ttl.
• Error Surface (contracts/stream_contract/src/errors.rs):
  • Added missing error variants ArithmeticOverflow = 34, StreamStillActive = 35, StreamNotActive = 36.
• Tests (contracts/stream_contract/src/test.rs):
  • Added test_querying_stream_metadata_automatically_extends_ttl with mock ledger increments (400,000 ledgers) verifying get_stream restores TTL to contract max.
  • Added test_all_read_only_position_queries_extend_ttl verifying TTL extensions across get_claimable_amount, get_vesting_schedule, get_projected_end_time, and is_stream_completed.
  • Added test_bump_position_ttl_helper_directly verifying direct helper execution, non-existent key safety, and the bump_stream_ttl contract entrypoint.

Testing

Test Coverage

• Unit tests added/updated
• Integration tests added/updated
• Manual testing performed

Test Steps

1. Run cargo test in contracts/stream_contract to execute all 226 contract unit, integration, and property tests:

   cargo test