Instance storage TTL bump policy (Config / NextStreamId)

[Jagadeeshftw]

Description

Summary

Within the Fluxora streaming contract, this work tightens externally visible assurances for one focused concern. Treasury operators, recipient-facing applications, and third-party auditors must be able to reason about this area using only on-chain observables and published protocol documentation—without inferring hidden rules from how the implementation happens to be structured. The scenarios captured by this issue title must therefore have crisp success semantics, crisp failure semantics, and no silent drift between stored state, user-visible errors, and emitted events. Permissionless maintenance or read paths, if involved, must have clearly documented trust impact for operators. In practical terms, treat “Instance storage TTL bump policy (Config / NextStreamId)” as the scope boundary: everything materially related to that caption should be covered by evidence (automated or documented) in this change, and anything intentionally excluded should be called out with rationale and residual risk.

Issue caption: Instance storage TTL bump policy (Config / NextStreamId)

Domain context

This repository hosts the Fluxora streaming contract on Soroban (Stellar). Streams lock funded assets in contract
storage, release entitlement over time according to schedule parameters (including cliffs), and expose explicit roles:
senders who fund and may adjust certain parameters, recipients who claim vested value, administrators who may intervene
under policy, and—where applicable—permissionless callers for maintenance reads or cleanup. Integrators (wallets,
indexers, treasury tooling) depend on coherent state transitions, emitted signals, and error behavior when inputs or
timing are invalid.

Work to complete

1. Characterize the intended protocol semantics for Instance storage TTL bump policy (Config / NextStreamId) in both success and failure cases, treating the Summary above as the authoritative scope statement.
2. Map which roles may participate, what each role must prove, and which operations must be impossible for non-authorized actors.
3. Enumerate edge cases driven by time (start, cliff, end, cancellation freeze), numeric ranges, and stream status combinations; capture expectations with tests or explicit audit exceptions.
4. Ensure externally visible behavior—persistent fields, contract errors, and emitted payloads—does not contradict documentation that integrators rely on.

Definition of done

• An independent reader can confirm Instance storage TTL bump policy (Config / NextStreamId) matches the stated intent using tests, traces, snapshots (where used), or written review notes.
• Documentation for this slice of the protocol is consistent with observable on-chain behavior after the change.
• The pull request explains verification performed, scope boundaries, and any residual assumptions or risks.

Constraints for contributors

• Describe outcomes, invariants, and evidence, not a single “right” internal design unless the issue title already names a concrete subsystem.
• Prefer observable guarantees: state transitions, balances, authorization failures, emitted events, error classifications, and documentation that integrators rely on.
• If something cannot be tested automatically, capture the gap as audit notes with explicit rationale and residual risk.

Requirements and context

• Must be secure, well-tested, and documented.
• Should be gas-conscious (Soroban budget) and easy to audit.

Suggested execution

1. Fork the repo and create a branch:

   git checkout -b feature/instance-ttl-policy

2. Implement changes
   • Contract / modules: contracts/stream/src/lib.rs
   • Comprehensive tests: contracts/stream/src/test.rs and contracts/stream/tests/integration_suite.rs
   • Documentation: docs/ (e.g. streaming.md, security.md, events.md)
   • Include Rust doc comments on public items (NatSpec-style clarity for auditors)
   • Validate security assumptions (CEI ordering, token trust model, auth paths)
3. Test and commit
   • Run cargo test in contracts/stream (and workspace if applicable)
   • Cover edge cases (overflow, TTL, paused/cancelled/completed)
   • Attach test output summary + security notes in the PR

Example commit message

docs(stream): clarify instance TTL bump semantics

Guidelines

• Aim for ≥95% coverage on touched Rust modules (cargo llvm-cov or project-standard tooling).
• Clear documentation (protocol semantics + operator runbooks where relevant)
• Timeframe: 96 hours

[drips-wave]

This issue has been added to the Stellar Wave Program and is worth 200 Points.

🧑‍💻 Interested in contributing? Apply to work on this issue on Drips Wave, earn points, and receive rewards.

Warning

Only applications submitted via the apply link above will be considered. Please do not apply by commenting on the issue or opening a PR directly.

🤠 Repo maintainers: You can manage this issue's Points and Complexity on your Maintainer Dashboard here. Please keep an eye on applications and respond quickly 💙

ℹ️ Learn more about Drips Wave

[drips-wave]

@Jagadeeshftw flavor365 could not be assigned to this issue because they have reached the maximum of 4 accepted assignments per organization in the current wave of the Stellar Wave Program.

The assignee has been removed. Please choose a different contributor.

[bigjoe-io]

@bigjoe-io has applied to work on this issue as part of the Stellar Wave Program's 3rd wave.

I am interested in contributing to this repository as the project moves into the intermediate training phase. With my experience in full-stack development, Git workflows, CI/CD, and building real-world applications, I can support the development of practical projects, improve code quality, and assist in implementing scalable solutions that enhance the learning experience.

I look forward to contributing to the next phase and helping strengthen the impact already achieved.

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

[rocknwa]

@rocknwa has applied to work on this issue as part of the Stellar Wave Program's 3rd wave.

I have solid experience with Soroban storage patterns, TTL management, and designing observable protocol guarantees. I’ll formalize the TTL bump semantics, ensure consistency across state, errors, and events, and back it with comprehensive tests and clear documentation for auditors and integrators.

Please assign this to me — I’ll ensure it’s secure, gas-conscious, and fully verifiable 👍

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

[drips-wave]

Congratulations, @bigjoe-io! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on March 30, 2026.

🧑‍💻 @bigjoe-io: 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 🌊