Add saturating-arithmetic and overflow tests for usage and billing math

[mikewheeleer]

Test saturating arithmetic in counters and billing computation

Description

contracts/escrow/src/lib.rs relies on saturating_add for usage counters and saturating_mul for compute_billing/settle, documented to "saturate at u32::MAX" and "i128::MAX" rather than overflow. None of these saturation edges are exercised in contracts/escrow/src/test.rs. This issue adds tests that drive the counters and billing math to their boundaries.

Requirements and context

• Repository scope: Agentpay-Org/Agentpay-contracts only.
• Cover: per-pair usage saturating at u32::MAX; TotalUsageByAgent saturating; TotalRequestsAllTime (u64) accumulation near large values.
• Cover: compute_billing saturating at i128::MAX with a large price × large usage; settle returns the saturated value and still drains the counter.
• Set counters near the boundary by recording in large increments rather than relying on internal access.
• Test-only change unless a genuine bug surfaces.

Suggested execution

• Fork the repo and create a branch
• git checkout -b test/contracts-21-saturation-tests
• Implement changes
  • Write code in: contracts/escrow/src/lib.rs — no changes expected.
  • Write comprehensive tests in: contracts/escrow/src/test.rs — the saturation scenarios above.
  • Add documentation: note covered invariants in the test module header.
  • Include NatSpec-style doc comments (///) on any test helpers.
  • Validate security: no panic/overflow under adversarial inputs.
• Test and commit

Test and commit

• Run cargo fmt --all -- --check, cargo build, and cargo test.
• Cover edge cases: one-below-max then +1, exact-max, settle at saturated billing.
• Include the full cargo test output and a short security notes section in the PR description.

Example commit message

test: cover saturating arithmetic in usage counters and billing

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.