Document the stroops unit convention and the off-chain vs on-chain settlement difference

[mikewheeleer]

Document the stroops unit and the off-chain settlement semantics

Description

The billing and settlement code in src/index.ts measures money in priceStroops and billedStroops, and comments call settle the "off-chain mirror of the on-chain settle() entrypoint" — but nothing documents what a stroop is (1 XLM = 10,000,000 stroops), why integer stroops are used, or the critical fact that POST /api/v1/settle here only computes and drains the counter and moves no actual value. A consumer can easily believe a successful settle response means funds moved. This issue documents the unit and the semantics precisely.

Requirements and context

• Repository scope: Agentpay-Org/Agentpay-backend only.
• Add a docs/billing-units.md explaining the stroop unit, the integer-only convention, the relationship to XLM, and the precision rationale.
• Explicitly document that off-chain settle drains the accumulator and quotes the bill but does not transfer funds, and how it relates to the on-chain contract's settle().
• Cross-reference the relevant endpoints (/billing/:agent/:serviceId, /billing/total, /settle) and the bigint-precision direction.
• Keep it accurate to the current implementation; mark planned on-chain transfer as future work.

Suggested execution

• Fork the repo and create a branch
• git checkout -b docs/docs-84-stroops-units
• Implement changes
  • Write code in: no production change; documentation only.
  • Write comprehensive tests in: none required.
  • Add documentation: add docs/billing-units.md and link it from README.md.
  • Use realistic example amounts (e.g. price in stroops → XLM).
  • Validate security assumptions: document the no-funds-moved reality so integrators do not over-trust settle.
• Test and commit

Test and commit

• Run npm test and npm run lint to confirm nothing breaks.
• Verify every referenced endpoint/field exists in src/index.ts.
• Include a note in the PR summarising the documented semantics.

Example commit message

docs: document the stroops unit and off-chain settlement semantics

Guidelines

• Minimum 95 percent test coverage for impacted modules (where applicable).
• 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 backend changes with proper error handling, auth middleware, and database optimizations. PR incoming shortly.