Add an integer-overflow-safe stroops billing type to prevent float precision loss

[mikewheeleer]

Implement overflow-safe stroops arithmetic for billing

Description

Billing math in src/index.ts multiplies requests * price with plain JS numbers in GET /api/v1/billing/:agent/:serviceId, POST /api/v1/settle, and GET /api/v1/billing/total. Usage is saturated at Number.MAX_SAFE_INTEGER, but requests * priceStroops can silently exceed 2^53 and lose precision — unacceptable for a value that maps to on-chain stroops. This issue moves billing amounts to BigInt so totals are exact.

Requirements and context

• Repository scope: Agentpay-Org/Agentpay-backend only.
• Compute billedStroops with BigInt and serialise as a decimal string in the response (documented as a string to avoid JSON precision loss).
• Apply consistently across the per-pair billing, settle, and protocol-wide billing/total endpoints.
• Keep request counts as integers but guard the multiplication path against Number precision loss.
• Document the response-type change (number → string) clearly as it is a breaking change for clients.

Suggested execution

• Fork the repo and create a branch
• git checkout -b feature/payments-11-bigint-stroops
• Implement changes
  • Write code in: the billing/settle handlers in src/index.ts and a src/util/stroops.ts helper.
  • Write comprehensive tests in: new src/util/stroops.test.ts — large totals, exactness above 2^53, summation.
  • Add documentation: document the string-typed amounts in docs/billing.md and the OpenAPI doc.
  • Add TSDoc on the stroops helper.
  • Validate security assumptions: no overflow, no negative results.
• Test and commit

Test and commit

• Run npm run build, npm test, and npm run lint.
• Cover edge cases: counts near MAX_SAFE_INTEGER, high prices, zero price.
• Include the full npm test output in the PR description.

Example commit message

feat: use bigint for stroops billing to avoid float precision loss

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.

[123xiaode456-boop]

/claim

[123xiaode456-boop]

/attempt #82

[pq198363-ops]

/claim

[pq198363-ops]

/attempt #233