Add a batched get_usage_batch read for many agent-service pairs in one call

[mikewheeleer]

Implement a batched usage read entrypoint

Description

get_usage in contracts/escrow/src/lib.rs returns the counter for exactly one (agent, service_id) pair. A settlement loop or dashboard that needs the current usage for many pairs must issue one read invocation per pair, multiplying RPC round-trips and host invocations. This issue adds a single read that returns the counters for a caller-supplied list of pairs, with a bounded length to keep the call deterministic.

Requirements and context

• Repository scope: Agentpay-Org/Agentpay-contracts only.
• Add get_usage_batch(env, pairs: Vec<(Address, Symbol)>) -> Vec<u32> returning one count per input pair, in input order, using the same unwrap_or(0) default as get_usage.
• Bound the input length with a documented MAX_BATCH_READ constant and reject oversized requests with a typed error so a caller cannot force an unbounded loop.
• This is a pure read — no require_auth, no state mutation, no pause gate (consistent with the existing getters).
• Reuse the single-pair read logic so the batch and single paths cannot drift.

Suggested execution

• Fork the repo and create a branch
• git checkout -b enhancement/contracts-get-usage-batch
• Implement changes
  • Write code in: contracts/escrow/src/lib.rs — get_usage_batch reusing the per-pair read.
  • Write comprehensive tests in: contracts/escrow/src/test.rs — order preserved, unknown pairs return 0, oversized batch rejected, empty batch returns empty vec.
  • Add documentation: document the batch read and its bound in README.md.
  • Include NatSpec-style doc comments (///) matching the existing style in lib.rs.
  • Validate security: bounded loop, read-only, no auth bypass.
• Test and commit

Test and commit

• Run cargo fmt --all -- --check, cargo build, and cargo test.
• Cover edge cases: duplicate pairs in one request, mix of known/unknown pairs, exactly-at-bound length.
• Include the full cargo test output and a short security notes section in the PR description.

Example commit message

feat: add batched get_usage_batch read for many pairs

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.

[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.

[grantfox-oss]

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

Good luck! Track your progress on GrantFox.

[grantfox-oss]

🎉 This issue has been marked as completed on GrantFox as part of the Official Campaign campaign!

@Baskarayelu's PR #62 was approved and merged by @mikewheeleer.

🏆 @Baskarayelu: You earned 35 FoxPoints for this contribution! Your current tier: Explorer (258 total points). Track your full progress on GrantFox.

👏 Great work, @Baskarayelu! Keep contributing to Agentpay-Org.