Add a read entrypoint exposing the current rate-limit window state for an agent

[mikewheeleer]

Implement get_rate_window to inspect an agent's live rate-limit state

Description

The fixed-window rate limiter in record_usage in contracts/escrow/src/lib.rs stores per-agent (window_start, count) under DataKey::RateWindow(Address), but there is no read entrypoint to inspect it. An agent or operator cannot ask "how many requests have I used in the current window and when does it reset?" without triggering a real record_usage, so clients cannot self-throttle or surface remaining quota in a UI. This issue exposes the window state read-only.

Requirements and context

• Repository scope: Agentpay-Org/Agentpay-contracts only.
• Add get_rate_window(env, agent) -> (u64, u32) returning (window_start, count), defaulting to (0, 0) when no window has opened, matching the unwrap_or((0, 0)) used in record_usage.
• Optionally add a convenience get_remaining_in_window(env, agent) -> u32 computed from MaxRequestsPerWindow and the current count, accounting for an expired window (returns the full cap when the window has rolled over); document the time-dependence on env.ledger().timestamp().
• This is a pure read — no require_auth, no pause gate, no state mutation — consistent with the existing getters; do not roll the window forward as a side effect of reading.
• Keep the change additive.

Suggested execution

• Fork the repo and create a branch
• git checkout -b feature/contracts-get-rate-window
• Implement changes
  • Write code in: contracts/escrow/src/lib.rs — get_rate_window (and optional get_remaining_in_window).
  • Write comprehensive tests in: contracts/escrow/src/test.rs — window state reflects recorded usage, reads do not mutate state, expired window reported correctly via env.ledger().with_mut.
  • Add documentation: document the rate-window reads in README.md.
  • Include NatSpec-style doc comments (///) matching the existing style in lib.rs.
  • Validate security: read-only, no window advance on read.
• Test and commit

Test and commit

• Run cargo fmt --all -- --check, cargo build, and cargo test.
• Cover edge cases: never-recorded agent, mid-window, just-expired window, limiter disabled.
• Include the full cargo test output and a short security notes section in the PR description.

Example commit message

feat: add get_rate_window read for an agent's rate-limit state

Guidelines

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

Community & contribution rewards

• 💬 Join the AgentPay community on Discord for questions, reviews, and faster merges: https://discord.gg/eXvRKkgcv
• ⭐ 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.

[GBOYEE]

Hello! I can work on this. I'll implement the solution with proper Soroban patterns, auth checks, and comprehensive tests. PR incoming shortly.

[gloskull]

Hello, I have 4 years of experience delivering solutions for projects like this, covering backend, frontend, and smart contract development. After carefully reviewing your requirements, I have a clear understanding of the task and am confident in my ability to deliver a clean, efficient, and thoroughly tested solution on time. I prioritize code quality, maintainability, and industry best practices throughout the development process. My PR will be submitted in under 10hours.