feat(contract): use LOW_WATERMARK threshold for TTL bumps

[Adjutant500]

Here's a PR description you can paste in:

──────────────────────────────────────────────────────────────────────────────────────────────────────────────────

feat(contract): use LOW_WATERMARK threshold for TTL bumps

What

Replaces every extend_ttl(&key, MAX_TTL, MAX_TTL) call in both Soroban contracts with the threshold form
extend_ttl(&key, LOW_WATERMARK, MAX_TTL).

Two new constants are added:

┌─────────────────────────────────────┬───────────────────────┬──────────────────────┐
│ Contract │ MAX_TTL │ LOW_WATERMARK │
├─────────────────────────────────────┼───────────────────────┼──────────────────────┤
│ Registry (contract/src/lib.rs) │ 3_110_400 (~180 days) │ 1_555_200 (~90 days) │
├─────────────────────────────────────┼───────────────────────┼──────────────────────┤
│ Agents (contract/agents/src/lib.rs) │ 100_000_000 │ 50_000_000 │
└─────────────────────────────────────┴───────────────────────┴──────────────────────┘

Both watermarks are set at ½ × MAX_TTL.

Why

The previous unconditional bump charged the caller for the full TTL window on every write, even when the entry's
remaining TTL was, say, 179 days and almost nothing had decayed. The threshold form tells the host: only perform
the bump (and bill the rent) if remaining TTL has actually fallen below LOW_WATERMARK. This halves the worst-case
rent cost on the two hottest paths:

• update_reputation — bumps Service(id) + LastVote(id, caller) on every vote
• record_payment — bumps Agent(address) + Policy(address) on every payment

What is not changed

extend_ttl(TEST_MAX_TTL, TEST_MAX_TTL) calls inside #[cfg(test)] storage-seeding helpers are left as-is — those
are direct test setup writes, not production rent paths, and they need the full value to satisfy the ledger mock.

Docs

• docs/storage-layout.md — TTL column for every key updated to describe threshold semantics; LOW_WATERMARK values
  added; "TTL classes" section rewritten
• README.md — hackathon section updated to accurately describe the threshold approach

Testing

Existing test suite covers update_reputation and record_payment behaviour. No test logic was changed; all tests
should pass once the Rust toolchain is available in CI.

Closes #297

[drips-wave]

@Adjutant500 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

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 77948f73-e3c8-4a9e-a572-3b9b67a50b54

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}