Add per-agent, per-window rate limiting to record_usage

[mikewheeleer]

Implement per-agent rate limiting on usage recording

Description

record_usage in contracts/escrow/src/lib.rs enforces per-call min/max bounds but has no time-windowed rate limit: a single agent can call it unboundedly within a ledger window, inflating counters and ledger write load. This issue adds a configurable per-agent rate limit anchored to env.ledger().timestamp() so abusive call patterns are throttled on-chain.

Requirements and context

• Repository scope: Agentpay-Org/Agentpay-contracts only.
• Add admin-configurable MaxRequestsPerWindow and WindowSeconds, plus per-agent DataKey::RateWindow(Address) tracking (window_start, count_in_window).
• In record_usage, roll the window forward when expired and reject calls that would exceed the cap with a new RateLimitExceeded error (append-only).
• Default to disabled (no limit) when unset, preserving current behaviour; expose getters for the configured values.
• Document the windowing semantics (fixed vs. sliding) precisely.

Suggested execution

• Fork the repo and create a branch
• git checkout -b feature/contracts-10-rate-limiting
• Implement changes
  • Write code in: contracts/escrow/src/lib.rs — config keys, per-agent window state, and the rate check in record_usage.
  • Write comprehensive tests in: contracts/escrow/src/test.rs — advance the ledger clock to cross windows, assert throttling and reset.
  • Add documentation: document the rate-limit config in README.md.
  • Include NatSpec-style doc comments (///) matching the existing style in lib.rs.
  • Validate security: window math is overflow-safe and cannot be reset by the agent.
• Test and commit

Test and commit

• Run cargo fmt --all -- --check, cargo build, and cargo test.
• Cover edge cases: exactly-at-cap, window rollover, disabled (default), and clock not advancing.
• Include the full cargo test output and a short security notes section in the PR description.

Example commit message

feat: add per-agent per-window rate limiting to record_usage

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.

[greatest0fallt1me]

Hello Maintainers 👋,
I’m interested in picking up this issue and contributing to the project.
I have solid experience working across both frontend and blockchain layers, including building user interfaces with Next.js and developing Stellar smart contracts using Rust (Soroban). I’m familiar with translating Figma designs into pixel-accurate UIs, handling wallet integrations, and writing efficient, well-tested contract logic.
I focus on writing clean, maintainable code, following repository standards, and keeping communication transparent throughout the development process. I can start immediately and complete the work within the expected timeframe.
Excited to collaborate and add value to the project 🚀
Thank you!

[grantfox-oss]

🦊 GrantFox — @greatest0fallt1me 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 #10)
2. Your PR will be reviewed by the Agentpay-Org maintainers

Good luck! Track your progress on GrantFox.