Add a per-pair route rate limit with a configurable cooldown using PairLastRouteAt

[mikewheeleer]

Implement a per-pair route cooldown rate limit

Description

compute_route_fee in src/lib.rs already stamps DataKey::PairLastRouteAt(source, destination) with env.ledger().timestamp() on every route, but nothing ever reads it to throttle activity — a pair can be routed an unbounded number of times in a single ledger. For a stablecoin router this is a real abuse surface (spam routing, oracle-front-running, griefing the route counter). This issue uses the already-stored PairLastRouteAt to enforce an optional minimum interval between routes per pair.

Requirements and context

• Repository scope: StableRoute-Org/Stableroute-contracts only.
• Add DataKey::PairCooldown(Symbol, Symbol) (seconds) plus admin-gated set_pair_cooldown / get_pair_cooldown; default 0 (disabled, fully backward compatible).
• In compute_route_fee, after the liquidity check, compare env.ledger().timestamp() against PairLastRouteAt + cooldown and reject early routes with an append-only RouteCooldownActive error.
• Keep the existing timestamp stamp and route event; do not alter any current error codes.
• Bump the persistent-entry TTL on the new cooldown slot when written.

Suggested execution

• Fork the repo and create a branch
• git checkout -b feature/contracts-31-route-cooldown
• Implement changes
  • Write code in: src/lib.rs — DataKey::PairCooldown, set_pair_cooldown, get_pair_cooldown, and the cooldown check in compute_route_fee.
  • Write comprehensive tests in: src/lib.rs #[cfg(test)] mod test — use env.ledger().set_timestamp to assert a too-soon route is rejected and a route after the cooldown succeeds.
  • Add documentation: document the rate-limit model in README.md.
  • Include NatSpec-style doc comments (///) on the new entrypoints.
  • Validate security assumptions: cooldown cannot underflow; disabled (0) preserves current behavior; first route is always allowed.
• Test and commit

Test and commit

• Run cargo fmt --all -- --check, cargo build, and cargo test.
• Cover edge cases and failure paths: cooldown disabled, first route, route exactly at boundary, route one second early, cooldown changed mid-flight.
• Include the full cargo test output and a short security notes section in the PR description (threat model + mitigations).

Example commit message

feat: add per-pair route cooldown rate limit with tests and docs

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.

[Baskarayelu]

I’d love to be assigned this issue and contribute across the relevant areas, whether it involves smart contracts, UI development, backend logic, design implementation, or overall system integration. I’m comfortable working across the full stack and can adapt to the project’s technical requirements to ensure a smooth and consistent contribution.