Add an admin reset_rate_window entrypoint to clear an agent's throttle state

[mikewheeleer]

Implement an admin override to reset a rate-limit window

Description

Once an agent hits the per-window cap in record_usage in contracts/escrow/src/lib.rs, it must wait for the fixed window to roll over before it can record again — there is no operator override. If an agent was throttled in error (e.g. a misconfigured cap that was since raised, or a legitimate burst the operator wants to forgive), the admin has no way to clear the agent's RateWindow state. This issue adds an admin-gated reset so a throttle can be lifted immediately.

Requirements and context

• Repository scope: Agentpay-Org/Agentpay-contracts only.
• Add reset_rate_window(env, agent): admin-gated, pause-respecting, removing DataKey::RateWindow(agent) so the next record_usage opens a fresh window. Idempotent — resetting an agent with no window is a no-op.
• Emit a rate_reset(agent) event (additive) so the override is auditable.
• Document that this does not change the configured cap/window — it only clears the agent's accumulated count for the current window.
• Keep error codes append-only.

Suggested execution

• Fork the repo and create a branch
• git checkout -b feature/contracts-reset-rate-window
• Implement changes
  • Write code in: contracts/escrow/src/lib.rs — reset_rate_window entrypoint + event.
  • Write comprehensive tests in: contracts/escrow/src/test.rs — throttle an agent, reset, then record succeeds in the same ledger; reset on no-window is a no-op; non-admin caller and paused contract rejected.
  • Add documentation: document the operator override in README.md.
  • Include NatSpec-style doc comments (///) matching the existing style in lib.rs.
  • Validate security: only admin can reset; an agent cannot self-clear its window.
• Test and commit

Test and commit

• Run cargo fmt --all -- --check, cargo build, and cargo test.
• Cover edge cases: reset mid-window, reset with limiter disabled, reset then immediately re-throttle.
• Include the full cargo test output and a short security notes section in the PR description.

Example commit message

feat: add admin reset_rate_window to clear an agent throttle

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.