Add an emergency admin-gated drain_usage_batch to zero many counters at once

[mikewheeleer]

Implement a batched usage-zeroing entrypoint for incident response

Description

There is no single-transaction way in contracts/escrow/src/lib.rs to wipe usage across many (agent, service_id) pairs. After a metering bug that over-counted across a fleet, an operator must call reset_usage/settle once per pair to clean up — one transaction each, slow and expensive during an incident. This issue adds an admin-gated batched zeroing entrypoint distinct from settlement (no billing, no LastSettlement stamp) for fast incident cleanup.

Requirements and context

• Repository scope: Agentpay-Org/Agentpay-contracts only.
• Add drain_usage_batch(env, pairs: Vec<(Address, Symbol)>): admin-gated, pause-respecting, zeroing each DataKey::Usage(agent, service_id) without touching LastSettlement, lifetime counters, or emitting a billing event.
• Bound the batch length with a documented constant and reject oversized batches with a typed error (append-only) to keep the loop bounded.
• Emit one summary event (e.g. drain_bat(count)) for the audit trail, distinct from settled and any single-pair reset event.
• Document that this is a maintenance/incident tool, not a settlement path, and that lifetime analytics are intentionally preserved.

Suggested execution

• Fork the repo and create a branch
• git checkout -b feature/contracts-drain-usage-batch
• Implement changes
  • Write code in: contracts/escrow/src/lib.rs — drain_usage_batch reusing the usage key and the admin-auth helper.
  • Write comprehensive tests in: contracts/escrow/src/test.rs — multi-pair zeroing, lifetime counters and LastSettlement untouched, oversized batch rejected, non-admin and paused rejected.
  • Add documentation: document the incident-cleanup tool in README.md.
  • Include NatSpec-style doc comments (///) matching the existing style in lib.rs.
  • Validate security: bounded loop, only admin, no billing side effects, analytics preserved.
• Test and commit

Test and commit

• Run cargo fmt --all -- --check, cargo build, and cargo test.
• Cover edge cases: empty batch, never-used pairs, duplicate pairs, exactly-at-bound, paused contract.
• Include the full cargo test output and a short security notes section in the PR description.

Example commit message

feat: add admin drain_usage_batch for fast incident cleanup

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.

[GBOYEE]

Hello! I can work on this. I'll implement the solution with proper Soroban patterns and comprehensive test coverage. PR incoming shortly.