Document the storage model and DataKey TTL classification in a STORAGE.md reference

[1nonlypiece]

Document the router storage and TTL model

Description

src/lib.rs defines twelve DataKey variants with subtle semantics — keyed per-pair slots vs global singletons, default sentinels (i128::MAX for max-amount/liquidity, 0 for min-amount, false for pair/paused), and an instance-vs-persistent split the doc comment only gestures at. There is no single reference an integrator or auditor can read to understand what is stored, where, with what default, and how it ages out. This issue produces an authoritative storage reference document.

Requirements and context

• Repository scope: StableRoute-Org/Stableroute-contracts only.
• Create docs/storage.md (and link from README.md) with a table per DataKey: key shape, value type, storage tier, default-when-absent, the entrypoints that read/write it, and TTL class.
• Document the sentinel conventions explicitly (i128::MAX = unbounded, absent bool = false, etc.).
• Note the archival/TTL risk and reference any TTL-bumping work as the mitigation.
• No production code change beyond optionally tightening /// comments on DataKey variants.

Suggested execution

• Fork the repo and create a branch
• git checkout -b docs/contracts-44-storage-reference
• Implement changes
  • Write code in: src/lib.rs — optionally align /// comments on DataKey variants (no behavior change).
  • Write comprehensive tests in: src/lib.rs #[cfg(test)] mod test — no new tests required; ensure existing ones pass.
  • Add documentation: docs/storage.md plus a README link.
  • Include NatSpec-style doc comments (///) consistency across all DataKey variants.
  • Validate security assumptions: documented defaults exactly match the unwrap_or values in the source.
• Test and commit

Test and commit

• Run cargo fmt --all -- --check, cargo build, and cargo test.
• Cover edge cases and failure paths: verify each DataKey variant appears once with the correct documented default.
• Include the full cargo test output and a short security notes section in the PR description (threat model + mitigations).

Example commit message

docs: add authoritative storage model and DataKey TTL reference

Guidelines

• Minimum 95 percent test coverage for impacted modules.
• Clear, reviewer-focused documentation.
• Timeframe: 96 hours.

Community & contribution rewards

• 💬 Join the StableRoute community on Discord for questions, reviews, and faster merges: https://discord.gg/37aCpusvx
• ⭐ This is a GrantFox OSS / Official Campaign task and may be rewarded. When your PR is merged you'll be prompted to rate the project — if this issue and the maintainers helped you ship, we'd be grateful for a 5-star rating. Clear questions in Discord and tidy, well-tested PRs are the fastest path to a merge and a reward.

[1nonlypiece]

Hi Maintainers 👋,

I’d like to apply for this issue.

I have hands-on experience with Next.js frontend development as well as Stellar smart contracts using Rust (Soroban). I’m comfortable working with Figma designs, integrating APIs/wallets on the frontend, and implementing, testing, and optimizing smart contracts on Stellar.

I can follow the project guidelines, communicate progress clearly, and deliver clean, well-tested code within the expected timeline.

Looking forward to contributing to the project 🚀
Thanks!

[grantfox-oss]

🦊 GrantFox — @1nonlypiece has been assigned to this issue as part of the Official Campaign campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #42)
2. Your PR will be reviewed by the StableRoute-Org maintainers

Good luck! Track your progress on GrantFox.